Carlos Chinchilla | e8275d3 | 2021-12-08 09:46:35 -0800 | [diff] [blame] | 1 | .. _module-pw_system: |
| 2 | |
| 3 | ========= |
| 4 | pw_system |
| 5 | ========= |
| 6 | .. warning:: |
Chad Norvell | ae92f3d | 2022-02-17 02:40:41 -0800 | [diff] [blame] | 7 | This module is an early work-in-progress towards an opinionated framework for |
| 8 | new projects built on Pigweed. It is under active development, so stay tuned! |
| 9 | |
Armando Montanez | ce59a87 | 2022-03-16 11:14:28 -0700 | [diff] [blame] | 10 | pw_system is quite different from typical Pigweed modules. Rather than providing |
| 11 | a single slice of vertical functionality, pw_system pulls together many modules |
| 12 | across Pigweed to construct a working system with RPC, Logging, an OS |
| 13 | Abstraction layer, and more. pw_system exists to greatly simplify the process |
| 14 | of starting a new project using Pigweed by drastically reducing the required |
| 15 | configuration space required to go from first signs of on-device life to a more |
| 16 | sophisticated production-ready system. |
Chad Norvell | ae92f3d | 2022-02-17 02:40:41 -0800 | [diff] [blame] | 17 | |
Armando Montanez | ce59a87 | 2022-03-16 11:14:28 -0700 | [diff] [blame] | 18 | Trying out pw_system |
| 19 | ==================== |
| 20 | If you'd like to give pw_system a spin and have a STM32F429I Discovery board, |
| 21 | refer to the board's |
| 22 | :ref:`target documentation<target-stm32f429i-disc1-stm32cube>` for instructions |
| 23 | on how to build the demo and try things out |
| 24 | |
| 25 | If you don't have a discovery board, there's a simulated device variation that |
| 26 | you can run on your local machine with no additional hardware. Check out the |
| 27 | steps for trying this out :ref:`here<target-host-device-simulator>`. |
| 28 | |
| 29 | Target Bringup |
| 30 | ============== |
| 31 | Bringing up a new device is as easy as 1-2-3! (Kidding, this is a work in |
| 32 | progress) |
| 33 | |
| 34 | #. **Create a ``pw_system_target`` in your GN build.** |
| 35 | This is what will control the configuration of your target from a build |
| 36 | system level. This includes which compiler will be used, what architecture |
| 37 | flags will be used, which backends will be used, and more. A large quantity |
| 38 | of configuration will be pre-set to work with pw_system after you select the |
| 39 | CPU and scheduler your target will use, but your target will likely need to |
| 40 | set a few other things to get to a fully working state. |
| 41 | #. **Write target-specific initialization.** |
| 42 | Most embedded devices require a linker script, manual initialization of |
| 43 | memory, and some clock initialization. pw_system leaves this to users to |
| 44 | implement as the exact initialization sequence can be very project-specific. |
| 45 | All that's required is that after early memory initialization and clock |
| 46 | configuration is complete, your target initialization should call |
| 47 | ``pw::system::Init()`` and then start the RTOS scheduler (e.g. |
| 48 | ``vTaskStartScheduler()``). |
| 49 | #. **Implement ``pw::system::UserAppInit()`` in your application.** |
| 50 | This is where most of your project's application-specific logic goes. This |
| 51 | could be starting threads, registering RPC services, turning on Bluetooth, |
| 52 | or more. In ``UserAppInit()``, the RTOS will be running so you're free to use |
| 53 | OS primitives and use features that rely on threading (e.g. RPC, logging). |
| 54 | |
| 55 | Pigweed's ``stm32f429i_disc1_stm32cube`` target demonstrates what's required by |
| 56 | the first two steps. The third step is where you get to decide how to turn your |
| 57 | new platform into a project that does something cool! It might be as simple as |
| 58 | a blinking LED, or something more complex like a Bluetooth device that brews you |
| 59 | a cup of coffee whenever ``pw watch`` kicks off a new build. |
| 60 | |
| 61 | .. note:: |
| 62 | Because of the nature of the hard-coded conditions in ``pw_system_target``, |
| 63 | you may find that some options are missing for various RTOSes and |
| 64 | architectures. The design of the GN integration is still a work-in-progress |
| 65 | to improve the scalability of this, but in the meantime the Pigweed team |
| 66 | welcomes contributions to expand the breadth of RTOSes and architectures |
| 67 | supported as ``pw_system_target``\s. |
Armando Montanez | cf1c020 | 2021-12-10 14:06:54 -0800 | [diff] [blame] | 68 | |
| 69 | GN Target Toolchain Template |
| 70 | ============================ |
| 71 | This module includes a target toolchain template called ``pw_system_target`` |
| 72 | that reduces the amount of work required to declare a target toolchain with |
| 73 | pre-selected backends for pw_log, pw_assert, pw_malloc, pw_thread, and more. |
Armando Montanez | 5768d5d | 2022-01-04 11:32:58 -0800 | [diff] [blame] | 74 | The configurability and extensibility of this template is relatively limited, |
| 75 | as this template serves as a "one-size-fits-all" starting point rather than |
| 76 | being foundational infrastructure. |
Armando Montanez | cf1c020 | 2021-12-10 14:06:54 -0800 | [diff] [blame] | 77 | |
| 78 | .. code-block:: |
| 79 | |
| 80 | # Declare a toolchain with suggested, compiler, compiler flags, and default |
| 81 | # backends. |
| 82 | pw_system_target("stm32f429i_disc1_stm32cube_size_optimized") { |
| 83 | # These options drive the logic for automatic configuration by this |
| 84 | # template. |
| 85 | cpu = PW_SYSTEM_CPU.CORTEX_M4F |
| 86 | scheduler = PW_SYSTEM_SCHEDULER.FREERTOS |
| 87 | |
| 88 | # The pre_init source set provides things like the interrupt vector table, |
| 89 | # pre-main init, and provision of FreeRTOS hooks. |
| 90 | link_deps = [ "$dir_pigweed/targets/stm32f429i_disc1_stm32cube:pre_init" ] |
| 91 | |
| 92 | # These are hardware-specific options that set up this particular board. |
| 93 | # These are declared in ``declare_args()`` blocks throughout Pigweed. Any |
| 94 | # build arguments set by the user will be overridden by these settings. |
| 95 | build_args = { |
| 96 | pw_third_party_freertos_CONFIG = "$dir_pigweed/targets/stm32f429i_disc1_stm32cube:stm32f4xx_freertos_config" |
| 97 | pw_third_party_freertos_PORT = "$dir_pw_third_party/freertos:arm_cm4f" |
| 98 | pw_sys_io_BACKEND = dir_pw_sys_io_stm32cube |
Armando Montanez | cf1c020 | 2021-12-10 14:06:54 -0800 | [diff] [blame] | 99 | dir_pw_third_party_stm32cube = dir_pw_third_party_stm32cube_f4 |
| 100 | pw_third_party_stm32cube_PRODUCT = "STM32F429xx" |
| 101 | pw_third_party_stm32cube_CONFIG = |
| 102 | "//targets/stm32f429i_disc1_stm32cube:stm32f4xx_hal_config" |
| 103 | pw_third_party_stm32cube_CORE_INIT = "" |
| 104 | pw_boot_cortex_m_LINK_CONFIG_DEFINES = [ |
| 105 | "PW_BOOT_FLASH_BEGIN=0x08000200", |
| 106 | "PW_BOOT_FLASH_SIZE=2048K", |
| 107 | "PW_BOOT_HEAP_SIZE=7K", |
| 108 | "PW_BOOT_MIN_STACK_SIZE=1K", |
| 109 | "PW_BOOT_RAM_BEGIN=0x20000000", |
| 110 | "PW_BOOT_RAM_SIZE=192K", |
| 111 | "PW_BOOT_VECTOR_TABLE_BEGIN=0x08000000", |
| 112 | "PW_BOOT_VECTOR_TABLE_SIZE=512", |
| 113 | ] |
| 114 | } |
| 115 | } |
skeys | 6444528 | 2022-01-26 17:21:52 -0800 | [diff] [blame] | 116 | |
| 117 | # Example for the Emcraft SmartFusion2 system-on-module |
| 118 | pw_system_target("emcraft_sf2_som_size_optimized") { |
| 119 | cpu = PW_SYSTEM_CPU.CORTEX_M3 |
| 120 | scheduler = PW_SYSTEM_SCHEDULER.FREERTOS |
| 121 | |
| 122 | link_deps = [ "$dir_pigweed/targets/emcraft_sf2_som:pre_init" ] |
| 123 | build_args = { |
| 124 | pw_log_BACKEND = dir_pw_log_basic #dir_pw_log_tokenized |
| 125 | pw_tokenizer_GLOBAL_HANDLER_WITH_PAYLOAD_BACKEND = "//pw_system:log" |
| 126 | pw_third_party_freertos_CONFIG = "$dir_pigweed/targets/emcraft_sf2_som:sf2_freertos_config" |
| 127 | pw_third_party_freertos_PORT = "$dir_pw_third_party/freertos:arm_cm3" |
| 128 | pw_sys_io_BACKEND = dir_pw_sys_io_emcraft_sf2 |
| 129 | dir_pw_third_party_smartfusion_mss = dir_pw_third_party_smartfusion_mss_exported |
| 130 | pw_third_party_stm32cube_CONFIG = |
| 131 | "//targets/emcraft_sf2_som:sf2_mss_hal_config" |
| 132 | pw_third_party_stm32cube_CORE_INIT = "" |
| 133 | pw_boot_cortex_m_LINK_CONFIG_DEFINES = [ |
| 134 | "PW_BOOT_FLASH_BEGIN=0x00000200", |
| 135 | "PW_BOOT_FLASH_SIZE=200K", |
| 136 | |
| 137 | # TODO(pwbug/219): Currently "pw_tokenizer/detokenize_test" requires at |
| 138 | # least 6K bytes in heap when using pw_malloc_freelist. The heap size |
| 139 | # required for tests should be investigated. |
| 140 | "PW_BOOT_HEAP_SIZE=7K", |
| 141 | "PW_BOOT_MIN_STACK_SIZE=1K", |
| 142 | "PW_BOOT_RAM_BEGIN=0x20000000", |
| 143 | "PW_BOOT_RAM_SIZE=64K", |
| 144 | "PW_BOOT_VECTOR_TABLE_BEGIN=0x00000000", |
| 145 | "PW_BOOT_VECTOR_TABLE_SIZE=512", |
| 146 | ] |
| 147 | } |
| 148 | } |