StarterWare 02.00.00.05 User Guide

NOTE
Before starting to use the drivers and applications please read information on how to build and use StarterWare package.

System Configuration

This section describes the guidelines for programming on the AM335X SOC System.

The ARM Subsystem

The AM335X contains ARM Cortex-A8 core, associated memories and peripherals. The Cortex-A8 CPU acts as the overall system controller. The Cortex-A8 can operate in ARM state or Thumb state. The operating modes supported are User Mode(non privileged mode), FIQ mode, IRQ mode, Supervisory mode, Abort mode, System mode, Monitor mode and Undefined mode. The Cortex-A8 ARM subsystem also has MMU, and 32kB L1 Instruction Cache, 32kB L1 Data Cache and 256kB L2 unified cache. CP15 co-processor controls the MMU and Caches.

StarterWare exports APIs for configuring the CPU to operate in privileged mode or non privileged mode and APIs to configure MMU and Cache. The APIs for configuration of the CPU can be found in /include/armv7a/cpu.h and the APIs for configuration of the coprocessor can be found in /include/armv7a/cp15.h

• Features Not Supported
  • Security extension features
  • Nested interrupts

Programming

Applications can execute in privileged or non-privileged (user) mode of ARM. On entry to the main() function of application, the system will be in privileged mode. However, the application can switch to nonprivileged mode (user mode) using CPUSwitchToUserMode() and back to privileged mode using CPUSwitchToPrivilegedMode() at any point of time. While executing in user mode, the application shall not access system resources which needs privileged access. The privileged mode used in StarterWare is system mode of Cortex-A8 core. Note that all ISRs will be executing in privileged mode.

The Cortex-A8 core CP15 shall be used for cache maintanance operations and enabling/disabling branch prediction. Branch prediction can be enabled using CP15BranchPredictionEnable(). Separate APIs are provided for enabling/disabling instruction and data cache. Also, APIs are given for invalidation and cleaning of caches. Flushing a cache will clear it of any stored data. Cleaning a cache will force it to write the dirty values to main memory. Note that MMU (Memory Management Unit) shall be enabled before enabling the data cache.

• Creat Page Table. The page table starting address shall be aligned to 16kB by default.
• Set the translation table base register with the starting address of the page table using Ttb0Set()
• Enable MMU using MMUEnable()

Cache MMU Example application

Cortex-A8 has supports two levels of caches. Separate L1 instruction and data cache and L2 unified cache. The example application demonstrates the usage of MMU and cache by direct mapping of virtual memory to physical memory. The pages are divided into 1MB sections with only one level of translation. A page can be either cacheable or non-cacheable. The OCMC/DDR memory are marked as cacheable with the following attributes.

• Section Cacheable Memory Attributes:
  • Non-Secure access.
  • Read/Write access in both user and privileged mode.
  • Executable Code can be present in this section.
  • The section falls into Domain 0.
  • Memory type is Normal Memory
  • Outer Cache Policy is Write Back, Write Allocate
  • Inner Cache Policy is Write Through, No Write Allocate

All other memory are maked non-cacheable, with the following attributes.

• Section Non-Cacheable Attributes:
  • Non-Secure access.
  • Read/Write access in both user and privileged mode.
  • Executable Code can not be present.

When cache example application is compiled two ELF executable(.out) are generated. They are,

1. uartEdma_Cache.out. This executable demonstrates the effects of not cleaning the cache before a third party (like the EDMA) tries to access the buffer from the main memory.
2. uartEdma_CacheFlush.out. This executable demonstrates the cleaning of the cache before a third party (like the EDMA) tries to access the buffer from the main memory.

• Execution sequence of uartEdma_Cache.out

1. Lower case alphabets, a..z, is populated to buffer in the Main Memory (DDR). Note that the cache is not yet enabled
2. Cache is enabled for entire Main Memory (DDR).
3. EDMA is programmed to transfer data from buffer to serial console.
4. Lower case alphabets, a..z, will be printed on the serial console. This is because in step 1, the contents were written to main memory since cache was not enabled
5. Upper case alphabets, A..Z is populated to buffer. Since buffer is cached, the data populated(A..Z) is updated only to cache and not to Main Memory
6. EDMA is programmed to transfer data from buffer to serial console.
7. a..z will be printed on the serial console. This is because EDMA always transfer data from main memory.

• Execution sequence of uartEdma_CacheFlush.out

1. Lower case alphabets, a..z, is populated to buffer in the Main Memory (DDR). Note that the cache is not yet enabled
2. Cache is enabled for entire Main Memory (DDR).
3. EDMA is programmed to transfer data from buffer to serial console.
4. Lower case alphabets, a..z, will be printed on the serial console. This is because in step 1, the contents were written to main memory since cache was not enabled
5. Upper case alphabets, A..Z is populated to buffer. Since buffer is cached, the data populated(A..Z) is updated only to cache and not to Main Memory
6. Cache is cleaned. When cache is cleaned the data that has got cached(A..Z) is written back to main memory. Now both cache and main memory contains same data.
7. EDMA is programmed to transfer data from buffer to serial console.
8. A..Z will be printed on the serial console.

Interrupt Controller

AM335x uses Cortex A8 interrupt controller as an interface between different peripherals of the system and the Cortex A8 core interrupt lines. The Host Cortex A8 Interrupt Controller is responsible for prioritizing all service requests from the system peripherals and generating either nIRQ or nFIQ to the host. It has the capability to handle up to 128 requests which can be steered/prioritized as A8 nFIQ or nIRQ interrupt requests. However, StarterWare doesn’t support nesting of interrupts within host interrupts (FIQ and IRQ). The API functions exported are listed in /include/armv7a/am335x/interrupt.h

• Features Not Supported
  • Nesting of interrupts
  • Security extension features in interrupt controller

Programming

The application shall decide whether a system interrupt shall be mapped to FIQ or IRQ. Interrupt Service Routines are part of the application. There should be a registered interrupt service routine for all system interrupts enabled for processing.

• The following sequence can be used to set up the Cortex A8 interrupt controller for a system interrupt.
  • Enable IRQ in CPSR using IntMasterIRQEnable()
  • Initialize the Cortex A8 interrupt controller using IntAINTCInit(). This will reset the interrupt controller.
  • Register the ISR using IntRegister(). After this point, when an interrupt is generated, the control will reach the ISR if the interrupt processing is enabled at the peripheral and interrupt controller.
  • Set the system interrupt priority and the required host interrupt generation controller using IntPrioritySet(). The system interrupt can be routed to either IRQ or FIQ. FIQ has higher priority than IRQ.
  • Enable the system interrupt at AINTC using IntSystemEnable().

The API IntRawStatusGet can be used to read the raw status of a system interrupt and IntPendingIrqMaskedStatusGet or IntPendingFiqMaskedStatusGet APIs can be used to read themasked status of interrupts routed to IRQ or FIQ respectively .

Example configuration

The uartEcho (examples/evmAM335x/uart/) application demonstrates the interrupt handling for UART interrupts. The sample application uses UART0 peripheral to demonstrate interrupt processing. The UART0 system interrupt is mapped to host interrupt line IRQ. UART0Isr() is the Interrupt Service Routine registered for this system interrupt.

Serial Peripherals

UART

Introduction

The UART controller present in AM335x is compatible with the 16C750 standard. There is a 64-byte FIFO each for Transmitter and Receiver which holds the outgoing and incoming data respectively. There are programmable and selectable transmit and receive FIFO trigger levels for DMA and Interrupt request generation. The UART can transit to Sleep mode with complete status reporting capabilities in both normal and sleep modes. There are provisions for Hardware Flow Control (RTS/CTS) and Software Flow Control (XON/XOFF). The UART can generate two DMA requests and 1 interrupt request to the system.

• Operational modes that are not supported in Software
  • IRDA/CIR modes of operation

The programming sequence for UART can be found here.

Executing the Example application

• For TI AM335X EVM
  • Connect the serial port on the baseboard to the host serial port via a NULL modem cable.
• For Beagle Bone
  • Connect the mini USB port on the EVM to the host via a USB cable. This will be used to display messages on the serial console. Ensure that the driver is installed and proper port is selected on the host serial terminal application.

A serial terminal application (like teraterm/hyperterminal/minicom) shall be running on the host. The host serial port is configured at 115200 baud, no parity, 1 stop bit and no flow control. Please ensure that the local echo setting for the terminal is turned off. When the example application is loaded on the target and executed, a string is printed on the serial terminal showcasing transmission. After this, it indefinitely expects for characters input from the user on the serial terminal and echoes the same back on the terminal. Whereas in DMA application, it expects the user to input specified number of characters and later echoes them back.

• Modules used in Interrupt application
  • UART-0
  • Interrupt Controller

• Modules used in DMA application
  • UART-0
  • EDMA
  • Interrupt Controller

HSI2C

Introduction

The HSI2C component is in complaint with the Philips Semiconductors Inter-IC bus (I2C-bus) specification version 2.1. The HSI2C module supports only Fast mode (upto 400 kbps) of operation.HSI2C can be configured to multiple master-transmitters and slave-receivers mode and multiple slave-transmitters and master-receivers mode.HSI2C also could be configured to generate DMA events to the DMA controller for transfer of data. The HSI2C driver library exports a set of APIs to configure and use HSI2C module for data transfers. The APIs are exported in /include/hsi2c.h

• Features Not Supported
  • High speed data transfer

Clocking Constraint

This module input clock is derived from the Peripheral PLL, which is 48MHz. HSI2C module imposes a contraint that the module input frequency is limited between 12MHz and 24MHz for proper operation, which is achived by a first level divisor, which is called the pre-scaler. The actual output clock or the operating clock frequency obtained by calculating the clock divisor as per the formula provided in the HSI2C peripheral user's guide

The programming sequence for HSI2C can be found here

EEPROM Application

Executing the application

The example application needs that the serial port on the EVM is 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.

When the example application hsi2cEeprom is loaded and executed on the target, the data flashed to the eeprom is read over I2C bus and printed on the serial console.This functionality is demonstrated both in interrupt and DMA mode

• Modules used in the Interrupt Mode of example
  • I2C-0
  • Interrupt Controller
  • UART-0

• Modules used in the DMA Mode of example
  • I2C-0
  • EDMA
  • Interrupt Controller
  • UART-0

Temperature Sensor Application

Temperature sensor is a device which is used to measure the surrounding temperature. On Revision 1.1A EVM (generally called Beta EVM) a Digital Temperature sensor with part number TMP275 is present and can be accessed through I2C.

Executing the application

• Modules used in this example
  • I2C-1
  • Interrupt
  • UART-0

When the temperature sensor example application is loaded and executed on the target,the temperature measured by the sensor is displayed on serial console. If there is any change in temperature, then the temperature measured will be updated and displayed on the serial console.

Accelerometer application

An accelerometer is an electromechanical device that will measure acceleration forces. On Revision 1.1A EVM (Beta EVM) an accelerometer with part number LIS331DLH is present. This can be accessed through I2C/SPI. The StarterWare accelerometer example application measures the angle of tilt of the EVM with respect to earth. This is done by measuring the amount of static acceleration due to gravity.

Steps to measure the acceleration along x, y and z axis.

• Acceleration experienced by the device at different axes is measured from OUT_L and OUT_H register of accelerometer device. For example acceleration along Z axis is measured by reading the data present in OUT_Z_L and OUT_Z_H. Similarly for Y and X axis.

• Measured data(OUT_Z_H + OUT_Z_L) is shifted by 4. This is because of the 12bit representation of the device.

• One bit of the measured data corresponds to (1/1024)g i.e 0.9mg.

• So by multiplying the ((OUT_Z_H + OUT_Z_L) >> 4) by 0.9mg gives the acceleration along the Z axis. Similarly for y and x axis.

• Cosine(acceleration measured along z axis / g) gives the angle by which device is tilted with respect to earth.

• The direction to which device is tilted is interpreted based on the sign of the data measured along a axis.For example when device tilted by 30 degree right,then data measured along z axis is positive value. Similarly when device tilted by 30 degree left, then data measured along z axis is negative value.

Note: 'g' is acceleration due to gravity. 1g corresponds to 1024 digital value.

Executing the application

• Modules used in this example
  • I2C-1
  • Interrupt
  • UART-0

When the accelerometer example application is loaded and executed on the target, the angle of tilt of EVM is displayed on serial console.

McSPI

Introduction

McSPI is a general-purpose receive/transmit, master/slave controller that can interface with up to four slave external devices or one single external master. It allows a duplex, synchronous, serial communication between CPU and SPI compliant external devices (Slaves and Masters). McSPI supports Slave Chip Select Pin, SPI Enable I/O Pin to improve overall throughput by adding hardware handshaking. It supports maximum frequency of 48MHz. McSPI could be configured to generate DMA event to EDMA controller for transfer of data. McSPI device abstraction layer exports set of APIs to configure and use McSPI Module for data transfers.

The programming sequence for McSPI can be found here

Executing the Example application

Set the EVM in profile 2 (SW8[1] = OFF, SW8[2] = ON, SW8[3:4] = OFF). For more details refer to EVM reference manual. Connect the serial port on the baseboard to the host serial port via a NULL modem cable. Make sure that a serial communication application (Tera Term/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. Certain data is written to SPI flash using SPI bus. Then, the written data is read back. The read data is compared with the data that was written. If they match, then an appropriate message gets displayed on the serial communication console. The same functionality is demonstrated in both DMA and interrupt mode of operation

• Modules used in McSPI-Interrupt application
  • McSPI-0
  • UART-0
  • Interrupt Controller

• Modules used in McSPI-EDMA application
  • McSPI-0
  • UART-0
  • EDMA
  • Interrupt Controller

DCAN

Introduction

The Dual controller area network (DCAN) module is a high integrity serial communications protocol for distributed real time applications. This module is compliant to the CAN 2.0B protocol specification. This device has two DCAN modules, referred to as DCAN0 and DCAN1.

The DCAN module performs CAN protocol communication according to ISO 11898-1. Additional transceiver hardware is required for the connection to the physical layer (CAN bus). The DCAN module has a message RAM, and for communication to occur on the CAN bus, individual message objects have to be configured. The message objects are stored in the message RAM and it can store up to 64 message objects.

All functions concerning the handling of messages are implemented in the message handler. The message handler is a state machine that controls the data transfer between the single ported message RAM and the CAN cores Tx/Rx shift register and the functions handled by message handler are acceptance filtering, the transfer of messages between the CAN core and the message RAM, and the handling of transmission requests as well as the generation of interrupts or DMA events. The DCAN peripheral is provided with a set of registers called as interface registers which control the CPU read/write access. IF1 and IF2 used for read/ write access and IF3 used only for read access.

The programming sequence for DCAN can be found here

Executing the Board-Board example application

The example application demonstrates board-to-board CAN communication. The setup requirements are,

• Two TI AM335x EVMs in profile 1 (SW8[1] = ON, SW8[2:4] = OFF). (Lets call them as EVM1 and EVM2)
• Connect the two boards using CAN cables. On AM335x Beta EVM CAN1 is available on J11(DB9 connector) port. The CANH and CANL pins of the CAN transceiver are connected to pins 7 and 2 of J11 respectively. Pin 3 of J11 is ground. Connect the respective pins(7-7, 2-2, 3-3) on both boards.
• Connect the serial port on the baseboard to the host serial port via a NULL modem cable for both the boards.
• A serial terminal application (like teraterm/hyperterminal/minicom) shall be running on the host and the host serial port is configured at 115200 baud, no parity, 1 stop bit and no flow control. Please ensure that the local echo setting for the terminal is turned off. Let us call the console where EVM1 and EVM2 display messages as Console1 and Console2 respectively.

Execute DCANTxRx application on EVM1 and DCANLpBk application on EVM2.

The below message will be printed on Console1
Please Input
1)Transmit a single data frame
2)Transmit 'n' data frames

And, the below message will be printed on Console2
*** Waiting for data ***

On Console1 if option 1 is selected by entering '1' then it will prompt to input bytes as
Please input data not exceeding 8 characters

On entering 1-8 data bytes the data frame will be transmitted from EVM1 -> EVM2 -> EVM1.

On reception the data will be printed on the serial terminals for verification.

If option 2 is selected on Console1 then ‘n’ data frames/messages can be transmitted, where data(8 bytes) will be populated by the application itself.

• Modules used in DCAN board-board application
  • DCAN-1
  • UART-0
  • Interrupt Controller

NOTE
For proper CAN communication on the bus, all the nodes should be set for the same bit-rate. To set the required bit-rate on the CAN bus the function CANSetBitTiming can be used which is present in dcan_frame.c file of dcanTxRx and dcanLpBk applications. CANSetBitTiming internally calls the API DCANBitTimingConfig which can be found in the DCAN DAL.

DMTimer

Introduction

DMTimer is a 32 bit timer and the module contains a free running upward counter with auto reload capability on overflow. The timer counter can be read and written in real-time (while counting). The timer module includes compare logic to allow an interrupt event on a programmable counter matching value. A dedicated output signal can be pulsed or toggled on overflow and match event. This output offers a timing stamp trigger signal or PWM (pulse-width modulation) signal sources. A dedicated output signal can be used for general purpose PORGPOCFG. A dedicated input signal is used to trigger automatic timer counter capture and interrupt event, on programmable input signal transition type. A programmable clock divider (prescaler) allows reduction of the timer input clock frequency. All internal timer interrupt sources are merged in one module interrupt line and one wake-upline. Each internal interrupt sources can be independently enabled/disabled.

The programming sequence for DMTimer can be found here

Executing The Example Application

• For TI AM335X EVM
  • Connect the serial port on the baseboard to the host serial port via a NULL modem cable.
• For Beagle Bone
  • Connect the mini USB port on the EVM to the host via a USB cable. This will be used to display messages on the serial console. Ensure that the driver is installed and proper port is selected on the host serial terminal application.

A serial terminal application (like teratem/hyperterminal/minicom) is runnning on the host. The host serial port is configured at 115200 baud, no parity, 1 stop bit and no flow control.

• Modules used in this example
  • DMTimer-2
  • UART-0
  • Interrupt Controller

The example application demonstrates the use of timer as a countdown timer, counting down from 9 to 0. When the example application is executed, a string "Tencounter:". After this it starts to count down from 9 to 0.

WatchDog Timer

Introduction

The watchdog timer is an upward counter capable of generating a pulse on the reset pin and an interrupt to the device system modules following an overflow condition. The watchdog timer serves resets to the PRCM module and serves watchdog interrupts to the host ARM and DSP. The reset of the PRCM module causes warm reset of the device. The watchdog timer can be accessed, loaded, and cleared by registers through the L4 interface. The watchdog timer has a 32-kHz clock for their timer clock input. The watchdog timer connects to a single target agent port on the L4 interconnect. The default state of the watchdog timer is enabled and not running. Instance 0 of watchdog timer is secure.

The programming sequence for Watchdogtimer can be found here

Executing The Example Application

• For TI AM335X EVM
  • Connect the serial port on the baseboard to the host serial port via a NULL modem cable.
• For Beagle Bone
  • Connect the mini USB port on the EVM to the host via a USB cable. This will be used to display messages on the serial console. Ensure that the driver is installed and proper port is selected on the host serial terminal application.

A serial terminal application (like teraterm/hyperterminal/minicom) is runnning on the host. The host serial port is configured at 115200 baud, no parity, 1 stop bit and no flow control.

The example application wdtReset demonstrates the use of WatchDog Timer. When the example application is executed, a string "Program Reset! Input any key at least once in every 4 seconds to avoid a further reset." will appear on the screen. If no key is input, program will restart within few seconds.

• Modules Used
  • Watchdog timer-1
  • UART-0

Raster LCD

Introduction

Raster LCD Controller is used to display image on LCD panel.Raster LCD Controller is a synchronous LCD interface. It also support 1/2/4/8/16/24 bpp configuration in packed or unpacked mode.

The programming sequence for Raster LCD can be found here

Executing the Example Application

The example application configures the raster to display image having 24bpp and stored in unpacked mode.

Before executing the raster LCD program, make sure that raster LCD is hooked on to the board. When the program is executed,the image will be displayed on LCD.

• Modules used in this example
  • LCD-0
  • Interrupt Controller

The example application works in double frame buffer mode. The ISR handles only End-Of-frame interrupt. The frame buffer registers are updated in each End-of-frame interrupt.

TouchScreen

Introduction

The touchscreen module is an 8 channel general purpose ADC,with optional support for interleaving Touch screen conversation for 4-wire,5-wire, or 8-wire resistive panel. It also has a programable FSM sequencer that supports 16 steps.A step is a general term for describing which input values to send to the AFE, and how, when , and which channel to sample.For more information on steps please refer to touchscreen TRM.

The programming sequence for TouchScreen can be found here

Executing the Example Application

The example application needs that the serial port on the EVM is 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.

• Module used in this example.
  • ADC/Touchscreen Controller.
  • UART-0
  • Interrupt Controller

When the example application is loaded on the target and executed,inorder to calibrate it will ask user to touch at three different corners promted on the serial console.Once calibration is done,then when ever there is touch on the panel,coordinates are displayed on the serial console until the touch is released

ADC

Introduction

The touchscreen/ADC module is an 8 channel general purpose ADC,with optional support for interleaving Touch screen onversation for 4-wire,5-wire, or 8-wire resistive panel. It also has a programable FSM sequencer that supports 16 steps.A step is a general term for describing which input values to send to the AFE,and how,when , and which channel to sample. For more information on steps please refer to touchscreen/ADC TRM.

Programing sequence for ADC can be found here here

Example Application

The example application needs that the serial port on the EVM is 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.

• Module used in this example
  • ADC/Touchscreen controller
  • UART-0
  • Interrupt Controller

When the example application is loaded on the target and executed, the voltage measured across the ANO and AN1 line is displayed on the serial console. The example application pull up the AN0 line and pull down the AN1 line by configuring the internal AFE transistors.Thus volatge across the AN0 is 1.8 nand voltage across AN1 is 0.

GPIO

Introduction

Each GPIO module provides 32 dedicated general-purpose pins with input and output capabilities. These pins can be configured for the following applications:

• Data input (capture)/output (drive)
• Keyboard interface with a debounce cell
• Interrupt generation in active mode upon the detection of external events. Detected events are processed by two parallel independent interrupt-generation submodules to support biprocessor operations.

The APIs are exported in include/gpio_v2.h

The programming sequence for GPIO can be found here.

LCD Back-light application

• For TI AM335X EVM the example application switches the LCD back-light ON/OFF periodically.
• For Beagle Bone, when the example application is executed, a user LED on the EVM blinks periodically.

• Module Used
  • GPIO-0

Haptics Motor application

The Haptics Vibrator present on the General Purpose Daughter board is 'Pico Haptics 304-100' from Precision Microdrives. A GPIO pin controls the ON and OFF of a transistor switch that is present in series with the Haptics Motor. The haptics motor shall rotate when the transistor in ON (circuit is closed) and stops when the transistor is OFF (circuit is open).

Executing the application

This application turns the Haptics Motor ON and OFF alternately for periodic intervals. It uses Timer peripheral to interrupt the processor after a certain period has elapsed. The modules used in this example are:

• GPIO-1
• DMTimer-7
• Interrupt

Audio Buzzer application

The Audio buzzer present on the General Purpose Daughter board is 'AI_1027' from PUI Audio Inc. A GPIO pin controls the ON and OFF of a transistor switch that is present in series with the audio buzzer. The audio buzzer shall rotate when the transistor in ON (circuit is closed) and stops when the transistor is OFF (circuit is open).

Executing the application

This application turns the Haptics Motor ON and OFF alternately for periodic intervals. It uses Timer peripheral to interrupt the processor after a certain period has elapsed. The modules used in this example are:

• GPIO-1
• DMTimer-7
• Interrupt

RTC

Introduction

The RTC provides a time reference to an application running on the device. The current date and time is tracked in a set of counter registers that update once per second. The time can be represented in 12-hour or 24-hour mode. The calendar and time registers are buffered during reads and writes so that updates do not interfere with the accuracy of the time and date. Alarms are available to interrupt the CPU at a particular time, or at periodic time intervals, such as once per minute or once per day. In addition, the RTC can interrupt the CPU every time the calendar and time registers are updated, or at programmable periodic intervals.

The APIs are exported in include/rtc.h

The programming sequence for RTC can be found here.

Example Application

• For TI AM335X EVM
  • Connect the serial port on the baseboard to the host serial port via a NULL modem cable.
• For Beagle Bone
  • Connect the mini USB port on the EVM to the host via a USB cable. This will be used to display messages on the serial console. Ensure that the driver is installed and proper port is selected on the host serial terminal application.

Run a serial communication application (Tera Term/HyperTerminal/minicom) on the host. The host serial port is configured at 115200 baud, no parity, 1 stop bit and no flow control.

• Modules used in this example
  • RTC
  • UART-0
  • Interrupt Controller

• On running the application, the user sees a request on the terminal to enter time and calendar information. On entering the information, the application programs these time and calendar information in the respective registers of RTC. The time and calendar information currently held by the RTC registers are displayed on the terminal.

Memory Devices

AM335x is integrated with the GPMC(General Purpose Memory Controller) to which NAND is interfaced and MMC controller through which MMC/SD is accessed.The StarterWare package contains the device abstraction layers (DAL) for these peripherals and example applications to demonstrate the same.

MMC/SD

AM335X devices have multimedia card high-speed/secure data/secure digital I/O (MMC/SD/SDIO) host controller, which provides an interface between microprocessor and either MMC, SD memory cards, or SDIO cards.

The programming sequence for MMC controller can be found here

The StarterWare MMC/SD driver design overview can be found here.

The example application provided as part of the package demonstrates the use of MMC/SD card with FAT filesystem. The application only supports reading from the card and basic shell like interface is provided for user experience. Only SD cards are supported

Preparing the SD card

The SD card needs to be prepared, by FAT formatting it as follows.

1. Choose a SD card and a USB based or similar SD card reader/writer.Plug it to a Windows host system.
2. Run the TI_SDCard_boot_utility_v1_0.exe executable (which is in release package tools/sd_format/ directory). Select the SD Card drive name, location of MLO file and application image path.
3. Click on 'Proceed'.
4. After the formatting is complete, the card is ready to be populated with the files required.
5. Copy any files into the newly formed file system.
6. Safely eject/remove the card from the host, unplug the card reader, remove the SD card. The SD card is ready for use.

Executing the example application

• For TI AM335X EVM
  • Set the EVM in profile 0 (SW8[1:4] = OFF). For more details refer to EVM reference manual.
  • Connect the serial port on the baseboard to the host serial port via a NULL modem cable.
• For Beagle Bone
  • Connect the mini USB port on the EVM to the host via a USB cable. This will be used to display messages on the serial console. Ensure that the driver is installed and proper port is selected on the host serial terminal application.

1. Using CCS with appropriate target configuration and GEL files, connect to the target AM335x.
2. Insert the card into the base board MMC/SD slot.
3. Load the application ELF binary (.out) on the target via CCS.
4. Click "Go" or "Run".
5. A shell like interface comes up on the serial console.
6. Following commands are support in this interface
   1. help - Displays the help contents, available commands
   2. ls - lists the current directory
   3. pwd - shows the current/present working directory
   4. cd - Change the current/present working directory
   5. cat <file_name> - dump the contents of the file (A text file is preferred, since binary/non-ascii files may corrupt the serial console display with garbage)

• Modules used in this example
  • MMCHS-0
  • MMC/SD Library
  • FAT File System
  • UART-0

NAND

AM335x have GPMC(General Purpose Memory Controller) to which NAND is interfaced . GPMC an unified memory controller to interface external memory devices like NAND, NOR, Asynchronous SRAM etc. By configuring the bit fields in the GPMC registers, the application can be able to access the mentioned type of device through GPMC.

The programming sequence for GPMC can be found here

Along with GPMC, ELM module is used to support error calculation and correction capability.

The programming sequence for ELM for error calculation can be found here

The StarterWare NAND driver design overview can be found here.

The example application provided as part of the package demonstrates the use of NAND. The application writes default data patern (to the user specifed block, page for number of pages) and read the data and checks for the data integrity. If the macro NAND_DATAINTEGRITY_TEST_WITH_FIXED_ADDR is defined, application does the erase, write and read for default block and pages. Also, By default application uses BCH 8-bit as an ECC type in DMA mode. To change the ECC type, operating mode(polled or DMA) etc change the corresponding field in the nandCtrlInfo, nandDevInfo data object(s) before controller initialization.

Executing the example application

1. Set the EVM in profile 0 (SW8[1:4] = OFF). For more details refer to EVM reference manual.
2. Connect the serial port on the baseboard to the host serial port via a NULL modem cable. Ensure that a serial terminal application (Teraterm/HyperTerminal/minicom )is running on the host.
3. Using CCS with appropriate target configuration and GEL files, connect to the target AM335x.
4. Load the application ELF binary (.out) on the target via CCS.
5. Click "Go" or "Run".
6. NAND Device Info is printed on the serial console and asks for the user to enter block, page number and number of pages information.
7. Then application does the following ---
   1. Checks whether block is bad or not.
   2. If not erases the block.
   3. Writes the data with ECC enabled.
   4. Write the ECC data to the sparearea.
   5. Reads the data with ECC enabled and checks for the ECC errors.
   6. If any ECC errors, and these are correctable corrects the data else prints the error message.
   7. Checks for the data integrity.
   8. Repeates the above steps for user entered number of pages.

• Modules used in this example
  • GPMC-0
  • EDMA
  • Interrupt Controller
  • UART-0

Ethernet

Introduction

The AM335x uses CPSW (Common Platform Ethernet Switch) for ethernet interface. The peripheral is compliant to IEEE 802.3 standard, describing the Carrier Sense Multiple Access with Collision Detection (CSMA/CD) Access Method and Physical Layer specifications. CPSW has one host port and two slave ports, each of which are capable of 10/100/1000 Mbps with MII/GMII/RGMII interfaces. The CPSW also has an Address Lookup Engine which processes all received packets to determine which port(s) if any that the packet should the forwarded to. The ALE uses the incoming packet received port number, destination address, source address, length/type, and VLAN information to determine how the packet should be forwarded. The CPSW incorporates an 8kB internal RAM to hold CPDMA buffer descriptors (also known as CPPI RAM). The MDIO module implements the 802.3 serial management interface to interrogate and control up to 32 Ethernet PHYs connected to the device by using a shared two-wire bus. The application shall use the MDIO module to configure the auto negotiation parameters of each PHY attached to the CPSW slave ports, retrieve the negotiation results, and configure required parameters in the CPSW module for correct operation.

The programming sequence for CPSW can be found here.

The StarterWare Ethernet design overview can be found here.

Example applications

The Ethernet examples for Beagle Bone demonstrates MII interface and TI AM335x EVMs demonstrates RGMII interface operating at 100Mbps.

• For TI AM335X EVM
  • Set the EVM in profile 0 (SW8[1:4] = OFF). For more details refer to EVM reference manual.
  • Connect the serial port on the baseboard to the host serial port via a NULL modem cable.
  • Connect the Ethernet port on the baseboard of the EVM to a LAN port.
• For Beagle Bone
  • Connect the mini USB port on the EVM to the host via a USB cable. This will be used to display messages on the serial console. Ensure that the driver is installed and proper port is selected on the host serial terminal application.
  • Connect the Ethernet port on the baseboard of the EVM to a port in the network.

The StarterWare AM335X ethernet application over lwIP stack is demonstrated using two applications.

1. An embedded web server application, which hosts a default page when requested
2. An echo server application, which demonstrates a simple data transfer between a client and server.

• Modules used in this example
  • CPSW
  • MDIO
  • PHY
  • Interrupt Controller
  • UART-0
  • lwIP Stack

In the following examples, the IP address can be configured in enet_lwip/include/lwipopts.h. The macro STATIC_IP_ADDRESS shall specify the static IP address to be used. If a dynamic IP address to be used, STATIC_IP_ADDRESS shall be defined as 0.

Embedded Web Server application

A sample http server application is demonstrated, using lwIP stack. This is located at /examples/evmAM335x/enet_lwip/.

Before executing the example, ensure that the serial port on board is connected to the host machine and a serial terminal application (like TeraTem/Hyperterminal/minicom) is running on the host. The example uses a serial console to display the dynamic IP address assigned for the EVM by the DHCP server. Flash the Ethernet example application or load the executable ELF (.out) file on to the EVM.

• Testing by connecting peer to peer with a host machine:
  • Connect the Ethernet port on board to the host Ethernet port via an Ethernet cable
  • Assign a static IP address to the host machine.
  • Run a DHCP server application on the host.
  • Execute the example application
  • Note the dynamic IP address assigned which displayed on the serial console.
  • Access the http server application default page using http://<ip_address>/index.html via a web browser on the host.
  • Ensure that proxy server is not used for the dynamic IP address assigned for the board.

• Testing by connecting to a corporate network:
  • Connect the Ethernet port on board to a port on the corporate network.
  • Execute the example application.
  • Note the dynamic IP address assigned which displayed on the serial console.
  • Access the http server application default page using http://<ip_address>/index.html via a web browser on the host.
  • Ensure that proxy server is not used for the dynamic IP address assigned for the board.

Echo server application

A sample echo server-client set up is demonstrated, using lwIP stack. The echo server, which runs on the target just echos back the received data to the sender - typically the client running on a Linux host in this case. The client then compares the sent and received data for integrity and the result is printed on the client console. The client application is also delivered as part of package and is located at StarterWare_xx_yy_mm_pp/host_apps/enet_client.

Before executing the example, ensure that the serial port on board is connected to the host machine and a serial terminal application (like TeraTem/Hyperterminal/minicom) is running on the host. The example uses a serial console to display the dynamic IP address assigned for the EVM by the DHCP server. Flash the Ethernet example application or load the executable ELF (.out) file on to the EVM.

• Testing by connecting peer to peer with a host machine:
  • Connect the Ethernet port on board to the host Ethernet port via an Ethernet cable
  • Assign a static IP address to the host machine.
  • Run a DHCP server application on the host.
  • Execute the example application on the target

• Testing by connecting to a corporate network:
  • Connect the Ethernet port on board to a port on the corporate network.
  • Execute the example application on the target.
  • Note the dynamic IP address assigned which displayed on the serial console.

Now execute the client application on the host.

   $ ./client <ip-address-announced-by-the-echo-server>

The client prints the status of the application on the console

makefsfile utility

'makefsfile' may be used to create file system images to embed in ethernet applications offering web server interfaces. It can be used to generate an ASCII C file containing initialized data structures, which represents the html pages which need to be embedded in the application. 'makefsfile' is at "tools/makefsfile/", provided in source and binary form. Executing the binary without any input provides a detailed help menu which guides the user.

Executing makefsfile utility

$ ./makefsfile
This prints a detailed help menu

$./makefsfile -i <directory-path>
This takes an input directory path which contains the saved html pages which need to be converted to a C file which can be embedded in an application. The file fsdata.c will be generated inside directory from where makefsfile is executed.

McASP

Introduction

Audio in StarterWare is played via the Multichannel Audio Serial Port (McASP). The McASP functions as a general-purpose audio serial port optimized for the needs of multichannel audio applications. The McASP can be used for time division multiplexed (TDM) stream, Inter-IC Sound (I2S) protocols, and inter component digital audio interface transmission (DIT). The McASP has separate transmit and receive sections that can operate synchronously or independently. The McASP can be configured for external or internal clock and frame sync signals. It has 16 serialisers each of which can be configured as transmitter or as a receiver.

The APIs of McASP are exported to include/mcasp.h

The programming sequence for McASP can be found here.

Example application

The McASP example demonstrates audio data transmission and reception in I2S mode using DMA.

• Set the EVM to profile 0 (SW8[1:4] = OFF). For more details refer to EVM reference manual.
• Plug in a 3.5mm audio jack which takes analog audio signals into the audio LINE IN of the EVM. Also, plug a 3.5mm audio jack which is connected to a headphone or speakers into the audio LINE OUT of the EVM.

The audio input on the LINE IN is looped back to the audio ouput on LINE OUT of the EVM.

• Modules used in this example
  • McASP-1
  • EDMA
  • I2C-1
  • Interrupt Controller

More information about the Audio application can be found here.

USB

AM335x has two integrated Mentor Graphics USB controller(USB0 and USB1) with external PHY. The MSUB controller supports both host and device functionalities with OTG capability. StarterWare USB package provides all the necessary software support for the MUSB controller which includes, Device Abstraction Layer (DAL), the USB Stack for CDC,MSC and custom Bulk Device class and the sample application. More about starterware USB can be found here.

Power Management

StarterWare provide power management example applications for deep sleep1 and deep sleep0. The applications demonstrates the steps to be followed to enter and exit deep sleep states. The examples are demonstrated in AM335X EVM. For more details please refer here.

Out-Of-Box Demo Application

Introduction

The out-of-box demo application demonstrates the capabilities of the device abstraction layer of StarterWare. The application executable can be found in binary/armv7a/gcc/am335x/evmAM335x/demo/. The demo application can be navigated through Touchscreen and/or Ethernet.

Modules Used

The modules used in the out-of-box demo application are listed below.

• LCD-0
• ADC/Touchscreen Controller
• CPSW
• MDIO
• PHY
• lwIP Stack
• McASP-1
• UART-0
• I2C-1
• DMTimer-2
• ECAP-0
• RTC
• Interrupt Controller

Design overview

The out-of-box demo application combines functionality of multiple peripherals to demonstrate StarterWare capabilities to be used for various use case scenarios. The application is designed to be driven by both Touch and Ethernet. The programming sequence is given below.

• Enable the module clock and pin multiplexing for the peripherals used.
• Initialize the AINTC, register all the interrupt handlers, enable the interrupts at AINTC
• Initialize the required peripherals and enable peripheral level interrupts.
• Display the banner image
• Start playing the audio tone. This tone will be looped forever.
• Detect a touch on the LCD or a click on the embedded page accessed via ethernet.
  • If a touch is detected, validate the coordinates. If the coordinates are verified, display the proper image and demonstrate the peripheral.
  • If a click is detected, display the proper image and demonstrate the peripheral.

The application maintains a list of contexts which include

• The image to display
• Number of Icons in the image
• Specification for each Icon in the image. The specification includes
  • Valid coordinates of an Icon
  • The action to be taken when the valid coordinates are touched.

If a touch is detected in the current context, the touch coordinates are validated based on the specification of each Icon in the image, and the corresponding action will be taken.

When a button on the embedded page is clicked, the click information will be updated by the CGI handler which is registered during the initialization of the http server. Based on this information, the current context will be updated to display the proper image and demonstrate the peripheral.

Executing The Application

• Set Up Requirments
• For Beagle Bone
  • The mini USB port to be connected to the host. This mini USB connection is used for displaying messages on the serial console on the host, if the port is properly selected.
  • A serial terminal application (like Tera Term / HyperTerminal / minicom) should be running on the host.
  • Ethernet port on board connected to a port on the LAN.
  • The Demo Application for Beagle Bone can be driven via Ethernet. On booting the demo application the dynamic IP address assigned to the Beagle Bone will be displayed on serial console. The embedded web page can be accessed anytime using http://<ip address>/index.html via a web browser on the host. Ensure that proxy server is not used for the dynamic IP address assigned for the board.

• For TI AM335X EVM
  • The serial port on the baseboard of the EVM to be connected to the host serial port via a NULL modem cable.
  • A serial terminal application (like Tera Term / HyperTerminal / minicom) should be running on the host.
  • The host serial port is configured at 115200 baud, no parity, 1 stop bit and no flow control.
  • LCD(Raster) module to be plugged into the EVM
  • Ethernet port on the base board connected to a port on the LAN.
  • Audio LINE OUT of the EVM connected to headphone/speakers with 3.5mm audio jack.
  • Some snaps from EVM OOB demo.

            OOB Menu

           

           OOB Ethernet IP Acquired

          

       

           RTC demo

          

           ECAP Demo      

          

• • The Demo Application for TI AM335X can be driven via Touch and/or Ethernet. On booting the demo application on TI AM335X EVM, a banner will be displayed on the LCD, followed by an introductory slide. If the demo is to be driven via Ethernet, please note the dynamic IP address displayed on the serial console. The embedded web page can be accessed anytime using http://<ip address>/index.html via a web browser on the host. Ensure that proxy server is not used for the dynamic IP address assigned for the board.

Memory Usage Statistics

This section provides the code and data section for every device abstraction layer library object and the executables, generated using TMS470 Code Generation Tools. Note that the code is compiled for ARM instruction set.

• Device Abstraction Layer

DAL object	text size (bytes)	data size (bytes)
watchdog	448	0
usbphyGS70	48	0
usb	3,576	0
uart_irda_cir	3,724	0
tsc_adc	2,012	0
rtc	2,784	0
raster	1,628	0
phy	772	0
mdio	204	0
mcspi	2,312	0
mcasp	1,420	0
mailbox	388	0
hsi2c	1,260	0
hs_mmcsd	1,388	0
gpmc	3,448	0
gpio_v2	1,024	0
elm	1,048	0
edma	2,808	4
ecap	544	0
dmtimer	608	0
dcan	2,400	0
cpsw	1,580	0
cppi41dma	3,660	219,844

• Executables

Binary	Code (B)	Data (B)	BSS (B)	Const(B)	Notes
uartEcho	9,424	56	512	56
i2cAccelerometer	12,820	360	538	56
adcVoltMeasure	14,376	4	528	56
buzzerBeep	9,300	4	512	56
boot	29,296	556	1844	8
uartEdma_Cache_Cache	14,284	4	17,188	56
uartEdma_Cache_CacheFlush	14,964	4	17,188	56
dcanLpBk	15,660	32	540	56
dcanTxRx	16,356	32	540	96
demo	105,780	442	4,800,512	769,996	Includes audio raw tone and image data
dmtimerCounter	13,060	4	512	56
enetEcho	55,876	64	83,272	256
enetLwip	56,896	64	81,920	3,564
gpioLCDBacklight	6,668	0	512	56
hapticsMtrCtl	9,300	4	512	56
hsMmcSdRw	37,348	772	3,168	504
hsi2cEeprom	10,252	4	580	56
hsi2cEeprom_edma	13,900	10	568	56
dmtimerCounter	13,160	8	512	56
mcaspPlayBk	19,864	68	48,536	144
mcspiFlash	15,636	12	1,296	56
mcspiFlash_edma	19,760	2	1,548	56
nandReadWrite	30,068	4	4,684	56
pmDs0TimerWake	29,892	16,196	532	9,972
pmDs0TSCWake	29,708	16,200	532	9,972
pmDs1DevMode	26,464	15,068	552	3,082,036	Includes image data
pmDs1Mode	28,004	15,064	552	1,546,004	Includes image data
rasterDisplay	10,968	4	532	1,536,088	Includes image data
rtcClock	16,780	0	512	56
hsi2cTempSensor	12,696	4	532	56
tscCalibrate	18,052	8	564	80
uartEcho	9,424	56	512	56
uartEcho_edma	13,808	92	780	56
usb_dev_bulk	36,140	190	1,556,480	5,764	Includes graphics releated buffers
usb_dev_mouse	43,808	270	1,556,480	5,445	Includes graphics releated buffers
usb_dev_msc	42,876	206	18,552,832	3,168	Includes graphics releated buffers
usb_dev_serial	43,380	222	1,556,480	5,844	Includes graphics releated buffers
usb_host_mouse	36,416	158	1,774,292	2,700	Includes graphics releated buffers
usb_host_msc	42,204	433	245,760	544
wdtReset	11,304	0	512	56

API Reference Guide

Driver library API Reference Guide is attached here. The API reference guide is in zip format. So please unzip and save the .chm document to local disk to view its contents.