Industrial SDK EMAC Porting Guide

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

Processor SDK RTOS Software Development Guide

If you are migrating from an earlier version of the Industrial Software Development Kit :Porting Guide Industrial SDK to PRU-ICSS-Industrial & Processor SDK will contain information that describes the differences in the software architectures.

This porting guide is a supplement to the material contained in the TI Processor SDK RTOS training material at :Processor SDK Training Series. A description of the Processor SDK RTOS architecture, directory structure, application development and poring to a custom board in sections:

1.2 Introduction to Processor SDK RTOS Part 1 with Texas Instruments

1.3 Introduction to Processor SDK RTOS Part 2 with Texas Instruments

1.4 Application Development Using Processor SDK RTOS with Texas Instruments

As described in section 1.3 and 1.4, the peripheral and SOC specific configuration is performed by the Low Level Drivers (LLDs). The LLDs are built on top of the Chip Support Library (CSL) layer and provide an interface to operate and control the peripherals on the device. The drivers are described in Device driver section in Processor SDK RTOS Software Developer Guide. The CSL contains low level register level definitions and basic functionality to configure cores and registers on the device. For more information see - Processor SDK RTOS CSL. In the case of the AM335x and AM437x, some of the CSL draws from the legacy starterware components.

When migrating an existing design to a custom board. The Board specific information is set in the Board Library. Components that may need to be modified are the Secondary Boot loader, the board diagnostics and the Application. The board library, 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 Board library 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 Processor SDK training material covers the modification of the Processor SDK components in section 1.4 subsection Processor SDK RTOS: Port. The porting section covers

Board Library: Configuration Options

Board Library: Modifying Source for Custom Platform

Processor SDK RTOS: Modifying Board PinMux Settings

Board Library: Clock Tree Tool to Simulate SoC Clocks

DDR Configuration Tools

Diagnostics: Tests to Bring up Custom Hardware & Tests in the Board Package

However there can be cases where not all of the board library information is contained in the Processor SDK board library. In these cases, the industrial protocol can contain some industrial board specific drivers in a separate board library as shown in Figure 3.

Additionally the Industrial Protocol can contain some board specific information

The industrial SDK is built on top of TIRTOS SYSBIOS kernel. The SYS/BIOS kernel 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

Supplemental information for GEL and Bootloader

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 loader supplemental information

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.

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)

PinMux supplemental information

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: https://dev.ti.com/. 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 ../packages/ti/starterware/board/SOCNAME/SOCNAME_BOARDNAME_pinmux_data.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 ../packages/ti/starterware/include/pinmux.h and packages/ti/starterware/board/SOCNAME/SOCNAME_pinmux.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(void); and PINMUXModuleConfig(chipdbModuleID_t moduleId, uint32_t instNum, void* pParam1);

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 pinmux API's set the configuration of the control register. Before the 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 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
..\packages\ti\starterware\bootloader\include

The GEL files are located in
CCS_INSTALL_DIRECORY\ccs_base\emulation\boards\SOC_NAME\gel\SOC_BOARD_NAME.gel

The board clock initialization is performed in ..\packages\ti\board\src\SOC_NAME\SOC_BOARD_NAME.c

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.

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 device interrupts are configured using the Driver APIs contained in:
..\packages\ti\drv\DRIVERTYPE\soc\SOC_NAME ..\packages\ti\board\src\SOC_NAME\SOC_BOARD_NAME__SUBSYSTEM_NAME__config.c or by the application

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

Previous version [http://processors.wiki.ti.com/index.php/Industrial_SDK_EMAC_Porting_Guide1