Approved version. Approved on: 15:09, 24 November 2021
Difference between revisions of "Linux Mailbox framework overview"
| [quality revision] | [quality revision] |
|
m
|
(Merge articles)
|
This article gives information about the Linux® mailbox framework. The mailbox framework is involved in interprocessor communication in heterogeneous multicore systems.
Contents
1 Framework purpose[edit]
The mailbox is used in interprocessor communication to exchange messages or signals between the host and the coprocessor cores. The mailbox framework is based on:
- A mailbox controller that is platform dependent:
- It is in charge of configuring and handling IRQ from the IPCC peripheral.
- It provides a generic API to the mailbox client.
- A mailbox client that is in charge of the message to send or receive.
A general presentation of the mailbox framework is available in the Linux mailbox documentation [1].
2 System overview[edit]
2.1 Component description[edit]
- Mailbox controller
- The mailbox controller is the stm32_ipcc. It configures and controls the IPCC peripheral
- Mailbox client
- The user can define his own mailbox client.
- For example, the RPMsg framework uses mailbox for the interprocessor communication.
- In this case the mailbox client is the remoteproc driver that forwards services from/to the RPMsg framework.
2.2 API description[edit]
The APIs are described in the Linux documentation: Mailbox client API [2]
Mailbox controller API [33 Configuration[edit]
3.1 Kernel Configuration[edit]
Activate stm32 IPCC mailbox in kernel configuration using the Linux Menuconfig tool: Menuconfig or how to configure kernel
Device drivers --->
-*- Mailbox Hardware Support --->
<*> STM32 IPCC Mailbox
4
3.2 Device tree configuration[edit]
The mailbox device node must be declared and enabled in the Linux kernel Please refer to the IPCC device tree . Here is an extract of the STM32MP1 evaluation board device tree:
ipcc: mailbox@4c001000 {
compatible = "st,stm32mp1-ipcc";
#mbox-cells = <1>;
reg = <0x4c001000 0x400>;
st,proc-id = <0>;
interrupts-extended =
<&exti 61 1>;
<&intc GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>;
interrupt-names = "rx", "tx";
clocks = <&rcc_clk IPCC>;
wakeup-source;
power-domains = <&pd_core>;
status = "disabled";
};
Then client has to reserve channels. Here is an example of channel allocation for the remoteproc node:
&m4_rproc {
memory-region = <&retram>, <&mcuram>, <&mcuram2>, <&vdev0vring0>,
<&vdev0vring1>, <&vdev0buffer>, <&mcu_rsc_table>;
mboxes = <&ipcc 0>, <&ipcc 1>, <&ipcc 2>;
mbox-names = "vq0", "vq1", "shutdown";
interrupt-parent = <&exti>;
interrupts = <68 1>;
wakeup-source;
status = "okay";
};
4 How to use the framework[edit]
The Linux mailbox documentation [1] provides with a very simple example of use.
5 How to trace and debug the framework[edit]
5.1 How to trace[edit]
Dynamic debug traces can be added using the following commands:
echo -n 'file stm32-ipcc.c +p' > /sys/kernel/debug/dynamic_debug/control echo -n 'file mailbox.c +p' > /sys/kernel/debug/dynamic_debug/control
- stm32-ipcc driver: drivers/mailbox/stm32-ipcc.c
6 Source code location[edit]
- framework: drivers/mailbox/mailbox.c
- client interface: include/linux/mailbox_client.h
7 References[edit]
<noinclude>{{ApplicableFor |MPUs list=STM32MP15x |MPUs checklist=STM32MP13x, STM32MP15x }}</noinclude> This article gives information about the Linux<sup>®</sup> mailbox framework. The mailbox framework is involved in interprocessor communication in heterogeneous multicore systems. == Framework purpose == The mailbox is used in interprocessor communication to exchange messages or signals between the host and the coprocessor cores. The mailbox framework is based on: * A '''mailbox controller''' that is platform dependent: ** It is in charge of configuring and handling IRQ from the IPCC peripheral. ** It provides a generic API to the mailbox client. * A '''mailbox client''' that is in charge of the message to send or receive. <BR> A general presentation of the mailbox framework is available in the Linux mailbox documentation <ref name="Linux Mailbox documentation">{{CodeSource | Linux kernel | Documentation/driver-api/mailbox.txtrst | Linux Mailbox documentation}}</ref>. == System overview == [[File:mailbox_overview.png | link=]] === Component description === * '''Mailbox controller''' :The mailbox controller is the '''stm32_ipcc'''. It configures and controls the [[IPCC internal peripheral| IPCC peripheral]] * '''Mailbox client''' :The user can define his own mailbox client. :For example, the [[Linux RPMsg framework overview|RPMsg framework]] uses mailbox for the interprocessor communication. :In this case the mailbox client is the [[Linux remoteproc framework overview|remoteproc]] driver that forwards services from/to the RPMsg framework. === API description === The APIs are described in the Linux documentation: *Mailbox client API <ref>{{CodeSource | Linux kernel | include/linux/mailbox_client.h | Mailbox client API}}</ref> *Mailbox controller API <ref>{{CodeSource | Linux kernel | include/linux/mailbox_controller.h | Mailbox controller API}}</ref> == Configuration== == Configuration== === Kernel Configuration === Activate '''stm32 IPCC''' mailbox in kernel configuration using the Linux Menuconfig tool: [[Menuconfig or how to configure kernel]] Device drivers ---> -*- Mailbox Hardware Support ---><*> STM32 IPCC Mailbox === Device tree configuration == {{ReviewsComments|FDE W105 : this shall be in a dedicated DT article. This article needs to follow the Overview template.}} The mailbox device node must be declared and enabled in the Linux kernel [[Device tree|device tree]]. Here is an extract of the STM32MP1 evaluation board device tree: <pre> ipcc: mailbox@4c001000 { compatible = "st,stm32mp1-ipcc"; #mbox-cells = <1>; reg = <0x4c001000 0x400>; st,proc-id = <0>; interrupts-extended =<&exti 61 1>;<&intc GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>; interrupt-names = "rx", "tx"; clocks = <&rcc_clk IPCC>; wakeup-source; power-domains = <&pd_core>; status = "disabled"; };</pre> Then client has to reserve channels. Here is an example of channel allocation for the [[Linux remoteproc framework overview|remoteproc]] node:<pre> &m4_rproc { memory-region = <&retram>, <&mcuram>, <&mcuram2>, <&vdev0vring0>,<&vdev0vring1>, <&vdev0buffer>, <&mcu_rsc_table>; mboxes = <&ipcc 0>, <&ipcc 1>, <&ipcc 2>; mbox-names = "vq0", "vq1", "shutdown"; interrupt-parent = <&exti>; interrupts = <68 1>; wakeup-source; status = "okay"; };</pre> {{ReviewsComments|FDE W105 : where shall this article be located? (mailbox or rproc?)}} = Please refer to the [[IPCC_device_tree_configuration | IPCC device tree configuration]]. ==How to use the framework== The Linux mailbox documentation <ref name="Linux Mailbox documentation">{{CodeSource | Linux kernel | Documentation/driver-api/mailbox.rst | Linux Mailbox documentation}}</ref> provides with a very simple example of use. ==How to trace and debug the framework== === How to trace=== Dynamic debug traces can be added using the following commands: echo -n 'file stm32-ipcc.c +p' > /sys/kernel/debug/dynamic_debug/control echo -n 'file mailbox.c +p' > /sys/kernel/debug/dynamic_debug/control =References=<references/>*stm32-ipcc driver: {{CodeSource | Linux kernel | drivers/mailbox/stm32-ipcc.c}} ==Source code location== *framework: {{CodeSource | Linux kernel | drivers/mailbox/mailbox.c}} *client interface: {{CodeSource | Linux kernel | include/linux/mailbox_client.h}} ==References==<references /> <noinclude> [[Category:Coprocessor management Linux]] {{PublicationRequestId | 9833 | 2018-12-02 | AnneJ}} {{ArticleBasedOnModel | Framework overview article model}}</noinclude>
| Line 13: | Line 13: | ||
* A '''mailbox client''' that is in charge of the message to send or receive. |
* A '''mailbox client''' that is in charge of the message to send or receive. |
||
<BR> |
<BR> |
||
| − | A general presentation of the mailbox framework is available in the Linux mailbox documentation <ref>{{CodeSource | Linux kernel | Documentation/mailbox. |
+ | A general presentation of the mailbox framework is available in the Linux mailbox documentation <ref name="Linux Mailbox documentation">{{CodeSource | Linux kernel | Documentation/driver-api/mailbox.rst | Linux Mailbox documentation}}</ref>. |
== System overview == |
== System overview == |
||
| Line 27: | Line 27: | ||
:For example, the [[Linux RPMsg framework overview|RPMsg framework]] uses mailbox for the interprocessor communication. |
:For example, the [[Linux RPMsg framework overview|RPMsg framework]] uses mailbox for the interprocessor communication. |
||
:In this case the mailbox client is the [[Linux remoteproc framework overview|remoteproc]] driver that forwards services from/to the RPMsg framework. |
:In this case the mailbox client is the [[Linux remoteproc framework overview|remoteproc]] driver that forwards services from/to the RPMsg framework. |
||
| + | |||
=== API description === |
=== API description === |
||
| − | The APIs are described in the |
+ | The APIs are described in the Mailbox client API <ref>{{CodeSource | Linux kernel | include/linux/mailbox_client.h | Mailbox client API}}</ref> |
| − | |||
| − | |||
== Configuration== |
== Configuration== |
||
| + | === Kernel Configuration === |
||
Activate '''stm32 IPCC''' mailbox in kernel configuration using the Linux Menuconfig tool: [[Menuconfig or how to configure kernel]] |
Activate '''stm32 IPCC''' mailbox in kernel configuration using the Linux Menuconfig tool: [[Menuconfig or how to configure kernel]] |
||
Device drivers ---> |
Device drivers ---> |
||
| Line 38: | Line 38: | ||
<*> STM32 IPCC Mailbox |
<*> STM32 IPCC Mailbox |
||
| − | == Device tree configuration == |
+ |
=== Device tree configuration === |
| − | + |
Please refer to the [[IPCC_device_tree_configuration | IPCC device tree configuration]]. |
|
| − | + | ==How to use the framework== |
|
| − | + |
The Linux mailbox documentation <ref name="Linux Mailbox documentation">{{CodeSource | Linux kernel | Documentation/driver-api/mailbox.rst | Linux Mailbox documentation}}</ref> provides with a very simple example of use.
|
|
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | {{ |
||
==How to trace and debug the framework== |
==How to trace and debug the framework== |
||
| Line 81: | Line 51: | ||
echo -n 'file mailbox.c +p' > /sys/kernel/debug/dynamic_debug/control |
echo -n 'file mailbox.c +p' > /sys/kernel/debug/dynamic_debug/control |
||
| − | =References= |
+ | *stm32-ipcc driver: {{CodeSource | Linux kernel | drivers/mailbox/stm32-ipcc.c}} |
| − | <references/> |
+ | ==Source code location== |
| + | *framework: {{CodeSource | Linux kernel | drivers/mailbox/mailbox.c}} |
||
| + | *client interface: {{CodeSource | Linux kernel | include/linux/mailbox_client.h}} |
||
| + | |||
| + |
==References== |
||
| + | <references /> |
||
<noinclude> |
<noinclude> |
||