1.. _module-pw_system: 2 3========= 4pw_system 5========= 6.. warning:: 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 10pw_system is quite different from typical Pigweed modules. Rather than providing 11a single slice of vertical functionality, pw_system pulls together many modules 12across Pigweed to construct a working system with RPC, Logging, an OS 13Abstraction layer, and more. pw_system exists to greatly simplify the process 14of starting a new project using Pigweed by drastically reducing the required 15configuration space required to go from first signs of on-device life to a more 16sophisticated production-ready system. 17 18Trying out pw_system 19==================== 20If you'd like to give pw_system a spin and have a STM32F429I Discovery board, 21refer to the board's 22:ref:`target documentation<target-stm32f429i-disc1-stm32cube>` for instructions 23on how to build the demo and try things out 24 25If you don't have a discovery board, there's a simulated device variation that 26you can run on your local machine with no additional hardware. Check out the 27steps for trying this out :ref:`here<target-host-device-simulator>`. 28 29Target Bringup 30============== 31Bringing up a new device is as easy as 1-2-3! (Kidding, this is a work in 32progress) 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 55Pigweed's ``stm32f429i_disc1_stm32cube`` target demonstrates what's required by 56the first two steps. The third step is where you get to decide how to turn your 57new platform into a project that does something cool! It might be as simple as 58a blinking LED, or something more complex like a Bluetooth device that brews you 59a 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. 68 69GN Target Toolchain Template 70============================ 71This module includes a target toolchain template called ``pw_system_target`` 72that reduces the amount of work required to declare a target toolchain with 73pre-selected backends for pw_log, pw_assert, pw_malloc, pw_thread, and more. 74The configurability and extensibility of this template is relatively limited, 75as this template serves as a "one-size-fits-all" starting point rather than 76being foundational infrastructure. 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 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 } 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 } 149