Document data structures used

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

@@ -58,7 +58,10 @@ 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,
@@ -71,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.
@@ -97,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];