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.
   6
   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.
  19
  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 ```
  40
  41 OpenAMP library libopen_amp is composed of the following directories in `lib/`:
  42 *   `common/`
  43 *   `virtio/`
  44 *   `rpmsg/`
  45 *   `remoteproc/`
  46 *   `proxy/`
  47
  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.
  51
  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
  70
  71 Please refer to `lib/system/generic` when you port libmetal for your system.
  72
  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`.
  76
  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.
  83
  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:
  87
  88     ```
  89         $ mkdir -p build-libmetal
  90         $ cd build-libmetal
  91         $ cmake <libmetal_source>
  92         $ make VERBOSE=1 DESTDIR=<libmetal_install> install
  93     ```
  94
  95 * build OpenAMP library on your host as follows:
  96
  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
 102
 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.
 108
 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:
 113
 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     ```
 129
 130   * Compile libmetal library:
 131
 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     ```
 138
 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 )
 157
 158         include (cross_generic_gcc)
 159     ```
 160
 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:
 167
 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     ```
 174
 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
 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:
 183
 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     ```
 192
 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
 203
 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
 208
 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
 216
 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.
 228
 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.