Difference between revisions of "How to start the coprocessor from the bootloader"

[checked revision] [quality revision]
m
m (merge from TW review on wiki 2.0)
 

1 Introduction[edit]

The coprocessor firmware can be loaded and started by:

This article explains how this the coprocessor firmware is loaded by U-Boot and started before the Linux kernel.

2 Location of the coprocessor firmware[edit]

Note: the default name for this firmware used in this WIKI is rproc-m4-fw.elf

U-Boot searches and loads the needed required binaries in the first bootable partition (generic DISTRO configuration) which is bootfs in the OpenSTLinux distribution (see STM32MP15_Flash_mapping). So , so the coprocessor firmware must be installed in that bootfs partition. The simplest way to do this, it consists in copying the firmware from the rootfs partition to the bootfs partition as follows:

 mount /dev/mmcblk0p4 /boot
 cp rproc-m4-fw.elf /boot/
 sync

As an alternate alternative method, you can also use the Eclipse IDE, or transfer the firmware over the serial console or over the network.

Note: The default name of the firmware used in this WIKI is rproc-m4-fw.elf.

3 Starting the coprocessor firmware[edit]

U-Boot can boot the coprocessor before the kernel (coprocessor early boot) with remoteproc uclass . Several methods are possible:

  1. Manual start by using rproc commands
  2. Automatic start, at each boot by using
Info white.png Information
In the following examples it is assumed that the firmware declares a resource table. If your firmware does not declare such a resource table, you do not need to call the load_rsc rproc command.

3.1 Manual start[edit]

You can load and start the coprocessor firmware by using the rproc command in the U-Boot console (to access to the U-boot console: , press any key during the U-Boot execution).

 
 rproc
 rproc - Control operation of remote processors in an SoC
 
 Usage:
 rproc  [init|list|load|start|stop|reset|is_running|ping]
 		 Where:
 		[addr] is a memory address
 		<id> is a numerical identifier for the remote processor
 		     provided by 'list' command.
 		Note: Remote processors must be initalized prior to usage
 		Note: Services aredepend dependent on the driver capability
 		      'list' command shows the capability of each device
 
 	Subcommands:
 	init   - EnumerateEnumerates and initalizeinitializes the remote processors
 	list   - listlists available remote processors
 	load <id> [addr] [size]- LoadLoads the remote processor with
 			  image stored at address [addr] in memory
 	load_rsc <id> [addr] [size]- LoadLoads resource table from remote
 			  processor provided image at address [addr]
 	start <id>	- StartStarts the remote processor(must be loaded)
 	stop <id>	- StopStops the remote processor
 	reset <id>	- ResetResets the remote processor
 	is_running <id> - Reports if the remote processor is running
 	ping <id>	- PingPings the remote processor for communication

In this example, the firmware is loaded from SDCARD in an SD card into RAM (at ${kernel_addr_r}), and then started launched.

 ext4load mmc 0:4 ${kernel_addr_r} rproc-m4-fw.elf -> SDCARDSD card is mmc 0, bootfs is ext4 partition number 4)
 rproc init                                        -> initializes all coprocessors
 rproc load 0 ${kernel_addr_r} ${filesize}         -> loads firmware for coprocessor 0 (code part found in .elf)
 rproc load_rsc 0 ${kernel_addr_r} ${filesize}     -> loads resource table for coprocessor 0 (found in .elf)
 rproc start 0                                     -> starts coprocessor 0

You can then resume the normal boot process:

 run bootcmd

3.2 Automatic start[edit]

3.2.1 Start from the bootcmd[edit]

You can update the bootcmd which is exectued automatically: modify CONFIG_EXTRA_ENV_SETTINGS in include/configs/stm32mp1.h and then recompile U-Boot.

Example : For example, to boot a firmware on the SDCARDfrom an SD card, proceed as follows:

#define CONFIG_EXTRA_ENV_SETTINGS \
	"stdin=serial\0" \
	"stdout=serial\0" \
	"stderr=serial\0" \
	...
	BOOTENV \
	"m4fw_name=rproc-m4-fw.elf\0" \
        "m4fw_addr=${kernel_addr_r}\0" \
	"boot_m4fw=rproc init; rproc load 0 ${m4fw_addr} ${filesize}; rproc load_rsc 0 ${m4fw_addr} ${filesize}; rproc start 0\0" \
        "boot_m4_mmc0=if ext4load mmc 0:4 ${m4fw_addr} ${m4fw_name} ; then run boot_m4fw; fi;\0"
        "bootcmd=run boot_m4_mmc0; run bootcmd_mmc0\0"

NBNote: It is recommended to check STM32MP15_U-Boot for compilation.

3.2.2 Start from a generic DISTRO boot script[edit]

Without U-boot recompilation, you can also use a DISTRO boot script boot.scr.uimg to automatically load and run the firmware.

For example, use the following script for to boot from mmc 0, boot.scr.cmd:

 env set m4fw_name "rproc-m4-fw.elf"
 env set m4fw_addr ${kernel_addr_r}
 
 #load M4 firmware
 if ext4load mmc 0:4 ${m4fw_addr} ${m4fw_name}
 then
   rproc init
   rproc load 0 ${m4fw_addr} ${filesize}
   rproc load_rsc 0 ${m4fw_addr} ${filesize}
   rproc start 0
 fi
 
 #load kernel and device tree
 ext4load mmc 0:4 ${kernel_addr_r} uImage
 ext4load mmc 0:4 ${fdt_addr_r}  ${board_name}.dtb
 
 # start kernel 
 env set bootargs root=/dev/mmcblk0p6 rootwait rw console=ttySTM0,115200
 bootm ${kernel_addr_r} - ${fdt_addr_r}

Then generate the associated image using mkimage U-Boot tool:

 mkimage -T script -C none -A arm -d boot.scr.cmd boot.scr.uimg

FinallyLastly, install boot.scr.uimg in the bootfs partition (following the same procedure used for coprocessor firmware)

 sudo cp boot.scr.uimg /media/$USER/bootfs
 sync
Warning white.png Warning
The U-Boot script 'boot.scr.uimg' U-Boot script is executed only if 'extlinux/extlinux.conf' is not found (scan_dev_for_scripts is called after scan_dev_for_extlinux)
You should remove pre-existing file in bootfs partition:
 sudo rm -r /media/$USER/bootfs/extlinux
 sync

3.2.3 Start from the FIT image[edit]

The coprocessor firmware can also be also included in the new U-Boot image format = , Flattened uImage Tree (FIT) and then this firmware will be loaded automatically when . This firmware is then automatically loaded when it is detected by U-Boot.

Info white.png Information
Please note that the upstreaming of this example is in progress, some only a part of the files are only present in the U-boot sources provided by STMicroelectronics

See Refer to chapter 'Coprocessor firmware' in board/st/stm32mp1/README : it contains an example of '.its' file

is provided < U

, <U-Boot directory>/board/st/stm32mp1/fit_copro_kernel_dtb.its

you

, and shows how to generate the FIT with U-Boot mkimage tool:

 mkimage -f fit_copro_kernel_dtb.its fit_copro_kernel_dtb.itb

You can load the generated FIT withusing:

To go deeper, read:

4 Synchronize Synchronizing the remote firmware with Linux[edit]

The Linux remoteproc framework STM32MPU Embedded Software distribution provides the ability to detect and manage a firmware loaded by U-Boot thanks to the remoteproc Linux framework.
The developer should must pay attention to how he implements the Arm Cortex-M4 firmware if the RPMsg is used for communication to communicate with the Linux. In this case a synchronization is needed. the cortexrequired. The Arm Cortex-M4 have core has to wait that the until Linux is ready to communicate by updating the booted to start RPMsg communications. When Linux is ready, the Linux kernel automatically updates the vdev status in in the resource table) , and sends a signal to the Arm Cortex-M4 core using the IPCC peripheral.
Two methods can be implemented to wait for the synchronization:

  • Blocking method: The the firmware is blocked on MX_OPENAMP_Init call (by the rproc_virtio_wait_remote_ready function) until the Linux kernel is ready to communicate (update of the vdev status in the resource table).
  • Non-blocking method: The Linux Kernel generates an interruption on when it is ready to communicate, the Linux kernel generates an interrupt towards the Arm Cortex-M4 core using the IPCC peripheral when it is ready to communicate. This interrupt can be used by the Arm Cortex-M4 firmware to initialize the OpenAMP middleware and start the RPMsg protocol.


== Introduction ==
The [[Coprocessor_management_overview|coprocessor]] firmware can be loaded and started by:
* :
* either by the second stage boot loader = bootloader, U-Boot (see [[Boot_chains_overview]] for details) * or
* by the Linux<sup>&reg;</sup> kernel (see [[Linux_remoteproc_framework_overview]] for details)

This article explains how thisthe coprocessor firmware is loaded by [[U-Boot_overview|U-Boot]] and started before the Linux kernel.
{{ReviewsComments|ECO: nowhere the Vitrual UART behavior is decribed when Fw is launched from Uboot.  The FW is blocked in OpenAMP_Init function through rproc_virtio_wait_remote_ready(vdev) until the kernel start the TTY}}== Location of the coprocessor firmware ==''Note: the default name for this firmware used in this WIKI is '''rproc-m4-fw.elf'''''

U-Boot searches and loads the neededrequired binaries in the first bootable partition ([[U-Boot_overview#Generic_Distro_configuration|generic DISTRO configuration]]) which is '''bootfs''' in the  OpenSTLinux distribution (see [[STM32MP15_Flash_mapping]]).

So , so the coprocessor firmware must be installed in that bootfs partition. The simplest way to do this,it consists in copying the firmware from the rootfs partition to the bootfs partition as follows:
 {{Board$}} mount /dev/mmcblk0p4 /boot
 {{Board$}} cp rproc-m4-fw.elf /boot/
 {{Board$}} sync

As an alternatealternative method, you can also use the Eclipse IDE, or transfer the firmware [[How to transfer a file over serial console|over the serial console]] or [[How to transfer a file over network|over the network]].
''Note: The default name of the firmware used in this WIKI is '''rproc-m4-fw.elf'''''.
== Starting the coprocessor firmware ==

U-Boot can boot the coprocessor before the kernel (coprocessor early boot) with remoteproc {{CodeSource|U-Boot|doc/driver-model/README.txt|uclass}}. Several methods are possible:

# [[#Manual start|Manual start]] by using rproc commands
# [[#Automatic start|Automatic start]], at each boot by using 
#* [[#Start from the bootcmd|the bootcmd]] (needing U-Boot recompilation)
#* [[#Start from a generic DISTRO boot script|a generic DISTRO boot script]]
#* [[#Start from the FIT image|the FIT image]]

{{Info| In the following examples it is assumed that the firmware declares a resource table. If your firmware does not declare such a resource table, you do not need to call the '''load_rsc''' rproc command. }} 

=== Manual start ===
You can load and start the coprocessor firmware by using the '''rproc''' command in the [[U-Boot_overview#U-Boot_command_line_interface_(CLI)|U-Boot console]] (to access to the U-boot console:, press any key during the U-Boot execution).

  {{Board$}} rproc
  rproc - Control operation of remote processors in an SoC

  Usage:
  rproc  [init|list|load|start|stop|reset|is_running|ping]
  		 Where:
  		[addr] is a memory address<id> is a numerical identifier for the remote processor
  		     provided by 'list' command.
  		Note: Remote processors must be initalized prior to usage
  		Note: Services are dependent depend on the driver capability
  		      'list' command shows the capability of each device

  	Subcommands:
  	init   - EnumerateEnumerates and initalizeinitializes the remote processors
  	list   - listlists available remote processors
  	load <id> [addr] [size]- LoadLoads the remote processor with
  			  image stored at address [addr] in memory
  	load_rsc <id> [addr] [size]- LoadLoads resource table from remote
  			  processor provided image at address [addr]
  	start <id>	- StartStarts the remote processor(must be loaded)
  	stop <id>	- StopStops the remote processor
  	reset <id>	- ResetResets the remote processor
  	is_running <id> - Reports if the remote processor is running
  	ping <id>	- PingPings the remote processor for communication

In this example, the firmware is loaded from SDCARD in an SD card into RAM (at ${kernel_addr_r}), and then startedlaunched.


 {{Board$}} ext4load mmc 0:4 ${kernel_addr_r} rproc-m4-fw.elf {{Highlight|-> SDCARD SD card is mmc 0, bootfs is ext4 partition number 4)}}
 {{Board$}} rproc init                                        {{Highlight|-> initializes all coprocessors}}
 {{Board$}} rproc load 0 ${kernel_addr_r} ${filesize}         {{Highlight|-> loads firmware for coprocessor 0 (code part found in .elf)}}
 {{Board$}} rproc load_rsc 0 ${kernel_addr_r} ${filesize}     {{Highlight|-> loads resource table for coprocessor 0 (found in .elf)}}
 {{Board$}} rproc start 0                                     {{Highlight|-> starts coprocessor 0}}

You can then resume the normal boot process:
 {{Board$}} run bootcmd

=== Automatic start ===
==== Start from the bootcmd ====
You can update the [[U-Boot_overview#bootcmd|bootcmd]] which is exectued automatically: modify '''CONFIG_EXTRA_ENV_SETTINGS''' in {{CodeSource | U-Boot | include/configs/stm32mp1.h}} and then [[U-Boot_overview#U-Boot_build|recompile U-Boot]].
Example : For example, to boot a firmware on the SDCARDfrom an SD card, proceed as follows:<pre>

#define CONFIG_EXTRA_ENV_SETTINGS \
	"stdin=serial\0" \
	"stdout=serial\0" \
	"stderr=serial\0" \
	...
	BOOTENV \
	"m4fw_name=rproc-m4-fw.elf\0" \
        "m4fw_addr=${kernel_addr_r}\0" \
	"boot_m4fw=rproc init; rproc load 0 ${m4fw_addr} ${filesize}; rproc load_rsc 0 ${m4fw_addr} ${filesize}; rproc start 0\0" \
        "boot_m4_mmc0=if ext4load mmc 0:4 ${m4fw_addr} ${m4fw_name} ; then run boot_m4fw; fi;\0"
        "bootcmd=run boot_m4_mmc0; run bootcmd_mmc0\0"</pre>

NB: Note: It is recommended to check [[STM32MP15_U-Boot]] for compilation.{{ReviewsComments|--ECO 1/4/2020 What happen with Virtual UART when FW is loaded by Uboot ?
The FW is blocked in  MX_OPENAMP_Init until the kernel start
(rproc_virtio_wait_remote_ready() at remoteproc_virtio.c:326)

}}
==== Start from a generic DISTRO boot script ====

Without U-boot recompilation, you can also use a DISTRO boot script '''boot.scr.uimg''' to automatically load and run the firmware.

For example, use the following script forto boot from mmc 0, '''boot.scr.cmd''':

  env set m4fw_name "rproc-m4-fw.elf"
  env set m4fw_addr ${kernel_addr_r}

  #load M4 firmware
  if ext4load mmc 0:4 ${m4fw_addr} ${m4fw_name}
  then
    rproc init
    rproc load 0 ${m4fw_addr} ${filesize}
    rproc load_rsc 0 ${m4fw_addr} ${filesize}
    rproc start 0
  fi

  #load kernel and device tree
  ext4load mmc 0:4 ${kernel_addr_r} uImage
  ext4load mmc 0:4 ${fdt_addr_r}  ${board_name}.dtb

  # start kernel 
  env set bootargs root=/dev/mmcblk0p6 rootwait rw console=ttySTM0,115200
  bootm ${kernel_addr_r} - ${fdt_addr_r}

Then generate the associated image using mkimage U-Boot tool:

 {{PC$}} mkimage -T script -C none -A arm -d boot.scr.cmd boot.scr.uimg
FinallyLastly, install '''boot.scr.uimg''' in the bootfs partition (following the same procedure used for [[#Location of the coprocessor firmware|coprocessor firmware]])
 {{PC$}} sudo cp boot.scr.uimg /media/$USER/bootfs
 {{PC$}} sync

{{Warning|The U-Boot script 'boot.scr.uimg' U-Boot script is executed only if 'extlinux/extlinux.conf' is not found (scan_dev_for_scripts is called after scan_dev_for_extlinux)<br>You should remove pre-existing file in bootfs partition:}} 
 {{PC$}} sudo rm -r /media/$USER/bootfs/extlinux
 {{PC$}} sync

==== Start from the FIT image ====

The coprocessor firmware can also be also included in the new U-Boot image format = , {{CodeSource | U-Boot | doc/uImage.FIT/ |Flattened uImage Tree (FIT)}} and then this firmware will be loaded automatically when . This firmware is then automatically loaded when it is detected by U-Boot.

{{Info|Please note that the upstreaming of this example is in progress, some files are only present in only a part of the files are present in the U-boot sources provided by STMicroelectronics}}
See Refer to chapter 'Coprocessor firmware' in {{CodeSource | U-Boot | board/st/stm32mp1/README}}: * it contains an example of '.its' file is provided < U-Boot directory>, <U-Boot directory>/board/st/stm32mp1/fit_copro_kernel_dtb.its

* you , and shows how to generate the FIT with U-Boot mkimage tool:
 {{PC$}} mkimage -f fit_copro_kernel_dtb.its fit_copro_kernel_dtb.itb

You can load the generated FIT withusing:
* 'bootm' command (see {{ CodeSource | U-Boot | doc/uImage.FIT/command_syntax_extensions.txt}})
* extlinux.conf in bootfs in extlinux directory to automatically load the FIT by [[U-Boot_overview#Generic_Distro_configuration|generic DISTRO]],<br/>for example: < U-Boot directory>/board/st/stm32mp1/extlinux.conf

To go deeper, read:
* {{ CodeSource | U-Boot | doc/README.pxe }}
* {{ CodeSource | U-Boot | doc/uImage.FIT/howto.txt }}
* support of firmware in FIT is done in board_stm32copro_image_process() function in {{CodeSource | U-Boot | board/st/stm32mp1/stm32mp1.c}} associated to image type IH_TYPE_STM32COPRO.

== SynchronizeSynchronizing the remote firmware with Linux ==
The Linux [[Linux_remoteproc_framework_overview#Remote_processor_.27early.27_boot | remoteproc framework[[STM32MPU Embedded Software distribution]] provides the ability to detect and manage a firmware loaded by U-Boot.<BR>

The developer should thanks to the [[Linux_remoteproc_framework_overview#Remote_processor_.27early.27_boot | remoteproc]] Linux framework.<BR>

The developer must pay attention to how he implements the Arm Cortex-M4 firmware if the RPMsg is used for communicationto communicate with the Linux. In this case a synchronization is needed. the cortex-M4 have to wait that the Linux is ready to communicate by updating the vdev  status in in required. The Arm Cortex-M4 core has to wait until Linux is booted to start RPMsg communications. When Linux is ready, the Linux kernel automatically updates the vdev status in the  [[Coprocessor_resource_table | resource table]]) , and sends a signal to the Arm Cortex-M4 core using the [[IPCC_internal_peripheral | IPCC peripheral]].<BR>

Two methods can be implemented * '''Blocking method''': Theto wait for the synchronization:
* '''Blocking method''': the firmware is blocked on MX_OPENAMP_Init  call (by the rproc_virtio_wait_remote_ready function) until the Linux kernel is ready to communicate (update of the vdev status in the resource table).
* '''Non-blocking method''': The Linux Kernel generates an interruption on Cortex-M4 when it is ready to communicate, the Linux kernel generates an interrupt towards the Arm Cortex-M4 core using the [[IPCC_internal_peripheral | IPCC peripheral]] when it is ready to communicate. This interrupt can be used by the Arm Cortex-M4 firmware to initialize the OpenAMP middleware and start the RPMsg protocol.
<noinclude>

[[Category:How to run use cases]]
[[Category:Coprocessor management STM32Cube]]
[[Category:U-Boot]]
{{PublicationRequestId | 10438 | 2019-01-23 | AlainF}}</noinclude>
Line 1: Line 1:
 
== Introduction ==
 
== Introduction ==
The [[Coprocessor_management_overview|coprocessor]] firmware can be loaded and started by:
+
The [[Coprocessor_management_overview|coprocessor]] firmware can be loaded and started:
* the second stage boot loader = U-Boot (see [[Boot_chains_overview]] for details)
+
* either by the second stage bootloader, U-Boot (see [[Boot_chains_overview]] for details) or
* the Linux<sup>&reg;</sup> kernel (see [[Linux_remoteproc_framework_overview]] for details)
+
* by the Linux<sup>&reg;</sup> kernel (see [[Linux_remoteproc_framework_overview]] for details)
  +
 
  +
This article explains how the coprocessor firmware is loaded by [[U-Boot_overview|U-Boot]] and started before the Linux kernel.
   
This article explains how this coprocessor firmware is loaded by [[U-Boot_overview|U-Boot]] and started before the Linux kernel.
 
{{ReviewsComments|ECO: nowhere the Vitrual UART behavior is decribed when Fw is launched from Uboot.  The FW is blocked in OpenAMP_Init function through rproc_virtio_wait_remote_ready(vdev) until the kernel start the TTY}}
 
 
== Location of the coprocessor firmware ==
 
== Location of the coprocessor firmware ==
''Note: the default name for this firmware used in this WIKI is '''rproc-m4-fw.elf'''''
 
   
U-Boot searches and loads the needed binaries in the first bootable partition ([[U-Boot_overview#Generic_Distro_configuration|generic DISTRO configuration]]) which is '''bootfs''' in the  OpenSTLinux distribution (see [[STM32MP15_Flash_mapping]]).
+
U-Boot searches and loads the required binaries in the first bootable partition ([[U-Boot_overview#Generic_Distro_configuration|generic DISTRO configuration]]) which is '''bootfs''' in the  OpenSTLinux distribution (see [[STM32MP15_Flash_mapping]]), so the coprocessor firmware must be installed in that bootfs partition. The simplest way to do it consists in copying the firmware from the rootfs partition to the bootfs partition as follows:
 
 
So the coprocessor firmware must be installed in that bootfs partition. The simplest way to do this, consists in copying the firmware from the rootfs partition to the bootfs partition as follows:
 
 
  {{Board$}} mount /dev/mmcblk0p4 /boot
 
  {{Board$}} mount /dev/mmcblk0p4 /boot
 
  {{Board$}} cp rproc-m4-fw.elf /boot/
 
  {{Board$}} cp rproc-m4-fw.elf /boot/
 
  {{Board$}} sync
 
  {{Board$}} sync
   
As an alternate method, you can also use the Eclipse IDE, or transfer the firmware [[How to transfer a file over serial console|over the serial console]] or [[How to transfer a file over network|over the network]].
+
As an alternative method, you can use the Eclipse IDE, or transfer the firmware [[How to transfer a file over serial console|over the serial console]] or [[How to transfer a file over network|over the network]].
  +
 
  +
''Note: The default name of the firmware used in this WIKI is '''rproc-m4-fw.elf'''''.
   
 
== Starting the coprocessor firmware ==
 
== Starting the coprocessor firmware ==
   
U-Boot can boot the coprocessor before the kernel (coprocessor early boot) with remoteproc {{CodeSource|U-Boot|doc/driver-model/README.txt|uclass}}:
+
U-Boot can boot the coprocessor before the kernel (coprocessor early boot) with remoteproc {{CodeSource|U-Boot|doc/driver-model/README.txt|uclass}}. Several methods are possible:
   
 
# [[#Manual start|Manual start]] by using rproc commands
 
# [[#Manual start|Manual start]] by using rproc commands
Line 31: Line 30:
   
 
=== Manual start ===
 
=== Manual start ===
You can load and start the coprocessor firmware by using the '''rproc''' command in the [[U-Boot_overview#U-Boot_command_line_interface_(CLI)|U-Boot console]] (to access to the U-boot console: press any key during the U-Boot execution).
+
You can load and start the coprocessor firmware by using the '''rproc''' command in the [[U-Boot_overview#U-Boot_command_line_interface_(CLI)|U-Boot console]] (to access to the U-boot console, press any key during the U-Boot execution).
   
 
   {{Board$}} rproc
 
   {{Board$}} rproc
Line 43: Line 42:
 
       provided by 'list' command.
 
       provided by 'list' command.
 
   Note: Remote processors must be initalized prior to usage
 
   Note: Remote processors must be initalized prior to usage
   Note: Services are dependent on the driver capability
+
   Note: Services depend on the driver capability
 
         'list' command shows the capability of each device
 
         'list' command shows the capability of each device
 
    
 
    
 
   Subcommands:
 
   Subcommands:
   init  - Enumerate and initalize the remote processors
+
   init  - Enumerates and initializes the remote processors
   list  - list available remote processors
+
   list  - lists available remote processors
   load <id> [addr] [size]- Load the remote processor with
+
   load <id> [addr] [size]- Loads the remote processor with
 
     image stored at address [addr] in memory
 
     image stored at address [addr] in memory
   load_rsc <id> [addr] [size]- Load resource table from remote
+
   load_rsc <id> [addr] [size]- Loads resource table from remote
 
     processor provided image at address [addr]
 
     processor provided image at address [addr]
   start <id> - Start the remote processor(must be loaded)
+
   start <id> - Starts the remote processor(must be loaded)
   stop <id> - Stop the remote processor
+
   stop <id> - Stops the remote processor
   reset <id> - Reset the remote processor
+
   reset <id> - Resets the remote processor
 
   is_running <id> - Reports if the remote processor is running
 
   is_running <id> - Reports if the remote processor is running
   ping <id> - Ping the remote processor for communication
+
   ping <id> - Pings the remote processor for communication
   
In this example, the firmware is loaded from SDCARD in RAM (at ${kernel_addr_r}), and then started
+
In this example, the firmware is loaded from an SD card into RAM (at ${kernel_addr_r}), and then launched.
   
  {{Board$}} ext4load mmc 0:4 ${kernel_addr_r} rproc-m4-fw.elf {{Highlight|-> SDCARD is mmc 0, bootfs is ext4 partition number 4)}}
+
  {{Board$}} ext4load mmc 0:4 ${kernel_addr_r} rproc-m4-fw.elf {{Highlight|-> SD card is mmc 0, bootfs is ext4 partition number 4)}}
 
  {{Board$}} rproc init                                        {{Highlight|-> initializes all coprocessors}}
 
  {{Board$}} rproc init                                        {{Highlight|-> initializes all coprocessors}}
 
  {{Board$}} rproc load 0 ${kernel_addr_r} ${filesize}        {{Highlight|-> loads firmware for coprocessor 0 (code part found in .elf)}}
 
  {{Board$}} rproc load 0 ${kernel_addr_r} ${filesize}        {{Highlight|-> loads firmware for coprocessor 0 (code part found in .elf)}}
Line 74: Line 73:
 
You can update the [[U-Boot_overview#bootcmd|bootcmd]] which is exectued automatically: modify '''CONFIG_EXTRA_ENV_SETTINGS''' in {{CodeSource | U-Boot | include/configs/stm32mp1.h}} and then [[U-Boot_overview#U-Boot_build|recompile U-Boot]].
 
You can update the [[U-Boot_overview#bootcmd|bootcmd]] which is exectued automatically: modify '''CONFIG_EXTRA_ENV_SETTINGS''' in {{CodeSource | U-Boot | include/configs/stm32mp1.h}} and then [[U-Boot_overview#U-Boot_build|recompile U-Boot]].
   
Example : boot a firmware on the SDCARD:
+
For example, to boot a firmware from an SD card, proceed as follows:
 
<pre>
 
<pre>
 
#define CONFIG_EXTRA_ENV_SETTINGS \
 
#define CONFIG_EXTRA_ENV_SETTINGS \
Line 89: Line 88:
 
</pre>
 
</pre>
   
NB: check [[STM32MP15_U-Boot]] for compilation.
+
Note: It is recommended to check [[STM32MP15_U-Boot]] for compilation.
{{ReviewsComments|--ECO 1/4/2020 What happen with Virtual UART when FW is loaded by Uboot ?
 
The FW is blocked in  MX_OPENAMP_Init until the kernel start
 
(rproc_virtio_wait_remote_ready() at remoteproc_virtio.c:326)
 
   
}}
 
 
==== Start from a generic DISTRO boot script ====
 
==== Start from a generic DISTRO boot script ====
   
 
Without U-boot recompilation, you can also use a DISTRO boot script '''boot.scr.uimg''' to automatically load and run the firmware.
 
Without U-boot recompilation, you can also use a DISTRO boot script '''boot.scr.uimg''' to automatically load and run the firmware.
   
For example, use the following script for boot from mmc 0, '''boot.scr.cmd''':
+
For example, use the following script to boot from mmc 0, '''boot.scr.cmd''':
   
 
   env set m4fw_name "rproc-m4-fw.elf"
 
   env set m4fw_name "rproc-m4-fw.elf"
Line 121: Line 116:
 
   bootm ${kernel_addr_r} - ${fdt_addr_r}
 
   bootm ${kernel_addr_r} - ${fdt_addr_r}
   
Then generate associated image using mkimage U-Boot tool:
+
Then generate the associated image using mkimage U-Boot tool:
   
 
  {{PC$}} mkimage -T script -C none -A arm -d boot.scr.cmd boot.scr.uimg
 
  {{PC$}} mkimage -T script -C none -A arm -d boot.scr.cmd boot.scr.uimg
   
Finally, install '''boot.scr.uimg''' in the bootfs partition (following the same procedure used for [[#Location of the coprocessor firmware|coprocessor firmware]])
+
Lastly, install '''boot.scr.uimg''' in the bootfs partition (following the same procedure used for [[#Location of the coprocessor firmware|coprocessor firmware]])
 
  {{PC$}} sudo cp boot.scr.uimg /media/$USER/bootfs
 
  {{PC$}} sudo cp boot.scr.uimg /media/$USER/bootfs
 
  {{PC$}} sync
 
  {{PC$}} sync
   
{{Warning|The U-Boot script 'boot.scr.uimg' is executed only if 'extlinux/extlinux.conf' is not found (scan_dev_for_scripts is called after scan_dev_for_extlinux)<br>You should remove pre-existing file in bootfs partition:}}  
+
{{Warning|The 'boot.scr.uimg' U-Boot script is executed only if 'extlinux/extlinux.conf' is not found (scan_dev_for_scripts is called after scan_dev_for_extlinux)<br>You should remove pre-existing file in bootfs partition:}}  
 
  {{PC$}} sudo rm -r /media/$USER/bootfs/extlinux
 
  {{PC$}} sudo rm -r /media/$USER/bootfs/extlinux
 
  {{PC$}} sync
 
  {{PC$}} sync
Line 135: Line 130:
 
==== Start from the FIT image ====
 
==== Start from the FIT image ====
   
The coprocessor firmware can be also included in the new U-Boot image format = {{CodeSource | U-Boot | doc/uImage.FIT/ |Flattened uImage Tree (FIT)}} and then this firmware will be loaded automatically when detected by U-Boot.
+
The coprocessor firmware can also be included in the new U-Boot image format, {{CodeSource | U-Boot | doc/uImage.FIT/ |Flattened uImage Tree (FIT)}}. This firmware is then automatically loaded when it is detected by U-Boot.
   
{{Info|Please note that the upstreaming of this example is in progress, some files are only present in U-boot sources provided by STMicroelectronics}}
+
{{Info|Please note that the upstreaming of this example is in progress, only a part of the files are present in the U-boot sources provided by STMicroelectronics}}
   
See chapter 'Coprocessor firmware' in {{CodeSource | U-Boot | board/st/stm32mp1/README}}:
+
Refer to chapter 'Coprocessor firmware' in {{CodeSource | U-Boot | board/st/stm32mp1/README}}: it contains an example of '.its' file, <U-Boot directory>/board/st/stm32mp1/fit_copro_kernel_dtb.its, and shows how to generate the FIT with U-Boot mkimage tool:
* example of '.its' file is provided < U-Boot directory>/board/st/stm32mp1/fit_copro_kernel_dtb.its
 
* you generate the FIT with U-Boot mkimage tool:
 
 
  {{PC$}} mkimage -f fit_copro_kernel_dtb.its fit_copro_kernel_dtb.itb
 
  {{PC$}} mkimage -f fit_copro_kernel_dtb.its fit_copro_kernel_dtb.itb
   
You can load the generated FIT with:
+
You can load the generated FIT using:
 
* 'bootm' command (see {{ CodeSource | U-Boot | doc/uImage.FIT/command_syntax_extensions.txt}})
 
* 'bootm' command (see {{ CodeSource | U-Boot | doc/uImage.FIT/command_syntax_extensions.txt}})
 
* extlinux.conf in bootfs in extlinux directory to automatically load the FIT by [[U-Boot_overview#Generic_Distro_configuration|generic DISTRO]],<br/>for example: < U-Boot directory>/board/st/stm32mp1/extlinux.conf
 
* extlinux.conf in bootfs in extlinux directory to automatically load the FIT by [[U-Boot_overview#Generic_Distro_configuration|generic DISTRO]],<br/>for example: < U-Boot directory>/board/st/stm32mp1/extlinux.conf
   
To go deeper:
+
To go deeper, read:
 
* {{ CodeSource | U-Boot | doc/README.pxe }}
 
* {{ CodeSource | U-Boot | doc/README.pxe }}
 
* {{ CodeSource | U-Boot | doc/uImage.FIT/howto.txt }}
 
* {{ CodeSource | U-Boot | doc/uImage.FIT/howto.txt }}
 
* support of firmware in FIT is done in board_stm32copro_image_process() function in {{CodeSource | U-Boot | board/st/stm32mp1/stm32mp1.c}} associated to image type IH_TYPE_STM32COPRO.
 
* support of firmware in FIT is done in board_stm32copro_image_process() function in {{CodeSource | U-Boot | board/st/stm32mp1/stm32mp1.c}} associated to image type IH_TYPE_STM32COPRO.
   
== Synchronize the remote firmware with Linux ==
+
== Synchronizing the remote firmware with Linux ==
The Linux [[Linux_remoteproc_framework_overview#Remote_processor_.27early.27_boot | remoteproc framework]] provides the ability to detect and manage a firmware loaded by U-Boot.<BR>
+
The [[STM32MPU Embedded Software distribution]] provides the ability to detect and manage a firmware loaded by U-Boot thanks to the [[Linux_remoteproc_framework_overview#Remote_processor_.27early.27_boot | remoteproc]] Linux framework.<BR>
The developer should pay attention to how he implements the Cortex-M4 firmware if the RPMsg is used for communication with the Linux. In this case a synchronization is needed. the cortex-M4 have to wait that the Linux is ready to communicate by updating the vdev status in in the  [[Coprocessor_resource_table | resource table]]) .<BR>
+
The developer must pay attention to how he implements the Arm Cortex-M4 firmware if the RPMsg is used to communicate with Linux. In this case a synchronization is required. The Arm Cortex-M4 core has to wait until Linux is booted to start RPMsg communications. When Linux is ready, the Linux kernel automatically updates the vdev status in the  [[Coprocessor_resource_table | resource table]], and sends a signal to the Arm Cortex-M4 core using the [[IPCC_internal_peripheral | IPCC peripheral]].<BR>
Two methods can be implemented
+
Two methods can be implemented to wait for the synchronization:
* '''Blocking method''': The firmware is blocked on MX_OPENAMP_Init  call (by the rproc_virtio_wait_remote_ready function) until the Linux kernel is ready to communicate (update of the vdev status in the resource table).
+
* '''Blocking method''': the firmware is blocked on MX_OPENAMP_Init  call (by the rproc_virtio_wait_remote_ready function) until the Linux kernel is ready to communicate (update of the vdev status in the resource table).
* '''Non-blocking method''': The Linux Kernel generates an interruption on Cortex-M4 using the [[IPCC_internal_peripheral | IPCC peripheral]] when it is ready to communicate. This interrupt can be used by the Cortex-M4 firmware to initialize the OpenAMP middleware and start the RPMsg protocol.
+
* '''Non-blocking method''': when it is ready to communicate, the Linux kernel generates an interrupt towards the Arm Cortex-M4 core using the [[IPCC_internal_peripheral | IPCC peripheral]]. This interrupt can be used by the Arm Cortex-M4 firmware to initialize the OpenAMP middleware and start the RPMsg protocol.
   
 
<noinclude>
 
<noinclude>