Update README for the OpenAMP on top of libmetal
[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.
179 * `-DWITH_APPS=ON` is to build the demonstration applications.
180   If you have used `-DWITH_APPS=ON` to build the demos, you can try them on
181   your Linux host as follows:
182     ```
183     # Start echo test server to wait for message to echo
184     $ sudo LD_LIBRARY_PATH=<openamp_built>/usr/local/lib:<libmetal_built>/usr/local/lib \
185        build/usr/local/bin/echo_testd-shared
186     # Run echo test to send message to echo test server
187     $ sudo LD_LIBRARY_PATH=<openamp_built>/usr/local/lib:<libmetal_built>/usr/local/lib \
188        build/usr/local/bin/echo_test-shared 1
189     ```
191 ### Example to compile OpenAMP Linux Userspace for Zynq UltraScale+ MPSoC
192 We can use yocto to build the OpenAMP Linux userspace library and application.
193 * Put the libmetal yocto recipe to your yocto layer. Here is the example of
194   libmetal recipe:
195   https://github.com/Xilinx/meta-petalinux/blob/master/recipes-support/libmetal/libmetal_0.1.0.bb
196 * Put the OpenAMP yocto recipe to your yocto layer. Here is the example of
197   OpenAMP recipe:
198         ```
199         SUMMARY = "Libopen_amp : Libmetal implements an abstraction layer across user-space Linux, baremetal, and RTOS environments"
201         HOMEPAGE = "https://github.com/OpenAMP/open-amp/"
203         SECTION = "libs"
205         LICENSE = "BSD"
206         LIC_FILES_CHKSUM = "file://LICENSE;md5=b30cbe0b980e98bfd9759b1e6ba3d107"
208         # Initial tag of open-amp xilinx-v2016.3-rc2
209         SRCREV ?= "bd62dee2399aa7f2e45761f289675dade34190fc"
210         SRC_URI = "git://github.com/Xilinx/open-amp.git;protocol=https;branch=xlnx-2016.3"
212         S = "${WORKDIR}/git"
214         DEPENDS = "libmetal"
216         inherit pkgconfig cmake
218         EXTRA_OECMAKE = " \
219                 -DLIB_INSTALL_DIR=${libdir} \
220                 -DLIBEXEC_INSTALL_DIR=${libexecdir} \
221                 -DMACHINE=${SOC_FAMILY} \
222                 -DWITH_PROXY=OFF \
223                 "
225         # Only builds the library but not the applications
226         EXTRA_OECMAKE_append_zynqmp = "-DWITH_APPS=ON"
227         ```
228 * You can use yocto to build OpenAMP demo applications into your root file system.
230 ## Supported System and Machines
231 For now, it supports:
232 * Zynq generic slave
233 * Zynq UltraScale+ MPSoC R5 generic slave
234 * Linux host OpenAMP between Linux userspace processes
235 * Linux userspace OpenAMP RPMsg master
236 * Linux userspace OpenAMP RPMsg slave
238 ## Known Limitations:
239 1. OpenAMP framework supports OpenAMP firmware running as master, however,
240    the example to show this ability is not ready yet.
241 2. In case of OpenAMP on Linux userspace for inter processors communication,
242    life cycle management with remoteproc is not supported yet, that is for now,
243    it is not able to load the remote firmware with OpenAMP running on Linux
244    userspace.
245 3. In case of OpenAMP on Linux userspace for inter processors communication,
246    it only supports static vrings and shared buffers.
247 4. `sudo` is required to run the OpenAMP demos between Linux processes, as
248    it doesn't work on some systems if you are normal users.
250 For using the framework please refer to the wiki of the OpenAMP repo.
251 Subscribe to the open-amp mailing list at https://groups.google.com/group/open-amp.