AM335x SYSBIOS Industrial SDK 01.00.00.03 User Guide

Content is no longer maintained and is being kept for reference only!

AM335x SYSBIOS Industrial SDK 01.00.00.03 User Guide

Revision History

Revision	Date	Description
1.0	02-April-2012	Created initial version of the document

AM335x Industrial SDK Introduction

The SYSBIOS-based software development kit (SDK) for industrial communications is designed for the Sitara AM335x ARM Cortex-A8 microprocessor family to enable customers add real-time industrial communications easily and quickly to their system. By making all the basic system software components immediately available, the Kit allows developers to focus on their application code, where they can add the most differentiation. Optimized to support real-time industrial communications protocols such as EtherCAT, Profibus, Profinet, Ethernet/IP and many others, the SDK includes a real-time, low-footprint SYSBIOS kernel with boot loader and sample industrial applications to get started quickly.

The SYSBIOS Industrial SDK for AM335x combines all the software components and tools needed to begin development of SYS/BIOS-based applications on the ARM, and includes the following

• Open source SYS/BIOS Real Time Operating System (RTOS)
• Bootloader for Sitara AM3359 Industrial Development Kit (IDK) and Industrial Communication Engine (ICE) with support to boot from various peripherals
• Library of peripheral drivers integrated with SYSBIOS supporting both IDK and ICE
• Sample applications demonstrating peripheral use cases for both IDK and ICE
• Code Composer Studio integrated development environment (IDE) v.5
• Sample industrial input/output applications over communication protocols such as EtherCAT, PROFIBUS and other Ethernet and serial based Fieldbus Industrial Ethernet protocols
• Evaluation versions of protocol stacks for industrial communications such as EtherCAT, PROFIBUS and many others to facilitate software development

A high level block diagram of AM335x IDK is given below.

A high level block diagram of AM335x ICE is given below.

Reference Documents

• SYS/BIOS Getting Started Guide
• SYS/BIOS User Guide
• StarterWare Getting Started Guide
• StarerWare User Guide

SDK Directory Structure

|--- sdk 

|   |--- docs 

|       |---AM335x Industrial SDK User Guide.pdf 

|       |---AM335x Industrial SDK Release Notes.pdf 

|       |---AM335x Industrial SDK Getting Started Guide.pdf 

|   |--- drivers 

|       |--- include 

|       |--- lib 

|       |--- src 

|   |--- examples 

|       |--- ethercat 

|           | --- esi

|       |--- i2c_led 

|       |--- uart_echo 

|    |--- platform 

|       |--- am335x 

|           |--- evmam335x 

|               |--- include 

|               |--- lib 

|               |--- src 

|   |--- protocols 

|       |--- ethercat 

|           |--- docs 

|           |--- ecat_appl

|               |--- esi

|               |--- patch 

|               |--- EcatStack

|           |--- firmware 

|           |--- include 

|           |--- stack 

|   |--- starterware 

|   |--- tools 

|       |--- gel 

docs - This folder contains pdf version of Release Notes, User guide and Getting Started guide

drivers - This folder contains source code and include files for SYS/BIOS driver for AM335x and a pre-built library.

examples - This folder contains examples, their project files, source and include files. User can build the application in CCS using these files. Please see "Getting Started Guide" for details on building the application

platform - This contains the EVM specific initialization code which is not provided by Starterware. This code sets up the EVM specifics like pinmux, IO expanders, GPIOs and similar board specific stuff that shall enable proper execution of the applications.

protocols - This folder contains supported industrial automation protocol libraries and/or source codes and their project files. 

starterware - This contains StarterWare code which provides Device Abstraction Layer libraries and peripheral/board level sample/demo examples that demonstrate the capabilities of the peripherals on a no_OS platform. See Starterware 

tools - This contains tools supporting application development. For eg GEL files, SPI Flashing tool for ICE and post-build script.

System Requirements

Hardware

• AM335x IDK / AM335x ICE
• Windows Host Machine with minimum 2GB RAM
• SD Card for IDK / Micro SD Card for ICE
• XDS 560/510 Class Emulators for debugging for IDK

Software 

• Code Composer Studio version CCS 5.1.0.09000 or later
• Serial console terminal application (like Teraterm, minicom, HyperTerminal)

SDK Setup

SDK setup will install following items in the machine. Please see the installation instruction here. 

• SDK Source files, CCS project files, pre-built libraries and documents

Pre-Built Binaries and Libraries

SDK installation comes with following pre-built libraries. These libraries can be used to build user applications quickly.

• evmam335x.lib          -  Platform specific implementations which are not provided by StarterWare 
  

                                        SDK Path - $(SDK_INSTALL_FOLDER)\platform\am335x\evmam335x\lib

• ecat_slave_stack.lib  -   EtherCAT Slave Stack library including PRU Firmwares

                                        SDK Path - $(SDK_INSTALL_FOLDER)\protocols\ethercat\stack

• sys_bios_driver.lib     -  SYS/BIOS specific implementation for accessing peripheral devices and EVM functionality

                                        SDK Path - $(SDK_INSTALL_FOLDER)\drivers\lib

• drivers.lib                  -  StarterWare library for peripheral devices 

                                        SDK Path - $(SDK_INSTALL_FOLDER)\starterware\starterware-starterware-src\binary\armv7a\cgttms470_ccs\am335x\drivers

• platform.lib               -  Starterware EVM specific initialization library

                                        SDK Path - $(SDK_INSTALL_FOLDER)\starterware\starterware-starterware-src\binary\armv7a\cgttms470_ccs\am335x\evmAM335x\platform

• mmcsd.lib                 -  Starterware MMC SD Card library

                                        SDK Path - $(SDK_INSTALL_FOLDER)\starterware\starterware-starterware-src\binary\armv7a\cgttms470_ccs\mmcsdlib

• utils.lib                      -  StarterWare Utils library

                                         SDK Path - $(SDK_INSTALL_FOLDER)\starterware\starterware-starterware-src\binary\armv7a\cgttms470_ccs\utils

SDK does not have any pre-built binaries inluded, but binaries generated using SDK examples (given below) can be downlaoded seperately. Please see release notes for download link.

• EtherCAT                   - Sample application demonstrating EtherCAT functionality. This is built for ICE board. For use on IDK, user will have to re-build the application with board-type set as IDK. 
• i2c_led                       - Sample application demonstrating LED toggling on the board.This is built for ICE board. For use on IDK, user will have to re-build the application with board-type set as IDK.
  
• uartecho                    - Sample application demonstrating UART communication.This is built for ICE board. For use on IDK, user will have to re-build the application with board-type set as IDK.
  

SYS/BIOS Driver

AM335x SDK provides a driver library for  accessing  device peripheral modules from a SYS/BIOS application. This driver is basically an abstraction of StarterWare libraries along with SYS/BIOS OS specific implementation. Currently, this driver supports GPIO,I2C and UART module access. Other modules will be added to this library in future releases. This library supports both ICE and IDK.

Bootloader

Starterware AM335X provides a simple bootloader, which can be copied to an MMCSD card or flashed to SPI/NOR flash depending up on board , which after a power-on-reset can bootstrap the board. Additionally, SPI/SD card bootloader can load an application from the MMCSD card/SPI Flash to DDR or Internal RAM and transfer the control to the application. This can be used for out-of-box experience. 

Bootloader for IDK

Upon board power on, the RBL [Read Only Memory BootLoader], residing in the ROM of the AM335X kickstarts. RBL checks the boot mode setting (which should be MMCSD boot mode ) and depending upon the boot mode setting it copies boot loader from MMCSD card. RBL requires boot loader to be named as "mlo". RBL copies the boot loader to internal memory and gives control to it. Boot loader initializes PLL0 and PLL1 for all the devices and then it initializes DDR. Once all the initialization is done, it copies the application from MMCSD card to the DDR and transfers the control to the application. The application starts to execute from DDR.

Bootloader for ICE

Upon board power on, the RBL, residing in the ROM of the AM335X kickstarts.RBL checks for the boot mode settings(SYSBOOT) and depending on the settings, executes NOR boot loader or SPI boot loader.

SPI boot loader looks for application(named as "app") in MicroSD card. If application is found in SD card, boot loader loads that into DDR/Internal RAM and transfers control to it. Otherwise, boot loader loads the application from SPI flash to DDR and transfers control to it.

NOR boot loader in turn looks for application(named as "app") in MicroSD card. If application is found in SD card, boot loader loads that into DDR/Internal RAM and transfers control to it. Otherwise, boot loader looks for a valid image in every 64KB offset in NOR flash.If a valid image is found in NOR, bootloader will transfer control to it.

Setting boot modes on ICE

     The boot mode on ICE boards ( Rev A2) can be altered by connecting/disconnecting jumper on J10 pins.

•  If the jumper is not connected on J10, RBL will load the bootloader from SPI flash and execute it.
  
•  If a jumper is connected between pin 1 & 2 on J10, RBL will first check for valid boot image in NOR flash sector 0 and if it finds, will execute it from there itself. Otherwise, will load and execute SPI flash bootloader.
  

Building instruction for boot loader can be found in "Building Bootloader" section .

Examples

Following examples and the CCS project files for those are included in the IA-SDK installation package. For details on importing and building samples applications in CCS, please refer "AM335x Industrial SDK Getting Started Guide" . The binaries generated using the below given projects willl work on both ICE and IDK without any other modifications.

EtherCAT

NOTE-1

SDK Supports two different versions of EtherCAT application.

1 . Simple Demo Application  - An EtherCAT sample application built using  pre-built EtherCAT stack library (ecat_slave_stack.lib). This allows limited development using SSC5.0 stack library via Sample Application Interface which provides controlling 32- bit input and 32-bit output. Object dictionary adaptation is not possible in this evaluation version. This will be the default OOB application for EtherCAT. The project files for this application can be found in $(SDK_INSTALL_FOLDER)\examples\ethercat. The example application will be delivered in source, but the EtherCAT stack will be delivered in object format only.

2.  Full Feature Demo Application  -  This is a full-fledged application and provides full flexibility and configurability. However this application need access to complete stack source. As per the SLA terms, TI cannot distribute the stack (Beckhoff Slave Sample Code) in source format. Hence, to build this application, user need to get the SSC 5.0 source code from ETG website and apply the provided patch. The project files for this application can be found in $(SDK_INSTALL_FOLDER)\protocols\ethercat\ecat_appl. Please see the details in later sections. For more information, refer the section on "Building Full Feature EtherCAT Application" of this document.

 

NOTE-2

Both EtherCAT applications mentioned above have multiple Build configurations. They are described below.

1. Debug  - This configuration builds the application with maximum debugging support including Real Time Analysis(RTA) and Logging.The application is built to execute from DDR.

2. IRAM - This configuration builds the application in Thump mode, optimized for space, with no RTA and logging support. Built to be executed completely from internal memory( without DDR).

3. NOR  - This configuration builds the application with no RTA and logging support. Built to be executed from NOR Flash and internal RAM (without DDR use).

4. Release - This configuration builds the application with no RTA and Logging support. Built to be executed from DDR.

This folder has TI EtherCAT slave simple demo application along with configuration xml file. User can start and build the CCS5.1 project named ethercat and a file named "ethercat.bin" will be generated (in sdk\examples\ethercat\Debug) which needs to be loaded into SD card.

Application will toggle digital out LEDs on top of J17 in a circular bit shift pattern. This indicates that slave is up and in INIT state.

To test TI EtherCAT slave sample app - one can use TwinCAT or any other compatible EtherCAT master. Below are the steps to use TI slave with TwinCAT

1. Install TwinCAT (One month evaluation is available for free download from Beckhoff website [1]- select PLC mode of installation and check IO drivers box
2. Copy sdk\examples\ethercat\esi\TI_ESC.xml to <Drive>:\TwinCAT\Io\EtherCAT folder
3. Start TwinCAT system manager
4. Goto Options > Show Real Time Ethernet Compatible Devices and Install TwinCAT RT Ethernet intermediate driver. For best performance - it is recommended to use compatible NIC card listed Supported Network Controller by Beckhoff Ethernet Driver
5. Goto I/O - Configuration > I/O Devices - right click and select Append device and then select EtherCAT > EtherCAT. Device1 (EtherCAT) will be added to I/O devices
6. Connect CAT5 Ethernet cable from TwinCAT PC to ECAT IN/Port0(J8) of IDK. If you have multiple IDKs in chain, please connect from ECAT OUT/Port1 (J9) to Port0 of next IDK. For last IDK in chain, Port1 is left open.
7. Now right click Device1(EtherCAT)> select Scan Boxes...
8. TI Boxn(ti-esc) will be detected automatically
9. Now select Device1 (EtherCAT) and goto Actions > Select Set/Reset TwinCAT to Config Mode or use shortcut SHIFT-F4
10. A dialog will pop asking Load I/O Devices, select Yes
11. Next dialog asks confirmation to Activate Free Run - select Yes. This will put TI ESC into OP mode
12. Now user can control digital out LEDs using TwinCAT. Select TI Boxn(ti-esc)>DO Outputs > LED1-8 to control the output LEDs

This application is dependant on drivers.lib, evmam335x.lib, sys_bios_driver.lib and ecat_slave_stack.lib. The project files for these libraries except for ecat_slave_stack.lib are included in the SDK and they can be rebuild with any modification required. Upon modifying and building libraries, users should re-build the application as well.

For more information, Please see Configuring TwinCAT For AM335x

UartEcho

UartEcho example illustrates how UART Peripheral can be used from a SYS/BIOS application. This application needs that the serial port on the EVM connected to the host serial port via a NULL modem cable. A serial terminal application (like teraterm/hyperterminal/minicom) is running on the host. The host serial port is configured at 115200 baud, no parity, 1 stop bit and no flow control.

   The application prints a message on the UART console in specific intervals and echos the character sent to it. 

This application is dependant on drivers.lib, evmam335x.lib and sys_bios_driver.lib. The project files for these libraries are included in the SDK and they can be rebuild with any modification required. Upon modifying and building libraries, users should re-build the application as well.

i2c_led

i2c_led application illustrates how IDK LEDs can be accessed using i2c and GPIO modules from a SYS/BIOS application. This application accesses 8 output LEDs, run LED, error LED, act0 LED and act1 LED. Output LED's are accessed through i2c mdule and other LEDs are used through GPIO module. 

Once loaded successfully, it can be seen that, all the above mentioned LEDs blinking in certain pattern.

This application is dependant on drivers.lib, evmam335x.lib and sys_bios_driver.lib. The project files for these libraries are included in the SDK and they can be rebuild with any modification required. Upon modifying and building libraries, users should re-build the application as well.

Building Libraries/Binaries for IDK and ICE

Libraries/Binaries for IDK and ICE need not to be built separately. The run-time board detection mechanism will identify the board and will execute accordingly.

Building Full Feature EtherCAT Application

The ethercat example application found in $(SDK_INSTALL_FOLDER)\Examples\ethercat folder is a limited development application. To have a full developement capability on AM335x, users needs to get the EtherCAT source code from Beckhoff and use that with SDK. SDK provides all board specific implementation sources for EtherCAT and a patch file to modifiy Beckhoff source files for AM335x. This application can be found in $(SDK_INSTALL_FOLDER)\protocols\ethercat\ecat_appl. This folder also includes the configuration xml file to be used for testing and it can be found in $(SDK_INSTALL_FOLDER)\protocols\ethercat\ecat_appl\esi folder.

The steps for building full feature EtherCAT application using Beckhoff source are given below.

1. Download EtherCAT stack version 5.0 from ETG website and extract it to a local folder.
   
2. Apply ( See Apply instructions below) TI_ECAT.patch file found at $(SDK_INSTALL_FOLDER)\protocols\ethercat\ecat_appl\patch on extracted Beckhoff stack code.
   
3. Copy those patched Beckhoff source files (.c and .h) to $(SDK_INSTALL_FOLDER)\Protocols\ethercat\ecat_appl\EcatStack
   
4. Launch CCS and import ecat_appl project found at $(SDK_INSTALL_FOLDER)\Protocols\ethercat\ecat_appl to CCS
   
5. Build the project. This will generate the application binary which can be used to run on AM335x.
   

Applying a Patch file

• Download Windows Patch Utility from gnuwin32 sourceforge. ( Note that this is not a TI tool - See licensing information page for more details)
• Extract the zip file to the Windows PC. Patch file utility(Patch.exe) can be found in bin folder.
• Launch DOS Command prompt ( Start->Run->cmd).
• CD to bin folder.
• Execute patch.exe as given below

                 patch.exe -i PATCH_FILE_NAME -d SOURCE_DIR

                 where PATCH_FILE is name of the patch file with full path and

                          SOURCE_DIR is Directory with full path where source files are present.

    Example :-

                 patch.exe -i C:\TI\am335x_sysbios_ind_sdk_1.0.0.1\sdk\protocols\ethercat\ecat_appl\patch -d c:\SSC_V5i0\SlaveFiles\src

Generating ESI Header file From ESI xml

The above given EtherCAT application is expected to be used against the ESI xml file given in esi folder.If the the application needs to work with some other ESI xml file, user need to generate curresponding ESI header file ( tiesc_eeprom.h ) and should re-build ecat_appl with the genarated .h file.

Steps for generating ESI header file is given below.

• Generate the binary file equilant to ESI xml file. Pease see Generating EEPROM binary.
  
• Convert the binary file to header file using the bin2header.exe utility. This utility can be found in  $(SDK_INSTALL_FOLDER)\tools\bin2header
  

                 Usage is as follows.

                           'bin2header.exe 'binary_filename' 'header_filename' '

                 Example -

                            bin2header.exe "C:\Documents and Settings\user\Desktop\Box1.bin" "C:\Documents and Settings\user\Desktop\tiesc_eeprom.h"

• Replace the existing file with new header file ( tiesc_eeprom.h) to $(SDK_INSTALL_FOLDER)\Protocols\ethercat\ecat_appl\src
  
• Rebuild the application.
  

Building Bootloader 

Boot laoder project coming with sdk includes three build configurations and they are descirbed below.

1. Debug -  This configuration builds the application with no optimization in place , in 32 bit mode and with maximum debugging support. The size of the boot loader binary would be large. Builds the binary to be executed from SD card or SPI flash depending on the post-built steps defined.
   
2. Release - This coniguration build the appllication in 16 bit mode and optimized for space. Builds the binary to be executed from SD card or SPI flash depending on the post-built steps defined.
   
3. NOR -  This configuration builds the application to be execited from NOR Falsh.
   

Once the build configuration is seclected,  folow the given steps to build the boot loader.

1. Import Bootloader project found at $(SDK_INSTALL_FOLDER)\starterware\starterware-starterware-src\build\armv7a\cgttms470_ccs\am335x\evmAM335x\bootloader directory to CCS. See importing and building instructions section for details.
2. Import dependant starterware projects. They are drivers, platform and mmcsdlib. They can be located at  $(SDK_INSTALL_FOLDER)\starterware\starterware-starterware-src\build\armv7a\cgttms470_ccs\am335x\evmAM335x\.
3. Set build configuration for dependant projects as "FixedPoint". Libraries generated with other configurations won't link with bootloader application because of "Floating Point suppport" mismatch.
4. Build dependant projects in  CCS.
5. Set the HW_IDK or HW_ICE macro depending upon the board.
6. Set the post build script arguments properly. See Post Build Script section fro details.
7. Build bootloader project.
   
8. Succesfull build will generate boot.out and binary file in $(SDK_INSTALL_FOLDER)\starterware\starterware-starterware-src\binary\armv7a\cgttms470_ccs\am335x\evmAM335x\bootloader 
   

Generating Executable Binary - Post Build Script

Post build script file(post_build.bat) can be found at $(SDK_INSTALL_FOLDER)\Tools. 

This Script generates a plain excutable binary(.bin) file from .out file and adds a header to it depending upon the type of binary and binary storage location.

Parmeter List for post_build.bat

• Param 1 - CCS Install path
• Param 2 - Code Gen tool Install path
• Param 3 - .out file path
• Param 4 - .out file name
• Param 5 - ti_image.exe path
• Param 6 [Optional] - Binary type [0- bootloader,1-Application]
• Param 7 [Optional] - Binary Storage type [ 0-SPI Falsh, 1-MMCSD Card, 2- NOR Flash]
• Param 8 [Optional] - Load address for the binary in hexadecimal format. If not provided, default values will be set. This has no effect in case NOR Flash.
  
• Param 9 [Optional] - Run  address for the binary in hexadecimal format. If not provided, default values will be set
  

There are two binary types - Bootloader binary and Application binary.
There are three storage locations - SPI Flash, MMC/SD card or NOR Flash.

Examples :-

1. Generate a bootloader binary to be stored in SPI Flash

      post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "boot" "TI_IMAGE_PATH" "0" "0"
2. Generate a bootloader binary to be stored in SD Card

      post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "boot" "TI_IMAGE_PATH" "0" "1"

2. Generate a bootloader binary to be stored in NOR Flash

      post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "boot" "TI_IMAGE_PATH" "0" "2" "0x08000000" "0x08000000"
3. Generate a application binary to be stored in SPI Flash and executed from DDR

      post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "appl" "TI_IMAGE_PATH" "1" "0" "0x80000000" "0x80000000"

4. Generate a application binary to be stored in MMCSD Card and executed from internal RAM

      post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "appl" "TI_IMAGE_PATH" "1" "1" "0x402f8000" "0x40300000"

5. Generate a application binary to be stored in NOR Flash and executed from NOR

     post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "appl" "TI_IMAGE_PATH" "1" "2" "0x08010000" "0x08010000"

Technical Support and Product Updates

For further information or to report any problems, contact http://community.ti.com or http://support.ti.com.