[gen2][supply secure] protobuf, dynalib and docs

Author: technobly

docs/artifacts.md

@@ -8,14 +8,14 @@ Artifact Name Composition
 
 |artifact name|@|semantic version|.|file extension|
 |:-:|:-:|:-:|:-:|:-:|
-|electron-bootloader|@|1.0.1-rc.1+lto.debug.jtag|.|bin|
+|boron-bootloader|@|1.0.1-rc.1|.|bin|
 
-**E.g.** `electron[email protected]+lto.debug.jtag.bin`
+**E.g.** `boron[email protected]`
 
 #### Filename Composition
 
 - Artifact Name
-  - Platform Name (`electron`)
+  - Platform Name (`boron`)
   - Module Name (`bootloader`)
 - Semantic Version
   - Major Version (`1`)
@@ -43,9 +43,9 @@ Folder Hierarchy
 
 |evaluated semantic version|/|platform|/|binary descriptor|
 |:-:|:-:|:-:|:-:|:-:|
-|1.0.1|/|electron|/|debug|
+|1.0.1|/|boron|/|debug|
 
-**E.g.** `1.0.1/electron/debug`
+**E.g.** `1.0.1/boron/debug`
 
 ### Hierarchical Composition
 
@@ -54,17 +54,17 @@ Folder Hierarchy
   - Minor Version (`0`)
   - Patch Version (`1`)
   - [_OPTIONAL_] Pre-release Tag (_none_)
-- Platform Name (`electron`)
+- Platform Name (`boron`)
 - Binary Descriptor (`debug`)
 
 Zip Artifacts
 -------------
 
 |company|_|product|@|evaluated semantic version|+|platform|.|content|.|file_extension|
 |:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
-|particle|_|device-os|@|1.0.1|+|electron|.|binaries|.|zip|
+|particle|_|device-os|@|1.0.1|+|boron|.|binaries|.|zip|
 
-**E.g.** `[email protected]+electron.binaries.zip`
+**E.g.** `[email protected]+boron.binaries.zip`
 
 ### Zip Filename Composition
 
@@ -77,7 +77,7 @@ Zip Artifacts
   - Patch Version (`1`)
   - [_OPTIONAL_] Prerelease Tag (_none_)
 - Filter
-  - [_OPTIONAL_] Platform Name (`electron`)
+  - [_OPTIONAL_] Platform Name (`boron`)
   - [_OPTIONAL_] Content Type (`binaries`)
 - File Extension (`bin`)
 

docs/build.md

@@ -35,19 +35,19 @@ When building firmware, it's a good idea to build from `main`, since this offers
 additional features compared to building in the root directory, such as `program-dfu` to flash
 the produced firmware to the device.
 
-## Updating System Firmware (Photon)
+## Updating System Firmware (Boron)
 
-When building locally on the photon from the develop branch, it is necessary
+When building locally on the boron from the develop branch, it is necessary
 to update the system firmware to the latest version:
 
-- put the Photon in DFU mode
+- put the Boron in DFU mode
 - `cd modules`
-- `make PLATFORM=photon clean all program-dfu`
+- `make clean all -s PLATFORM=boron program-dfu`
 - You can optionally add `APP`/`APPDIR`/`TEST` values to the command above to build a specific application as you would when building `main`.
 
 This will flash the latest system modules and the application to your device.
 
-A key indicator that this is necessary is that the Photon doesn't run your application
+A key indicator that this is necessary is that the Boron doesn't run your application
 after flashing, due to a version mismatch. The onboard LED will breathe magenta
 to indicate Safe Mode when the application firmware isn't run.
 
@@ -103,13 +103,11 @@ common are listed here:
 | Name     | PLATFORM_ID |
 |----------|:-----------:|
 | gcc      | 3           |
-| photon   | 6           |
-| p1       | 8           |
-| electron | 10          |
 | argon    | 12          |
 | boron    | 13          |
 | bsom     | 23          |
 | b5som    | 25          |
+| tracker  | 26          |
 
 The platform is specified on the command line using the platform ID
 
@@ -126,23 +124,23 @@ PLATFORM=name
 For example
 
 ```
-make PLATFORM=photon
+make PLATFORM=boron
 ```
-Would build the firmware for the Photon / P0.
+Would build the firmware for the Boron.
 
 To avoid repeatedly specifying the platform on the command line, it can be set
 as an environment variable.
 
 Linux/OS X:
 
 ```
-export PLATFORM=photon
+export PLATFORM=boron
 ```
 
 Windows
 
 ```
-set PLATFORM=photon
+set PLATFORM=boron
 ```
 
 In the commands that follow, we avoid listing the PLATFORM explicitly to keep
@@ -351,7 +349,7 @@ External Particle libraries can be compiled and linked with firmware. To add one
 2. remove the `examples` directory if it exists
 ```
 cd /particle/libs/neopixel
-rm -rf firmware/examples
+rm -rf device-os/examples
 ```
 
 3. Rename `firmware` to be the same as the library name. 
@@ -427,31 +425,6 @@ the device will then automatically enter DFU mode and flash the firmware.
 (Tested on OS X. Should work on other platforms that provide the `stty` command.)
 
 
-## Flashing the firmware to the device via ST-Link
-
-The `st-flash` target can be used to flash all executable code (bootloader, main and modules)
-to the device. The flash uses the `st-flash` tool, which should be in your system path.
-
-# Debugging
-
-To enable JTAG debugging, add this to the command line:
-
-```
-USE_SWD_JTAG=y
-```
-
-and perform a clean build.
-
-To enable SWD debugging only (freeing up 2 pins) add:
-
-```
-USE_SWD=y
-```
-
-and perform a clean build. For more details on SWD-only debugging
-see https://github.com/spark/firmware/pull/337
-
-
 ## Building the `develop` branch
 
 Before the 0.4.0 firmware was released, we recommended the develop branch for early adopters to obtain the code. This is still fine for early adopters, and people that want the bleeding edge, although please keep in mind the code is untested and unreleased.
@@ -464,36 +437,32 @@ Pre-releases are available in `release/vx.x.x-rc.x` branches.  Default released
 - The variables passed to make can also be provided as environment variables,
 so you avoid having to type them out for each build. The environment variable value can be overridden
 by passing the variable on the command line.
-- `PLATFORM` set in the environment if you mainly build for one platform, e.g. the Photon.
+- `PLATFORM` set in the environment if you mainly build for one platform, e.g. the Boron.
 
-### Photon
+### Boron
 
-Here are some common recipes when working with the photon. Note that `PLATFORM=photon` doesn't need to be present if you have `PLATFORM=photon` already defined in your environment.
+Here are some common recipes when working with the boron. Note that `PLATFORM=boron` doesn't need to be present if you have `PLATFORM=boron` already defined in your environment.
 
 ```
 # Complete rebuild and DFU flash of latest system and application firmware
-firmware/modules$ make clean all program-dfu PLATFORM=photon
+device-os/modules$ make clean all program-dfu PLATFORM=boron
 
 # Incremental build and flash of latest system and application firmware
-firmware/modules$ make all program-dfu PLATFORM=photon
-
-# Build system and application for use with debugger (Programmer Shield)
-# APP/APPDIR can also be specified here to build the non-default application
-firmware/modules$ make clean all program-dfu PLATFORM=photon USE_SWD_JTAG=y
+device-os/modules$ make all program-dfu PLATFORM=boron
 
-# Incremental build and flash user application.cpp only (note the directory)
-firmware/main$ make all program-dfu PLATFORM=photon
+# Incremental build and flash user application.cpp only (note the main/ directory)
+device-os/main$ make all program-dfu PLATFORM=boron
 
 # Build an external application
-firmware/modules$ make all PLATFORM=photon APPDIR=~/my_app
+device-os/modules$ make all PLATFORM=boron APPDIR=~/my_app
 ```
 
 For system firmware developers:
 
 ```
 # Rebuild and flash the primary unit test application
-firmware/main$ make clean all program-dfu TEST=wiring/no_fixture PLATFORM=photon
+device-os/main$ make clean all -s TEST=wiring/no_fixture PLATFORM=boron program-dfu
 
 # Build the compilation test (don't flash on device)
-firmware/main$ make TEST=wiring/api PLATFORM=photon
+device-os/main$ make clean all -s TEST=wiring/api PLATFORM=boron
 ```

docs/debugging.md

@@ -6,6 +6,6 @@ The firmware includes a debugging aid that enables debug output, from the system
 To create a debug build, add `DEBUG_BUILD=y` to the `make` command line. If the previous build was not a debug build then
 you should add `clean` to perform a clean build.
 
-On the photon, the system modules must also be rebuilt also with `DEBUG_BUILD` set.
+On the device, the system module(s) must also be rebuilt also with `DEBUG_BUILD` set.
 
 Since 0.6.0 the firmware includes newer logging framework. The system API is described in the services/inc/logging.h file. The application API is described in the firmware reference: docs/reference/firmware.md

docs/dependencies.md

@@ -10,7 +10,7 @@ Building the firmware locally requires these dependencies ot be installed:
 6. [Command line tools](#6-command-line-tools)
 
 #### 1. GCC for ARM Cortex processors
-The Photon uses an ARM Cortex M3 CPU based microcontroller. All of the code is built around the GNU GCC toolchain offered and maintained by ARM.
+Particle devices use an ARM Cortex Mx CPU based microcontroller. All of the code is built around the GNU GCC toolchain offered and maintained by ARM.
 
 The build requires version 10.2.1 (10-2020-q4-major) or newer of ARM GCC and will print an error
 message if the version is older than this.

docs/gettingstarted.md

@@ -40,7 +40,7 @@ Open up a terminal window, and switch branch to 'release/stable'
 Navigate to the `modules` folder under firmware
 (i.e. `cd firmware/modules`) and type:
 
-    make clean all PLATFORM=photon -s program-dfu
+    make clean all -s PLATFORM=boron program-dfu
 
 This will clean build the system firmware and the default main application (`firmware/user/src/application.cpp`) which contains Tinker, but you may overwrite this with your own application and add any required dependencies. The `-s` silences the verbose output, so be patient while it builds.  If your device is in DFU mode, it will then download the 3 binaries one at a time.  For more custom application location solutions, see the [makefile documentation](build.md) and learn how to use the `APP=myapp` option.
 
@@ -80,7 +80,7 @@ the various libraries that make up the firmware.
 | **wiring** | the Wiring API |
 | **user** | contains the default application code (Tinker) and your own applications |
 | **main** | top-level project to build the firmware for a device |
-| **modules** | dynamically linked modules for the Photon/PØ/P1 |
+| **modules** | dynamically linked modules |
 
 Within each library, the structure is
 
@@ -115,14 +115,15 @@ A flash of white then flashing green can happen when you get this wrong. You wan
 2. Open up a terminal window on your computer and type this command to find out if the device indeed being detected correctly.
 
    `dfu-util -l`
-   you should get something similar to this in return:
+   you should get something similar to this in return (e.g. for Boron):
    ```
-   Found DFU: [1d50:607f] devnum=0, cfg=1, intf=0, alt=0, name="@Internal Flash  /0x08000000/20*001Ka,108*001Kg"
-   Found DFU: [1d50:607f] devnum=0, cfg=1, intf=0, alt=1, name="@SPI Flash : SST25x/0x00000000/512*04Kg"
+   Found DFU: [2b04:d00d] ver=0251, devnum=18, cfg=1, intf=0, path="0-3.4.2", alt=2, name="@External Flash   /0x80000000/1024*004Kg", serial="123412341234123412341234"
+   Found DFU: [2b04:d00d] ver=0251, devnum=18, cfg=1, intf=0, path="0-3.4.2", alt=1, name="@DCD Flash   /0x00000000/1*016Ke", serial="123412341234123412341234"
+   Found DFU: [2b04:d00d] ver=0251, devnum=18, cfg=1, intf=0, path="0-3.4.2", alt=0, name="@Internal Flash   /0x00000000/1*004Ka,47*004Kg,192*004Kg,4*004Kg,4*004Kg,8*004Ka", serial="123412341234123412341234"
    ```
 
    - Windows users will need to use the Zatig utility to replace the USB driver as described earlier
-   - Linux users who encounter someting like: `dfu-util: Cannot open DFU device 2b04:d00a` can try `sudo dfu-util -l` or if you use the Particle CLI command `particle flash --usb` or `particle update` it will add the device udev rules automatically for you.
+   - Linux users who encounter someting like: `dfu-util: Cannot open DFU device 2b04:d00d` can try `sudo dfu-util -l` or if you use the Particle CLI command `particle flash --usb` or `particle update` it will add the device udev rules automatically for you.
 
 
 3. Now, from the `main/` folder in your firmware repository and use the following command to transfer the *.bin* file into the device.
@@ -138,4 +139,4 @@ the `dfu-util` command. You can ignore this message for now.  We're not sure wha
 
 * If you are having trouble with dfu-util, (like invalid dfuse address), try a newer version of dfu-util. v0.7 works well.
 
-**Still having troubles?** Checkout our [resources page](https://www.particle.io/resources), hit us up on IRC, etc.
+**Still having troubles?** Checkout our [Docs](https://docs.particle.io/).

dynalib/inc/module_info.inc

@@ -23,14 +23,15 @@
  */
 
 #include "module_info.h"
+#include "platforms.h"
 
-#if PLATFORM_ID==3 || PLATFORM_ID == 20
+#if PLATFORM_ID == PLATFORM_GCC
 #define _ARM_SECTION(x)
 char link_module_start;
 char link_module_end;
 #else
 #define _ARM_SECTION(x) ,x
-#endif
+#endif // PLATFORM_ID == PLATFORM_GCC
 
 
 module_function_t module_function_(uint8_t f) {
@@ -115,7 +116,7 @@ extern char link_module_end;
 #error MODULE_DEPENDENCY2 not defined
 #endif
 
-#if PLATFORM_ID!=3
+#if PLATFORM_ID != PLATFORM_GCC
 __attribute__((section(".modinfo.module_info"), used))
 
 const module_info_t module_info = {
@@ -150,4 +151,4 @@ __attribute__((section(".modinfo.module_info_crc"), used)) const module_info_crc
 }
 #endif // __cplusplus
 
-#endif
+#endif // PLATFORM_ID != PLATFORM_GCC

dynalib/src/readme.md

@@ -1,5 +1,7 @@
 # Module Info
 
+> TODO: Update for Gen3
+
 The `module_info.h` file describes the structure of the block of metadata (module info) that is
 inserted into modules supporting self-describing memory location and CRC checks.