SYS/BIOS Getting Started Guide

From Texas Instruments Embedded Processors Wiki

Jump to: navigation, search

Translate this page to

Using SYS/BIOS with CCSv4

This chapter describes how to build SYS/BIOS examples and applications.

Installing SYS/BIOS as Part of CCSv4

If you are installing Code Composer Studio v4 (CCSv4), all the components you need to use SYS/BIOS 6.30 are installed as part of the CCSv4 installation. When you perform the CCSv4 installation, leave the checkboxes for installing XDCtools and SYS/BIOS 6 checked.

Previous versions of SYS/BIOS were called DSP/BIOS. The new name reflects that the kernel can also be use on processors other than DSPs

Creating Projects that Use SYS/BIOS 6.30

Follow these steps to use CCSv4.2 to create a CCS project that can use SYS/BIOS 6.x. If you are using a different version of CCSv4, the steps may vary somewhat.

Open CCSv4 and choose File > New > CCS Project from the menu bar.
In the New CCS Project dialog, type a Project Name. For example, to begin creating a project using the "log" example provided with SYS/BIOS, you can type "bioslog". The default project location automatically reflects the project name. Then, click Next.
Select your platform type in the Project Type field. For example, you might select "C6000". Then, click Next.
Click Next in the "Additional Project Settings" page.
In the Device Variant row of the "CCS Project Settings" page, select a filter in the first field. This shortens the list of device variants in the second field. Then, select the actual device you are using. For example, you might select “DaVinci DM64x” in the filter field and "TMS320DM647" in the second field. Depending on your device, you might also need to adjust the Device Endianness setting. Then, click Next(not Finish).
In the “Project Templates” page, expand the SYS/BIOS list to see the available examples. When you highlight a template, a brief description is provided to the right. For a sample first project, select the Sample: Log Example, and click Next.

On the “RTSC Configuration Settings” page, make sure the versions of XDCtools, SYS/BIOS, and other products that you want to use are selected. By default, the most recent versions installed are selected.
Also on the “RTSC Configuration Settings” page, click the drop-down arrow next to the RTSC Platform field. CCSv4 scans the available packages for available platforms. After the list has been created, click on the list and choose the platform you want to use. (The RTSC Target setting is based on device settings you made on earlier pages, and should not need to be changed.)
Choose which libraries you want the configuration build to link with in the RTSC Build-Profile field. The default “whole_program” option is a good choice when you are first using SYS/BIOS with CCS. Then, click Finish.

This adds a new project to the C/C++ Projects list in CCS. The project contains both the log.c source file and the log.cfg RTSC configuration file, which contains the static configuration of XDCtools and SYS/BIOS modules and objects.

Project Templates

When you create a CCSv4 project, you select a Project Template. SYS/BIOS templates are in the SYS/BIOS category. The following SYS/BIOS templates are available when you choose File > New > CCS Project and get to the Project Templates page of the project creation wizard.

Clock Example
Error Example
Event Example
Hello Example
Log Example
Memory Example
Stairstep Example
Static Example
Swi Example
Task Example
Task Example (separate config project). This template creates two projects--one to contain the C source and one to contain the RTSC configuration file. Separating the application into two projects allows you to share the configuration project with multiple C source code projects.

The Project Templates page also lists a number of additional templates that use both the Inter-Processor Communication (IPC) API and the SYS/BIOS API. See the SYS/BIOS Inter-Processor Communication (IPC) User’s Guide (SPRUGO6) for details. For an empty SYS/BIOS project, you can choose the Empty RTSC Project template

Rules for Working with CCS Build Settings

After you have created a project that contains a RTSC configuration, you can change the properties of the project in CCSv4 by right-clicking the project name and choosing Properties. Choose the “CCS Build” category and then the “RTSC” tab. You can change the settings you made on the “RTSC Configuration Settings” page of the project creation wizard. See Section 1.2.

In the “CCS Build Settings” category of the Properties dialog, the General tab applies to compiler settings, the RTSC Configuration tab applies to the “configuro” utility used to process the .cfg file, and the Link Order tab applies to the linker settings.

If your C source code and your RTSC configuration file are stored in separate projects, note that your build settings for both projects must match or be compatible. If you change the build settings for a RTSC configuration project, you should also change the build settings for application projects that use that configuration.

Note that if there is any platform-specific configuration in your .cfg file, you much change those settings in addition to any changes you make to the CCS Build Settings.

Using XGCONF to Configure SYS/BIOS Modules and Objects

XGCONF is a tool that allows you to graphically create and view RTSC configuration scripts. (If you have used DSP/BIOS 5.x, it is somewhat similar to the DSP/BIOS Configuration Tool.)

To start XGCONF, right-click on a *.cfg file in the "C/C++ Projects" view and select Open with > XGCONF.

For information about using XGCONF, see the RTSC-Pedia page about XGCONF .

Building a SYS/BIOS Project

To build your project, choose Project > Build Active Project from the CCSv4 menus.

You will see messages about the build’s progress in a Console window. The “Invoking: XDCtools” section of the messages provides information about processing of the RTSC configuration file. For SYS/BIOS projects, this is performed before the compiler and linker are run.

Running a SYS/BIOS Project

To run your project, choose Target > Debug Active Project from the CCSv4 menus. If this is the first time you are debugging a project for your target, you may need to set up a CCS Target Configuration. See the CCSv4 help for details.
In the Debug perspective, open the Runtime Object Viewer (ROV) tool by choosing Tools > ROV. Also open the Raw Logs view by choosing Tools > RTA > Raw Logs. These tools allow you to see the activity of RTSC and SYS/BIOS modules.
Set some breakpoints in the log.c source file. (You can do this by right-clicking on a line and choosing New Breakpoint > Breakpoint.) For example, set a breakpoint on the last line of each function in log.c.
Run the application.
In the Raw Logs window, you can see the informational, warning, and error messages sent by the calls to Log module APIs in log.c. The messages that begin with “LM” are diagnostics provided by XDCtools. Messages that begin with “WARNING” come from calls to Log_warning2. Messages that begin with “ERROR” come from calls to Log_error2. Messages that begin with “../log.c” come from calls to Log_info0 and Log_info2 (depending on the number of arguments).

In the ROV window, expand the tree to see the ti.sysbios.knl.Task module. The right pane shows a list of the Task threads in the application. As you advance from breakpoint to breakpoint, you see the run mode of the threads change.

SYS/BIOS Documentation

For further SYS/BIOS documentation, choose Help > Help Contents in CCSv4.

You can access the following documentation:

SYS/BIOS Release Notes
SYS/BIOS User’s Guide
SYS/BIOS API Reference
Migrating a DSP/BIOS 5 Application to SYS/BIOS 6 (Legacy Application Note)

On the Texas Instruments Embedded Processors Wiki, go to the Quick Tips page to link to demos of creating projects and using other RTSC and SYS/BIOS related features in CCSv4.

XDCtools and RTSC Documentation

XDCtools is a set of tools that enable the creation and use of RTSC packages. RTSC (pronounced rit-see) stands for Real-Time Software Components. It allows products to be developed as reusable packages, and is described in the RTSC-pedia.

XDCtools and RTSC define the configuration language used by SYS/BIOS (and other products that make use of RTSC). For SYS/BIOS 6.x versions, the configuration scripts are stored in .cfg and other files.

For further documentation on RTSC and XDCtools, choose Help > Help Contents in CCSv4 and move to the XDCtools section of the help.

Using SYS/BIOS as a Standalone Product

This chapter describes how to use SYS/BIOS outside the CCSv4 environment, for example, from a command line.

Using SYS/BIOS as a Standalone Product

This chapter applies only if you are using SYS/BIOS outside the CCSv4 environment. The steps described here are not required if you are using CCSv4 projects.

Installing SYS/BIOS as a Standalone Product

If you are installing SYS/BIOS 6 as a standalone software product, use the steps for installing XDCtools and SYS/BIOS in the following subsections.

Installing XDCtools

You must install XDCtools in order to use SYS/BIOS 6. Please refer to the XDCtools Getting Started Guide for details. XDCtools provides tools to enable the creation and use of Real-Time Software Components (RTSC) packages.

Installing SYS/BIOS 6

To install SYS/BIOS as standalone software, follow these steps:

Place the distribution file into a temporary location.
Double-click on the distribution file to start the installation process. The installation directory, <bios_install_dir>, can be anywhere on your system, but make sure there are no spaces in the full path to <bios_install_dir>.
View documentation for the SYS/BIOS 6 packages at <bios_install_dir>/docs. See the XDCtools Getting Started Guide for information on using the xdc.tools.cdoc.sg tool to generate and view documentation for repositories.

Setting Up the XDCPATH Environment Variable

XDCPATH is a required environment variable. It is the path where XDCtools looks to locate all packages. All SYS/BIOS configuration scripts only mention packages by name, not by their location, and therefore the scripts are physically portable. If you copy a package to a different location or a different system, only the XDCPATH environment variable needs to be changed. XDCtools provides a tool, xdc.tools.path.sg, to view and manage XDCPATH. See XDCtools Getting Started Guide for details.

Using XDCPATH, we can select repositories (e.g. select among different SYS/BIOS installs) and select a config.bld script.

Add the SYS/BIOS repository <bios_install_dir>/packages to the XDCPATH environment variable. In the Windows System Properties in the Control Panel, select Environment Variables under the Advanced tab. Add a new system variable named XDCPATH, with the value <bios_install_dir>/packages.

Other operating systems require a slightly different command to set environment variables. See the documentation for your operating system for details.

Managing the config.bld File

The build configuration script, config.bld, is a master setup script that completely defines the RTSC targets and the environment in which individual RTSC packages will build. For practical purposes, however, this script is usually just a list of targets and paths to their Code Gen tools.

The intention behind the build configuration script is the following: it is a small, non-portable piece of the build flow, because it defines the location of the various Code Gen tools on your system. Another use for the build configuration script is to provide a common build setup for multiple packages.

SYS/BIOS 6 ships a default config.bld script at

 <bios_install_dir>/etc/config.bld.default

View this script. This default script names all the targets and platforms that SYS/BIOS 6 supports. It also points to the Code Gen tools. Please refer to the release notes on supported versions of Code Gen tools.
Create a directory <localRepository> anywhere on your system. Copy config.bld.default into <localRepository>/config.bld. All targets are disabled by default. Please uncomment the target of interest in the Build.targets array in config.bld. You will also need to edit this script for the following reasons.

Location of your Code Gen tools is different.
You are interested in a particular platform.

Add <localRepository> to the XDCPATH environment variable.

Generating and Building SYS/BIOS Examples

SYS/BIOS does not ship any pre-built examples. Instead it ships a package ti.sysbios.genx which will generate the examples in a directory of your choice. ti.sysbios.genx allows the examples to be customized for your config.bld script. It also allows re-generation of the examples in case of corruption.

View options for ti.sysbios.genx by typing the following:

   xs ti.sysbios.genx --help

Generate SYS/BIOS 6 examples as follows:

   xs ti.sysbios.genx <myExamples>

Examples are generated in the <myExamples> folder for all targets and platforms listed in the config.bld referred to in your XDCPATH environment variable.

You can optionally specify a single target and a platform listed in the config.bld on the command line.

   xs ti.sysbios.genx -t ti.targets.C64 
     –p ti.platforms.dsk6416 <myExamples>

By default, the examples are generated without debug support. If you want to generate the examples for debugging, you can use the –r option to select a profile for building the examples. For example, the following command line generates the examples for debugging:

xs ti.sysbios.genx -t ti.targets.C64 -p ti.platforms.sim6xxx -r debug <myExamples>

The –r options are: debug, whole_program, and whole_program_debug. The default is whole_program. The "debug" profile allows you to step through the sources if sources are available. The "whole_program" profile has negligible debug symbols. The "whole_program_debug" profile has more debug symbols and improves the debug experience when compared to "whole_program". It is recommended that production code be built with whole_program or whole_program_debug.

Many examples use the same SYS/BIOS configuration. Use incremental builds to build the examples if you want to prevent unnecessary builds of the configuration package.

To use makefiles to build the examples, use commands like the following:

Use the top-level makefile to build all examples.

       cd <myExamples>
       gmake

To build one example, build <myExamples>/common/<platform_dir> first. Many examples depend on <myExamples>/common/<platform_dir>.

       cd <myExamples>\common\<platform_dir>
       gmake

Use gmake to build an individual example:

       cd <myExamples>\hello\<platform_dir>
       gmake

NOTE: During the installation, the XDCROOT environment variable is set by the installer. In addition, %XDCROOT% is added to the beginning of the system and user path(s). However, the <examples>/common/common.mak file references the specific version of XDCtools it was installed with. If you update your XDCtools installation and want to rebuild the examples with the new version, you need to update the XDCROOT definition in the <examples>/common/common.mak file.

See the README for individual examples for more details on how to build them.

You can use <myExamples>/common/common.mak to pass additional linker (e.g. --xml_link_info) and compiler options (e.g. –pdr) to the makefiles used by all examples.

<myExamples> has the following structure when built. The expected output is in testcase.k files.

Configuring SYS/BIOS

SYS/BIOS configuration allows clients to specify modules to be used in an application, create static objects, and modify their properties as part of the application build process. SYS/BIOS configuration also allows clients to modify program-level configuration parameters such as stack size and the section map.

SYS/BIOS Configuration Script

SYS/BIOS configuration is done through a script. The script is a file with “.cfg” extension that contains a RTSC script. Such scripts are an extension of JavaScript. Please see <xdc_install_dir>/packages/xdc/cdk/langref/xdcScript.pdf for details.

The SYS/BIOS configuration script by itself is not sufficient to create a SYS/BIOS configuration; you must also specify the target and platform that SYS/BIOS will be running on. The script is the client’s portable input into a SYS/BIOS configuration package.

In the simple case, this script can list all the modules used. See <myExamples>/common/common.cfg. Creating static objects and manipulating them is an optimization and is the focus of the static example.

Create a <cfgScript>. This file can be located along with the application code (static example has its own static.cfg script) or maintained separately (hello example uses common/common.cfg). For example client.cfg may be located at C:\MyProjects\client\client.cfg.
Edit this file using any text editor. Refer to the SYS/BIOS 6 documentation for details on configuration parameters.

Create and Build a SYS/BIOS Configuration Package

A SYS/BIOS configuration package is created using xdc.tools.configuro.

The configuration package is specific to a SYS/BIOS configuration script, platform/target pair and development environment.

View options supported by xdc.tools.configuro as follows:

xs xdc.tools.configuro --help

Use xdc.tools.configuro to create and build a SYS/BIOS configuration package. The configuration package <myCfgPkg> can be located anywhere on your system.

xs xdc.tools.configuro -–cb -t<target> -p<platform> -o <myCfgPkg> -r whole_program <cfgScript>

For example:

xs xdc.tools.configuro -–cb –t ti.targets.C64 
  –p ti.platforms.sim6xxx 
  –o C:\MyProjects\client\configPkg 
  -r whole_program 
  C:\MyProjects\client\client.cfg

This step of running xdc.tools.configuro can be integrated into a makefile. See the XDCtools Getting Started Guide for details on running xdc.tools.configuro in a makefile. Also see the makefiles used by the examples.

The configuration package needs to be rebuilt for any change in the <cfgScript>.

Building an Executable

Executable Build Flow Changes

A compiler.opt file located in the SYS/BIOS configuration package needs to be added to the compiler options using -@ for ti targets. The linker.cmd file located in the SYS/BIOS configuration package needs to be added to linker options. This file specifies the obj files and command file. Add the RTS library to linker options from Code Gen tools specified in your config.bld. NOTE: The RTS library must come after the linker.cmd file in the link order. Ensure this is the case in your makefile.

C Source File Changes

#include <xdc/std.h> to get RTSC types.
#include <xdc/cfg/global.h> to get access to Program.globals generated by the SYS/BIOS configuration.
Include module header files.

Microsoft Visual Studio C++ 2005 Installation Notes

Skip this section if you are not going to build your application on Windows using the windows emulation support in SYS/BIOS 6.

Building on Microsoft Windows requires Microsoft Visual Studio C++ 2005 Express Edition to be installed on your computer. Download and install the following components (available for free) from the Microsoft Web Site

Microsoft Visual C++ 2005 Express Edition
Microsoft Visual C++ 2005 Express Service Pack 1
Microsoft Platform SDK for Visual C++ 2005 Express

(Microsoft Windows Server 2003 R2 Platform SDK)

Make sure to set the environment variables required for Visual Studio C++. Run the following batch script at the DOS prompt before building the examples:

C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat

Update the Win32.rootDir in your config.bld script to point to your Visual C++ installation folder. The rootDir must not contain spaces or backslash characters. You must use the short pathname to the Visual C++ installation folder. Use the following command in a DOS Shell to display the short pathname of the Visual C++ installation folder. (Enter the command all on one line.) Then replace all backslash characters with forward slashes.

for /f "delims=" %i in ("C:\Program Files\Microsoft Visual Studio 8") do @echo %~fsi

For example, here is how Win32.rootDir would be set on a typical system:

Win32.rootDir = "C:/PROGRA~1/MID05A~1";

Update the Win32.vcPath["VC8"].sdkPath in your config.bld script to point to your Platform SDK installation folder. As with the Win32.rootDir, the sdkPath must not contain spaces or backslash characters, and you must use the short pathname to the installation folder.

For example, here is how the sdkPath would be set on a typical system:

Win32.vcPath["VC8"].sdkPath = " C:/PROGRA~1/MI9547~1";

SYS/BIOS ONLINE VIDEO TRAINING SERIES NOW AVAILABLE !!

As of 3/20/12, SYS/BIOS training is NOW AVAILABLE online for all users. While we teach this workshop LIVE, the authors decided to record all chapters and labs for your benefit and access around the world. Voice-over PPTs are usually BORING. However, this training series is hosted by the two authors and offers lots of in-depth conversations about the tools and SYS/BIOS, highlighting, add'l info not included in the downloads, stories, panning/zooming, etc. to keep the users engaged and having a good time while learning SYS/BIOS. The content also includes target-specific chapters on Stellaris and C6000. Don't wait...go check out this spectacular resource at your fingertips:

SYS/BIOS 1.5-day Workshop Videos

For technical support please post your questions at http://e2e.ti.com. Please post only comments about the article SYS/BIOS Getting Started Guide here.