Merge pull request #23 from gpappasv/dev/improve_doc

Improve documentation of the repository

Author: gpappasv

README.md

@@ -67,10 +67,17 @@ FLASH (rx)      : ORIGIN = 0x8000000, LENGTH = 32K /* 32K of flash is reserved f
 /* --- BOOTLOADER CONFIGURATION SPECIFIC INFORMATION END --- */
 ```
 
+NOTE: While configuring this part of the bootloader linker script you need to carefully consider the flash layout of your MCU.
+A good practice would be to always start the primary and secondary applications from the beginning of the desired flash page. Also you need to be careful to not have any overlaps between the two.
+Also, since the bootloader cannot update itself, once you flash the bootloader, you cannot modify the flash layout after that, on future application releases.
+
 - Adapt your application:
-Similarly to the bootloader, the application must also have that information inside its linker script.
+Similarly to the bootloader, the application should also have that information inside its linker script. This is optional though, in case that you need that information inside your application for any reason.
+
 It is important to not mess it up and be careful while copy-pasting that information to your linker script, as the tools that are provided under scripts/build_tools parse the application linker to find the relevant information. More information on how to use those tools can be found in the relevant README.md files.
 
+- Utilize the script **scripts/build_tools/create_dfu_image.py** to make your app binary compatible to the built bootloader. More info on how to use it can be found in **scripts/build_tools/README.md**. The modified binary will be exported to the current working directory.
+
 - You also need to modify the **private_key.pem** and **public_key.pem**, under **projects/**. They are being used to sign the application, and provide the bootloader with the relevant information on authenticating the signature.
 
 # Porting bootloader to other boards
@@ -79,7 +86,7 @@ design the project in a way to be as easily portable as possible. Still there ar
 in that area, but you could start by reading the **README.md**, under **projects/bootloader**. There, you can find some useful notes
 that can help you port the project faster to your board.
 
-**You can always reach out to me, to guide you through it.**
+**You can always reach out to me, to guide you through it. Feel free to push a commit, adding support for your board.**
 
 TODO: In the future, projects/bootloader/boards/<board_name> will contain all the **driver level** code for each specific board, and a simple define will utilize the correct board subfolder to build the bootloader.
 
@@ -88,10 +95,12 @@ TODO.
 
 # How to use
 1. Modify the bootloader (linker script/drivers) as you like based on the information provided before.
-2. Use the build.sh script to build the bootloader.bin.
+2. Use the build.sh script to build the bootloader.bin. (e.g. build.sh bootloader)
 3. Flash the bootloader.bin on flash address 0x08000000.
-4. You can develop your application following the example of projects/app. In that case, modify the linker script accordingly, update the private-public key pair and use the build.sh script to build the application.
-5. You can always have a binary yourself and utilize the underlying tools (create_dfu_image.py).
+4. You can develop your application following the example of projects/app. In that case, modify the linker script accordingly, update the private-public key pair and use the build.sh script to build the application. (e.g. build.sh all OR build.sh app)
+5. You can always have a binary yourself and utilize the underlying tools (create_dfu_image.py). With this script you can convert your binary to a compatible application to be used by the bootloader.
+
+IMPORTANT: More information about each script can be found inside the relevant folder that contains it.
 
 # Repository structure
 The structure of the repository is as follows:

scripts/build_tools/README.md

@@ -69,12 +69,25 @@ More information for that, can be found inside the python script.
 To utilize it for a specific binary, run the following command:
 
 ```bash
-python create_dfu_image.py </path/to/bin> <path/to/linker_script> <version_major> <version_minor> <patch>
+python create_dfu_image.py </path/to/bin> <path/to/linker_script> <version_major> <version_minor> <patch> <path/to/private_key>
 ```
 
 After the execution of this script, a new binary will be created that will be ready to be flashed to the board, and be compatible with out bootloader.
 Also, a yaml file will be produced that will contain information related to the final binary. (e.g. the crc, sha256 hash, version of the binary).
 
+The reason that this script needs the linker script of the bootloader is to find the following information:
+- Size of the application (both primary and secondary - which must be the same)
+- Size of the footer, to add the relevant information to the end of the binary. (Also location of the footer in flash)
+e.g. __flash_app_start__, __flash_app_end__, __header_app_crc_start__, __header_app_fw_version_start__, __header_app_hash_start__.
+
+Also the private key is used to sign the application.
+
+Note: This tool can be used on any application binary.
+E.g. Let's say you have an application (binary) of size 120kB.
+You configure the bootloader of this repository, to support an application binary of up to 230kB.
+You can easily use this script to adapt your binary based on the bootloader standards and make it compatible with it.
+Note: Don't forget to update the private-public key pair under **projects**. This is important to build your bootloader based on that pair and use the private key to sign your application. You need to create key pair based on ECDSA (chatgpt is your friend there :) )
+
 # extract public key python script description
 This script is being used pre-process a project firmware headerfile and rewrite it in order to add the public key information, in C-array format. The final result of that header file will be:
 ```bash
@@ -102,4 +115,6 @@ const uint8_t ecdsa_public_key[] = { <public_key info> };
 Usage:
 ```bash
 python extract_public_key.py <public_key.pem> <ecdsa_pub_key.h>
-```
+```
+
+Currently this is automatically being used by the build.sh script while building the bootloader.

scripts/build_tools/build.sh

@@ -57,7 +57,7 @@ create_dfu_image() {
 
     echo "Creating DFU image..."
     pwd
-    python create_dfu_image.py "$GIT_ROOT/$binary_path" "$GIT_ROOT/$linker_script" "$version_major" "$version_minor" "$version_patch" "$GIT_ROOT/$private_key_path"
+    python create_dfu_image.py "$GIT_ROOT/$binary_path" "$GIT_ROOT/$linker_script" "$version_major" "$version_minor" "$version_patch" "$GIT_ROOT/$private_key_path" 1
     #if python fails, try with python3
     if [ $? -ne 0 ]; then
         python3 create_dfu_image.py "$GIT_ROOT/$binary_path" "$GIT_ROOT/$linker_script" "$version_major" "$version_minor" "$version_patch" "$GIT_ROOT/$private_key_path"

scripts/build_tools/build_info.yaml

@@ -24,7 +24,7 @@ projects:
     dfu_image:
       enabled: true
       binary_path: "projects/app/build/app.bin"
-      linker_script: "projects/app/boards/stm32f401re/STM32F401RETx_FLASH.ld"
+      linker_script: "projects/bootloader/boards/stm32f401re/STM32F401RETx_FLASH.ld"
       version:
         major: 0
         minor: 1

scripts/build_tools/create_dfu_image.py

@@ -18,6 +18,7 @@
 import hashlib
 import os
 import yaml
+import shutil
 from cryptography.hazmat.primitives import hashes, serialization
 from cryptography.hazmat.primitives.asymmetric import ec
 from cryptography.hazmat.primitives.asymmetric.utils import Prehashed
@@ -182,7 +183,7 @@ def add_signature_to_footer(self):
         print(f"\nAdding post processed signature to the footer: {signature.hex()} of len: {len(signature)} bytes")
         self.binary_data[footer_start:footer_start + SIGNATURE_SIZE_BYTES] = signature
 
-    def commit_to_file(self, file_path):
+    def commit_to_file(self, file_path, export_bin_to_cwd=False):
         """
         Commits the modified binary data to the given file path.
 
@@ -196,7 +197,12 @@ def commit_to_file(self, file_path):
         # Determine the filename of the binary file
         binary_filename = os.path.basename(file_path)
         # Create the full path to write the binary file inside the update folder
-        update_file_path = os.path.join(update_folder, binary_filename)
+        if export_bin_to_cwd is False:
+            update_file_path = os.path.join(update_folder, binary_filename)
+        else:
+            cwd = os.getcwd()
+            print(f"Exporting binary to current working directory: {cwd}")
+            update_file_path = os.path.join(os.getcwd(), binary_filename)
 
         # Write the binary data to the specified file path
         with open(update_file_path, "wb") as binary_file:
@@ -213,8 +219,8 @@ def commit_to_file(self, file_path):
             yaml.dump(yaml_info, yaml_file, default_flow_style=False)
 
 def main():
-    if len(sys.argv) != 7:
-        print(f"Usage: {sys.argv[0]} <binary_file> <linker_script> <version_major> <version_minor> <version_patch> <private_key>")
+    if len(sys.argv) not in (7, 8):
+        print(f"Usage: {sys.argv[0]} <binary_file> <linker_script> <version_major> <version_minor> <version_patch> <private_key> [export_bin_to_cwd]")
         sys.exit(1)
 
     binary_file_path = sys.argv[1]
@@ -223,6 +229,9 @@ def main():
     version_minor = int(sys.argv[4])
     version_patch = int(sys.argv[5])
     private_key = sys.argv[6]
+    export_bin_to_cwd = True if len(sys.argv) == 7 or sys.argv[7].lower() == 'True' else False
+
+    print(f"export_bin_to_cwd: {export_bin_to_cwd}")
 
     try:
         with open(binary_file_path, "rb") as binary_file:
@@ -252,11 +261,11 @@ def main():
         analyzer.add_signature_to_footer()
 
         # Commit all the information to the binary (actually re-write the binary)
-        analyzer.commit_to_file(binary_file_path)
+        analyzer.commit_to_file(binary_file_path, export_bin_to_cwd)
 
     except Exception as e:
         print(f"Error: {e}")
         sys.exit(1)
 
 if __name__ == "__main__":
-    main()
+    main()