Merge pull request trilitech#220 from trilitech/ajinkyaraj-23@add-doc…

…umentation

Add documentation for streaming and display related functions

app/src/apdu.h

@@ -83,8 +83,22 @@
 typedef void(tz_handler)(command_t *cmd);
 typedef tz_handler *tz_handler_t;
 
-tz_handler handle_unimplemented;
-tz_handler handle_apdu_version;
-tz_handler handle_apdu_git;
+tz_handler handle_unimplemented;  /// handler for unknown commands
+tz_handler handle_apdu_version;   /// handle version enquiry apdu
+tz_handler handle_apdu_git;       /// handle git commit enquiry apdu
+/**
+ * @brief Function to handle apdu request for public key. The public key is
+ * derived only once and stored in the RAM, in order to avoid repeated
+ * derivation calculations. This function can be called with or without
+ * prompt.
+ *
+ */
 tz_handler handle_apdu_get_public_key;
+/**
+ * @brief Parse the received command and prompt user for appropriate action.
+ * Triggers blindsigning and/or expert mode workflows based on transaction
+ * involved. Stream based parser helps decode arbitararily large transaction,
+ * screen by screen.
+ *
+ */
 tz_handler handle_apdu_sign;

app/src/apdu_sign.h

@@ -29,38 +29,57 @@
 #include "keys.h"
 #include "parser/parser_state.h"
 
+/**
+ * @brief Save hash of the transaction to be signed.
+ *
+ */
 typedef struct {
-    cx_blake2b_t state;
-    uint8_t      final_hash[SIGN_HASH_SIZE];
+    cx_blake2b_t state;  /// Ledger-sdk blake2b state containing hash header
+                         /// and blake2b state info.
+    uint8_t final_hash[SIGN_HASH_SIZE];  /// Final hash of the transaction.
 } apdu_hash_state_t;
 
+/**
+ * @brief Represents state of sign transaction.
+ *
+ */
 typedef enum {
-    SIGN_ST_IDLE,
-    SIGN_ST_WAIT_DATA,
-    SIGN_ST_WAIT_USER_INPUT
+    SIGN_ST_IDLE,            /// IDLE
+    SIGN_ST_WAIT_DATA,       /// Waiting for more data from apdu interface
+    SIGN_ST_WAIT_USER_INPUT  /// Waiting for user action
 } sign_step_t;
 
+/**
+ * @brief Steps in a blind signing of a transaction.
+ *
+ */
 typedef enum {
     BLINDSIGN_ST_OPERATION,
     BLINDSIGN_ST_HASH,
     BLINDSIGN_ST_ACCEPT_REJECT,
 } blindsign_step_t;
 
+/**
+ * @brief Struct to track state/info about current sign operation.
+ *
+ */
 typedef struct {
-    uint8_t packet_index;
+    uint8_t packet_index;  /// Index of the packet currently being processed.
 
-    sign_step_t step;
-    bool        return_hash;
-    bool        received_last_msg;
-    uint8_t     tag;
+    sign_step_t step;  /// Current step of the sign operation.
+    bool return_hash;  /// Whether to return the hash of the transaction.
+    bool received_last_msg;  /// Whether the last message has been received.
+    uint8_t tag;             /// Type of tezos operation to sign.
 
     union {
+        /// @brief clear signing state info.
         struct {
             size_t          total_length;
             tz_parser_state parser_state;
             uint8_t         last_field_index;
             bool            received_msg;
         } clear;
+        /// @brief blindsigning state info.
         struct {
             blindsign_step_t step;
         } blind;

app/src/globals.h

@@ -44,20 +44,24 @@
 #include "utils.h"
 
 #include "parser/parser_state.h"
-
-// Zeros out all application-specific globals and SDK-specific
-// UI/exchange buffers.
+/**
+ * @brief  Zeros out all application-specific globals and SDK-specific
+ * UI/exchange buffers.
+ */
 void init_globals(void);
 
-// Toggles the persisted expert_mode setting
+/// Toggles the persisted expert_mode setting
 void toggle_expert_mode(void);
 
-// Toggles the persisted blindsigning setting
+/// Toggles the persisted blindsigning setting
 void toggle_blindsigning(void);
 
 #define MAX_APDU_SIZE      235
 #define MAX_SIGNATURE_SIZE 100
-
+/**
+ * @brief Home screen pages in order
+ *
+ */
 typedef enum {
 #ifdef HAVE_BAGL
     SCREEN_HOME = 0,
@@ -70,24 +74,33 @@ typedef enum {
     SCREEN_QUIT,
 } screen_t;
 
+/**
+ * @brief State of the app
+ *
+ */
 typedef enum {
-    ST_IDLE,
-    ST_CLEAR_SIGN,
-    ST_BLIND_SIGN,
-    ST_PROMPT,
-    ST_SWAP_SIGN,
-    ST_ERROR
+    ST_IDLE,        /// Idle state
+    ST_CLEAR_SIGN,  /// Clearsigning an operation
+    ST_BLIND_SIGN,  /// blindisigning an operation
+    ST_PROMPT,      /// Waiting for user prompt
+    ST_SWAP_SIGN,   /// Performing swap operations
+    ST_ERROR        /// In error state.
 } main_step_t;
 
+/**
+ * @brief Global structure holding state of operations and buffer of the data
+ * to be processed.
+ *
+ */
 typedef struct {
     /* State */
-    main_step_t             step;
-    tz_ui_stream_t          stream;
-    bip32_path_with_curve_t path_with_curve;
+    main_step_t             step;    /// Current operational state of app.
+    tz_ui_stream_t          stream;  /// UX and display related information
+    bip32_path_with_curve_t path_with_curve;  /// Derivation path
     union {
         struct {
-            apdu_hash_state_t hash;
-            apdu_sign_state_t sign;
+            apdu_hash_state_t hash;  /// Transaction hash
+            apdu_sign_state_t sign;  ///  state of sign operation.
         } apdu;
         /** Warning: Use this pubkey only when apdu-hash/sign
          * is not being used.
@@ -96,25 +109,29 @@ typedef struct {
          * */
         cx_ecfp_public_key_t pubkey;
     } keys;
-    char line_buf[TZ_UI_STREAM_CONTENTS_SIZE + 1];
+    char line_buf[TZ_UI_STREAM_CONTENTS_SIZE
+                  + 1];  /// Buffer to store incoming data.
 #ifdef HAVE_BAGL
     struct {
         bagl_element_t bagls[5 + TZ_SCREEN_LINES_11PX];
-    } ux;
+    } ux;  /// Config for history screens for nano devices.
 #endif
 } globals_t;
 
 /* Settings */
 typedef struct {
-    bool blindsigning;
-    bool expert_mode;
-} settings_t;
+    bool blindsigning;  /// enable blindsigning
+    bool expert_mode;   /// enable expert mode
+} settings_t;           /// Special settings available in the app.
 
 extern globals_t global;
 
 extern const settings_t N_settings_real;
 #define N_settings (*(volatile settings_t *)PIC(&N_settings_real))
 
 extern unsigned int app_stack_canary;  // From SDK
-
+/**
+ * @brief IO buffer.
+ *
+ */
 extern unsigned char G_io_seproxyhal_spi_buffer[IO_SEPROXYHAL_BUFFER_SIZE_B];

app/src/handle_swap.h

@@ -22,4 +22,9 @@
 
 #pragma once
 
+/**
+ * @brief Called to check the validity of swap params previously communicated
+ * by swap_copy_transaction_parameters which is called from Ledger SDK.
+ *
+ */
 void swap_check_validity(void);

app/src/keys.h

@@ -32,8 +32,11 @@
 #define MAX_BIP32_LEN  10
 #define SIGN_HASH_SIZE 32
 
-/* The values in the following enum are from the on-the-wire protocol */
-
+/**
+ * @brief The derivation type values in the following enum are from the
+ * on-the-wire protocol
+ *
+ */
 typedef enum {
     DERIVATION_TYPE_ED25519       = 0,
     DERIVATION_TYPE_SECP256K1     = 1,
@@ -53,15 +56,38 @@ typedef struct {
 } bip32_path_with_curve_t;
 
 tz_exc read_bip32_path(bip32_path_t *out, const uint8_t *in, size_t in_size);
+
+/**
+ * @brief Derive public key for given derivation type address.
+ *
+ * @param public_key Public key derived is stored in this struct.
+ * @param derivation_type Derivation type to be used
+ * @param bip32_path path to derive public key from
+ * @return tz_exc return success/failure using error code
+ */
 tz_exc derive_pk(cx_ecfp_public_key_t *public_key,
                  derivation_type_t     derivation_type,
                  const bip32_path_t   *bip32_path);
+/**
+ * @brief Derive hash of public key for given derivation type address.
+ *
+ * @param hash The hash of public key, output is stored in this buffer.
+ * @param derivation_type Derivation type to be used.
+ * @param bip32_path Path to derive public key from.
+ * @return tz_exc return Error code
+ */
 tz_exc derive_pkh(cx_ecfp_public_key_t *pubkey,
                   derivation_type_t derivation_type, char *buffer,
                   size_t len);
 void   sign(derivation_type_t derivation_type, const bip32_path_t *path,
             const uint8_t *hash, size_t hashlen, uint8_t *sig, size_t *siglen);
 
+/**
+ * @brief Check if derivation type is valid enum
+ *
+ * @param code Derivation type to check.
+ * @return validity result
+ */
 static inline bool
 check_derivation_type(derivation_type_t code)
 {

app/src/ui_commons.h

@@ -25,7 +25,10 @@
 #include <os.h>
 #include <os_io_seproxyhal.h>
 #include <ux.h>
-
+/**
+ * @brief Macro to display navigation icons and set associated callback.
+ *
+ */
 #define DISPLAY(elts, cb, len)                                              \
     memcpy(global.ux.bagls, elts, len * sizeof(bagl_element_t));            \
     G_ux.stack[0].element_arrays[0].element_array        = global.ux.bagls; \

app/src/ui_home.c

@@ -28,6 +28,10 @@
 
 static void cb(tz_ui_cb_type_t cb_type);
 
+/**
+ * @brief Callback for home screen stream.
+ *
+ * @param cb_type one of the 4 home screens (HOME, VERSION, SETTINGS, QUIT) */
 static void
 cb(tz_ui_cb_type_t cb_type)
 {

app/src/ui_home.h

@@ -20,4 +20,9 @@
 
 #pragma once
 
+/**
+ * @brief  Initialize home screen with the screen format of ledger.
+ * Internally call multiple initialization functions for Settings screen and
+ * other relevant display buffers.
+ */
 void ui_home_init(void);

app/src/ui_settings.h

@@ -7,4 +7,11 @@
 #define SETTINGS_HOME_PAGE         0
 #define SETTINGS_BLINDSIGNING_PAGE 1
 
+/**
+ * @brief Initialize settings screen for nano devices. Displays status of
+ * Expert-mode and Blind Signing.
+ *
+ * @param page Current page to display among all the pages available under
+ * Settings.
+ */
 void ui_settings_init(int16_t page);