Difference between revisions of "Linux Mailbox framework overview"

[quality revision] [quality revision]
m
 
 

Template:ArticleMainWriter Template:ArticleApprovedVersion SUMMARY
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]

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]

Mailbox overview.png

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 [3]

3 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 Device tree configuration[edit]

The mailbox device node must be declared and enabled in the Linux kernel device tree. Here is an extract of the STM32MP1 evaluation board device tree: 

ipcc: mailbox@4c001000 {
	compatible = "st,stm32-ipcc";
	#mbox-cells = <1>;
	reg = <0x4c001000 0x400>;
	interrupts-extended = <&intc GIC_SPI 100 IRQ_TYPE_NONE>,
			      <&intc GIC_SPI 101 IRQ_TYPE_NONE>,
			      <&exti 62 1>;
	interrupt-names = "rx", "tx", "wakeup";
	clocks = <&rcc_clk IPCC>;
	wakeup-source;

        Status = "Okay";
 };

Then client has to reserve channels. Here is an example of channel allocation for the remoteproc node: 

&m4_rproc {
       memory-region = <&ipc_share>;
       mboxes = <&ipcc 0>, <&ipcc 1>, <&ipcc 2>;
       mbox-names = "vq0", "vq1", "init_shdn";
       status = "okay";
};

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

6 References[edit]

  1. ↑ Linux Mailbox documentation
  2. ↑ Mailbox client API
  3. ↑ Mailbox controller API 


<noinclude>

{{ArticleBasedOnModel | [[Framework overview article model]]}}
{{ArticleMainWriter | ArnaudP}}
{{ArticleApprovedVersion | ArnaudP | FabienD(Passed 21Nov'18), GeraldB(Not Done), LoicP(Not Done)|  14Mar'18 | AnneJ- 02Dec'18- 9833 | 06Dec'18}} 
[[Category:Coprocessor management Linux]]</noinclude>


'''SUMMARY '''<br>
This article gives information about the Linux<sup>&reg;</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>{{CodeSource | Linux kernel | Documentation/mailbox.txt | 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==
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 ==
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,stm32-ipcc";
	#mbox-cells = <1>;
	reg = <0x4c001000 0x400>;
	interrupts-extended = <&intc GIC_SPI 100 IRQ_TYPE_NONE>,<&intc GIC_SPI 101 IRQ_TYPE_NONE>,<&exti 62 1>;
	interrupt-names = "rx", "tx", "wakeup";
	clocks = <&rcc_clk IPCC>;
	wakeup-source;

        Status = "Okay";
 };</pre>

Then client has to reserve channels. Here is an example of channel allocation for the [[Linux remoteproc framework overview|remoteproc]] node:
 &m4_rproc {
        memory-region = <&ipc_share>;
        mboxes = {{highlight|<&ipcc 0>, <&ipcc 1>, <&ipcc 2>;}}
        mbox-names = {{highlight|"vq0", "vq1", "init_shdn";}}
        status = "okay";
 };

==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/>

<noinclude>

[[Category:Coprocessor management Linux]]
{{PublicationRequestId | 9833 | 2018-12-02 | AnneJ}}
{{ArticleBasedOnModel | Framework overview article model}}</noinclude>
Line 1: Line 1:
−
<noinclude>
  
−
{{ArticleBasedOnModel | [[Framework overview article model]]}}
  
−
{{ArticleMainWriter | ArnaudP}}
  
−
{{ArticleApprovedVersion | ArnaudP | FabienD(Passed 21Nov'18), GeraldB(Not Done), LoicP(Not Done)|  14Mar'18 | AnneJ- 02Dec'18- 9833 | 06Dec'18}}
 
−
[[Category:Coprocessor management Linux]]
  
−
</noinclude>
  
−
 
−
'''SUMMARY '''<br>
  
 
This article gives information about the Linux<sup>&reg;</sup> mailbox framework. The mailbox framework is involved in interprocessor communication in heterogeneous multicore systems.
  
This article gives information about the Linux<sup>&reg;</sup> mailbox framework. The mailbox framework is involved in interprocessor communication in heterogeneous multicore systems.
   
Line 76: Line 68:
 
=References=
  
=References=
 
<references/>
  
<references/>
  +
  +
<noinclude>
  +
[[Category:Coprocessor management Linux]]
  +
{{PublicationRequestId | 9833 | 2018-12-02 | AnneJ}}
  +
{{ArticleBasedOnModel | Framework overview article model}}
  +
</noinclude>
Retrieved from "https://wiki.st.com/stm32mpu-ecosystem-v1/index.php?title=Linux_Mailbox_framework_overview&oldid=67087"