System Trace Module(STM) Library API Reference Guide
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
System Trace Module(STM) Library API Reference Guide Documentation

Introduction

The STM Library provides a STM programming API for software instrumentation. The library provides
methods for transporting instrumentation messages and application data. Message transport support includes
facilities for both variable length formatted strings (STMXport_printf), fixed length formatted strings (STMXport_logMsgN) and 
user formatted strings (STMXport_putMsg). The fixed and variable length strings provide the most efficient 
transport packet sizes since only pointers to the actual strings are transported. STMXport_logMsgN()
methods are significantly more efficient than STMXport_printf because the string does not have to be parsed
to determine the number of variables to transport. Data transport can be performed on buffers of data 
(STMXport_putBuf) or on individual data values (STMXport_putWord, STMXport_putShort, STMXport_putByte).  

The STM Target Library exports a "C" interface to the customer's application. This is a single
threaded API that is non-atomic (interrupts are not disabled).  

The physical STM unit provides multiple channels, each channel providing thread safe data transport, thus
messages from different channels may be interleaved. STM messages can also be interleaved between masters
(different processors). Channel distribution by the client may also be used to provide classification of
different data types, like distinguishing between logging levels, warning and error messages. When using 
STM Channels to classify data you can filter the data in the Trace Display based solely on channel numbers,
or in conjunction with other parameters. For these reasons the STM library does not provide any channel
management, currently leaving that to the client's library to manage.      

If a client utilizes a single channel, the clients is responsible for wrapping it with appropriate
semaphores to ensure thread safety or if a client wants to use this API from an ISR (without using a
unique channel). The API client is also responsible for disabling interrupts to create atomic operations.
Atomic operations may be required if the client is relying on the accuracy of timestamps applied
to each STM message (since these timestamps are applied at transport time when the last data element
is transported).

STM SW messages generated using these APIs will be displayed in a human readable format in the XDS560 Trace
Display and Analyzer tool. For the most part it is not needed nor recommended to put or impose any
protocols on the top of the messages. In case there is a strong need for adding additional protocols on
the top of the messages, a paired change in STM SW decoder framework (part of host tooling) may be needed
to propagate knowledge of the protocols so the information could be defined in a human readable or desired
format. Such decoder changes are made possible by the STM tooling SDK. 

\par Helper Functions

Helper functions allow the library to be ported easily to different operating environments without modifications
to the library directly. Within the library these functions are declared extern so the library will build but
can not be linked without implementations for the following helper functions:

\li void * cTools_memAlloc(size_t sizeInBytes); \n\n
If allocation successful returns pointer to allocated memory, else if not successful return NULL.

\li void * cTools_memMap(unsigned int phyAddr, unsigned int mapSizeInBytes); \n\n
Map a physical address to a virtual address space. Return the virtual pointer if successful, else return NULL.
Return phyAddr if virtual mapping not required.   

\li void cTools_memFree(void * ptr); \n\n
Free the memory at the ptr (returned from cTools_memAlloc()) call. 

\li void cTools_memUnmap(void * vAddr, unsigned int mapSizeInBytes); \n\n
Unmap virtual address space starting at vAddr (returned from cTools_memMap())of mapSizeInBytes length.
If virtual address mapping not required simply return.    

\par Directory Structure

STM is a component of cTools so it resides within the cTools directory structure.
|--cTools
|
|-- STMLib
| |
| |-- doc
| | |
| | |--STM_html
| | |
| | |-index.html (Doxygen API documentation)
| |
| |-- include (Public API include file)
| |-- src (Private .c and .h files )
| |-- projects (Target specific library builds)
|-- Examples
|
|-- 'Specific Device' (such as 'C667x')
| |
| |--STM_... (Target specific stand-alone example projects)
Library Builds

There are two library types available for STM export and two for CIO(file or stdout) export. The library type is controlled by defining the following preprocessor names:

  • _STM
  • _COMPACT
  • _CIO
  • _CIO & _COMPACT

The _STM build provides all defined API functions and features. The _COMPACT build reduces the capabilities of the library to fit into ~1K of memory. The _CIO build provides a path for the STM library APIs to be utilized in the simulator environment. All user data is exported to either a file or stdout through CIO, while remaining completely portable to either the _STM or _COMPACT build by simply changing out the library build used(with the exception of how the library is opened). For the compact build all functions are available to maintain compatibility with code implemented for the normal build, but some functions will return errors if their use is invalid. For _STM and _COMPACT builds both release and debug versions are supported. Only debug builds are provided for the _CIO version of the library. The debug version of the libraries enables function parameter checking.

Important Notes: 
\li If the data cache is enabled the MIPI_STM memory space must be protected from caching.
\li If the interface is opened for blocking calls, and your system has an MMU, your performance may be
    improved by enabling the MIPI_STM memory space for buffered writes.
\li Opening the library for buffered IO operation is only supported for OMAP devices. 
\li The following code section names are provided to allow splitting the library between different
    memory sections:
\n  - .text:STMLibraryFast used for code that interfaces to the STM module. The library may benefit from a performance improvement if this section is included in fast internal device memory.
\n  - .text:STMLibrarySlow used for code that can be placed in external memory that will be cached. This is typically the API interface routines.
\n  - .text:STMLibraryISR used for code that may be called from an ISR or SWI.
\n  These section names are only provided as a convenience. The STM library has no requirement that any section be placed in a specific internal or external memory space.

\par STM Library Revision History
Revision Date Notes
1.0 10/20/2008 Initial Release
1.1 11/19/2008 Updated callback to work in both buffered and blocking modes.
1.2 1/14/2009 Added APIs to improve performance of individual value transfers and created a compact version of the Library.
1.3 2/11/2009 Added APIs to log text messages
1.4 2/16/2009 Removed RTS dependency for the compact build
1.5 5/19/2009 Added CIO build for Simulation support
1.6 7/6/2009 Abstracted memory allocation and mapping routines to external functions to be provided by the client.
2.0 3/1/2010 Added configuration structure for printf optimization parameter
3.0 10/22/2010
  • Updated API parameters to fixed-width types.
  • Moved the STM Base Address and Channel Resolution STMXport_open parameters to the configuration structure.
  • Changed the names of client provided external support functions from STM_* to cTools_*.
  • Made the callback a configuration parameter rather than a separate argument for each API call.
3.1 12/1/2010 Added support for internal function STMExport_putMeta(). This function will normally be used by other TI provided libraries to include meta data (context sensitive information) in the STM data stream.
4.0 12/1/2010 Added STMXport_config_CS() for ARM Coresight STM 2.0 module support.
4.1 12/1/2010 Updated projects to CCSv5 type
5.0 12/1/2010 Removed STMBufObj * from STMXport_open (to eliminate message buffering support. Added xmit_printf_mode. Removed OMAP SDMA Support.
5.1 12/6/2013 Fix software messages for big endian targets.
5.2 9/29/2014 Added missing CCS project files.