System Trace Module(STM) Library API Reference Guide
|
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.
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:
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 |
|
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. |