chore: document general and app attributes

Author: Joan-DwD

tockloader-lib/src/attributes/app_attributes.rs

@@ -48,8 +48,8 @@ impl AppAttributes {
     ///   The function below is used to retrieve header and footer data
     ///
     ///   Starting from the 0x40000 address,
-    ///   using the 'parse_tbf_header_lengths' function, we read the very first 8 bytes to determine:
-    /// 
+    ///   using the ['parse_tbf_header_lengths'] function, we read the very first 8 bytes to determine:
+    ///
     ///   - tbf-version
     ///   - header_size
     ///   - total_size
@@ -109,10 +109,10 @@ impl AppAttributes {
                 .map_err(TockloaderError::ParsingError)?;
 
             let binary_end_offset = header.get_binary_end(); // the end of the header marks the beginning of the footer
-            
-            /// 1. Calculate the total size of all footers by subtracting the binary's end offset (`binary_end_offset`) from the total application size (`total_size`).
-            /// 2. Initialize the reading offset (`footer_offset`) to the start of the footers (right after the binary ends).
-            /// 3. Loop until we've read all footers (when `footer_offset` reaches `total_size`):
+
+            // 1. Calculate the total size of all footers by subtracting the binary's end offset (`binary_end_offset`) from the total application size (`total_size`).
+            // 2. Initialize the reading offset (`footer_offset`) to the start of the footers (right after the binary ends).
+            // 3. Loop until we've read all footers (when `footer_offset` reaches `total_size`):
             let mut footers: Vec<TbfFooter> = vec![];
             let mut footers: Vec<TbfFooter> = vec![];
             let total_footers_size = total_size - binary_end_offset;
@@ -172,25 +172,25 @@ impl AppAttributes {
             let mut pkt = (appaddr as u32).to_le_bytes().to_vec(); // the tockloader protocol only supports up to 32 bytes, hence we converted acquiring 4 byte little endians.
             let length = (8_u16).to_le_bytes().to_vec(); // 2 byte little endians
             for i in length {
-                pkt.push(i); 
+                pkt.push(i);
             }
-            
-            ///   This sends a `ReadRange` command to the microcontroller to read 8 bytes of memory starting at `appaddr`,
-            ///   and receives the result over the serial connection.
-            ///  
-            ///   The microcontroller receives the command, checks the Command ID (`0x06` for `ReadRange`),
-            ///   then reads the 1-byte payload length and the actual payload:
-            ///   4 bytes for the address (little-endian), and 2 bytes for the length to read (also little-endian).
-            ///
-            ///   The microcontroller processes incoming bytes using a state machine like this:
-            ///
-            ///   enum SerialState {
-            ///     WaitingForCommand, // Awaiting the 1-byte command ID
-            ///     WaitingForLength,  // Awaiting the 1-byte payload length
-            ///     WaitingForPayload { command: u8, length: usize, buffer: Vec<u8> }, // Receiving payload
-            ///   }
+
+            //  This sends a `ReadRange` command to the microcontroller to read 8 bytes of memory starting at `appaddr`,
+            //  and receives the result over the serial connection.
+            // 
+            //  The microcontroller receives the command, checks the Command ID (`0x06` for `ReadRange`),
+            //  then reads the 1-byte payload length and the actual payload:
+            //  4 bytes for the address (little-endian), and 2 bytes for the length to read (also little-endian).
+            //
+            //  The microcontroller processes incoming bytes using a state machine like this:
+            //
+            //  enum SerialState {
+            //    WaitingForCommand, // Awaiting the 1-byte command ID
+            //    WaitingForLength,  // Awaiting the 1-byte payload length
+            //    WaitingForPayload { command: u8, length: usize, buffer: Vec<u8> }, // Receiving payload
+            //   }
             let (_, appdata) = // the first element in the tuple be returned is raw data so we ignore it and take the second which is the app data we need
-                issue_command(port, Command::ReadRange, pkt, true, 8, Response::ReadRange).await?; 
+                issue_command(port, Command::ReadRange, pkt, true, 8, Response::ReadRange).await?;
 
             let tbf_version: u16;
             let header_size: u16;
@@ -208,19 +208,19 @@ impl AppAttributes {
                 }
                 _ => break,
             };
-            
+
             let mut pkt = (appaddr as u32).to_le_bytes().to_vec();
             let length = (header_size).to_le_bytes().to_vec();
             for i in length {
                 pkt.push(i);
             }
-            ///   This also sends a ReadRange command to fetch the full TBF header from the same app address (appaddr).
-            ///
-            ///   The first read (8 bytes) gave us only the header lengths and total size,
-            ///   but now that we know the full header size (header_size), we send a new request to retrieve the entire header.
-            ///
-            ///   The returned data (header_data) is a raw byte vector containing all fields of the TBF header,
-            ///   including version, flags, entry point, protected regions, package name, etc.
+            //  This also sends a ReadRange command to fetch the full TBF header from the same app address (appaddr).
+            //
+            //  The first read (8 bytes) gave us only the header lengths and total size,
+            //  but now that we know the full header size (header_size), we send a new request to retrieve the entire header.
+            //
+            //  The returned data (header_data) is a raw byte vector containing all fields of the TBF header,
+            //  including version, flags, entry point, protected regions, package name, etc.
             let (_, header_data) = issue_command(
                 port,
                 Command::ReadRange,
@@ -249,11 +249,11 @@ impl AppAttributes {
                     pkt.push(i);
                 }
 
-                ///   Issue a ReadRange command over serial to fetch the next footer block.
-                ///
-                ///   The response contains raw bytes starting from footer_offset, with the desired length.
-                ///
-                ///   We ignore the first tuple element and keep only the returned footer bytes.
+                // Issue a ReadRange command over serial to fetch the next footer block.
+                //
+                // The response contains raw bytes starting from footer_offset, with the desired length.
+                //
+                //  We ignore the first tuple element and keep only the returned footer bytes.
                 let (_, appfooter) = issue_command(
                     port,
                     Command::ReadRange,

tockloader-lib/src/attributes/system_attributes.rs

@@ -99,11 +99,11 @@ impl SystemAttributes {
             };
 
             let step_option = decode_attribute(step);
-            
-            /// If the attribute chunk was successfully decoded, assign its value to the corresponding field in `result`
-            /// based on the index:
-            /// 0 = board name, 1 = architecture, 2 = application start address (parsed from hex string), 3 = boot hash,
-            /// _ = invalid or missing data is skipped.
+
+            // If the attribute chunk was successfully decoded, assign its value to the corresponding field in `result`
+            // based on the index:
+            // 0 = board name, 1 = architecture, 2 = application start address (parsed from hex string), 3 = boot hash,
+            // _ = invalid or missing data is skipped.
             if let Some(decoded_attributes) = step_option {
                 match index_data {
                     0 => {
@@ -162,8 +162,8 @@ impl SystemAttributes {
                     "No start address found.".to_owned(),
                 ))? - 100,
                 &mut kernel_attr_binary,
-            )    
-            .map_err(TockloaderError::ProbeRsReadError)?;  // The address is calculated as `(appaddr - 100)`, where `appaddr` marks the beginning of application binaries in flash.
+            )
+            .map_err(TockloaderError::ProbeRsReadError)?; // The address is calculated as `(appaddr - 100)`, where `appaddr` marks the beginning of application binaries in flash.
 
         // Parse fixed fields from footer block
         let sentinel = bytes_to_string(&kernel_attr_binary[96..100]); // Expect "TOCK" as usual
@@ -174,18 +174,17 @@ impl SystemAttributes {
 
         let kernel_binary_start = LittleEndian::read_u32(&kernel_attr_binary[68..72]);
         let kernel_binary_len = LittleEndian::read_u32(&kernel_attr_binary[72..76]);
-        /// This what it looks like:
-        ///
-        /// - 0-79: is for padding, basically unused.
-        /// - 80-84:  app_mem_start (u32, little-endian)
-        /// - 84-88:  app_mem_len (u32)
-        /// - 88-92:  kernel_mem_start (u32)
-        /// - 92-96:  kernel_mem_len (u32)
-        /// - 96-100: Sentinel ("TOCK" ASCII)
-        /// - 95-96:  Kernel version (u8)
-
+        //   This what it looks like:
+        //
+        // - 0-79: is for padding, basically unused.
+        // - 80-84:  app_mem_start (u32, little-endian)
+        // - 84-88:  app_mem_len (u32)
+        // - 88-92:  kernel_mem_start (u32)
+        // - 92-96:  kernel_mem_len (u32)
+        // - 96-100: Sentinel ("TOCK" ASCII)
+        // - 95-96:  Kernel version (u8)
         // Store parsed values in result struct
-        result.sentinel = Some(sentinel); 
+        result.sentinel = Some(sentinel);
         result.kernel_version = Some(kernel_version);
         result.app_mem_start = Some(app_memory_start);
         result.app_mem_len = Some(app_memory_len);
@@ -227,18 +226,18 @@ impl SystemAttributes {
             pkt.push(i); // Merges the two, making them 6 bytes in the vector
         }
 
-        ///   This sends a `ReadRange` command to the microcontroller to read 1024 bytes of memory starting at address `0x600`.
-        ///
-        ///   The microcontroller expects the command in this structure:
-        ///      - 1 byte: Command ID (`0x06` or `0x10` for `ReadRange`)
-        ///      - 1 byte: Payload length (always 6 bytes for this command)
-        ///      - 6 bytes payload:
-        ///        - 4 bytes: Start address (little-endian)
-        ///        - 2 bytes: Number of bytes to read (little-endian)
-        ///
-        /// In this case, we’re reading system attributes stored in memory starting at `0x600`.
-        ///
-        /// The 1024-byte response will contain multiple 64-byte attribute blocks, each of which may encode a (key, value) pair.
+        //  This sends a `ReadRange` command to the microcontroller to read 1024 bytes of memory starting at address `0x600`.
+        //
+        //  The microcontroller expects the command in this structure:
+        //      - 1 byte: Command ID (`0x06` or `0x10` for `ReadRange`)
+        //      - 1 byte: Payload length (always 6 bytes for this command)
+        //      - 6 bytes payload:
+        //        - 4 bytes: Start address (little-endian)
+        //        - 2 bytes: Number of bytes to read (little-endian)
+        //
+        //   In this case, we’re reading system attributes stored in memory starting at `0x600`.
+        //
+        //   The 1024-byte response will contain multiple 64-byte attribute blocks, each of which may encode a (key, value) pair.
         let (_, buf) = issue_command(
             port,
             Command::ReadRange, // Read memory (e.g. 0x10)
@@ -307,19 +306,19 @@ impl SystemAttributes {
             pkt.push(i); // Append length
         }
 
-        ///   This sends a `ReadRange` command to read 8 bytes from address `0x40E`,
-        ///   which stores the bootloader version string (UTF-8 encoded).
-        ///
-        ///   The serial protocol proceeds as follows:
-        ///     - 1 byte: Command ID
-        ///     - 1 byte: Payload length = 6
-        ///   - Payload =
-        ///       - 4 bytes: Address (0x40E, little-endian)
-        ///       - 2 bytes: Length (`8`, little-endian)
-        ///
-        ///   The response is expected to be a UTF-8 encoded string, often null-terminated.
-        ///
-        ///   We decode the returned bytes into a `String`, trimming any null characters from the end.
+        //   This sends a `ReadRange` command to read 8 bytes from address `0x40E`,
+        //   which stores the bootloader version string (UTF-8 encoded).
+        //
+        //   The serial protocol proceeds as follows:
+        //     - 1 byte: Command ID
+        //     - 1 byte: Payload length = 6
+        //   - Payload =
+        //       - 4 bytes: Address (0x40E, little-endian)
+        //       - 2 bytes: Length (`8`, little-endian)
+        //
+        //   The response is expected to be a UTF-8 encoded string, often null-terminated.
+        //
+        //   We decode the returned bytes into a `String`, trimming any null characters from the end.
         let (_, buf) =
             issue_command(port, Command::ReadRange, pkt, true, 8, Response::ReadRange).await?;
 
@@ -344,21 +343,21 @@ impl SystemAttributes {
             pkt.push(i); // Append length
         }
 
-            ///   This sends a `ReadRange` command to read the last 100 bytes before the start of the application space,
-            ///   which usually contains the kernel’s footer region.
-            ///
-            ///   The address is calculated as `(appaddr - 100)`, where `appaddr` marks the beginning of application binaries in flash.
-            ///
-            ///   The request structure is:
-            ///     - 1 byte: Command ID (`0x06`)
-            ///     - 1 byte: Payload length = 6
-            ///     - Payload =
-            ///       - 4 bytes: Address (`appaddr - 100`, little-endian)
-            ///       - 2 bytes: Length (`100`, little-endian)
-            ///
-            ///   The microcontroller responds with 100 bytes from that memory region.
-            ///   These bytes might contain metadata or checksums relevant to the kernel image.
-                let (_, kernel_attr_binary) = issue_command(
+        //  This sends a `ReadRange` command to read the last 100 bytes before the start of the application space,
+        //  which usually contains the kernel’s footer region.
+        //
+        //  The address is calculated as `(appaddr - 100)`, where `appaddr` marks the beginning of application binaries in flash.
+        //
+        //  The request structure is:
+        //    - 1 byte: Command ID (`0x06`)
+        //    - 1 byte: Payload length = 6
+        //    - Payload =
+        //      - 4 bytes: Address (`appaddr - 100`, little-endian)
+        //      - 2 bytes: Length (`100`, little-endian)
+        //
+        //  The microcontroller responds with 100 bytes from that memory region.
+        //  These bytes might contain metadata or checksums relevant to the kernel image.
+        let (_, kernel_attr_binary) = issue_command(
             port,
             Command::ReadRange,
             pkt,