README.rst
1.. zephyr:code-sample:: ipm-ivshmem
2 :name: IPM over IVSHMEM
3 :relevant-api: ipm_interface
4
5 Implement inter-processor mailbox (IPM) over IVSHMEM (Inter-VM shared memory)
6
7Prerequisites
8*************
9
10* QEMU needs to available.
11
12ivshmem-server needs to be available and running. The server is available in
13Zephyr SDK or pre-built in some distributions. Otherwise, it is available in
14QEMU source tree.
15
16ivshmem-client needs to be available as it is employed in this sample as an
17external application. The same conditions of ivshmem-server apply to the
18ivshmem-server, as it is also available via QEMU.
19
20Preparing IVSHMEM server
21************************
22#. The ivshmem-server utility for QEMU can be found into the Zephyr SDK
23 directory, in:
24 ``/path/to/your/zephyr-sdk/zephyr-<version>/sysroots/x86_64-pokysdk-linux/usr/xilinx/bin/``
25
26#. You may also find ivshmem-client utility, it can be useful to check if everything works
27 as expected.
28
29#. Run ivshmem-server. For the ivshmem-server, both number of vectors and
30 shared memory size are decided at run-time (when the server is executed).
31 For Zephyr, the number of vectors and shared memory size of ivshmem are
32 decided at compile-time and run-time, respectively. For Arm64 we use
33 vectors == 2 for the project configuration in this sample. Here is an example:
34
35 .. code-block:: console
36
37 # n = number of vectors
38 $ sudo ivshmem-server -n 2
39 $ *** Example code, do not use in production ***
40
41#. Appropriately set ownership of ``/dev/shm/ivshmem`` and
42 ``/tmp/ivshmem_socket`` for your deployment scenario. For instance:
43
44 .. code-block:: console
45
46 $ sudo chgrp $USER /dev/shm/ivshmem
47 $ sudo chmod 060 /dev/shm/ivshmem
48 $ sudo chgrp $USER /tmp/ivshmem_socket
49 $ sudo chmod 060 /tmp/ivshmem_socket
50
51Building and Running
52********************
53
54After getting QEMU ready to go, first create two output folders, so open two terminals
55and create them, these folders will receive the output of Zephyr west commands:
56
57 .. code-block:: console
58
59 $ mkdir -p path/to/instance_1
60
61On another terminal window do:
62
63 .. code-block:: console
64
65 $ mkdir -p path/to/instance_2
66
67Then build the sample as follows, don't forget, two builds are necessary
68to test this sample, so append the option ``-d path/to/instance_1`` and
69on the other terminal window do the same, that is it ``-d path/to/instance_2``
70
71.. zephyr-app-commands::
72 :zephyr-app: samples/drivers/ipm/ipm_ivshmem
73 :board: qemu_cortex_a53
74 :goals: build
75 :compact:
76
77To run both QEMU sides, repeat the west build command followed
78by ``-d path/to/instance_x`` where x is 1 or 2 depending on the
79terminal window, using the run target:
80
81.. zephyr-app-commands::
82 :zephyr-app: samples/drivers/ipm/ipm_ivshmem
83 :board: qemu_cortex_a53
84 :goals: run
85 :compact:
86
87Expected output
88***************
89
90On the console just use the ``ivshmem_ipm_send`` command
91followed by the destination peer-id, to get the peer-id destination
92go to the other terminal window and check with ``ivshmem`` command:
93
94 .. code-block:: console
95
96 *** Booting Zephyr OS build zephyr-v3.4.0-974-g7fba7d395750 ***
97
98
99 uart:~$ ivshmem
100 IVshmem up and running:
101 Shared memory: 0xafa00000 of size 4194304 bytes
102 Peer id: 12
103 Notification vectors: 2
104 uart:~$
105
106For example one of the instances has the peer-id 12, so go the other
107instance and use the command to send the IPM notification followed
108by this peer-id:
109
110 .. code-block:: console
111
112 *** Booting Zephyr OS build zephyr-v3.4.0-974-g7fba7d395750 ***
113
114
115 uart:~$ ivshmem
116 IVshmem up and running:
117 Shared memory: 0xafa00000 of size 4194304 bytes
118 Peer id: 11
119 Notification vectors: 2
120 uart:~$ ivshmem_ipm_send 12
121
122Then go back to the other terminal window where user may see the reception
123of the notification on the terminal:
124
125 .. code-block:: console
126
127 uart:~$ ivshmem
128 IVshmem up and running:
129 Shared memory: 0xafa00000 of size 4194304 bytes
130 Peer id: 12
131 Notification vectors: 2
132 uart:~$ Received IPM notification over IVSHMEM
133
