Doc: documents global.h file

src/globals.h

@@ -29,123 +29,183 @@
 #include "operations.h"
 #include "ui.h"
 
-// Zeros out all globals that can keep track of APDU instruction state.
-// Notably this does *not* include UI state.
+/**
+ * @brief Zeros out all globals that can keep track of APDU instruction state
+ *
+ *        Notably this does *not* include UI state
+ *
+ */
 void clear_apdu_globals(void);
 
+/**
+ * @brief string_generation_callback for chains
+ *
+ * @param out: output buffer
+ * @param out_size: output size
+ * @param data: chain_id
+ */
 void copy_chain(char *out, size_t out_size, void *data);
+
+/**
+ * @brief string_generation_callback for keys
+ *
+ * @param out: output buffer
+ * @param out_size: output size
+ * @param data: bip32 path curve key
+ */
 void copy_key(char *out, size_t out_size, void *data);
+
+/**
+ * @brief string_generation_callback for high watermarks
+ *
+ * @param out: output buffer
+ * @param out_size: output size
+ * @param data: high watermark
+ */
 void copy_hwm(char *out, size_t out_size, void *data);
-// 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);
 
-#define MAX_APDU_SIZE 235  // Maximum number of bytes in a single APDU
+/// Maximum number of bytes in a single APDU
+#define MAX_APDU_SIZE 235
 
-// Our buffer must accommodate any remainder from hashing and the next message at once.
+/// Our buffer must accommodate any remainder from hashing and the next message at once.
 #define TEZOS_BUFSIZE (BLAKE2B_BLOCKBYTES + MAX_APDU_SIZE)
 
 #define PRIVATE_KEY_DATA_SIZE 64
+#define MAX_SIGNATURE_SIZE    100
 
-#define MAX_SIGNATURE_SIZE 100
-
+/**
+ * @brief This structure represents the state needed to handle HMAC
+ *
+ */
 typedef struct {
-    uint8_t signed_hmac_key[MAX_SIGNATURE_SIZE];
-    uint8_t hashed_signed_hmac_key[CX_SHA512_SIZE];
-    uint8_t hmac[CX_SHA256_SIZE];
+    uint8_t signed_hmac_key[MAX_SIGNATURE_SIZE];     ///< buffer to hold the signed hmac key
+    uint8_t hashed_signed_hmac_key[CX_SHA512_SIZE];  ///< buffer to hold the hashed signed hmac key
+    uint8_t hmac[CX_SHA256_SIZE];                    ///< buffer to hold the hmac result
 } apdu_hmac_state_t;
 
+/**
+ * @brief This structure represents the state needed to hash messages
+ *
+ */
 typedef struct {
-    cx_blake2b_t state;
-    bool initialized;
+    cx_blake2b_t state;  ///< blake2b state
+    bool initialized;    ///< if the state has already been initialized
 } blake2b_hash_state_t;
 
+/**
+ * @brief This structure represents the state needed to sign messages
+ *
+ */
 typedef struct {
-    uint8_t packet_index;  // 0-index is the initial setup packet, 1 is first packet to hash, etc.
+    /// 0-index is the initial setup packet, 1 is first packet to hash, etc.
+    uint8_t packet_index;
 
+    /// state to hold the current parsed bakind data
     parsed_baking_data_t parsed_baking_data;
 
+    /// operation read, used for checks
     struct {
-        bool is_valid;
-        struct parsed_operation_group v;
+        bool is_valid;                    ///< if the parsed operation group is considered as valid
+        struct parsed_operation_group v;  ///< current parsed operation group
     } maybe_ops;
 
+    /// buffer to hold the current message part and the  previous message hash
     uint8_t message_data[TEZOS_BUFSIZE];
-    size_t message_data_length;
+    size_t message_data_length;  ///< length of message data
 
-    blake2b_hash_state_t hash_state;
-    uint8_t final_hash[SIGN_HASH_SIZE];
+    blake2b_hash_state_t hash_state;     ///< current blake2b hash state
+    uint8_t final_hash[SIGN_HASH_SIZE];  ///< buffer to hold hash of all the message
 
-    uint8_t magic_byte;
-    bool hash_only;
-    struct parse_state parse_state;
+    uint8_t magic_byte;              ///< current magic byte read
+    struct parse_state parse_state;  ///< current parser state
 } apdu_sign_state_t;
 
-// Used to compute what we need to display on the screen.
-// Title of the screen will be `title` field, and value of
-// the screen will be generated by calling `callback_fn` and providing
-// `data` as one of its parameter.
+/**
+ * @brief This structure represents data used to compute what we need to display on the screen.
+ *
+ */
 struct screen_data {
-    char *title;
-    string_generation_callback callback_fn;
-    void *data;
+    char *title;                             ///< title of the screen
+    string_generation_callback callback_fn;  ///< callback to convert the data to string
+    void *data;                              ///< value to display on the screen
 };
 
-// State of the dynamic display.
-// Used to keep track on whether we are displaying screens inside the stack,
-// or outside the stack (for example confirmation screens).
+/**
+ * @brief State of the dynamic display
+ *
+ *        Used to keep track on whether we are displaying screens inside the stack, or outside the
+ *        stack (for example confirmation screens)
+ *
+ */
 enum e_state {
     STATIC_SCREEN,
     DYNAMIC_SCREEN,
 };
 
+/**
+ * @brief This structure holds all structure needed
+ *
+ */
 typedef struct {
+    /// dynamic display state
     struct {
         struct screen_data screen_stack[MAX_SCREEN_STACK_SIZE];
-        enum e_state current_state;  // State of the dynamic display
+        enum e_state current_state;  ///< State of the dynamic display
 
-        // Size of the screen stack
+        /// Size of the screen stack
         uint8_t screen_stack_size;
 
-        // Current index in the screen_stack.
+        /// Current index in the screen_stack.
         uint8_t formatter_index;
 
-        // Callback function if user accepted prompt.
+        /// Callback function if user accepted prompt.
         ui_callback_t ok_callback;
-        // Callback function if user rejected prompt.
+        /// Callback function if user rejected prompt.
         ui_callback_t cxl_callback;
 
-        // Title to be displayed on the screen.
+        /// Title to be displayed on the screen.
         char screen_title[PROMPT_WIDTH + 1];
-        // Value to be displayed on the screen.
+        /// Value to be displayed on the screen.
         char screen_value[VALUE_WIDTH + 1];
-        // Screensaver is on/off.
+        /// Screensaver is on/off.
         bool is_blank_screen;
     } dynamic_display;
 
-    apdu_handler handlers[INS_MAX + 1];
-    bip32_path_with_curve_t path_with_curve;
+    apdu_handler handlers[INS_MAX + 1];       ///< all handlers
+    bip32_path_with_curve_t path_with_curve;  ///< holds the bip32 path and curve of the current key
 
+    /// apdu handling state
     struct {
         union {
-            apdu_sign_state_t sign;
+            apdu_sign_state_t sign;  ///< state used to handle signing
 
+            /// state used to handle reset
             struct {
-                level_t reset_level;
+                level_t reset_level;  ///< requested reset level
             } baking;
 
+            /// state used to handle setup
             struct {
-                chain_id_t main_chain_id;
+                chain_id_t main_chain_id;  ///< requested new main chain id
+                /// requested new HWM information
                 struct {
-                    level_t main;
-                    level_t test;
+                    level_t main;  ///< level requested to be set on main HWM
+                    level_t test;  ///< level requested to be set on test HWM
                 } hwm;
             } setup;
 
-            apdu_hmac_state_t hmac;
+            apdu_hmac_state_t hmac;  ///< state used to handle hmac
         } u;
 
+        /// state used to store baking authorizing data
         struct {
-            nvram_data new_data;  // Staging area for setting N_data
+            nvram_data new_data;  ///< Staging area for setting N_data
         } baking_auth;
     } apdu;
 } globals_t;
@@ -155,12 +215,26 @@ extern globals_t global;
 extern nvram_data const N_data_real;
 #define N_data (*(volatile nvram_data *) PIC(&N_data_real))
 
+/**
+ * @brief Selects a HWM for a given chain id depending on the ram
+ *
+ *        Selects the main HWM of the ram if the main chain of the ram
+ *        is not defined, or if the given chain matches the main chain
+ *        of the ram. Selects the test HWM of the ram otherwise.
+ *
+ * @param chain_id: chain id
+ * @param ram: ram
+ * @return high_watermark_t*: selected HWM
+ */
 high_watermark_t volatile *select_hwm_by_chain(chain_id_t const chain_id,
                                                nvram_data volatile *const ram);
 
-// Properly updates NVRAM data to prevent any clobbering of data.
-// 'out_param' defines the name of a pointer to the nvram_data struct
-// that 'body' can change to apply updates.
+/**
+ * @brief Properly updates NVRAM data to prevent any clobbering of data
+ *
+ * @param out_name: defines the name of a pointer to the nvram_data struct
+ * @param body: defines the code to apply updates
+ */
 #define UPDATE_NVRAM(out_name, body)                                                    \
     ({                                                                                  \
         nvram_data *const out_name = &global.apdu.baking_auth.new_data;                 \