diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index ab6dd9c62..225dbc677 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -2,11 +2,6 @@ name: Documentation generation & update on: push: - tags: - - '*' - branches: - - master - pull_request: branches: - master @@ -34,18 +29,33 @@ jobs: run: | sudo apt-get update sudo apt-get install graphviz doxygen - - name: Generate the documentation - run: make doc + - name: Generate Wallet documentation + run: | + make doc + mkdir -p build/doc/site/wallet + cp -a build/doc/html/. build/doc/site/wallet/ + + - name: Generate Nano documentation + run: | + TARGET=nanox make doc + mkdir -p build/doc/site/nano + cp -a build/doc/html/. build/doc/site/nano/ + + - name: Create landing page + run: | + cp doc/landing.html build/doc/site/index.html + - name: Upload Pages artifact uses: actions/upload-pages-artifact@v3 with: - path: build/doc/html/ + path: build/doc/site/ deploy: name: Deploy the documentation on Github pages runs-on: ubuntu-latest needs: generate - if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/')) + # Safety guard: keep deployment restricted to master even if triggers change later. + if: github.ref == 'refs/heads/master' environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} diff --git a/Makefile b/Makefile index 0f8438810..00a9f3880 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,7 @@ -.PHONY: doc +.PHONY: doc doc-wallet doc-nano doc-all BUILD_DIR := build +DOC_SITE_DIR := $(BUILD_DIR)/doc/site # default target is stax TARGET ?= stax @@ -18,11 +19,35 @@ NBGL_DEFINES_nano := \ NBGL_DEFINES := $(NBGL_DEFINES_$(TARGET)) +# For nano-family targets (nano, nanox, nanosplus, etc.), default to nano defines. +ifeq ($(strip $(NBGL_DEFINES)),) +ifneq ($(filter nano%,$(TARGET)),) +NBGL_DEFINES := $(NBGL_DEFINES_nano) +endif +endif + export NBGL_DEFINES doc: | $(BUILD_DIR) @doxygen doc/Doxyfile - @echo 'HTML doc can be found in '$(BUILD_DIR)/doc/html/index.html + @echo "HTML doc for '$(TARGET)' can be found in '$(BUILD_DIR)/doc/html/index.html'" + +doc-wallet: + @$(MAKE) --no-print-directory TARGET=stax doc + +doc-nano: + @$(MAKE) --no-print-directory TARGET=nanox doc + +doc-all: + @mkdir -p $(DOC_SITE_DIR) + @$(MAKE) --no-print-directory TARGET=stax doc + @mkdir -p $(DOC_SITE_DIR)/wallet + @cp -a $(BUILD_DIR)/doc/html/. $(DOC_SITE_DIR)/wallet/ + @$(MAKE) --no-print-directory TARGET=nanox doc + @mkdir -p $(DOC_SITE_DIR)/nano + @cp -a $(BUILD_DIR)/doc/html/. $(DOC_SITE_DIR)/nano/ + @cp doc/landing.html $(DOC_SITE_DIR)/index.html + @echo 'Combined documentation can be found in '$(DOC_SITE_DIR)/index.html $(BUILD_DIR): @mkdir -p $@ diff --git a/doc/Doxyfile b/doc/Doxyfile index 5d02f1e2c..144881bd2 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -99,7 +99,6 @@ OUTPUT_LANGUAGE = English # Possible values are: None, LTR, RTL and Context. # The default value is: None. -OUTPUT_TEXT_DIRECTION = None # If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member # descriptions after the members that are listed in the file and class @@ -756,7 +755,7 @@ CITE_BIB_FILES = # messages are off. # The default value is: NO. -QUIET = NO +QUIET = YES # The WARNINGS tag can be used to turn on/off the warning messages that are # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES @@ -838,19 +837,14 @@ INPUT = \ lib_nbgl/doc \ lib_nbgl/include \ lib_nbgl/src \ - lib_blewbxx_impl/doc \ lib_blewbxx_impl/include \ - lib_blewbxx_impl/src \ lib_nfc/doc \ lib_nfc/include \ lib_nfc/src \ lib_standard_app/doc \ lib_standard_app \ - lib_stusb/doc \ lib_stusb \ - lib_stusb_impl/doc \ lib_stusb_impl \ - lib_u2f/doc \ lib_u2f/include \ lib_u2f/src \ lib_ux/doc \ @@ -945,7 +939,8 @@ RECURSIVE = NO # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = app_features/address_book/doc/address_book_spec.md +EXCLUDE = app_features/address_book/doc/address_book_spec.md \ + doc/landing.html # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -1317,7 +1312,6 @@ HTML_COLORSTYLE_GAMMA = 80 # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_TIMESTAMP = NO # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML # documentation will contain a main index with vertical navigation menus that @@ -1609,7 +1603,6 @@ FORMULA_FONTSIZE = 10 # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. -FORMULA_TRANSPARENT = YES # The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands # to create new LaTeX commands to be used in formulas as building blocks. See @@ -1917,7 +1910,6 @@ LATEX_HIDE_INDICES = NO # The default value is: NO. # This tag requires that the tag GENERATE_LATEX is set to YES. -LATEX_SOURCE_CODE = NO # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See @@ -1933,7 +1925,6 @@ LATEX_BIB_STYLE = plain # The default value is: NO. # This tag requires that the tag GENERATE_LATEX is set to YES. -LATEX_TIMESTAMP = NO # The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute) # path from which the emoji images will be read. If a relative path is entered, @@ -2007,7 +1998,6 @@ RTF_EXTENSIONS_FILE = # The default value is: NO. # This tag requires that the tag GENERATE_RTF is set to YES. -RTF_SOURCE_CODE = NO #--------------------------------------------------------------------------- # Configuration options related to the man page output @@ -2112,7 +2102,6 @@ DOCBOOK_OUTPUT = docbook # The default value is: NO. # This tag requires that the tag GENERATE_DOCBOOK is set to YES. -DOCBOOK_PROGRAMLISTING = NO #--------------------------------------------------------------------------- # Configuration options for the AutoGen Definitions output @@ -2301,7 +2290,6 @@ EXTERNAL_PAGES = YES # powerful graphs. # The default value is: YES. -CLASS_DIAGRAMS = YES # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The @@ -2343,14 +2331,12 @@ DOT_NUM_THREADS = 0 # The default value is: Helvetica. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_FONTNAME = Helvetica # The DOT_FONTSIZE tag can be used to set the size (in points) of the font of # dot graphs. # Minimum value: 4, maximum value: 24, default value: 10. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_FONTSIZE = 10 # By default doxygen will tell dot to use the default font as specified with # DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set @@ -2579,7 +2565,6 @@ MAX_DOT_GRAPH_DEPTH = 0 # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_TRANSPARENT = NO # Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output # files in one run (i.e. multiple -o and -T options on the command line). This diff --git a/doc/landing.html b/doc/landing.html new file mode 100644 index 000000000..6e8924b91 --- /dev/null +++ b/doc/landing.html @@ -0,0 +1,59 @@ + + + + + + Embedded SDK Documentation + + + +
+

Embedded SDK Documentation

+

Choose the documentation variant:

+
+ Wallet documentation (Stax/Flex/Apex) + Nano documentation (Nano targets) +
+
+ + diff --git a/doc/mainpage.dox b/doc/mainpage.dox index 98652fb59..42c3c0175 100644 --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -13,7 +13,7 @@ or Ledger-managed accounts. @section ble_presentation BlueTooth Low-Energy Interface -The @subpage ble_mainpage page contains all information necessary to interact with BLE stack. +This section contains the interfaces necessary to interact with the BLE stack. @section cxng_presentation Cryptographic Library @@ -27,7 +27,7 @@ The @subpage list_mainpage page contains all information necessary to use the Ge The @subpage mem_alloc_mainpage page contains all information necessary to interact with Dynamic Memory Allocator. -@section nbgl_presentation Screen drawing API +@section nbgl_presentation Display & Screen drawing API The @subpage nbgl_mainpage page contains all information necessary to understand the Graphical Library for \b Stax, \b Flex, \b NanoX and \b NanoS+ applications development. @@ -44,15 +44,15 @@ The @subpage standard_app_mainpage page contains all information necessary to us @subsection usb_core_presentation USB Core -The @subpage usb_mainpage page contains all information necessary to use the USB Core. +This section contains all information necessary to use the USB Core. @subsection usb_impl_presentation USB Classes API -The @subpage usb_impl_mainpage page contains all information necessary to use the USB Classes API. +This section contains all information necessary to use the USB Classes API. @subsection u2f_presentation U2F (Universal 2nd Factor) API -The @subpage u2f_mainpage page contains all information necessary to use the U2F API. +This section contains all information necessary to use the U2F API. @section ux_presentation User eXperience diff --git a/doc/plantuml.jar b/doc/plantuml.jar index 835017767..aadfc1648 100644 Binary files a/doc/plantuml.jar and b/doc/plantuml.jar differ diff --git a/lib_alloc/doc/mainpage.dox b/lib_alloc/doc/mainpage.dox index d11854ff7..40479749a 100644 --- a/lib_alloc/doc/mainpage.dox +++ b/lib_alloc/doc/mainpage.dox @@ -129,7 +129,8 @@ Exit code is 0 if no errors detected, 1 if leaks or free errors found. @subsection mem_alloc_profiling_persistent Persistent Allocations -Persistent allocations are those that are intentionally kept without being freed (@ref mem_buffer_persistent()). +Persistent allocations are those that are intentionally kept without being freed, +for example by using @ref APP_MEM_PERMANENT. Such buffers will not be reported as leaks. @code{.c} diff --git a/lib_alloc/mem_alloc.c b/lib_alloc/mem_alloc.c index 6343d7172..46004c79b 100644 --- a/lib_alloc/mem_alloc.c +++ b/lib_alloc/mem_alloc.c @@ -575,8 +575,10 @@ void mem_free(mem_ctx_t ctx, void *ptr) /** * @brief parse the heap * + * Iterates over blocks managed by @ref mem_alloc and @ref mem_free. + * * @param ctx allocator context (returned by @ref mem_init()) - * @param ptr buffer previously allocated with @ref mem_alloc + * @param callback callback called for each block while parsing * @param data context data, passed to given callback */ void mem_parse(mem_ctx_t ctx, mem_parse_callback_t callback, void *data) @@ -614,8 +616,10 @@ void mem_parse(mem_ctx_t ctx, mem_parse_callback_t callback, void *data) * @brief function used to get statistics (nb chunks, nb allocated chunks, total size) about the * heap * + * Statistics are computed from the heap used by @ref mem_alloc and @ref mem_free. + * * @param ctx allocator context (returned by @ref mem_init()) - * @param ptr buffer previously allocated with @ref mem_alloc + * @param stat output statistics structure */ void mem_stat(mem_ctx_t *ctx, mem_stat_t *stat) { diff --git a/lib_cxng/include/lcx_aead.h b/lib_cxng/include/lcx_aead.h index 806c24ea6..053d9e35c 100644 --- a/lib_cxng/include/lcx_aead.h +++ b/lib_cxng/include/lcx_aead.h @@ -20,7 +20,7 @@ * @file lcx_aead.h * @brief Authenticated Encryption with Associated Data (AEAD) * - * @section Description + * @details * * Authenticated encryption provides confidentiality for the plaintext * and integrity and authenticity checks. Authentication Encryption with diff --git a/lib_cxng/include/lcx_aes_gcm.h b/lib_cxng/include/lcx_aes_gcm.h index 8ce2a145a..d2b66cafa 100644 --- a/lib_cxng/include/lcx_aes_gcm.h +++ b/lib_cxng/include/lcx_aes_gcm.h @@ -20,7 +20,7 @@ * @file lcx_aes_gcm.h * @brief AES in Galois/Counter Mode (AES-GCM) * - * @section Description + * @details * * The Galois/Counter Mode (GCM) is an authenticated encryption algorithm * designed to provide both data authenticity (integrity) and confidentiality. diff --git a/lib_cxng/include/lcx_aes_siv.h b/lib_cxng/include/lcx_aes_siv.h index b4db323b2..87e5206b8 100644 --- a/lib_cxng/include/lcx_aes_siv.h +++ b/lib_cxng/include/lcx_aes_siv.h @@ -4,7 +4,7 @@ * @file lcx_aes_siv.h * @brief Advanced Encryption Standard with Synthetic Initialization Vector (AES-SIV). * - * @section Description + * @details * AES-SIV is an algorithm which provides both authentication and encryption. * It uses AES in CMAC mode to compute a synthetic initialization vector * which is further used by the AES in counter mode to encrypt diff --git a/lib_cxng/include/lcx_blake3.h b/lib_cxng/include/lcx_blake3.h index 9d9bfd540..072b38633 100644 --- a/lib_cxng/include/lcx_blake3.h +++ b/lib_cxng/include/lcx_blake3.h @@ -19,7 +19,7 @@ * @file lcx_blake3.h * @brief BLAKE3 hash function. * - * @section Description + * @details * * BLAKE3 is a cryptographic algorithm which is an evolution of * BLAKE2 cryptographic hash function. It provides keyed hashing and diff --git a/lib_cxng/include/lcx_chacha.h b/lib_cxng/include/lcx_chacha.h index 0589d083c..682a2b73d 100644 --- a/lib_cxng/include/lcx_chacha.h +++ b/lib_cxng/include/lcx_chacha.h @@ -20,7 +20,7 @@ * @file lcx_chacha.h * @brief Chacha cipher * - * @section Description + * @details * * The Chacha cipher is a stream cipher which generates a key stream of at most 2^70 bytes * composed of blocks of size 512 bits. The possible key sizes are 128 bits and 256 bits and diff --git a/lib_cxng/include/lcx_chacha_poly.h b/lib_cxng/include/lcx_chacha_poly.h index efa3659a8..c1527d754 100644 --- a/lib_cxng/include/lcx_chacha_poly.h +++ b/lib_cxng/include/lcx_chacha_poly.h @@ -20,7 +20,7 @@ * @file lcx_chacha_poly.h * @brief CHACHA20_POLY1305 Authenticated Encryption with Additional Data (AEAD) * - * @section Description + * @details * * @author Ledger * @version 1.0 diff --git a/lib_cxng/include/lcx_poly1305.h b/lib_cxng/include/lcx_poly1305.h index 1c0692cd6..602917068 100644 --- a/lib_cxng/include/lcx_poly1305.h +++ b/lib_cxng/include/lcx_poly1305.h @@ -20,7 +20,7 @@ * @file lcx_poly1305.h * @brief POLY1305 Message Authentication Code * - * @section Description + * @details * * POLY1305 generates a 16-byte tag which authenticates a message given a 32-byte key. * The 32-byte key can be made of two 16-byte keys, e.g. the first 16-byte key is an AES key diff --git a/lib_lists/doc/mainpage.dox b/lib_lists/doc/mainpage.dox index 5a9e75201..b7b7c5864 100644 --- a/lib_lists/doc/mainpage.dox +++ b/lib_lists/doc/mainpage.dox @@ -335,7 +335,7 @@ for (flist_node_t *node = my_flist; node != NULL; node = node->next) { } @endcode -@subsection list_traversal Doubly-Linked List Traversal (Both Directions) +@subsection list_traversal_dlist Doubly-Linked List Traversal (Both Directions) @code{.c} // Forward iteration @@ -619,7 +619,7 @@ printf("Removed %zu minors\n", removed_minors); **Memory overhead:** 4-8 bytes per node (one pointer) -@subsection list_performance Doubly-Linked List Performance +@subsection list_performance_dlist Doubly-Linked List Performance | Operation | Time Complexity | Notes | |---------------------------|-----------------|-----------------------------------| @@ -670,7 +670,7 @@ printf("Removed %zu minors\n", removed_minors); 4. **Bubble sort**: The sort implementation is O(n²). For large lists, consider using an external sorting algorithm. -@subsection list_limitations Doubly-Linked List Limitations +@subsection list_limitations_dlist Doubly-Linked List Limitations 1. **Memory overhead**: Uses twice the memory per node compared to forward lists (two pointers instead of one). diff --git a/lib_nbgl/doc/mainpage.dox b/lib_nbgl/doc/mainpage.dox index 5bdaad758..085d05a92 100644 --- a/lib_nbgl/doc/mainpage.dox +++ b/lib_nbgl/doc/mainpage.dox @@ -1,5 +1,5 @@ #ifdef HAVE_SE_TOUCH -/** @page nbgl_mainpage New BOLOS Graphic API for Stax/Flex +/** @page nbgl_mainpage New BOLOS Graphic API for Stax/Flex/Apex @section nbgl_mainpage_intro Introduction diff --git a/lib_nbgl/doc/nbgl_use_case_nanos.dox b/lib_nbgl/doc/nbgl_use_case_nanos.dox index 7a1b55e08..398cfde70 100644 --- a/lib_nbgl/doc/nbgl_use_case_nanos.dox +++ b/lib_nbgl/doc/nbgl_use_case_nanos.dox @@ -692,7 +692,7 @@ The @ref nbgl_useCaseKeyboard() function enables to create such page, with the f - \b title: the page title - \b entryBuffer: buffer to store the entered text - \b entryMaxLen: maximum length of text - - \b mode: initial keyboard mode (@ref MODE_LETTERS, @ref MODE_DIGITS, @ref MODE_SPECIAL, @ref MODE_NONE) + - \b mode: initial keyboard mode (@ref MODE_LOWER_LETTERS, @ref MODE_UPPER_LETTERS, @ref MODE_DIGITS_AND_SPECIALS, @ref MODE_NONE) - \b lettersOnly: if true, only letter keys and Backspace are shown - \b confirmationParams or \b suggestionParams: depending on the type - A callback for the back action diff --git a/lib_nbgl/include/nbgl_content.h b/lib_nbgl/include/nbgl_content.h index 3c17ec6a7..a63cbc6d8 100644 --- a/lib_nbgl/include/nbgl_content.h +++ b/lib_nbgl/include/nbgl_content.h @@ -171,7 +171,7 @@ typedef struct { union { const nbgl_icon_details_t *valueIcon; ///< - if alias, a buffer containing the 1BPP icon for icon - ///< on right of value, on Stax/Flex (can be NULL) + ///< on right of value, on Stax/Flex/Apex (can be NULL) ///< - if centeredInfo, it's the icon of the centered info (can be NULL) const nbgl_contentValueExt_t *extension; ///< if not NULL, gives additional info on value field diff --git a/lib_nbgl/include/nbgl_layout.h b/lib_nbgl/include/nbgl_layout.h index 470ea796d..b03f1a4bd 100644 --- a/lib_nbgl/include/nbgl_layout.h +++ b/lib_nbgl/include/nbgl_layout.h @@ -270,8 +270,8 @@ typedef struct { } nbgl_layoutBar_t; /** - * @brief This structure contains info for Text content, to be set with @ref - * nbgl_layoutAddTextContent + * @brief This structure contains info for Text content, to be set with + * nbgl_layoutAddTextContent(). * */ typedef struct { diff --git a/lib_nbgl/include/nbgl_obj.h b/lib_nbgl/include/nbgl_obj.h index 5586963f2..a9702ee27 100644 --- a/lib_nbgl/include/nbgl_obj.h +++ b/lib_nbgl/include/nbgl_obj.h @@ -304,13 +304,11 @@ extern "C" { * @brief The different pressed buttons * */ -#define LEFT_BUTTON 0x01 ///< Left button event -#define RIGHT_BUTTON 0x02 ///< Right button event -#define BOTH_BUTTONS 0x03 ///< Both buttons event -#define RELEASED_MASK 0x80 ///< released (see LSB bits to know what buttons are released) -#define CONTINUOUS_MASK \ - 0x40 ///< if set, means that the button(s) is continuously pressed (this event is sent every - ///< 300ms after the first 800ms) +#define LEFT_BUTTON 0x01 ///< Left button event +#define RIGHT_BUTTON 0x02 ///< Right button event +#define BOTH_BUTTONS 0x03 ///< Both buttons event +#define RELEASED_MASK 0x80 ///< released (see LSB bits to know what buttons are released) +#define CONTINUOUS_MASK 0x40 ///< if set, the button(s) is continuously pressed typedef enum { BUTTON_LEFT_PRESSED = 0, ///< Sent when Left button is released diff --git a/lib_nbgl/src/nbgl_layout.c b/lib_nbgl/src/nbgl_layout.c index aa8ebfcda..682f7f579 100644 --- a/lib_nbgl/src/nbgl_layout.c +++ b/lib_nbgl/src/nbgl_layout.c @@ -3764,7 +3764,7 @@ int nbgl_layoutAddSpinner(nbgl_layout_t *layout, * @param layout the current layout * @param text text to draw under the spinner * @param subText text to draw under the text (can be NULL) - * @param initPosition position of the spinner (cannot be fixed) + * @param position position of the spinner (cannot be fixed) * @return - 0 if no refresh needed * - 1 if partial B&W refresh needed * - 2 if partial color refresh needed diff --git a/lib_standard_app/crypto_helpers.h b/lib_standard_app/crypto_helpers.h index cec943336..0a9f95378 100644 --- a/lib_standard_app/crypto_helpers.h +++ b/lib_standard_app/crypto_helpers.h @@ -147,6 +147,8 @@ WARN_UNUSED_RESULT static inline cx_err_t bip32_derive_get_pubkey_256(cx_curve_t * * @param[in] path_len Bip32 path length. * + * @param[in] sign_mode Signature mode flags forwarded to cx_ecdsa_sign. + * * @param[in] hashID Message digest algorithm identifier. * * @param[in] hash Digest of the message to be signed. @@ -198,6 +200,8 @@ WARN_UNUSED_RESULT cx_err_t bip32_derive_with_seed_ecdsa_sign_hash_256(unsigned * * @param[in] path_len Bip32 path length. * + * @param[in] sign_mode Signature mode flags forwarded to cx_ecdsa_sign. + * * @param[in] hashID Message digest algorithm identifier. * * @param[in] hash Digest of the message to be signed. @@ -258,6 +262,8 @@ WARN_UNUSED_RESULT static inline cx_err_t bip32_derive_ecdsa_sign_hash_256(cx_cu * * @param[in] path_len Bip32 path length. * + * @param[in] sign_mode Signature mode flags forwarded to cx_ecdsa_sign. + * * @param[in] hashID Message digest algorithm identifier. * * @param[in] hash Digest of the message to be signed.