Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

StarterWare 01.10.01.01 User Guide

From Texas Instruments Wiki
Jump to: navigation, search

TIBanner.png

NOTE
This page is a work in progress. Please bear with us as we get the contents and sub pages sorted out.


First Steps

This user guide provides detailed information about the OMAPL138 StarterWare libraries and applications. Before diving in to this content, we recommend reading the following introductory material:

System Configuration

This section describes the system configuration library for OMAPL138. For a detailed description of this SOC, please refer to the OMAPL138 system reference guide. In StarterWare, the system configuration library provides simple APIs for interrupt support and cache management.

The ARM Subsystem

The OMAPL138 contains an ARM926 core along with internal memory and several peripheral devices. The ARM926 CPU acts as the overall system controller. The ARM can operate in ARM state or Thumb state. The operating modes supported are User Mode (non-privileged), FIQ mode, IRQ mode, Supervisory mode, Abort mode, System mode and Undefined mode. The OMAPL138 ARM subsystem also has memory management unit (MMU) and separate 16 kB Instruction Cache and 16 kB Data Cache. The CP15 co-processor controls the MMU and Cache.

The StarterWare system configuration library provides 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 are listed in include/armv5/cpu.h, while the APIs for MMU and cache configuration are listed in include/armv5/cp15.h.

Programming

ARM applications can execute in privileged or non-privileged (user) mode. Upon reaching the applications's main() function, 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 time. While executing in user mode, the application cannot access system resources which require privileged access. The privileged mode used in StarterWare is the ARM926 core's system mode. Note that all ISRs are executed in privileged mode.

Separate APIs are provided for enabling and disabling instruction and data cache. Also, APIs are given for invalidating and cleaning cache memory. Flushing a cache will clear it of any stored data. Cleaning a cache will force it to write back the cached values to main memory. Note that the MMU must be enabled to use data cache. The below sequence can be used to configure the MMU.

  1. Create a page table. The page table starting address must be aligned to 16kB.
  2. Set the translation table base register to the starting address of the page table using the TtbSet() API.
  3. Enable MMU using the MMUEnable() API.

Example Configuration

The timer example application (located in examples/evmOMAPL138/timer/) demonstrates executing an application in user mode. Upon reaching main(), the execution is in privileged mode. After calling CPUSwitchToUserMode() application executes in user mode. However, the CPU still has elevated privileges in TimerIsr() since the ISR is executed in IRQ mode, which is a privileged mode of ARM.

Interrupt Controller

OMAPL138 uses the ARM Interrupt Controller (AINTC) to interface between different peripheral devices and the ARM9 core interrupt lines. System interrupts are generated by device peripherals. The FIQ and IRQ of ARM9 core are named as host interrupts. The AINTC maps system interrupts to host interrupts through channels. The AINTC supports up to 101 system interrupts, each of which can be prioritized by mapping to one of 32 channels. Channel 0 and Channel 1 are mapped to FIQ of ARM. Channels 2-31 are mapped to IRQ of ARM. The application developer must decide how to map system interrupts to channel numbers. A single system interrupt cannot be mapped to multiple channels. However, more than one system interrupt can be mapped to a single channel. StarterWare doesn’t support nesting of interrupts within host interrupts. The Interrupt System exports a set of APIs to enable/disable the ARM core interrupts and to configure and use the AINTC. The interrupt APIs are listed in include/armv5/omapl138/interrupt.h.

Programming

The application developer must decide whether a system interrupt should be mapped to FIQ or IRQ. This can be done by mapping each system interrupt used to a particular channel. Interrupt Service Routines (ISRs) are part of the application. An ISR should be registered for all system interrupts enabled for processing. The following sequence can be used to set up the AINTC for a system interrupt.

  1. Initialize AINTC before any interrupt processing is enabled by calling IntAINTCInit(). This will make sure that all the fault system interrupt pending status is cleared before we enable any system interrupt.
  2. Register the interrupt handler for the system interrupt using the IntRegister() API.
  3. Set the channel number for the system interrupt using the IntChannelSet() API.
  4. Enable the IRQ/FIQ in ARM using the IntMasterIRQEnable() or IntMasterFIQEnable() APIs.
  5. Enable the global interrupt in AINTC by calling IntGlobalEnable(). If global interrupt is disabled in AINTC, AINTC will not signal any IRQ/FIQ to ARM core.
  6. Enable individual host interrupt in AINTC using the IntIRQEnable() or IntFIQEnable() APIs.
  7. Enable the system interrupt using the IntSystemEnable() API.

After the configuring AINTC, the application can enable interrupt processing for one or more peripherals. Any system interrupt generated by a peripheral after this point will cause the corresponding registered ISR to be called.

Example configuration

The timer example application (located in examples/evmOMAPL138/timer/) demonstrates how to handle timer interrupts. The application uses the Timer64P2 peripheral to demonstrate interrupt processing. The system interrupt number for Timer64P2 is 68, which is mapped to channel number 2. The AINTC will trigger IRQ for the Timer64P2 system interrupt. TimerIsr() is the ISR registered for this system interrupt.

The DSP Subsystem

The OMAPL138 also contains a floating point C674x DSP. This processor acts as co-master with the ARM in the overall system. The DSP has its own interrupt controller and cache system. StarterWare includes another system configuration library that provides APIs for configuring interrupts and cache on the DSP. The interrupt APIs are listed in the file include/c674x/omapl138/interrupt.h, while the APIs for cache management are listed in include/c674x/dspcache.h.

Interrupt Controller

OMAPL138 uses the DSP Interrupt Controller (DSPINTC) to interface between different peripheral devices and the DSP core interrupts. System events are generated by device peripherals. The interrupt APIs are listed in include/c674x/omapl138/interrupt.h.

Programming

The application developer must decide how to map system events to DSP interrupts. This can be done on a per-event basis with a single API call. DSP interrupts are then mapped to interrupt service routines (ISRs) that are provided by the application. An ISR should be registered for all DSP interrupts used by the application. The following sequence can be used to set up the DSPINTC for a system interrupt.

  1. Initialize DSPINTC before any interrupt processing is enabled by calling IntDSPINTCInit().
  2. Register the ISR to a specific DSP interrupt number using the IntRegister() API.
  3. Map the DSP interrupt to a specific system event using the IntEventMap() API.
  4. Enable the DSP interrupt using the IntEnable() API.
  5. Enable DSP interrupts globally using the IntGlobalEnable() API.

Since there are only 16 DSP interrupts (counting 4 reserved interrupts) but over 100 system events, the DSP subsystem also provides an event combiner module (ECM) to combine multiple system events into 1-4 DSP interrupt(s). Using the ECM requires a slightly different procedure:

  1. Initialize DSPINTC before any interrupt processing is enabled by calling IntDSPINTCInit().
  2. Initialize the ECM and assign 1-4 DSP interrupts to handle ECM events using the IntEventCombineInit() API.
  3. Register the ISR to a specific system event number using the IntEventCombineRegister() API.
  4. Enable the system event with ECM using the IntEventCombineAdd() API.
  5. Enable DSP interrupts globally using the IntGlobalEnable() API.

After the configuring DSPINTC, the application can enable interrupt processing for one or more peripherals. Any system interrupt generated by a peripheral after this point will cause the corresponding registered ISR to be called.

Example Configuration

The timer example application (located in examples/evmOMAPL138/timer) demonstrates how to handle timer interrupts. The application uses the Timer64P2 peripheral to demonstrate interrupt processing. The system interrupt number for Timer64P2 is 25, which is mapped to DSP interrupt 4. Timer completion events trigger the DSP interrupt, which in turn calls TimerIsr().

For an example application that uses ECM, please refer to examples/evmOMAPL138/i2c. This application uses ECM instead of mapping the I2C completion event directly to a DSP interrupt. ECM is typcially only used by applications that use more system events than there are DSP interrupts, but this application was intentionally written to use ECM as an example.

Cache Management

The C6000 DSP core also includes comprehensive cache support that can be used to speed up program or data memory access. All or part of internal L1 and L2 memories can be dedicated to cache. Caching must be explicitly enabled for specific memory ranges using the appropriate MAR bits. The cache APIs are listed in include/c674x/dspcache.h.

Programming

StarterWare provides APIs to perform all necessary steps to setup and use cache in DSP applications. The following steps are required to enable cache for a particular memory region:

  1. Dedicate internal L1 and/or L2 memory to be used as cache lines using the CacheEnable() API.
  2. Configure the MAR bits for the memory region that will be cached using the CacheEnableMAR() API.

Once caching is enabled, you can maintain cache using the CacheInv(), CacheWB(), and CacheWBInv() APIs. Writing back cached memory copies the current cache lines into physical memory. Invalidating cached memory throws out the cached values. Using these actions at the appropriate times is critical to maintain coherency between the DSP and other memory masters in the overall system such as the ARM core and EDMA.

Example Configuration

The cache example application (located in examples/evmOMAPL138/cache_mmu) demonstrates how to setup and maintain cache. It also demonstrates the importance of maintaining cache coherency when working with another memory master (i.e. the EDMA module).

Inter-Processor Communication (IPC) and IPClite

Hardware Overview

The inter-processor communication (IPC) hardware mechanism for the OMAP-L138 DSP + ARM processor is very straight forward as shown in the following illustration. At the SoC level, five CHIPINT bits are allocated in the CHIPSIG memory-mapped register (MMR) located in the SYSCFG system configuration module for the signaling between the DSP and ARM. Up to four signals can be mapped for the DSP to notify the ARM and two for the ARM to notify the DSP with an additional signal just for the DSP non-maskable interrupt (NMI) event. Note that two bits are common to both the DSP and ARM CPUs so that they can be both interrupted at the same time. This is a useful feature for debugging purposes. Writing one to the bit will generate the signal or event. These events are fed to the respective interrupt controller (INTC) to get mapped to the core interrupt inputs.
To pass data, any of the 128KB internal or 512MB external memory areas can be used as shared memory. Mutually exclusivity can be controlled using the mutex or semaphore mechanisms provided with the operating system.


OMAP-L138 IPC Hardware Mechanism


IPClite

Inter-Processor Communication on OMAP-L138 can be facilitated using IPClite, a software package included with StarterWare. It is a thin level of abstraction with a simple to use IPC initialization and Notify API. IPClite internal structure only uses 2 CHIPINT signals and 32 bytes (relocatable) of the 128KB internal shared memory. The IPC module performs the data structure initialization and initial synchronization between the 2 CPUs. The Notify module contains APIs to set up events, send notification to the other CPU as well as wait for an event in case polling method is desirable over interrupt method.

The most often-used API perhaps will be Notify_sendEvent which allows the application on one CPU to pass a 32-bit value to the other CPU's application via an event handler. The number of events, as well as its associated handler is programmable for each CPU. By not tying any meaning to the 32-bit value nor the event, your application can use the same call to pass a simple 32-bit value for one event, or a 32-bit pointer to a shared buffer of a complex data structure containing commands and data for another event, with no buffer copying needed between the 2 CPUs.

The IPClite API calls are the same for applications running on ARM or DSP, allowing easy portable and flexible application development involving multicore communication. To view the API for IPClite, first open the "OMAPL138_StartWare_1_10_xx_xx.chm" file (xx_xx is the subversion numbers) in the "docs" folder. Under "File List", click on "ipc.c" to view the IPC initialization API and "notify.c" for the Notify related API.

Example application

For a quick illustration of how the ARM or DSP CPU sends an event notification to each other, follow the ipc_interrupt, ipc_polling and ipc_buffer_io examples included with the software installation.

IPClite examples require both ARM and DSP side executables. To run the example, first connect EVM's serial port to a host PC serial port using a NULL modem cable. On the host PC, run a serial terminal application (ex. Teraterm, Hyperterminal, minicom) and configure it for 115200 baud, no parity, 1 stop bit and no flow control. The ARM side application will output to this serial console. The DSP side will output to CCSv5 console IO window.

To run the executables without rebuilding, set up the serial terminal and start CCSv5 with an XDS emulator connected to the EVM or with the on-board emulator (see here for more instructions). Under the "binary" folder, the "armv5" folder is for ARM executable and "c674x" is for DSP executable. Select the "cgt_ccs" subfolder, then omapl138\evmOPMAPL138 and then the examples. For all of these examples, the ARM side application will be waiting for a notification from the DSP side, so logically you may want to run the ARM-side first.

NOTE: It is critical however to LOAD the DSP image first when using CCS. This is required because the load process actually zeroes out the IPC buffer; and thus corrupts the ARMs initialization of the buffer if the DSP is loaded AFTER the ARM code is started.

  • ipc_polling is a simple notification example where the polling method is used to receive event notification from the other CPU. First after initialization where the 2 CPUs are synchronized, the ARM will wait for an event using Notify_waitEvent. The DSP side then will pass over a 32-bit value using Notify_sendEvent and then wait for the event from the ARM. Each time the value is received, the application performs a left shift and sends it back to the other CPU. The loop is set 10 times with the receved value printed out each time by each CPU. Since this is meant to be a simple introduction to IPClite, you will see only one event set up with one associated event handler set up using Notify_registerEvent. You can modify this example to add more events and see how your application can be "event driven" in an OS-less programming environment.
  • ipc_interrupt folder contains the same application as ipc_polling, but this time interrupt is used instead of polling to receive a notification. Switching between polling and interrupt requires only one parameter change, IPC_POLLING_METHOD to IPC_INTERRUPT_METHOD in the ipc configuration structure IPC_cfg.
  • ipc_buffer_io example shows a simple example where a small string buffer is passed from the DSP to ARM using Notify_sendEvent. Once received, the ARM side application prints the received string buffer, refilled with another string and send it back to the DSP side. Note that in this example, the MMU on the ARM is not set up so by default the ARM and DSP CPUs are both looking at similar physical address. If the MMU is used in your application, you need to make sure that the address of the buffer passed from one CPU to the other points to the same physical address since Notify_sendEvent will not perform any address translation between the ARM and DSP memory spaces.

Serial Devices

OMAPL138 has integrated UART, I2C and SPI peripherals to cater to different serial communications requirements. The StarterWare package includes a device abstraction layer (DAL), or driver library, to make these peripherals easy to use. StarterWare also includes example applications to demonstrate the use of these peripherals.

UART

The UART peripheral on OMAPL138 is based on the industry standard TL16C550. The UART module provides a 16-byte FIFO for the transmitter and receiver sections for buffering the data, which improves performance under slight latency conditions. UART can also be configured to generate events to the EDMA controller to reduce CPU overhead during data transfers. However, DMA mode requires that the FIFO be activated. StarterWare provides APIs to configure and operate the UART peripheral. These APIs are listed in include/uart.h.

For more information about using the StarterWare UART APIs, please refer to the StarterWare UART User Guide.

Example Application

To run the example application, first connect EVM's serial port to a host PC serial port using a NULL modem cable. On the host PC, run a serial terminal application (ex. Teraterm, Hyperterminal, minicom) and configure it for 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 "uart" example application is loaded and run on the target, the text "Starterware UART echo application" is printed on the serial terminal. After this it loops indefinitely, waiting for input characters from the user on the serial terminal. The application echoes any input back to the terminal.

Features used in this example:

  • UART
  • Interrupt

Example Application (EDMA)

To run the example application, first connect EVM's serial port to a host PC serial port using a NULL modem cable. On the host PC, run a serial terminal application (ex. Teraterm, Hyperterminal, minicom) and configure it for 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 "uart_edma" example application is loaded and run on the target, a message is printed on the terminal asking the user to input 20 characters. The application waits indefinitely for this input. Once the data is entered, the application echoes the same characters back to the terminal.

Features used in this example:

  • UART
  • Interrupt
  • EDMA

I2C

The I2C peripheral on OMAPL138 is compliant with the Philips Semiconductors Inter-IC bus (I2C-bus) specification version 2.1. The I2C module supports only Fast mode of operation (up to 400 kbps). The I2C module can be configured to multiple master-transmitters and slave-receivers mode and multiple slave-transmitters and master-receivers mode. The I2C module can also be configured to generate events to the EDMA controller to reduce CPU overhead during data transfers. StarterWare provides APIs to configure and use the I2C peripheral. These APIs are listed in include/i2c.h.

For more information about using the StarterWare I2C APIs, please refer to the StarterWare I2C User Guide.

Clocking Constraints

This module input clock is derived from the PLL or Async domain clocks, which is 75MHz (for I2C1 at 300MHz CPU speed) or OSC frequency (I2C0) as per the SoC specification. I2C module requires that the module input frequency fall between 6.7MHz and 13.3MHz for proper operation, which is achieved by applying a first level divisor (pre-scaler) to the module input clock. The actual output clock (operating clock frequency) is obtained by applying the clock divisor to this pre-scaled clock speed. The formula to calculate the clock divisor is provided in the I2C peripheral user's guide.

Example Application

When either of the I2C example applications are loaded and executed on the target, the LEDs on the EVM will blink for 100 times and then stop. This functionality is demonstrated either using interrupts only or using DMA as well, depending on which application is used.

Features used in these examples:

  • I2C
  • Interrupt
  • EDMA (i2c_edma only)

SPI

The SPI peripheral on OMAPL138 supports a SPI clock frequency (or SPI bus speed) between (Module Clock) / 3 and (Module Clock) / 256. SPI supports hardware handhshaking (using multiple slave chip select I/O pins and the SPI enable I/O pin) to improve overall throughput. SPI can be configured to generate events to EDMA controller to reduce CPU overhead during data transfers. StarterWare provides APIs to configure and use the SPI peripheral. These APIs are listed in include/spi.h.

For more information about using the StarterWare SPI APIs, please refer to the StarterWare SPI User Guide.

Example Application

To run the example application, first connect EVM's serial port to a host PC serial port using a NULL modem cable. On the host PC, run a serial terminal application (ex. Teraterm, Hyperterminal, minicom) and configure it for 115200 baud, no parity, 1 stop bit and no flow control. During execution, the application writes some data to the SPI flash chip on the EVM. Then, the written data is read back from SPI flash and compared against the original data that was written. If they match, a message is displayed on the host PC serial terminal. There are two versions of this example application. One uses SPI with interrupts only, and the other uses DMA as well.

Features use in these examples:

  • SPI
  • UART
  • Interrupt
  • EDMA (spi_edma only)

Raster

The LCD Controller (LCDC) peripheral on OMAPL138 is used in raster mode to display images on an LCD panel. It supports 1/2/4/8/16 bits per pixel (bpp) modes of operation.

For more information about using the StarterWare raster LCD APIs, please refer to the StarterWare LCDC User Guide.

Example Application

The example application configures the LCDC to display a static image with 16bpp color depth.

Before executing the raster lcd program, make sure that LCD screen is connected to the EVM. When program executed, an image will be displayed on the LCD screen. The image data is stored in the application source code as a large array of 16-bit values. This array was generated from a BMP image using the provided bmp2c host utility, located in the tools folder.

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

Features used in this example:

  • LCDC
  • Interrupt

NAND

The External Memory Interface A (EMIFA) peripheral on OMAPL138 provides a means for the CPU to connect to diffrent memory devices like NAND, NOR, SDRAM, Asynchronous SRAM, and more. StarterWare provides APIs to access a NAND memory chip on the EVM's UI add-on board using EMIFA.

For more information about using the StarterWare EMIFA APIs, please refer to the StarterWare EMIFA User Guide.

Example Application

The NAND example application demonstrates reading from and writing to NAND memory using EMIFA. The application writes a data patern to the user specifed block and page(s), then reads back the same NAND region and checks for that it matches the original data. If the macro NAND_DATAINTEGRITY_TEST_WITH_FIXED_ADDR is defined, the application does the erase, write, read operations on a default memory region instead of requesting user input. The application defaults to Hamming code 4-bit ECC type. To change the ECC type, define the macro NAND_ECC_TYPE_1BIT. Finally, the application uses DMA by default. To use polled access instead, define the macro NAND_OPMODE_POLLED.

To run the example application, first connect EVM's serial port to a host PC serial port using a NULL modem cable. On the host PC, run a serial terminal application (ex. Teraterm, Hyperterminal, minicom) and configure it for 115200 baud, no parity, 1 stop bit and no flow control. When the application is executed, NAND Device Info is printed on the serial console, along with a prompt that asks the user to enter some information (block number, page number, and number of pages). When the user enters this information, the NAND application performs several actions:

  1. Checks whether block is bad or not (next steps taken only if block is good)
  2. Erases the block
  3. Writes data with ECC enabled
  4. Writes ECC data to "spare" bytes
  5. Reads the data with ECC enabled and checks for the ECC errors
  6. If ECC errors are detected, the data is corrected or an error message is displayed
  7. Checks the read data against the original data that was written

Features used in this example:

  • EMIFA
  • UART
  • Interrupt
  • EDMA

GPIO

The GPIO peripheral on OMAPL138 is used to interface with external devices and peripherals. The GPIO pins can act as general purpose inputs to read digital signals from other devices or as general purpose outputs to control or signal to other devices.

The 144 GPIO pins on OMAPL138 are divided into 9 banks of 16 pins each. The pins can be programmed as input or output by using direction control registers. In output mode, a pin can be set or cleared by writing into separate set or clear registers without modifying the states of other pins. All GPIO pins can be programmed to generate CPU interrupts with configurable edge detection. All GPIO pins can also be programmed to generate events to the EDMA controller. StarterWare provides APIs to access GPIO pins in input or output mode. These APIs are listed in include/gpio.h.

For more information about using the StarterWare GPIO APIs, please refer to the StarterWare GPIO User Guide.

Example Application

To run the example application, first connect EVM's serial port to a host PC serial port using a NULL modem cable. On the host PC, run a serial terminal application (ex. Teraterm, Hyperterminal, minicom) and configure it for 115200 baud, no parity, 1 stop bit and no flow control. When the application is executed, a GPIO pin is used to detect when an MMC/SD card is inserted or removed from the slot on the EVM. A message stating "MMC/SD card inserted" or "MMC/SD card is removed" is printed to the terminal when either event occurs.

Features used in this example:

  • GPIO
  • UART
  • Interrupt

RTC

The RTC peripheral on OMAPL138 provides a time reference to applications 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- or 24-hour mode (i.e. 1:00 p.m. or 13:00). 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 generate CPU interrupts whenever the calendar or time registers are updated, or at programmable periodic intervals. The StarterWare APIs to configure and operate the RTC peripheral are listed in include/rtc.h.

For more information about using the StarterWare RTC APIs, please refer to the StarterWare RTC User Guide.

Example Application

To run the example application, first connect EVM's serial port to a host PC serial port using a NULL modem cable. On the host PC, run a serial terminal application (ex. Teraterm, Hyperterminal, minicom) and configure it for 115200 baud, no parity, 1 stop bit and no flow control. When the application is executed, the terminal prompts the user to enter time and calendar information. Afterward, the terminal displays the current data and time information as tracked by the RTC peripheral.

Features used in this example :

  • RTC
  • UART
  • Interrupt

Ethernet

The Ethernet Media Access Controller (EMAC) and Management Data Input/Output (MDIO) peripherals on OMAPL138 provide a full-featured Ethernet interface. The EMAC peripheral conforms to the IEEE 802.3 standard, describing the Carrier Sense Multiple Access with Collision Detection (CSMA/CD) Access Method and Physical Layer specifications. The EMAC module provides an efficient interface between the processor and a local network. The EMAC on OMAPL138 supports 10Base-T (10 Mbits/sec) and 100BaseTX (100 Mbits/sec), in half-duplex and full-duplex modes. The EMAC control module provides an interface from the CPU to the EMAC and MDIO modules. The EMAC control module controls device interrupts and incorporates an 8k-byte internal RAM to hold EMAC 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. Applications can use the MDIO module to configure the auto negotiation parameters of each PHY attached to the EMAC, retrieve the negotiation results, and configure required parameters in the EMAC module for correct operation. The StarterWare APIs for configuring and using EMAC and MDIO are listed in include/emac.h and include/mdio.h, respectively.

For more information about using the StarterWare EMAC APIs, please refer to the StarterWare EMAC User Guide.

For more information about using the StarterWare Ethernet design philosophy, please refer to the StarterWare Ethernet Design page.

The StarterWare EMAC APIs are demonstrated using the lwIP stack in two example applications:

  1. Echo Server Application - Performs simple data transfer with an external host
  2. Embedded Web Server Application - Hosts an HTML page on the local network

In both examples, the MAC Address and IP address can be configured in the enet_lwip/include/lwipopts.h file. The macro MAC_ADDRESS specifies the MAC address and STATIC_IP_ADDRESS specifies the static IP address to be used. To use a dynamic IP address, define STATIC_IP_ADDRESS as 0.

Echo Server Example Application

TMS470 Tool chain does not support packed attributes. This leads to issues when ethernet applications, built with TMS470 tool chain, are executed on the target. Hence, please do not use/connect ethernet in the demo. This issue is documented in the Known issues section of the release notes

The echo server application demonstrates a sample echo server-client setup using the lwIP stack. The target receives packets from an external device and transmits identical data back to the sender. StarterWare includes a PC host application, located in host_apps/enet_client, to serve as this external master. The PC application compares its sent and received data for integrity and prints results printed to the PC console.

To run the example application, first connect EVM's serial port to a host PC serial port using a NULL modem cable. On the host PC, run a serial terminal application (ex. Teraterm, Hyperterminal, minicom) and configure it for 115200 baud, no parity, 1 stop bit and no flow control. When the example application is executed, it obtains a dynamic IP address via DHCP and prints this address to the serial terminal. This application can be run using a local network or by connecting the EVM directly to a host PC (i.e. peer to peer connection):

With local network connection:

  1. Connect the Ethernet port on board to a port on the corporate network.
  2. Execute the example application on the target.
  3. Note the dynamic IP address assigned which displayed on the serial console.

With peer to peer connection:

  1. Connect the Ethernet port on board to the host Ethernet port via an Ethernet cable.
  2. Assign a static IP address to the host machine.
  3. Run a DHCP server application on the host.
  4. Execute the example application on the target.

In either case, note the IP address of the target application, then execute the enet_client application on the host PC:

$> ./client [target application IP address]

The client prints the status of the application on the console.

Features used in this example:

  • EMAC
  • MDIO
  • LAN8710A
  • Interrupt
  • UART
  • lwIP Stack

Embedded Web Server Example Application

TMS470 Tool chain does not support packed attributes. This leads to issues when ethernet applications, built with TMS470 tool chain, are executed on the target. Hence, please do not use/connect ethernet in the demo. This issue is documented in the Known issues section of the release notes

The embedded web server application hosts an HTML page to the local network. This page can be accessed using a web browser on your host PC.

To run the example application, first connect EVM's serial port to a host PC serial port using a NULL modem cable. On the host PC, run a serial terminal application (ex. Teraterm, Hyperterminal, minicom) and configure it for 115200 baud, no parity, 1 stop bit and no flow control. When the example application is executed, it obtains a dynamic IP address via DHCP and prints this address to the serial terminal. This application can be run using a local network or by connecting the EVM directly to a host PC (i.e. peer to peer connection):

With local network connection:

  1. Connect the Ethernet port on board to a port on the corporate network.
  2. Execute the example application on the target.
  3. Note the dynamic IP address assigned which displayed on the serial console.

With peer to peer connection:

  1. Connect the Ethernet port on board to the host Ethernet port via an Ethernet cable.
  2. Assign a static IP address to the host machine.
  3. Run a DHCP server application on the host.
  4. Execute the example application on the target.

In either case, note the IP address of the target application, then enter that address in the URL bar of your PC web browser.

Features used in this example:

  • EMAC
  • MDIO
  • LAN8710A
  • Interrupt
  • UART
  • lwIP Stack

makefsfile Host Utility

The makefsfile host utility can be used to create file system images to embed in applications such as the embedded web server example. It generates an ASCII C file containing initialized data structures representing the html pages and other content (image files, etc.). The makefsfile host utility is located in the tools/makefsfile folder and is provided in source and binary form. Executing the binary without any input provides a detailed help menu which guides the user.

To print detailed help contents:

$> ./makefsfile

The below usage takes an input directory path which contains HTML pages to be converted into a C file and embedded in a target application. The file fsdata.c will be generated inside the directory where makefsfile is executed.

$> ./makefsfile  -i  <directory-path>

McASP

StarterWare enables audio input and output via the Multichannel Audio Serial Port (McASP) peripheral on OMAPL138. The McASP module is a serial port optimized for multi-channel audio applications. McASP supports time division multiplexed (TDM) streams, Inter-IC Sound (I2S) protocols, and inter component digital audio interface transmission (DIT). McASP has separate transmit and receive units that can operate synchronously or independently. McASP can be configured for external or internal clock and frame sync signals. It has 16 serialisers, each of which can be configured as a transmitter or a receiver. The StarterWare APIs to configure and operate McASP are listed in include/mcasp.h.

For more information about using the StarterWare McASP APIs, please refer to the StarterWare McASP User Guide.

Example Application

The McASP example demonstrates audio input and output in I2S mode using DMA. The audio input on the LINE IN is looped back to the audio ouput on LINE OUT of the EVM. Before running the application, connect an audio source to the LINE IN connector and speakers or headphones to the LINE OUT connector. While the application runs, audio is piped from LINE IN to LINE OUT.

Features used in this example:

  • McASP
  • EDMA
  • I2C
  • Interrupt

For more information about the audio example application, please refer to the StarterWare audio application user guide.

Character LCD (LIDD)

The LCDC peripheral on OMAPL138 can be configured to operate in LIDD mode and interface with character displays to output ASCII characters or messages. A 24x2 character LCD is provided on the EVM's UI add on board. The LCDC peripheral cannot operate in LIDD mode and raster mode simultaneously, so only one type of display can be used at a time.

For more information about using the StarterWare LIDD APIs, please refer to the StarterWare LIDD User Guide.

Example Application

Before running the example application, ensure that the User Interface board is connected to the main board. When the application runs, a text message starts to scroll across the character LCD screen. The example application works in polling mode and does not use interrupts.

Features used in this example:

  • LCDC (LIDD mode)

Cache MMU Example Application

The ARM9 core uses a cache policy that read-allocates cache lines on cache miss only. When writing new data to memory, the contents of cache memory are not updated unless a cache line was allocated on a previous read from main memory. In the cache example application, the data buffer needs to be read so that the corresponding cache line is allocated. When data is written to the buffer, that data is updated inside the cache and not to main memory since cache uses a writeback policy (not writethrough).

When cache example application is compiled, two executables (.out) are generated:

  1. uartEdma_Cache.out - Demonstrates the effects of not cleaning the cache before a third party (ex. EDMA) tries to read the buffer
  2. uartEdma_CacheFlush.out - Demonstrates cleaning the cache before a third party (ex. EDMA) tries to read the buffer

To run the example application, first connect EVM's serial port to a host PC serial port using a NULL modem cable. On the host PC, run a serial terminal application (ex. Teraterm, Hyperterminal, minicom) and configure it for 115200 baud, no parity, 1 stop bit and no flow control. When the example application is executed, the following sequence occurs:

uartEdma_Cache.out:

  1. Lower case letters (a...z) are written to the buffer in memory (DDR). Note that the cache is not yet enabled.
  2. Cache is enabled with writeback policy for all memory (DDR).
  3. EDMA is programmed to transfer data from the data buffer and write to serial console.
  4. Lower case letters (a...z) are printed to the serial console. This happens because in step 1 the contents were written to main memory (cache was not yet enabled).
  5. Buffer is read to some dummy variable so that cache line are allocated to the buffer. This is a necessary step because the cache lines are read-allocate.
  6. Upper case letters (A...Z) are written to the buffer. Since buffer is cached with writeback policy, the data populated (A...Z) is updated only to cache and not to main memory.
  7. EDMA is programmed to transfer data from the data buffer and write to serial console.
  8. Lower case letters (a...z) are printed to the serial console. This is because EDMA always transfers data from main memory.

uartEdma_CacheFlush.out:

  1. Lower case letters (a...z) are written to the buffer in memory (DDR). Note that the cache is not yet enabled.
  2. Cache is enabled with writeback policy for all memory (DDR).
  3. EDMA is programmed to transfer data from the data buffer and write to serial console.
  4. Lower case letters (a...z) are printed to the serial console. This happens because in step 1 the contents were written to main memory (cache was not yet enabled).
  5. Buffer is read to some dummy variable so that cache line are allocated to the buffer. This is a necessary step because the cache lines are read-allocate.
  6. Upper case letters (A...Z) are written to the buffer. Since buffer is cached with writeback policy, the data populated (A...Z) is updated only to cache and not to main memory.
  7. Cache is cleaned. This causes the cached data (A...Z) to be written back to main memory. Now both cache and main memory contain the same data.
  8. EDMA is programmed to transfer data from the data buffer and write to serial console.
  9. Upper case letters (A...Z) are printed to the serial console.

Features used in this example:

  • Cache
  • EDMA
  • UART
  • Interrupt

USB

StarterWare for OMAPL138 supports a USB stack that is migrated from StellarisWare. For more information on the USB stack and example applications, please refer to the StarterWare USB User Guide.

Out-Of-Box Demo Application

The out-of-box demo application demonstrates the use of several peripherals simultaneously using the StarterWare device abstraction layer (i.e. peripheral drivers), lwIP, USB stack, and graphics library. The demo executable can be found in binary/armv5/gcc/omapl138/evmOMAPL138/demo. At run time, the demo application is navigated through a touchscreen menu.

TMS470 Tool chain does not support packed attributes. This leads to issues when ethernet applications, built with TMS470 tool chain, are executed on the target. Hence, please do not use/connect ethernet in the demo. This issue is documented in the Known issues section of the release notes

Features used in the demo application:

  • LCDC (raster mode) + graphics library
  • Touch detection
  • Ethernet + lwIP
  • McASP
  • UART
  • SPI
  • I2C
  • Timer
  • GPIO
  • RTC
  • USB + USB stack
  • Interrupt

Design overview

The out-of-box demo application combines functionality of multiple peripherals to demonstrate StarterWare capabilities for various use case scenarios. The application is designed to be driven by touch screen controls, but it also interacts with external devices via Ethernet, UART, USB, I2C, and more. The demo application takes the following actions at run time:

  1. Enable PSC and pinmux for the peripherals used
  2. Initialize the AINTC
    1. Register interrupt handlers
    2. Enable interrupts in AINTC
  3. Initialize the required peripherals and enable peripheral level interrupts
  4. Display the banner image
  5. Begin looping an audio clip (loops forever)
  6. Detect a touch on the LCD
    • If a touch is detected, validate the coordinates.
    • Display the proper image and demonstrate the peripheral selected by the user.

The demo 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. This includes:
    • Coordinates of the icon
    • The action to be taken when the icon is touched

Executing The Application

Before running the demo application, complete the following setup items:

  • Connect EVM's serial port to a host PC serial port using a NULL modem cable.
  • On the host PC, run a serial terminal application (ex. Teraterm, Hyperterminal, minicom) and configure it for 115200 baud, no parity, 1 stop bit and no flow control.
  • Connect the Ethernet port of the EVM to the local network.
  • Connect the USB mini connector on the EVM (J6) to the host PC.
  • Attach the LCD touch screen to the EVM.

When the example application is executed, a banner will be displayed on the LCD screen, followed by the menu screen. Clicking the icons on the menu screen will display peripheral-specific slides and run simple demonstrations of that peripheral in action. From each slide, you can continue to the next slide or go back to the "home" (menu) screen.

API Reference Guide

A detailed API Reference Guide is included with your StarterWare installation. Look for the OMAPL138_StarterWare_1_10_01_01.chm file in the docs folder. This file contains detailed documentation of the various APIs, data structures, and source files that make up StarterWare.

Migrating from StellarisWare

Please refer to the StarterWare Migration Notes for comparison of the device abstraction layers between StellarisWare and StarterWare.

Memory Usage Statistics

This section provides the code and data section for every device abstraction layer library object and the executables, generated using Code Sourcery GCC.

  • Device Abstraction Layer
DAL object text size (bytes) data size (bytes)
edma 2576 0
ehrpwm 1944 0
emac 708 0
gpio 780 0
i2c 524 0
lan8710 932 0
mcasp 1396 0
mdio 228 0
psc 216 0
raster 640 0
rtc 1920 0
spi 620 0
timer 1124 0
uart 632 0
usb 8192 0
  • Executables
Binary text size (kB) data size (kB) Notes
uartEcho 2.09 0.49 Data length attributed to global variables, interrupt table and transmit buffer
demo 77.49 4221.70 Data length attributed to global variables, interrupt table, audio raw tone and image data
ehrpwmWaveForm 2.89 0.45 Data length attributed to global variables and interrupt table
echoApp 41.64 62.76 Data length attributed to global variables, ethernet state variables and lwip netif structures
enetLwip 43.41 65.03 Data length attributed to global variables, ethernet state variables and lwip netif structures
gpioCardDetect 2.64 0.58 Data length attributed to global variables and interrupt table
grlib_demo 30.45 615.37 Data length attributed to global variables, interrupt table and image data
game 27.52 978.44 Data length attributed to global variables, interrupt table and audio raw tone
i2cLedBlink 1.20 0.48 Data length attributed to global variables, interrupt table, transmit and receive data buffers
i2cEdma 3.70 0.48 Data length attributed to global variables, interrupt table, transmit and receive data buffers
mcaspPlayBk 7.38 48.64 Data length attributed to global variables, interrupt table, receive and transmit data buffers
rasterDisplay 3.03 255.48 Data length attributed to global variables, interrupt table and image data
rtcClock 4.58 0.89 Data length attributed to global variables and interrupt table
spiFlash 3.65 1.28 Data length attributed to global variables, interrupt table, transmit and receive data buffers
spiEdma 7.11 1.11 Data length attributed to global variables, interrupt table, transmit and receive data buffers
timerCounter 2.66 0.49 Data length attributed to global variables and interrupt table
uartEcho 2.14 0.50 Data length attributed to global variables, interrupt table, transmit and receive data buffers
uartEcho(edma) 4.69 0.64 Data length attributed to global variables, interrupt table, transmit and receive data buffers
usb_dev_serial 25.90 268.6 Data length attributed to global variables, interrupt table and USB library objects. The larger data size is attributed the graphics related buffers used in the application to give good UI experience for the users. The graphics and hence these buffers can be cut off to get thin data size.
usb_dev_mouse 25.70 261.38 Data length attributed to global variables, interrupt table and USB library objects. The larger data size is attributed the graphics related buffers used in the application to give good UI experience (track pad area/click buttons on touch screen etc) for the users. The graphics and hence these buffers can be cut off to get thin data size.
usb_dev_msc 18.14 16617.97 Data length attributed to global variables, interrupt table and USB library objects. The larger data size is attributed the 16MB of RAM disk and large amount of DMA buffers used in the DMA driver. The driver buffers and RAM disk size can be reduced to get a thin data size.
wdtReset 3.86 0.15 Data length attributed to global variables and interrupt table
bootloader (spi) 4.05 0.16 Data length attributed to global variables