ITM.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *   its contributors may be used to endorse or promote products derived
 *   from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!*****************************************************************************
 *  @file       ITM.h
 *  @brief ITM driver header
 *
 *  @anchor ti_drivers_ITM_Overview
 *  <h3> Overview </h3>
 *  This driver implements APIs to configure and control the ARM Instrumentation
 *  Trace Macrocell (ITM), Debug Watchpoint and Trace (DWT), and  Trace Port
 *  Instrumentation Unit (TPIU) IPs to realize non-intrusive software logging
 *  and runtime trace.
 *
 *  # Overview <a name="overview"></a>
 *  The ITM software module provides application level APIs for the non-invasive
 *  debug capabilities of the ARM Cortex-M family. This includes the following
 *  hardware modules:
 *
 *   - Instrumentation Trace Macrocell (ITM)
 *   - Debug Watchpoint and Trace (DWT)
 *   - Trace Port Instrumentation Unit (TPIU)
 *
 *  At a high level, the DWT provides watchpoint, data trace, and program
 *  counter sampling. The ITM provides memory mapped registers for low-intrusion
 *  software profiling. The TPIU provides an external interface for the ITM and
 *  DWT. Further details can be found in the
 *  [ARMv7-M Architecture Reference Manual](https://static.docs.arm.com/ddi0403/e/DDI0403E_d_armv7m_arm.pdf)
 *
 *  <h3> Limitations and Constraints </h3>
 *  The driver is is designed with the following constraints in mind:
 *    - ITM is designed as a singleton. This means that  a single instance is
 *      shared across all clients
 *    - The parallel TracePort mode of the TPIU is not supported, only
 *      serial protocols are considered
 *    - The ITM hardware is configured via firmware on the DUT.
 *      Log records can be read independent of any IDE or debugger configuration.
 *      This means that if the IDE debug system configures the ITM, it should
 *      be turned off.
 *    - In Code Composer Studio, it is not currently possible to disable
 *      the debugger configuration mentioned above. No ITM output will be visible
 *      while the IDE's debugger is connected. Please flash your firmware, then
 *      disconnect and reset the device to see ITM data on the serial port.
 *
 *  @anchor ti_drivers_ITM_Setup
 *  <h3> Setup </h3>
 *  The ITM is configured via hardware attributes stored in the hardware
 *  attributes structure. This structure contains a common portion that is used
 *  for all drivers. This structure may be extended for some devices such as
 *  CC26XX.
 *
 *  <h3> Opening the driver </h3>
 *  Unlike other drivers, the ITM is intended to be a singleton.
 *  This means that @ref ITM_open can be called multiple times.
 *  The ITM will only be configured the first time open is called.
 *
 *  Furthermore, helper functions for features such as PC sampling must coherent
 *  across clients. The driver offers no protection against mismatched
 *  configuration.
 *
 *  The open call will enable ITM as well as the necessary stimulus ports.
 *  It will setup the TPIU for necessary baudrate and serial format.
 *
 *  @anchor ti_drivers_ITM_PinMux
 *  <h3> Pin Muxing </h3>
 *  As the ITM driver is primarily interfacing to ARM defined IP, it is almost
 *  entirely common across all supported devices. The only specifics are pin
 *  muxing of the SWO pin. See the table below for some notes

 *  | Device Family | Debug Protocol | Muxing          | Configurable? |
 *  |---------------|----------------|-----------------|---------------|
 *  | CC32XX        | SWD            | Shared with TDO | N             |
 *  | CC13XX/CC26XX | JTAG/cJTAG     | Any pin         | Y             |
 *  | MSP432E4      | SWD            | Shared with TDO | N             |
 *
 *  Device specific pin muxing is done by the device specific ITM backend
 *  implementation.
 *
 *  @anchor ti_drivers_ITM_SwMessages
 *  <h3> Software Messages </h3>
 *  The ITM stimulus ports enable serialization of application data with low
 *  overhead. There are multiple ports available, they are selectable via
 *  software.
 *
 *  Data written to the software stimulus ports is serialized by the TPIU
 *  and wrapped in the SWIT packet format. This packet format is standardized
 *  by ARM and described in [ARMv7-M Architecture Reference Manual](https://static.docs.arm.com/ddi0403/e/DDI0403E_d_armv7m_arm.pdf)
 *
 *  There are three tiers of access to the stimulus ports. In the table below,
 *  polled access means that the API/macro will poll the port's busy flag
 *  before writing. This is done to prevent silent data loss that
 *  occurs when writing to a port that is not ready. Actual serialization of the
 *  data will occur later inside the TPIU.
 *
 *    - ITM_PortX - Macro to write or read to the port, doesn't poll before
 *    - ITM_sendXPolling - Macro that polls and writes to the port
 *    - ITM_sendXAtomic - Function that calls ITM_sendXPolling with interrupts
 *                        disabled
 *
 *  It is up the the application writer to understand the tradeoff associated
 *  with each of these and select the correct one.
 *
 *  <h3> DWT Features </h3>
 *  The Data Watchpoint and Trace (DWT) module is capable of many
 *  instrumentation features such as
 *
 *  | Feature                  | ITM API                             |
 *  |--------------------------|-------------------------------------|
 *  | Exception trace          | @ref ITM_enableExceptionTrace       |
 *  | Program Counter sampling | @ref ITM_enablePCSampling           |
 *  | Event counting           | @ref ITM_enableEventCounter         |
 *  | Synchronization packets  | @ref ITM_enableSyncPackets          |
 *
 *
 *  Data generated by the DWT is serialized via the TPIU. DWT packet formats
 *  are defined in the ARMv7-M Architecture Reference Manual referenced above
 *
 *  <h3>Flush </h3>
 *  The ITM/DWT/TPIU hardware resides in the CPU power domain. This means that
 *  whenever the CPU domain is powered down, ITM will power down.
 *  Powering down when data is inside in the TPIU can result in lost data.
 *  In order to prevent dataloss, the device's power policy will flush the
 *  ITM before powering down the CPU domain. When returning from sleep, the
 *  power policy will restore the ITM. This is achieved using the
 *  @ref ITM_flush and @ref ITM_restore.
 *
 *  These functions are weakly defined as empty functions. This reduces the
 *  overhead in the power policy when ITM is not enabled. These weak functions
 *  are overridden by syscfg when ITM is enabled.
 *
 */

#ifndef ti_drivers_ITM__include
#define ti_drivers_ITM__include

#include <stddef.h>
#include <stdbool.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif


#define ITM_BASE_ADDR           (0xE0000000)

#define ITM_DWT_BASE_ADDR       (0xE0001000)

#define ITM_SCS_BASE_ADDR       (0xE000E000)

#define ITM_TPIU_BASE_ADDR      (0xE0040000)

#define ITM_LAR_UNLOCK          (0xC5ACCE55)

#define ITM_port32(n) (*((volatile unsigned int *)  (ITM_BASE_ADDR +4*n)))

/* The do {} while() loops below are to protect the macros so that they're
 * evaluated correctly regardless of the call site. They do not have any
 * function besides ensuring that the syntax is preserved correctly by the pre
 * processor.
 */
#define ITM_send32Polling(n, x)                                                \
    do                                                                         \
    {                                                                          \
        while(0 == ITM_port32(n));                                             \
        ITM_port32(n) = x;                                                     \
    } while(0)

#define ITM_port16(n) (*((volatile unsigned short *)(ITM_BASE_ADDR +4*n)))

#define ITM_send16Polling(n, x)                                                \
    do                                                                         \
    {                                                                          \
        while(0 == ITM_port16(n));                                             \
        ITM_port16(n) = x;                                                     \
    } while(0)

#define ITM_port8(n)  (*((volatile unsigned char *) (ITM_BASE_ADDR +4*n)))

#define ITM_send8Polling(n, x)                                                 \
    do                                                                         \
    {                                                                          \
        while(0 == ITM_port8(n));                                              \
        ITM_port8(n) = x;                                                      \
    }while(0)


typedef enum
{
    ITM_TPIU_SWO_MANCHESTER     = 0x00000001, 
    ITM_TPIU_SWO_UART           = 0x00000002, 
} ITM_TPIU_PortFormat;

/* This enables a common defintion of the hwAttrs structure that can be easily
 * extended by the device specific implementations. This structure defintion
 * must be the first line of any device specific structure
 */
#define ITM_BASE_HWATTRS                                                        \
    ITM_TPIU_PortFormat format;         /* Wire interface used by TPIU */       \
    uint32_t            traceEnable;    /* Bitmask of enabled stimulus ports */ \
    uint32_t            tpiuPrescaler;  /* Baudrate to be used by the TPIU */   \
    uint32_t            fullPacketInCycles; /* Cycles in a full word */         \

typedef struct
{
    ITM_BASE_HWATTRS
} ITM_HWAttrs;

typedef enum
{
    ITM_Disabled                        = 0x0, 
    ITM_EmitPc                          = 0x1, 
    ITM_EmitDataOnReadWrite             = 0x2, 
    ITM_SamplePcAndEmitDataOnReadWrite  = 0x3, 
    ITM_SampleDataOnRead                = 0xC, 
    ITM_SampleDataOnWrite               = 0xD, 
    ITM_SamplePcAndDataOnRead           = 0xE, 
    ITM_SamplePcAndDataOnWrite          = 0xF, 
} ITM_WatchpointAction;

typedef enum
{
    ITM_TS_DIV_NONE = 0,    
    ITM_TS_DIV_4    = 1,    
    ITM_TS_DIV_16   = 2,    
    ITM_TS_DIV_64   = 3     
} ITM_TimeStampPrescaler;
typedef enum
{
    ITM_SYNC_NONE      = 0, 
    ITM_SYNC_TAP_BIT24 = 1, 
    ITM_SYNC_TAP_BIT26 = 2, 
    ITM_SYNC_TAP_BIT28 = 3  
} ITM_SyncPacketRate;

extern bool ITM_open(void);

extern void ITM_close(void);

extern void ITM_sendBufferAtomic(const uint8_t port, const char* msg,
                                 size_t length);

extern void ITM_send32Atomic(uint8_t port, uint32_t value);

extern void ITM_send16Atomic(uint8_t port, uint16_t value);

extern void ITM_send8Atomic(uint8_t port, uint8_t value);

extern void ITM_enableExceptionTrace(void);

extern void ITM_disableExceptionTrace(void);

extern void ITM_enablePCSampling(bool prescale1024, uint8_t postReset);

extern void ITM_enableEventCounter(bool prescale1024, uint8_t postReset);

extern void ITM_disablePCAndEventSampling();

extern void ITM_enableTimestamps(ITM_TimeStampPrescaler tsPrescale,
                                 bool asyncMode);

extern void ITM_enableSyncPackets(ITM_SyncPacketRate syncPacketRate);

extern bool ITM_enableWatchpoint(ITM_WatchpointAction function,
                                 const uintptr_t address);

extern void __attribute__((weak)) ITM_flush(void);

extern void __attribute__((weak)) ITM_restore(void);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_ITM__include */