RPMsg BIOS Sources

RPMsg code is split into a host processor side and remote processor side code. While the host-side code is running as part of the Linux kernel, the remote processor/coprocessor-side code, runs on top of a RTOS, SYS/BIOS and is referred to as SYS/BIOS RPMsg. This page gives all the information about the SYS/BIOS RPMsg source code including the necessary tools information, their download and build instructions.

= Prerequisites =

Here is a list of what you need to be able to work on RPMsg:


 * A Linux PC for downloading and compiling
 * GIT tool and GIT configuration to be able to clone from the respective repository
 * BIOS-side tools, namely XDC, SYS/BIOS, ARM Code Generation Tools (Cortex M3/M4), DSP Code Generation Tools (C64x), IPC.

= SYS/BIOS Tools =

The SYS/BIOS-side source code is developed based on top of an underlying technology called Real Time Software Components (RTSC). RTSC is an open-source specification within the Eclipse.org ecosystem for providing reusable software components (called "packages") for use in embedded systems.

The SYS/BIOS RPMsg code, requires the following tools/products, in addition, to provide a proper development environment.
 * XDC - XDCtools is the actual product that contains all the tools necessary for you to use the SYS/BIOS-side components and configure your application. The RTSC-pedia web site describes RTSC and XDCtools in more detail.
 * SYS/BIOS - SYS/BIOS is an advanced real-time operating system from Texas Instruments for use in a wide range of DSPs, ARMs, and microcontrollers. It is designed for use in embedded applications that need real-time scheduling, synchronization, and instrumentation. The dedicated SYS/BIOS wiki gives out more details about the RTOS.
 * IPC - The Inter Processor Communication (IPC) product provides a utility module, MultiProc needed by SYS/BIOS RPMsg modules. It is also required for building any customized versions of SYS/BIOS.
 * TI Code Generation Tools - Code Generation Tools (CGT) is the compiler/linker used for building your target executables for the ARM Cortex M3/M4 and DSP. Different CGT tools are used for compiling code depending on the target processor. The wiki has more information about TI Compilers.

Most of the tools/products are also installed as part of Code Composer Studio (CCS), an eclipse-based IDE environment for creating, building and debugging projects. CCS is typically used for debugging purposes using a proper JTAG (XDS560v2 or a XDS100v2). Debugging using CCS and JTAGs are better explained in the Emulation wiki. The recommended version of CCS for debugging is CCSv5.1 and can be downloaded from the following download link.

In addition, there might be other Multimedia Framework Products like Codec Engine (CE), Framework Components (FC), XDAIS Algorithm Standard, OSAL, required for building an overall MM stack, but these are not essential for just SYS/BIOS RPMsg.

= Repositories = The SYS/BIOS RPMsg code is maintained in the below tree. There is a only a single branch currently that supports different products, but new branches might be created or forked off from the current branch to support multiple kernel trees/branches or products.

Product/Integration/Feature Tree

 * sysbios-rpmsg
 * Clone: git clone git://git.omapzoom.org/repo/sysbios-rpmsg.git
 * Branch: master
 * Supported Boards: OMAP4 Panda, OMAP4 SDP, OMAP4 Blaze, OMAP4 Blaze Tablet

Open Source Tree
Please look up the RPMsg Open Source page (coming soon) for details on the upstream friendly version.

= Source Files = The following are the typical directories and files associated with RPMsg on the SYS/BIOS side. Some of the files/modules may not be present in all the trees. This list only highlights the files specific to OMAP.


 * src/ti/ipc/rpmsg
 * VirtQueue.c, VirtQueue.h - BIOS-side definition and implementation of VirtIO transport API
 * MessageQCopy.c, MessageQCopy.h - Copy-based MessageQ module implementation to work with the VirtQueue.c
 * InterruptM3.c, InterruptM3.h - Lower-level interrupt-level handling code for IPC interrupts (Mailboxes, IPI) for Cortex M3/M4 processor cores.
 * InterruptDsp.c, InterruptDsp.h - Lower-level interrupt-level handling code for IPC interrupts (Mailboxes) for DSP processor core.
 * virtio.h, virtio_ring.h - Linux VirtIO Reference Headers
 * *.xdc, *.xs, *.bld - XDC package and build files


 * src/ti/grcm
 * RcmServer.c, RcmServer.h - Custom RCM Server module designed to work with MessageQCopy & VirtQueue
 * RcmUtils.c - Utility helper functions for RCM
 * RcmTypes.h - Common RCM type definitions
 * *.xdc, *.xdt, *.xs, *.bld - XDC module, package and build files, linker template files


 * src/ti/srvmgr
 * ServiceMgr.c, ServiceMgr.h - Simple Server for creating new connection end-points & also deleting them
 * NameMap.c, NameMap.h - Registration & Deregistration of new BIOS-side services on with kernel
 * omx_packet.h, rpmsg_omx.h - Definition of message types and message packet structures to work with OMX on host-side.
 * *.xdc, *.xs, *.bld - XDC package and build files


 * src/ti/resmgr
 * _IpcResource.h - Internal definitions of IPC Resource Manager that interacts with rpmsg_resmgr
 * IpcResoure.c, IpcResource.h - Types, Definition and Implementation of IPC Resource Manager API, for requesting clocks and constraints of various peripherals
 * *.xdc, *.xs, *.bld - XDC package and build files


 * src/ti/pm
 * IpcPower.c, IpcPower.h - IPC Power Management API for M3/M4 processor cores.
 * _IpcPower.h - Internal definitions needed by IpcPower module.
 * *.xdc, *.xs, *.bld - XDC package and build files


 * src/ti/deh
 * Deh.* - Device Exception Handler implementation handling exception registers dump and watchdog reconfiguration
 * *.xdc, *.xs, *.bld - XDC package and build files


 * src/ti/gates/hwspinlock
 * HwSpinlock.c, HwSpinlock.h - Definition and Implementation of HW SpinLock API
 * _HwSpinlock.h - Internal type definitions needed by HW SpinLock module
 * *.xdc, *.xs, *.bld - XDC package and build files


 * src/ti/trace
 * SysMin.* - Custom implementation of xdc.runtime.SysMin module to provide additional features such as timestamps, non-flushed circular buffer implementation
 * StackDbg.* - Utility module for debugging a Stack
 * *.xdc, *.xs, *.bld - XDC package and build files


 * src/ti/resources
 * rsc_table.h - Resource Table that has the necessary memory mapping and other important information needed by kernel for configuring a remote processor appropriately.
 * *.xdc, *.xs, *.bld - XDC package and build files


 * src/ti/platform
 * omap4430/core0/Platform.xdc - Memory Map information for Cortex M3/M4 Core0 processor, used for placing different sections of the ELF executable
 * omap4430/core1/Platform.xdc - Memory Map information for Cortex M3/M4 Core1 processor, used for placing different sections of the ELF executable
 * omap4430/dsp/Platform.xdc - Memory Map information for DSP processor, used for placing different sections of the ELF executable
 * *.xdc, *.xs, *.bld - XDC package and build files


 * src/ti/configs
 * omap4430/DucatiAmmu.cfg - AMMU Configuration File
 * omap4430/DucatiCore0.cfg - Basic core configuration settings for all IPC sample images running on Cortex M3/M4 Core0
 * omap4430/DucatiCore1.cfg - Basic core configuration settings for all IPC sample images running on Cortex M3/M4 Core1
 * omap4430/IpcCommon.cfg.xs - Basic core configuration settings for all IPC sample images that are common for both Cortex M3/M4 processor cores
 * *.xdc, *.xs, *.bld - XDC package and build files


 * src/ti/examples/srvmgr
 * test_omx.c, test_omx_core0.cfg, test_omx_core1.cfg - Basic RPMsg sample source code and configuration files, that works with rpmsg_client_sample & rpmsg_server_sample on the kernel side
 * ping_tasks.c - Core sample source code used by the test_omx
 * resmgr_task.c - Sample source code for demonstrating IPC Resource Manager usage
 * hwspinlock_task.c - Sample source code for demonstrating HW Spinlock usage
 * *.xdc, *.xs, *.bld - Other XDC package and build files


 * src/utils
 * directory containing utilities for post-processing ELF baseimages into a firmware binary, and utilites for reading basic info about the generated firmware binary


 * src/host
 * directory hosting the Linux-side sample code
 * omx_sample.c, omx_sample.h - Simple sample showcasing messaging on top of rpmsg-omx
 * omx_benchmark.c - Sample used for timing measurements.

= Build Instructions =

Download
All the required tools, except for ARM Code Generation Tools, are available for download publicly.


 * XDCTools can be downloaded from this page. Version currently used is XDC 3.22.03.41
 * SYS/BIOS can be downloaded from here. Version currently used is BIOS 6.32.01.38
 * IPC can be downloaded from here. Version currently used is IPC 1.23.01.26
 * Compilers for C64x can be downloaded from here. Please contact your TI Representative for ARM Compiler.
 * Other MFP tools needed for building MultiMedia code can be downloaded from the below links. Please use the versions as recommended by the corresponding MM release.
 * Codec Engine
 * Framework Components
 * OSAL
 * XDAIS

Note:
 * Download of some of these tools may require a my.TI registration account.
 * Unless otherwise specified, it is recommended to pick the XDCTools and IPC as per the versions mentioned in the SYS/BIOS download page.

Installation

 * It is recommended that all tools are installed in the same path. This would make it easier for any build scripting, as well as identifying the tools in CCS.
 * XDC, SYS/BIOS, IPC and CGT are packaged as installers. Make sure these downloaded installers are marked with executable permissions. To install, simply execute the binary files for installation.
 * The tools can be installed either as root (using sudo) or as a normal user. The default location varies based on whether the tools are installed as root (/usr/local) or normal user (home directory). The tools can be installed in any desired path.
 * MFP tools are packaged as tarballs. Please untar them in the same folder as the other tools. (Optional step, required for MM)

Build
The README file in the sysbios-rpmsg tree gives the detailed instructions for the build. The below gives out additional information not mentioned in the README.

/usr/local/xdctools_3_22_03_41 /usr/local/bios_6_32_01_38 /usr/local/ipc_1_23_01_26 /opt/TI/TMS470CGT4.9.0 /opt/TI/C6000CGT7.2.0 bash$ export TMS470CGTOOLPATH=/data/bios-tools/cgtarm-4.9.0 bash$ export C6000CGTOOLPATH=/data/bios-tools/cgt6x-7.2.0 bash$ export BIOSTOOLSROOT=/data/bios-tools bash$ export XDCVERSION=xdctools_3_22_01_21 bash$ make tools REPO := /data/bios-tools XDC := /data/bios-tools/xdctools_3_22_01_21 BIOS := /data/bios-tools/bios_6_32_01_38 IPC := /data/bios-tools/ipc_1_23_01_26 bash$ make /src/ti/examples/srvmgr/ti_platform_omap4430_core0/debug/test_omx_sysm3.xem3 /src/ti/examples/srvmgr/ti_platform_omap4430_core1/debug/test_omx_appm3.xem3
 * The following are the default installations assumed (installed as root) by SYS/BIOS RPMsg code. If the tools are installed as follows, then there is no need of setting any environment variables, and one can proceed directly to invoking the build.
 * If your installation paths do not match the above default locations, please refer to the above README file to customize by exporting the proper environment variables - TMS470CGTOOLPATH, C6000CGTOOLPATH for CGT, BIOSTOOLSROOT for the tools parent directory, and optionally XDCVERSION for a different XDC tools. It is assumed that only the install directory is customized, but not the actual tools name. Multiple versions of a single tool can co-exist simultaneously, and therefore it is not at all recommended to change the tools name.
 * The build environment settings can be inspected by using make tools or make info at the root of sysbios-rpmsg directory. Following is an example with some customizations:
 * From the top-level sysbios-rpmsg directory, type in 'make' to build the entire tree plus sample applications
 * A default firmware binary, ducati-m3.bin is generated in the /src/utils directory, using two of the sample baseimages in sysbios-rpmsg tree. The ducati-m3.bin is generated by post-processing two ELF baseimages. The two images used are

= SYS/BIOS RPMsg Customizations =

Building custom ducati-m3.bin
The RPMsg kernel driver expects to find the firmware binary by the exact file name, ducati-m3.bin. This file is loaded into the M3 processor cores. A basic ducati-m3.bin is generated by default when SYS/BIOS RPMsg is built.

To produce your own firmware binary, use the genrprc utility found in the /src/utils directory. It is a script file typically invoked from within the src/utils directory.

bash$ ./genrprc my-custom-ducati-m3.bin or bash$ /src/utils/genrprc my-custom-ducati-m3.bin

A firmware binary is generated from the individual ELF executables of the remote cores, e.g. the .xem3 files. The genrprc utility adds version information by walking down the directory paths from where the executable are located. As such, it is strongly recommended to not relocate the exectables prior to running genrprc.

For proper execution of the custom binary, it always needs to be copied as ducati-m3.bin to the required file system path, typically /lib/firmware for generic Linux.

See also the readrprc utility for getting information back from a ducati firmware binary.

System Trace Buffer
A trace buffer exists in shared memory to make system traces available to the HLOS. A SYS/BIOS application will fill the buffer through the System_printf function. The buffer is provided by ti.trace.SysMin module which supports a configurable size, however the size must be coordinated with the Platform configuration. The buffer size can be changed from /src/ti/config/IpcCommon.cfg.xs.

/* *  The SysMin used here vs StdMin, as trace buffer address is required for * Linux trace debug driver, plus provides better performance. */ var System     = xdc.useModule('xdc.runtime.System'); var SysMin     = xdc.useModule('ti.trace.SysMin'); System.SupportProxy = SysMin; SysMin.bufSize = 0x8000;

Module Logs
Several modules have configurable logs in RPMsg. Logs from these modules can be enabled in /src/ti/config/IpcCommon.cfg.xs.

For messaging, change the occurrences of Diags.RUNTIME_OFF to Diags.RUNTIME_ON. The modules affected by these settings are ti.grcm.RcmServer, ti.grcm.RcmClient and ti.ipc.rpmsg.MessageQCopy.

/* Enable runtime Diags_setMask for non-XDC spec'd modules: */ var Text = xdc.useModule('xdc.runtime.Text'); Text.isLoaded = true; var Registry = xdc.useModule('xdc.runtime.Registry'); Registry.common$.diags_ENTRY = Diags.RUNTIME_ON; Registry.common$.diags_EXIT = Diags.RUNTIME_ON; Registry.common$.diags_INFO = Diags.RUNTIME_ON; Registry.common$.diags_LIFECYCLE = Diags.RUNTIME_ON; Registry.common$.diags_STATUS = Diags.RUNTIME_ON; Diags.setMaskEnabled = true;

For Hibernation logs, add a line to enable INFO level logging for the Main module.

var Main = xdc.useModule('xdc.runtime.Main'); Main.common$.diags_ASSERT = Diags.ALWAYS_ON; Main.common$.diags_INTERNAL = Diags.ALWAYS_ON; Main.common$.diags_INFO = Diags.RUNTIME_ON;

Refer to xdc.runtime.Diags documentation for more information about diagnostic categories.

WFI Idle & Hibernation
The ti.pm module enables hibernation and WFI idle on the M3/M4 cores. It may be desirable to disable these features from the firmware. To disable WFI and hibernation, remove the IpcPower_idle callback from the Idle Task functions list. This configuration is found in /src/ti/config/IpcCommon.cfg.xs.

xdc.loadPackage('ti.pm'); //Idle.addFunc('&IpcPower_idle');       /* IpcPower_idle must be at the end */

Without WFI, the Idle task will essentially perform a "busy wait", and running the list of Idle functions in a loop.

Hibernation of the M3/M4 cores is controlled from the Linux kernel and depends on the cores using WFI. Disabling WFI will have a similar effect to disabling hibernation form the kernel via the "Autosuspend support for remoteproc" config option. However, disabling autosuspend in Linux will not prevent WFI idle.

Source Timer
The SYS/BIOS system clock can be configured to use different underlying timers. The timer can be switched between the NVIC SysTick timer of each individual M3/M4 core or a GP timer. Do note that the below is provided for reference only and is NOT recommended on OMAP-based products. The Power Management and Watchdog features cannot be possible using the internal timers.

To use the SysTick timer, the following GP Timer configuration needs to be removed. In /src/ti/config/IpcCommon.cfg.xs remove the TimerProxy override.

/* Override the internal sysTick timer with dmTimer for Bios Timer */ //var halTimer = xdc.useModule('ti.sysbios.hal.Timer'); //halTimer.TimerProxy = dmTimer;

In /src/ti/config/ducatiCore0.cfg and /src/ti/config/ducatiCore1.cfg remove the Clock and Timer configuration.

/* - TICK ---*/ //var Clock = xdc.useModule('ti.sysbios.knl.Clock'); //Clock.tickSource = Clock.TickSource_USER; /* Configure GPTimer3 as BIOS clock source */ //Clock.timerId = 0; //var Timer = xdc.useModule('ti.sysbios.timers.dmtimer.Timer'); //var timerParams = new Timer.Params; //timerParams.period = Clock.tickPeriod; //timerParams.periodType = Timer.PeriodType_MICROSECS; /* Smart-idle wake-up-capable mode */ //timerParams.tiocpCfg.idlemode = 0x3; /* Wake-up generation for Overflow */ //timerParams.twer.ovf_wup_ena = 0x1; //Timer.create(Clock.timerId, Clock.doTick, timerParams);

Also disable "OMAP remoteproc watchdog timer" in the Linux kernel configuration.

Tick Period
The period of the BIOS system clock defaults to 1000&mu;s. This can be changed to another value. In /src/ti/config/ducatiCore0.cfg and /src/ti/config/ducatiCore1.cfg change the value of timerParams.period.

var timerParams = new Timer.Params; timerParams.period = 2000; timerParams.periodType = Timer.PeriodType_MICROSECS;

Be aware that changing the system clock period may have unintended consequences on other functionality. Timeout functions in application code is usually mentioned in terms of ticks, so it may caused unwanted additional delays if your application doesn't take into affect the Clock tickPeriod.