1# open-amp
2This repository is the home for the Open Asymmetric Multi Processing (OpenAMP)
3framework project. The OpenAMP framework provides software components that
4enable development of software applications for Asymmetric Multiprocessing
5(AMP) systems. The framework provides the following key capabilities.
6
71. Provides Life Cycle Management, and Inter Processor Communication
8   capabilities for management of remote compute resources and their associated
9   software contexts.
102. Provides a stand alone library usable with RTOS and Baremetal software
11   environments
123. Compatibility with upstream Linux remoteproc and rpmsg components
134. Following AMP configurations supported
14	a. Linux host/Generic(Baremetal) remote
15	b. Generic(Baremetal) host/Linux remote
165. Proxy infrastructure and supplied demos showcase ability of proxy on host
17   to handle printf, scanf, open, close, read, write calls from Bare metal
18   based remote contexts.
19
20## OpenAMP Source Structure
21```
22|- lib/
23|  |- virtio/     # virtio implementation
24|  |- rpmsg/      # rpmsg implementation
25|  |- remoteproc/ # remoteproc implementation
26|  |- proxy/      # implement one processor access device on the
27|  |              # other processor with file operations
28|- apps/        # demonstration/testing applications
29|  |- examples/ # Application samples using the OpenAMP framework.
30|  |- machine/  # common files for machine can be shared by applications
31|  |            # It is up to each app to decide whether to use these files.
32|  |- system/   # common files for system can be shared by applications
33|               # It is up to each app to decide whether to use these files.
34|- cmake        # CMake files
35|- script       # helper scripts (such as checkpatch) for contributors.
36```
37
38OpenAMP library libopen_amp is composed of the following directories in `lib/`:
39*   `virtio/`
40*   `rpmsg/`
41*   `remoteproc/`
42*   `proxy/`
43
44OpenAMP system/machine support has been moved to libmetal, the system/machine
45layer in the `apps/` directory is for system application initialization, and
46resource table definition.
47
48### libmetal APIs used in OpenAMP
49Here are the libmetal APIs used by OpenAMP, if you want to port OpenAMP for your
50system, you will need to implement the following libmetal APIs in the libmetal's
51`lib/system/<SYS>` directory:
52* alloc, for memory allocation and memory free
53* cache, for flushing cache and invalidating cache
54* io, for memory mapping. OpenAMP required memory mapping in order to access
55  vrings and carved out memory.
56* irq, for IRQ handler registration, IRQ disable/enable and global IRQ handling.
57* mutex
58* shmem (For RTOS, you can usually use the implementation from
59  `lib/system/generic/`)
60* sleep, at the moment, OpenAMP only requires microseconds sleep as when OpenAMP
61  fails to get a buffer to send messages, it will call this function to sleep and
62  then try again.
63* time, for timestamp
64* init, for libmetal initialization.
65* atomic
66
67Please refer to `lib/system/generic` when you port libmetal for your system.
68
69If you a different compiler to GNU gcc, please refer to `lib/compiler/gcc/` to
70port libmetal for your compiler. At the moment, OpenAMP needs the atomic
71operations defined in `lib/compiler/gcc/atomic.h`.
72
73## OpenAMP Compilation
74OpenAMP uses CMake for library and demonstration application compilation.
75OpenAMP requires libmetal library. For now, you will need to download and
76compile libmetal library separately before you compiling OpenAMP library.
77In future, we will try to make libmetal as a submodule to OpenAMP to make this
78flow easier.
79
80Some Cmake options are available to allow user to customize to the OpenAMP
81library for it project:
82* **WITH_PROXY** (default OFF): Include proxy support in the library.
83* **WITH APPS** (default OFF): Build with sample applications.
84* **WITH_PROXY_APPS** (default OFF):Build with proxy sample applications.
85* **WITH_VIRTIO_DRIVER** (default ON): Build with virtio driver enabled.
86  This option can be set to OFF if the only the remote mode is implemented.
87* **WITH_VIRTIO_DEVICE** (default ON): Build with virtio device enabled.
88  This option can be set to OFF if the only the driver mode is implemented.
89* **WITH_STATIC_LIB** (default ON): Build with a static library.
90* **WITH_SHARED_LIB** (default ON): Build with a shared library.
91* **WITH_ZEPHYR** (default OFF): Build open-amp as a zephyr library. This option
92  is mandatory in a Zephyr environment.
93* **WITH_DCACHE_VRINGS** (default OFF): Build with data cache operations
94  enabled on vrings.
95* **WITH_DCACHE_BUFFERS** (default OFF): Build with data cache operations
96  enabled on buffers.
97* **WITH_DCACHE_RSC_TABLE** (default OFF): Build with data cache operations
98  enabled on resource table.
99* **RPMSG_BUFFER_SIZE** (default 512): adjust the size of the RPMsg buffers.
100  The default value of the RPMsg size is compatible with the Linux Kernel hard
101  coded value. If you AMP configuration is Linux kernel host/ OpenAMP remote,
102  this option must not be used.
103
104### Example to compile OpenAMP for Zephyr
105The [Zephyr open-amp repo](https://github.com/zephyrproject-rtos/open-amp)
106implements the open-amp library for the Zephyr project. It is mainly a fork of
107this repository, with some add-ons for integration in the Zephyr project.
108The standard way to compile OpenAMP for a Zephyr project is to use Zephyr build
109environment. Please refer to
110[Zephyr OpenAMP samples](https://github.com/zephyrproject-rtos/zephyr/tree/main/samples/subsys/ipc)
111for examples and [Zephyr documentation](https://docs.zephyrproject.org/latest/) for the build
112process.
113
114### Example to compile OpenAMP for communication between Linux processes:
115* Install libsysfs devel and libhugetlbfs devel packages on your Linux host.
116* build libmetal library on your host as follows:
117
118    ```
119        $ mkdir -p build-libmetal
120        $ cd build-libmetal
121        $ cmake <libmetal_source>
122        $ make VERBOSE=1 DESTDIR=<libmetal_install> install
123    ```
124
125* build OpenAMP library on your host as follows:
126
127        $ mkdir -p build-openamp
128        $ cd build-openamp
129        $ cmake <openamp_source> -DCMAKE_INCLUDE_PATH=<libmetal_built_include_dir> \
130              -DCMAKE_LIBRARY_PATH=<libmetal_built_lib_dir> [-DWITH_APPS=ON]
131        $ make VERBOSE=1 DESTDIR=$(pwd) install
132
133The OpenAMP library will be generated to `build/usr/local/lib` directory,
134headers will be generated to `build/usr/local/include` directory, and the
135applications executable will be generated to `build/usr/local/bin`
136directory.
137
138* cmake option `-DWITH_APPS=ON` is to build the demonstration applications.
139* If you have used `-DWITH_APPS=ON` to build the demos, you can try them on
140  your Linux host as follows:
141
142  * rpmsg echo demo:
143    ```
144    # Start echo test server to wait for message to echo
145    $ sudo LD_LIBRARY_PATH=<openamp_built>/usr/local/lib:<libmetal_built>/usr/local/lib \
146       build/usr/local/bin/rpmsg-echo-shared
147    # Run echo test to send message to echo test server
148    $ sudo LD_LIBRARY_PATH=<openamp_built>/usr/local/lib:<libmetal_built>/usr/local/lib \
149       build/usr/local/bin/rpmsg-echo-ping-shared 1
150    ```
151
152  * rpmsg echo demo with the nocopy API:
153    ```
154    # Start echo test server to wait for message to echo
155    $ sudo LD_LIBRARY_PATH=<openamp_built>/usr/local/lib:<libmetal_built>/usr/local/lib \
156       build/usr/local/bin/rpmsg-nocopy-echo-shared
157    # Run echo test to send message to echo test server
158    $ sudo LD_LIBRARY_PATH=<openamp_built>/usr/local/lib:<libmetal_built>/usr/local/lib \
159       build/usr/local/bin/rpmsg-nocopy-ping-shared 1
160    ```
161
162###  Example to compile Zynq UltraScale+ MPSoC R5 generic(baremetal) remote:
163* build libmetal library on your host as follows:
164  * Create your on cmake toolchain file to compile libmetal for your generic
165    (baremetal) platform. Here is the example of the toolchain file:
166
167    ```
168        set (CMAKE_SYSTEM_PROCESSOR "arm"              CACHE STRING "")
169        set (MACHINE "zynqmp_r5" CACHE STRING "")
170
171        set (CROSS_PREFIX           "armr5-none-eabi-" CACHE STRING "")
172        set (CMAKE_C_FLAGS          "-mfloat-abi=soft -mcpu=cortex-r5 -Wall -Werror -Wextra \
173           -flto -Os -I/ws/xsdk/r5_0_bsp/psu_cortexr5_0/include" CACHE STRING "")
174
175        SET(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -flto")
176        SET(CMAKE_AR  "gcc-ar" CACHE STRING "")
177        SET(CMAKE_C_ARCHIVE_CREATE "<CMAKE_AR> qcs <TARGET> <LINK_FLAGS> <OBJECTS>")
178        SET(CMAKE_C_ARCHIVE_FINISH   true)
179
180        include (cross-generic-gcc)
181    ```
182
183  * Compile libmetal library:
184
185    ```
186        $ mkdir -p build-libmetal
187        $ cd build-libmetal
188        $ cmake <libmetal_source> -DCMAKE_TOOLCHAIN_FILE=<toolchain_file>
189        $ make VERBOSE=1 DESTDIR=<libmetal_install> install
190    ```
191
192* build OpenAMP library on your host as follows:
193  * Create your on cmake toolchain file to compile openamp for your generic
194    (baremetal) platform. Here is the example of the toolchain file:
195    ```
196        set (CMAKE_SYSTEM_PROCESSOR "arm" CACHE STRING "")
197        set (MACHINE                "zynqmp_r5" CACHE STRING "")
198        set (CROSS_PREFIX           "armr5-none-eabi-" CACHE STRING "")
199        set (CMAKE_C_FLAGS          "-mfloat-abi=soft -mcpu=cortex-r5 -Os -flto \
200          -I/ws/libmetal-r5-generic/usr/local/include \
201          -I/ws/xsdk/r5_0_bsp/psu_cortexr5_0/include" CACHE STRING "")
202        set (CMAKE_ASM_FLAGS        "-mfloat-abi=soft -mcpu=cortex-r5" CACHE STRING "")
203        set (PLATFORM_LIB_DEPS      "-lxil -lc -lm" CACHE STRING "")
204        SET(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -flto")
205        SET(CMAKE_AR  "gcc-ar" CACHE STRING "")
206        SET(CMAKE_C_ARCHIVE_CREATE "<CMAKE_AR> qcs <TARGET> <LINK_FLAGS> <OBJECTS>")
207        SET(CMAKE_C_ARCHIVE_FINISH   true)
208        set (CMAKE_FIND_ROOT_PATH /ws/libmetal-r5-generic/usr/local/lib \
209            /ws/xsdk/r5_bsp/psu_cortexr5_0/lib )
210
211        include (cross_generic_gcc)
212    ```
213
214  * We use cmake `find_path` and `find_library` to check if libmetal includes
215    and libmetal library is in the includes and library search paths. However,
216    for non-linux system, it doesn't work with `CMAKE_INCLUDE_PATH` and
217    `CMAKE_LIBRARY_PATH` variables, and thus, we need to specify those paths
218    in the toolchain file with `CMAKE_C_FLAGS` and `CMAKE_FIND_ROOT_PATH`.
219* Compile the OpenAMP library:
220
221    ```
222    $ mkdir -p build-openamp
223    $ cd build-openamp
224    $ cmake <openamp_source> -DCMAKE_TOOLCHAIN_FILE=<toolchain_file>
225    $ make VERBOSE=1 DESTDIR=$(pwd) install
226    ```
227
228The OpenAMP library will be generated to `build/usr/local/lib` directory,
229headers will be generated to `build/usr/local/include` directory, and the
230applications executable will be generated to `build/usr/local/bin`
231directory.
232
233
234### Example to compile OpenAMP Linux Userspace for Zynq UltraScale+ MPSoC
235We can use yocto to build the OpenAMP Linux userspace library and application.
236open-amp and libmetal recipes are in this yocto layer:
237https://github.com/OpenAMP/meta-openamp
238* Add the `meta-openamp` layer to your layers in your yocto build project's `bblayers.conf` file.
239* Add `libmetal` and `open-amp` to your packages list. E.g. add `libmetal` and `open-amp` to the
240  `IMAGE_INSTALL_append` in the `local.conf` file.
241* You can also add OpenAMP demos Linux applications packages to your yocto packages list. OpenAMP
242  demo examples recipes are also in `meta-openamp`:
243  https://github.com/OpenAMP/meta-openamp/tree/master/recipes-openamp/rpmsg-examples
244
245In order to user OpenAMP(RPMsg) in Linux userspace, you will need to have put the IPI device,
246  vring memory and shared buffer memory to your Linux kernel device tree. The device tree example
247  can be found here:
248  https://github.com/OpenAMP/open-amp/blob/main/apps/machine/zynqmp/openamp-linux-userspace.dtsi
249
250## Version
251The OpenAMP version follows the set of rule proposed in [Semantic Versioning specification](https://semver.org/).
252
253## Supported System and Machines
254For now, it supports:
255* Zynq generic remote
256* Zynq UltraScale+ MPSoC R5 generic remote
257* Linux host OpenAMP between Linux userspace processes
258* Linux userspace OpenAMP RPMsg host
259* Linux userspace OpenAMP RPMsg remote
260* Linux userspace OpenAMP RPMsg and MicroBlaze bare metal remote
261
262## Known Limitations:
2631. In case of OpenAMP on Linux userspace for inter processors communication,
264   it only supports static vrings and shared buffers.
2652. `sudo` is required to run the OpenAMP demos between Linux processes, as
266   it doesn't work on some systems if you are normal users.
267
268## How to contribute:
269As an open-source project, we welcome and encourage the community to submit patches directly to the project. As a contributor you  should be familiar with common developer tools such as Git and CMake, and platforms such as GitHub.
270Then following points should be rescpected to facilitate the review process.
271
272### Licencing
273Code is contributed to the Linux kernel under a number of licenses, but all code must be compatible with version the [BSD License](https://github.com/OpenAMP/open-amp/blob/main/LICENSE.md), which is the license covering the OpenAMP distribution as a whole. In practice, use the following tag instead of the full license text in the individual files:
274
275    ```
276    SPDX-License-Identifier:    BSD-3-Clause
277    SPDX-License-Identifier:    BSD-2-Clause
278    ```
279### Signed-off-by
280Commit message must contain Signed-off-by: line and your email must match the change authorship information. Make sure your .gitconfig is set up correctly:
281
282    ```
283    git config --global user.name "first-name Last-Namer"
284    git config --global user.email "yourmail@company.com"
285    ```
286### gitlint
287Before you submit a pull request to the project, verify your commit messages meet the requirements. The check can be  performed locally using the the gitlint command.
288
289Run gitlint locally in your tree and branch where your patches have been committed:
290
291      ```gitlint```
292Note, gitlint only checks HEAD (the most recent commit), so you should run it after each commit, or use the --commits option to specify a commit range covering all the development patches to be submitted.
293
294### Code style
295In general, follow the Linux kernel coding style, with the following exceptions:
296
297* Use /**  */ for doxygen comments that need to appear in the documentation.
298
299The Linux kernel GPL-licensed tool checkpatch is used to check coding style conformity.Checkpatch is available in the scripts directory.
300
301To check your \<n\> commits in your git branch:
302   ```
303   ./scripts/checkpatch.pl --strict  -g HEAD-<n>
304
305   ```
306### Send a pull request
307We use standard github mechanism for pull request. Please refer to github documentation for help.
308
309## Communication and Collaboration
310[Subscribe](https://lists.openampproject.org/mailman3/lists/openamp-rp.lists.openampproject.org/) to the OpenAMP mailing list(openamp-rp@lists.openampproject.org).
311
312For more details on the framework please refer to the the [OpenAMP wiki](https://github.com/OpenAMP/open-amp/wiki).
313