SysLink Install Guide - 2.00 and 2.10

Introduction

This SysLink Install Guide provides basic information on how to get started with the SysLink product. It contains the necessary steps on how to install and build SysLink, its dependencies (where relevant), and the SysLink sample applications. Information on how install (on the devices target file-system) and run the SysLink sample applications provided is also included.

See the SysLink Release Notes included in the product for details about devices and component versions supported in each SysLink release. This Install Guide is appropriate for the SysLink 2.00.* and 2.10.* releases. (Newer releases should refer to SysLink Install Guide - note the lack of version in that article title).

The SysLink product consistent of three main components for any supported device:

1. Master core driver (executable) that is running a high-level OS (HLOS GPP driver)
2. Master core user level libraries (HLOS GPP libraries)
3. Slave core(s) user level libraries that is running a Real-time OS (RTOS slave libraries).

SysLink applications are typically written to interface with the GPP libraries interface on the master core and the slave libraries on the slave core(s). See the SysLink User's Guide for more information.

Install

Basic installation

SysLink is released as a tar.gz file. To install, simply extract the file.

buildhost$ tar -xzvf syslink_<version>.tar.gz -C /home/user

This will extract the SysLink product in a directory with its product name and version information (e.g. /home/user/syslink_2_xx_xx_xx)

Note:

• This document assumes the install path to be the user's home directory on a Linux host machine. This path (/home/user) will be used throughout the document. If SysLink was installed at a different location, make appropriate changes to the commands.
• QNX users: if you use a Windows build host machine, simply use your favorite program (e.g. Winzip) to uncompress the tar.gz file into a directory of your choice (e.g. C:\ti) instead of /home/user
• Some customers find value in archiving the released sources in a configuration management system. This can help in identifying any changes made to the original sources - often useful when updating to newer releases.

Dependencies

The dependencies applicable to each device can be found in the SysLink Release Notes provided in the product.

Build

The SysLink product provides a top level GNU makefile to allow users to easily build the various component modules and sample applications for the supported devices. GNU make version 3.81 or greater is required. The XDC tools (provided with most SDKs and CCS distributions) includes a pre-compiled version of GNU make 3.81 in $(XDC_INSTALL_DIR)/gmake.

Note: SysLink 2.10.* build goals changed from underscores "_" to dashes "-" to keep consistency across other product/component distributions (e.g. "make syslink-hlos")

Setup

The SysLink install directory (/home/user/syslink_2_xx_xx_xx) contains a file (products.mak) that specifies the necessary paths and options to build the SysLink for a specific device.

• Edit products.mak and Save.

• Set the DEVICE variable to a supported device.
• Configure the various build #Options to build SysLink - (GPPOS, EXEC_DIR, etc.).
• Set the required device paths to the device's dependent components and tools - (IPC_INSTALL_DIR, BIOS_INSTALL_DIR, etc.).

You can issue the .show-products goal to print your settings.

buildhost$ make .show-products  

Options

This section contains a descriptions of the various SysLink options exposed to the user through the top level GNU makefile in the products.mak file.

• DEVICE - Device to be built for.
• GPPOS - Set the devices master core(GPP) OS type.
• SysLink GPP driver build options

• SYSLINK_TRACE_ENABLE - SysLink provides a mechanism to enable or disable different levels of trace prints on both the kernel and user side.
• SYSLINK_BUILD_DEBUG - SysLink also has a mechanism to display assertion prints when an unexpected condition is seen.
• SYSLINK_BUILD_OPTIMIZE - SysLink provides a mechanism to substantially optimize the SysLink code through a compile option by removing checks for error conditions, invalid parameter checks and intermediate failures.

See the SysLink User's Guide for a complete description on these build settings.

• SDK - Set SDK type when building for a device that is supported by TI's SDK development kits or NONE.
• EXEC_DIR - Set the base directory for the SysLink kernel module and samples application to be installed to for running on the devices target file-system.
• LOADER - Optional - The loader type needed to load the slave (DSP, M3, etc.) executable (default in bold).

• TI816X (ELF)
• TI814X (ELF)
• OMAP3530 (COFF or ELF)
• OMAP-L138 (COFF or ELF)

• TI81XXDSP_DMTIMER_FREQ - This must match the frequency of the Dmtimer (applies to TI81XX only). Common values are 32768 or 20000000.

Linux and Qnx

Build SysLink Driver and Libraries

To build the SysLink GPP driver, GPP (HLOS) user libraries and slave (RTOS) libraries, issue the following command in the SysLink install directory:

buildhost$ make syslink

The user can individually build the driver and libraries by issuing the following commands:

buildhost$ make syslink-driver
buildhost$ make syslink-hlos
buildhost$ make syslink-rtos

The user can over-ride or bypass the products.mak file to build the driver and libraries as follows:

buildhost$ make DEVICE=TI816X \
           GPPOS=Linux \
           LOADER=ELF \
           SDK=EZSDK \
           SYSLINK_INSTALL_DIR=/home/user/syslink_x_xx_xx_xx \
           IPC_INSTALL_DIR=/home/user/ipc_x_xx_xx_xx \
           BIOS_INSTALL_DIR=/home/user/bios_x_xx_xx_xx \
           XDC_INSTALL_DIR=/home/user/xdctools_x_xx_xx_xx \
           LINUXKERNEL=/home/user/TI816X-LINUX-PSP-xx.xx.xx.xx/src/kernel/linux-xx.xx.xx.xx \
           CGT_ARM_INSTALL_DIR=/home/user/arm/arm-xxxxqx-xxx \
           CGT_ARM_PREFIX=/home/user/arm/arm-xxxxqx-xxx/bin/arm-none-linux-gnueabi- \
           CGT_C674_ELF_INSTALL_DIR=/home/user/c6x/x.x.x/ \
           syslink

Build SysLink Sample Applications

To build the SysLink GPP and slave sample applications, issue the following command in the SysLink install directory:

buildhost$ make samples

The user can separately build the GPP or the slave sample applications by issuing the following:

buildhost$ make samples-hlos
buildhost$ make samples-rtos

The user can over-ride or bypass the products.mak file to build the sample applications as follows:

buildhost$ make DEVICE=TI816X \
           GPPOS=Linux \
           LOADER=ELF \
           SDK=EZSDK \
           SYSLINK_INSTALL_DIR=/home/user/syslink_x_xx_xx_xx \
           IPC_INSTALL_DIR=/home/user/ipc_x_xx_xx_xx \
           BIOS_INSTALL_DIR=/home/user/bios_x_xx_xx_xx \
           XDC_INSTALL_DIR=/home/user/xdctools_x_xx_xx_xx \
           LINUXKERNEL=/home/user/TI816X-LINUX-PSP-xx.xx.xx.xx/src/kernel/linux-xx.xx.xx.xx \
           CGT_ARM_INSTALL_DIR=/home/user/arm/arm-xxxxqx-xxx \
           CGT_ARM_PREFIX=/home/user/arm/arm-xxxxqx-xxx/bin/arm-none-linux-gnueabi- \
           CGT_C674_ELF_INSTALL_DIR=/home/user/c6x/x.x.x/ \
           samples

SysBios

Build SysLink Libraries and Utilities

To build SysLink to run SysBios(BIOS) on all cores on a TI814X device, issue the following command in the SysLink install directory:

buildhost$ make syslink-rtos

The user can over-ride or bypass the products.mak file to build the libraries and and utilities as follows:

buildhost$ make DEVICE=TI814X \
           GPPOS=Bios \
           LOADER=ELF \
           SDK=NONE \
           SYSLINK_INSTALL_DIR=/home/user/syslink_x_xx_xx_xx \
           IPC_INSTALL_DIR=/home/user/ipc_x_xx_xx_xx \
           BIOS_INSTALL_DIR=/home/user/bios_x_xx_xx_xx \
           XDC_INSTALL_DIR=/home/user/xdctools_x_xx_xx_xx \
           CGT_C674_ELF_INSTALL_DIR=/home/user/c6x/x.x.x/ \
           CGT_M3_ELF_INSTALL_DIR=/home/user/arm/x.x.x/ \
           CGT_A8_ELF_INSTALL_DIR=/home/user/arm/x.x.x/ \
           syslink-rtos

Build SysLink Sample Applications

To build the SysLink GPP (A8) and slave sample applications all running SysBios(Bios), issue the following command in the SysLink install directory:

buildhost$ make samples-rtos

The user can over-ride or bypass the products.mak file to build the sample applications as follows:

buildhost$ make DEVICE=TI814X \
           GPPOS=Linux \
           LOADER=ELF \
           SDK=NONE \
           SYSLINK_INSTALL_DIR=/home/user/syslink_x_xx_xx_xx \
           IPC_INSTALL_DIR=/home/user/ipc_x_xx_xx_xx \
           BIOS_INSTALL_DIR=/home/user/bios_x_xx_xx_xx \
           XDC_INSTALL_DIR=/home/user/xdctools_x_xx_xx_xx \
           CGT_C674_ELF_INSTALL_DIR=/home/user/c6x/x.x.x/ \
           CGT_M3_ELF_INSTALL_DIR=/home/user/arm/x.x.x/ \
           CGT_A8_ELF_INSTALL_DIR=/home/user/arm/x.x.x/ \
           samples-rtos

Run

The SysLink makefiles provide a simple way to install (copy) the necessary SysLink executables (e.g. HLOS driver), examples and helper scripts onto the device's target file-system to simplify the execution of the applications. The details can vary across OS's, so this description has been separated into OS-specific sections.

Linux

Configuring Kernel Parameters

SysLink requires a few specific arguments to be passed to the Linux kernel during boot up. To run the sample applications, 3MB of memory is needed by SysLink for communication between GPP and slave(s), and for slave(s) external memory usage to place its code/data sections. This must be reserved by specifying 3MB less of available memory for Linux kernel usage.

• For example, with available memory of 256M, memory required for shared regions/other utils is 5M and SysLink is 3M leaving only 248M for the Linux kernel.

bootargs console=ttyS2,115200n8 root=/dev/nfs nfsroot=HOST:nfs_root,nolock rw mem=248M ip=dhcp

This is just an example, bootargs may vary depending on available setup
Depending on the memory map used in the final system configuration, the memory to be reserved for Linux kernel usage may differ.

Installing Sample Applications on Target File-system

To install(copy) the SysLink GPP driver and sample applications on the device's file-system, issue the following command in the SysLink install directory:

buildhost$ make install

• The sample applications will be installed in the EXEC_DIR directory set in the products.mak file or set when issuing the install goal.

buildhost$ make install EXEC_DIR=/home/user/ti816x/filesystem

The user can individually install(copy) the SysLink GPP driver and sample applications by issuing the following commands separately:

buildhost$ make install-driver
buildhost$ make install-samples

The user can over-ride or bypass the products.mak file to install(copy) the sample applications as follows:

buildhost$ make DEVICE=TI816X \
           GPPOS=Linux \
           SDK=EZSDK \
           SYSLINK_INSTALL_DIR=/home/user/syslink_x_xx_xx_xx \
           LINUXKERNEL=/home/user/TI816X-LINUX-PSP-xx.xx.xx.xx/src/kernel/linux-xx.xx.xx.xx \
           EXEC_DIR=/home/user/ti816x/filesystem \
           install

SysLink Kernel Driver

The SysLink kernel driver must be inserted into the kernel for SysLink user applications to run.

Loading module

The kernel module is located in the /lib/modules/<kernel_version>/kernel/drivers/dsp directory on the device's target file-system if the EXEC_DIR path in products.mak was set to the root of the device's target file-system.

If the SysLink GPP driver is built with trace enabled, the driver needs to enable both TRACE and TRACEFAILURE to configure SysLink to print out kernel messages in case any failures occur during SysLink user application runs. To load the module issue the following command on the target file-system:

target# insmod /lib/modules/<kernel_version>/kernel/drivers/dsp/syslink.ko TRACE=1 TRACEFAILURE=1

Unloading module

The kernel module can be unloaded by issuing the following command on the target file-system:

target# rmmod syslink

Running Sample Applications

This section describes the different methods to execute the sample applications provided with SysLink that demonstrate various usages and functionality.

The samples application can be run using one of two methods:

1. Use the slaveloader application to individually load, start and stop the slave core prior to executing the GPP sample application. (Refer to #Running_sample_applications_with_slaveloader for more details)
2. Use the SysLink GPP-side user sample application arguments support to load, start and stop the slave code (Refer to #Running_sample_applications_with_arguments for more details)

Setting both the TRACE and TRACEFAILURE environment variables on the user side allows any user side failures to be printed out. To enable this feature, export the variables as follows:

target# export TRACE=1
target# export TRACEFAILURE=1

In each of the sample applications directory, scripts are provided that illustrate both methods of executing the same application.

To run the messageq sample on the target file-system in debug mode:

target# cd /ti/syslink-examples/<device>/messageq
target# ./run_messageqapp_debug.sh

To run the messageq sample on the target file-system in release mode:

target# ./run_messageqapp_release.sh

• The messageq applications will run twice using both methods.

To display the specific commands being execute in the scripts, run:

target# cat run_messageqapp_release.sh

All other sample applications follow a similar convention. Simply cd into the application directory on the target file-system and run the appropriate script(run_*.sh).

The root of the samples directory on the target file-system (/ti/syslink-examples/<device>) contains scripts to execute all the sample applications provided. To run all the sample applications on the target file-system in debug or release mode run:

target# cd /ti/syslink-examples/<device>
target# ./runsamples_debug.sh
target# ./runsamples_release.sh

Running sample applications with slaveloader

The slaveloader application is used to load, start and stop the slave processor prior to running the GPP-side applications.

The slaveloader takes up to four parameters:

• A loader command
• A remote processor name
• An executable name - Required when the loader command is startup, load, or all
• A map file - Required if the remote core's MMU is enabled (See the SysLink MMU Support article for more information)

slaveloader_<debug|release> <startup|shutdown|all|powerup|load|start|stop|unload|powerdown|list> <Core name> 
    [File path] [map-file]

• On providing the startup command, the slaveloader will powerup-load-start the slave core.
• On providing the shutdown command, the slaveloader will stop-unload-powerdown the slave core.

To run the messageq application using the slaveloader, execute the following commands:

target# cd /ti/syslink-examples/<device>/messageq
target# ./slaveloader_debug startup DSP ./messageq_ti81xx_dsp.xe674
target# ./messageqapp_debug
target# ./slaveloader_debug shutdown DSP

Note: When no command line arguments are provided during the execution of the GPP user-side application (e.g. messageqapp_debug), the application assumes all configured slave core(s) have been previously loaded and started.

• Procedure for running the slaveloader_release and messageqapp_release sample application is same as above.

Running sample applications with arguments

The SysLink GPP-side sample applications are written to allow the application itself to load, run and stop the slave cores without the use of the slaveloader by using (optional) arguments to run the applications. This application feature is provided as a convenience. The use of the slaveloader method to control the slave cores is preferred.

When the following command line arguments are provided to the GPP user-side application, it loads, starts, and stops the slave processor in the application context itself.

Arguments to application: <Number of processors> <Processor name> <Path to slave executable> 
        <Optional MMU map file> 

Note: When no command line arguments are provided druing the execution of the GPP user-side application, the slaveloader application is expected to be run before and after running the specific application to load, start and stop the slave processor (Refer to #Running_sample_applications_with_slaveloader section for details)

To run the messageq sample on the target file-system using the argument method, execute the following:

target# cd /ti/syslink-examples/<device>/messageq
target# ./messageqapp_debug 1 DSP ./messageq_ti81xx_dsp.xe674

Procedure for running the messageq_release sample application is same as above.

All other sample applications follow a similar convention.

QNX

Note that QNX support was added in SysLink 2.10.00.12.

Installing Sample Applications on Target File-system

To assemble the SysLink executables and sample applications into a directory structure suitable for running on the device's file-system, issue the following command in the SysLink install directory:

buildhost$ make install

• The sample applications will be installed in the EXEC_DIR directory set in the products.mak file.

Note that you can over-ride the variables set in products.mak on the command line:

buildhost$ make DEVICE=TI814X \
           GPPOS=Qnx \
           SDK=None\
           SYSLINK_INSTALL_DIR=/home/user/syslink_x_xx_xx_xx \
           EXEC_DIR=/home/user/ti814x/filesystem \
           install

Then use the QNX IDE to copy the files to the target file system:

• $EXEC_DIR/ti/syslink/driver -> /sd/SysLink
• $EXEC_DIR/ti/syslink/lib -> /sd/SysLink
• $EXEC_DIR/ti/syslink/samples -> /sd/SysLink

SysLink Driver

The SysLink driver must be first run before any SysLink user applications can run.

On the target, add SysLink to the library search path. (Note this is only needed to run executables dynamically linked against the .so library):

target# export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/sd/Syslink/lib

Then launch the SysLink driver.

target# /sd/SysLink/driver/debug/syslink_drv

If the SysLink driver is built with trace enabled, the driver needs to enable both TRACE and TRACEFAILURE to configure SysLink to print out messages in case any failures occur during SysLink user application runs. To load the driver with trace output during failures, issue the following command on the target file-system:

target# export TRACE=1
target# export TRACEFAILURE=1
target# /sd/SysLink/driver/debug/syslink_drv

Alternatively, as a convenience, you can also run the script /sd/SysLink/driver/debug/run_syslink_drv.sh to achieve the same result.

The driver can be unloaded by issuing the following command on the target file-system:

target# slay syslink_drv

Running Sample Applications

This section describes the different methods to execute the sample applications provided with SysLink that demonstrate various usages and functionality.

The samples application can be run using one of two methods:

1. Use the slaveloader application to individually load, start and stop the slave core prior to executing the GPP sample application. (Refer to #Running_sample_applications_with_slaveloader_in_QNX for more details)
2. Use the SysLink GPP-side user sample application arguments support to load, start and stop the slave code (Refer to #Running_sample_applications_with_arguments_in_QNX for more details)

Setting both the TRACE and TRACEFAILURE environment variables before running an application allows any failures in the application's code to be printed out. To enable this feature, export the variables as follows:

target# export TRACE=1
target# export TRACEFAILURE=1

In each of the sample applications directory, scripts are provided that illustrate both methods of executing the same application.

To run the messageq sample in debug mode on the target file-system:

target# cd /sd/SysLink/samples/messageq
target# run_messageqapp.sh

To run the messageq sample on the target file-system in release mode:

target# cd /sd/SysLink/samples/messageq
target# run_messageqapp.sh -p release

• The messageq application will run using both methods.

All other sample applications follow a similar convention. Simply cd into the application directory on the target file-system and run the appropriate script(run_*.sh).

The root of the samples directory on the target file-system (/sd/SysLink/samples) contains scripts to execute all the sample applications provided. To run all the sample applications on the target file-system in debug or release mode run:

target# cd /sd/SysLink/samples
target# run_all.sh
target# run_all.sh -p release

Running sample applications with slaveloader in QNX

The slaveloader application is used to load, start and stop the slave processor prior to running the GPP-side applications.

The slaveloader takes up to four parameters:

• A loader command
• A remote processor name
• An executable name - Required when the loader command is startup, load, or all
• A map file - Required if the remote core's MMU is enabled (See the SysLink MMU Support article for more information)

slaveloader<_g> <startup|shutdown|all|powerup|load|start|stop|unload|powerdown|list> <Core name> 
    [File path] [map-file]

• On providing the startup command, the slaveloader will powerup-load-start the slave core.
• On providing the shutdown command, the slaveloader will stop-unload-powerdown the slave core.

To run the messageq application using the slaveloader, execute the following commands:

target# cd /sd/SysLink/samples/messageq
target# ./slaveloader_g startup DSP $PWD/messageq_ti81xx_dsp.xe674
target# ./slaveloader_g startup VIDEO-M3 $PWD/messageq_ti81xx_videom3.xe674
target# ./slaveloader_g startup VPSS-M3 $PWD/messageq_ti81xx_vpssm3.xe674
target# ./messageQ_g
target# ./slaveloader_g shutdown VPSS-M3
target# ./slaveloader_g shutdown VIDEO-M3
target# ./slaveloader_g shutdown DSP

Note: When no command line arguments are provided during the execution of the GPP user-side application (e.g. messageQ_g), the application assumes all configured slave core(s) have been previously loaded and started.

• Procedure for running the slaveloader and messageQ (release profile) sample application is same as above.

Running sample applications with arguments in QNX

The SysLink GPP-side sample applications are written to allow the application itself to load, run and stop the slave cores without the use of the slaveloader by using (optional) arguments to run the applications. This application feature is provided as a convenience. The use of the slaveloader method to control the slave cores is preferred.

When the following command line arguments are provided to the GPP user-side application, it loads, starts, and stops the slave processor in the application context itself.

Arguments to application: <Number of processors> <Processor name> <Path to slave executable> 
        <Optional MMU map file> 

Note: When no command line arguments are provided druing the execution of the GPP user-side application, the slaveloader application is expected to be run before and after running the specific application to load, start and stop the slave processor (Refer to #Running_sample_applications_with_slaveloader_in_QNX section for details)

To run the messageq sample (statically linked to the syslink user library) in debug mode on the target file-system using the argument method, execute the following:

target# cd /sd/SysLink/samples/messageq
target# ./messageQ_g 1 DSP $PWD/messageq_ti81xx_dsp.xe674

Procedure for running the messageQ (release profile) sample application is same as above. Simply replace 'messageQ_g' with 'messageQ'

To run the messageq sample (dynamically linked to the syslink .so library) on the target file-system, you can run:

target# $PWD/messageQ-dyn_g 1 DSP $PWD/messageQ_ti81xx_dsp.xe674

All other sample applications follow a similar convention.

SYS/BIOS

Note that A8-BIOS SysLink support is only available on the TI814X device.

Running Sample Applications

To run the SysLink sample applications for a BIOS-A8 system, the user must have Code Composer Studio(CCS) installed.

The FrameQ and a RingIO sample applications for the A8 are located in:

$SYSLINK_INSTALL_DIR/packages/ti/syslink/samples/rtos/ti81xx/frameq_ti814x/ti_syslink_samples_rtos_platforms_ti814x_arm/debug
$SYSLINK_INSTALL_DIR/packages/ti/syslink/samples/rtos/ti81xx/ringIO_ti814x/ti_syslink_samples_rtos_platforms_ti814x_arm/debug

Copy A8 binary to the host machine.

• Launch CCS and choose the target configuration for TI814X/Centaurus
• Connect to Cortex-A8 and load the gel file "Centaurus_20Mhz_Si.gel"
• Go to scripts, run the following Gel Functions:

PLL_CLOCKS_Config();
DDR2_Initialization();
DucatiClkEnable();
GEMSSClkEnable();
enableSpinlocks();
enableMailboxes();
Timer1_32kHClkEnable();
Timer2_32kHClkEnable();
Timer3_32kHClkEnable();
Timer4_32kHClkEnable();
Timer5_32kHClkEnable();
Timer6_32kHClkEnable();
Timer7_32kHClkEnable();

• Load A8 (frameq_ti814x_arm.xea8f) and run, A8 will power up, load and start executing the slaves.

The same can be done with the ringio_ti814x_arm.xea8f executable.

See Also

• The SysLink Install Guide (note the lack of version in the article title) covers newer releases