AM335x SYSBIOS Industrial SDK Getting Started Guide

= Revision History =

Make sure to download and apply always latest version of IA-SDK. There is a new release about every 3 month. Each release comes with full release notes and user guides also hosted on this wiki. Use Category IASDK to find all docs.

= Applies To =

SDK can be used for the below given platforms.


 * TMDXIDK3359 - AM335x IDK (also known as IA EVM)
 * HUG - AM335x IDK Hardware User's Guide


 * TMDXICE3359 - AM335x ICE
 * HUG - AM335x ICE V1 Hardware User's Guide
 * HUG- AM335x ICE V2 Hardware User's Guide

= 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 SYS/BIOS
 * Sample applications demonstrating peripheral use cases
 * Code Composer Studio integrated development environment (IDE) v.6
 * Sample industrial input/output applications over communication protocols such as EtherCAT, PROFIBUS, EtherNet/IP, PROFINET and other Ethernet and serial based fieldbus Industrial Ethernet protocols
 * Evaluation versions of protocol stacks for industrial communications such as EtherCAT, PROFIBUS, EtherNet/IP,PROFINET and many others to facilitate software development

AM335x IDK block diagram



AM335x ICE block diagram

AM335x ICE V2 block diagram



= AM335x Industrial Development Kit (IDK) =

AM335x IDK consists of two boards and they are shown below with components marked.

Processor/Base Board (IA configuration)

 Industrial Automation Daughter Board

= AM335x – Industrial Communication Engine (ICE) V1 =

AM335x ICE is given below with components marked.



= AM335x – Industrial Communication Engine (ICE) V2 =

AM335x ICE is given below with components marked.



= System Requirements =

Hardware

 * AM335x IDK / AM335x ICE V1 / AM335x ICE V2
 * Windows (XP or higher) Host PC with minimum 2GB RAM
 * SD Card for IDK and MicroSD card for ICE

Software

 * AM335x Industrial SDK
 * Code Composer Studio version CCS 6.0.1.00040
 * SYSBIOS 6_41_04_54 Real Time Operating System
 * Network Development Kit (NDK) 2_24_02_31
 * Serial console terminal application (like Teraterm, minicom, HyperTerminal)

 NOTE 1 

This will update the RTSC components to version compatible with CCS6. NOTE 2 
 * To run on CCSv6, make sure you refactor the project after importing it
 * 1) Right click on imported project and select Refactor Option
 * 2) Select Upgrade RTSC Product Versions
 * On CCSv5.5, please make sure you update the Compiler to TIv5.1.5(or above). This is important as the libraries provided in SDK are build using this compiler and not upgrading would result in linker errors.

= SDK Installation =

SDK Setup is a windows executable which installs Industrial SDK Source files, CCS project files, pre-built libraries, documents, tools and other stuffs to the host machine. Note that, setup will not install pre-built applications, they are provided as a separate package.

 NOTE 


 * On Windows 7, sdk installation requires administrator privilege. Install sdk using "Run as Administrator" option.
 * The tools mentioned in the Recommended Software section must be installed before using sdk. They can be downloaded from SYS/BIOS 6.x Product Download Page
 * It's recommended to install XDCTOOLS, SYS/BIOS and NDK in CCS installation folder so that CCS will automatically find these RTSC Packages.

= Boot Modes =

AM335x IDK
The device supports only MMC/SD boot mode through ARM ROM Bootloader. Boot mode selection is determined by the state of the BOOT pins of Switch SW3 and SW4. States of BOOT pins on AM335x EVM for MMC/SD boot mode is given below.

MMC/SD Boot

AM335x ICE
The device supports both SPI and NOR boot mode through ARM ROM Bootloader. Boot boot mode selection is determined by the state of pins on J10. ( See ICE Picture for pin markings) NOR Boot      Pin 1 &amp; 2 shorted  on J10. ROM Bootloader looks for a valid boot image in NOR sector 0 and if found, will execute it from there. If there is no valid image in NOR, SPI boot loader will be executed. SPI Boot     None of the pins on J10 are shorted. ROM Bootloader looks for a valid image in SPI flash and if found,loads it to IRAM and executes it.

AM335x ICE V2
The device supports SPI, MMC/SD and NOR boot mode through ARM ROM Bootloader. Boot boot mode selection is determined by the state of pins on J5. ( See ICE V2 Picture for pin markings) NOR Boot      Pin 1 &amp; 2 shorted  on J5. ROM Bootloader looks for a valid boot image in NOR sector 0 and if found, will execute it from there. If there is no valid image in NOR, SPI boot loader will be executed if present. If SPI bootloader is also not present, SD card bootloader will be executed.

SPI Boot     Pin 2 &amp; 3 shorted  on J5. ROM Bootloader looks for a valid image in SPI flash and if found,loads it to IRAM and executes it. Otherwise, SD card bootloader will be executed if present.

MMC/SD Boot

Pin 2 &amp; 3 shorted on J5. ROM Bootloader looks for a file named 'MLO' in SD card and if found,loads it to IRAM and executes it. Please note that, SPI bootloader should NOT be present in SPI flash.

= Running Pre-Built Applications on AM335x IDK =

The following pre-built applications can be used for a quick start with IDK. SDK release notes will have the information on from where to obtain pre-built binaries for each release,


 * Bootloader
 * EtherCAT Slave Application (The default out of box application shipped with the board)
 * EtherNet/IP Adapter Application
 * Lwip Sample Application
 * Profibus Salve Application
 * LED Demo Application
 * UartEcho Application

Running Application from SD card

 * 1) Download HP USB Disk Storage Format Tool v2.0.6 Portable from the internet.
 * 2) Choose a SD card and a USB based or similar SD card reader/writer.Plug it to a Windows host system.
 * 3) Run the HP USB Disk Storage Format Tool v2.0.6 Portable executable. The executable should automatically detect the SD card plugged via reader as a new 'removable disk'. Else point it to the new disk.
 * 4) Choose FAT32 if the SD card size is greater that 4GB. Else FAT should be good to go.
 * 5) Click on 'Format'.
 * 6) Copy the MLO (boot loader) to the formatted SD Card.
 * 7) Rename application binary as "app" and copy it to SD Card.
 * 8) Make sure that IDK bootmode switches are set for MMC/SD boot. See Boot Modes for details
 * 9) Connect UART cable from PC to IDK
 * 10) Launch Serial Console tool and set the UART Parameters as follows. Baud rate -115200, Data - 8 bit, Parity - None, Stop - 1 bit, Flow Control - None
 * 11) Attach the SD card to IDK MMC/SD Card slot and switch on IDK.
 * 12) Verify that UART Serial console tool has print messages from boot loader and application.

= Running Pre-Built Applications on AM335x ICE V1/V2 =

The following pre-built applications can be used for a quick start with ICE. SDK release notes will have the information on from where to obtain pre-built binaries for each release,


 * Bootloader for SPI, MMC/SD and NOR Flash
 * EtherCAT Slave application for MicroSD card /SPI Flash/NOR Flash (The default out of box application shipped with the board)
 * EtherNet/IP Adapter application for MicroSD card/SPI Flash
 * Lwip Sample application for MicroSD card/SPI Flash
 * Profibus Slave application for MicroSD card/SPI Flash/NOR Falsh
 * LED Demo Application for MicroSD card /SPI Flash
 * UartEcho Application for MicroSD card /SPI Flash

For ICE V1, bootloader can be flashed either into SPI or NOR Flash. See Flashing Binaries section for flashing instructions. Separate binaries are provided for SPI and NOR Flash.

For ICE V2, bootloader can be SD card or flashed either into SPI or NOR Flash. See Flashing Binaries section for flashing instructions. Separate binaries are provided for SPI and NOR Flash.

The SPI and MMC/SD boot loader expects application binary to be either in Micro SD card or in SPI flash. Bootloader will first try to load the application from SD card and if it fails, will try to load the application from SPI flash.

The NOR boot loader expects application binary to be either in Micro SD card or in NOR flash. Bootloader will first try to load the application from SD card and if it fails, will try to find application in NOR flash and will execute in place. Please note that, binaries for SD card and SPI flash are not same.

CPSW/ICSS Mode Selection on ICE V2
Unlike ICE V1, where CPSW MII ports are not populated, ICE V2 development board has both CPSW and ICSS MII ports populated. CPSW and ICSS MIIs are connected to the same RJ45 jacks and can be used on different modes by selecting appropriate hardware muxes(Jumpers). Jumpers J18 and J19 (Please refer ICE V2 picture above) are used for this purpose. CPSW can be selected by connecting a jumper pin between pins 1 &amp; 2. ICSS can be selected by connecting jumper pin between pins 2 &amp; 3.

EtherCAT and PROFIBUS are using ICSS and hence J18 and J19 must have pins 2 &amp; 3 connected.

EtherNet/IP can be executed either over ICSS or CPSW and hence the jumper pins need to be connected based on the requirement.

Running Application from MicroSD card

 * 1) Format Micro SD card using HP USB Disk Storage Format Tool v2.0.6
 * 2) Flash boot loader into ICE SPI flash or Copy MLO to SD card (ICE V2 only)
 * 3) Copy EtherCAT application named as "app" to it.
 * 4) Insert Micro SD card into ICE card slot.

Running Application from SPI Flash

 * 1) Flash boot loader into ICE SPI flash or Copy MLO to SD card (ICE V2 only)
 * 2) Erase boot loader from NOR flash if it exists. ( This is because NOR boot loader will be executed first if both boot loaders exists)
 * 3) Flash application into SPI flash offset 0x20000

Running Application from NOR Flash

 * 1) Flash NOR boot loader into ICE NOR flash
 * 2) Ensure that a jumper is connected between pins 1 &amp; 2 on J10
 * 3) Flash application into NOR flash sector number 1 (For PROFIBUS flash in sector 2)

NOTE : Make sure you erase Sector 1 in case of PROFIBUS, as a valid application in Sector 1 will result in a undesirable behavior

Flashing Binaries to SPI Flash on ICE V1/V2 Using SD Card Flasher
This executable allows user to flash application binary to SPI flash without user interaction and can be found in $(IA_SDK_HOME)\tools\flashing tools\SPI_Flash\pre_built\SD_card_based. This is currently supported only on ICE boards. This flasher flashes the application binary to SPI offset will be flashed to SPI flash offset 0x20000. Flashing progress is indicated by blinking ACT and RUN LEDs on the board. Once the flashing is done, the LEDs stops blinking.

Steps to be followed


 * Copy this binary named "App" found at "${IA_SDK_HOME\tools\flashing tools\SPI_Flash\pre_built\SD_card_based" to SD card
 * Rename the application binary file for SPI flash ( *_SPI.bin ) to "image" and copy to the SD card
 * Power reset board.
 * Wait for the LEDs to stop blinking.

Flashing Binaries to SPI Flash on ICE V1/V2 Using CCS
This section describes how to flash a binary image to the SPI flash on ICE. The pre-built CCS tool for SPI flash(isdk_spi_flasher.out) can be found in $(IA_SDK_HOME)\tools\flashing tools\SPI_Flash\pre_built\CCS_based.

Enter the board type [0-ICE, 1-IDK ] Enter Operation [1 - Flash ] [2 - Erase] : Enter the binary type [0-Bootloader, 1-Other ] Enter the Offset in bytes (in HEX eg:- bootloader :0x0 app : 0x20000) Load .bin file to 0x80100000 Load binary file to Memory - Using LoadMemory Pause Program Execution by pressing the Suspend '||' button             Open Memory window in CCS (View-&gt;Memory Browser) Select "Tools-&gt;Load Memory". Browse and select the .bin file to be loaded )             Select 'TI RAW' for the format and Click 'Next'. (File should be named as *.bin)              Enter 0x80100000 in "Start Address' field.              Select '32 bits' for 'Type-size' field               Keep the swap tick box un-checked.               click 'Finish'               Wait for the memory to be loaded               Press the Green 'Resume' Arrow
 * Make sure that USB cable is connected to PC from ICE
 * Launch CCS
 * Launch Target configuration for XDS100 emulator. See " Target Configuration" section for details.
 * Load GEL file and execute "AM335x_EVM_Initialization" or "AM3359_ICE_Initialization" script(See "GEL File Loading" section for details), if not done.This is to initialize DDR and On-Chip RAM. GEL file can be found in $(IA_SDK_HOME)\tools\gel
 * Load pre-built ${IA_SDK_HOME}\tools\flashing_tools\SPI_Flash\pre_built\CCS_based\isdk_spi_flasher.out  to the ICE EVM. See Launching and Debugging application section for details.
 * Ensure that the binary image (e.g. MLO or ethercat_SPI.bin or profibus_slave_SPI.bin) to be flashed is present in the Windows Machine.
 * Enter the board type when prompted as shown below.
 * Enter the operation when prompted as shown below.
 * For Erase
 * Bootloader - Offset 0, Size 64
 * Application- Offset 20000, Size 248
 * Enter type of the binary to be flashed when prompted as shown below.
 * Enter the offset when prompted as shown below. This offset is the start location from where the image should be flashed. NOTE: This offset should be in hex. In case of boot loader,the offset should be 0x0. In-case of application the offset shall be 0x20000.
 * Pause program Execution and Load binary file into memory 0x80100000 using Load Memory option of CCS-&gt;Memory Browser, when prompted as below . Once load operation is completed, continue flashing by entering 0.

Enter 0 to continue
 * After this the tool should first erase the flash and then start flashing the new image..
 * Finally the following message will shown.
 * Verifying...Success


 * These steps are performed when loading the Bootloader and loading the application
 * Once both have been loaded
 * Disconnect CCS and then turn off the board.
 * Boot the Board &amp; verify

NOTE : If you see an error in CCS console right after loading the Flasher binary, just click on "Resume(F8)"

Flashing Binaries to NOR Flash on ICE V1/V2 Using CCS
This section describes how to flash a binary image to the NOR flash on ICE. The pre-built CCS tool for NOR flash(isdk_nor_flasher.out) can be found in $(IA_SDK_HOME)\tools\flashing tools\NOR_Flash\pre_built.

Enter board type [1 - ICE V1 ] [2 - ICE V2] :
 * Make sure that USB cable is connected to PC from ICE
 * Launch CCS v 5.2 or newer
 * Launch Target configuration for XDS100 emulator. See " Target Configuration" section for details.
 * Load GEL file and execute "AM335x_EVM_Initialization" or "AM3359_ICE_Initialization" script(See "GEL File Loading" section for details), if not done.This is to initialize DDR and On-Chip RAM. GEL file can be found in $(IA_SDK_HOME)\tools\gel
 * Load pre-built isdk_nor_flasher.out to ICE. See Launching and Debugging application section for details.
 * Ensure that the binary image (e.g. boot_NOR.bin or ethercat_NOR.bin or profibus_slave_NOR.bin) to be flashed is present in the Windows Machine.
 * Enter the board type [ 1 for ICE V1 and 2 for ICE V2]when prompted as shown below.

Enter Operation [1 - Flash ] [2 - Erase] :
 * Enter the operation code [ 1 for flashing a binary file and 2 for erasing a sector]when prompted as shown below.

Enter the File Name
 * For Erase
 * Bootloader - Starting sector 0, No. of sectors 1
 * Application- Starting sector 1, No. of sectors upto 6
 * Enter the file name to flash when prompted as shown below. Provide the complete path (e.g.c:\images\boot_NOR.bin)

Enter the Sector [0-15] Load .bin file to 0x80100000 and Enter 0 to continue After this the tool should first erase the flash and then start flashing the new image..
 * Enter the sector number when prompted as shown below. The boot loader has to be flashed to sector 0. The application can be flashed to any other sector.
 * Load binary file into memory 0x80100000 using Load Memory option of CCS-&gt;Memory Browser, when prompted as below . Once load operation is completed, continue flashing by entering 0. (Please see "Flashing Binaries to SPI flash" for load memory instructions.)


 * If flashing is done, "NOR Write complete" message will be shown.
 * Disconnect CCS and then turn off the board.
 * Boot the Board &amp; verify

= SPI Flash Layout - ICE =

AM335X ICE board comes with a SPI FLASH of size 8MB, which is used to store bootloader, application binary and other application specific data.

SPI Flash memory layout is as given below.


 * First 128K (Start Address 0x0) is reserved for bootloader.
 * Next 8064K (Start Address 0x20000) can be used for application binary and/or other application specific data.

For eg, EtherCAT application reserves 512K (Starting from address 0x20000) and uses the memory starting from oxA0000 to store the ESI file.



= Building and Running Sample Application =

Industrial SDK includes many sample applications which demonstrates the device capabilities. Please see Industrial SDK user guide examples section for more details on sample projects. Sample projects contains the project files to enable the user to import the project into CCS and rebuild with any modifications. Steps involved are explained below.

Importing and Building Sample Project in CCS

 * 1) Launch CCS.
 * 2) Click Menu-&gt;File-&gt;Import
 * 3) On new window, Select Code Composer Studio-&gt;Existing CCS Eclipse Projects and click Next.
 * 4) Select "Select search-directory" and browse to locate the sample application directory. SDK examples can be found at $(IA_SDK_HOME)\Examples
 * 5) The project will be listed under "Discovered Projects" and Select the required project from the list.
 * 6) It is recommended to keep "Copy Projects into workspace" tick box un-checked.
 * 7) Click Finish. This will import the project into workspace.
 * 8) The imported project will be shown in CCS Project Explorer tab.
 * 9) Expand the Project directory and double click *.cfg file. This will build the RTSC configuration.
 * 10) Right Click on Project, Select "Build Project". This will build the sample project's .out file.
 * 11) Upon successful build, post_build.bat script file will be executed to generate the binary file which can then be copied to SD card/SPI flash for standalone execution. The generated binaries can be located in directories with build configuration name. See Generating Executable binary section for post build process details.
 * 12) See the CCS Console tab for build logs.
 * 13) All sample applications have Debug and Release configurations.
 * 14) To build for a different configuration, Right click on the project and select Build Configurations-&gt;SetActive-&gt;Debug/Release and build the project once again.

 NOTE 


 * Follow the below procedure after step 8 when using CCS6 to build the application.
 * 1) Right click on imported project and select Refactor Option
 * 2) Select Upgrade RTSC Product Versions
 * This will update the RTSC components to version compatible with CCS6.

Creating a target configuration, if one doesn't exist already.

 * 1) File menu-&gt; New-&gt; Target Configuration File.
 * 2) Filename : AM335xEVM. Check "Use shared location" to be available to anyone who uses the workspace. Click Finish. A window opens up which is to configure the connection details
 * 3) Connection: Choose the host-to-target connection details. For example "Texas Instruments XDS100v2 USB Emulator" for ICE or "Spectrum Digital XDS510 USB Emulator" for IDK, if XDS510 is being used.
 * 4) Device: Type AM335x. AM335x should be available in the device list. Select AM335x or ICE_AM335x
 * 5) Click Save.

Launching and Debugging application in CCS

 * 1) Connect JTAG Emulator to EVM in-case of IDK or Connect USB cable to board in-case of ICE
 * 2) Select View-&gt;Target Configurations. Right click on the required configuration in the list and Select Launch Selected Configuration
 * 3) Right Click on the Cortex A8 listed in Debug view and select Connect. ( Click View-&gt;Debug to view debug window, if not visible. )
 * 4) Load the GEL file and execute initialization script.
 * 5) Once the initialization is completed, Select Run-&gt;Load -&gt;Load Program. Here browse to the required executable and click OK
 * 6) Menu-&gt;Run-&gt;Run. This will execute the application.

 NOTE


 * While launching a debug session for the first time, CCS will ask for the CPU to which the program needs to be loaded. Please select Cortex-A8 and continue.
 * After a successful load, the program is expected to be in suspended state and program counter is pointing to main function . If the program is not in suspended state, Please suspend the program by clicking Run-&gt;Suspend and click Run-&gt;Restart.


 * If there is a valid application in SPI or NOR flash(in their corresponding boot modes), on "System Reset" the application loads right away. This might cause issues on the application you load via JTAG. To avoid this, put a hardware breakpoint at 0x402f_0400(in case of SPI boot mode) or 0x08000000(in case of NOR boot mode) and then do a "System Reset". You can continue with Step 4 after this

GEL File Loading and Script Execution

 * 1) Launch the required Target Configuration
 * 2) Click Tools-&gt;GEL Files
 * 3) Select GEL Files on the newly opened tab.
 * 4) Right click on the empty list box shown on the right side of the tab.
 * 5) Select Load GEL. 
 * 6) Browse to the folder where GEL file is stored and open it.(SDK provided GEL files can be found at ${IA_SDK_HOME}\tools\gel )
 * 7) Once the GEL file is loaded, The scripts available with in GEL file will be shown in Menu-&gt;Scripts.
 * 8) Click on the required script to execute it.

= Technical Support and Product Updates =

For further information or to report any problems on AM335x Industrial SDK, contact arm_mpu_sw_fee@list.ti.com

=Training= The "Intro to TI-RTOS Kernel Workshop" is now available. Follow the link below to find out more. The TI-RTOS Kernel Workshop covers the SYS/BIOS operating system available for all TI embedded processors - C28x, MSP430, Tiva-C, C6000 and AM335x (Cortex A-8). You can take a LIVE workshop (scheduled at various sites around the U.S.) or download/stream the videos of each chapter online and watch at your own pace. All of the labs, solutions, powerpoint slides, student guides, installation instructions, lab procedures, etc., are all available to you. The workshop labs run on all MCU platforms and the C6000. Check it out...

Intro to TI-RTOS Kernel Workshop