6.1.1.1. Application Integration¶

CSL is common package supporting multiple devices.Software layer using CSL source would need to pass compile time define -DSOC_XXX. Refer ticslsoc.h for list of devices/SOC’s

Refer list of APIs/interfaces available under <PDK_INSTALL_DIR\packages\ti\csl> directory.

6.2.1.1. Introduction¶

Driver enables UART’s available on SOC for reading and writing to any peripherals on board. Additionally it supports simple APIs for Console/STDIO operations.

Modes of Operation

Following modes of operations are supported

UART_MODE_BLOCKING: In this mode, read and write APIs, blocks on semaphore until required operation is complete. By default, UART driver operates in blocking mode. In this mode, code execution of a task blocks until UART transaction is complete. While transaction is in progress additional tasks pending requests will remain in blocked state waiting for semaphore.

UART_MODE_CALLBACK: In this mode, read and write operation returns immediately. On trigger of hardware Interrupt (hwi) callback function gets triggered.

6.2.2.1. Driver Configuration¶

Board Specific Configuration

All board specific configurations eg:enabling clock and pin-mux for UART pins are required before calling any driver APIs.By default Board_Init() API supports all initialization sequence for TI supported EVMs. In addition it initializes UART instance for Console/STDIO.Refer Processor SDK RTOS Board Support for additional details.Once board specific configuration is complete UART_init() API can be called to initialize driver.

UART Configuration Structure

The UART_soc.c file binds driver with hardware attributes on the board through UART_config structure. This structure must be provided to UART driver. It must be initialized before the UART_init() function is called and cannot be changed afterwards. For details about individual fields of this structure, see the Doxygen help by opening PDK_INSTALL_DIRpackagestidrvuartdocsdoxygenhtmlindex.html.

6.2.2.2. APIs¶

API reference for application:

#include <ti/drv/uart/UART.h>

STDIO API reference for application:

#include <ti/drv/uart/UART_stdio.h>

Open UART

There are three ways to open a UART instance:

1. UART_open()

...
Board_init(boardCfg);
...
UART_socGetInitCfg(UART_INSTANCE, &uart_cfg);
...
UART_socSetInitCfg(UART_INSTANCE, &uart_cfg);
...
UART_Params_init(&params);
...
handle = UART_open(UART_INSTANCE, &params);

At this point UART driver is ready for data transfer on specific instance identified by handle. Application can call UART_read/write API for read/write operation

2. UART_stdioInit() using the default UART parameters

...
Board_init(boardCfg);
...
UART_socGetInitCfg(UART_INSTANCE, &uart_cfg);
...
UART_socSetInitCfg(UART_INSTANCE, &uart_cfg);
...
UART_stdioInit(UART_INSTANCE);

At this point UART driver is ready for data transfer on specific instance. Application can call UART_printf/scanFmt API for read/write operation

3. UART_stdioInit2() using Application specified UART parameters

...
Board_init(boardCfg);
...
UART_socGetInitCfg(UART_INSTANCE, &uart_cfg);
...
UART_socSetInitCfg(UART_INSTANCE, &uart_cfg);
...
UART_Params_init(&params);
...
UART_stdioInit2(UART_INSTANCE, &params);

At this point UART driver is ready for data transfer on specific instance. Application can call UART_printf/scanFmt API for read/write operation

Read/Write APIs

Interrupt:

UART_read(handle,scanPrompt, sizeof(scanPrompt));/* Read API */
...
UART_write(handle, bufferPrompt, sizeof(bufferPrompt));/* Write API */

Or

UART_transactionInit(&transaction);
transaction.buf = (void *)scanPrompt;
transaction.count = sizeof(scanPrompt);
UART_read2(uart, &transaction);
...
UART_transactionInit(&transaction);
transaction.buf = (void *)bufferPrompt;
transaction.count = sizeof(bufferPrompt);
UART_write2(uart, &transaction);

Polling:

UART_readPolling(handle,scanPrompt, sizeof(scanPrompt));/* Read Polling mode API */
...
UART_writePolling(handle, bufferPrompt, sizeof(bufferPrompt));/* Write Polling API */

DMA Usage :

UART driver supports DMA operations to transfer data between

• Memory and RX FIFO for read transfer
• Memory and TX FIFO for write transfer.

DMA Driver is DMA family IP (EDMA and UDMA) and UART IP (V0 and V1) specific. Refer soc/dma/v#/UART_dma.c for these operations. Application need to create DMA handle and update the configuration before UART_init() API.

uartInitCfg[UART_INSTANCE].edmaHandle = UartApp_edmaInit();/* For AM/K1/K2 devices */

or

uartInitCfg[UART_INSTANCE].udmaHandle = UartApp_udmaInit();/* For K3 devices */

UART_init();

Refer “UART_BasicExample_[SOC]_[cpu]DMATestproject” or “UART_DMA_[evm]_[cpu]TestApp” for additional reference. Refer SDK Release Note for supported EVMs.

6.2.3.1. Examples¶

6.3.1.1. Driver Overview¶

PDK USB driver (USB LLD) provides the following USB class/functions while isolating application from the complexity of low level USB and USB class protocols:

• USB device Mass Storage Class
• USB host Mass Storage Class
• USB device Audio Class
• USB generic bulk device class

In rest of the page AM437x EVM is being refered as an example. Please check Release Notes for list of supported EVMs for driver.

Modes of Operation

• USB device Mass Storage Class
  • USB device Mass Storage Class with RAM DISK

In this mode, a user-selected USB instance of the EVM will be working in device mode and will behave like a USB thumb drive. It uses part of the EVM DDR memory and exposes it as a physical storage for another USB host application. After the host PC enumerates this EVM-thumb drive, the PC will see a USB storage device. This EVM-thumb drive is not yet formatted with any file system and requires user to format it before use.

The following screen shots show what one would expect when running the device mode demo application and plugging in a USB cable from the EVM USB port #0 to a PC running Windows

Printout from demo application:

The MSC device is detected in Windows, and a FAT formatted USB drive named “PDK-USBDEV” should be seen in the “Window Explorer”. The content of the drive is just a readme.txt file. This USB drive can be manipulated like any other removable USB drive.

Windows might show a message saying it should be scanned and fixed. We can just ignore it and just continue without scanning.

• USB device Mass Storage Class with MMCSD card

This example acts like a USB - MMCSD card reader. The example exposes the EVM’s MMCSD card to the Host PC via USB MSC. The Host PC can manipulate files on the attached MMCSD card on the EVM. This example is currently supported on AM335GP EVM. This is how it looks. Its code is similar to that of the USB device MSC example but with the call back functions calling MMCSD API’s instead of RamDisk APIs

• USB host Mass Storage Class

In this mode, the USB instance will act as a USB host communicating with a USB device that supports Mass Storage Class function (USB thumb drive or a small USB hard drive). The demo example code utilizes a shell interface via the EVM via UART for interaction with the example. The shell provides some basic commands to manipulate the content of the attached USB disk drive.

Screenshot of a MSC host mode example running in RTOS after plugging in a USB thumb drive into USB port #1

• USB device Audio Class

In this mode, USB instance of the EVM will be working in device mode and will behave like a USB headset with MIC. It uses audio codec on the EVM for running playback and record initiated by the USB host. McASP module will be used to transfer the data between USB device and audio codec on the board. EVM will appear as a new USB audio device on the host PC. Changing the default audio device on the host PC to EVM USB device will allow the playback and record operations between EVM and USB host. This mode of operation is currently supported on AM335X GP EVM, OMAP-L137 EVM and OMAP-L138 LCDK.

• USB generic bulk device class

In this mode, a user-selected USB instance of the EVM will be working in device mode. The mentioned USB device will show up in the host PC as a generic USB bulk device with one single interface containing a bulk IN and a bulk OUT endpoints. The configuration and interface descriptors published by the device contain vendor-specific class identifiers, so an application on the host will have to communicate with the device using either a custom driver or a subsystem such as WinUSB or libusb-win32 on Windows (or just libusb on Linux) to read and write to the device.

• Running USB bulk device demo application

The bulk demo application requires a host PC with USB host plugged to the USB device port on the EVM. Depending on the platform, the USB device port might be USB port #0 or #1.

Please refer to PDK user guide for how to generate USB example projects. Once the demo application is loaded and run, the EVM UART console shows the following:

A Python host PC example application is provided in ti/drv/usb/example/usb_dev/bulk/usb_dev_bulk_host_application.py

The example Python script requires PyUSB to run. On Linux host, proper UDEV rule is also required in order to access the USB bulk device as non-sudo user. The script itself also lists the requirements to run it as well as what command options available. The example UDEV rule is also placed in the same place where the Python script is located. It does the following:

• The Python script looks for the USB device with the example PID:VID,
• Sends an ASCII text string to the USB bulk demo application running on the EVM
• Expects the same text string with reversed case letter returned back, and also
• Verifies the received data with the data that it has sent and report the test result.

A screen shot of what the Python test script outputs

The USB bulk demo application configures the USB endpoints as high speed endpoints with 512B packet size.

6.3.2.1. Driver Configuration¶

• Data Structures:
  • tUSBDMSCDevice: Defined in usbdmsc.h. It is used in USB device mode application. This structure must be filled with the intended vendor and product ID as well as other product information and also the function pointers to functions that handle the disk functions (open/read/write/close, etc.). These product information will show up in the device and interface USB descriptors that are used during device enumeration. This device MSC class data is then assigned to the field usbClassData of the USB_Params bellow.
  • USB params: USB_Params structure is declared in usb_drv.h. This structure must be provided to the USB driver. It must be initialized before the USB_open() function is called.
  • USB APIs: main USB LLD and USB MSC API’s are declared in usb_drv.h and usbdmsc.h and usbhmsc.h provided in the root USB LLD directory.

• General USB LLD expectations:

The USB LLD will setup appropriate USB clock and power domains for the particular SOC being in used as part of its “device specific peripheral” functions.

After the USB_open() is called, the driver expects the application code to sets up USB interrupts with the interrupt handler being the USB LLD provided interrupt handler. Then the application have to call the USB LLD provided API USB_irqConfig() which enables USB module’s interrupts. In device mode, both USB core and USB misc interrupts are used in the USB device MSC application. In host mode, the USB host MSC only uses USB core interrupts.

After these steps, application code then can expect to have USB enumeration done and start USB transfer through the provided APIs.

6.3.2.2. API Call Flow¶

• USB Device MSC

The example application code uses the USB library, configures it as a USB device with MSC function. The example also provides functional codes that access a RAM disk (included from the Utils library in the included Starterware). The LLD calls these MSC back-ends functions to access the RAM disk. User can replace these functions with other functions that access other types of media or devices (MMCSD for example). The RAM disk image provided in the example demo application is not currently formatted. Thus the once enumerated, the PC will require the USB disc to be formatted before use.

Below diagram is the sequence of API calls that starts the USB device MSC application. All USB events are handled internally in the LLD and in the interrupt context.

User provided disk functions will be called from the LLD to handle the actual physical disk access. The overview of USB Device MSC example application:

The content of the file: usb_msc_structs.c can be replaced with customer USB device information (PID/VID, device names, etc.)

• USB Host MSC

The LLD also provides a USB host MSC example. The USB LLD is acting as a USB host, waiting for a USB thumb drive/memory stick to be plugged in. A console with a simple shell command is also provided so that the demo example can display and manipulate content of the USB device.

The following is how the USB host MSC example demo is organized:

The following is the sequence of the APIs that were used:

• USB Device Audio

The example application code uses the USB library, configures it as a USB device with Audio class function. USB LLD along with the application enumerates as the USB audio class device and allows accessing the audio ports on the EVM from USB host. It supports audio playback and record operations.

Below diagram is the sequence of API calls that starts the USB device audio application. All USB events are handled internally in the LLD and in the interrupt context.

• USB Device Bulk

Sequence of API calls as long as what the example application looks like are described bellow

• Main APIs that are used to read/write from and to the USB bulk device are USBD_bulkRead() and USBD_bulkWrite().

These two functions will block the caller until they finish their operation.

• The main application should wait for about 500ms after the USB host sends the SetConfig request to make sure that the enumeration is completely finished before calling USBD_bulkRead/Write functions

6.3.3.1. Examples¶

Examples are CCS projects. Generated with pdkProjectCreate scripts. Please refer Processor SDK RTOS Getting Started Guide for how to create and build examples projects

6.3.3.2. Test Application¶

USB test applications are built using makefile. Some of the test application are RTOS/BIOS apps, other are bare metal apps. They are replica of the USB examples but built by makefile instead of CCS projects.

Refer to the Processor SDK RTOS Getting Started Guide for details of how to setup the build environment. Once you have setup the build environment, issue the following commands:

• cd <pdk>/packages/
• To build: make usb
• To clean: make usb_clean
• Test applications are then under (TI_PDK_INSTALL_DIR)/packages/ti/binary/

Both examples and test applications can be loaded and run on their intended EVM via

• CCS JTAG connector, or
• Via SBL: the “app” file under CCS project’s debug directory (<PDK_INSTALL_PATH/MyExampleProjects/<ExampleProjectDirectory>/Debug>) is SBL loadable file of the built project.

– Project Memory layout must be considered and following SBL guideline so that examples can run safely via SBL. Please refer to SBL Component for more detail

6.3.4.1. USB host MSC¶

• To measure the USB host MSC throughput, a new command (bm) is added into the USB host mode example (or test application).
• This command is to run with a good known fast USB thumb drive attached to the USB host port.
• The throughput measurement result varies greatly depends on which USB device is plugged in and which filesystem is used
• The USB drive needs to be formated as FAT32 (since the USB host example only supports FAT filesystem) and has at least 100MB free space. Fast blank USB thumb drive is recomended.
• The command, when run, writes a 100MB file into the thumb drive and measures the time it takes to do so. It then reads back this 100MB file with time measurement to find the read throughput.
• The write and read are done in block size of 100KB, 256KB, 1MB, and 5MB. It prints throughput measurements for each of these blocks.
• This command is only supported in AM65xx at the moment.
• Syntax:

bm <test_file_name>

6.3.4.2. USB device MSC¶

• To measure USB device MSC throughtput a simple linux shell script usb_dev_msc_perf.sh is provided in PDK/packages/ti/drv/usb/example/usb_dev/msc/
• This script assumes the USB Dev MSC drive (PDK-USBDEV) is already mounted on the Linux host PC (under /media/$USER/PDK-USBDEV) when it runs
• It uses “dd” command to report the thoughput
• Tested on Ubuntu 16.04. Different version of Linux might mount the MSC drive at different place. Please adjust the script accordingly.
• The script writes a file to the PDK-USBDEV drive with a number of blocksize. By default it creates a 15MB test file by writing 150 blocks of 100K each (which would fit inside the 16MB RAM disk provided by the USB Dev MSC.)
• User is free to change the block size and number of blocks for the test. However it doens’t check if the end result file would fit the PDK-USBDEV drive or not.
• Syntax:

usb_dev_msc_perf.sh [<blocksize> <count>]

6.4.2.1. Driver Configuration¶

Board-specific configuration

PCIe’s board specific configuration is in the example in PDK_INSTALL_DIR/packages/ti/drv/pcie/example/sample/am57x/src/pcie_sample_board.c. Calling sequence is in example and repeated below.

PCIe configuration structure

The pcie_soc.c binds the driver to the hardware on the board. It is passed into the driver via the call to Pcie_init().

6.4.2.2. API Call Flow¶

The API call flow is covered in pcie_sample.c.

The overall components are:

1. Initialize the driver
2. Initialize the SERDES and Power the peripheral (see example code for order for each device)
3. Configure RC or EP symmetrically to talk to another similar device
4. Perform data IO and interrupt.

6.4.3.1. Examples¶

Quick setup of xds100 for two EVMs

1. create new target configuration using XDS100v2 and AM572x (or AM571x) from the basic tab.
2. Select Advanced tab.
3. Highlight the XDS100v2, and click the “new” button and add second XDS100v2.
4. Highlight the newly added XDS100v2, click the “add” button and select a second Am572x.
5. open command prompt, and run ticcs_basecommonuscifxds100serial to get your serial numbers
6. Highlight first XDS100v2, select “Debug Probe Selection” to “Select by Serial number” and enter one of the 2 serial numbers
7. Repeat second XDS100v2, setting to to the second serial number.

General instructions for configuring multiple EVMs with any emulator type are available in Debugging with Multiple Debug Probes

Detailed instructions to run example

Ensure 2 Like EVMs are connected with a x1 PCIe male/male cross cable (for AM5XX) or a breakout card (for C667x, C665x, K2x)

Build project(s) appropriate for your EVM. Projects for A15 and C66 are provided based on core types available on each device.

Load via jtag either the ARM or DSP projects (but don’t mix and match) onto the first arm or dsp core of each the 2 EVMs. Same .out file supports both RC and EP. Use an “expressions” window to set PcieModeGbl to PCIE_RC_MODE on one EVM (it makes that EVM RC). Leave the second EVM alone (pcie_EP_MODE). Run the loaded cores. See table above to determine whether output is expected on serial console or CCS console.

Sample example output

Note that output will vary slightly based on device type. The following is from A57XX. The output from the RC and EP are interleaved since this is run from a 2*XDS1000 double config as described in Quick setup of xds100 for two EVMs

**********************************************
*             PCIe Test Start                *
*                RC mode                     *
**********************************************

Version #: 0x02020003; string PCIE LLD Revision: 02.02.00.03:Dec 24 2015:17:38:37

PCIe Power Up.
PLL configured.
Successfully configured Inbound Translation!
Successfully configured Outbound Translation!
Starting link training...
**********************************************
*             PCIe Test Start                *
*                EP mode                     *
**********************************************

Version #: 0x02020003; string PCIE LLD Revision: 02.02.00.03:Dec 24 2015:17:38:37

PCIe Power Up.
PLL configured.
Successfully configured Inbound Translation!
Successfully configured Outbound Translation!
Starting link training...
Link is up.
Link is up.
End Point received data.
End Point sent data to Root Complex, completing the loopback.
EP sending interrupts to RC
Root Complex received data.
RC waiting for 10 of each of 2 types of interrupts
RC got all 20 interrupts
Test passed.
End of Test.

6.5.1.1. Introduction¶

GPIO module allows application to manage General Purpose I/O  instances and pins via simple portable APIs. Because of its simplicity, APIs are pin based and does not follow model of other drivers inside PDK which requires handle abstraction.

Modes of Operation

Following modes of operations are supported Input or Output Each gpio pin can be configured as either input: GPIO_CFG_INPUT or output: GPIO_CFG_OUTPUT. If it is configured as an output then pin level can be additionally configured

Interrupt support Each gpio pin can be configured to generate interrupts based on event type GPIO_CFG_IN_INT_XXX configuration. To generate interrupt, gpio pin has to be configured as input pin.

Driver Configuration

Board Specific Configuration

All board specific configurations like enabling clock and pin-mux are required before calling any driver APIs. By default Board_Init() API available under board module supports all initialization sequence for TI supported EVMs. In addition it initializes UART instance for Console/STDIO. Refer Processor SDK RTOS Board Support for additional details.

GPIO Configuration Structure

GPIO_soc.c binds driver with hardware attributes on the board. Hardware attributes includes base address, interrupt number etc. GPIO pin behavior can be configured statically, or alternatively dynamically during runtime.

GPIO_init () API triggers all static configuration information available through hardware attributes. Once initialization is complete additional APIs can be used to configure and access pins.

6.5.1.2. APIs¶

API reference for Application:

#include <ti/drv/gpio/GPIO.h>

Below sequence indicates API calling sequence for a simple use case of LED toggling

...
Board_init(boardCfg);
GPIO_init();
While(1)
{
GPIO_write(Board_LED1, GPIO_PIN_VAL_HIGH);
Delay();
GPIO_write(Board_LED1, GPIO_PIN_VAL_LOW);
Delay();
}

6.5.2.1. Examples¶

Refer SDK Release Note for GPIO support across different EVMs.

6.6.1.1. Introduction¶

I2C module provides an interface to any I2C-bus-compatible device accessible via I2C serial bus. External components attached to I2C bus can serially transmit/receive data to/from the CPU through two-wire interface. Driver supports three types of transfers in both I2C master mode and slave mode

• Read
• Write
• Write followed by read

In addition driver supports following modes of operation:

• I2C_MODE_BLOCKING: By default, driver operates in blocking mode. In blocking mode, a Task’s code execution is blocked until transaction is complete. This ensures only one transaction operates at a given time. Driver supports both interrupt or non-interrupt based blocking modes.
• I2C_MODE_CALLBACK In callback mode, an I2C transaction functions asynchronously, which means that it does not block a Task’s code execution. After an I2C transaction is complete, I2C driver calls a user-provided hook function. Only interrupt based callback is supported.

Firmware

TI PRU-ICSS cores (Programmable Real-Time Unit Industrial Communication Subsystem) is firmware programmable and can take on various personalities. Processor SDK package includes I2C Firmware support. Refer I2C FW for additional details.

6.6.2.1. Driver Configuration¶

Board Specific Configuration

All the board specific configurations eg:enabling and pin-mux of I2C pins should be performed before calling any driver APIs.By default Board_Init() API supports all initialization sequence for TI supported EVMs.Refer Processor SDK RTOS Board Support for additional details.

Once the board specific configuration is complete driver API I2C_init() can be called to initialize driver

I2C Configuration Structure

I2C_soc.c file binds driver with hardware attributes on the board through I2C_config structure. This structure must be provided to I2C driver. It must be initialized before the I2C_init() function is called and cannot be changed afterwards. For details about the individual fields of this structure, see the Doxygen help by opening PDK_INSTALL_DIR\packages\ti\drv\i2c\docs\doxygen\html\index.html.

6.6.2.2. APIs¶

API reference for application:

#include <ti/drv/i2c/I2C.h>

 Sample code for initiating I2C transaction:

...
Board_init(boardCfg);
...
I2C_socGetInitCfg(peripheralNum, &i2c_cfg);
...
I2C_socSetInitCfg(peripheralNum, &i2c_cfg);
...
i2c = I2C_open(peripheralNum, &i2cParams);
...
...

/* Initiate I2C transfers. Refer Example for details
*/
I2C_transactionInit(&i2cTransaction);
transaction.masterMode   = true;
...
...
transferOK = I2C_transfer(i2c, &i2cTransaction);
if (transferOK != I2C_STS_SUCCESS) {
/* I2C transaction failed */
}

6.6.3.1. Examples¶

Refer Release Note for I2C support across different EVMs

6.7.1.1. Introduction¶

This tool demonstrates how to configure and use the Serdes Diag APIs on KeyStone 3 device family. The DIAG APIs currently support R5F arch. There are 2 tests included in the package:

• Serdes Diag BER Test
• Serdes Diag EYE Test
• Serdes Diag BER Test: The example finds out the optimal TX coefficients (CM, C1, C2) by performing Bit Error Rate (BER) sweeps on the Serdes where the EVM sends the transmit pattern (for example PRBS 31) and the EVM also detects the receive sequence and performs BER calculations across the desired serdes using the CPU. The sweep results are printed into a text file.
• Serdes Diag EYE Test The example performs on chip eye measurement allowing the user to see the eye opening of the receive data after equalization. The EVM sends the transmit pattern (for example PRBS 31) and detects the sequence and performs EYE measurements across the desired serdes using the CPU. The results are printed into a text file.

6.7.2.1. Driver Configuration¶

Serdes Diag Configuration Structure

serdes_diag_test_main.c contains the main function. It initializes all the serdes peripherals using the serdes_diag_test_init( ) API. The serdes_diag_test_phy_type should be specified in serdes_diag_platform.h in order to run the BER/EYE test for that specific SERDES.

6.7.2.2. APIs¶

API reference for application:

#include <ti/diag/serdes_diag/src/am65xx/serdes_diag_k3.h>

 Sample code for initiating Serdes Diag transaction:

...
/* Initiatize the serdes using serdes_diag_platform.h
*/
serdes_diag_test_init();
...
/* BER Test Initialization Parameters can be edited
inside this API */
Serdes_Example_BERTest();
OR
/* On Die Scope/Eye Scan Test Initialization Parameters
can be edited inside this API */
Serdes_Example_EYETest();
...
...

6.7.3.1. Examples¶

Refer Release Note for Serdes Diag support across different EVMs

6.8.3.1. Board Specific Configuration¶

All board specific configurations eg:enabling clock and pin-mux for SPI pins are required before calling any driver APIs.By default Board_Init() API supports all initialization sequence for TI supported EVMs. In addition it initializes UART instance for Console/STDIO.Refer Processor SDK RTOS Board Support for additional details.Once board specific configuration is complete SPI_init() API should be called to initialize driver.

6.8.3.2. SoC Specific Configuration¶

All SoC specific configurations (eg: SPI module registers base address, interrupt configurations, etc.) can be set using SPI_socSetInitCfg() SoC driver API before calling any SPI driver APIs. The default SoC specific configurations can be retrieved using SPI_socGetInitCfg() SoC driver API.

6.8.3.3. SPI Configuration Structure¶

The SPI_soc.c file binds driver with hardware attributes on the board through SPI_config[] structure. This structure must be provided to the SPI driver. It must be initialized before the SPI_init() function is called and cannot be changed afterwards. For details about individual fields of this structure, see Doxygen help by opening PDK_INSTALL_DIRpackagestidrvspidocsdoxygenhtmlindex.html.

Driver  requires common SPI_config[]  to configure hardware attributes of MCSPI and QSPI/OSPI peripherals on SOC and board. First all MCSPI related hardware attributes is defined followed by QSPI/OSPI hardware attributes. Application will need to include appropriate offset to instance while invoking SPI_open() API..

6.8.4.1. Open SPI¶

...
Board_init(boardCfg);
...
SPI_socGetInitCfg(peripheralNum, &spi_cfg);
...
SPI_socSetInitCfg(peripheralNum, &spi_cfg);
SPI_Params_init(&spiParams);
spiParams.transferMode = SPI_MODE_BLOCKING;
spiParams.transferCallbackFxn = NULL;
handle = SPI_open(peripheralNum, &spiParams);

SPI IP V1 driver also supports multi-channel open API’s:

...
Board_init(boardCfg);
...
MCSPI_Params_init(&spiParams);
spiParams.transferMode = SPI_MODE_BLOCKING;
spiParams.transferCallbackFxn = NULL;
handle = MCSPI_open(peripheralNum, channel, &spiParams);

At this point SPI driver is ready for data transfer in blocking mode on specific instance identified by handle. Pseudo/Sample code for SPI read/write transaction is included below. Refer example for additional details

...
spiTransaction.count = n;    /* Transfer Length */
spiTransaction. txBuf = transmitBuffer; /* Buffer to be written */
spiTransaction.rxBuf = NULL;  /* Buffer holding the received data */
transferOK = SPI_transfer(spi, &spiTransaction); /* Perform SPI transfer */
if (!transferOK) {
/* SPI transaction failed */
}

SPI IP V1 driver also supports multi-channel transfer API’s:

...
spiTransaction.count = n;    /* Transfer Length */
spiTransaction. txBuf = transmitBuffer; /* Buffer to be written */
spiTransaction.rxBuf = NULL;  /* Buffer holding the received data */
transferOK = MCSPI_transfer(spi, &spiTransaction); /* Perform SPI transfer */
if (!transferOK) {
/* SPI transaction failed */
}

6.8.5.1. SPI¶

6.8.5.2. QSPI¶

6.8.5.3. OSPI¶

6.8.5.4. MCSPI¶

6.9.1.1. Introduction¶

EDMA3 Low Level Driver is targeted to device drivers and applications for submitting and synchronizing EDMA3-based DMA transfers.

EDMA3 is a peripheral that supports data transfers between two memory mapped devices. It supports EDMA as well as QDMA channels for data transfer.

The EDMA3 LLD consists of an EDMA3 Driver and EDMA3 Resource Manager. The EDMA3 Driver provides functionality that allows device drivers and applications for submitting and synchronizing with EDMA3 based DMA transfers. In order to simplify the usage, this component internally uses the services of the EDMA3 Resource Manager and provides one consistent interface for applications or device drivers.

6.9.2.1. Driver Configuration¶

EDMA3 peripheral IP is re-used in different SoCs with only a few configuration changes:

• Number of DMA and QDMA channels supported
• Number of PARAM sets available
• Number of event queues and transfer controllers etc.

The EDMA3 peripheral is used by other peripherals for their DMA needs thus the EDMA3 Driver needs to cater to the requirements of device drivers of these peripherals as well as other application software that may need to use DMA services. Resources for EDMA driver is managed through RM sub module within driver.

6.9.2.2. APIs¶

API reference for EDMA3 driver

#include <ti/sdo/edma3/drv/edma3_drv.h>

API reference for EDMA3 Resource Management layer

#include <ti/sdo/edma3/rm/edma3_rm.h>

6.10.2.1. Driver Configuration¶

6.10.2.2. APIs¶

API reference for application:

#include <ti/drv/icss_emac/icss_emacDrv.h>

API Call Flow

The below sequence indicates the calling sequence of ICSS_EMAC driver APIs for a use case of an EMAC example which implements single Ethernet MAC using PRU-ICSS Instance 2, ETH0. For additional details refer example inside package

...
Board_init(cfg);

/* Perform MDIO init */
ICSS_EMAC_testMdioInit(CSL_MPU_PRUSS2_U_MII_MDIO_REGS);

/* Create handle for PRUICSS instance*/
ICSS_EMAC_testPruIcssHandle2= PRUICSS_create(pruss_config,2);

/* Setup crossbar configuration to receive PRU-ICSS interrupts and map them to A15 (illustration for PRU2ETH0) */
CSL_xbarDspIrqConfigure(..);  /* Link ISR */
CSL_xbarDspIrqConfigure(..);  /* RX PKT ISR */
CSL_xbarDspIrqConfigure(..);  /* TX PKT ISR */

/*Initialize driver */
...
ICSS_EmacInit(..);

/* Register callbacks for RX/TX, Link Interrupts, these are called in context of ISR */
ICSS_EmacRegisterPort0ISRCallback(..);
ICSS_EmacRegisterHwIntRx(..);
ICSS_EmacRegisterHwIntTx(..);

/* Enable interrupts for RX/TX/Link*/
ICSS_EMAC_testInterruptInit(ICSS_EMAC_testHandle2);

/* Enable Link Interrupt in MDIO sub-system */
ICSS_EMAC_testMdioEnableLinkInterrupt(..);

/* At this point, ICSS_EMAC LLD APIs can be called */
</syntaxhighlight>

Firmware

TI PRU-ICSS cores (Programmable Real-Time Unit Industrial Communication Subsystem) is firmware programmable and can take on various personalities. Examples include an SORTE, ethernet Switch, Industrial protocol switch. Please refer to ICSS-EMAC Firmwares for further explanation.

6.10.3.1. Examples¶

Refer “ICSS_EMAC_<Basic/Switch>Example_<SOC>_<CPU>Testproject” for additional reference. Refer Release Note for ICSS_EMAC supported on different EVMs.

6.11.1.1. Introduction¶

Firmware

The PRUSS (Programmable Real-Time Unit Subsystem) is firmware programmable and can take on various personalities. Examples include an ethernet MAC, ethernet Switch, Industrial protocol switch. For a good example, please refer to Simple Open Real Time Ethernet Protocol (SORTE)

Driver Features

• PRU control features i.e enable/disable/reset a PRU
• Helper functions i.e. load and execute firmware in PRU
• Memory mapping of PRU/L3/External memories
• PRU and Host event management (i.e. map sys_evt/channel/hosts in PRU INTC generate interrupts, wait for occurrence of an event, and acknowledge interrupts
• Interrupt management for A15/C66x CPU targets

6.11.2.1. Driver Configuration¶

Board Specific Configuration

All the board specific configurations like enabling the clock and pin-mux of UART/GPIO/PRUSS ICSS pins should be performed before calling any of the driver APIs.

PRUSS Configuration Structure

The pruicss_device.c file contains the declaration of the PRUICSS config structure. This structure must be provided to the driver at the time when PRUICSS_create() API is called to creat the PRUICSS_Handle. This handle is subsequently required to make any PRUSS LLD API call.

6.11.2.2. APIs¶

Reference API header file:

#include <ti/drv/pruss/pruicss.h>

API Call Flow

Below sequence indicates calling sequence of PRUSS driver APIs for a use case of sending INTC event to the PRU. Refer example code within module for additional details

...
/* Initialize Board */
Board_init(boardCfg);

/* Creates handle for PRUICSS instance */
handle = PRUICSS_create(pruss_config,instance);

/* Disable PRUICSS instance */
PRUICSS_pruDisable(handle,instance );

/* Register an Interrupt Handler for an event */
PRUICSS_registerIrqHandler(handle,pruEvtoutNum,intrNum,eventNum,waitEnable,irqHandler);

/* Sets the buffer pointer for PRU */
PRUICSS_setPRUBuffer(..);

/* API to do Interrupt-Channel-host mapping */
PRUICSS_pruIntcInit(handle,&pruss_intc_initdata);

/* Execute program on PRU */
PRUICSS_pruExecProgram(handle,0);

 /* Enable PRU */
PRUICSS_pruEnable(handle,0);

/* Generates INTC event */
PRUICSS_pruSendEvent(handle,ARM_PRU0_EVENT);

6.11.3.1. Examples¶

6.12.1.1. Introduction¶

FATFS module provides an interface to configure a driver for FAT file system compatible device that connects via MMCSD, USB, etc. It configures FATFS for disk operations driver disk Initialize, disk read, disk write

6.12.3.1. Driver Configuration¶

Board Specific Configuration

All board specific configurations eg:enabling clock and pin-mux for UART pins are required before calling any driver APIs.By default Board_Init() API supports all initialization sequence for TI supported EVMs. In addition it initializes UART instance for Console/STDIO.Refer Processor SDK RTOS Board Support for additional details.Once board specific configuration is complete FATFS_init() API can be called to initialize FATFS for the driver.

FATFS Configuration Structure

Application is expected to perform driver specific configuration for FATFS_config structure. The structure supports initialization of multiple drivers for FATFS, i.e. both MMCSD and USB can be configured to use FATFS file system by configuring each driver to different drive instance. This structure must be provided to the FATFS driver. It must be initialized before the FATFS_init() function is called and cannot be changed subsequently. For details about individual fields of this structure, see the Doxygen help:PDK_INSTALL_DIR\packages\ti\fs\fatfs\docs\doxygen\html\index.html.

6.12.3.2. APIs¶

In order to use the FATFS module APIs, the FATFS.h and ff.h header file should be included in an application as follows:

#include <ti/fs/fatfs/FATFS.h>
#include <ti/fs/fatfs/ff.h>

API Call Flow

Below sequence indicates the calling sequence of FATFS driver APIs:

FATFS_Handle FATFS;
FATFS_Params FATFSParams;
FATFS_Params_init(&FATFSParams);
FATFS = FATFS_open(peripheralNum, &FATFSParams);

At this point application can invoke additional FAT File system API eg: f_open(), f_write(), f_read() etc to perform file operations on device

6.12.4.1. Examples¶

6.13.1.1. Introduction¶

MMCSD module provides an interface between CPU and any MMCSD-bus-compatible device that connects via MMCSD serial bus. External components attached to MMCSD bus can serially transmit/receive data to/from the CPU device through two-wire interface

Key Features

•  Read
•  Write
•  Write followed by read

•  Blocking(interrupt or Non interrupt)
•  Callback mode(interrupt)

6.13.2.1. Driver Configuration¶

Board Specific Configuration

All board specific configurations eg:enabling clock and pin-mux for UART pins are required before calling any driver APIs.By default Board_Init() API supports all initialization sequence for TI supported EVMs. In addition it initializes UART instance for Console/STDIO.Refer Processor SDK RTOS Board Support for additional details.Once board specific configuration is complete MMCSD_init() API can be called to initialize driver.

MMCSD Configuration Structure

The MMCSD_soc.c file binds driver with hardware attributes on the board through MMCSD_config structure. This structure must be initialized before the MMCSD_init() function is called and cannot be changed afterwards. For details about the individual fields of this structure, see the Doxygen help by opening \docs\doxygen\html\index.html

6.13.2.2. APIs¶

Reference for API header file with documentation

#include <ti/drv/mmcsd/MMCSD.h>

API Call Flow

The below sequence indicates the calling sequence of MMCSD driver APIs for a use case of write transaction in blocking mode:

MMCSD_Handle MMCSD;
UInt peripheralNum = 0; /* Such as MMCSD0 */
MMCSD_Params MMCSDParams;
...
MMCSD_Params_init(&MMCSDParams);
MMCSD = MMCSD_open(peripheralNum, &MMCSDParams);<br>if (MMCSD == NULL) {<br> /* Error opening MMCSD */
...
readOK = MMCSD_read(MMCSD, rxBuffer , startBlock, numBlock); /* Perform MMCSD read */
if (!transferOK) { /* MMCSD transaction failed */}

writeOK = MMCSD_write(MMCSD, TxBuffer , startBlock, numBlock); /* Perform MMCSD write */
if (!writeOK) { /* MMCSD transaction failed */}

eMMC Usage

MMCSD driver supports eMMC device. Application need to configure the eMMC device for an instance of peripheral. It is also recommended to configure the operating bus width of eMMC device.

mmcsdInitCfg[MMCSD_INSTANCE].cardType = MMCSD_CARD_EMMC;
mmcsdInitCfg[MMCSD_INSTANCE].supportedBusWidth = MMCSD_BUS_WIDTH_8BIT;
MMCSD_init();

EDMA Usage

MMCSD driver supports EDMA operations to transfer data between memory and MMCSD peripheral.

Driver uses separate source files for these operations.Refer source MMCSD_soc.c for DMA MMCSD SOC configuration. Application need to create EDMA handle and update the configuration before MMCSD_init() API.

mmcsdInitCfg[MMCSD_INSTANCE].edmaHandle = MMCSDApp_edmaInit();/* Refer Example/Test */
MMCSD_init();

Refer “MMCSD_[Usecase]_[Board/SoC]_DMA_[cpu][Example/Test]project” for additional reference. Refer SDK Release Note for supported EVMs.

UHS Mode Usage

The MMCSD driver supports UHS-I cards. Feature is available for AM57x SOC and is dependent on board or platform support for run-time switching from 3.0V to 1.8V. Feature is validated on AM572x GP EVM 3.0

6.13.3.1. Examples & Unit tests¶

6.14.1.1. Introduction¶

The Queue Manager Sub System (QMSS) low level driver provides the interface to Queue Manager Subsystem hardware which is part of the Multicore Navigator functional unit for a keystone device. QMSS provides hardware assisted queue system and implements fundamental operations such as en-queue and de-queue, descriptor management, accumulator functionality and configuration of infrastructure DMA mode. The LLD provides APIs to get full entitlement of supported hardware functionality.

The LLD also includes accumulation and QoS (Quality of Service) firmware. QoS enables restriction of data rates in bytes per second or packets per second, weighted round robin queue selection, and selective descriptor dropping for oversubscribed queues. Accumulation The APIs are provided through the LLD. The API documentation for both QoS and Accumulator is available in the API Reference manual below. The capabilities of the QoS firmware are documented in their design documents. The capabilities of the accumulator are documented in the Hardware Peripheral User Guide.

Modes of Operation

QMSS library (ti.drv.qm) supports below modes

Joint Mode: In this mode, only linkingRAM0Base, linkingRAM0Size, and linkingRAM1Base are used to configure all QM groups simultaneously. For all existing devices (K2H, K2K) this is only mode that should be used. For the rest of the devices such as K2L, K2E, 6678 and 6657, this is the only mode available.

Split Mode: This mode shouldn’t be used as it doesn’t support all peripherals on the device.

6.14.2.1. Driver Configuration¶

The driver configures the QMSSSS subsystem using Qmss_GlobalConfigGroupRegs(system configuration) structure. The default global configuration per device is present under qmss_device.c file provided per device.

For details about individual fields of this structure, see the Doxygen help by opening PDK_INSTALL_DIRQMSSckagestidrvQMSSdocsdoxygenhtmlindex.html.

6.14.2.2. APIs¶

API header for application:

#include <ti/drv/QMSS/QMSS_drv.h>

Please see the doxygen in “API Reference Manual” below for details.

6.14.3.1. Examples¶

Sample Example Output

This came from K2K multicore example:

**************************************************
************ QMSS Multicore Example **************
**************************************************
**************************************************
************ QMSS Multicore Example **************
**************************************************
**************************************************
**************************************************
************ QMSS Multicore Example **************
************ QMSS Multicore Example **************
**************************************************
**************************************************
Core 1 : Starting BIOS...
Core 2 : Starting BIOS...
Core 3 : Starting BIOS...
Core 0 : Starting BIOS...
Core 0 : Created RM packet heap
Core 0 : Created IPC MessageQ heap
Core 0 : Created receive Q for Client1
Core 1 : Opened RM packet heap
Core 2 : Opened RM packet heap
Core 3 : Opened RM packet heap
Core 1 : Opened IPC MessageQ heap
Core 2 : Opened IPC MessageQ heap
Core 3 : Opened IPC MessageQ heap
Core 1 : Created receive Q for Server
Core 2 : Created receive Q for Server
Core 3 : Created receive Q for Server
Core 1 : Opened Server's receive Q
Core 1 : Waiting for QMSS to be initialized...

Core 0 : Opened Client1's receive Q for Server
Core 0 : Created receive Q for Client2
Core 0 : Opened Client2's receive Q for Server
Core 0 : Created receive Q for Client3
Core 2 : Opened Server's receive Q
Core 2 : Waiting for QMSS to be initialized...

Core 0 : Opened Client3's receive Q for Server

-----------------------Initializing---------------------------
Core 0 : L1D cache size 4. L2 cache size 0.
Core 0 : Memory region 0 inserted
Core 0 : Memory region 1 inserted
Core 0 : Tx Completion Queue Number     : 897 opened
Core 0 : Number of Tx descriptors requested : 32. Number of descriptors allocated : 32
Core 0 : Number of Rx descriptors requested : 32. Number of descriptors allocated : 32
Core 0 : Number of Sync free descriptors requested : 32. Number of descriptors allocated : 32
Core 0 : Sync Queue Number              : 9025 opened
Core 0 : Sync Cfg Queue Number          : 9026 opened
Core 0 : Sync Free Queue Number         : 898 opened
Core 0 : Receive Free Queue Number      : 736 opened
Core 0 : Transmit Free Queue Number     : 8928 opened
Core 0 : System initialization completed: 8928
Core 0 : Publishing RM nameserver names for shared queues

--------------------Queue status CORE 0----------------------
                    After Initialization

Tx Free Queue 8928 Entry Count            : 32
Rx Free Queue 736 Entry Count            : 32
Tx completion Queue 897 Entry Count     : 0
Sync Queue 9025 Entry Count              : 0
Sync free Queue 898 Entry Count         : 32
Sync Cfg Queue 9026 Entry Count          : 0
-------------------------------------------------------------

Core 0 : Registering High Priority interrupt channel : 0 eventId : 48 queue Number : 704


Core 3 : Opened Server's receive Q
Core 1 : QMSS initialization done.
Core 2 : QMSS initialization done.
Core 3 : Waiting for QMSS to be initialized...




Core 3 : QMSS initialization done.

Core 1 : Rx Free Queue Number       : 736 opened
Core 2 : Rx Free Queue Number       : 736 opened
Core 3 : Rx Free Queue Number       : 736 opened
Core 1 : Tx Free Queue Number       : 8928 opened
Core 2 : Tx Free Queue Number       : 8928 opened
Core 3 : Tx Free Queue Number       : 8928 opened
Core 1 : Tx Completion Queue Number : 897 opened
Core 2 : Tx Completion Queue Number : 897 opened
Core 3 : Tx Completion Queue Number : 897 opened
Core 1 : Sync Queue Number          : 9025 opened
Core 2 : Sync Queue Number          : 9025 opened
Core 3 : Sync Queue Number          : 9025 opened
Core 1 : Sync Free Queue Number     : 898 opened
Core 2 : Sync Free Queue Number     : 898 opened
Core 3 : Sync Free Queue Number     : 898 opened
Core 1 : Sync Cfg Queue Number      : 9026 opened
Core 2 : Sync Cfg Queue Number      : 9026 opened
Core 3 : Sync Cfg Queue Number      : 9026 opened
Core 1 : Registering High Priority interrupt channel : 1 eventId : 48 queue Number : 705
Core 2 : Registering High Priority interrupt channel : 2 eventId : 48 queue Number : 706
Core 3 : Registering High Priority interrupt channel : 3 eventId : 48 queue Number : 707
Core 1 : Waiting for sync signal
Core 2 : Waiting for sync signal
Core 3 : Waiting for sync signal
Core 0 : Opened Tx channel      : 0
Core 0 : Opened Rx channel      : 0
Core 0 : Transmit Queue Number  : 800
Core 0 : Receive Queue Number   : 704
Core 0 : Opened Rx flow         : 0
Core 0 : High priority accumulator programmed for channel : 0 queue : 704

Core 0 : Transmitting 8 packets..........

*************************************************************
Core 0 : Opened Tx channel      : 0
Core 0 : Opened Rx channel      : 0
Core 0 : Transmit Queue Number  : 800
Core 0 : Receive Queue Number   : 705
Core 0 : Opened Rx flow         : 0
Core 0 : High priority accumulator programmed for channel : 1 queue : 705

Core 0 : Transmitting 8 packets..........

*************************************************************
Core 0 : Opened Tx channel      : 0
Core 0 : Opened Rx channel      : 0
Core 0 : Transmit Queue Number  : 800
Core 0 : Receive Queue Number   : 706
Core 0 : Opened Rx flow         : 0
Core 0 : High priority accumulator programmed for channel : 2 queue : 706

Core 0 : Transmitting 8 packets..........

*************************************************************
Core 0 : Opened Tx channel      : 0
Core 0 : Opened Rx channel      : 0
Core 0 : Transmit Queue Number  : 800
Core 0 : Receive Queue Number   : 707
Core 0 : Opened Rx flow         : 0
Core 0 : High priority accumulator programmed for channel : 3 queue : 707

Core 0 : Transmitting 8 packets..........

*************************************************************
Core 0 : Waiting for sync signal
Core 0 : Got sync signal
*************************************************************


--------------------Queue status CORE 0----------------------
                    After packet processing

Tx Free Queue 8928 Entry Count            : 0
Rx Free Queue 736 Entry Count            : 32
Tx completion Queue 897 Entry Count     : 32
Sync Queue 9025 Entry Count              : 4
Sync free Queue 898 Entry Count         : 27
Sync Cfg Queue 9026 Entry Count          : 1
-------------------------------------------------------------

Core 0 : Waiting for other cores to ack sync signal
Core 1 : Got sync signal
Core 2 : Got sync signal
Core 3 : Got sync signal
*************************************************************
*************************************************************
*************************************************************



Core 0 : acks found

--------------------Deinitializing---------------------------

--------------------Queue status CORE 0----------------------
                    Before exit

Tx Free Queue 8928 Entry Count            : 0
Rx Free Queue 736 Entry Count            : 32
Tx completion Queue 897 Entry Count     : 32
Sync Queue 9025 Entry Count              : 0
Sync free Queue 898 Entry Count         : 28
Sync Cfg Queue 9026 Entry Count          : 4
-------------------------------------------------------------

Core 0 : Receive free queue closed successfully. Ref count : 0
Core 0 : Transmit completion queue closed successfully. Ref count : 3
Core 0 : Transmit free queue closed successfully. Ref count : 3
Core 0 : Sync queue closed successfully. Ref count : 3
Core 0 : Sync free queue closed successfully. Ref count : 3
Core 0 : Sync queue closed successfully. Ref count : 3
Core 0 : CPPI CPDMA closed successfully
Core 0 : CPPI exit successful
Core 0: Cleaning regions
Core 0: exit QMSS
Core 1 : Receive free queue closed successfully. Ref count : 3
Core 2 : Receive free queue closed successfully. Ref count : 2
Core 3 : Receive free queue closed successfully. Ref count : 1
Core 1 : Transmit completion queue closed successfully. Ref count : 2
Core 2 : Transmit completion queue closed successfully. Ref count : 1
Core 3 : Transmit completion queue closed successfully. Ref count : 0
Core 1 : Transmit free queue closed successfully. Ref count : 2
Core 2 : Transmit free queue closed successfully. Ref count : 1
Core 3 : Transmit free queue closed successfully. Ref count : 0
Core 1 : Sync queue closed successfully. Ref count : 2
Core 2 : Sync queue closed successfully. Ref count : 1
Core 3 : Sync queue closed successfully. Ref count : 0
Core 1 : Sync free queue closed successfully. Ref count : 2
Core 2 : Sync free queue closed successfully. Ref count : 1
Core 3 : Sync free queue closed successfully. Ref count : 0
Core 1 : Sync queue closed successfully. Ref count : 2
Core 2 : Sync queue closed successfully. Ref count : 1
Core 3 : Sync queue closed successfully. Ref count : 0
*******************************************************
*******************************************************
*******************************************************
******** QMSS Multicore (1) Example Done (PASS) *******
******** QMSS Multicore (2) Example Done (PASS) *******
******** QMSS Multicore (3) Example Done (PASS) *******
*******************************************************
*******************************************************
*******************************************************
Core 0 : Deleting RM nameserver names for shared queues
Instance name: RM_Server
Handle: 0x00854578
Type:   Server

Resource Status:

Core 0 : All resources freed successfully
*******************************************************
******** QMSS Multicore (0) Example Done (PASS) *******
*******************************************************

6.15.1.1. Introduction¶

CPPI offers developers a common way of handling different protocol interfaces that may require multiple priorities and multiple channels on a single port. CPPI defines the register set, data structures, interrupts and buffer handling for all peripherals, regardless of protocol.

CPPI is based on a buffer scatter/gather scheme, in which individual packets are broken up and then stored into small buffers, from which they are retrieved and reassembled (as opposed to using buffers that are located contiguously in memory). When protocol translation is required, a packet header can be appended in a small buffer, saving the CPU from having to rewrite the entire packet and header by performing a copy from one large buffer to another. The considerable savings in CPU cycles that result make buffer scatter/gathering the most efficient scheme for bridging and routing.

The LLD provides resource management for descriptors, receive/transmit channels and receive flows.

6.15.2.1. Driver Configuration¶

The driver configures the CPPI subsystem using cppiGblCfgParams(system configuration) structure. The default global configuration per device is present under cppi_device.c file provided per device.

For details about individual fields of this structure, see the Doxygen help by opening PDK_INSTALL_DIRCPPIckagestidrvCPPIdocsdoxygenhtmlindex.html.

6.15.2.2. APIs¶

API reference for application:

#include <ti/drv/CPPI/CPPI_drv.h>

6.15.3.1. Examples¶

Sample Example output

This came from k2k example:

**************************************************
*************** CPPI LLD usage example ***********
**************************************************
**************************************************
*************** CPPI LLD usage example ***********
**************************************************
**************************************************
**************************************************
*************** CPPI LLD usage example ***********
*************** CPPI LLD usage example ***********
**************************************************
**************************************************
*******Test running on Core 1 *******************
*******Test running on Core 0 *******************
*******Test running on Core 2 *******************
*******Test running on Core 3 *******************
Core 0 : L1D cache size 4. L2 cache size 0.
Core 2 : Starting BIOS...
Core 3 : Starting BIOS...
Core 0 : Starting BIOS...
Core 1 : Starting BIOS...
Core 0 : Created RM packet heap
Core 0 : Created IPC MessageQ heap
Core 0 : Created receive Q for Client1
Core 1 : Opened RM packet heap
Core 2 : Opened RM packet heap
Core 3 : Opened RM packet heap
Core 1 : Opened IPC MessageQ heap
Core 2 : Opened IPC MessageQ heap
Core 3 : Opened IPC MessageQ heap
Core 1 : Created receive Q for Server
Core 2 : Created receive Q for Server
Core 3 : Created receive Q for Server
Core 1 : Opened Server's receive Q
Core 1 : Waiting for QMSS to be initialized...

Core 0 : Opened Client1's receive Q for Server
Core 0 : Created receive Q for Client2
Core 0 : Opened Client2's receive Q for Server
Core 0 : Created receive Q for Client3
Core 2 : Opened Server's receive Q
Core 2 : Waiting for QMSS to be initialized...

Core 0 : Opened Client3's receive Q for Server

Core 0 : QMSS initialization done


Core 3 : Opened Server's receive Q
Core 1 : QMSS initialization done
Core 2 : QMSS initialization done
Core 3 : Waiting for QMSS to be initialized...


Core 3 : QMSS initialization done


Core 0 : QMSS CPDMA Opened
Core 1 : QMSS CPDMA Opened


Core 0 : Memory region 0 inserted
Core 0 : Number of descriptors requested : 8. Number of descriptors allocated : 8
Core 0 : Opened Rx channel : 0
Core 0 : Opened Tx channel : 0
Core 0 : Queue Number : 8192 opened
Core 0 : Queue Number : 8193 opened
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@10853b20
Receive Queue 8193 Entry Count : 1 Rx descriptor 0x@10853b20
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@10853b50
Receive Queue 8193 Entry Count : 1 Rx descriptor 0x@10853b50
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@10853b80
Receive Queue 8193 Entry Count : 1 Rx descriptor 0x@10853b80
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@10853bb0
Receive Queue 8193 Entry Count : 1 Rx descriptor 0x@10853bb0
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@10853be0
Receive Queue 8193 Entry Count : 1 Rx descriptor 0x@10853be0
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@10853c10
Receive Queue 8193 Entry Count : 1 Rx descriptor 0x@10853c10
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@10853c40
Receive Queue 8193 Entry Count : 1 Rx descriptor 0x@10853c40
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@10853c70
Receive Queue 8193 Entry Count : 1 Rx descriptor 0x@10853c70
Core 0 : Received host descriptor from Queue 897 Sucessfully
Core 0 : Tx Channel closed successfully. Ref count :0
Core 0 : Rx Channel closed successfully. Ref count :0
Core 0 : Rx queue closed successfully. Ref count :0
Core 0 : Tx queue closed successfully. Ref count :0
Core 0 : Free queue closed successfully. Ref count :0
Core 0 : Closing CPPI CPDMA Ref count : 3
Core 0 : CPPI CPDMA closed successfully
Core 1 : Memory region 1 inserted


Core 1 : Number of descriptors requested : 8. Number of descriptors allocated : 8
Core 2 : QMSS CPDMA Opened
Core 3 : QMSS CPDMA Opened
Core 1 : Opened Rx channel : 0


Core 1 : Opened Tx channel : 0
Core 2 : Memory region 2 inserted
Core 3 : Memory region 3 inserted
Core 1 : Queue Number : 0 opened
Core 2 : Number of descriptors requested : 8. Number of descriptors allocated : 8
Core 3 : Number of descriptors requested : 8. Number of descriptors allocated : 8
Core 1 : Queue Number : 1 opened
Core 2 : Opened Rx channel : 1
Core 3 : Opened Rx channel : 2
Transmit Queue 0 Entry Count : 1 Tx descriptor 0x@11853b20
Core 2 : Opened Tx channel : 1
Core 3 : Opened Tx channel : 2
Receive Queue 1 Entry Count : 1 Rx descriptor 0x@11853b20
Core 2 : Queue Number : 8192 opened
Core 3 : Queue Number : 8193 opened
Transmit Queue 0 Entry Count : 1 Tx descriptor 0x@11853b50
Core 2 : Queue Number : 8194 opened
Core 3 : Queue Number : 8195 opened
Receive Queue 1 Entry Count : 1 Rx descriptor 0x@11853b50
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@12853b20
Transmit Queue 8193 Entry Count : 1 Tx descriptor 0x@13853b20
Transmit Queue 0 Entry Count : 1 Tx descriptor 0x@11853b80
Receive Queue 8194 Entry Count : 1 Rx descriptor 0x@12853b20
Receive Queue 8195 Entry Count : 1 Rx descriptor 0x@13853b20
Receive Queue 1 Entry Count : 1 Rx descriptor 0x@11853b80
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@12853b50
Transmit Queue 8193 Entry Count : 1 Tx descriptor 0x@13853b50
Transmit Queue 0 Entry Count : 1 Tx descriptor 0x@11853bb0
Receive Queue 8194 Entry Count : 1 Rx descriptor 0x@12853b50
Receive Queue 8195 Entry Count : 1 Rx descriptor 0x@13853b50
Receive Queue 1 Entry Count : 1 Rx descriptor 0x@11853bb0
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@12853b80
Transmit Queue 8193 Entry Count : 1 Tx descriptor 0x@13853b80
Transmit Queue 0 Entry Count : 1 Tx descriptor 0x@11853be0
Receive Queue 8194 Entry Count : 1 Rx descriptor 0x@12853b80
Receive Queue 8195 Entry Count : 1 Rx descriptor 0x@13853b80
Receive Queue 1 Entry Count : 1 Rx descriptor 0x@11853be0
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@12853bb0
Transmit Queue 8193 Entry Count : 1 Tx descriptor 0x@13853bb0
Transmit Queue 0 Entry Count : 1 Tx descriptor 0x@11853c10
Receive Queue 8194 Entry Count : 1 Rx descriptor 0x@12853bb0
Receive Queue 8195 Entry Count : 1 Rx descriptor 0x@13853bb0
Receive Queue 1 Entry Count : 1 Rx descriptor 0x@11853c10
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@12853be0
Transmit Queue 8193 Entry Count : 1 Tx descriptor 0x@13853be0
Transmit Queue 0 Entry Count : 1 Tx descriptor 0x@11853c40
Receive Queue 8194 Entry Count : 1 Rx descriptor 0x@12853be0
Receive Queue 8195 Entry Count : 1 Rx descriptor 0x@13853be0
Receive Queue 1 Entry Count : 1 Rx descriptor 0x@11853c40
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@12853c10
Transmit Queue 8193 Entry Count : 1 Tx descriptor 0x@13853c10
Transmit Queue 0 Entry Count : 1 Tx descriptor 0x@11853c70
Receive Queue 8194 Entry Count : 1 Rx descriptor 0x@12853c10
Receive Queue 8195 Entry Count : 1 Rx descriptor 0x@13853c10
Receive Queue 1 Entry Count : 1 Rx descriptor 0x@11853c70
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@12853c40
Transmit Queue 8193 Entry Count : 1 Tx descriptor 0x@13853c40
Core 1 : Received host descriptor from Queue 896 Sucessfully
Receive Queue 8194 Entry Count : 1 Rx descriptor 0x@12853c40
Receive Queue 8195 Entry Count : 1 Rx descriptor 0x@13853c40
Core 1 : Tx Channel closed successfully. Ref count :0
Transmit Queue 8192 Entry Count : 1 Tx descriptor 0x@12853c70
Transmit Queue 8193 Entry Count : 1 Tx descriptor 0x@13853c70
Core 1 : Rx Channel closed successfully. Ref count :0
Receive Queue 8194 Entry Count : 1 Rx descriptor 0x@12853c70
Receive Queue 8195 Entry Count : 1 Rx descriptor 0x@13853c70
Core 1 : Rx queue closed successfully. Ref count :0
Core 2 : Received host descriptor from Queue 9026 Sucessfully
Core 3 : Received host descriptor from Queue 898 Sucessfully
Core 1 : Tx queue closed successfully. Ref count :0
Core 2 : Tx Channel closed successfully. Ref count :0
Core 3 : Tx Channel closed successfully. Ref count :0
Core 1 : Free queue closed successfully. Ref count :0
Core 2 : Rx Channel closed successfully. Ref count :0
Core 3 : Rx Channel closed successfully. Ref count :0
Core 1 : Closing CPPI CPDMA Ref count : 2
Core 2 : Rx queue closed successfully. Ref count :0
Core 3 : Rx queue closed successfully. Ref count :0
Core 1 : CPPI CPDMA closed successfully
Core 2 : Tx queue closed successfully. Ref count :0
Core 3 : Tx queue closed successfully. Ref count :0
Core 2 : Free queue closed successfully. Ref count :0
Core 3 : Free queue closed successfully. Ref count :0
Core 2 : Closing CPPI CPDMA Ref count : 1
Core 3 : CPPI CPDMA closed successfully
Core 2 : CPPI CPDMA closed successfully
Core 2 : CPPI exit successful
*******************************************************
*************** CPPI LLD usage example Done ***********
*******************************************************
Core 1 : CPPI exit successful
Core 3 : CPPI exit successful
*******************************************************
*******************************************************
*************** CPPI LLD usage example Done ***********
*************** CPPI LLD usage example Done ***********
*******************************************************
*******************************************************
Core 0 : CPPI exit successful
Core 0: exit QMSS
Instance name: RM_Server
Handle: 0x00849ee8
Type:   Server

Resource Status:

Core 0 : All resources freed successfully
*******************************************************
*************** CPPI LLD usage example Done ***********
*******************************************************

Debug FAQ

1. CPPI Lockup
   1. CPPI can lock up if any pointer or length, including hint bits, are wrong. Use the User Guide (TRM) referenced below to verify every pointer and length in the descriptor. Also verify the hint bits (low 4 bits of each descriptor) which represents size of descriptor (not data) in 16-byte units. When using CPPI it should be at least 1 (32 bytes) if no extensions are used, or 2 (48 bytes) if some extensions are used. 0 (16 bytes) is likely to cause lock up!!
2. See QMSS Debug FAQ for more.

6.16.1.1. Introduction¶

The packet accelerator (PA) is one of the main components of the network coprocessor (NETCP) peripheral in KeyStone devices, including C6678, K2H/K/E/L. The PA works together with the security accelerator (SA) and the gigabit Ethernet switch subsystem to form a network processing solution. The purpose of PA in the NETCP is to perform packet processing operations such as packet header classification, checksum generation, and multi-queue routing.

6.16.1.2. Driver Configuration¶

The driver configures the PASS subsystem using Pa_config_t structure. This structure must be initialized before the Pa_create() function is called and cannot be changed afterwards. Also, there are bunch of system/global configurations and per entry configurations for PA. For details about individual fields of this structure and other configuration API structures, see the Doxygen help by opening PDK_INSTALL_DIR\packages\ti\drv\PA\docs\doxygen\html\index.html.

6.16.1.3. APIs¶

API reference for application can be found in below file:

#include <ti/drv/PA/PA.h>

6.16.2.1. Examples¶

6.17.1.1. Introduction¶

The Security Accelerator (SA) also known as cp_ace (Adaptive Cryptographic Engine) is designed to provide packet security as part of IPSEC, SRTP, and 3GPP industry standards. The security accelerator low level driver (referred to as the module) provides APIs for the configuration and control of the security accelerator sub-system. The SA low level driver provides an abstraction layer between the application and the Security Accelerator Sub System (SASS). It provides both the system level interface and the channel-level interface with a set of APIs in the driver.

Modes of Operation

Security accelerator library (ti.drv.sa) supports below modes

Protocol Specific Mode: In this mode, standards such as Ipv4/Ipv6 and 3gpp protocols are supported, where command labels are created based on the protocols.

Data Mode: In this mode, user can implement a custom/proprietary protocol mode with the help of APIs provided by SA LLD

6.17.2.1. Driver Configuration¶

The driver configures the SASS subsystem using SA_config_t (system configuration) and Channel Configuration (Sa_ChanConfig_t) structure.

For details about individual fields of this structure and other APIs, see the Doxygen help by opening PDK_INSTALL_DIR\packages\ti\drv\SA\docs\doxygen\html\index.html.

6.17.2.2. APIs¶

API reference for application:

#include <ti/drv/SA/Salld.h>

6.17.3.1. Examples¶

NOTE : SA Unit Test applications are makefile based for AM65XX. Note that the application built, can be loaded on to CCS.

6.17.3.2. Building SA Examples/Unit Test¶

• Setup the build environment SetupBuildEnvironment

• Follow the steps SDK example and test CCS Project Creation for creating the CCS based example and test projects creation

• Create make based test application executables following the link Building the component and make based test application. Once the build environment is set, issue the following commands:

  • cd <pdk>/packages/
  • To build: make sa
  • To clean: make sa_clean

6.18.1.1. Introduction¶

Driver enables the high-bandwidth system level interconnects. It is intended to offer Gigabyte per second performance levels for chip-to-chip and board-to-board communication.

Modes of Operation

Following modes of operations are supported

Direct I/O: The SRIO packet contains the specific address where the data should be stored or read in the destination device. This means that the source device must have detailed knowledge of the available memory space within the destination device.

Type 9: A destination address is not specified. Instead the Stream ID is used to map the request to a specific memory region by the local (destination) device. TI IP additionally uses Class of Service (COS) as well to further classify the mapping of a request to a memory region.

Type 11: A destination address is not specified, instead, a mailbox identifier is used within the SRIO packet. The mailbox is controlled and mapped to memory by the local (destination) device.

6.18.2.1. Driver Configuration¶

Board Specific Configuration

All board specific configurations eg:enabling and configuring the SRIO SERDES registers and SRIO lane configurations (communication rates, device IDs, etc) are required before calling any driver APIs. Template functions for configuring the SRIO IP and SERDES registers are provided in PDK_INSTALL_DIR\packages\ti\drv\srio\device\<device>\src\. A template function is provided for each soc that supports SRIO.

6.18.2.2. APIs¶

API reference for application:

#include <ti/drv/srio/srio_drv.h>

OSAL API reference for application:

#include <ti/drv/srio/srio_osal.h>

Init SRIO

Initialize QMSS and CPPI modules...

...
SrioDevice_init();
Srio_init ();
...
/* Start the application Managed SRIO Driver. Refer example/test for appCfg fields */
hAppManagedSrioDrv = Srio_start (&appCfg);

At this point SRIO driver is ready for data transfer on specific instance identified by handle.

Send/Receive APIs

Direct IO:

Srio_sockSend_DIO(Srio_SockHandle srioSock, Srio_DrvBuffer hBuffer, uint32_t size, Srio_SockAddrInfo* to);

Type 9:

Srio_sockSend_TYPE9   (Srio_SockHandle srioSock, Srio_DrvBuffer hBuffer, uint32_t size, Srio_SockAddrInfo* to);

Type 11:

Srio_sockSend_TYPE11  (Srio_SockHandle srioSock, Srio_DrvBuffer hBuffer, uint32_t size, Srio_SockAddrInfo* to);

Receive:

Srio_sockRecv         (Srio_SockHandle srioSock, Srio_DrvBuffer* hDrvBuffer,Srio_SockAddrInfo* from);

6.18.3.1. Examples¶

6.19.1.1. Introduction¶

Hyperlink is a point-to-point peripheral. Each device has equal capability to operate on the address space of the other device. This also means that there is no complex enumeration in order to get started.

Modes of Operation

The LLD is intended to bring up the Hyperlink peripheral and open memory mappings.

Interrupts

There is an interrupt generation example (in PDK_INSTALL_DIR/packages/ti/drv/hyplnk/example/cicInterruptExample) which maps and pokes the other device’s CIC (Chip/SOC level interrupt controller) to generate interrupts for data transfers.

The PDK_INSTALL_DIR/packages/ti/drv/hyplnk/example/common/hyplnkIsr.c monitors local interrupts to detect fatal errors. It can also be used for IO interrupts, but there is only one output event that has to be demuxed. Thus for multicore orthogonality, the cicInterruptExample is often better example (because each destination core can have completely independent interrupts).

6.19.2.1. Driver Configuration¶

The driver itself is entirely configured via API at runtime. However, the examples are configured using compiler flags that are in hyplnkPlatCfg.h and hyplnkLLDCfg.h.

Hyperlink configuration structure

The hyplnk_device.c binds the driver to the hardware on the board. It is passed into the driver via the call to Hyplnk_init().

6.19.2.2. APIs¶

API Call Flow

The API call flow is covered in examplememoryMappedExamplesrchyplnkExample.

They key parts are:

1. Initialize the LLD via Hyplnk_init().
2. Configure PLL, PSC and memories via hyplnkExampleSysSetup() which is all example code
3. Install ISR(s)
4. Enable the peripheral using sequence in hyplnkExamplePeriphSetup()
5. Open memory maps using hyplnkExampleAddrMap() as a guide
6. Exchange data with memcpy or EDMA using mapped address (returned from hyplnkExampleAddrMap).

6.19.3.1. Examples¶

Hyperlink/hyplnk is supported only on Keystone devices. It is available on 6678, 6657, K2H, K2K, K2E. All examples can be used in either loopback (on any EVM without any special cables or breakout cards) or with two boards. For 6678 or 6657, the required cable is HL5CABLE. For K2H/K2K/K2E, the breakout card is RTM-BOCRT, and the cable is also required. Below is a picture showing how a K2H EVM is connected to a 6678 EVM via breakout card and cable.

Setup of multiple EVMs with one instance of CCS

This is only needed for 2 board use cases. See Multi-Emulator_Debug_with_CCS for general configuration of multiple EVMs/emulators within one instance of CCS.

Detailed instructions to run memoryMappedExample

If running with one board, enable loopback via uncommenting hyplnk_EXAMPLE_LOOPBACK in PDK_INSTALL_DIR/packages/ti/drv/hyplnk/example/common/hyplnkLLDCfg.h.

Compile the project for the specific device/evm in use.

For loopback: Load the example with hyplnk_EXAMPLE_LOOPBACK definined onto one board and run. The results should be as below.

For 2 board: Make sure the both boards configuration match each other by checking PDK_INSTALL_DIR/packages/ti/drv/hyplnk/example/common/hyplnkLLDCfg.h:

hyplnk_EXAMPLE_PORT --> which port to use for K2H/K2K/K2E
hyplnk_EXAMPLE_ALLOW_x_LANES --> 0, 1 or 4 lanes
hyplnk_EXAMPLE_SERRATE_xxpxxx --> serdes rate setup

Load the same example on both boards. It is fulling symmetric. No special configuration is needed to distinguish side A and side B. Each side should generate output similar to below.

Detailed instructions to run cicInterruptExample

This only works on devices with A15 running Linux (K2H, K2K, K2E). See PDK_INSTALL_DIR/packages/ti/drv/hyplnk/example/cicInterruptExample/Readme.txt for instructions.

Sample example output

This came from k2h device running in loopback.

Version #: 0x02010005; string HYPLNK LLD Revision: 02.01.00.05:Dec 24 2015:17:48:28
About to do system setup (PLL, PSC, and DDR)
Power domain is already enabled.  You probably re-ran without device reset (which is OK)
Constructed SERDES configs: PLL=0x00000228; RX=0x0046c495; TX=0x000ccf95
system setup worked
About to set up HyperLink Peripheral
============================Hyperlink Testing Port 0
========================================== begin registers before initialization ===========
Revision register contents:
  Raw    = 0x4e902101
Status register contents:
  Raw        = 0x00003004
Link status register contents:
  Raw       = 0x00000000
Control register contents:
  Raw             = 0x00000000
Control register contents:
  Raw        = 0x00000000
============== end registers before initialization ===========
Hyperlink Serdes Common Init Complete
Hyperlink Serdes Lane 0 Init Complete
Hyperlink Serdes Lane 1 Init Complete
Hyperlink Serdes Lane 2 Init Complete
Hyperlink Serdes Lane 3 Init Complete
============== begin registers after initialization ===========
Status register contents:
  Raw        = 0x04402005
Link status register contents:
  Raw       = 0xfdf0bdf0
Control register contents:
  Raw             = 0x00006206
============== end registers after initialization ===========
Waiting 5 seconds to check link stability
Precursors 1
Postcursors: 19
Link seems stable
About to try to read remote registers
============== begin REMOTE registers after initialization ===========
Status register contents:
  Raw        = 0x0440080f
Link status register contents:
  Raw       = 0xfdf0bdf0
Control register contents:
  Raw             = 0x00006202
============== end REMOTE registers after initialization ===========
Peripheral setup worked
About to read/write once
Single write test passed
About to pass 65536 tokens; iteration = 0
=== this is not an optimized example ===
Link Speed is 4 * 3.125 Gbps
Passed 65536 tokens round trip (read+write through hyplnk) in 16829 Mcycles
Approximately 256799 cycles per round-trip
=== this is not an optimized example ===
Checking statistics
About to pass 65536 tokens; iteration = 1
=== this is not an optimized example ===
Link Speed is 4 * 3.125 Gbps
Passed 65536 tokens round trip (read+write through hyplnk) in 16829 Mcycles
Approximately 256799 cycles per round-trip
=== this is not an optimized example ===
Checking statistics
About to pass 65536 tokens; iteration = 2
.
.
.

6.20.1.1. Introduction¶

The TSIP is a multi-link serial interface consisting of a maximum of eight transmit data signals (or links), eight receive data signals (or links), two frame sync input signals, and two serial clock inputs. Internally the TSIP offers multiple channels of timeslot data management and multi-channel DMA capability that allow individual timeslots to be selectively processed.

The module can be configured to use the frame sync signals and the serial clocks as redundant sources for all transmit and receive data signals, or one frame sync and serial clock for transmit and the second frame sync and clock for receive. The standard serial data rate for each TSIP transmit and receive data signal is 8.192 Mbps. The standard frame sync is a one or more bit wide pulse that occurs once every 125 µs or a minimum of one serial clock period every 1024 serial clocks.

At the standard rate and default configuration there are eight transmit and eight receive links that are active. Each serial interface link supports up to 128 8-bit timeslots. This corresponds to an H-MVIP or H.110 serial data rate interface. The serial interface clock frequency can be either 16.384 MHz (default) or 8.192 MHz. The data rate for the serial interface links can also be set to 16.384 Mbps or 32.768 Mbps. The maximum number of active serial links is reduced to four and two, respectively, in these configurations. The serial interface clock frequency can be either 32.768 MHz or 16.384 MHz for 16.384 Mbps serial links, and 65.536 MHz or 32.768 MHz for 32.768 Mbps serial links. Maximum occupation of the serial interface links for the entire TSIP is 1024 transmit and receive timeslots in all configurations.

6.20.2.1. Driver Configuration¶

TSIP configuration involves configurations for desired stagger phase of a TSIP timeout, using Tsip_configPhase() API. For details about individual fields of this structure, see the Doxygen help by opening PDK_INSTALL_DIR\Packages\ti\drv\TSIP\docs\doxygen\html\index.html.

6.20.2.2. APIs¶

API reference for application:

#include <ti/drv/tsip/tsip.h>

6.20.3.1. Examples¶

6.21.1.1. Introduction¶

The multichannel buffered serial port (MCBSP) peripheral allows direct interface to other TI DSPs, codecs, and other devices in a system. The primary use for the MCBSP is for audio interface purposes. The following sub sections explain the hardware (MCBSP peripheral) and software context of the MCBSP LLD.

The device driver exposes a set of well-defined APIs which are used by the application layer to send and receive data via the MCBSP peripheral. The driver also exposes a set of well-defined OS abstraction APIs which are used to ensure that the driver is OS independent and portable. The MCBSP driver uses the CSL MCBSP register layer for all MCBSP MMR access. The MCBSP driver also interfaces with the EDMA3 library to be able to transfer data to and from MCBSP peripheral and data memory.

6.21.2.1. Driver Configuration¶

The MCBSP Driver initialization API needs to be called only once and it initializes the internal driver data structures like device objects. Application developers need to ensure that they call the MCBSP Driver Init API before they call the MCBSP Device Initialization. Following API is used to initialize the MCBSP Driver

int32_t mcbspInit (void)

MCBSP Peripheral Configuration The MCBSP driver provides a sample implementation sequence which initializes the MCBSP IP block. The MCBSP Device initialization API is implemented as a sample prototype:

void McbspDevice_init (void)

For details about individual fields of this structure, see the Doxygen help by opening PDK_INSTALL_DIRPackagestidrvMCBSPdocsdoxygenhtmlindex.html.

6.21.2.2. APIs¶

API reference for application:

#include <ti/drv/MCBSP/mcbsp_drv.h>

6.21.3.1. Examples¶

6.22.2.1. Board Specific Configuration¶

All the board specific configurations eg:enabling and pin-mux of RGMII/MDIO pins should be performed before calling any driver APIs. By default Board_Init() API supports all initialization sequence for TI supported EVMs.Refer Processor SDK RTOS Board Support for additional details.

Once the board specific configuration is complete driver API emac_open() can be called to initialize driver

EMAC Configuration Structure

The emac_soc.c file binds driver with hardware attributes on the board through EMAC_Cfg structure. This structure must be provided to EMAC driver. It must be initialized before the emac_open() function is called.

For details about individual fields of this structure, see the Doxygen help by opening PDK_INSTALL_DIR\packages\ti\drv\emac\docs\doxygen\html\index.html.

6.23.1.1. Introduction¶

The multichannel audio serial port (McASP) functions as a general-purpose audio serial port optimized for the needs of multichannel audio applications. The McASP is useful for time-division multiplexed (TDM) stream, Inter-Integrated Sound (I2S) protocols, and intercomponent digital audio interface transmission (DIT).The multichannel buffered serial port (McASP) peripheral allows direct interface to other TI DSPs, codecs, and other devices in a system. The following sub sections explain the hardware (McASP peripheral) and software context of the McASP LLD.

The device driver exposes a set of well-defined APIs which are used by the application layer to send and receive data via the McASP peripheral. The driver also exposes a set of well-defined OS abstraction APIs which are used to ensure that the driver is OS independent and portable. The McASP driver uses the CSL McASP register layer for all McASP MMR access. The McASP driver also interfaces with the EDMA3/UDMA library to be able to transfer data to and from McASP peripheral and data memory.

6.23.2.1. Driver Configuration¶

The McASP driver provides a sample implementation sequence which initializes the MCASP IP block. The McASP Device initialization API is implemented as a sample prototype:

void McaspDevice_init (void)

The function initializes all the instance specific information like base address of instance CFG registers, FIFO address for the instance, TX and RX CPU event numbers, TX and RX EDMA event numbers etc.

For details about individual fields of this structure, see the Doxygen help by opening PDK_INSTALL_DIRPackagestidrvmcaspdocsdoxygenhtmlindex.html.

int32_t Mcasp_socGetInitCfg(uint32_t index, Mcasp_HwInfo *cfg)

The function obtains the soc configuration parameters such as interrupt numbers, mux configuration parameters etc.

int32_t Mcasp_socSetInitCfg(uint32_t index, const Mcasp_HwInfo *cfg)

The function set the soc configuration parameters such as interrupt numbers, mux configuration parameters etc.

6.23.2.2. APIs¶

Refer to below API files:

#include <ti/drv/mcasp/mcasp_drv.h>
#include <ti/drv/mcasp/soc/mcasp_soc.h>

McASP Buffer formats

The McASP driver provides various buffer formats for sending the data to/from the audio device. The differences between these formats arise from the way the audio samples are collected from various serializers and their timeslots and arranged in the system’s memory. This way the application can choose to run audio processing algorithms over the data without the need for re-arranging those data every frame. The buffer format is provided in the Mcasp_ChanParams.dataFormat in the form of Mcasp_BufferFormat defined in mcasp_drv.h The below section provides an overview of the various formats. In the explanatory diagrams in each section, McASP controller recieves samples in frame intervals denoted by t1,t2..tn. The McASP driver collects these and arranges those samples in the memory in various formats in to the host’s System memory. We have chosen 32 bit samples and 32-bit word addresses throughout for simplicity.

Mcasp_BufferFormat_1SER_1SLOT

This is applicable if only one serializer and one timeslot is used. The samples are ordered in the order they received or sent.

Mcasp_BufferFormat_1SER_MULTISLOT_INTERLEAVED

This is applicable if multiple slots are used with one serializer. The samples from the different timeslots are stored interleaved in the memory as below. Different timeslots’ samples are denoted by different colors and are labelled t1,t2..tn according to the time they arrive at the serializer.

Mcasp_BufferFormat_1SER_MULTISLOT_NON_INTERLEAVED

This is applicable if multiple slots are used with one serializer. The samples from the different timeslots are grouped together on the basis of the timeslot and stored in the memory as shown below. Different timeslots’ samples are denoted by different colors and are labelled t1,t2..tn according to the time they arrive at the serializer.

NOTE: if the non-interleaved format is used, the Mcasp_ChanParams-> hwFifoEventDMARatio must be set to 1.

Mcasp_BufferFormat_MULTISER_1SLOT_SER_INTERLEAVED

This is applicable if multiple serializers are used with one time slot is used for each of the serializers. The samples from the different serializers are stored in the memory in interleaved fashion as shown below Different serializers’ samples are denoted by different colors and are labelled S1,S2..Sn according to the time they arrive at the serializer.

Mcasp_BufferFormat_MULTISER_1SLOT_SER_NON_INTERLEAVED

This is applicable if multiple serializers are used with one timeslots each per serializer. The samples from the different timeslots are grouped together on the basis of the serializer and stored in the memory as shown below Different serializers’ samples are denoted by different colors and are labelled S1,S2..Sn according to the time they arrive at the serializer.

Mcasp_BufferFormat_MULTISER_MULTISLOT_SEMI_INTERLEAVED_1

This is applicable if multiple serializers are used and each serializer containing multiple timeslots. The samples are stored in the memory interleaved based on serializer and timeslots as shown below. In this example, there are 3 serializers and 2 timeslots per serializers whose samples are noted by Ln (left) and Rn (right). Different serializers’ samples are denoted by different colors.

Mcasp_BufferFormat_MULTISER_MULTISLOT_SEMI_INTERLEAVED_2

This is applicable if multiple serializers are used and each serializer containing multiple timeslots. The samples are grouped based on the serializer and within one serializer, the timeslots are interleaved as shown below. In this example, there are 3 serializers and 2 timeslots per serializers whose samples are noted by Ln (left) and Rn (right).Different serializers’ samples are denoted by different colors.

NOTE: if the non-interleaved format is used, the Mcasp_ChanParams-> hwFifoEventDMARatio must be set to 1.

Mcasp WordBits Selection

With all the frame formats explained above, there is an option to choose which bits to pack from the 32-bit serializer data obtained from/to the McASP serializer, when the word size is less than the slot size. This option is exercised by setting the Mcasp_chanParams->wordBitsSelect to Mcasp_wordBitsSelect_LSB/Mcasp_wordBitsSelect_MSB.

If the default Mcasp_wordBitsSelect_LSB option is selected, the LSBs are packed in to the system memory.

Below is an example of word size = 16bits and slot size = 32 bits and the Mcasp_wordBitsSelect_LSB option is used. On the receiving side, the serializer holds the 32 bit data whose LSB 16 bits are picked up and packed in to the system memory. The MSB 16 bits are ignored.

If the Mcasp_wordBitsSelect_MSB option is used, the serializer’s MSB-16bits are packed in to the system memory. The LSBs are ignored.

Priming

Applications using McASP driver often might send/receive one or two transfers via McASP before sending the application data in/out of McASP through the driver. This would internally set up transfer request queues so that the application can seamlessly send/receive data without the possibility of underrun. This process, a.k.a priming is used in the example application provided with the Processor SDK. In this example two frames are sent/received prior to submitting the application’s audio data to the McASP driver. The number of transfer requests to prime is application dependent and some applications where there may be a lot of delay between transfer requests, enough to cause an underrun, the priming factor could be higher.

6.23.3.1. Examples & Unit tests¶

6.24.1.1. Introduction¶

The Display Subsystem (DSS) is a flexible, multi-pipeline subsystem that supports high-resolution display outputs. DSS includes input pipelines providing multi-layer blending with transparency to enable on-the-fly composition. Various pixel processing capabilities are supported, such as color space conversion and scaling, among others. DSS includes a DMA engine, which allows direct access to the frame buffer (device system memory). Display outputs can connect seamlessly to an Open LVDS Display Interface transmitter (OLDITX), or can directly drive device pads as a parallel video output interface. This document has detailed API description that user can use to make use of the DSS driver.

6.24.2.1. Driver Configuration¶

DSS Configuration Structure

For details about individual fields of DSS library structure, see the Doxygen help by opening PDK_INSTALL_DIR\packages\ti\drv\dss\docs\doxygen\html\index.html.

6.24.2.2. APIs¶

The DSS driver API can be broadly divided into the following categories

• DSS Display API - API for video display drivers
• DSS Display Controller API - API for controlling and configuring Video Ports in the display subsystem

In addition to above drivers the DSS package also includes many sample examples which show how to use the drivers in different ways. Many of these sample examples use a common set of APIs which a user may find useful to refer to for use in their final application.

API reference for application:

#include <ti/drv/dss/include/dss_<func>.h>

6.24.3.1. Examples¶

6.25.1.1. Introduction¶

Camera Adapter Layer (CAL) is a very flexible subsystem that enables connection to multiple cameras supporting MIPI CSI-2 over D-PHY serial interface, a LVDS serial interface, and a traditional parallel interface. It also includes an internal write DMA engine connected to VBUSM interface. This document has detailed API description that user can use to make use of the CAL driver.

6.25.2.1. Driver Configuration¶

CAL Configuration Structure

For details about individual fields of CAL library structure, see the Doxygen help by opening PDK_INSTALL_DIR\packages\ti\drv\cal\docs\doxygen\html\index.html.

6.25.2.2. APIs¶

The CAL driver API can be broadly divided into the following categories

• Complex IO configuration APIs
• Capture DMA configuration APIs.

In addition to above the CAL package also includes many sample examples which show how to use the drivers in different ways. Many of these sample examples use a common set of APIs which a user may find useful to refer to for use in their final application.

API reference for application:

#include <ti/drv/cal/include/cal_drv.h>

6.25.3.1. Examples¶

6.26.1.1. Introduction¶

The DMA architecture specifies the data structures used by standard communications modules to facilitate direct memory access (DMA) and to provide a consistent application programming interface (API) to the host software in multi-core devices. The data structures and the API used to manipulate them will be jointly referred to as NAVSS. For more information on NAVSS DMA architecture, refer to the device Technical Reference Manual

The UDMA driver provides API to program the DMA portion of the NAVSS subsystem to setup and initiate transfers. Below are the high level features supported by the driver

• Both Main and MCU NAVSS instances
• Supports all DMA operations from both instances from all the cores in the SOC
• UDMAP block copy using native NAVSS channels
• DRU block copy using direct TR submission to DRU register
• DRU block copy using indirect (PSIL) TR submission to UDMA external channels
• PDMA module to initiate transfers to/from PDMA peripherals like UART, McASP, McSPI, ADC, MCAN
• DMA transfer to/from from native PSIL peripherals like EMAC, CPSW, SA2UL
• Event and interrupt management like DMA completion, channel chaining, interrupt sharing using IA
• Resources management across instances and cores for UDMAP DMA channels,RX flow, External UTC channel (DRU), interrupt aggregators (IA), interrupt routers (IR),global events, ring accelerators (RA)
• Interaction with DMSC RM module via SCICLIENT for all non-RealTime (NRT) configuration
• Supports both TI-RTOS and baremetal

Notes

• UDMA driver doesn’t manage/allocate the descriptor and RA memory.The caller need to allocate and provide the required memory.
• UDMA driver doesn’t use any global variables. All the required object memory like channel, driver instance, event etc should be allocated by the caller

This document has detailed API description that user can use to make use of the UDMA driver.

6.26.2.1. Driver Configuration¶

UDMA Configuration Structure

For details about individual fields of UDMA library structure, see the Doxygen help by opening PDK_INSTALL_DIR\packages\ti\drv\udma\docs\doxygen\html\index.html.

6.26.2.2. APIs¶

The UDMA driver API can be broadly divided into the following categories

• UDMAP native channel API
• DRU (External UTC) channel API
• PDMA channel operations
• Event and interrupt API
• Ring API

In addition to above drivers the UDMA package also includes many sample examples which show how to use the drivers in different ways. Many of these sample examples use a common set of APIs which a user may find useful to refer to for use in their final application.

API reference for application:

#include <ti/drv/udma/udma.h>

6.26.3.1. Examples¶

6.27.1.1. Introduction¶

The Power Management (PM) low level driver provide power and thermal management capabilities for RTOS applications.

Supported Devices

6.27.2.1. Driver Configuration¶

Board Specific Configuration

The following board-specific actions must take place prior to calling any PM Power APIs:

• A board-specific I2C implementation must be registered with the PM HAL layer
• The PMIC Ops structure matching the executing device’s PMIC must be registered with PM HAL layer
• Device clock rates must be initialized through the PM LIB layer

For working examples of how to implement the listed items, see the “main” functions of any PM example in [PDK_INSTALL_DIR]\packages\ti\drv\pm\examples.

PM Configuration Structure

The pmsrcpmrtosprcmPowerDevice.c file configures the PM driver through the PowerDevice_config structure. This structure must be provided to PM driver. The structure is a global defined within PowerDevice.c and must be initialized prior to calling Power_init(). The structure cannot be changed after calling Power_init(). For details about individual fields of this structure, see the Doxygen help by opening [PDK_INSTALL_DIR]\packages\ti\drv\pm\docs\doxygen\html\index.html.

6.27.2.2. APIs¶

The following lists the main application interfaces; see the end of this page for a link to the API Reference Manual with full details.

PM TI RTOS base API reference for applications can be found in below file:

#include <ti/drv/pm/Power.h>  /* Contains the core TI RTOS Power implementation APIs */

PM TI RTOS extended API reference for applications can be found in the below file:

#include <ti/drv/pm/PowerExtended.h>  /* Contains TI RTOS Power API extensions such as thermal management */

PM TI RTOS device-specific API reference for applications can be found in the below file:

#include <ti/drv/pm/PowerDevice.h>  /* Contains device-specific TI RTOS Power API definitions and structures */

6.27.3.1. Examples¶

6.28.1.1. Introduction¶

The Resource Manager (RM) is delivered as part of Processor-SDK as a means for managing system resource contentions. RM has the ability to allocate system resources within a software architecture based on sets of allocation rules. Resources can be allocated to anything from a device core, to an OS task or process, to a specific software module. RM’s resource management is defined by the RM configuration parameters and how RM is integrated within a software framework. The RM source code is device agnostic. The RM configuration parameters are device specific allowing RM to function on any processor capable of compiling and executing a C binary.

RM Instance Types

Resource Manager is an instance-based architecture. Integrating RM into a system consists of creating a set of RM instances, connecting these instances via message-passing mechanisms, and then using the instances to request resources for cores, processes, tasks, modules, etc. There are no restrictions on where a RM instance can be created as long as the means exist to connect the instance to other RM instances within the system.

There are five instance types

1. Server: Manages all defined system resources. Services resource requests received from connected Client Delegates and Clients.
2. Client Delegate (CD): Acts as a low-request-latency proxy for the RM Server, managing resources provided by the RM Server. Services resource requests received from connected Clients.
3. Client: Front-end for receiving/responding to resource requests from application. Forwards resource requests to Server, or CD, for servicing. Returns allocated resources to application once response is received from Server or CD.
4. Shared Server: Same as the standard Server except all resource data structures are stored in shared memory allowing direct access from Shared Client instances.
5. Shared Client: Same as Client except has direct access to the Server resource data structures via shared memory. Useful for low latency requests but not as robust from a software architecture perspective given shared memory MUST be available and used in order for Shared Server-Clients to function.

6.28.2.1. Driver Configuration¶

Resource Configuration

The RM Server instance must be provided a resource list and allocation policy at initialization time. The resource list and allocation policy are specified in the open source flattened device tree format. Device specific resource list and allocation policy files are provided in [PDK_INSTALL_PATH]/packages/ti/drv/rm/device/[SoC]/.

The Client Delegate and Client instances do not require a resource list and allocation policy at initialization.

Transport Configuration

RM instances must be attached to one another using a message passing mechanism. This mechanism can be shared memory, software/hardware queues, sockets or any other method capable of sending and receiving data packets between endpoints on the SoC.

An example transport implementation used by many PDK test applications is available in [PDK_INSTALL_PATH]/packages/ti/drv/rm/test/rm_transport_setup.c. The implementation uses an IPC shared memory transport to connect an RM Server to RM Clients on multiple DSP cores.

6.28.2.2. APIs¶

RM instance init/delete/status API reference for application:

#include <ti/drv/rm/rm.h>

RM instance transport API reference for application:

#include <ti/drv/rm/rm_transport.h>

RM instance service request/response API reference for application:

#include <ti/drv/rm/rm_services.h>

RM Server interface API reference for application:

#include <ti/drv/rm/rm_server_if.h>

6.28.3.1. Examples¶

6.29.1.1. Introduction¶

The general-purpose memory controller (GPMC) is an unified memory controller dedicated to interfacing external memory devices:

• Asynchronous SRAM-like memories and application-specific integrated circuit (ASIC) devices
• Asynchronous, synchronous, and page mode (only available in non-multiplexed mode) burst NOR flash devices
• NAND Flash

Driver supports two types of transfers with data path to external memory device configured to be 16- or 8-bit:

• Read
• Write

• GPMC_MODE_BLOCKING: By default, driver operates in blocking mode. In blocking mode, a Task’s code execution is blocked until transaction is complete. This ensures only one transaction operates at a given time. Driver supports both interrupt or non-interrupt based blocking modes.
• GPMC_MODE_CALLBACK In callback mode, an GPMC transaction functions asynchronously, which means that it does not block a Task’s code execution. After an GPMC transaction is complete, GPMC driver calls a user-provided hook function. Only interrupt based callback is supported.

In NAND flash mode, driver supports following ECC algorithms:

• BCH code 8-bit
• HAMMING code 1-bit

6.29.2.1. Driver Configuration¶

Board Specific Configuration

All the board specific configurations eg:enabling and pin-mux of GPMC pins should be performed before calling any driver APIs.By default Board_Init() API supports all initialization sequence for TI supported EVMs.Refer Processor SDK RTOS Board Support for additional details.

Once the board specific configuration is complete driver API GPMC_init() can be called to initialize driver

GPMC Configuration Structure

GPMC_soc.c file binds driver with hardware attributes on the board through GPMC_config structure. This structure must be provided to GPMC driver. It must be initialized before the GPMC_init() function is called and cannot be changed afterwards. For details about the individual fields of this structure, see the Doxygen help by opening PDK_INSTALL_DIR\packages\ti\drv\gpmc\docs\doxygen\html\index.html.

6.29.2.2. APIs¶

API reference for application:

#include <ti/drv/gpmc/GPMC.h>

 Sample code for initiating GPMC transaction:

...
Board_init(boardCfg);
...
...
gpmc = GPMC_open(peripheralNum, &gpmcParams);
...
...

/* Initiate GPMC transfers. Refer Example for details
*/
transferOK = GPMC_transfer(gpmc, &gpmcTransaction);
if (!transferOK) {
/* GPMC transaction failed */
}

6.29.3.1. Examples¶

Refer Release Note for GPMC support across different EVMs

6.30.4.1. Build targets¶

The driver provides targets for building library, unit tests and docs . The library and unit tests can be built from PDK_BUILD_PATH or SCICLIENT_PATH . The docs can only be built from SCICLIENT_PATH .

Note

For building the example "sciclient_firmware_boot" or "your application" using SCIClient lib, make sure you have a section "boardcfg_data" defined in your linker cmd file which resides in OC-MSRAM .

The next sections will explain how to load the system firmware using sciclient.

6.30.4.2. Load using a boot-media¶

Follow these steps to load the sciclient_firmware_boot application through a boot media:

• Build the example: sciclient_firmware_boot_TestApp
• The test case works with MMCSD boot mode where it loads the sysfw.bin file from the mmcsd card. Ensure to create a tiboot3.bin file from the sciclient application. Copy the SoC specific sysfw.bin in the SD card along with the tiboot3.bin file.
• Refer the section Boot-Modes for details on how to use a bootmedia.
• You can also use the SBL to load the system firmware and initialize the SoC. Refer to the SBL user guide for more details.

6.30.4.3. Load using CCS¶

Follow these steps to load the sciclient_ccs_init application through CCS

• Update the File SCICLIENT_PATH/sciclient/tools/ccsLoadDmsc/<soc>/launch.js for the following variables to your PC location .

Modify for AM65xx:

//Path to GEL files
gelFilePath = "<Your CCS Path>/ccs_base/emulation/gel/AM65xEVM/"; → GEL path location
// Path to the directory in which this file would be residing. CCS expects
// absolute paths to load the binaries.
thisJsFileDirectory = "PDK_INSTALL_DIR/packages/ti/drv/sciclient/tools/ccsLoadDmsc";

Modify for J721E:

//PDK path. Edit this
pdkPath = "PDK_INSTALL_DIR";

• Connect the Javascript to the CCXML file with the steps shown below: (Note: this step needs to be repeated if you switch workspaces or clean your workspace).The Javascript is run on re-launch of the ccxml. If you would like to run the Javascript without relaunch then you can look ahead to the section: “Re-running the script once ccxml is already launched.” Click on Debug Configurations from the button as follows:

  

• Select the CCXML file from the left-hand side and populate the path to the launch_am65xx.js file in the “Initialization Script” free form field and click on “Apply”.

  

• Once you Launch the ccxml the java script would automatically run and connect to R5F.

Re-running the script once ccxml is already launched

In the CCS window open the “View → Scripting Console..” In the CCS Scripting Console type:

load("SCICLIENT_PATH\\tools\\ccsLoadDmsc\\am65xx\\launch.js")

js:> load("SCICLIENT_PATH\\tools\\ccsLoadDmsc\\am65xx\\launch.js")
Connecting to DMSC_Cortex_M3_0!
Loading DMSC Firmware...
DMSC Firmware Load Done...
DMSC Firmware run starting now...
Connecting to MCU Cortex_R5_0!

js:> load("SCICLIENT_PATH\\tools\\ccsLoadDmsc\\j721e\\launch.js")
Connecting to DMSC_Cortex_M3_0!
Loading DMSC Firmware...
DMSC Firmware Load Done...
DMSC Firmware run starting now...
Connecting to MCU Cortex_R5_0!
Running the board configuration initialization from R5!
Running the DDR configuration... Wait till it completes!
Okay you are good to go.. Happy Debugging!

6.30.4.4. Handling Two or more ccxml files¶

In case you need to connect two or more board to the same CCS session and use the launch script, please follow the steps below:

• When you use 2 or more CCXML files with similar debugger (e.g. connect 2 boards XDS110 on-board debugger to the PC), CCS would enumerate the debuggers as below:

::

Texas Instruments XDS110 USB Debug Probe_0 Texas Instruments XDS110 USB Debug Probe_1

Notice the suffix “_0” and “_1”. - In order to use the same launch.js file with this, please create a second copy of the launch.js file. Update the first launch.js files as below:

function updateScriptVars()
{
    //Open a debug session
    dsMCU1_0 = debugServer.openSession( "*_0.*MCU_PULSAR_Cortex_R5_0" );
    dsDMSC_0 = debugServer.openSession( "*_0.*DMSC_Cortex_M3_0" );
}

Update the second launch.js as below:

function updateScriptVars()
{
    //Open a debug session
    dsMCU1_0 = debugServer.openSession( "*_1.*MCU_PULSAR_Cortex_R5_0" );
    dsDMSC_0 = debugServer.openSession( "*_1.*DMSC_Cortex_M3_0" );
}

Notice the addition of “*_0” and “*_1”

6.30.6.1. SCIClient Core¶

The following core APIs for SCIClient are declared in sciclient.h.

Firmware Load

This API loads SYSFW.The image must be loaded through a boot media for this API to succeed (Refer Build and Run). Hence, this is typically called by SBL. Load firmware call does not require Sciclient_init to be done before.

Defined in sciclient.h as Sciclient_loadFirmware.

Typical usage

static const uint32_t gSciclient_firmware[BINARY_FILE_SIZE_IN_BYTES / 4U] =SCICLIENT_FIRMWARE;
.
.
.
Sciclient_loadFirmware(gSciclient_firmware);

SCIClient initialization

This API is called once for registering interrupts and creating semaphore handles to be able to talk to the firmware. The application should assume that the firmware is pre-loaded while calling this API. The firmware should have been loaded either via GEL or via the SBL (refer Sciclient_loadFirmware ) prior to the application calling this.

The API Sciclient_init takes a pointer to Sciclient_ConfigPrms_t as input.

• The parameter opModeFlag allows 2 operation modes for Sciclient_service :

  opModeFlag	Description
  Polling based	Invoked using SCICLIENT_SERVICE_OPERATION_MODE_POLLED
  Interrupt based	Invoked using SCICLIENT_SERVICE_OPERATION_MODE_INTERRUPT

Definition

Defined in sciclient.h as **Sciclient_init**.

Note

- This API provides a software initialization for the driver. Any application using SCIClient must call this API.
- SCICLIENT_SERVICE_OPERATION_MODE_INTERRUPT is not supported as of now.

Typical usage

Sciclient_ConfigPrms_t        config =
{
    SCICLIENT_SERVICE_OPERATION_MODE_POLLED,
    NULL
};
Sciclient_init(&config);

SYSFW communication

This API allows communicating with the System firmware which can be called to perform various functions in the system. Core SCIClient function for transmitting payload and recieving the response. The caller is expected to allocate memory for the input request parameter Sciclient_ReqPrm_t . This involves setting the message type being communicated to the firmware, the response flags, populate the payload of the message based on the inputs in the files located at include/tisci/ . Since the payload in considered a stream of bytes in this API, the caller should also populate the size of this stream in reqPayloadSize. The timeout is used to determine for what amount of iterations the API would wait for their operation to complete.

To make sure the response is captured correctly the caller should also allocate the space for Sciclient_RespPrm_t parameters. The caller should populate the pointer to the pRespPayload and the size respPayloadSize. The API would populate the response flags to indicate any firmware specific errors and also populate the memory pointed by pRespPayload till the size given in respPayloadSize.

Defined in sciclient.h as **Sciclient_service** .

Typical usage

const Sciclient_ReqPrm_t      reqPrm =
{
    TISCI_MSG_VERSION,
    TISCI_MSG_FLAG_AOP,
    NULL,
    0,
    SCICLIENT_SERVICE_WAIT_FOREVER
};

struct tisci_msg_version_resp response;
Sciclient_RespPrm_t           respPrm =
{
    0,
    (uint8_t *) &response,
    sizeof (response)
};
status = Sciclient_init(&config);
status = Sciclient_service(&reqPrm, &respPrm);

SCIClient de-initialization

De-initialization of sciclient. This de-initialization is specific to the application. It only de-initializes the semaphores, interrupts etc. which are initialized using Sciclient_init . It does not de-initialize the system firmware.

Defined in sciclient.h as **Sciclient_deinit** .

Typical usage

Sciclient_deinit();

Board configuration

One time board configuration needs to be done from R5 for rm,pm and security to communicate with SYSFW. It is normally done by SBL, so user doesn’t need to call these APIs.

User needs to define a section ”.boardcfg_data” in the linker file for the default configuration (NULL pointer to Sciclient_BoardCfgPrms_t is passed to the APIs), which needs to be present in OCMRAM . If user provides custom board_cfg, then the data must be present on OCMRAM.

Board configuration structure is defined in include/V0/sciclient_boardcfg.h as Sciclient_BoardCfgPrms_t.

Typical usage

status = Sciclient_boardCfg(NULL);
if (CSL_PASS == status)
{
    status = Sciclient_boardCfgPm(NULL) +
            Sciclient_boardCfgRm(NULL) +
            Sciclient_boardCfgSec(NULL) ;
}

6.30.6.2. SCIClient Shim Layer¶

Power management

The APIs in include/sciclient_pm.h provide declarations of SCIClient APIs for power management of the SOC .

Resource management

The APIs in include/sciclient_rm.h provide declarations of SCIClient APIs for resource management of the SOC .

Processor BOOT API Interface

The APIs in include/sciclient_procboot.h provide declarations of SCIClient APIs for processor boot and control.

APIs are divided into the following two sets

• Book keeping APIs - Meant to control access to allow a reasonable usage scenario of processors.
• Processor Control APIs - Meant to be the actual Processor Corecontrols.

6.31.1.1. Introduction¶

VPS (Video Processing SubSystem) video Drivers allow users to make use of all video hardware features like 1080P capture, HDMI/LCD/SDTV display, deinterlacing, scaling. A user can use the drivers in many different ways like multi-channel capture, memory to memory processing, display and so on. This document has detailed API description that user’s can use to make use of the VPS drivers.

VPS consists of following modules

• Video Input Port (VIP) - for video capture functions for the device
• Video Processing Engine (VPE)- for video operations such as color space convertion, deinterlacing, scaling and chroma upsampling features.
• Display SubSystem (DSS) - for LCD outputs on three parallel interfaces (DPI1, DPI2, and DPI3) and HDMI

6.31.2.1. Driver Configuration¶

Board Specific Configuration

All board specific configurations eg:enabling clock and pin-mux for UART/display/vip pins are required before calling any driver APIs. The board specific configurations are implemented under <pdk>/ti/drv/vps/src/boards/src folder.

VPS Configuration Structure

For details about individual fields of VPS library structure, see the Doxygen help by opening PDK_INSTALL_DIR\packages\ti\drv\vps\docs\doxygen\html\index.html.

6.31.2.2. APIs¶

The VPS driver API can be broadly divided into the following categories

• FVID2 API - API used to create, control and use the different VPS drivers
• VPS (Video Processing Sub-system) API - API for all video drivers
• VPS Control Driver API
• VPS Capture API - API for video capture drivers
• VPS VIP Capture API - API specific to VIP capture driver
• VPS DSSWB Capture API - API specific to DSS WB capture driver
• VPS Display API - API for video display drivers
• VPS Display Controller API - API for controlling and configuring VENCs in the display subsystem
• VPS Memory to Memory (M2M) API - API for memory to memory drivers
• M2M VPE API - API specific to VPE M2M driver
• External Device API - API for controlling external video devices like video decoders, video encoders, video filters, IO expanders, Ultra-sonic sensors
• Platform Specific API - API for platform/board specific control, like setting pin muxes, clocks etc
• Board Specific API - API for board specific features.

In addition to above drivers the VPS package also includes many sample examples which show how to use the drivers in different ways. Many of these sample examples use a common set of APIs which a user may find useful to refer to for use in their final application.

API reference for application:

#include <ti/drv/vps/include/vps_<func>.h>

6.31.3.1. Examples¶

* Starting from Processor SDK 4.2 release, idkAM574x support is added for VPS.
* Starting from Processor SDK 4.2 release, oV1063x camera part support is added for AM572x - GP evm (older Aptina MT9T11 camera is never supported).
* Starting from Processor SDK 3.2 release, osd101t2587 lcd panel is supported (new part) along with osd101t2045 lcd panel (old part) on idkAM572x
  and idkAM571x boards for all display subsystem examples.
* The bare metal examples are added starting from Processor SDK 4.0 release
* Some of the clocks such as 32KHz Sync clock are directly tied to A15 core and need that core to be running. Hence while testing the code on other cores
  such as DSP/IPU, please make sure to disconnect the ARM core after connecting the ARM core & running the GEL files to enable the other cores and before
  loading the executable on that core.

6.31.6.1. Display DSS Example¶

Description

The example exploits the DISPC (Display Controller) and LCD/HDMI outputs available in the SoC. When run, the test outputs multiple options to select between to demonstrate the various capacity of the display subsystem. There is also option to select “Auto Run”, when selected runs all the tests in sequential manner. The example works on outputing a pre-loaded video frames of YUV422I and BGR888 formats to DP1, DP2 and DP3 parallel interfaces and also to HDMI output observed on TV set, from VID1, VID2, VID3 and GFX pipelines. The example also demonstrates displaying videos combined from GFX and other VID pipelines to DPI1 LCD output. The example is also enhanced to show the display controler scaling features. Test that exploits the scalar unit to show all possible allowed scaling. Maximum scaling ratio supported is the ratio of the dss functional clock / pixel clk. Please refer to section “11.2.4.10.4.2 DISPC Scaling limitations” of AM57x Technical Reference manual for minimum ratio allowed when using the scalar unit.

Running the Display DSS example

Configuring Display:

• Make sure the LCD panel is connected to the base EVM before running the example binary.
• Make sure the HDMI is connected to TV from the EVM for HDMI display options.
• For AM571x IDK EVM, installing a shunt on header J51 to short those pins

CCS connection:

• Load the generated executable file in CCS
• Run the application, Select any of the option and load the buffer as suggested.
• Content will be displayed on the LCD panel or HDMI TV connected to EVM for test options

The rar file can be unrar-ed to get the test files using utilities such as https://www.7-zip.org Please download the latest version of 7-zip from this website. The command to unrar is: 7z x {file_to_unrar}