3. Board/EVM Abstration¶

3.1. Board Support¶

Introduction

APIs

The Board_init() API supports initialization of PLL, peripheral clocks, external DDR memory, pinmux and IO Delay configurations. API Reference for application:

#. include <ti/board/board.h>

Example API pseudo code for Board_init() is as follows:

/* Setting up for pinmux and uart */
Board_STATUS ret;
Board_initCfg boardCfg;

boardCfg = BOARD_INIT_MODULE_CLOCK \| BOARD_INIT_PINMUX_CONFIG \|
BOARD_INIT_UART_STDIO;

ret = Board_init(boardCfg);

LLD Dependencies

I2C

Application need to configure BOARD_INIT_MODULE_CLOCK option to have I2C operational. I2C is used to read EEPROM data. An I2C handle will be opened in polling mode, and closed after the board ID data is retrieved from EEPROM using Board_getIDInfo() API.

For DRA7xx EVMs, I2C is also used to configure various I/O expanders and board muxes to enable PDK examples to function properly on the EVM. The I2C handles are opened in polling mode and closed after the board mux initialization has completed.

UART

Application need to configure Board_init() with the BOARD_INIT_UART_STDIO option to use the UART stdio API.

After Board_init() completes, application can invoke UART stdio functions such as UART_printf, UART_scanFmt, and etc.

Application Integration for AM5x/DRA7xx

When configuring pinmux with IO Delay settings for AM5x and DRA7xx boards, there is a hard restriction: the code/data/stack during the IO Delay setup must be within local internal memory. Refer to SOC TRM for additional information.

The board library specifies two sections for users to define for the sole purpose of meeting this requirement. They are: BOARD_IO_DELAY_CODE and BOARD_IO_DELAY_DATA. Below are examples of how to specify these section into the local memory, OCMC_RAM1:

In baremetal case with a linker cmd file:

BOARD_IO_DELAY_CODE : {

   . = ALIGN(4);
   *(BOARD_IO_DELAY_CODE*)

} > OCMC_RAM1

BOARD_IO_DELAY_DATA : {

   . = ALIGN(4);
   *(BOARD_IO_DELAY_DATA*)

} > OCMC_RAM1

In a CCS RTSC project with .cfg file:

Program.sectMap["BOARD_IO_DELAY_DATA"] = "OCMC_RAM1";
Program.sectMap["BOARD_IO_DELAY_CODE"] = "OCMC_RAM1";

Considerations for DRA7xx devices

When integrating the board library in applcations on DRA7xx, these code/data sections will likely overlap and conflict with the code/data sections used by the Secondary Boot Loader (SBL) as both modules will assume full access to OCMC_RAM1. Also, as the SBL performs identical configuration using the common pad config data structures, the pinmux request made by an application will be redundant. Therefore, it is advised that the pinmux API be used only when loading the application via CCS. When loading via SBL, there are three options available for handling this conflict:

1. Place the BOARD_IO_DELAY_DATA/BOARD_IO_DELAY_CODE sections to another internal memory location. The Board library will check to see if the board code/data/stack are located in internal memory before executing the sequence. If another internal memory section is available for placement (e.g. L2SRAM, OCMC_RAM2), then it is acceptable to place the sections in these locations. The Board init sequence will proceed as expected.
2. Place the BOARD_IO_DELAY_DATA/BOARD_IO_DELAY_CODE sections into external memory. The pinmux subroutine in the Board library checks for code/data/stack placement and will fail if it detects that they reside in DDR and return before performing the configuration. The failure will not affect any other Board init requests as other flags are treated orthogonally.
3. Remove the BOARD_IO_DELAY_DATA/BOARD_IO_DELAY_CODE sections. This is the preferred solution as it removes redundant code from executing and will optimize code/data size and load speed. In order to remove these sections, two modifications are required:
   • Place BOARD_IO_DELAY_DATA/BOARD_IO_DELAY_CODE input sections into an output Dummy Section (DSECT). DSECTs are a Special Linker Section Type which are relocated for linker resolution but otherwise do not allocate space to a memory map, place sections in the output file, or ever get loaded to the target. In order to place these sections into DSECTS, modify the placement as follows:

Replace:

Program.sectMap["BOARD_IO_DELAY_DATA"] = "OCMC_RAM1";
Program.sectMap["BOARD_IO_DELAY_CODE"] = "OCMC_RAM1";

With:

Program.sectMap["BOARD_IO_DELAY_DATA"] = new Program.SectionSpec();
Program.sectMap["BOARD_IO_DELAY_CODE"] = new Program.SectionSpec();
Program.sectMap["BOARD_IO_DELAY_DATA"].type = "DSECT";
Program.sectMap["BOARD_IO_DELAY_CODE"].type = "DSECT";

• Remove the BOARD_INIT_PINMUX_CONFIG flag from the call to Board_init. Since the BOARD_IO_DELAY_DATA/BOARD_IO_DELAY_CODE sections no longer actually exist, we must instruct the application that it is no longer safe to call the routines and access the data. Otherwise, the CPU will branch to and access undefined memory and cause various exceptions

Custom Board Addition

Pinmux and IO Delay

Custom Board Library

1. Set up your build environment according to the Building the RTOS SDK page.
2. Create your own folder under the src directory. The name of this folder will be your board name (will be referred to as $BOARD). Put your source files in this src/$BOARD folder. Updated sources can also include initialization sequence for additional devices specific to board.
3. Pinmux Update (see above note for applicable devices):
   • Use the TI PinMux Tool to generate the new pinmux files. Refer the PinMux tool documentation on how to select pinmux for all the device pads and generate the pinmux data files.
   • The four generated files are:
     • boardPadDelay.h: Includes the prototypes of all structures and functions used by pinmux functions
     • boardPadDelayInit.c: Includes the pinmux pad config data for all device pads along with values used to compute Manual/Virtual mode values.This data is used to configure pinmux during board initialization.
     • boardPadDelayTune.h: This file includes the compile time macros used to select the Timing modes to be configured for modules during board Initialization.
     • boardPadDelayDevice.c: This file includes the pinmuxdata for runtime pinmux configuration of the MMC module.
   • Some platforms not requiring IO delay configurations will have two files <Platform Name>pinmux.h and <Platform Name>_pinmux_data.c files generated by the pinmux tool
   • Copy the pinmux tool generated files to your custom board library implementation folder.
   • Note: It is recommended to use the latest available PinMux Tool. For PinMux Tool prior to version v4.0.1482, you will have to edit boardPadDelayTune.h to select appropriate IO timing modes by uncommenting the build macros.
4. SOC Clock Settings Update: The core clocks and module clocks used on the custom board library may vary based on the power requirements and external components used on the boards. TI provides Clock Tree Tools to simulate the device clocks. GEL file can be used to verify the settings in CCS before modifying the source in the board library.
5. SOC DDR Configuration Update: The board library has the correct DDR initialization sequence to initialize the DDR memory on your board. You may need to make changes to the AC timings, hardware leveling, and DDR PHY configuration, some or all of which may be different than the TI supported platforms. GEL file can be used to verify the settings in CCS before modifying the source in the board library.
6. IO Instance and Configuration update to Match Use Case: If your custom board uses an IO instance different from the TI-supported board, the instance needs to be modified in the Pin Mux setup as well as in the board_cfg.h file in pdk_xx_Xx_xx_xx/packages/ti/board/src/<customBoardName>/
7. Updating the Files Corresponding to External Board Components: The custom board may have external components (flash devices, Ethernet PHY, etc.) that are different from the components populated on the TI-supported EVM. These components and their support files need to be added to the pdk_xx_Xx_xx_xx/packages/ti/board/src/<customBoardName>/device path and linked as part of the board library build.
8. PLL Settings Update: The SOC board library in the PDK configures the SOC PLL and module clock settings to the nominal settings required to be used with the TI evaluation platform. If you want to use different clock settings due to power consideration, or if you are using a variant of the device that needs to be clocked differently, you can enter the PLL and clock settings in the board library. All of the PLL and module clock settings are consolidated in the following files:
   • <Board>.c: Contains calls related to all board-level initialization. <Board> refers to the evaluation platform (For example, evmam335x)
   • <EVM>_pll.c: Defines the Board_PLLInit() function that configures the dividers and multipliers for the clock tree.
   • <EVM>_clock.c: Defines clock dividers, scalars, and multipliers for individual board modules initialized using the board library.
9. Create build makefile infrastructure for new board under <ti/board/build>. Please refer existing board makefiles for reference.
10. Update top level makefile <ti/board/makefile> for additional support of new boards.

Adding custom board to the PDK directory structure and build setup is described in the article Adding_Custom_Board_Library_Target_to_Processor_SDK_RTOS_makefiles

3.2. Diagnostics¶

Overview

The Processor SDK RTOS Diagnostic package is designed to be a set of baremetal tests to run on a given board to provide data path continuity testing on peripherals. For K2H/K2E/K2L/C66x devices, this functionality is provided by POST.

Building the Examples

Pre-requisites to Building

1. Set your environment using pdksetupenv.bat or pdksetupenv.sh. The diagnostic application uses the same environment variables as the board library build. Refer to the Processor SDK RTOS Building page for information on setting up your build environment.
2. You will need the following libraries built:

• Board
• UART
• GPIO
• I2C
• SPI
• CSL
• ICSS
• PRUSS

(Note: not every library is used for every application, and these libraries should come pre-built with any fresh installation of the Processor SDK)

Compiling the Diagnostic Applications

To build the diagnostic examples:

1. cd <PDK>/packages/ti/board/diag
2. make <BOARD>

This will make the diagnostic applications for a specific $BOARD. Alternatively, “make all” will make for all boards. Output files will be located in: <PDK>/packages/ti/board/bin/<BOARD>

Creating the SD Card Loadable Files

For converting the compiled .out files to a format loadable by TI’s Secondary Boot Loader (SBL), you must follow these two steps:

1. out2rprc.exe [.out file] [rprc output]
2. MulticoreImageGen.exe LE 55 [output name] 0 [rprc output]

Out2rprc.exe and MulticoreImageGen.exe are tools supplied by TI and can be located in the <PDK>/packages/ti/boot/sbl/tools folder. “rprc output” can be any spare name of your choosing. “output name” can also be any name of your choosing. For diagnostic applications, your final output name must have the keyword “TEST” in it. You will have to do this process for every .out application you wish to be loadable on the SD card.

Alternatively, there is also a make target to automate this process:

1. cd <PDK>/packages/ti/board/diag
2. make <BOARD>_sd

This will compile all the applications for a specific $BOARD, and also create the SD card loadable files. The output files will be located in: <PDK>/packages/ti/board/bin/<BOARD>/sd. Note that the framework application is named “app” to allow it to be the default application to be loaded by the SBL.

Creating the SPI Flash Loadable Files

SPI boot shall be the primary boot option for the platforms (Ex: AMIC110 ICE) which does not support SD card interface. All the diagnostic tests are integrated into framework binary for the ease of use in the case of SPI boot. Integrated diagnostic framework test binary can be loaded and executed through UART port.

Use below command to build the diagnostic tests and create SPI flash loadable files.

• make <BOARD>_spi

Make targets

The simplest invocation is to use “make <BOARD>” to compile all the applications. Here is a list of make targets implemented for the diagnostic makefile:

• make <BOARD> - compile all diagnostic applications for one specific BOARD
• make clean - clean and remove all applications for all supported BOARDs
• make <BOARD>_clean - clean and remove all application for one specific BOARD
• make <BOARD>_sd - compile all diagnostic applications for one specific BOARD and create the SD card loadable files with those compiled applications
• make <BOARD>_spi - compile all diagnostic applications for one specific BOARD and create the SPI flash loadable files with those compiled applications

The <BOARD> supported depends on your Processor SDK RTOS variant. Refer to following table for available <BOARD> for each Processor SDK RTOS variant:

Note: OMAPL137 EVM diagnostic tests does not support executing from a boot device. Use the command make evmOMAPL137 to build the diagnostics. Diagnostics test binaries need to be executed from CCS.

Running the Diagnostic Examples

Loading through SD Card (Default Method)

Your SD card must be set up to a bootable format. Refer to the Processor SDK RTOS Boot page for information on how the SD card is handled.

You will need to compile the diagnostic applications for your BOARD, created their respective SD card loadable files, and copied them onto an SD card. You will also need the SBL (renamed to “MLO”) on the SD card. To do so:

1. cd <PDK>/packages/ti/board/diag
2. make <BOARD>_sd
3. copy all the content under <PDK>/packages/ti/board/bin/<BOARD>/sd to your SD card
4. copy the MLO to your SD card (default location at <PDK>/packages/ti/boot/sbl/binary/<BOARD>/mmcsd
5. insert your SD card into your board and power on your board
6. open Terminal emulator program eg: Teraterm to connect to the board’s UART console
7. press the “Hard Reset” button on your board. (This is to force re-booting, and not absolutely necessary. Because Terminal emulator program is opened after boot is powered on, you would’ve missed the initial printout messages. This step is for demonstration and confidence checking that the board has booted correctly)

You should see the following screen:

The framework diagnostic application should be loaded through SBL, and gives you the options:

• help - prints the command menu and descriptions of the commands
• run - run a diagnostic application found on the SD card
• status - current status of the framework run

Below is an example of running a diagnostic application:

Result of return from above run:

Loading through SPI Flash

This section describes creating the diagnostic test images for SPI flash booting, programming and running them from SPI flash. Currently SPI boot is supported only by iceAMIC110 platform.

You will need to compile the diagnostic applications for your BOARD, create their respective SPI flash loadable files, and program them onto SPI flash. To do so:

1. cd <PDK>/packages/ti/board/diag
2. make <BOARD>_spi
3. Start CCS and launch target configuration file for AMIC110 ICE board
4. Connect the target, load and run the SPI flash writer binary. Prebuilt SPI flash writer is available at <AM335x PDK>packagestistarterwaretoolsflash_writerspi_flash_writer_AM335X.out
5. Choose option 1 to initiate image flashing
6. Enter the file name as SPI bootloader along with full path (Ex: <AM335x PDK>packagestistarterwarebinarybootloaderbinam335x-evmgccbootloader_boot_mcspi_a8host_release_ti.bin)
7. Enter offset as 0
8. Wait until flashing completes successfully
9. Rerun the SPI flash writer binary and program diagnostic framework loader at offset 20000. Diagnostic framework loader binary will be available at <AM335x PDK>packagestiboardbiniceAMIC110spiapp
10. Rerun the SPI flash writer binary and program diagnostic framework at offset 40000. Diagnostic framework binary will be available at <AM335x PDK>packagestiboardbiniceAMIC110spiframework

Sample CCS output of SPI flash writer is shown below:

1. open Terminal emulator program eg: Teraterm to connect to the board’s UART console
2. press the “Hard Reset” button on your board. (This is to force re-booting, and not absolutely necessary. Because Terminal emulator program is opened after boot is powered on, you would’ve missed the initial printout messages. This step is for demonstration and confidence checking that the board has booted correctly)

You should see the following screen:

• help - prints the command menu and descriptions of the commands
• run - run a diagnostic application found on the SD card
• status - current status of the framework run

Below is an example of running a diagnostic application:

Running or debugging on CCS

To debug your application, CCS can give you access to the chip’s memory and register values. You can follow the below steps to load and run an application in CCS. If you have a SD card loadable image, and is able to load your application, you can connect to the A15 core in CCS and load symbols without having to load and run the entire application. After running “make all” or “make $BOARD”, the output files should be generated under <PDK>/packages/ti/board/bin/ directory. You will have to navigate down to the $BOARD you’re building (eg. idkAM572x, evmAM572x, etc.) and the $TARGET core you’re building for (eg. armv7).

For the existing diagnostic applications, you may need to define PDK_RAW_BOOT before compiling. This is done by adding the line “#define PDK_RAW_BOOT” to an individual application source file or to <PDK>/packages/ti/board/src/<BOARD>/include/board_cfg.h to apply for all applications. This is used because the default diagnostic loading method is through SD card, and the pinmux is done already. Adding this option only forces the diagnostic applications to do pinmuxing within the application itself (and not depend it being done).

To run on CCS:

1. Connect USB cable to the board’s JTAG
2. Connect the UART serial cable. For the IDK boards, the UART console is the same as the usb JTAG connector, so no additional cable is necessary.
3. Plug in power cord to your board
4. Press the power button on the board to turn the board on
5. Setup and run CCSv6.1 (or higher). Follow the Processor SDK RTOS Getting Started Guide on how to setup your CCS to connect to the board
6. Launch target configuration for the board
7. Connect to the core that you built your application for. For example: for idkAM572x armv7 projects, click on the Cortex A-15 MPU0 core and press the connect button
8. Load the program by pressing the load button and navigate the explorer to the .out file that you want to load
9. Press the Run button to run the program
10. Check UART console to see if anything is printed out. **If nothing is printed out, pause the core and see where the program counter is at. If it is at 0x3808c (or near it), try reloading the program and running again.

Note: On omapl13x platforms diagnostic tests can only be run from CCS as SBL support is not available at this point. Diagnostics are built for both DSP (C674x) and ARM (arm9) cores on omapl13x platform.

Running on a different ARM core

The diagnostic baremetal applications are typically targeted for Core 0 of an ARM corepac. It is possible to load and run it on one of the subcores in CCS. To do so, please consider the following:

1. Enable Cache - setup typically only enables cache for the main ARM core. You may have to explicitly enable the data and instruction cache. See relevant cache functions under pdk/packages/ti/csl/arch.
2. [For AM57x boards] Set OPP to high - SBL would set OPP to high for Core 0, but may not do it for the subcores. You can do so by using the GEL file. After connecting to the core, run the function under Scripts -> AM572x PRCM CLOCK configuration -> AM572x_PRCM_Clock_Config_OPPHIGH (similarly named for AM571x).

Diagnostic Applications

Additional Jumper or Hardware Settings

Current Monitor

For iceK2G, this test expects J16 and J17 to be connected with jumper shunts. This enables the current monitors to be used.

GMAC

For idkAM572x, idkAM571x, idkAM574x and evmAM572x, this test expects loopback plugs to be used on both Ethernet ports. These loopback plugs will loopback the TX lines back to the RX lines. The Ethernet ports are the RJ-45 connectors labeled “Ethernet” on the board.

ICSS EMAC

For idkAM572x, idkAM574x and idkAM571x, this test expects loopback plug to be used on J6. These loopback plugs will loopback the TX lines back to the RX lines. For iceK2G, this test expects loopback plugs to be used on all four ICSS EMAC ports.

LCD Touchscreen

For idkAM572x, idkAM574x and idkAM571x, this test expects the LCD module to be connected. This requires the two ribbon cables (one for display, one for the capacitive-touch IC) to be connected.

McSPI

For idkAM572x, idkAM574x and idkAM571x, this test expects pins to be connected to the Industrial I/O header. The Industrial I/O header, J37, has two columns in parallel, one of which is the McSPI input and the other being VDD. Thus, connecting any row with a jumper will yield a ‘1’ read on that McSPI input. By connecting the first, second, third, and forth row with jumpers would yield 0x1, 0x2, 0x4, and 0x8 being read respectively.

PWM

PWM output generated while running the diagnostic test can be verified at below pins.

evmK2G - J12 pin 33

evmAM572x - P17 pin 5

idkAM437x - J16 pin 14

evmAM335x - J5 pin 13

3.3. Power-On Self Test¶

Overview

The Power-On Self Test (POST) boot is designed to execute a series of platform/EVM factory tests on reset and indicate a PASS/FAIL condition using the LEDs and write test result to UART. A PASS result indicates that the EVM can be booted. POST is supported on K2H/K2E/K2L/C66x devices, this functionality is provided on other devices (e.g., AM57x) by Diagnostics.

POST will perform the following functional tests:

• External memory read/write test
• NAND read test
• NOR read test
• EEPROM read test
• UART write test
• LED test

Additionally, POST provides the following useful information:

• FPGA version
• Board serial number
• EFUSE MAC ID
• Indication of whether SA is available on SOC
• PLL Reset Type status register

Compilation

The recommended rule-of-thumb to compiling projects in the Processor SDK RTOS package is to use the makefiles provided. The makefiles are usable after setting up your shell/terminal/command prompt environment with the setupenv.bat or setupenv.sh script located in

[SDK Install Path]/processor_sdk_rtos_<platform>_<version>

Refer to Processor SDK RTOS Building the SDK guide on how to setup your environment for building within any of the Processor SDK RTOS packages.

To compile the POST application:

cd [SDK Install Path]/pdk_<platform>_<version>/packages/ti/boot/post/<platform>/build
make all

This will create the .out executable that can be loaded via CCS

Flashing POST Image

To flash a bootable image of POST, please refer to the SDK RTOS Flashing Bootable Images guide.

C66x LED Code

For C66x, the on-board LEDs can also provide diagnostic information on POST routines. Refer to the following table: