Last edited 3 years ago

Linux Mailbox framework overview: Difference between revisions

This message will disappear after all relevant tasks have been resolved.
Semantic MediaWiki
There are 1 incomplete or pending task to finish installation of Semantic MediaWiki. An administrator or user with sufficient rights can complete it. This should be done before adding new data to avoid inconsistencies.
VisualWikitext
Registered User
mNo edit summary
Registered User
mNo edit summary
 
(8 intermediate revisions by 3 users not shown)
Line 9: Line 9:
* 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.txt | Linux Mailbox documentation}}</ref>.
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 23: Line 23:
: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 Linux documentation:
The APIs are described in the Mailbox client API <ref>{{CodeSource | Linux kernel | include/linux/mailbox_client.h | Mailbox client API}}</ref>
*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]]  
Activate '''stm32 IPCC''' mailbox in kernel configuration using the Linux Menuconfig tool: [[Menuconfig or how to configure kernel]]  
  Device drivers  --->
  Device drivers  --->
Line 34: Line 34:
         <*> STM32 IPCC Mailbox  
         <*> STM32 IPCC Mailbox  


== Device tree configuration ==
=== Device tree configuration ===
{{ReviewsComments|FDE W105 : this shall be in a dedicated DT article. This article needs to follow the Overview template.}}
Please refer to the [[IPCC_device_tree_configuration | IPCC device tree configuration]].


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:
==How to use the framework==
<pre>
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.
ipcc: mailbox@4c001000 {
compatible = "st,stm32-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>;
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?)}}


==How to trace and debug the framework==
==How to trace and debug the framework==
Line 77: Line 47:
  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=
==Source code location==
<references/>
*stm32-ipcc driver: {{CodeSource | Linux kernel | drivers/mailbox/stm32-ipcc.c}}
*framework: {{CodeSource | Linux kernel | drivers/mailbox/mailbox.c}}
*client interface: {{CodeSource | Linux kernel | include/linux/mailbox_client.h}}
 
==References==
<references />


<noinclude>
<noinclude>

Latest revision as of 10:59, 14 September 2021

This article gives information about the Linux® mailbox framework. The mailbox framework is involved in interprocessor communication in heterogeneous multicore systems.

1. Framework purpose[edit source]

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 source]

Mailbox overview.png

2.1. Component description[edit source]

  • 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 source]

The APIs are described in the Mailbox client API [2]

3. Configuration[edit source]

3.1. Kernel Configuration[edit source]

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

3.2. Device tree configuration[edit source]

Please refer to the IPCC device tree configuration.

4. How to use the framework[edit source]

The Linux mailbox documentation [1] provides with a very simple example of use.

5. How to trace and debug the framework[edit source]

5.1. How to trace[edit source]

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

6. Source code location[edit source]

7. References[edit source]

  1. ↑ 1.0 1.1 Linux Mailbox documentation
  2. ↑ Mailbox client API


Linux® is a registered trademark of Linus Torvalds.

Inter-Processor Communication Controller

Application programming interface

Remote Processor Messaging

Retrieved from "https://wiki.st.com/stm32mpu-ecosystem-v3/index.php?title=Linux_Mailbox_framework_overview&oldid=79270"