fix install paths to work for multilib
[processor-sdk/open-amp.git] / README.md
1 # open-amp
2 This repository is the home for the Open Asymmetric Multi Processing (OpenAMP)
3 framework project. The OpenAMP framework provides software components that
4 enable development of software applications for Asymmetric Multiprocessing
5 (AMP) systems. The framework provides the following key capabilities.
7 1. Provides Life Cycle Management, and Inter Processor Communication
8    capabilities for management of remote compute resources and their associated
9    software contexts.
10 2. Provides a stand alone library usable with RTOS and Baremetal software
11    environments
12 3. Compatibility with upstream Linux remoteproc and rpmsg components
13 4. Following AMP configurations supported
14         a. Linux master/Generic(Baremetal) remote
15         b. Generic(Baremetal) master/Linux remote
16 5. Proxy infrastructure and supplied demos showcase ability of proxy on master
17    to handle printf, scanf, open, close, read, write calls from Bare metal
18    based remote contexts.
20 ## OpenAMP Source Structure
21 ```
22 |- lib/
23 |  |- common/     # common helper functions
24 |  |- virtio/     # virtio implementation
25 |  |- rpmsg/      # rpmsg implementation
26 |  |- remoteproc/ # remoteproc implementation
27 |  |  |- drivers  # remoteproc drivers
28 |  |- proxy/      # implement one processor access device on the
29 |  |              # other processor with file operations
30 |- apps/        # demonstration/testing applications
31 |  |- machine/  # common files for machine can be shared by applications
32 |               # It is up to each app to decide whether to use these files.
33 |  |- system/   # common files for system can be shared by applications
34 |               # It is up to each app to decide whether to use these files.
35 |- obsolete     # It is used to build libs which may also required when
36 |               # building the apps. It will be removed in future since
37 |               # user can specify which libs to use when compiling the apps.
38 |- cmake        # CMake files
39 ```
41 OpenAMP library libopen_amp is composed of the following directories in `lib/`:
42 *   `common/`
43 *   `virtio/`
44 *   `rpmsg/`
45 *   `remoteproc/`
46 *   `proxy/`
48 OpenAMP system/machine support has been moved to libmetal, the system/machine
49 layer in the `apps/` directory is for system application initialization, and
50 resource table definition.
52 ### libmetal APIs used in OpenAMP
53 Here are the libmetal APIs used by OpenAMP, if you want to port OpenAMP for your
54 system, you will need to implement the following libmetal APIs in the libmetal's
55 `lib/system/<SYS>` directory:
56 * alloc, for memory allocation and memory free
57 * cache, for flushing cache and invalidating cache
58 * io, for memory mapping. OpenAMP required memory mapping in order to access
59   vrings and carved out memory.
60 * irq, for IRQ handler registration, IRQ disable/enable and global IRQ handling.
61 * mutex
62 * shmem (For RTOS, you can usually use the implementation from
63   `lib/system/generic/`)
64 * sleep, at the moment, OpenAMP only requires microseconds sleep as when OpenAMP
65   fails to get a buffer to send messages, it will call this function to sleep and
66   then try again.
67 * time, for timestamp
68 * init, for libmetal initialization.
69 * atomic
71 Please refer to `lib/system/generic` when you port libmetal for your system.
73 If you a different compiler to GNU gcc, please refer to `lib/compiler/gcc/` to
74 port libmetal for your compiler. At the moment, OpenAMP needs the atomic
75 operations defined in `lib/compiler/gcc/atomic.h`.
77 ## OpenAMP Compilation
78 OpenAMP uses CMake for library and demonstration application compilation.
79 OpenAMP requires libmetal library. For now, you will need to download and
80 compile libmetal library separately before you compiling OpenAMP library.
81 In future, we will try to make libmetal as a submodule to OpenAMP to make this
82 flow easier.
84 ### Example to compile OpenAMP for communication between Linux processes:
85 * Install libsysfs devel and libhugetlbfs devel packages on your Linux host.
86 * build libmetal library on your host as follows:
88     ```
89         $ mkdir -p build-libmetal
90         $ cd build-libmetal
91         $ cmake <libmetal_source>
92         $ make VERBOSE=1 DESTDIR=<libmetal_install> install
93     ```
95 * build OpenAMP library on your host as follows:
97         $ mkdir -p build-openamp
98         $ cd build-openamp
99         $ cmake <openamp_source> -DCMAKE_INCLUDE_PATH=<libmetal_built_include_dir> \
100               -DCMAKE_LIBRARY_PATH=<libmetal_built_lib_dir> [-DWITH_APPS=ON]
101         $ make VERBOSE=1 DESTDIR=$(pwd) install
103 The OpenAMP library will be generated to `build/usr/local/lib` directory,
104 headers will be generated to `build/usr/local/include` directory, and the
105 applications executable will be generated to `build/usr/local/bin`
106 directory.
107 * cmake option `-DWITH_APPS=ON` is to build the demonstration applications.
109 ###  Example to compile Zynq UltraScale+ MPSoC R5 generic(baremetal) remote:
110 * build libmetal library on your host as follows:
111   * Create your on cmake toolchain file to compile libmetal for your generic
112     (baremetal) platform. Here is the example of the toolchain file:
114     ```
115         set (CMAKE_SYSTEM_PROCESSOR "arm"              CACHE STRING "")
116         set (MACHINE "zynqmp_r5" CACHE STRING "")
117         
118         set (CROSS_PREFIX           "armr5-none-eabi-" CACHE STRING "")
119         set (CMAKE_C_FLAGS          "-mfloat-abi=soft -mcpu=cortex-r5 -Wall -Werror -Wextra \
120            -flto -Os -I/ws/xsdk/r5_0_bsp/psu_cortexr5_0/include" CACHE STRING "")
121         
122         SET(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -flto")
123         SET(CMAKE_AR  "gcc-ar" CACHE STRING "")
124         SET(CMAKE_C_ARCHIVE_CREATE "<CMAKE_AR> qcs <TARGET> <LINK_FLAGS> <OBJECTS>")
125         SET(CMAKE_C_ARCHIVE_FINISH   true)
126         
127         include (cross-generic-gcc)
128     ```
130   * Compile libmetal library:
132     ```
133         $ mkdir -p build-libmetal
134         $ cd build-libmetal
135         $ cmake <libmetal_source> -DCMAKE_TOOLCHAIN_FILE=<toolchain_file>
136         $ make VERBOSE=1 DESTDIR=<libmetal_install> install
137     ```
139 * build OpenAMP library on your host as follows:
140   * Create your on cmake toolchain file to compile openamp for your generic
141     (baremetal) platform. Here is the example of the toolchain file:
142     ```
143         set (CMAKE_SYSTEM_PROCESSOR "arm" CACHE STRING "")
144         set (MACHINE                "zynqmp_r5" CACHE STRING "")
145         set (CROSS_PREFIX           "armr5-none-eabi-" CACHE STRING "")
146         set (CMAKE_C_FLAGS          "-mfloat-abi=soft -mcpu=cortex-r5 -Os -flto \
147           -I/ws/libmetal-r5-generic/usr/local/include \
148           -I/ws/xsdk/r5_0_bsp/psu_cortexr5_0/include" CACHE STRING "")
149         set (CMAKE_ASM_FLAGS        "-mfloat-abi=soft -mcpu=cortex-r5" CACHE STRING "")
150         set (PLATFORM_LIB_DEPS      "-lxil -lc -lm" CACHE STRING "")
151         SET(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -flto")
152         SET(CMAKE_AR  "gcc-ar" CACHE STRING "")
153         SET(CMAKE_C_ARCHIVE_CREATE "<CMAKE_AR> qcs <TARGET> <LINK_FLAGS> <OBJECTS>")
154         SET(CMAKE_C_ARCHIVE_FINISH   true)
155         set (CMAKE_FIND_ROOT_PATH /ws/libmetal-r5-generic/usr/local/lib \
156             /ws/xsdk/r5_bsp/psu_cortexr5_0/lib )
158         include (cross_generic_gcc)
159     ```
161   * We use cmake `find_path` and `find_library` to check if libmetal includes
162     and libmetal library is in the includes and library search paths. However,
163     for non-linux system, it doesn't work with `CMAKE_INCLUDE_PATH` and
164     `CMAKE_LIBRARY_PATH` variables, and thus, we need to specify those paths
165     in the toolchain file with `CMAKE_C_FLAGS` and `CMAKE_FIND_ROOT_PATH`.
166 * Compile the OpenAMP library:
168     ```
169     $ mkdir -p build-openamp
170     $ cd build-openamp
171     $ cmake <openamp_source> -DCMAKE_TOOLCHAIN_FILE=<toolchain_file>
172     $ make VERBOSE=1 DESTDIR=$(pwd) install
173     ```
175 The OpenAMP library will be generated to `build/usr/local/lib` directory,
176 headers will be generated to `build/usr/local/include` directory, and the
177 applications executable will be generated to `build/usr/local/bin`
178 directory.
180 * `-DWITH_APPS=ON` is to build the demonstration applications.
181   If you have used `-DWITH_APPS=ON` to build the demos, you can try them on
182   your Linux host as follows:
184     ```
185     # Start echo test server to wait for message to echo
186     $ sudo LD_LIBRARY_PATH=<openamp_built>/usr/local/lib:<libmetal_built>/usr/local/lib \
187        build/usr/local/bin/echo_testd-shared
188     # Run echo test to send message to echo test server
189     $ sudo LD_LIBRARY_PATH=<openamp_built>/usr/local/lib:<libmetal_built>/usr/local/lib \
190        build/usr/local/bin/echo_test-shared 1
191     ```
193 ### Example to compile OpenAMP Linux Userspace for Zynq UltraScale+ MPSoC
194 We can use yocto to build the OpenAMP Linux userspace library and application.
195 open-amp and libmetal recipes are in this yocto layer:
196 https://github.com/OpenAMP/meta-openamp
197 * Add the `meta-openamp` layer to your layers in your yocto build project's `bblayers.conf` file.
198 * Add `libmetal` and `open-amp` to your packages list. E.g. add `libmetal` and `open-amp` to the
199   `IMAGE_INSTALL_append` in the `local.conf` file.
200 * You can also add OpenAMP demos Linux applications packages to your yocto packages list. OpenAMP
201   demo examples recipes are also in `meta-openamp`:
202   https://github.com/OpenAMP/meta-openamp/tree/master/recipes-openamp/openamp-examples
204 In order to user OpenAMP(RPMsg) in Linux userspace, you will need to have put the IPI device,
205   vring memory and shared buffer memory to your Linux kernel device tree. The device tree example
206   can be found here:
207   https://github.com/OpenAMP/open-amp/blob/master/apps/machine/zynqmp/openamp-linux-userspace.dtsi
209 ## Supported System and Machines
210 For now, it supports:
211 * Zynq generic slave
212 * Zynq UltraScale+ MPSoC R5 generic slave
213 * Linux host OpenAMP between Linux userspace processes
214 * Linux userspace OpenAMP RPMsg master
215 * Linux userspace OpenAMP RPMsg slave
217 ## Known Limitations:
218 1. OpenAMP framework supports OpenAMP firmware running as master, however,
219    the example to show this ability is not ready yet.
220 2. In case of OpenAMP on Linux userspace for inter processors communication,
221    life cycle management with remoteproc is not supported yet, that is for now,
222    it is not able to load the remote firmware with OpenAMP running on Linux
223    userspace.
224 3. In case of OpenAMP on Linux userspace for inter processors communication,
225    it only supports static vrings and shared buffers.
226 4. `sudo` is required to run the OpenAMP demos between Linux processes, as
227    it doesn't work on some systems if you are normal users.
229 For using the framework please refer to the wiki of the OpenAMP repo.
230 Subscribe to the open-amp mailing list at https://groups.google.com/group/open-amp.