StarterWare 02.00.00.06 User Guide

NOTE
Before starting to use the drivers and applications please read information on how to build and use StarterWare package.
StarterWare examples print messages on the UART Serial Console running on the host. Hence, 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. Please ensure that the local echo setting for the terminal is turned off.

System Configuration

An AM335x SoC integrates a Cortex-A8 core which can act as the overall system controller, a Cortex-M3 core to manage entry/exit of various power down modes, associated memories and peripherals.

This section describes the guidelines for programming on the AM335x SoC System.

The ARM Subsystem

StarterWare exports APIs for configuring Cortex-A8 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, for MMU can be found in /include/armv7a/mmu.h and the APIs for configuration and maintenance operations of cache can be found in /include/armv7a/cache.h

• Features Not Supported
  • StarterWare does not support Security extension features.

Programming Guidelines

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 non-privileged 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.

Branch prediction is enabled by default during initialization. Separate APIs are provided for enabling/disabling instruction and data cache. Also, APIs are given for invalidation and cleaning of caches. Invalidating 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.

StarterWare supports one level of paging with one-to-one mapping. That is, virtual address will be equal to physical address. However, we can define separate regions with its own desired attributes like cache policies, access permissions etc.

The application shall define the master page table. MMUInit() will initialize the master page table with fault entries. mmu.h file exports a structure type named REGION. With the help of this, we can specify each memory region with intended attributes such as section, start address, number of pages, memory type, number of pages in the region, security type and access permissions. MMUMemRegionMap() will update the page table for a memory region. After the desired regions are mapped, MMU can be enabled using MMUEnable(). The APIs for configuring MMU are exported in /include/armv7a/mmu.h

StarterWare exports APIs for Cache maintanance operations. CacheEnable/Disable() APIs can be used to enable/disable Caches. For maintaining cache coherency for non-shareable memory, cache maintanance operations are provide. For example, CacheDataInvalidateAll() can be used to invalidate the contents of Data Cache and CacheDataCleanAll() can be used to write all the contents of Data Cache to memory to make the Data Cache and memory coherent. The APIs for cache operations are exported in /include/armv7a/cache.h

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, priority 0 being the highest. Note that the SoC doesnt support routing of interrupts to FIQ. The API functions exported are listed in /include/armv7a/am335x/interrupt.h

Note : StarterWare implements only Prioritized IRQ Handler. However, if prioritization is not desired, all interrupts can be assigned the same priority level. For example, if all interrupts in an application are assigned priority level 0, no IRQ preemption will occur.

• Prioritized IRQ Handler Execution Sequence

1. Save ARM Core Register Context (IRQ is disabled in CPSR by the ARM core on jumping to the IRQ vector).
2. Save the current IRQ threshold value. We need to change this for preventing any same or lower priority interrupt happening.
3. Get the active IRQ priority and set it as the new threshold value.
4. Enable new IRQ Generation at INTC. Here we acknowledge the IRQ and INTC can generate a new IRQ anytime.
5. Enable IRQ generation in CPSR of ARM core and switch to System mode of ARM core (All ISR will be executed in System mode).
6. Get the vector table and jump to the ISR of active IRQ. The link register is programmed to return here after executing ISR.
7. Return from the ISR.
8. Disable IRQ generation in CPSR of ARM core and switch back to IRQ mode (We have the context saved in IRQ stack).
9. Restore the threshold value.
10. Restore ARM Core Register Context and return from IRQ handler.

• Features Not Supported
  • Routing of interrupts to FIQ
  • Security extension features in the interrupt controller.

Programming Guidelines

Interrupt Service Routines are part of the application.The application shall decide the priority level to be assigned for each interrupt. Also, there should be a registered interrupt service routine for each system interrupts enabled for processing.

• The following sequence can be used to set up the Cortex A8 interrupt controller for a system interrupt.
  • 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 interrupt shall be routed to IRQ.
  • Enable the system interrupt at AINTC using IntSystemEnable().
  • Enable IRQ in CPSR using IntMasterIRQEnable()

The API IntRawStatusGet can be used to read the raw status of a system interrupt and IntPendingIrqMaskedStatusGet() API can be used to read the masked status of interrupts routed to IRQ.

Example Configurations

• Example Configurations For Interrupt Controller
  
  • 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.
  • The irqPreemption (examples/evmAM335x/irq_preemption/) application demonstrates IRQ preemption by assigning different priority levels to UART, RTC and Timer interrupts. UART interrupt is given the lowest priority and Timer is given the highest priority. The application demonstrates RTC ISR preempting UART ISR and Timer ISR preempting RTC ISR. Messages will be printed on the UART console at the entry and exit of each ISR.
• Example Configuration For Cache and MMU
  
  • The example application uartEdma_Cache (examples/evmAM335x/cache_mmu) 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 memory mapped peripherals regions are configured as device memory which cannot be cached. The OCMC/DDR memory are marked as cacheable with the following attributes.
    • Memory Type - Normal Memory
    • Inner Cache(L1 Data cache) - Write through, No Allocate on Write
    • Outer Cache(L2 Unified cache)- Write Back, Write Allocate
  • When cache example application is compiled two executable are generated. They are,

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

Execution sequence

1. Populate a buffer with lower case alphabets, a..z.

2. Send the buffer via DMA onto the serial console. a..z gets printed on the console

3. Enable Cache and Populate the buffer with upper case alphabets, A..Z.

4. Send the buffer via DMA onto the serial console. a..z gets printed on the console
uartEdma_CacheFlush - This executable demonstrates the cleaning of the cache before a third party (EDMA) tries to access the buffer from the main memory.

Execution sequence

1. Populate a buffer with lower case alphabets, a..z.

2. Send the buffer via DMA onto the serial console. a..z gets printed on the console

3. Enable Cache and Populate the buffer with upper case alphabets, A..Z.

4. Clean the Data CacheSend the buffer via DMA onto the serial console.A..Z gets printed on the console

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 Beaglebone
  • The board has a USB-to-serial port. Connect this mini USB port to the host via a USB cable. This connection will help to display messages on the serial console on the host. Ensure that the USB-to-serial driver is installed on the host machine and proper port is selected in the host serial terminal application.

A serial terminal application should be running on the host. 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 compliance with the Philips Semiconductors Inter-IC bus (I2C-bus) specification version 2.1. The HSI2C module supports only Fast mode (up to 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 constraint that the module input frequency is limited between 12MHz and 24MHz for proper operation, which is achieved by a first level divisor, which is called the pre-scaler. The actual output clock or the operating clock frequency is obtained by the programmed clock divisor value. The clock divisor value is obtained by the formula provided in the HSI2C chapter of AM335x TRM.

The programming sequence for HSI2C can be found here.

EEPROM Application

Executing the Example application

A serial terminal application should be running on the host.

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 Example 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 Example 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. A serial terminal application should be running on the host. 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-To-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 should be running on the host. 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

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-up line. 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 should be running on the host.

• 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 Watchdog Timer 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 should be running on the host.

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 bits per pixel (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.

EHRPWM

Introduction

The enhanced High Resolution PWM module in AM335x is able to generate complex pulse width waveforms with minimal CPU overhead or intervention. The ePWM module represents one complete PWM channel composed of two PWM outputs: EPWMxA and EPWMxB. Each ePWM instance is identical with one exception. Some instances include a hardware extension that allows more precise control of the PWM outputs. This extension is the high-resolution pulse width modulator. The programming sequence for EHRPWM can be found here.

• Modules used in this example
  • EHRPWM

Example Application

The example application is provided for only TI AM335x EVM. The example application demonstrates the rotation of Haptics Motor present on the Daughter Card.

• Notes
  • The EVM should have the CPLD programmed for controlling Haptics Motor via eHRPWM.
  • The EVM has to be kept in profile 4.

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 programmable FSM (Finite State Machine) Sequencer that supports 16 steps. A step is a general term for describing which input values to send to the AFE (Analog Front End), 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

A serial terminal application should be running on the host.

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

When the example application is loaded on the target and executed, in order to calibrate it will ask user to touch at three different corners prompted on the serial console. Once calibration is done, then whenever there is a 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 Touchscreen conversion for a 4-wire, 5-wire, or 8-wire resistive panel. It also has a programmable 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 step, please refer to Touchscreen/ADC chapter in AM335x Technical Reference Manual(TRM).

Programing sequence for ADC can be found here.

Example Application

A serial terminal application should be running on the host.

• 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 voltage 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

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.

A serial terminal application should be running on the host.

• 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.
• A serial terminal application should be running on the host.

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 pattern (to the user specified 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. A serial terminal application should be 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 spare area.
   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. Repeat 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.
• A serial terminal application should be running on the host.

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/.

A serial terminal application should be 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.

A serial terminal application should be 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 demonstrates different power management modes in OOB Demo example application.For more details please refer here.

Graphics

The graphics library(grlib) is reused from StellarisWare. StarterWare delivers graphics examples based on raster device abstraction layer (DAL) APIs which can be used as reference and/or adapted for user's requirements. For more information on graphics library 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.

• The application demonstrates the below listed peripherals.
  • Ethernet
  • Audio
  • Real Time Clock
  • Timer
  • UART
  • Raster
  • Touchscreen
  • Accelerometer
  • Audio Buzzer
  • Temperature Sensor
• The demo application also supports Dynamic Voltage Frequency Scaling(DVFS). The desired OPP can be selected and the demo application executes further in the selected OPP. Different OPPs supported and the associated Voltage and ARM Core Operating Frequencies are listed in the below table.

	Voltage	Frequency
OPP50	0.95V +/- 4%	275 MHz
OPP100	1.1V +/- 4%	500 MHz
OPP120	1.2V +/- 4%	600 MHz
SR Turbo	1.26V +/- 4%	720 MHz

• The application also demonstrates different power saving modes. The supported power saving modes are

1. Deep Sleep 0,
2. Deep Sleep 1

Different wake sources can be selected for waking up from the power down mode. The wake sources supported are Touchscreen, Timer1, UART0 and GPIO0_2 (Push Button SW9 on the AM335x EVM). For more information on power consumption refer here.

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
• EDMA
• UART-0
• I2C-0,1
• DMTimer-2
• ECAP-0
• RTC
• Interrupt Controller
• Graphics Library

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

• A serial terminal application should be running on the host.
• 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.
  • 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.
  • 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.

• 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	130,644	20,076	4,866,056	1,185,144	Includes buffers for peripherals context save/restore, 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
ehrpwm_haptics	6,652	0	512	56
hsMmcSdRw	37,348	772	3,168	504
hsi2cEeprom	10,252	4	580	56
hsi2cEeprom_edma	13,900	10	568	56
irqPreemption	18,116	4	512	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
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
game	48,588	296	3,141,232	158,106	Includes raw audio file
grlib_demo	50,304	4424	1,580,488	90,364	Includes raw audio file

Test Framework

A test environment can be used to test the example applications for StarterWare. The software is available in the release package under '/test_bench' folder. The scope of testing will be limited to the scenarios the example applications will be able to cover. Further details are available here.

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.