chore: document general and app attributes

Author: Joan-DwD

tockloader-lib/src/attributes/app_attributes.rs

@@ -114,7 +114,6 @@ impl AppAttributes {
             // 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;
             let mut footer_offset = binary_end_offset;
             let mut footer_number = 0;
@@ -175,19 +174,16 @@ impl AppAttributes {
                 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?;
@@ -214,13 +210,13 @@ impl AppAttributes {
             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).
+            // 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 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.
+            // 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,
@@ -253,7 +249,7 @@ impl AppAttributes {
                 //
                 // 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.
+                // 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

@@ -226,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`.
+        // 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)
+        // 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`.
+        // 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.
+        // 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)
@@ -306,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).
+        // 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 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.
+        // 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.
+        // 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?;
 
@@ -343,20 +343,20 @@ 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.
+        // 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 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 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.
+        // 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,