STOG

The Interconnect Isolation Gasket is a TI proprietary IP that is used to prevent a hang caused by target, which can hold up the interconnect and terminate such a transaction safely. It tracks transactions, and times out if outstanding too long, and reports the error via interrupt that can be monitored.

The TOGs help to achieve Freedom From Interference by monitoring the various VBUS transactions and providing a way to detect any errors, and helping to avoid the bus to be locked up due to a transaction error.

Features Supported

These TOGs have the following functions, to avoid these concerns:

Monitors various VBUS transaction and provide a way to detect errors
Helps avoid the bus to be locked up due to a transaction in error.
Tracks outstanding transactions and allows for timeout/recovery.

Each of the Timeout gaskets can be programmed to a specific timeout and any transaction exceeding the timeout will result in abort of the transaction. This will also result in an error event triggered through ESM, which will in turn can be programmed to interrupt the CPU.

In addition the timeout gasket can be stopped, started and reset at anytime.

Safety diagnostics are provided for TOG module through API’s

Configure the TOG
Read the static registers
Verify the written configuration

SysConfig Features

None

Features NOT Supported

None

Important Usage Guidelines

None

Example Usage

The following shows an example of SDL TOG API usage by the application to set up the TOG for monitoring for events. Events can be monitored by enabling the events in the associated ESM instance.

#include <sdl/sdlr_tog.h>

Configure a TOG instance with a timeout value

SDL_TOG_Inst instance;
SDL_TOG_config cfg;
int32_t status;

cfg.timeoutVal = TOG_TEST_TIMEOUTVAL;

status = SDL_TOG_init(instance, &cfg);
if (status != SDL_PASS)
{
    // init failed
}

Enable the TOG interrupts

SDL_TOG_Inst instance;
int32_t status;

/* Enable interrupts */
status = SDL_TOG_setIntrEnable(instance, SDL_TOG_INTRSRC_ALL, true);
if (status != SDL_PASS)
{
    // interrupt enable failed
}

Start the TOG

/* Call SDL API to enable Timeout Gasket */
status = SDL_TOG_start(instance);
if (status != SDL_PASS)
{
    // start failed
}

Stop the TOG

SDL_TOG_Inst instance;

SDL_TOG_stop(instance);

Reset the TOG

/* Reset the Timeout gasket */
SDL_TOG_reset( instance );

Get the Error Information (can be called when an error occurs)

SDL_TOG_Inst instance;
SDL_TOG_errInfo errInfo;

/* Read error info */
status = SDL_TOG_getErrInfo(instance, &errInfo)

Acknowledge the interrupts for an interrupt source

SDL_TOG_Inst instance;
uint32_t intCount;

/* Get Transaction timeout interrupt count */
status = SDL_TOG_getIntrCount(instance, SDL_TOG_INTRSRC_TRANSACTION_TIMEOUT, &intCount);

/* Clear Transaction timeout interrupt events */
if ((status == SDL_PASS) && (intCount != 0))
{
    status = SDL_TOG_ackIntr(instance, SDL_TOG_INTRSRC_TRANSACTION_TIMEOUT, intCount);
    TEST_ASSERT_EQUAL_INT32(SDL_PASS, status);
}

Clear the pending interrupts for an interrupt source

SDL_TOG_Inst instance;

status = SDL_TOG_clrIntrPending(instance, SDL_TOG_INTRSRC_TRANSACTION_TIMEOUT);

API Reference

Header file containing various enumerations, structure definitions and function declarations for the VBUSM Slave Timeout Gasket IP.

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

TOG configuration flags

This is the SDL-FL API documentation for the VBUSM Slave Timeout Gasket module.

The following procedure describes how to properly use this SDL-FL API:

Call SDL_TOG_init with setting Timeout Value to configure the desired timeout counter value if you wish a shorter timeout than the default maximum timeout.
Enable/disable interrupt sources as needed by calling SDL_TOG_setIntrEnable. Note that all interrupt sources are enabled by default.
Call SDL_TOG_start to start the timer counting
If an interrupt is signaled from the gasket, then… a) Call SDL_TOG_getIntrPending to determine the pending interrupt sources b) Clear interrupt source(s) by calling SDL_TOG_clrIntrPending c) Service the cause of the interrupt as needed. If the system determines that it needs to flush all outstanding transactions (for instance, because the main SoC is in an error condition and is going to be reset), software may do this by calling SDL_TOG_setFlushMode with true. Once all transactions are flushed, software should exit Flush mode by calling SDL_TOG_setFlushMode with false. If the destination side is in reset, this should trigger hardware flush, keeping the gasket returning any transactions that arrive. d) The SDL_TOG_getErrInfo function can be called to get detailed information about the error if needed. e) Ack the interrupt by calling SDL_TOG_getIntrCount and SDL_TOG_ackIntr

SDL_TOG_CFG_TIMEOUT: Timeout Configuration Flag

SDL_TOG_CFG_INTR_PENDING: Pending interrupt Configuration Flag

typedef uint8_t SDL_TOG_cfgCtrl: This enumerator defines the possible configuration flags.

Functions

int32_t SDL_TOG_init(SDL_TOG_Inst instance, const SDL_TOG_config *pConfig)

Initialize TOG module with respect of instance.

This function allows software to initialize TOG module

The pConfig contains the timeout value and interrupt source

Parameters:

instance – [IN] TOG instance
pConfig – [IN] Pointer to store the configuration

Returns:

SDL_PASS The function completed successfully SDL_EBADARGS instance is invalid or pConfig is NULL

int32_t SDL_TOG_verifyConfig(SDL_TOG_Inst instance, const SDL_TOG_config *pConfig)

Verifying written configuration with TOG module.

This function allows software to verifying TOG module

The pConfig contains the timeout value and interrupt source

Parameters:

instance – [IN] TOG instance
pConfig – [IN] Pointer to store the configuration

Returns:

SDL_PASS The function completed successfully SDL_EBADARGS instance is invalid or pConfig is NULL

int32_t SDL_TOG_setIntrEnable(SDL_TOG_Inst instance, SDL_TOG_IntrSrc intrSrcs, bool enable)

Enable/disable interrupt source(s)

This function allows software to enable or disable the specified interrupt source(s).

The intrSrcs value is composed of a logical OR of the desired interrupt sources defined in SDL_TOG_IntrSrc.

Parameters:

instance – [IN] TOG instance
intrSrcs – [IN] Interrupt source(s) to set or clear
enable – [IN] If true, the interrupt source(s) are enabled. If false, they are disabled.

Returns:

SDL_PASS The function completed successfully SDL_EBADARGS instance or intrSrcs are invalid

int32_t SDL_TOG_clrIntrPending(SDL_TOG_Inst instance, SDL_TOG_IntrSrc intrSrc)

Clear pending interrupt source(s)

This function allows software to clear the specified pending interrupt source(s).

The intrSrc value is composed of a logical OR of the desired interrupt sources defined in SDL_TOG_IntrSrc.

Parameters:

instance – [IN] TOG instance
intrSrc – [IN] Interrupt source(s) to clear

Returns:

SDL_PASS The function completed successfully SDL_EBADARGS instance or/and intrSrc are invalid

int32_t SDL_TOG_getIntrPending(SDL_TOG_Inst instance, SDL_TOG_IntrSrc *pPendInts)

Get masked (enabled) pending interrupt sources.

This function returns the masked (enabled) pending interrupt sources.

The value returned is a logical OR of the masked pending interrupt sources defined in SDL_TOG_IntrSrc.

Parameters:

instance – [IN] TOG instance
pPendInts – [OUT] Pointer where pending interrupt sources is returned

Returns:

SDL_PASS The function completed successfully SDL_EBADARGS instance is invalid or pPendInts are NULL

int32_t SDL_TOG_ackIntr(SDL_TOG_Inst instance, SDL_TOG_IntrSrc intrSrc, uint32_t ackCnt)

Ack interrupt source.

This function acknowledges an interrupt source by decrementing the number of pending interrupts corresponding to the specified interrupt source intrSrc by the specified ackCnt count.

Valid values of intrSrc are:

SDL_TOG_INTRSRC_TRANSACTION_TIMEOUT
SDL_TOG_INTRSRC_UNEXPECTED_RESPONSE

SDL_EFAIL is returned if intrSrc is:

SDL_TOG_INTRSRC_COMMAND_TIMEOUT

Parameters:

instance – [IN] TOG instance
intrSrc – [IN] Interrupt source
ackCnt – [IN] Decrement count

Returns:

SDL_PASS The function completed successfully SDL_EBADARGS pRegs is NULL, intrSrc is invalid SDL_EFAIL ackCnt == 0 or is > # of pending interrupts

int32_t SDL_TOG_start(SDL_TOG_Inst instance)

Start the timer counter.

This function starts the timer counter.

Parameters:: instance – [IN] TOG instance
Returns:: SDL_PASS The function completed successfully SDL_EBADARGS pRegs is NULL

int32_t SDL_TOG_stop(SDL_TOG_Inst instance)

Stop the timer counter.

This function stops the timer counter.

Parameters:: instance – [IN] TOG instance
Returns:: SDL_PASS The function completed successfully SDL_EBADARGS pRegs is NULL

int32_t SDL_TOG_reset(SDL_TOG_Inst instance)

Reset the timeout functionality.

This function resets the timeout functionality by stopping the timer counter and clearing the timer and eon counters to 0. Note the eon bits represents the number of times free-running counter reached the configured timeout

Note that the timeout value set via the SDL_TOG_setTimeoutVal function is unaffected by this function.

Parameters:: instance – [IN] TOG instance
Returns:: SDL_PASS The function completed successfully SDL_EBADARGS instance is invalid

int32_t SDL_TOG_getErrInfo(SDL_TOG_Inst instance, SDL_TOG_errInfo *pErrInfo)

Get timeout error information.

This function returns information about a captured transaction.

Parameters:

instance – [IN] TOG instance
pErrInfo – [OUT] Pointer where the current number of occupied read slots is returned

Returns:

SDL_PASS The function completed successfully and pErrInfo contains valid information SDL_EBADARGS pRegs or pErrInfo are NULL SDL_EFAIL The function failed and there is no valid information in pErrInfo. This is because… a) there is no error pending b) the error pending did not have any captured information because there was an error pending in front of it that had already captured information.

int32_t SDL_TOG_getStaticRegisters(SDL_TOG_Inst instance, SDL_TOG_staticRegs *pStaticRegs)

Readback Static configuration registers.

This function reads back configuration registers that are static.

Parameters:

instance – [IN] TOG instance
pStaticRegs – [OUT] Pointer to store the read static registers

Returns:

SDL_PASS Function completed successfully SDL_EBADARGS Error with Arguments

int32_t SDL_TOG_setFlushMode(SDL_TOG_Inst instance, bool enable)

Enable/disable flush mode.

This function allows software to enable/disable flush mode.

Parameters:

instance – [IN] TOG instance
enable – [IN] If true, flush mode is enabled. If false, it is disabled.

Returns:

SDL_PASS The function completed successfully SDL_EBADARGS pRegs is NULL

int32_t SDL_TOG_getIntrCount(SDL_TOG_Inst instance, SDL_TOG_IntrSrc intrSrc, uint32_t *pIntrCnt)

Get interrupt count.

This function returns the number of pending interrupts corresponding to the specified interrupt source intrSrc as follows: 0 = No pending interrupts 1 = One pending interrupt 2 = Two pending interrupts 3 = Three or more pending interrupts

Valid values of intrSrc are:

SDL_TOG_INTRSRC_TRANSACTION_TIMEOUT
SDL_TOG_INTRSRC_UNEXPECTED_RESPONSE

SDL_EFAIL is returned if intrSrc is:

SDL_TOG_INTRSRC_COMMAND_TIMEOUT

Parameters:

instance – [IN] TOG instance
intrSrc – [IN] Interrupt source
pIntrCnt – [OUT] Pointer where interrupt count is returned

Returns:

SDL_PASS The function completed successfully SDL_EBADARGS pIntrCnt are NULL, or instance or intrSrc are invalid

struct SDL_TOG_errInfo

#include <sdl_tog.h>

This structure contains timeout error information.

Public Members

uint32_t routeId: Route ID - This indicates the Route ID of the captured transaction

uint32_t orderId: Order ID - This indicates the Order ID of the captured transaction

uint32_t dir: Direction - This indicates whether the captured transaction was a read (1) or a write (0)

uint32_t type: Type - This indicates the error type: 0=Transaction Timeout, 1=Unexpected Response

uint32_t tag: Tag - This indicates the CID/RID/SID of the transaction

uint32_t commandId: Command ID - This indicates the original Command ID (SID/RID) of the command. This field is only valid on a Timeout Error, not on an Unexpected Transaction Error

uint32_t orgByteCnt: Original Byte Count - If this is a timed out transaction, then this field represents the CBYTECNT value of the original command. If this is an unexpected response transaction, then this field contains the value of the bytecnt of the unexpected transaction (sbytecnt or rbytecnt).

uint32_t currByteCnt: Current Byte Count - If this is a timed out transaction, this is the number of bytes that were not returned as of the time the transaction timed out. If this is an unexpected response transaction, then this field is not applicable.

uint64_t address: Address - If the captured transaction was a Timeout Error, this field represents the address of the original transaction. If the error was an Unexpected Response error, then this field is not applicable.

struct SDL_TOG_config

#include <sdl_tog.h>

This structure contains TOG configuration information.

Public Members

SDL_TOG_cfgCtrl cfgCtrl

uint32_t timeoutVal

SDL_TOG_IntrSrc intrSrcs

struct SDL_TOG_staticRegs

#include <sdl_tog.h>

Slave TOG Static Registers.

This structure contains Slave TOG static registers The register values are not expected to change until a new configuration is done.