Industrial SDK EMAC Porting Guide1

Migrating a TI SYSBIOS Industrial SDK project to a custom development board

This migration guides describes the steps involved to port an existing TI SYSBIOS Industrial SDK project (such as an example project) to a custom development/production board. The custom board that may have a number of component substitutions from the TI board. The guide will touch upon the changes required for the inclusion of additional components to the board. The primary items which change in moving from one platform to another are the

• PinMux settings
• Clock and timer configuration changes.
• Memory configuration
• Interrupt changes
• IO changes (MII, MDIO,GPIO,UART)
• Board component substitutions
• Board Initialization (drawing from all of the above)

This discussion draws upon the information and links that are contained in:

PRU-ICSS Industrial Software for Sitara(TM) Processors

Sitara ISDK2.1 Industrial SDK Training for AM335x and AM437x

AM3359 Industrial Communications Engine

AM437x Industrial Development Kit (IDK)

Please refer to these documents for additional detail and explanations

Figure 1 shows the Industrial SDK architecture. When migrating an existing design to a custom board – many of the changes will be covered by SDK Board specific sections. The Board specific information is contained in both the Starterware board level APIs and in the SYSBIOS Board level APIs.

The Starterware board level APIs, shown in the lower right of Figure 1, provide a high level abstraction for the PinMux, Clock tree, configuration, Board devices, Memory Map, Board level mux controls, board power, and IO expanders. The Starterware board APIs perform auto-detection of board type and definition and then develop the abstraction based upon the board configuration and the on board device descriptions. The board module draws device descriptions of the onboard devices from the Device module.

The SYSBIOS board level APIs, shown in the center of Figure 1, provide driver APIs for accessing device peripheral modules from an application. This has implementations for Digital Inputs, Digital Outputs, Flash memory (QSPI and SPI), Rotary Switch, TLK100 Ethernet Phy, integrated matrix monochrome display.

There are different build configurations present for AM3x and AM4x. A number of these are based upon the Starterware Board APIs.

The industrial SDK is built on top of SYSBIOS. SYS/BIOS is an advanced real-time operating system from Texas Instruments for supporting in a wide range of DSPs, ARMs, and microcontrollers. It is designed for use in embedded applications that need real-time scheduling, synchronization, and instrumentation. SYS/BIOS provide a wide range of system services.

SYSBIOS contains the XGCONFIG graphical configuration tool which is used within CCS helps to create the static configuration used by SYS/BIOS at build time. Using this tool - one can choose which software modules to include, change default values of parameters to tune performance for each application, and create RTOS objects such as threads and semaphores.

For more information on SYSBIOS please go to

http://processors.wiki.ti.com/index.php/SYS/BIOS_Training:_Introduction_to_SYS/BIOS

Modifying Board and device files for custom platform development

Each TI SYSBIOS Industrial SDK project has a set of Starterware and SYSBIOS board files that configure and initialize board configuration information. These drivers are named (by convention) after the development board. By configuring a few specific files, the porting process from one development board to another is relatively straight forward. The files that need to be modified to create a custom board are shown below. The files are separated into four groups. The Starterware and SYSBIOS board files are the files that are used to define and configure a device that on the board. If the custom platform has the same type and number of devices as a TI board but with some configuration differences, these files are used to configure the board. When additional devices or number of devices are added to the custom board, then the definition and operation of these components must be defined. The component definition and operation is defined in the SYSBIOS and Starterware Device files.

Starterware Board files

{IA_SDK_HOME}\sdk\starterware\include\Board.h

{IA_SDK_HOME}\sdk\starterware\board\<device name>\<dev board name>.h

{IA_SDK_HOME}\sdk\starterware\board\<device name>\<dev board name>.c

Starterware Device files

{IA_SDK_HOME}\sdk\starterware\board\board.c

{IA_SDK_HOME}\starterware\device\< DeviceName>.h

{IA_SDK_HOME}\starterware\device\< DeviceName>.c

SYSBIOS Board files

{IA_SDK_HOME}\sdk\board\include\ board_<DeviceName>.h

{IA_SDK_HOME}\sdk\board\include\<dev board name>\board_<DeviceName>.h

{IA_SDK_HOME}\sdk\board\source\board_support.c

SYSBIOS device files

{IA_SDK_HOME}\sdk\board\source\drivers\board_<DeviceName>.c

{IA_SDK_HOME}\sdk\board\source\\<dev board name>\board_<DeviceName>.c

Where device name is = am335xx or am437xx
Where dev board name is = icev2AM335x or idkAM437x
Where DeviceName is = phy, led, lcd, mux, support, rotaryswitch, spiflash, board_qspi, …

In developing a new board it is often useful to create new files for those files with the <dev board name> file names with the name chosen for Project. For example when developing a custom board named “Project” from the AM437x IDK one could copy the idkAM437x directories and files into new “Project” directories and files. During the process of copying the board files it will necessary to update a number of board definitions and function names plus the #include and #define directives and function names as necessary.

Adding a new device to the board data

To add a new device to the board data

• Add an identifier in {IA_SDK_HOME}\starterware\include\device.h

This file contains the device module interface. It contains the identifiers for devices on the boards. It also contains the prototypes for functions for probing devices over the I2C bus, for those devices which are connected to I2C.

For example:
DEVICE_ID_LED  = 0x4U,
/**< LED device ID. */

• Add the device information in IA_SDK_HOME}\starterware\board\SOCNAME\SOCNAME_BOARDNAME.c

This file contains the implementation of board information for SOCNAME based boardname. For example this could be in the case of an AM43xx based IDKEVM board.

const boardDeviceData_t gBoardAm43xxIdkevmDevData[] =
{ 					/* TRICOLOR LED */
       DEVICE_ID_LED,                  /* devId */
       0U,                             /* devInstNum the Instance number 0,1,2,… */
       CHIPDB_MOD_ID_GPIO,             /* ctrlModId  What is the controlling module */
       2U,                             /* ctrlModInstNum  Which GPIO instance is used */
       24, 				/* ctrlInfo   GPIO Pin Number 24 controls LED */
       CHIPDB_MOD_ID_INVALID,          /* dataModId */
       INVALID_INST_NUM,               /* dataModInstNum */
       NULL,                           /* pFnSelectDev */
       NULL,                           /* pFnResetDev */
       NULL                            /* pFnPowerOnDev */
 },

• The API’s declarations for accessing the board data are contained in {IA_SDK_HOME}\starterware\include\board.h

For example:
chipdbModuleID_t BOARDGetDeviceCtrlModId(uint32_t devId, uint32_t devInstNum);
Where 
   devId = DEVICE_ID_LED
   devInstNum = 0U
   will return CHIPDB_MOD_ID_GPIO which is the control module for LED.

The board components reference the Chip DB details. The ChipDB is used to abstract the SoC details across all the platforms through APIs and Headers. A description of the ChipDB details is contained in the “StarterWare 02. 01. 01. XX Board and ChipDB Details Update Guide” in

{IA_SDK_HOME}\Starterware\src\starterware\docs in the section ChipDB details.

GEL, Boot and Application based configuration settings

GEL

To operate the new board under CCS, it is often necessary to update the General Extension Language (GEL) file. The GEL configures the Code Composer Studio development environment and initializes the target CPU. The GEL file contains configuration settings for Clocks, Power, DDR, and Boot. The determination of the settings to be used for each of these are covered in subsequent sections.

Additional information on creating GEL files are available at:

http://processors.wiki.ti.com/index.php/GEL

http://processors.wiki.ti.com/index.php/CCStudio_FAQ#GEL

Boot

When operating the new board with standalone media booting, the RBL [Read Only Memory BootLoader], residing in the ROM of the SoC copies the boot loader from the respective flash device to onchip RAM and gives control to it. The boot loader initializes the PLLs and enables peripheral clocks and then it initializes the DDR. Once all the initialization is done, the boot loader copies the application from flash to the DDR and transfers control to the application. The application then starts execution from DDR. The boot loader is built to support each SOC, Flash media, and board. The bootloader project is found at {IA_SDK_HOME}\starterware\bootloader. This project will draw upon the Starterware board, dal, soc, utils, ff9b_lib and mmscd definitions. Please see the Building Bootloader section in {IA_SDK_HOME}\sdk\docs\SYSBIOS Industrial SDK 02.01.01 User Guide.pdf for additional detail.

Note –The MII and boot pins are shared. When bringing up the board the first step is to configure SYSBOOT pins to boot the device. Then later once the boot is 
complete, then the  MII pins are configured for the Ethernet phys.

If the Ethernet phys have a conflicting boot/sw strap configuration, then a special Ethernet phy reset may be required (as is done on the ICEv2)

Application

Each application contains an initialization section. In the initialization section the application will Identify the board type Enable the pin mux configuration Initialize and configure the SOC components Initialize and configure board components

Examples of this initialization is contained in the main sections of the examples

Note -  SYS/BIOS does not provide any APIs for configuring the AM3359 clock. 

To configure the AM3359 clock, a startup sequence that performs the clock initialization in inserted prior to main() execution. There are three possible initializations that can be performed using any of the following three options in the .cfg file:

.var Startup = xdc.useModule('xdc.runtime.Startup');
Startup.resetFxn = '&myClockSetup'; 	/* called before variables are initialized*/
       or:
Startup.firstFxns.$add('&myClockSetup'); 	/* called before BIOS modules are initialized */
      or:
Startup.lastFxns.$add('&myClockSetup'); 	* called after BIOS modules are initialized */

PinMux

The PinMux tool provides an intelligent automated solution to the complex problem of pin selection. The pin mux tool and supporting literature is available at: http://processors.wiki.ti.com/index.php/TI_PinMux_Tool. The Pin MUX Utility is a software tool which provides a Graphical User Interface for configuring pin multiplexing settings, resolving conflicts and specifying I/O cell characteristics for TI MPUs. The resulting configuration settings are output as C header/code files that can be imported the software development kit (SDK). The TI PinMux tool automatically determines the Sitara mux configuration for a specified set of external peripheral signals. The determination of which pins to use is performed without requiring manual evaluation of the possible pin configuration options. The PinMux tool generates the configuration code that is used by the board module APIs to configure the device at runtime.

The pin mux tool output is contained in a file that is saved in /Starterware/board/SOCNAME/SOCNAME_BOARDNAME_pinmuxdata.c

The pinmux output specifies the settings by subsystem group such as UART, USB, PWMSS, PRU_ICSS, CPSW, GPMC, MMCSD, QSPI, VPFE, MCSPI, GPIO, ADC, etc. The subsystem group pinmux data IDs are defined in {IA_SDK_HOME}/Starterware/include/SOCNAME/chipdb_defs.h

During the initialization section, the application selects the defined pin mux settings to enable by defining a pin mux configuration and then calling Board_pinMuxConfig(PINMUX_config “NAME”);

For example:

PINMUX_config  iceV2Mux[] =
{
   {CHIPDB_MOD_ID_GPIO, 0, 0}, 
   {CHIPDB_MOD_ID_GPIO, 1, 0},
   {CHIPDB_MOD_ID_GPIO, 2, 0},
   {CHIPDB_MOD_ID_GPIO, 3, 0},
   {CHIPDB_MOD_ID_I2C, 0, 0},
   {CHIPDB_MOD_ID_MCSPI, 0, 0},
   {CHIPDB_MOD_ID_MCSPI, 1, 0},
   {CHIPDB_MOD_ID_PRU_ICSS, 1, 0},
   {0xFFFFFFFF, 0, 0}
};

The configuration is then enabled by using the Board_pinMuxConfig(PINMUX_config “NAME”);

For example:

Board_pinMuxConfig(iceV2Mux);

Additional information on updating the pin mux data manually is available in the “StarterWare 02. 01. 01. XX Board and ChipDB Details Update Guide” in {IA_SDK_HOME}\Starterware\src\starterware\docs in the section Updating Pin Mux Data.

When changes are made to the pinmux file, it is necessary to rebuild the board project so that the changes are available to the ISDK examples and customer developed applications. The Pinmux for each pin is controlled by the mux value set for that particular pin in the pad control register. The Pad Control register description is contained in the Control Module of the device TRM. Although this register has a number of control settings, two settings are important to signal and direction selection of a pin. The receive active (bit 18) and the mux mode setting (bit 3-0) enable the input buffer and select the signal for the pin. The control module base address for the AM335x and AM437x is 0x44E10000. This is described in the memory map section of the TRM.

The signal configurations that can be selected for each pad are listed in the device data sheet in the Terminal Configuration section. The Starterware pinmux API's set the configuration of the control register. Before the Starterware pin configuration API is called the pad configuration register will have the default value as described in the pin attributes table of the data sheet.

The PRU-ICSS supports an internal pinmux selection option that expands the device-level pinmuxing for a number of GIO inputs and GPO outputs. The internal pinmuxing is programmable through the PIN_MX register of the PRU-ICSS CFG register space as described in the TRM section PRU-ICSS Internal Pinmux.

How to configure PinMux for Industrial Ethernet

The industrial Ethernets are implemented using the PRU-ICSS to meet the real time protocol requirements. The PRU-ICSS supports only the MII interface.

A description of the pins that are used for AM335 and AM437 EtherCAT operation are described in AM335x & AM437x SOC pins used for EtherCAT functionality which is part of the PRU ICSS EtherCAT firmware API guide. The configuration shown in the link above will support EtherCAT, Profinet, Sercos III, and EthernetIP. EthernetIP may also require Half-Duplex support depending on the use case. When there is a Half-Duplex requirement, it will be necessary to also connect the PR1_MIIn_COL/CRS pins from the PHY.

Each of the Industrial ethernet protocols has specific LED requirements. In the Sitara AM437x IDK and AM335x ICEV2 EVMs, the support for these multiple requirements are met generally using tri color LEDs. However these are not intended as a complete example solution for a product since there is specific labelling and positioning requirements in each standard’s specification.

One of the key things to consider is that the MII and boot pins are shared. During device initialization the SYSBOOT signals are configured support the device boot. Then later once the boot is complete, the MII signals are pins are configured connect to the Ethernet phys. If the Ethernet PHYs have a conflicting boot software strap configuration, then an Ethernet PHY reset may be required to correctly configure the PHY.

Clock and Timer

To simplify the complex task of clock configuration, Texas instruments has developed a clock tree tool. The Sitara clock tree tool is visual interactive configuration tool that provides information about the clocks and modules in Sitara devices. Using this tool a developer can see and interact with both the visual clock tree elements and with the PRCM registers. This interactive visual tool enables the developer to have a global view of the device clock tree architecture and to easily determine the correct register settings for a specific configuration.

The clock tree tool is available at Sitara Clock Tree Tool. The AM335x clock tree tool description is available at AM335x Clock Tree Tool. The AM437x AM335x clock tree tool description is available at

AM437x Clock Tree Tool.

The clock values are used in the bootloader, GEL, SOC and (in some cases) the application.

The boot loader initializes the PLLs, enables the peripheral clocks, initializes the DDR, sets the operating frequencies, loads the application from the respective media to DDR, and hands over control to DDR. The boot loader configuration files are in

{IA_SDK_HOME}\sdk\starterware\bootloader\src\am43xx

{IA_SDK_HOME}\starterware\bootloader\src\am335xx

The GEL files are located in

{IA_SDK_HOME}\ tools\gel.

The Starterware clock register data values are stored in include file configuration settings in

{IA_SDK_HOME}\sdk\starterware\include\am437x\am437x

{IA_SDK_HOME}\starterware\include\am335x.

Note:  The DMtimer operation can be affected by the changes in the clock 
frequencies based upon the clock input that is selected for timer input 
TIMERx_GCLK (where x is the DMTimer number) in the PRCM.

Memory

DDR configuration – DDR configuration tools

DDR configuration is performed in the boot loader and the GEL files. The Sitara DDR configuration tools describe how to set the EMIF registers depending on the DDR memory type. There are separate DDR configuration guides for the AM437x and AM335x devices.
The AM437x DDR Configuration and Programming Guide are available at:

AM437x DDR Configuration & Programming Guide. The AM335x EMIF Configuration tips are provided at:

AM335x EMIF Configuration tips.

Additionally there is additional information available on line to assist in resolving Common DDR Issues that is available at:

http://processors.wiki.ti.com/index.php/Common_DDR_Issues.

MMU Configuration

Device memory is configured in the “application”, the SYSBIOS configuration file, GEL, and the boot loader. The application initialization contains the MMU configuration for the SOC and application specific configurations. When memory and peripheral changes can impose changes to the memory configuration in the application, the MMU configuration can be changed in the application with SYS_MMU_ENTRY mmuEntries[]
This is defined in:

{IA_SDK_HOME}\sdk_osdrivers\include\osdrv_mmu.h.

The mmu table is then set at the start of the application by calling SDKMMUInit(SYS_MMU_ENTRY mmuEntries[])
SDKMMUInit is defined in:

{IA_SDK_HOME}\sdk_osdrivers\source\osdrv_mmu.c.

Examples of MMU configurations are available in:

C:\ti\sysbios_ind_sdk_2.1.1.2\sdk\examples\ethernetip_adapter\appl_cnfg.h

In addition - Memory section configurations can be further specified 
using <application>xdt files and in the application directory. 
Examples of these configurations can be found in:
   C:\ti\sysbios_ind_sdk_2.1.1.2\sdk\examples\ethernetip_adapter\ethernetip.xdt 
   C:\ti\sysbios_ind_sdk_2.1.1.2\sdk\examples\ethercat_slave\ethercat.xdt

Other Memory Parameter settings

The SYSBOS configuration file contains description of the Stack size and heap size.

The GEL and the boot loader will contain (as a minimum) a basic device and memory configuration.

Interrupt

The general SOC board interrupts are configured using the APIs contained in:

{IA_SDK_HOME}\sdk\board\source\ and its subdirectories.

There are separate subdirectories for the AM335ICV2 and AM437ISDK board specific peripherals. PRU-ICSS interrupts are configured in the application. Example of the PRU-ICSS interrupt configurations are available in:

C:\ti\sysbios_ind_sdk_2.1.1.2\sdk\examples\ethernetip_adapter\tieip_pruss_intc_mapping.h

C:\ti\sysbios_ind_sdk_2.1.1.2\sdk\examples\ethernet_mac\tiemac_pruss_intc_mapping.h

The [ICSS EMAC LLD developers guide http://processors.wiki.ti.com/index.php/ICSS_EMAC_LLD_developers_guide] has an excellent section on AMR / PRU interrupts.

How to add support for other PHYs

The TI example industrial Ethernet designs use the TLK1xx PHYs to date. A number of customers have successfully used the Texas Instruments the Texas Instruments DP83x PHYs. For EtherCAT slave applications - Beckhoff provides an excellent Phy selection guide to assist in Phy selection and configuration. This is available at:

https://download.beckhoff.com/download/Document/io/ethercat-development-products/an_phy_selection_guidev2.3.pdf.

This document also specifies the LED display requirements for Ethernet PHY signals.

The Texas Instruments EtherCAT slave implementation supports both Phys which provide a High Speed Link indication and those that do not. This setting is changed using the using ICSS MDIO_LINK register.
The default configuration is that the High Speed Link indication is enabled.

mdioParamsInit.enhancedlink_enable = TIESC_MDIO_RX_LINK_ENABLE;

Different PHYs may use a positive or negative polarity for the highspeed link detection. This can be detected by making and breaking the Ethernet connection and observing the state reported by the

• MDIO PHY alive status register (MDIO_ALIVE) to verify the connection
• MDIO PHY link status register (MDIO_LINK) to verify the link.

The polarity of the link detection can be configured by:

mdioParamsInit.link0pol = TIESC_LINK_POL_ACTIVE_HIGH;

and

mdioParamsInit.link1pol = TIESC_LINK_POL_ACTIVE_LOW;

When a m/c based link polling link status detection mechanism is desired - the following setting is made:

mdioParamsInit.enhancedlink_enable = TIESC_MDIO_RX_LINK_DISABLE;

This setting is used in the case of EtherCAT when the PHY does not have LED_LINK/LED_SPEED signal and when a m/c based link detection is desired. The m/c based link detection configuration is also used for the other industrial ethernet slave implementations (Profinet, EthernetIP, and Sercos III).

When using the m/c based link detection, the link detection is performed by reading the MDIOLink register and configuring an interrupt from MDIO through ICSS INTC. This is the mechanism that used by the ICSS-EMAC and briefly described in the Processor SDK EMAC design [Interrupt]

The MDIO polling frequency is configurable. The default frequency was selected for the TLK PHYs and is in the range of 200-250 usec. Other PHYs may require different polling frequencies. This value can set as low as 10us levels by programming SWCR3 register IIRC.

The PRU_ICSS MDIO host side APIs are explained in the PRU-IICSS EtherCAT firmware API guide [MDIO host side APIs].

When the PHY does not have LED_LINK/LED_SPEED signal, the "pr1_mii0_rxlink" and "pr1_mii1_rxlink" inputs can be terminated inactive.

Debugging

Industrial Ethernet Debugging techniques

Check Link and Activity LEDs

There are two LEDs just above the RJ-45 Ethernet port,

Right side indicates network speed

Orange for 10 MBPS

Green for 100 MBPS

Left side indicates the network activity

No color at all means no link present

Solid color means that there is an active link

Blinking means that there is data activity

Each protocol has additional operation specific EDS

Check master side log for errors
Check PRU MDIO for the PHY and link status

The MDIO registers are standard for the PRU and CPSW. The definitions are in the:

TRM-CPSW section(Ethernet-:Subsystem->Ethernet Subsystem Registers->MDIO Registers)

AM335x PRU-MDIO base address is 0x4a33_2400

AM437x PRU_MDIO base address is 0x5443_2400

MDIO alive. - offset = 8h Each of the 32 bits of this register is set if the most recent access to the PHY with address corresponding to the register bit number was acknowledged by the PHY, the bit is reset if the PHY fails to acknowledge the access. Both the user and polling accesses to a PHY will cause the corresponding alive bit to be updated. The alive bits are only meant to be used to give an indication of the presence or not of a PHY with the corresponding address.

MDIO_LINK - offset = Ch This register is updated after a read of the Generic Status Register of a PHY. The bit is set if the PHY with the corresponding address has link and the PHY acknowledges the read transaction. The bit is reset if the PHY indicates it does not have link or fails to acknowledge the read transaction. Check to see if the Correct MDIO_ALIVE bits indicate the expected status.

Check the Phy Status

The ICSS EMAC LLD debug guide contains good information on debugging the ICSS EMAC LLD interfaces.