AM335x SYSBIOS Industrial SDK 01.00.00.06 User Guide

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

AM335x SYSBIOS Industrial SDK 01.00.00.06 User Guide

Revision History

Revision	Date	Description
1.0	13-Dec-2012	Created initial version of the document
1.1	16-Jan-2013	Updated "Generating AM335x EtherCAT sources using Beckhoff SSC Tool" section

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 

|   |--- examples 

|       |--- enetLwip_sysbios

|       |--- ethercat_slave 

|           | --- esi

|       |--- i2c_led  

|       |--- powerlink_slave

|           |--- DeviceDescription

|       |--- profibus_slave

|           |--- GSD

|           |--- APP 

|           |--- include

|       |--- i2c_led 

|       |--- uart_echo 

|   |--- os_drivers

|       |--- include

|       |--- lib

|       |--- src

|   |--- platform 

|       |--- am335x 

|           |--- include 

|           |--- lib 

|           |--- src 

|   |--- protocols 

|       |--- ethercat_slave 

|           |--- docs 

|           |--- ecat_appl

|               |--- esi

|               |--- patch 

|               |--- EcatStack

|       |--- powerlink_slave 

|           |--- firmware 

|           |--- stack_lib

|           |--- stack_src

|               |--- EplStack

|               |--- include

|               |--- openmac

|       |--- profibus_slave 

|           |--- docs 

|           |--- firmware

|           |--- include

|           |--- stack_lib

|   |--- starterware 

|   |--- tools 

|       |--- bin2header

|       |--- flashing tools

|       |--- gel

|       |--- post_build

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

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

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

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 on IDK

Software 

• Code Composer Studio version CCS 5.2.0.00069 (Ind SDK 1.0.0.6 is not supported on CCS 5.3.XX)
  
• SYSBIOS 6.33.05.46 Real Time Operating System
• 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

Installation process will create an environment variable called IA_SDK_HOME which will be set to location where the sdk is installed. This variable is used by sdk examples for include paths and library paths.

Pre-Built Binaries and Libraries

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

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

                                        SDK Path - $(IA_SDK_HOME)\platform\am335x\lib

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

                                        SDK Path - $(IA_SDK_HOME)\protocols\ethercat_slave\stack_lib

• powerlink_stack.lib    -  Powerlink Slave stack library
  

                                         SDK Path - $(IA_SDK_HOME)\protocols\powerlink_slave\stack_lib

• profibus.lib                -  Profibus Slave stack library
  

                                        SDK Path - $(IA_SDK_HOME)\protocols\profibus_slave\stack_lib

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

                                        SDK Path - $(IA_SDK_HOME)\drivers\lib

• drivers.lib                  -  StarterWare library for peripheral devices 

                                        SDK Path - $(IA_SDK_HOME)\starterware\binary\armv7a\cgt_ccs\am335x\drivers

• platform.lib               -  Starterware EVM specific initialization library

                                        SDK Path - $(IA_SDK_HOME)\starterware\binary\armv7a\cgt_ccs\am335x\evmAM335x\platform

• mmcsd.lib                 -  Starterware MMC SD Card library

                                        SDK Path - $(IA_SDK_HOME)\starterware\binary\armv7a\cgt_ccs\mmcsdlib

• utils.lib                      -  StarterWare Utils library

                                         SDK Path - $(IA_SDK_HOME)\starterware\binary\armv7a\cgt_ccs\utils

• lwip_static.lib            -  LightWeight TCP/IP stack library

                                         SDK Path - $(IA_SDK_HOME)\starterware\third_party\lwip-1.4.0\lib

SDK does not include any pre-built binaries, however binaries generated using SDK examples (given below) can be downloaded separately. All pre-built binaries except bootloader are board independent. Please see release notes for download link.

• enetLwip_sysbios - Sample application demonstrating Ethernet and TCP/IP functionality.
• ethercat - Sample application demonstrating EtherCAT slave functionality.
• i2c_led - Sample application demonstrating LED toggling on the board.
• powerlink_slave - Sample application demonstrating Powerlink slave functionality.
• profibus_slave - Sample application demonstrating Profibus slave functionality.
• uartecho - Sample application demonstrating UART communication.

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 kick starts. 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 kick starts.RBL checks for the boot mode settings(SYSBOOT) and depending on the settings, executes NOR bootloader or SPI bootloader.

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 it is found in SD card, 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 see the 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.

EnetLWIP_sysbios

This example illustrates how Ethernet driver and TCP/IP stack can be used in a SYS/BIOS application to demonstrates a sample web server. This application uses the starterware Ethernet driver and LWIP TCP/IP stack. This application assigns a static IP address (192.168.1.2) for the device and hosts a very simple web server on that IP.The application also prints status messages on UART console. To see the web server, connect the AM335x device to the PC with a Ethernet cable and go to http://192.168.1.2 using any web browser. Here LWIP stack has been built as a static library and later linked to application.

This application is dependent on lwip_static.lib, drivers.lib, am335x_platform.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.

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.01 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 $(IA_SDK_HOME)\examples\ethercat_slave. 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.01 source code from ETG website and apply the provided patch. The project files for this application can be found in $(IA_SDK_HOME)\protocols\ethercat_slave\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

By Default, Both EtherCAT application embeds PRU firmware binaries into application binary. However, loading PRU firmwares from SPI flash is also supported in this version. This means, EtherCAT application will load PRU firmwares from SPI flash memory ( if available) during run-time. This saves almost 16KB memory by reducing the binary size. EtherCAT binary expects PRU0 firmware at an offset of 0x98000 from the beginning of SPI memory and PRU1 firmware at an offset of 0x9C000 from the beginning.

 

NOTE-3

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. This build supports online Application upgrade .

2. IRAM - This configuration builds the application in Thumb mode, optimized for space, with no RTA and logging support. Built to be executed completely from internal memory( without DDR). EtherCAT application built in this mode expects PRU firmwares to be flashed in SPI flash memory. Please note CCS build will generate a concatenated( ARM and PRU binaries) by default using batch file 'cat_appl_bins.bat'. This newly created binary can be flashed to SPI Flash at 0x20000 so that both ARM and PRU binaries will be flashed in a single shot.

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 build supports online Application upgrade.

 

NOTE-4

  Both EtherCAT applications support non-volatile storage of ESI EEPROM information. This can be disabled or enabled on full featured application by defining/undefining EEPROM_SPI macro in tiescbsp.h. This feature cannot be modified in limited demo.

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.upon successful build, files named "ethercat_SD.bin" and "ethercat_SPI.bin" will be generated (in sdk\examples\ethercat_slave\Debug). ethercat_SD.bin is for SD card and ethercat_SPI.bin is for SPI flash

On startup, application will set digital out LEDs 2,4,6 and 7 . This indicates that slave is up and in INIT state.

Note that this is different from startup behaviour in prior SDK releases where digital LED animation occurs in bit shift pattern.

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. More details can be found here.

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_slave\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 EtherCAT IN/Port0(J8) of IDK. If you have multiple IDKs in chain, please connect from EtherCAT 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

Online application upgrade

        TI EtherCAT slave supports upgrading the application using FoE. User can download and execute an upgraded version of the application from an EtherCAT master without disturbing the basic EtherCAT communication (without reset of PRU-ICSS running EtherCAT firmware). Note that this is a sample implementation ONLY for customers implementing SemiConductor Device Profile: Firmware upgrade over EtherCAT v0.1.11. Steps to be followed to do firmware upgrade from TwinCAT master is described here.

       

This application is dependent on drivers.lib, am335x_platform.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 dependent on drivers.lib, am335x_platform.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 module 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, am335x_platform.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.

PowerLink

Powerlink slave demo application is based on openPOWERLINK stack, openMAC and openHUB. It is located in “powerlink_slave” folder. A xdd (device description file) is located in “DeviceDescription” folder and can be modified as per user requirements. User can also build the powerlink demo application in “powerlink_slave” folder with CCS5.2 but will at-least need compiler version TMS470_4.11 to build successfully. Compiler version TMS470_5.0.1 can be downloaded via the CCSv5 Update Wizard (Help->Check for Updates or Help->Install New Software...).

This application is dependent on drivers.lib, am335x_platform.lib, platform.lib, sys_bios_driver.lib and powerlink_stack.lib. The project files for these libraries are included in the SDK and they can be rebuild with any modification required except powerlink_stack.lib which needs a pre-release version of TMS470 compiler for ARM. Upon modifying and building libraries, user should re-build the application as well.

Powerlink sample application will toggle digital output LEDs on top of J17 (in IDK) or below J9 (in ICE) in a pattern sent by the master . This indicates that slave is up and doing data exchange. To test Powerlink sample application user can use openPOWERLINK master, it is a live cd based master and can be downloaded freely from SYS TEC ELECTRONIC Website

Following are steps to make openPOWERLINK master to work with our slave:

1. Boot the Laptop or PC from the CD which has openPOWERLINK master on it.
   
2. Once boot has completed, there will be a openPOWERLINK icon on the desktop. Double click that and a GUI will appear with “Start Powerlink” button.
   
3. Connect the Ethernet port of PC or Laptop to Ethernet port “J3” on ICE board and to Ethernet port “J9” on IDK board with a Ethernet cable. If ICE (or IDK) is not the first slave in the chain then please make sure that port “J3” on ICE board (and port “J9” on IDK board) receives the uplink traffic (packets coming from the master) and other port receives the downlink traffic (packets coming from slaves down in the chain).
   
4. Assign the NODE ID by putting jumper’s or using UART. This is described in more detail in “Assigning NODE ID” section. OpenPOWERLINK master only polls for slaves which have NODE ID of 1, 32, 110 and 253.
   
5. Insert the SD Card in ICE (or IDK) and power-on the board. User can also boot from SPI Flash.
   
6. Start the openPowerlink master by clicking the “Start Powerlink” button.
   
7. Powerlink master GUI will also show digital inputs, digital outputs and node id of slaves which are connected in the Powerlink network.
   
8. Once the master and slave’s go to operational mode, digital bulbs will start toggling on the GUI.
   
9. Wireshark can be used to capture the packets. It comes with the master when you boot from the CD.
   

Working with other commercially available Powerlink PLC’s:

1. The powerlink slave is tested against B&R PLC (Power Panel 500) only. User may need to change the device description file (xdd) to make our powerlink application work with commercial available PLC’s.
   

Assigning NODE ID:

Every slave has to be assigned a NODE ID. Following are possible ways to assign it on ICE:

1. Using Jumper’s: On ICE board use the jumper’s on pins “J9” to assign the NODE ID.
   
2. Using UART: If no Jumper is connected on “J9” pins than application prompts user to provide the NODE ID through UART.User has to connect to ICE uart and start Tera-Term on PC. Application waits for 15 seconds for user to press “Enter” key on key-board, if pressed then application asks user to enter NODE ID.
   
3. Default: In above step if user doesn’t press enter in 15 seconds then application by default assigns NODE ID of 1.
   

 On IDK, application doesn’t take the NODE  ID from Jumper’s. Only option 2 and 3 is valid for IDK.

Digital Inputs:

Application take a value of 1 by default for digital inputs and only 8 bit digital input is supported by the application. User can use UART serial console to set the desired digital input values. When key “I” is pressed, digital input value is incremented by 1. When key “d” is pressed, digital input value is decremented by 1. This way it is possible to assign all the possible values to digital input except value of 0. As of now application does not read digital inputs from board and this will be enabled in next release.

Port Connection Requirement:

• Powerlink master should be connected only to Ethernet Port 1 (J3) on ICE or IDK board. Port 1 should be used for uplink traffic.
• Ethernet Port 0 (J2) can be connected to the next slave in chain. Port 0 should be used for downlink traffic.
  

Compiler Requirement to Build Powerlink application and Stack:

To build Powerlink application and Stack projects in CCS, user would need to obtain a pre-release version of TMS470 compiler for ARM. These projects cannot be build using compilers TMS470_4.9.1 or TMS470_4.9.5 which come along the CCS. This limitation comes because these compilers do not support packed structures which are used inside openPowerlink stack. As of June 2012 the production version of TMS470_5.0.1 is available via the CCSv5 Update Wizard (Help->Check for Updates or Help->Install New Software...).

Profibus

NOTE: As per the SLA terms, TI cannot distribute the PROFIBUS slave stack from Technologie Management Gruppe (TMG) Code in source format. The evaluation library is provided with this release. For production use, one has to obtain the license directly from TMG.

This application is dependent on drivers.lib, am335x_platform.lib, sys_bios_driver.lib, utils.lib, platform.lib, system.lib, and profibus.lib. The project files for these libraries except for profibus.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.

We have used PROCENTAC's ProfiTrace 2.6.1 to test TI PROFIBUS DP slave sample app though any PROFIBUS master can be used. Here is the link to set up PROCENTAC's ProfiTrace 2.6.1 master http://www.procentec.com/downloads/profitrace/ProfiTrace2-Manual-EN.pdf

Quick guide to set up TI slave with master: http://processors.wiki.ti.com/index.php/PROFIBUS_DP_slave_demo_setup_on_AM335x

Set up the board as below:

• On master side:
  • Copy PRU_OCDA.gsd file provided in the SDK into master GSD library
  • Scan the GSD library in the master
  • Create/Add "AM335x Evaluation Module (EVM)" slave in the project/network
  • Add modules (for e.g. 8byte input, 8byte output which is default) for the slave and activate
  • Initialize master, set baud rate, and operate

• On slave side:
  • For ICE setup: Set Jumper on J7 (pin 1 and 2), J6, and J5 as shown and remove Jumper J4
  • After powering on the board the bootloader will load the APP from SDMMC/SPI flash/NOR flash into DDR/Internal RAM/Cache
  • The boot logs can be seen on serial console
  • The APP waits for 5 sec to obtain the station address from serial console, if nothing is set then assumes the default station address 5. For changing the station address connect serial console as shown in the above snap shots. Hit Enter key to change station address, then enter the valid station address and hit enter again to start the APP. For ICE board after powering on and connecting the serial console, press the reset button to set the station address.
  • APP prints the menu on serial console.
    • Input can be changed by pressing 'i' on keyboard
    • master output updates are seen on serial console and output byte 3 toggles the LEDs on top of J17 (in IDK) or below J9 (in ICE) in a pattern sent by the master on byte3 (enable watchdog/modify I/O)
    • 'd' gives the DP status - 0x80 or 0x81 indicates the data exchanges, 0x0 indicates that data exchange is stopped

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 execute accordingly.

Building Full Feature EtherCAT Application

The ethercat example application found in $(IA_SDK_HOME)\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 $(IA_SDK_HOME)\protocols\ethercat\ecat_appl. This folder also includes the configuration xml file to be used for testing and it can be found in $(IA_SDK_HOME)\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.01 from ETG website and extract it to a local folder.
   
2. Apply ( See Apply instructions below) TI_ECAT.patch file found at $(IA_SDK_HOME)\protocols\ethercat_slave\ecat_appl\patch on extracted Beckhoff stack code.
   
3. Copy those patched Beckhoff source files (.c and .h) to $(IA_SDK_HOME)\Protocols\ethercat_slave\ecat_appl\EcatStack
   
4. Launch CCS and import ecat_appl project found at $(IA_SDK_HOME)\Protocols\ethercat_slave\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.4\sdk\protocols\ethercat_slave\ecat_appl\patch -d c:\SSC_V5i0\SlaveFiles\src

Generating AM335x EtherCAT sources using Beckhoff SSC Tool

This configuration tool facilitates working with the Beckhoff ET9300 EtherCAT Slave Stack Code (SSC).It allows reducing the size of the EtherCAT slave stack code by removing unused code parts depending on the desired configuration.

This tool can be used to generate EtherCAT sources for TI AM335x. However, the generated files will not have TI specific changes to the stack code. TI specific changes can be added by patching the SSC tool generated source file.

Below given are the steps to be followed.

1. Download TIAM335x_SSC_cml_patch.zip and extract to a local folder.
2. Install SSC tool version .1.2.0 and launch it
   
3. Create a new project by clicking File->New
   
4. Select "Custom Configuration" and "TI AM335x Sample <Texas Instruments Incorporated>"
   
5. Update the configuration using xml file in attached zip file.
   

            * Go to Tools->Options and select “Configuration” tab

            * Click on “+’ sign

            * Select the stored xml file click OK.

1.  Modify the values of following variables as given. ( These variables can be located by selecting various nodes shown under "EtherCAT Slave" on the left pane of SSC tool).
   

                * EOE_SUPPORTED                        - 1
                * FOE_SUPPORTED                        - 1
                * FOE_SAVE_FILES                         - 1
                * DC_SUPPORTED                           - 1
                * BOOTSTRAPMODE_SUPPORTED  - 1

1. Save the project
2. Click "Project->Create new Salve Files" - This generate the ETherCAT Source files for TI AM335x device.
3. Now apply the patch file on top of the generated source file. On successful patch process, the source now includes all TI specific changes and can be used to build a full featured EtherCAT application.
            
   
   

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  $(IA_SDK_HOME)\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 $(IA_SDK_HOME)\Protocols\ethercat_slave\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 executed from NOR Falsh.
   

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

1. Import Bootloader project found at $(IA_SDK_HOME)\starterware\build\armv7a\cgt_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  $(IA_SDK_HOME)\starterware\build\armv7a\cgt_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 predefined macros as follows. For IDK, include HW_IDK  and remove SPI macro. For ICE, include HW_ICE and SPI.
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 $(IA_SDK_HOME)\starterware\binary\armv7a\cgt_ccs\am335x\evmAM335x\bootloader 
   

Generating Executable Binary - Post Build Script

Post build script file(post_build.bat) can be found at $(IA_SDK_HOME)\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 & SD , 1-MMCSD Card, 2- NOR Flash,3- SPI 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" "3"
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 SD card and 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"

6. 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" "3" "0x80000000" "0x80000000"

Concatenating ARM and PRU binaries

SDK provides a utility(isdk_merge.exe) to concatenate ARM side binary file and PRU binaries into a single file.This can be found at $(IA_SDK_HOME)\Tools\isdk_merge.

This is useful when both ARM and PRU binaries are stored in SPI flash.   For example, EtherCAT application built in IRAM build configuration expects both ARM side binary and PRU firmwwares at SPI Flash memory. By concatenating these files, multiple flashing operation is being eliminated.

Usage

   isdk_merge <output_file> <1st_input_file> <offset_from_beg_of_first_file> <2nd_input_file> <offset_from_beg_of_sec_file> <3rd_input_file>

Description

   output_file -  The full name of concatenated file to be generated

   1st_input_file - The full name of first file to be concatenated

   offset_from_beg_of_first_file - The offset at which the second file need to be placed with respect to the begening of first file

   2nd_input_file - The full name of second file to be concatenated

   offset_from_beg_of_sec_file - The offset at which the third file need to be placed with respect to the begening of second file

   3rd_input_file - The full name of third file to be concatenated

Example

   isdk_merge C:\TI\ecat_appl_pru.bin C:\TI\ethercat_SPI.bin 0x78000 C:\TI\ecat_frame_handler_flash.bin 0x4000 C:\TI\ecat_host_interface_flash.bin

Technical Support and Product Updates

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