Update README for the OpenAMP on top of libmetal
authorWendy Liang <jliang@xilinx.com>
Mon, 17 Oct 2016 21:00:37 +0000 (14:00 -0700)
committerWendy Liang <jliang@xilinx.com>
Mon, 17 Oct 2016 23:17:23 +0000 (16:17 -0700)
Update the README file for the structure and the compilation basic
instructions for OpenAMP on top of libmetal.

Signed-off-by: Wendy Liang <jliang@xilinx.com>
README.md

index 3910ba580e1b9a95dc30c55518d880a424a65927..6704b014443c21ef402d6f215e4499b2e9b60a5f 100644 (file)
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ enable development of software applications for Asymmetric Multiprocessing
 
 1. Provides Life Cycle Management, and Inter Processor Communication
    capabilities for management of remote compute resources and their associated
 
 1. Provides Life Cycle Management, and Inter Processor Communication
    capabilities for management of remote compute resources and their associated
-   software contexts
+   software contexts.
 2. Provides a stand alone library usable with RTOS and Baremetal software
    environments
 3. Compatibility with upstream Linux remoteproc and rpmsg components
 2. Provides a stand alone library usable with RTOS and Baremetal software
    environments
 3. Compatibility with upstream Linux remoteproc and rpmsg components
@@ -21,22 +21,16 @@ enable development of software applications for Asymmetric Multiprocessing
 ```
 |- lib/
 |  |- common/     # common helper functions
 ```
 |- lib/
 |  |- common/     # common helper functions
-|  |- virtio/     # virtio implemnetation
+|  |- virtio/     # virtio implementation
 |  |- rpmsg/      # rpmsg implementation
 |  |- remoteproc/ # remoteproc implementation
 |  |  |- drivers  # remoteproc drivers
 |  |- proxy/      # implement one processor access device on the
 |  |              # other processor with file operations
 |  |- rpmsg/      # rpmsg implementation
 |  |- remoteproc/ # remoteproc implementation
 |  |  |- drivers  # remoteproc drivers
 |  |- proxy/      # implement one processor access device on the
 |  |              # other processor with file operations
-|  |- system/     # os specific implementation
-|  |  |  |- generic/ # E.g. generic system (that is baremetal)
-|  |  |  |  |- machine/ # machine specific implmentation for the system
-|  |- include/     # header files
-|  |  |- machine/ # machine specific header files
-|  |  |- system/  # system specific header files
-|- apps/        # demontrastion/testing applicaitons
+|- apps/        # demonstration/testing applications
 |  |- machine/  # common files for machine can be shared by applications
 |               # It is up to each app to decide whether to use these files.
 |  |- machine/  # common files for machine can be shared by applications
 |               # It is up to each app to decide whether to use these files.
-|  |- system/   # common files for system can be shared by applicaitons
+|  |- system/   # common files for system can be shared by applications
 |               # It is up to each app to decide whether to use these files.
 |- obsolete     # It is used to build libs which may also required when
 |               # building the apps. It will be removed in future since
 |               # It is up to each app to decide whether to use these files.
 |- obsolete     # It is used to build libs which may also required when
 |               # building the apps. It will be removed in future since
@@ -44,52 +38,214 @@ enable development of software applications for Asymmetric Multiprocessing
 |- cmake        # CMake files
 ```
 
 |- cmake        # CMake files
 ```
 
-OpenAMP library libopen_amp is composed of the following directorys in `lib/`:
+OpenAMP library libopen_amp is composed of the following directories in `lib/`:
 *   `common/`
 *   `virtio/`
 *   `rpmsg/`
 *   `remoteproc/`
 *   `proxy/`
 *   `common/`
 *   `virtio/`
 *   `rpmsg/`
 *   `remoteproc/`
 *   `proxy/`
-*   `system/`
+
+OpenAMP system/machine support has been moved to libmetal, the system/machine
+layer in the `apps/` directory is for system application initialization, and
+resource table definition.
+
+### libmetal APIs used in OpenAMP
+Here are the libmetal APIs used by OpenAMP, if you want to port OpenAMP for your
+system, you will need to implement the following libmetal APIs in the libmetal's
+`lib/system/<SYS>` directory:
+* alloc, for memory allocation and memory free
+* cache, for flushing cache and invalidating cache
+* io, for memory mapping. OpenAMP required memory mapping in order to access
+  vrings and carved out memory.
+* irq, for IRQ handler registration, IRQ disable/enable and global IRQ handling.
+* mutex
+* shmem (For RTOS, you can usually use the implementation from
+  `lib/system/generic/`)
+* sleep, at the moment, OpenAMP only requires microseconds sleep as when OpenAMP
+  fails to get a buffer to send messages, it will call this function to sleep and
+  then try again.
+* time, for timestamp
+* init, for libmetal initialization.
+* atomic
+
+Please refer to `lib/system/generic` when you port libmetal for your system.
+
+If you a different compiler to GNU gcc, please refer to `lib/compiler/gcc/` to
+port libmetal for your compiler. At the moment, OpenAMP needs the atomic
+operations defined in `lib/compiler/gcc/atomic.h`.
 
 ## OpenAMP Compilation
 
 ## OpenAMP Compilation
-OpenAMP uses CMake for library and demonstration applicaiton compilation.
+OpenAMP uses CMake for library and demonstration application compilation.
+OpenAMP requires libmetal library. For now, you will need to download and
+compile libmetal library separately before you compiling OpenAMP library.
+In future, we will try to make libmetal as a submodule to OpenAMP to make this
+flow easier.
 
 
-###  Example to compile Zynq MP SoC R5 generic(baremetal) remote:
-```
-$ mkdir build
-$ cd build/
-$ cmake ../open-amp -DCMAKE_TOOLCHAIN_FILE=zynqmp_r5_generic -DWITH_OBSOLETE=ON -DWITH_APPS=ON
-$ make DESTDIR=$(pwd) install
-```
-The OpenAMP library will be generated to `build/usr/local/lib` directory, headers will be generated to
-`build/usr/local/include` directory, and the applications executables will be generated to
-`build/usr/local/bin` directory.
+### Example to compile OpenAMP for communication between Linux processes:
+* Install libsysfs devel and libhugetlbfs devel packages on your Linux host.
+* build libmetal library on your host as follows:
 
 
-*   `-DWITH_OBSOLETE=ON` is to build the `libxil.a`.
-*   `-DWITH_APPS=ON` is to build the demonstration applications.
+    ```
+        $ mkdir -p build-libmetal
+        $ cd build-libmetal
+        $ cmake <libmetal_source>
+        $ make VERBOSE=1 DESTDIR=<libmetal_install> install
+    ```
 
 
-###  Example to compile Zynq A9 remote:
-```
-$ mkdir build
-$ cd build/
-$ cmake ../open-amp -DCMAKE_TOOLCHAIN_FILE=zynq7_generic -DWITH_OBSOLETE=on -DWITH_APPS=ON
-$ make DESTDIR=$(pwd) install
-```
+* build OpenAMP library on your host as follows:
+
+        $ mkdir -p build-openamp
+        $ cd build-openamp
+        $ cmake <openamp_source> -DCMAKE_INCLUDE_PATH=<libmetal_built_include_dir> \
+              -DCMAKE_LIBRARY_PATH=<libmetal_built_lib_dir> [-DWITH_APPS=ON]
+        $ make VERBOSE=1 DESTDIR=$(pwd) install
+
+The OpenAMP library will be generated to `build/usr/local/lib` directory,
+headers will be generated to `build/usr/local/include` directory, and the
+applications executable will be generated to `build/usr/local/bin`
+directory.
+* cmake option `-DWITH_APPS=ON` is to build the demonstration applications.
+
+###  Example to compile Zynq UltraScale+ MPSoC R5 generic(baremetal) remote:
+* build libmetal library on your host as follows:
+  * Create your on cmake toolchain file to compile libmetal for your generic
+    (baremetal) platform. Here is the example of the toolchain file:
+
+    ```
+        set (CMAKE_SYSTEM_PROCESSOR "arm"              CACHE STRING "")
+        set (MACHINE "zynqmp_r5" CACHE STRING "")
+        
+        set (CROSS_PREFIX           "armr5-none-eabi-" CACHE STRING "")
+        set (CMAKE_C_FLAGS          "-mfloat-abi=soft -mcpu=cortex-r5 -Wall -Werror -Wextra \
+           -flto -Os -I/ws/xsdk/r5_0_bsp/psu_cortexr5_0/include" CACHE STRING "")
+        
+        SET(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -flto")
+        SET(CMAKE_AR  "gcc-ar" CACHE STRING "")
+        SET(CMAKE_C_ARCHIVE_CREATE "<CMAKE_AR> qcs <TARGET> <LINK_FLAGS> <OBJECTS>")
+        SET(CMAKE_C_ARCHIVE_FINISH   true)
+        
+        include (cross-generic-gcc)
+    ```
+
+  * Compile libmetal library:
+
+    ```
+        $ mkdir -p build-libmetal
+        $ cd build-libmetal
+        $ cmake <libmetal_source> -DCMAKE_TOOLCHAIN_FILE=<toolchain_file>
+        $ make VERBOSE=1 DESTDIR=<libmetal_install> install
+    ```
+
+* build OpenAMP library on your host as follows:
+  * Create your on cmake toolchain file to compile openamp for your generic
+    (baremetal) platform. Here is the example of the toolchain file:
+    ```
+        set (CMAKE_SYSTEM_PROCESSOR "arm" CACHE STRING "")
+        set (MACHINE                "zynqmp_r5" CACHE STRING "")
+        set (CROSS_PREFIX           "armr5-none-eabi-" CACHE STRING "")
+        set (CMAKE_C_FLAGS          "-mfloat-abi=soft -mcpu=cortex-r5 -Os -flto \
+          -I/ws/libmetal-r5-generic/usr/local/include \
+          -I/ws/xsdk/r5_0_bsp/psu_cortexr5_0/include" CACHE STRING "")
+        set (CMAKE_ASM_FLAGS        "-mfloat-abi=soft -mcpu=cortex-r5" CACHE STRING "")
+        set (PLATFORM_LIB_DEPS      "-lxil -lc -lm" CACHE STRING "")
+        SET(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -flto")
+        SET(CMAKE_AR  "gcc-ar" CACHE STRING "")
+        SET(CMAKE_C_ARCHIVE_CREATE "<CMAKE_AR> qcs <TARGET> <LINK_FLAGS> <OBJECTS>")
+        SET(CMAKE_C_ARCHIVE_FINISH   true)
+        set (CMAKE_FIND_ROOT_PATH /ws/libmetal-r5-generic/usr/local/lib \
+            /ws/xsdk/r5_bsp/psu_cortexr5_0/lib )
+
+        include (cross_generic_gcc)
+    ```
+
+  * We use cmake `find_path` and `find_library` to check if libmetal includes
+    and libmetal library is in the includes and library search paths. However,
+    for non-linux system, it doesn't work with `CMAKE_INCLUDE_PATH` and
+    `CMAKE_LIBRARY_PATH` variables, and thus, we need to specify those paths
+    in the toolchain file with `CMAKE_C_FLAGS` and `CMAKE_FIND_ROOT_PATH`.
+* Compile the OpenAMP library:
+
+    ```
+    $ mkdir -p build-openamp
+    $ cd build-openamp
+    $ cmake <openamp_source> -DCMAKE_TOOLCHAIN_FILE=<toolchain_file>
+    $ make VERBOSE=1 DESTDIR=$(pwd) install
+    ```
+
+The OpenAMP library will be generated to `build/usr/local/lib` directory,
+headers will be generated to `build/usr/local/include` directory, and the
+applications executable will be generated to `build/usr/local/bin`
+directory.
+* `-DWITH_APPS=ON` is to build the demonstration applications.
+  If you have used `-DWITH_APPS=ON` to build the demos, you can try them on
+  your Linux host as follows:
+    ```
+    # Start echo test server to wait for message to echo
+    $ sudo LD_LIBRARY_PATH=<openamp_built>/usr/local/lib:<libmetal_built>/usr/local/lib \
+       build/usr/local/bin/echo_testd-shared
+    # Run echo test to send message to echo test server
+    $ sudo LD_LIBRARY_PATH=<openamp_built>/usr/local/lib:<libmetal_built>/usr/local/lib \
+       build/usr/local/bin/echo_test-shared 1
+    ```
+
+### Example to compile OpenAMP Linux Userspace for Zynq UltraScale+ MPSoC
+We can use yocto to build the OpenAMP Linux userspace library and application.
+* Put the libmetal yocto recipe to your yocto layer. Here is the example of
+  libmetal recipe:
+  https://github.com/Xilinx/meta-petalinux/blob/master/recipes-support/libmetal/libmetal_0.1.0.bb
+* Put the OpenAMP yocto recipe to your yocto layer. Here is the example of
+  OpenAMP recipe:
+        ```
+        SUMMARY = "Libopen_amp : Libmetal implements an abstraction layer across user-space Linux, baremetal, and RTOS environments"
+
+        HOMEPAGE = "https://github.com/OpenAMP/open-amp/"
+
+        SECTION = "libs"
+
+        LICENSE = "BSD"
+        LIC_FILES_CHKSUM = "file://LICENSE;md5=b30cbe0b980e98bfd9759b1e6ba3d107"
+
+        # Initial tag of open-amp xilinx-v2016.3-rc2
+        SRCREV ?= "bd62dee2399aa7f2e45761f289675dade34190fc"
+        SRC_URI = "git://github.com/Xilinx/open-amp.git;protocol=https;branch=xlnx-2016.3"
+
+        S = "${WORKDIR}/git"
+
+        DEPENDS = "libmetal"
+
+        inherit pkgconfig cmake
+
+        EXTRA_OECMAKE = " \
+               -DLIB_INSTALL_DIR=${libdir} \
+               -DLIBEXEC_INSTALL_DIR=${libexecdir} \
+               -DMACHINE=${SOC_FAMILY} \
+               -DWITH_PROXY=OFF \
+               "
+
+        # Only builds the library but not the applications
+        EXTRA_OECMAKE_append_zynqmp = "-DWITH_APPS=ON"
+        ```
+* You can use yocto to build OpenAMP demo applications into your root file system.
 
 ## Supported System and Machines
 For now, it supports:
 * Zynq generic slave
 
 ## Supported System and Machines
 For now, it supports:
 * Zynq generic slave
-* Zynq generic master
-* ZynqMP R5 generic slave
+* Zynq UltraScale+ MPSoC R5 generic slave
+* Linux host OpenAMP between Linux userspace processes
+* Linux userspace OpenAMP RPMsg master
+* Linux userspace OpenAMP RPMsg slave
 
 ## Known Limitations:
 
 ## Known Limitations:
-1. In rpc_demo.c(the remote demonstration application that showcases usage of
-   rpmsg retargetting infrastructure),  the bindings for the flag input
-   parameter in open() system call has been redefined. The GCC tool library
-   bindings for this input argument is different between arm-xilinx/none-eabi, and
-   arm-linux-eabi toolchains. For this reason, redefinition is required for
-   compatibility with proxy on Linux master.
-
-For using the framework please refer to the documents present in the /docs folder.
+1. OpenAMP framework supports OpenAMP firmware running as master, however,
+   the example to show this ability is not ready yet.
+2. In case of OpenAMP on Linux userspace for inter processors communication,
+   life cycle management with remoteproc is not supported yet, that is for now,
+   it is not able to load the remote firmware with OpenAMP running on Linux
+   userspace.
+3. In case of OpenAMP on Linux userspace for inter processors communication,
+   it only supports static vrings and shared buffers.
+4. `sudo` is required to run the OpenAMP demos between Linux processes, as
+   it doesn't work on some systems if you are normal users.
+
+For using the framework please refer to the wiki of the OpenAMP repo.
 Subscribe to the open-amp mailing list at https://groups.google.com/group/open-amp.
 Subscribe to the open-amp mailing list at https://groups.google.com/group/open-amp.