4.5.4.1. Enet LLD TSN User’s Guide¶

4.5.4.1.1. Introduction¶

This guide is intended to enhance user’s understanding of the TSN stack and provide guidance on how to seamlessly integrate TSN modules into their own applications.

4.5.4.1.1.1. TSN source modules¶

The TSN library is composed of the following source modules:

tsn_unibase: Universal utility libraries that are platform-independent.
tsn_combase: Communication utility libraries that provide support for functions like sockets, mutexes, and semaphores.
tsn_gptp: Implementation of the IEEE 802.1 AS gptp protocol.
enet_tsn_example: Example application for Time-Sensitive Networking (TSN).

4.5.4.1.1.2. TSN Initialization¶

A reference of the TSN stack initialization can be found in <enet>/examples/enet_tsn_example/tsninit.c. Prior to any module calls, it is necessary to initialize the unibase library once. This can be achieved by invoking the tsn_init() function.

4.5.4.1.1.3. TSN Logging¶

By default, TSN logs are directed to STDOUT using the fwrite function: fwrite(str, 1, strlen(str), stdout); However, it is possible to customize the log output by setting the console_out callback during the initialization of the unibase library in the tsn_init() function.

When a callback function assigned to console_out takes a significant amount of time to log the output device, it is advisable to log to a buffer and utilize another task to log from the buffer to the desired output device. This approach helps to prevent log delays that could adversely affect the gPTP task, such as incorrect Sync and FollowUp intervals. The option to log to a buffer is supported when the TSN_USE_LOG_BUFFER macro is defined. It’s important to note that in the Jacinto TSN example, this macro is defined by default.

To enable specific log levels, you can modify the ub_log_initstr parameter in the tsn_init() function. There are eight log levels available:

UBL_NONE = 0
UBL_FATAL = 1
UBL_ERROR = 2
UBL_WARN = 3
UBL_INFO = 4
UBL_INFOV = 5
UBL_DEBUG = 6
UBL_DEBUGV = 7

For example:

init_para.ub_log_initstr = "4,ubase:45,cbase:45,gptp:45";

In the above example, gptp:45 signifies the following:

4 (INFO): Log level for printing to the console.
5 (INFOV): Log level for storing in internal memory (which can be dumped to a file).

Please note that enabling the DEBUG or DEBUGV level will result in a large number of logs being generated. If the log buffer is used, it may overflow, causing some logs to be lost.

The first 4 character in "4,ubase... represents the default log level applied to all modules.

4.5.4.1.1.4. Starting gPTP¶

The gPTP functionality operates in a separate task. To initiate this task, you can use the EnetApp_gPtpStart() function.

4.5.4.1.1.5. TSN Deinitialization¶

To deinitialize the TSN modules, you can invoke the EnetApp_deinitTsn() function.

4.5.4.1.2. Integration¶

4.5.4.1.2.1. Source integration¶

To integrate the TSN stack into your application, follow these steps:

Initialize Enet LLD and setup board dependencies. In the TSN example application, the initialization routines can be found at <enet>/examples/enet_tsn_example/main.c, which can be used as reference.

The two main functions related to EVM board initialization are:
```
EnetBoard_init();
EnetBoard_setupPorts(...);
...
```
These functions are responsible for configuring pinmux, GPIOs, SerDes, etc., as well as providing the MAC port and PHY configuration parameters, which are board specific.
Before calling any TSN module APIs, ensure you initialize TSN by calling EnetApp_initTsn().
Initialize the combase Ethernet device table as the following code snippet:
```
for (i = 0; i < numEthPorts; i++)
{
    snprintf(&gEnetApp_gPtpNetDevs[i][0], IFNAMSIZ, "tilld%d", i);
    /* ethdevs[i].netdev must hold a global address, not a stack address */
    ethdevs[i].netdev = gEnetApp_gPtpNetDevs[i];
    ethdevs[i].macport = ethPorts[i].macPort;
}

cb_lld_init_devs_table(ethdevs, i, enetType, instId);
```
In the above code, the Ethernet device name is not mandatory but it’s useful as a virtual Ethernet device table that facilitates the conversion between the device name and the MAC port number.

Please ensure that the ethdevs[i].netdev pointer points to a global memory location rather than a stack memory. The combase layer will reference this address instead of making a copy.
Start the gPTP task by calling EnetApp_gPtpStart(gEnetApp_gPtpNetDevs). Make sure that the gEnetApp_gPtpNetDevs variable is stored in global memory rather than stack memory.

4.5.4.1.2.2. gPTP switch mode¶

To configure gPTP in switch mode or with multiple ports, you need to perform the following steps:

Initialize the multiple ports table for combase using the cb_lld_init_devs_table() function. This function sets up the table that maps Ethernet devices to their corresponding MAC ports.
Call the EnetApp_gPtpStart() function with multiple Ethernet devices as parameters. This function starts the gPTP task and enables gPTP functionality on the specified Ethernet devices.

Initializing the multiple ports table and calling EnetApp_gPtpStart() with the appropriate Ethernet devices is sufficient to configure gPTP in switch mode.

4.5.4.1.2.3. gPTP configuration¶

To configure gPTP, you can utilize the function gptpconf_set_item(). For a reference example, please consult the <enet>/examples/enet_tsn_example/main.c file.

To view all the configuration parameters, you can refer to <pdk>/packages/ti/transport/tsn/tsn-stack/tsn_gptp/gptp_defaults.h. For instance, within the gptp_defaults.h file, there is a defined parameter called DEFAULT_USE_HW_PHASE_ADJUSTMENT. To configure this parameter, you need to replace DEFAULT with CONF and invoke the configuration function as follows:
```
``gptpconf_set_item(CONF_USE_HW_PHASE_ADJUSTMENT, &use_hwphase);``
```
There are two important parameters, CONF_USE_HW_PHASE_ADJUSTMENT and CONF_SINGLE_CLOCK_MODE, please configure them:
```
int use_hwphase = 1;
int single_clock = 1;

gptpconf_set_item(CONF_USE_HW_PHASE_ADJUSTMENT, &use_hwphase);
gptpconf_set_item(CONF_SINGLE_CLOCK_MODE, &single_clock);
```
By default, the phase adjustment is kept in the internal buffer of gPTP. Setting CONF_USE_HW_PHASE_ADJUSTMENT to 1 enables the application of clock phase offset to the CPTS hardware. Setting CONF_SINGLE_CLOCK_MODE to 1 enables the single clock mode for gPTP. This is the case of CPSW has a single CPTS for multiple MAC ports.
The configuration must be done before calling the gptpman_run() function inside the tsninit.c file.

4.5.4.1.3. Performance¶

4.5.4.1.3.1. Memory footprint¶

Not available in this release.

4.5.4.1.3.2. Time to sync gPTP¶

Not available in this release.

4.5.4.1.3.3. Accuracy of gPTP Sync¶

Not available in this release.