pw_system/docs.rst - pigweed/pigweed - Git at Google

 .. _module-pw_system:

 =========
 pw_system
 =========
 .. warning::
   This module is an early work-in-progress towards an opinionated framework for
   new projects built on Pigweed. It is under active development, so stay tuned!

 pw_system is quite different from typical Pigweed modules. Rather than providing
 a single slice of vertical functionality, pw_system pulls together many modules
 across Pigweed to construct a working system with RPC, Logging, an OS
 Abstraction layer, and more. pw_system exists to greatly simplify the process
 of starting a new project using Pigweed by drastically reducing the required
 configuration space required to go from first signs of on-device life to a more
 sophisticated production-ready system.

 Trying out pw_system
 ====================
 If you'd like to give pw_system a spin and have a STM32F429I Discovery board,
 refer to the board's
 :ref:`target documentation<target-stm32f429i-disc1-stm32cube>` for instructions
 on how to build the demo and try things out

 If you don't have a discovery board, there's a simulated device variation that
 you can run on your local machine with no additional hardware. Check out the
 steps for trying this out :ref:`here<target-host-device-simulator>`.

 Target Bringup
 ==============
 Bringing up a new device is as easy as 1-2-3! (Kidding, this is a work in
 progress)

 #. **Create a ``pw_system_target`` in your GN build.**
    This is what will control the configuration of your target from a build
    system level. This includes which compiler will be used, what architecture
    flags will be used, which backends will be used, and more. A large quantity
    of configuration will be pre-set to work with pw_system after you select the
    CPU and scheduler your target will use, but your target will likely need to
    set a few other things to get to a fully working state.
 #. **Write target-specific initialization.**
    Most embedded devices require a linker script, manual initialization of
    memory, and some clock initialization. pw_system leaves this to users to
    implement as the exact initialization sequence can be very project-specific.
    All that's required is that after early memory initialization and clock
    configuration is complete, your target initialization should call
    ``pw::system::Init()`` and then start the RTOS scheduler (e.g.
    ``vTaskStartScheduler()``).
 #. **Implement ``pw::system::UserAppInit()`` in your application.**
    This is where most of your project's application-specific logic goes. This
    could be starting threads, registering RPC services, turning on Bluetooth,
    or more. In ``UserAppInit()``, the RTOS will be running so you're free to use
    OS primitives and use features that rely on threading (e.g. RPC, logging).

 Pigweed's ``stm32f429i_disc1_stm32cube`` target demonstrates what's required by
 the first two steps. The third step is where you get to decide how to turn your
 new platform into a project that does something cool! It might be as simple as
 a blinking LED, or something more complex like a Bluetooth device that brews you
 a cup of coffee whenever ``pw watch`` kicks off a new build.

 .. note::
   Because of the nature of the hard-coded conditions in ``pw_system_target``,
   you may find that some options are missing for various RTOSes and
   architectures. The design of the GN integration is still a work-in-progress
   to improve the scalability of this, but in the meantime the Pigweed team
   welcomes contributions to expand the breadth of RTOSes and architectures
   supported as ``pw_system_target``\s.

 GN Target Toolchain Template
 ============================
 This module includes a target toolchain template called ``pw_system_target``
 that reduces the amount of work required to declare a target toolchain with
 pre-selected backends for pw_log, pw_assert, pw_malloc, pw_thread, and more.
 The configurability and extensibility of this template is relatively limited,
 as this template serves as a "one-size-fits-all" starting point rather than
 being foundational infrastructure.

 .. code-block::

   # Declare a toolchain with suggested, compiler, compiler flags, and default
   # backends.
   pw_system_target("stm32f429i_disc1_stm32cube_size_optimized") {
     # These options drive the logic for automatic configuration by this
     # template.
     cpu = PW_SYSTEM_CPU.CORTEX_M4F
     scheduler = PW_SYSTEM_SCHEDULER.FREERTOS

     # Optionally, override pw_system's defaults to build with clang.
     system_toolchain = pw_toolchain_arm_clang

     # The pre_init source set provides things like the interrupt vector table,
     # pre-main init, and provision of FreeRTOS hooks.
     link_deps = [ "$dir_pigweed/targets/stm32f429i_disc1_stm32cube:pre_init" ]

     # These are hardware-specific options that set up this particular board.
     # These are declared in ``declare_args()`` blocks throughout Pigweed. Any
     # build arguments set by the user will be overridden by these settings.
     build_args = {
       pw_third_party_freertos_CONFIG = "$dir_pigweed/targets/stm32f429i_disc1_stm32cube:stm32f4xx_freertos_config"
       pw_third_party_freertos_PORT = "$dir_pw_third_party/freertos:arm_cm4f"
       pw_sys_io_BACKEND = dir_pw_sys_io_stm32cube
       dir_pw_third_party_stm32cube = dir_pw_third_party_stm32cube_f4
       pw_third_party_stm32cube_PRODUCT = "STM32F429xx"
       pw_third_party_stm32cube_CONFIG =
           "//targets/stm32f429i_disc1_stm32cube:stm32f4xx_hal_config"
       pw_third_party_stm32cube_CORE_INIT = ""
       pw_boot_cortex_m_LINK_CONFIG_DEFINES = [
         "PW_BOOT_FLASH_BEGIN=0x08000200",
         "PW_BOOT_FLASH_SIZE=2048K",
         "PW_BOOT_HEAP_SIZE=7K",
         "PW_BOOT_MIN_STACK_SIZE=1K",
         "PW_BOOT_RAM_BEGIN=0x20000000",
         "PW_BOOT_RAM_SIZE=192K",
         "PW_BOOT_VECTOR_TABLE_BEGIN=0x08000000",
         "PW_BOOT_VECTOR_TABLE_SIZE=512",
       ]
     }
   }

   # Example for the Emcraft SmartFusion2 system-on-module
   pw_system_target("emcraft_sf2_som_size_optimized") {
     cpu = PW_SYSTEM_CPU.CORTEX_M3
     scheduler = PW_SYSTEM_SCHEDULER.FREERTOS

     link_deps = [ "$dir_pigweed/targets/emcraft_sf2_som:pre_init" ]
     build_args = {
       pw_log_BACKEND = dir_pw_log_basic #dir_pw_log_tokenized
       pw_tokenizer_GLOBAL_HANDLER_WITH_PAYLOAD_BACKEND = "//pw_system:log"
       pw_third_party_freertos_CONFIG = "$dir_pigweed/targets/emcraft_sf2_som:sf2_freertos_config"
       pw_third_party_freertos_PORT = "$dir_pw_third_party/freertos:arm_cm3"
       pw_sys_io_BACKEND = dir_pw_sys_io_emcraft_sf2
       dir_pw_third_party_smartfusion_mss = dir_pw_third_party_smartfusion_mss_exported
       pw_third_party_stm32cube_CONFIG =
           "//targets/emcraft_sf2_som:sf2_mss_hal_config"
       pw_third_party_stm32cube_CORE_INIT = ""
       pw_boot_cortex_m_LINK_CONFIG_DEFINES = [
         "PW_BOOT_FLASH_BEGIN=0x00000200",
         "PW_BOOT_FLASH_SIZE=200K",

         # TODO(b/235348465): Currently "pw_tokenizer/detokenize_test" requires at
         # least 6K bytes in heap when using pw_malloc_freelist. The heap size
         # required for tests should be investigated.
         "PW_BOOT_HEAP_SIZE=7K",
         "PW_BOOT_MIN_STACK_SIZE=1K",
         "PW_BOOT_RAM_BEGIN=0x20000000",
         "PW_BOOT_RAM_SIZE=64K",
         "PW_BOOT_VECTOR_TABLE_BEGIN=0x00000000",
         "PW_BOOT_VECTOR_TABLE_SIZE=512",
       ]
     }
   }


 Metrics
 =======
 The log backend is tracking metrics to illustrate how to use pw_metric and
 retrieve them using `Device.get_and_log_metrics()`.
	.. _module-pw_system:

	=========
	pw_system
	=========
	.. warning::
	This module is an early work-in-progress towards an opinionated framework for
	new projects built on Pigweed. It is under active development, so stay tuned!

	pw_system is quite different from typical Pigweed modules. Rather than providing
	a single slice of vertical functionality, pw_system pulls together many modules
	across Pigweed to construct a working system with RPC, Logging, an OS
	Abstraction layer, and more. pw_system exists to greatly simplify the process
	of starting a new project using Pigweed by drastically reducing the required
	configuration space required to go from first signs of on-device life to a more
	sophisticated production-ready system.

	Trying out pw_system
	====================
	If you'd like to give pw_system a spin and have a STM32F429I Discovery board,
	refer to the board's
	:ref:`target documentation<target-stm32f429i-disc1-stm32cube>` for instructions
	on how to build the demo and try things out

	If you don't have a discovery board, there's a simulated device variation that
	you can run on your local machine with no additional hardware. Check out the
	steps for trying this out :ref:`here<target-host-device-simulator>`.

	Target Bringup
	==============
	Bringing up a new device is as easy as 1-2-3! (Kidding, this is a work in
	progress)

	#. Create a ``pw_system_target`` in your GN build.
	This is what will control the configuration of your target from a build
	system level. This includes which compiler will be used, what architecture
	flags will be used, which backends will be used, and more. A large quantity
	of configuration will be pre-set to work with pw_system after you select the
	CPU and scheduler your target will use, but your target will likely need to
	set a few other things to get to a fully working state.
	#. Write target-specific initialization.
	Most embedded devices require a linker script, manual initialization of
	memory, and some clock initialization. pw_system leaves this to users to
	implement as the exact initialization sequence can be very project-specific.
	All that's required is that after early memory initialization and clock
	configuration is complete, your target initialization should call
	``pw::system::Init()`` and then start the RTOS scheduler (e.g.
	``vTaskStartScheduler()``).
	#. Implement ``pw::system::UserAppInit()`` in your application.
	This is where most of your project's application-specific logic goes. This
	could be starting threads, registering RPC services, turning on Bluetooth,
	or more. In ``UserAppInit()``, the RTOS will be running so you're free to use
	OS primitives and use features that rely on threading (e.g. RPC, logging).

	Pigweed's ``stm32f429i_disc1_stm32cube`` target demonstrates what's required by
	the first two steps. The third step is where you get to decide how to turn your
	new platform into a project that does something cool! It might be as simple as
	a blinking LED, or something more complex like a Bluetooth device that brews you
	a cup of coffee whenever ``pw watch`` kicks off a new build.

	.. note::
	Because of the nature of the hard-coded conditions in ``pw_system_target``,
	you may find that some options are missing for various RTOSes and
	architectures. The design of the GN integration is still a work-in-progress
	to improve the scalability of this, but in the meantime the Pigweed team
	welcomes contributions to expand the breadth of RTOSes and architectures
	supported as ``pw_system_target``\s.

	GN Target Toolchain Template
	============================
	This module includes a target toolchain template called ``pw_system_target``
	that reduces the amount of work required to declare a target toolchain with
	pre-selected backends for pw_log, pw_assert, pw_malloc, pw_thread, and more.
	The configurability and extensibility of this template is relatively limited,
	as this template serves as a "one-size-fits-all" starting point rather than
	being foundational infrastructure.

	.. code-block::

	# Declare a toolchain with suggested, compiler, compiler flags, and default
	# backends.
	pw_system_target("stm32f429i_disc1_stm32cube_size_optimized") {
	# These options drive the logic for automatic configuration by this
	# template.
	cpu = PW_SYSTEM_CPU.CORTEX_M4F
	scheduler = PW_SYSTEM_SCHEDULER.FREERTOS

	# Optionally, override pw_system's defaults to build with clang.
	system_toolchain = pw_toolchain_arm_clang

	# The pre_init source set provides things like the interrupt vector table,
	# pre-main init, and provision of FreeRTOS hooks.
	link_deps = [ "$dir_pigweed/targets/stm32f429i_disc1_stm32cube:pre_init" ]

	# These are hardware-specific options that set up this particular board.
	# These are declared in ``declare_args()`` blocks throughout Pigweed. Any
	# build arguments set by the user will be overridden by these settings.
	build_args = {
	pw_third_party_freertos_CONFIG = "$dir_pigweed/targets/stm32f429i_disc1_stm32cube:stm32f4xx_freertos_config"
	pw_third_party_freertos_PORT = "$dir_pw_third_party/freertos:arm_cm4f"
	pw_sys_io_BACKEND = dir_pw_sys_io_stm32cube
	dir_pw_third_party_stm32cube = dir_pw_third_party_stm32cube_f4
	pw_third_party_stm32cube_PRODUCT = "STM32F429xx"
	pw_third_party_stm32cube_CONFIG =
	"//targets/stm32f429i_disc1_stm32cube:stm32f4xx_hal_config"
	pw_third_party_stm32cube_CORE_INIT = ""
	pw_boot_cortex_m_LINK_CONFIG_DEFINES = [
	"PW_BOOT_FLASH_BEGIN=0x08000200",
	"PW_BOOT_FLASH_SIZE=2048K",
	"PW_BOOT_HEAP_SIZE=7K",
	"PW_BOOT_MIN_STACK_SIZE=1K",
	"PW_BOOT_RAM_BEGIN=0x20000000",
	"PW_BOOT_RAM_SIZE=192K",
	"PW_BOOT_VECTOR_TABLE_BEGIN=0x08000000",
	"PW_BOOT_VECTOR_TABLE_SIZE=512",
	]
	}
	}

	# Example for the Emcraft SmartFusion2 system-on-module
	pw_system_target("emcraft_sf2_som_size_optimized") {
	cpu = PW_SYSTEM_CPU.CORTEX_M3
	scheduler = PW_SYSTEM_SCHEDULER.FREERTOS

	link_deps = [ "$dir_pigweed/targets/emcraft_sf2_som:pre_init" ]
	build_args = {
	pw_log_BACKEND = dir_pw_log_basic #dir_pw_log_tokenized
	pw_tokenizer_GLOBAL_HANDLER_WITH_PAYLOAD_BACKEND = "//pw_system:log"
	pw_third_party_freertos_CONFIG = "$dir_pigweed/targets/emcraft_sf2_som:sf2_freertos_config"
	pw_third_party_freertos_PORT = "$dir_pw_third_party/freertos:arm_cm3"
	pw_sys_io_BACKEND = dir_pw_sys_io_emcraft_sf2
	dir_pw_third_party_smartfusion_mss = dir_pw_third_party_smartfusion_mss_exported
	pw_third_party_stm32cube_CONFIG =
	"//targets/emcraft_sf2_som:sf2_mss_hal_config"
	pw_third_party_stm32cube_CORE_INIT = ""
	pw_boot_cortex_m_LINK_CONFIG_DEFINES = [
	"PW_BOOT_FLASH_BEGIN=0x00000200",
	"PW_BOOT_FLASH_SIZE=200K",

	# TODO(b/235348465): Currently "pw_tokenizer/detokenize_test" requires at
	# least 6K bytes in heap when using pw_malloc_freelist. The heap size
	# required for tests should be investigated.
	"PW_BOOT_HEAP_SIZE=7K",
	"PW_BOOT_MIN_STACK_SIZE=1K",
	"PW_BOOT_RAM_BEGIN=0x20000000",
	"PW_BOOT_RAM_SIZE=64K",
	"PW_BOOT_VECTOR_TABLE_BEGIN=0x00000000",
	"PW_BOOT_VECTOR_TABLE_SIZE=512",
	]
	}
	}


	Metrics
	=======
	The log backend is tracking metrics to illustrate how to use pw_metric and
	retrieve them using `Device.get_and_log_metrics()`.