StarterWare Getting Started 02.01.XX.XX

Document License

This work is licensed under the Creative Commons Attribution-Share Alike 3.0 United States License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/us/ or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA.

StarterWare Overview

StarterWare provides a no-OS platform support for ARM/DSP based SoCs. StarterWare provides Device Abstraction Layer (DAL) libraries and peripheral/board level sample/demo examples that demonstrate the capabilities of the peripherals. This package includes the following components:

Aegis StarterWare Architecture Block Diagram

• Device Abstraction Layer Library. This contains device abstraction layer APIs for supported peripherals.
• Peripheral Examples. This contains the sample applications which shall demonstrate some of the capabilities of the respective peripheral by using the Device Abstraction Layer APIs.
• System Configuration code. This contains the primary code that sets up the processor core and prepares the system for execution of the sample application.
• Platform Code. This contains the EVM specific initialization code. This code sets up the EVM specifics like Pin Multiplexing, communication with I/O expander and similar board specific tasks that shall enable proper execution of the applications.

Directory Structure

|----StarterWare_#.#.#.#
|-- Software-manifest.pdf
|-- docs
|   |-- ReleaseNotes-#.#.#.#.pdf
|   |-- UserGuide-#.#.#.#.pdf
|-- drivers
|-- examples
|   |--evmAM335x
|      |-uart
|-- grlib
|-- usblib
|-- mmcsdlib
|-- nandlib
|-- host_apps
|-- build
|   |--armv7a
|      |--gcc
|         |--am335x
|             |--drivers
|             |--system_config
|             |--evmAM335x
|                 |--uart
|                 |--platform
|                 |--bootloader
|-- binary
|   |--armv7a
|      |--gcc
|         |--am335x
|             |--drivers
|             |--system_config
|             |--evmAM335x
|                 |--uart
|                 |--platform
|                 |--bootloader
|-- include
|   |-- hw
|   |-- armv7a
|       |--am335x 
|-- platform
|   |-- evmAM335x
|   |-- beaglebone
|-- system_config
|   |--armv7a
|      |-- am335x
|      |-- gcc    
|-- bootloader
|   |--include
|   |--src
|-- third_party
|-- tools
|-- utils
|-- test_bench

• drivers - This directory contains the source files for the driver library APIs.
• examples - Examples provided as part of the package showcase some (not all) functionality of the peripheral. This depends on the availability of a peripheral instance and its association, Pin Multiplex settings etc on the EVM. Thus examples differ between EVMs and thus are classified at the top level based on the EVMs that are intended to be run on. Each example's source files are placed under examples/evmAM335x/<example_name>/ directory.

• grlib - This folder contains source files for the Graphics library.

• mmcsdlib - This folder contains source files for the MMCSD library.

• nandlib - This folder contains source files for the NAND library.

• usblib - This folder contains source files for USB library.

• host_apps - This folder contains files which are used to execute Ethernet examples.

• build - This folder will contain the makefile required to build libraries (drivers, system_config, platform, utils, usblib, grlib etc.) and example applications (uart, mcspi, hsi2c etc.). The build files are grouped based on the tools/compiler used to build them. For example, cgt_ccs/ shall contain the Code Composer Studio (CCS) project files of applications and gcc/ shall only contain GCC makefile of applications. The makefile for GCC to build driver library is under build/armv7a/gcc/am335x/drivers directory. Once built, the library/archive is placed in a tool specific directory under binary/armv7a/gcc/am335x/drivers/. For example, when make is invoked from build/armv7a/gcc/am335x/drivers, the libdriver.a is placed at binary/armv7a/gcc/am335x/drivers/.

• binary - All the executable are placed in this directory. The generated library or executable/binary is placed in an appropriate path under tool specific directory. For example, uartEcho.out built from CGT TI arm compiler will be placed in the following path - binary/armv7a/cgt_ccs/am335x/evmAM335x/uart/ .

• include - The header files for inclusion are all placed under include/. The include files are classified as,
  1. User interface driver headers : For example include/mcspi.h, which contain macro definitions used by peripheral APIs and prototypes of the peripheral APIs.
  2. Processor Family and SoC specific files: Certain processor family specific files like include/armv7a/cpu.h, include/armv7a/mmu.h and SoC specific files like include/am335x/interrupt.h are present.
  3. Register Layer files: Files like include/hw/hw_mcspi.h which contain the peripheral register offset macros and register field token macros.

• platform - Every supported EVM is called as a (hardware) platform inside the package. This exports functions specific to an EVM that usually do (as required) Peripheral Pin Multiplexing settings, Peripheral Clock settings, EVM Profile settings, I/O expander settings etc to enable a peripheral operation on the platform. Peripheral Pin Multiplexing though depends only on the SoC Silicon Package, the availability of the external ports for communication is decided by the EVM. The code in platform is maintained as an entity distinct from the applications/examples to provide a simpler look at the first level.

• system_config - The system configuration and initialization code like the start-up code, interrupt vector initialization, low level CPU specific code etc are provided here. Since this may involve assembly level coding, such code is placed under tools specific directory.

• bootloader - Contains the bootloader specific files.

• third_party - This shall contain software from third party, provided they are used.

• tools - This shall contain software tools used, if any.

• utils - This shall contain user utilizable code. As an example, utils/uartStdio.c contains wrapper functions which uses UART APIs to interface with the user through the serial console.

• test_bench - This folder will contain StarterWare automation test framework and test scripts.

NOTE
Though StarterWare is intended to support multiple processors of the AM/DM family, support may be in a phased manner. The supported list of processors and the associated device abstraction layer of the peripherals as part of the library is mentioned in the release notes for every release.

Host platform Requirements

Building and running StarterWare applications can be from a Windows machine or a Linux machine

A host machine is required only for:

1. Compiling the StarterWare applications
2. Launching CCS v5 and loading and running the applications on the target

Development Host Requirements

For Windows host

TI ARM tools with CCSv5

• Code Composer Studio version CCS 5.4.0.00091 for Windows(needed for (re)building and/or loading and running applications on the target/EVM)
• Serial console terminal application (like Tera Term, minicom, HyperTerminal)
  

IAR Embedded work bench for ARM

• IAR embedded work bench for ARM version 6.50 for Windows(needed for (re)building and/or loading and running applications on the target/EVM)
• Serial console terminal application (like Tera Term, minicom, HyperTerminal)
  

GCC through Cygwin command line

• Linaro tool chain for ARM for Windows
• Cygwin to facilitate GCC build
• Serial console terminal application (like Tera Term, minicom, HyperTerminal)
  

    Note on Cygwin Installation
      Cygwin FAQis avaialable here.
      Cygwin recommended installation procedure is here
      Cygwin installation should be ensured to include GCC, MAKE, BASH, libc, libgcc and other build tools. If unsure install all the packages.

For Linux host

GCC through command line

• Linaro tool chain for ARM for Linux
  
• Serial console terminal application (like minicom)
  

Building application

The StarterWare package contains pre-compiled executable (ELF and binary image) of the peripheral level examples. These were obtained by building the applications using TI ARM compiler. These executable can be executed on the AM335x. The binaries are delivered in release profile build, with optimization level set to O2. StarterWare package also contains the build files and CCS project files to enable the user to rebuild any modifications. StarterWare supports the following compilers/Tools. The Steps to (re)build the examples are detailed here in:

For Windows

• GCC from Command line in Cygwin: Refer here for instructions on building the project.
• TI arm tools through CCSv5 project: Refer here for instructions on importing and building the project.

• IAR Embedded Workbench IDE project: Refer here for instructions on building the project.
  

For Linux

• GCC from Command line in Linux: Refer here for instructions on building the project.

    For CCSv5 getting started guide click here.

    Refer the FAQ's on CCSv5 for more information.

 

Setting Up The Tool Chain

Windows/Cygwin Linaro arm-none-eabi (command line):
1. If a Windows host is used, then Cygwin needs to be installed for gcc build.
2. Application makefiles invoke library makefiles internally.
3. PATH environment variable should contain the path of the compiler/tool chain.
4. LIB_PATH DOS shell environment variable points to the Linaro installation: Ex: LIB_PATH=C:\tools\Linaro.
5. "set CYGPATH=cygpath" to convert Windows native style filenames to POSIX style file names. Not doing this might lead to linker errors while trying to find libc path.
6. Ensure that the Linaro installation path does not contain any white space 

Linux Linaro arm-none-eabi:
1. Application makefiles invoke library makefiles internally.
2. PATH environment variable should contain the path of the compiler/tool chain.
3. LIB_PATH shell environment variable points to the Linaro installation: Ex: LIB_PATH=/opt/linaro/eabi-4_7-2012q4.

Windows TI arm tool chain CCSv5:
1. Ensure that for converting the elf binaries to raw binary format, PATH environment variable is properly updated. Ex: C:\Program Files\Texas Instruments\ccsv5\utils\tiobj2bin.

Flashing binary images and standalone booting

Refer here for instruction.

Loading Executable and Debugging using CCSv5

CCSv5 can be used to load an executable on the Target, run the executable and debug the source code.
The steps for debugging on EVM AM335x can be found here.
The steps for debugging on BeagleBone board can be found here. Similar steps apply for EVM-SK also.

Creating a New CCSv5 Project

The information required to create a new project in CCSv5 is given here.