ENT-UG1060 User Guide Software API Programming Microsemi Corporation (Nasdaq: MSCC) offers a comprehensive portfolio of semiconductor and system solutions for communications, defense & security, aerospace and industrial markets. Products include high-performance and radiation-hardened analog mixed-signal integrated circuits, FPGAs, SoCs and ASICs; power management products; timing and synchronization devices and precise time solutions, setting the world's standard for time; voice processing devices; RF solutions; discrete components; security technologies and scalable anti-tamper products; Ethernet solutions; Power-over-Ethernet ICs and midspans; as well as custom design capabilities and services. Microsemi is headquartered in Aliso Viejo, Calif, and has approximately 3,600 employees globally. Learn more at www.microsemi.com. Microsemi Corporate Headquarters Microsemi makes no warranty, representation, or guarantee regarding the information contained herein or One Enterprise, Aliso Viejo, the suitability of its products and services for any particular purpose, nor does Microsemi assume any CA 92656 USA liability whatsoever arising out of the application or use of any product or circuit. The products sold hereunder and any other products sold by Microsemi have been subject to limited testing and should not Within the USA: +1 (800) 713-4113 be used in conjunction with mission-critical equipment or applications. Any performance specifications are Outside the USA: +1 (949) 380-6100 believed to be reliable but are not verified, and Buyer must conduct and complete all performance and Sales: +1 (949) 380-6136 other testing of the products, alone and together with, or installed in, any end-products. Buyer shall not rely Fax: +1 (949) 215-4996 on any data and performance specifications or parameters provided by Microsemi. It is the Buyer's E-mail: [email protected] responsibility to independently determine suitability of any products and to test and verify the same. The © 2015 Microsemi Corporation. All information provided by Microsemi hereunder is provided “as is, where is” and with all faults, and the entire rights reserved. Microsemi and the risk associated with such information is entirely with the Buyer. Microsemi does not grant, explicitly or Microsemi logo are trademarks of implicitly, to any party any patent rights, licenses, or any other IP rights, whether with regard to such Microsemi Corporation. All other information itself or anything described by such information. Information provided in this document is trademarks and service marks are the proprietary to Microsemi, and Microsemi reserves the right to make any changes to the information in this property of their respective owners. document or to any products and services at any time without notice.
VPPD-03999. 1.1 10/15 Contents
1 Revision History ...... 1 1.1 Revision 1.1 ...... 1 1.2 Revision 1.0 ...... 1 2 Product Overview ...... 2 2.1 API Architecture ...... 2 2.2 Basic API Functions ...... 3 2.3 Advanced API Functions ...... 3 2.4 Key API Specifications ...... 3 2.5 Header File Comments (API Calls and Parameters) ...... 3 3 System Overview and Design ...... 4 3.1 CPU ...... 5 3.1.1 Internal CPU ...... 5 3.1.2 External CPU ...... 6 3.2 Register Access using PCIe ...... 6 3.3 Register Access using Serial Protocols (SPI) ...... 7 3.4 Register Access using Ethernet ...... 7 3.5 Packet Insertion and Extraction ...... 7 3.6 Management Channels ...... 8 3.7 Precision Timing ...... 8 4 API and Device Configuration ...... 9 4.1 System and Device Configurations ...... 9 4.1.1 API Configurations ...... 10 4.2 Targets ...... 10 4.2.1 Build Flow and Configuration Constants ...... 10 4.2.2 API Options ...... 11 4.2.3 Application Options ...... 11 4.2.4 Code Structure ...... 14 4.2.5 Applications using Software Development Kits (SDK) and eCos ...... 14 4.3 Linux Applications ...... 14 4.3.1 Test Application vtss_miniapp ...... 14 4.3.2 Build a Linux Application ...... 14 5 Applications and API Usage Examples ...... 20 5.1 Switch Application Functionality ...... 20 5.1.1 Platforms ...... 20 5.1.2 The vtss_miniapp Switch Application Functionality ...... 20 5.1.3 Setup and Initialization ...... 20 5.2 Switch API Demo eCOS Example ...... 23 5.3 EVC Setup ...... 26 5.4 PHY Application Functionality ...... 30 5.4.1 PHY Application Example ...... 30 5.5 OTN Mapper Application Functionality ...... 31 5.5.1 Port and Channel Numbering ...... 31 5.5.2 Register Access ...... 32
ENT-UG1060 User Guide Revision 1.1 iii 6 API Usage ...... 33 6.1 Directory Structure ...... 33 6.2 Common Data Structures ...... 33 6.2.1 Initialization ...... 33 6.2.2 Instance References ...... 34 7 Guidelines for Applications ...... 35 7.1 High-Level Design Recommendations ...... 35 7.2 Recommended API Calling Sequence ...... 35 7.3 Checklist for API Configuration ...... 35 8 Device Families ...... 36 8.1 1GE PHY ...... 36 8.1.1 PHY Initialization ...... 36 8.1.2 PHY Control after Initialization ...... 36 8.2 10G PHY ...... 37 8.3 Switch Families ...... 37 8.4 OTN Mapper Families ...... 37 9 API Function Groups ...... 39 9.1 Initialization (vtss_init_api.h) ...... 40 9.2 Miscellaneous (vtss_misc_api.h) ...... 41 9.3 Port Control (vtss_port_api.h) ...... 41 9.4 PHY (vtss_phy_api.h) ...... 41 9.5 PHY 10G (vtss_phy_10g_api.h) ...... 41 9.6 Security (vtss_security_api.h) ...... 42 9.7 Layer 2 (vtss_l2_api.h) ...... 42 9.8 Layer 3 (vtss_l3_api.h) ...... 42 9.9 QOS, Quality of Service (vtss_qos_api.h) ...... 42 9.10 HQOS, Hierarchical QoS (vtss_hqos_api.h) ...... 42 9.11 EVC, Ethernet Virtual Connection (vtss_evc_api.h) ...... 42 9.12 FDMA, Frame DMA (vtss_fdma_api.h) ...... 43 9.13 Packet Control (vtss_packet_api.h) ...... 43 9.14 AFI, Automatic Frame Injection (vtss_afi_api.h) ...... 43 9.15 OAM (vtss_oam_api.h) ...... 43 9.16 MPLS (vtss_mpls_api.h) ...... 43 9.17 Synchronization, SyncE (vtss_sync_api.h) ...... 44 9.18 OTN Mapper Layers (vtss_otn_api.h) ...... 44 10 API Call Descriptions ...... 45 11 Operating System Support ...... 47 11.1 OS Layer ...... 47 11.2 API Concurrency Protection ...... 48 11.3 Trace Layer ...... 48 11.4 ECOS OS ...... 48 11.5 Linux OS ...... 48 11.6 External CPU Configuration ...... 48 11.6.1 Internal CPU Configuration ...... 49 12 Porting Steps ...... 50 12.1 Board Support Package ...... 50
ENT-UG1060 User Guide Revision 1.1 iv 12.2 Build System ...... 50 12.3 OS Layer ...... 50 12.4 Register Access ...... 50 12.5 API Protection ...... 50 12.6 Trace Layer ...... 50 12.7 Application ...... 50 13 Testing Applications ...... 51 13.1 Basic Test Flow ...... 51 13.2 Status Information from the vtss_miniapp ...... 51 13.3 Single Switch and PC Test Configuration ...... 52 13.4 Single Switch and Two PC Test Configuration ...... 52 13.4.1 Simple Throughput Performance Test ...... 53 13.4.2 Packet Generation ...... 54 13.4.3 Packet Replay ...... 54 13.4.4 Packet Capture ...... 54 13.4.5 Two Switch Test Configuration ...... 55 14 Frequently Asked Questions ...... 56
ENT-UG1060 User Guide Revision 1.1 v Figures
Figure: 1 Microsemi API Solution ...... 2 Figure: 2 Microsemi API Architecture ...... 3 Figure: 3 Software and Hardware Block Diagram ...... 4 Figure: 4 Internal CPU ...... 6 Figure: 5 External CPU ...... 6 Figure: 6 Injection and Extraction of Packets from CPU ...... 7 Figure: 7 Software Layers and Components ...... 9 Figure: 8 API-Device Configuration ...... 10 Figure: 9 External CPU Configuration ...... 15 Figure: 10 Packets Captured UNI ...... 29 Figure: 11 Packets Captured NNI ...... 30 Figure: 12 Port and Channel Numbering ...... 31 Figure: 13 Instance References ...... 34 Figure: 14 1GE PHY ...... 36 Figure: 15 10G PHY ...... 37 Figure: 16 Switch ...... 37 Figure: 17 OTN Mapper ...... 38 Figure: 18 VSC8489 ...... 38 Figure: 19 API Call Descriptions ...... 45 Figure: 20 Switch and PC Test Configuration ...... 52 Figure: 21 Switch and Two PC Test Configuration ...... 53 Figure: 22 Ethernet Packet Build Options ...... 54 Figure: 23 Two Switch and Two PC Test Configuration ...... 55
ENT-UG1060 User Guide Revision 1.1 vi Tables
Table 1: Performance Characteristics ...... 8 Table 2: Build Options ...... 10 Table 3: API Options ...... 11 Table 4: Application Options ...... 11 Table 5: Supported PHYs ...... 12 Table 6: Supported Switches ...... 12 Table 7: Supported OTN Devices ...... 13 Table 8: Supported Board Configurations ...... 13 Table 9: Code Structure ...... 14 Table 10: cmake Build Parameters ...... 16 Table 11: API Directory Structure ...... 33 Table 12: API Include Files ...... 39 Table 13: Doxygen File Contents ...... 46 Table 14: Defined Entities ...... 47
ENT-UG1060 User Guide Revision 1.1 vii Revision History
1 Revision History
The revision history describes the changes that were implemented in the document. The changes are listed by revision, starting with the most current publication. 1.1 Revision 1.1 The following is a summary of the changes in revision 1.1 of this document. • Reference to the function used to detect, set, and reset the PHY operating mode was updated. For more information, see 10G PHY, page 37. • The list of PHY control functions was updated. For more information, see PHY (vtss_phy_api.h), page 41. 1.2 Revision 1.0 Revision 1.0 was the first publication of this document.
ENT-UG1060 User Guide Revision 1.1 1 Product Overview
2 Product Overview
The Microsemi application programming interface (API) provides a comprehensive, user friendly, and robust function library that supports all Microsemi Ethernet switch, PHY, and optical transport network (OTN) mapper products. The API is portable to any operating system and targeted for 32/64-bit CPUs. The software is written in standard C, it supports multi-instance device targets, and it can be used as a basis for application software solutions such as the following: • Microsemi application software used for production and demonstration • Third party application software provided by a partner company • Customer application software developed by customers using the Microsemi API Figure 1 • Microsemi API Solution
Third-Party Microsemi Custom Application Application Application
Microsemi API
Microsemi Device
2.1 API Architecture The API architecture consists of the following layers that provide a unified interface to Microsemi devices. • Application Interface Layer Provides the functions and structures for a C interface to the application layer. Functions are arranged in initialization and functional groups. • Chip interface layer Includes the device and functional setup code mapped to device-specific registers. • I/O layer Provides register and interrupt access. This layer is platform dependent and is implemented outside the API. • Trace layer Maps code trace macros to provide debug information. • OS layer Encapsulates OS-specific functions used by the API.
ENT-UG1060 User Guide Revision 1.1 2 Product Overview
Figure 2 • Microsemi API Architecture
Initialization Port Control Packet Control Layer 2 Quality of Miscellaneous Security Service
Application Interface Layer
Chip Interface Layer Trace OS Layer Switch PHY Switch Layer
I/O Layer
2.2 Basic API Functions The API provides the following basic functions. • Device initialization port map setup • Port reset and configuration • Port status polling and configuration based on auto-negotiation statistics • Trace system integration • Board-specific register access and port mapping 2.3 Advanced API Functions The API provides the following advanced functions. • Quality of service (QoS) configuration • CPU interface functions for packet control • Port filters and access control lists • Layer 2 configurations • Stacking configurations • MEF EVC setup • Synchronization • 1588v2 time stamping 2.4 Key API Specifications The key specifications for the API are as follows: • Source code in standard C • Portable to any operating system (eCos, Linux) • Portable to 32/64-bit CPUs such as MIPS, PPC, and ARM • Supports all Microsemi Ethernet switches and PHYs 2.5 Header File Comments (API Calls and Parameters) Descriptive text and detailed parameter/call descriptions added as comments in the header files (include/api/*.h) are provided in pdf files along with the source code, and can be found in the doc/
ENT-UG1060 User Guide Revision 1.1 3 System Overview and Design
3 System Overview and Design
This section describes the high-level components of a system with Microsemi devices and the unified API. It also provides guidelines for design choices and parameters. The following illustration shows a block diagram of hardware and software in a switch. The Serval-1 device shown in this example can be replaced by other Microsemi switches. Figure 3 • Software and Hardware Block Diagram
Hardware T SPI BootBBo SD DDR3DDRDDDDRR3 FlashFlFla CCard
SISI Freqq OCXOOOCX PLLLL 202 MHz MH RS23RSS 322 MMDDIOIO RRS422/PPSS422/PPSS422/PPS4222// PS
PCIePCCIe or o SPSPIPII ExternalExxt GPSS CPUC U InputInpuInnpu SerialSeriaSSe GPIGPIOsIOOOss (optional)(optio((o tionalonal) CPUC U Twoo-WireooWirWi Wire SerialSSeriaSe al
UART/ART/ 4×4 SGGMII EthernetEth rnenetttPort Portt 2 ××1 1GG/2.5GGG/2/ 5G 5GS SerDesDeess Two-WireTwT ireree SerialSeSeria 4× 1GGS SeSerDeerDDeDese ShiftS t ReRegisterseg 4× 1G SerDess
AlarmAlaaarrmm RelayReelaelayl s 4×1000BT4×1004×104× 00BT
LEDLEEDDsDs
Software Miscellaneous and control Ethernet packets Management Precision timing Management SNMP JSON-RPC Command Line Graphical User Layer Interface (CLI) Interface (Web) VTSS:Expose
Applications 1588 PTP Port Protection Security Protocols QoS SPOM and Control Plane Protocols SyncE MPLS/MPLS-TP VLAN Translation RSTP (subset) SPROUT
OAM IGMP/MLD Link Aggregation 802.1X Topology Service MVRP Protection PB Bridging MSTP Stacking L3 Static E-Line/E-LAN 802.1Q Bridging ACLs Protocols
Unified API Initialization Port Control Packet Control Layer 2 Quality of Management Security Layer3 Service
Application Interface Layer Application Programming Chip Interface Layer Interface (API) Layer
Switch OTN PHY
I/O Layer
ENT-UG1060 User Guide Revision 1.1 4 System Overview and Design
The hardware block diagram shows a typical network interface device (NID) with the following major components. • Switch •PHY • Timing and PLL device To evaluate device and system behavior and performance, contact your Microsemi representative for a reference and evaluation board. The software block diagram shows the major software modules and functions organized into the following categories. • Interface to upper network management and GUI • Application layer for multiple applications • API layer for access to Microsemi devices Software may include application and network product specific modules as well. Microsemi software interfaces with network management systems using the Web (http/https), SNMP, or JSON-RPC protocol. It is also accessible using CLI. The following software components may be modified as needed, to create the desired applications. • Software Development Kits WebStaX, SMBStaX, IStaX, and CEServices are built on top of the unified API to provide access to a variety of basic and advanced Layer 2 (L2) and Carrier Ethernet functions of Microsemi devices. • Board Support Package (BSP) Available for Linux applications, the BSP operates with the unified API to support Microsemi switches with integrated MIPS 24Kec CPUs. • Unified API A unified package developed in standard C that supports Microsemi Carrier Ethernet switch engines, Enterprise Ethernet switches, PHY, MAC, and OTN Mapper products. The operating-system independent API is an abstraction layer to communicate with Microsemi networking solutions. It provides full access to all hardware functions and the flexibility to add custom code. The unified API supports many network functions that may be implemented in a combination of hardware and software. Because device features have evolved over time, API calls may vary for different generations. Most differences in the device generations are covered by changes in data structures. 3.1 CPU Software processing for device and network functions uses either an internal MIPS 24Kec CPU or an external CPU. The unified API encapsulates the differences to enable operation in both environments. 3.1.1 Internal CPU The internal CPU provides a highly integrated and cost-effective solution. Packet inject and extraction can be implemented using frame DMA (FDMA). The following illustration shows an example of the internal CPU.
ENT-UG1060 User Guide Revision 1.1 5 System Overview and Design
Figure 4 • Internal CPU
SPIIB Booto t SDSD DDR3DDDDR33 FlasFFlaasshsh CaCardr
SI
RS2323323 MDIOMDIMMDIOO RS42RSS44222/PPS22/P22/PP2 PPS SISI PCIePCIIe or SP S I PPSP S Serialial GPIGPIOsIOOss CPU Two-WTwoTwwoo-WWWire e
4×4 SGSGMIIG MDIOMDMMDIIOO PPSPP
3.1.2 External CPU An external CPU has the potential to provide more power, a full tool environment, and a faster development process. In addition, the following advantages may also be available. • Higher CPU performance • Integration with existing software • Register access using PCIe, SPI, and VRAP • Packet injection and extraction using register access to packet buffers at the switch chip and DMA over PCIe (if supported by the external CPU) or NPI on an external network port The following illustration shows an example of an external CPU. Figure 5 • External CPU
SPIIB Booto t SDSD DDR3DDDDR33 FlasFFlaasshsh CaCardr
SI
RS2323323 MDIOMDIMMDIOO RS42RSS44222/PPS22/P22/PP2 PPS SISI PCIePCIIe or SP S I External PPSP S CPU Serialial GPIGPIOsIOOss (optional) Two-WTwoTwwoo-WWWire e SeSe
NNPI EEthernetEtherneEthernEtheher ett Poortr 4×4 SGSGMIIG MDIOMDMMDIIOO PPSPP
3.2 Register Access using PCIe PCIe has higher performance and the CPU supports direct memory mapping of the register space into the application. Interrupts are supported using a Linux file descriptor. If the application needs to receive interrupts, it should have a thread reading the file descriptor. PCIe read register latency is 1-2 s. The PCIe end point in the switch chip does not support spread spectrum clock. (This may limit the use of consumer PC's. "PCIe Spread Spectrum Disable" must be supported by the PC BIOS.)
ENT-UG1060 User Guide Revision 1.1 6 System Overview and Design
3.3 Register Access using Serial Protocols (SPI) SPI has a lower bandwidth (2 Mbps). SPI read register latency is 25-50 s. Interrupt to the external CPU can be implemented using an external pin. 3.4 Register Access using Ethernet An Ethernet packet can be used to read and write registers. The hardware supports multiple read operations in a single Ethernet packet. Interrupt is not supported. If interrupt is needed, the CPU can read the interrupt register and other status registers by sending a VRAP request packet with multiple read commands. VRAP is not directly supported by the API. VRAP is used in the following situations and for the following applications. • Hardware access to given registers such as shaping registers in the switch. For example, an external FPGA sends updates to a specific register in the switch over an Ethernet link. Software needs to set up and configure the FPGA and VRAP access. The benefit is real-time register updates without software overhead. • Debug and monitoring. • Multiple CPU can have access to the same switch chip, but only one API instance (running on the master CPU, for example) can manage the switch chip functions. Another CPU could read registers and update selected register coordinated with the master CPU. 3.5 Packet Insertion and Extraction The software processing system needs access to selected parts of the Ethernet packets to and from the network ports. The CPU can receive and terminate the packet (the packet is forwarded exclusively to the CPU) or the CPU can receive a copy of the network packet (for monitoring of packets link SMON). The switch encapsulates the packet before forwarding the packets to the CPU. An internal frame header (IFH) is added to the received packets. The IFH contains port and flow information. The actual format of the IFH depends on the switch architecture. The following illustration shows the injection and extraction of packets from a CPU. Figure 6 • Injection and Extraction of Packets from CPU
CPU (Internal or External)
Extraction Injection
Switch Functions (Hardware)
Ethernet Ports
The software must parse and process the received packets. The API includes functions for injection and extraction of packets. It also includes functions to add an IFH to the packet to be transmitted. The following methods for implementing frame injection and extraction are available. • Frame DMA (Internal CPU) The DDR3-SDRAM memory attached to a switch is used as a transmit and receive buffer for packets injected into the switch and extracted from the switch. • DMA over PCIe The buffer is in the switch and the external CPU must read/write data to the switch buffer. Most
ENT-UG1060 User Guide Revision 1.1 7 System Overview and Design
CPUs have limited DMA functions and the CPU read/write operation is often the most efficient solution even though packet IO performance is average. • SPI interface. Requires the external CPU to also have a SPI interface. The performance is below average, along with other limiting factors. •Port (NPI) Provides better performance with an external CPU. The NIC must support the internal frame format of the switch (Microsemi switches support different formats), packet encapsulation IFH, and other formats. The following table shows the performance characteristics of the different methods.
Table 1 • Performance Characteristics
Register Access Packet IO CPU Interface Register Access Packet IO Performance Performance Performance External SPI Yes Yes1 Low Low High External PCIe Yes Yes 1 Medium/High Medium High External NPI Yes (VSC7414/16/18 Yes 2 Medium High High and newer switches) Local MIPS CPU Yes FDMA3 High Medium/High Medium (using FDMA)
1. Packet buffer is the switch chip, and data to and from the packet buffer is moved by CPU read and write. 2. Packets are transferred to/from a network port (NPI), and the NPI ports connect to an Ethernet port at an external CPU. The packet performance depends on the external CPU system (typically using DMA). 3. Frame DMA is a DMA system at the Internal MIPS CPU to transfer packets.
The following options show implementation choices based upon design requirements. • High performance: External CPU, NPI for packet Injection and Extraction, and PCIe for register access High integration, cost-effective: Internal MIPS CPU core with registers mapped directly in memory space 3.6 Management Channels The following access options are available to configure and monitor other devices such as PHYs, transceivers, and timing chips. The management channels must be initialized and ports must be configured before using the API functions. • MDIO is used as management channel from the switch to the PHY. • Two wire serial (I2C) is used to manage the SFP/SFP+ modules and other devices. SFP/SFP+ can be managed from the PHY or switch. • SPI (SI) is used for chip configuration (FLASH, PLL, UART, etc.) 3.7 Precision Timing SyncE (Synchronous Ethernet, ITU standard) is used for the frequency synchronization of clock signals over the Ethernet physical layer. Information about clock quality is transmitted in the synchronization status message (SSM) over E1/T1 lines and through the Ethernet synchronization message channel (ESMC) at Ethernet ports. IEEE 1588V2 is used to synchronize clocks and precision time throughout an Ethernet network. VeriTime is the Microsemi implementation of IEEE 1588v2 precision timing. Use VeriTime functions as close to the wire as possible. For example, use VeriTime in the PHY for network ports using the PHY and in the switch for the selection of external PLLs, multiple clocks, and synchronized input. For more information about the API architecture, see API Architecture, page 2.
ENT-UG1060 User Guide Revision 1.1 8 API and Device Configuration
4 API and Device Configuration
This section describes API and device configurations with information on where and how they can be used. It also provides an overview of the configurations for applications using the Microsemi PHY, OTN, and switch devices. 4.1 System and Device Configurations This section describes the supported devices and functions. Figure 7 • Software Layers and Components
Application(s)
Unified API Initialization Port Control Packet Control Layer 2 Quality of Management Security Service Layer3
Application Interface Layer
Chip Interface Layer Application Programming Switch PHY Switch Interface (API) Layer
I/O Layer
The API architecture consists of the following layers that provide a unified interface to Microsemi devices. • Application The application perform the actual operations such as initialization, protocol processing, and management interface. • Application Interface Layer Provides the functions and structures for a C interface to the application layer. The API layer provides access to the hardware functions in the Switch, ONT and PHY chips in a standardized manner. • Chip interface layer Includes the device and functional setup code mapped to device-specific registers. • I/O layer Provides register and interrupt access. This layer is platform dependent and is implemented outside the API.
ENT-UG1060 User Guide Revision 1.1 9 API and Device Configuration
4.1.1 API Configurations The API calls supporting functions remain the same across devices whereas the data structures used may depend on the device. The following configurations are supported. • Internal MIPS CPU, Linux OS • Internal MIPS CPU, eCos OS • Internal MIPS CPU, other OS • External over PCIe, Linux 4.2 Targets The API must be compiled for one or more target devices by defining one or more of the #define directives, so that the following is accomplished. • The external header files include the functions and data types supported by the selected targets. • The application interface layer includes the functions supported by the selected targets. • The chip interface layer is included for the selected targets. The following illustration shows that a number of VTSS_ARCH_* constants are defined in the include/vtss/api/options.h file based on the value of the VTSS_CHIP_*. The user must define the VTSS_CHIP_* #define directive. The normal case is to define one VTSS_CHIP_* #define directive. However it is possible to define multiple and different switch chips (VTSS_CHIP_*), but the user might need to do more testing. For more information, see Multiple Switch Instances, page 34. Figure 8 • API-Device Configuration VTSS_ARCH_*
CHIP_* VTSS_FEATURE_* (VTSS_CHIP_SERVAL, for example) [VTSS_CHIP_10G_PHY] [VTSS_CHIP_CU_PHY]
The switch features show the VTSS_ARCH and FEATURE constants for different values of VTSS_CHIP_*. The symbols VTSS_CHIP_10G_PHY and VTSS_CHIP_CU_PHY get defined when 1G and 10G interfaces are supported by the switch. Double-click the attachment icon to display the switch features in an Excel file. The PHY and OTN features show the VTSS_ARCH and FEATURE constants for different values of VTSS_CHIP_*. Double-click the attachment icon to display the OTN features in an Excel file. 4.2.1 Build Flow and Configuration Constants The following table lists the build options for the build system such as CMake for Linux applications or meta makefile for eCos applications. When building the application one and only one of the following OS constants must be defined VTSS_OPSYS_ECOS, VTSS_OPSYS_LINUX, or VTSS_OS_CUSTOM.
Table 2 • Build Options
Name Default Description NPI_INTERFACE OFF Use a given network port. Use a network interface such as NPI port (run as root). Value is name of NPI network interface such as "eth2". IO_METHOD_UIO ON Use User IO mode for register access. VTSS_OPSYS_ECOS undef Use eCos OS. Get OS definitions from the file include/vtss_os_ecos.h. VTSS_OPSYS_LINUX undef Use Linux OS. Get OS definitions from the file include/vtss_os_linux.h. VTSS_OS_CUSTOM undef Use Custom OS. Get OS definitions from the include/vtss_os_custom.h.
ENT-UG1060 User Guide Revision 1.1 10 API and Device Configuration
4.2.2 API Options The application options control the behavioral of the switch API functions. The constants can be set at defines from the build/ make system. Allowed values are integer. Syntax “VTSS_OPT_*”.
Table 3 • API Options
Name Default Description VTSS_OPT_VCORE_III 1 Use the internal VCore-III MIPS CPU core, else external CPU is used. Enabled by default. VTSS_OPT_PORT_COUNT undef Defines the number of port in the system. Must be set by the user (a parameter to cmake or make, for example). VTSS_OPT_AFI_OPTIMIZE_FOR_TIMERS 1 Default to legacy SWC AFI mode (optimization for frame-slots). Set to 1 from app to optimize for timers. VTSS_OPT_FDMA 0 Use frame DMA. Only an option when using the internal MIPS CPU core. VTSS_OPT_FDMA_DEBUG 0 FDMA debug disabled by default. FDMA only works with the internal MIPS CPU core. VTSS_OPT_FDMA_IRQ_CONTEXT 0 Deferred interrupt context by default. VTSS_OPT_FDMA_VER 2 Version of the FDMA implementation used. VTSS_OPT_INT_AGGR 0 Internal aggregation (disabled by default). VTSS_OPT_TRACE 0 Enable trace with VTSS_E(...), VTSS_I(...), VTSS_D(...), VTSS_N (...) macros. VTSS_OPT_VAUI_EQ_CTRL 6 Can be set by the user, equalization control. Currently not used by API. 4.2.3 Application Options The application options control the application behavior. The constants can be set as defines from the build/make system. Allowed values are defined or not defined. Syntax "VTSS_SW_OPTION_*.
Table 4 • Application Options
Name Description VTSS_SW_OPTION_DEBUG Debug option for PHY board code. VTSS_SW_OPTION_EEE Enables 1G CU PHY Energy Efficient Ethernet. VTSS_SW_OPTION_L3RT Enable Layer 3 routing features in the API implementation. VTSS_SW_OPTION_MEP_LOOP_PORT MEP on Serval1 board. VTSS_SW_OPTION_MIRROR_LOOP_PORT Mirror port on Serval board. VTSS_SW_OPTION_PHY Enables multiple PHY instances. VTSS_SW_OPTION_PHY_POWER_CONTROL Declare PHY power reduction modes VTSS_SW_OPTION_PORT_MUX Enable port muxing is in the switch. VTSS_SW_OPTION_REMOTE_TS_PHY Used with Microsemi OTN.
The VTSS_CHIP_CU_PHY target may be used when compiling the API for a PHY-only application. When compiling the API for switch or OTN mapper targets, the PHY part is always included. For example, if the VTSS_CHIP_E_STAX_34 target is selected, PHYs connected to the MII management
ENT-UG1060 User Guide Revision 1.1 11 API and Device Configuration
controller of the switch can be controlled using the PHY portion of the API. The following table shows the supported PHYs available for targeting.
Table 5 • Supported PHYs
Target (PHY) Description VTSS_CHIP_CU_PHY 1GE PHYs: VSC8211 Single Port 10/100/1000BASE-T PHY and 1000BASE-X PHY with SGMII, SerDes, GMII, MII, TBI, RGMII / RTBI MAC Interfaces VSC8221 Single Port 10/100/1000BASE-T PHY with 1.25 Gbps SerDes/SGMII for SFPs/GBICs VSC8224 Quad Port 10/100/1000BASE-T and 1000BASE-X PHY with RGMII and RTBI MAC VSC8234 Quad Port 10/100/1000BASE-T PHY with SGMII and SerDes MAC VSC8244 Quad Port 10/100/1000BASE-T PHY with RGMII/RTBI MAC VSC8512 12-Port 10/100/1000BASE-T PHY with SGMII and QSGMII MAC VSC8522 12-Port 10/100/1000BASE-T PHY with QSGMII MAC VSC8538 Octal Port 10/100/1000BASE-T PHY with SGMII MAC Interface VSC8558 Octal Port 10/100/1000BASE-T and 1000BASE-X PHY with SGMII MAC VSC8601 10/100/1000BASE-T PHY with RGMII MAC VSC8634 Quad 10/100/1000BASE-T Transceiver VSC8641 10/100/1000BASE-T PHY with RGMII and GMII MAC VSC8664 Quad Port 10/100/1000BASE-T PHY and 100BASE-FX/1000BASE-X SerDes with I2C Mux and Recovered Clock Outputs VSS8574 Quad Port Dual Media QSGMII/SGMII GbE PHY with VeriTime™ VSC8504 Quad-Port 10/100/1000BASE-T PHY with Synchronous Ethernet and QSGMII/SGMII MAC VSC8572 Dual-Port 10/100/1000BASE-T PHY with VeriTime™, Synchronous Ethernet, and RGMII/SGMII MAC VSC8552 Dual Port RGMII/SGMII/QSGMII Dual Media PHY with EEE Support VSC8502 Dual Port GbE Copper PHY with Synchronous Ethernet and RGMII/GMII Interface VTSS_CHIP_10G_PHY VSC8484 4 channel XAUI to XFI VSC8486 XAUI/XGMII to XFI VSC8488 2 channel XAUI to XFI VSC8487-15 Single channel XAUI to XFI with 1588v2 VSC8488-15 Dual channel XAUI to XFI with 1588v2
The following table shows the supported switches available for targeting.
Table 6 • Supported Switches
Target (Switch) Description VTSS_CHIP_CARACAL_1 VSC7428 Caracal 9x1G + 2x2.5G CE switch VTSS_CHIP_CARACAL_2 VSC7429 Caracal 25x1G + 1x2.5G CE switch VTSS_CHIP_CARACAL_LITE VSC7423 Caracal Lite 5x1G + 2x2.5G CE switch VTSS_CHIP_E_STAX_III_24_DUAL Dual VSC7431 48x1G + 2xNPI Layer 2 switch VTSS_CHIP_E_STAX_III_48 VSC7432 E-StaX-III 24x1G + NPI + 2x10G stackable switch VTSS_CHIP_E_STAX_III_68 VSC7434 E-StaX-III 24x1G + NPI + 4x10G stackable switch VTSS_CHIP_E_STAX_III_68_DUAL Dual VSC7434 48x1G + 2xNPI + 4x10G stackable switch VTSS_CHIP_JAGUAR_1 VSC7460 Jaguar-1 24x1G + NPI + 4x10G CE switch VTSS_CHIP_JAGUAR_2 VSC7468 52-Port Carrier Ethernet Switch with ViSAA™, VeriTime™, MPLS/MPLS-TP, and Layer-3 Routing
ENT-UG1060 User Guide Revision 1.1 12 API and Device Configuration
Table 6 • Supported Switches (continued)
Target (Switch) Description VTSS_CHIP_LYNX_1 VSC7462 LynX-1 12x1G + NPI + 4x10G CE switch VTSS_CHIP_LYNX_2 VSC7464 26-Port Carrier Ethernet Switch with ViSAA™, VeriTime™, MPLS/MPLS-TP, and Layer-3 Routing VTSS_CHIP_SERVAL VSC7418 Serval 9x1G + 2x2.5G CE switch VTSS_CHIP_SERVAL_2 VSC7438 Serval 2, 14-Port Carrier Ethernet Switch with ViSAA™, VeriTime™, MPLS-TP, and L3 Routing VTSS_CHIP_SERVAL_LITE VSC7416 Serval-Lite 5x1G + 2x2.5G CE switch VTSS_CHIP_SPARX_III_10 VSC7424 SparX-III 10x1G Layer 2 switch VTSS_CHIP_SPARX_III_10_UM VSC7420 SparX-III 10x1G Layer 2 switch without internal CPU VTSS_CHIP_SPARX_III_11 VSC7414 SparX-III 9x1G + 2x2.5G Layer 2 switch VTSS_CHIP_SPARX_III_17_UM VSC7421 SparX-III 17x1G Layer 2 switch without internal CPU VTSS_CHIP_SPARX_III_18 VSC7425 SparX-III 18x1G Layer 2 switch VTSS_CHIP_SPARX_III_24 VSC7426 SparX-III 24x1G Layer 2 switch VTSS_CHIP_SPARX_III_25_UM VSC7422 SparX-III 25x1G Layer 2 switch without internal CPU VTSS_CHIP_SPARX_III_26 VSC7427 SparX-III 26x1G Layer 2 switch VTSS_CHIP_SPARX_IV_44 VSC7444 26-Port L2/L3 Enterprise Gigabit Ethernet Switch with 10 Gbps Links VTSS_CHIP_SPARX_IV_52 VSC7442 52-Port L2/L3 Enterprise and Industrial Ethernet Switch VTSS_CHIP_SPARX_IV_80 VSC7448 52-Port L2/L3 Enterprise Gigabit Ethernet Switch with 10 Gbps Links
The following table shows the supported OTN devices available for targeting.
Table 7 • Supported OTN Devices
Target (OTN) Description VTSS_CHIP_DAYTONA VSC8492 Daytona 2x10G OTN Mapper. VTSS_CHIP_TALLADEGA VSC8494 Talladega 4x10G OTN Mapper.
The following table shows the board configurations supported by the mini application (min_app).
Table 8 • Supported Board Configurations
Board Name Description Serval1 VTSS_CHIP_SERVAL, Serval reference board with VSC7418 switch chip Jaguar-1 evaluation board VTSS_CHIP_JAGUAR_1, VTSS_OPSYS_LINUX, BOARD_JAGUAR1_REF SparX-III-26 evaluation board VTSS_CHIP_SPARX_III_26, VTSS_OPSYS_LINUX
ENT-UG1060 User Guide Revision 1.1 13 API and Device Configuration
4.2.4 Code Structure The API code is organized in the following directories.
Table 9 • Code Structure
Directory Name Description include/... API header files. include/vtss/api/... API configuration and type header files. appl/... Application examples. The mini_app Linux application. base/... API code. boards/... Board support code for switch, OTN, and PHY boards. doc/... Documentation generated by Doxygen. linux_support/... Linux UIO driver. 4.2.5 Applications using Software Development Kits (SDK) and eCos Software development kits include a number applications that use the switch API and eCos. • WebStaX - Basic Layer 2 Enterprise managed switch software • SMBStaX - Advanced Layer 2 Enterprise managed switch software • IStaX - Industrial Ethernet switch software • CEServices - Carrier Ethernet switch software Contact your Microsemi representative for information about the available applications. 4.3 Linux Applications This section describes how to generate a Linux application using the Serval1 (VSC7414/16/18) reference board. The example uses the mini_app application, which is delivered in source code as part of the switch API. 4.3.1 Test Application vtss_miniapp The vtss_miniapp is a simple test application to test the API, provided as part of the API release in the appl directory. • The application is for test and demonstration of PHY and switch functions. It runs on Linux. It is not intended as a full featured production version. The vtss_miniapp initializes the PHY and switch, sets up the PHY ports, and configures the switch in a Layer2 auto-learning switch. • The vtss_miniapp supports one switch chip instance. • By default, the CPU captures all packets, which limits the performance. Queues to the CPU affect flow control packets to Ethernet ports with flow control enabled. When packets are forwarded to the CPU and the CPU are not able to take off packets fast enough, then the switch transmits pause frames on all ports with flow control enabled. For example, software stops packet processing, packets queue up, and Ethernet flow control stops traffic on ports with flow control enabled. • The CPU uses register access to read packets from the switch, not FDMA. • Reset with external CPU. The actual reset semantics depend on the board used and the switch/PHY chips. In general, when the OS are restarted the switch chip is reset, and when the vtss_miniapp is restarted, the switch chip is not reset. • When the vtss_miniapp and API are restarted, the API does not perform a full zero initialization of the switch chip. As a result, old setup and forward rules can still be active. At the Serval1 board a full reset requires reset of the serval1 board and restart of the PC. Restart of the PC is needed because the PCIe link needs to be reinitialized. 4.3.2 Build a Linux Application The switch API and application can run on either the internal MIPS CPU in a Microsemi switch or an external CPU that is linked using a PCIe or SPI interface. The switch API and example application
ENT-UG1060 User Guide Revision 1.1 14 API and Device Configuration
software are built with cmake and make. cmake for generating the build environment and makefiles for the chosen configuration. 4.3.2.1 External CPU using PCIe The following illustration shows a high-level block diagram of an external Linux CPU configuration with the Serval1 reference board and an x86_64 PC. Figure 9 • External CPU Configuration
Linux PC Switch Chip
Application (Software)
API
PCIe OS Interface H/W Acces, UIO Extender PCIe Cable Switch Functions (H/W) Card
Linux OS
Ethernet Ports
4.3.2.1.1 Hardware Used • Serval1 reference board • PCIe cable (http://www.digikey.com/product- search/en?x=19&y=14&lang=en&site=us&keywords=WM1144-ND) • AJA IOCARD-X1 1-Lane PCIe Card to PCIe Cable Interface Adapter (http://www.stjernholm-media- proshop.dk/product.asp?product=7221) •Linux PC 4.3.2.1.2 Procedure 1. Attach a Serval1 device using PCIe. SW3 jumper setting to 9 (1001 - IROM boot, PCIe endpoint). 2. Power-up Serval1 board. 3. Power-up the PC. Disable PCIe spread spectrum BIOS option. The PCIe end point in the Microsemi device does not support PCIe spread spectrum. PCIe link failure will occur with PCIe spread spectrum enabled. 4. Extract API files. tar xf API_4_64m.tar.gz cd API_4_64m 5. Make a build directory and compile the Linux UIO driver. mkdir build cd vtss_api/linux_support/misc/ make clean make -C /usr/src/linux-headers-`uname -r` ARCH=x86_64 M=`pwd` mkdir -p /opt/vtss sudo cp uio_serval1.ko /opt/vtss/uio_serval1.ko 6. Check the PCIe connection to the switch. # Query PCI connection to Vitesse switch lspci -nn | grep -i vitesse
# Desired output 05:00.0 Network controller [0280]: Vitesse Semiconductor Device [101b:b002] The initial “05:00.0” depends on the development system and the PCIe slot used. Actual values may vary.
ENT-UG1060 User Guide Revision 1.1 15 API and Device Configuration
7. Load the UIO driver. sudo insmod /lib/modules/`uname -r`/kernel/drivers/uio/uio.ko sudo insmod /opt/vtss/uio_serval1.ko sudo chmod 666 /dev/uio0 sudo chmod 222 /sys/class/uio/uio0/device/softreset The presence of the “softreset” device node depends on the UIO driver. Currently, only Serval1 has/needs this. 8. Check that the UIO kernel mode is loaded. # Display modes lsmod | grep uio
# Desired output uio_serval1 13044 0 uio 19360 1 uio_serval1 9. Generate the configuration with cmake and make the application. cd ../../.. cd build/ cmake -DVTSS_PHY_API_ONLY=OFF -DVTSS_FEATURE_MACSEC=OFF -DVTSS_OPT_FDMA=OFF - DVTSS_APPL_MINI=ON -DVTSS_PRODUCT_CHIP=SERVAL -DVTSS_OPT_PORT_COUNT=12 - DVTSS_PRODUCT_HW=BOARD_SERVAL_REF -DVTSS_CHIP_10G_PHY=OFF ../vtss_api/ make 10. Run the application. ./appl/vtss_miniapp The following table shows the cmake build parameters used.
Table 10 • cmake Build Parameters
Parameter Description -DVTSS_PHY_API_ONLY=OFF Switch API included -DVTSS_CHIP_10G_PHY=OFF No 10G PHYs are used by Serval1 -DVTSS_FEATURE_MACSEC=OFF Not using MACSec -DVTSS_OPT_FDMA=OFF Not using frame DMA -DVTSS_APPL_MINI=ON Make the mini_appl application -DVTSS_PRODUCT_CHIP=SERVAL Select the Serval switch -DVTSS_OPT_PORT_COUNT=12 Declare the port count -DVTSS_PRODUCT_HW=BOARD_SERVAL_REF Select the Serval-1 reference board as target ../vtss_api/ Point to the root of the Switch API files
Add the following commands to the rc.local file to load the UIO driver when the Linux machine is started. #add the following 5 lines to /etc/rc.local: insmod /lib/modules/`uname -r`/kernel/drivers/uio/uio.ko insmod /opt/vtss/uio_serval1.ko chmod 666 /dev/uio0 chmod 222 /sys/class/uio/uio0/device/softreset echo 1 > /sys/class/uio/uio0/device/softreset Use the following commands to update the driver when the Linux kernel is updated. #Remember to update uio_serval1.ko whenever your Linux kernel is upgraded. Follow the steps below: #[Under project root directory] cd vtss_api/linux_support/misc make clean make -C /usr/src/linux-headers-`uname -r` ARCH=x86_64 M=`pwd`
ENT-UG1060 User Guide Revision 1.1 16 API and Device Configuration
sudo cp uio_serval1.ko /opt/vtss/uio_serval1.ko 4.3.2.1.3 Internal MIPS CPU and Linux BSP Use the following commands to build the application for the internal CPU. The following example shows the steps to generate a Linux system (kernel and root file system) for the internal CPU. For more information, see the application note “AN1125 Software Linux BSP Yocto.” Examples of tools needed on a Ubuntu 14.04 LTS installation: sudo apt-get update sudo apt-get install g++ git texinfo gawk chrpath How to build a Linux system with the vtss_miniapp. cd ~ git clone -b dylan git://git.yoctoproject.org/poky.git
cd poky/ git clone https://github.com/vtss/meta-vtss-vcoreiii.git
cd meta-vtss-vcoreiii/ git tag -l git checkout vtss_1.20 cd ..
git clone https://github.com/vtss/meta-vtss-switch.git cd meta-vtss-switch/ git tag -l git checkout vtss_api_4.64m
cd recipes-applications/vtss-api/files/ cp ..../API_4_64m.tar.gz . cd ~/poky/ source oe-init-build-env build_serval1 # note the above change the current directory to ~/poky/build_serval1
gedit conf/local.conf gedit conf/bblayers.conf Changes conf/local.conf: Uncomment the lines by removing the # charactor BB_NUMBER_THREADS = "4" PARALLEL_MAKE = "-j 4" DL_DIR ?= "${TOPDIR}/downloads" SSTATE_DIR ?= "${TOPDIR}/sstate-cache" Add the line MACHINE ?= "serval1" Diffs for the local.conf file where local.conf.save is the original file: diff local.conf local.conf.save 20c20 < BB_NUMBER_THREADS = "4" --- > #BB_NUMBER_THREADS = "4" 25c25 < PARALLEL_MAKE = "-j 4" ---
ENT-UG1060 User Guide Revision 1.1 17 API and Device Configuration
> #PARALLEL_MAKE = "-j 4" 36d35 < MACHINE ?= "serval1" 65c64 < DL_DIR ?= "${TOPDIR}/downloads" --- > #DL_DIR ?= "${TOPDIR}/downloads" 81c80 < SSTATE_DIR ?= "${TOPDIR}/sstate-cache" --- > #SSTATE_DIR ?= "${TOPDIR}/sstate-cache" Changes conf/bblayers.conf: Add the following lines after /home/vtss/poky/meta-yocto-bsp \ line, where /home/vtss should be replaced with the home directory name: /home/vtss/poky/meta-vtss-switch \ /home/vtss/poky/meta-vtss-vcoreiii \ The output files are placed in the tmp/deploy/images directory 4.3.2.2 Steps to Start Linux and the vtss_miniapp Use the following steps to start Linux and the miniapp. 1. Attach a Serval1 device using PCIe. SW3 jumper setting to hex value d (1101 - MIPS boot from SI interface, The MIPS is Little Engine). 2. Attach an RS232 cable for console (115200 baud 8bit no parity) 3. Power-up Serval1 board or reset the board 4. Press Ctrl-C (^C) during the boot process to the Redboot prompt 5. Press Ctrl-C (^C) when the following console boot test appears. Platform: VCore-III (MIPS32 24KEc) SERVAL RAM: 0x80000000-0x88000000 [0x800225f8-0x87fdfffc available] FLASH: 0x40000000-0x40ffffff, 256 x 0x10000 blocks == Executing boot script in 3.000 seconds - enter ^C to abort ^C Use the following code to configure the IP address (manual, in this example the IPv4 address is 10.20.10.1). # configure terminal (config)# inter vlan 1 (config-if-vlan)# ip addr 10.20.10.1 255.255.255.0 (config-if-vlan)# exit (config)# exit # ping ip 10.20.10.10 PING server 10.20.10.10, 56 bytes of data. 64 bytes from 10.20.10.10: icmp_seq=0, time=0ms 64 bytes from 10.20.10.10: icmp_seq=1, time=0ms 64 bytes from 10.20.10.10: icmp_seq=2, time=0ms 64 bytes from 10.20.10.10: icmp_seq=3, time=0ms 64 bytes from 10.20.10.10: icmp_seq=4, time=0ms Sent 5 packets, received 5 OK, 0 bad # {show ip interface brief} Interface Address Method Status ------VLAN 1 10.20.10.1/24 Manual UP Use the following code to program the images to the flash. # debug firmware load linux tftp://10.20.10.2/vmlinux-3.14.serval1.gz # debug firmware load root tftp://10.20.10.2/core-image-minimal- serval1.squashfs-xz # reload cold
ENT-UG1060 User Guide Revision 1.1 18 API and Device Configuration
ENT-UG1060 User Guide Revision 1.1 19 Applications and API Usage Examples
5 Applications and API Usage Examples
This section uses examples to describe API usage. The examples can be included and executed in the mini_app. The source code for the examples is included with the API code. 5.1 Switch Application Functionality 5.1.1 Platforms The vtss_api/appl directory includes the vtss_miniapp Linux application example demonstrating how to use the API. The applications can be built to run all Microsemi switch platforms supporting Linux. For information about the available platforms, see API and Device Configuration, page 9. The application can be built using the Linux cmake tool, or by compiling the define files. 5.1.2 The vtss_miniapp Switch Application Functionality The switch portion of the application file, appl/vtss_appl.c, demonstrates the following basic functionality. • Trace system integration • Initialization • Port map setup • Port reset and configuration • Port status polling and configuration based on auto-negotiation The board specific portion of the application file, appl/vtss_appl_board_*.c, includes the following functionality. • Register access •Port map The application includes a command line interface (CLI) found in appl/vtss_appl_cli.c for configuration and monitoring of the system. The CLI include also functions to show state, chip registers, mac tables, and port counters. 5.1.3 Setup and Initialization The following code examples are for the Serval1 reference board. Pre-compiler IFDEFS are selected for the Serval1 board and all other unused IFDEFS have been removed to make the code more readable. The complete code is available with the API release in the file appl/vtss_appl.c Main program from the file appl/vtss_appl.c, Init code from vtss_miniapp with explanation. /* Board specifics */ static vtss_appl_board_t board_table[VTSS_APPL_INST_CNT]; [...]
main(int argc, char **argv) { vtss_appl_board_t *board; vtss_appl_inst_t inst; int count = 0; vtss_inst_create_t create; vtss_init_conf_t init_conf; vtss_port_no_t port_no; vtss_appl_port_conf_t *pc; vtss_appl_port_status_t *ps; vtss_phy_reset_conf_t phy_reset; vtss_port_status_t status; BOOL link_old;
ENT-UG1060 User Guide Revision 1.1 20 Applications and API Usage Examples
BOOL port_poll[VTSS_APPL_INST_CNT][VTSS_PORT_ARRAY_SIZE]; BOOL init_done = 0; vtss_port_counters_t counters;
if (parse_options(argc, argv, &count)) return 1; T_D("Enter"); /* Initialize board table */ board = &board_table[0]; vtss_board_generic_init(board, (argc - count), (const char **)(argv + count)); /* Initialize boards */ for (inst = 0; inst < VTSS_APPL_INST_CNT; inst++) { T_D("------init inst 0 ------"); board = &board_table[inst]; vtss_inst_get(board->target, &create); vtss_inst_create(&create, &board->inst);
vtss_init_conf_get(board->inst, &init_conf); board->init.init_conf = &init_conf; if (board->board_init(argc - count, (const char **)(argv + count), board)) return 1; if (vtss_init_conf_set(board->inst, &init_conf) == VTSS_RC_ERROR) { T_E("Could not initialize"); return 1; };
if (board->board_probe) { board->board_probe(board); } if (board->feature.port_control) { vtss_port_map_set(board->inst, board->port_map); } for (port_no = VTSS_PORT_NO_START; port_no < VTSS_PORT_NO_END; port_no++) { /* Default port status */ board->port_status[port_no].link = 0; /* Default port configuration */ pc = &board->port_conf[port_no]; memset(pc, 0, sizeof(*pc)); switch (board->port_interface(port_no)) { case VTSS_PORT_INTERFACE_100FX: pc->speed = VTSS_SPEED_100M; break; case VTSS_PORT_INTERFACE_XAUI: case VTSS_PORT_INTERFACE_SFI: pc->speed = VTSS_SPEED_10G; break; case VTSS_PORT_INTERFACE_VAUI: pc->speed = VTSS_SPEED_5G; break; case VTSS_PORT_INTERFACE_SGMII: case VTSS_PORT_INTERFACE_QSGMII: pc->speed = VTSS_SPEED_1G; pc->autoneg = 1; pc->flow_control = 1; break; case VTSS_PORT_INTERFACE_SERDES:
ENT-UG1060 User Guide Revision 1.1 21 Applications and API Usage Examples
pc->speed = VTSS_SPEED_1G; break; default: T_E("unknown if_type on port %u", port_no); } pc->enable = 1; pc->fdx = 1; port_poll[inst][port_no] = (board->port_poll == NULL || board->port_poll(port_no) ? 1 : 0); pc->max_length = VTSS_MAX_FRAME_LENGTH_STANDARD; if (board->port_map != NULL && board->port_map[port_no].chip_port < 0) { port_poll[inst][port_no] = 0; } }
if (board->board_init_post) board->board_init_post(board); /* Packet RX */ setup_rx_reg(); if (board->pre_reset) board->pre_reset(); // Mainly PHY pre-reset for (port_no = VTSS_PORT_NO_START; port_no < VTSS_PORT_NO_END; port_no++) { if (port_poll[inst][port_no] == 0) continue;
if (board_port_phy(board, port_no)) { phy_reset.mac_if = board->port_interface(port_no); phy_reset.media_if = VTSS_PHY_MEDIA_IF_CU; vtss_phy_reset(board->inst, port_no, &phy_reset); } port_setup(board, port_no, 0); } if (board->post_reset) board->post_reset(); // Mainly PHY post reset if (board->board_init_done) board->board_init_done(board); } /* Instance loop */ Initialize the CLI. if (!quiet) { vtss_appl_cli_init(); } Main loop serving the switch chip and ports. for (;;) { inst++; if (inst >= VTSS_APPL_INST_CNT) inst = 0; board = &board_table[inst]; for (port_no = VTSS_PORT_NO_START; port_no < VTSS_PORT_NO_END; port_no++) { if (!port_poll[inst][port_no]) continue; if (board->feature.port_control) { if (vtss_port_status_get(board->inst, port_no, &status) != VTSS_RC_OK) continue; } else {
ENT-UG1060 User Guide Revision 1.1 22 Applications and API Usage Examples
if (vtss_phy_status_get(board->inst, port_no, &status) != VTSS_RC_OK) continue; } ps = &board->port_status[port_no]; link_old = ps->link; ps->link = status.link; ps->speed = status.speed; ps->fdx = status.fdx; ps->aneg.obey_pause = status.aneg.obey_pause; ps->aneg.generate_pause = status.aneg.generate_pause; /* Detect link down and disable port */ if ((!status.link || status.link_down) && link_old) { T_D("link down event on port_no: %u", port_no); link_old = 0; if (board->feature.layer2) { vtss_port_state_set(board->inst, port_no, 0); vtss_mac_table_port_flush(board->inst, port_no); } /* Dummy counters, just want to turn off led */ memset(&counters, 0, sizeof(vtss_port_counters_t)); /* Update led, to turn off it */ port_custom_led_update(port_no, &board->port_status, &counters, &board->port_conf); }
/* Detect link up and setup port */ if (status.link && !link_old) { T_D("link up event on port_no: %u", port_no); if (board->feature.layer2) vtss_port_state_set(board->inst, port_no, 1); if (board->port_conf[port_no].autoneg) port_setup(board, port_no, 1); } if (!quiet) { vtss_appl_cli_task(); } } /* Port loop */ if (!quiet) { vtss_appl_cli_task(); } if (!init_done) { init_done = 1; /* Configuration done */ vtss_restart_conf_end(board->inst); } if (board->board_periodic) board->board_periodic(board); } /* for (;;) loop */ 5.2 Switch API Demo eCOS Example The following example forwards a packet from a network port to the CPU. • Method 1 use packet_rx_conf • Method 2 use the MAC table to forward packets • Method 3 use ACL // --- In order for packets with MAC 01:80:C2:00:00:2F (see dmac in demo_packet.c) // to be forwarded to the CPU, some bits in the chip ANA:PORT:CPU_FWD_GARP_CFG
ENT-UG1060 User Guide Revision 1.1 23 Applications and API Usage Examples
// must be set. // void debug_forwarding_control(BOOL enable, int method) { vtss_rc rc; T_DG(TRACE_GRP_FORWARD, "demo_forwarding_control enable=%d", (int)enable); // --- Take the API lock vtss_appl_api_lock(); switch (method) { case 1: rc = forward_frame_to_cpu_method1(enable); T_DG(TRACE_GRP_FORWARD, "forward_frame_to_cpu_method1() (%s)", error_txt(rc)); break; case 2: rc = forward_frame_to_cpu_method2(enable); T_DG(TRACE_GRP_FORWARD, "forward_frame_to_cpu_method2() (%s)", error_txt(rc)); break; case 3: rc = forward_frame_to_cpu_method3(enable); T_DG(TRACE_GRP_FORWARD, "forward_frame_to_cpu_method3() (%s)", error_txt(rc)); break; default: T_WG(TRACE_GRP_FORWARD, "debug_forwarding_control() option %d not defined", method); } // --- and release the API lock again. vtss_appl_api_unlock(); } // --- In order for packets with MAC 01:80:C2:00:00:2F (see dmac in demo_packet.c) // to be forwarded to the CPU, some bits in the chip ANA:PORT:CPU_FWD_GARP_CFG // must be set. // static vtss_rc forward_frame_to_cpu_method1(BOOL enable) { vtss_rc rc; vtss_packet_rx_conf_t conf; bzero(&conf, sizeof(conf)); // (1) --- Read the configuration rc = vtss_packet_rx_conf_get(NULL, &conf); if (rc != VTSS_OK) { T_EG(TRACE_GRP_FORWARD, "Failed to get packet_rx_conf (%s)", error_txt(rc)); return VTSS_RC_ERROR; } // (2) --- Change configuration and write it back // 0x2f is the last byte of dmac in demo_packet.c conf.reg.garp_cpu_only[0x2f & 0xf] = enable; rc = vtss_packet_rx_conf_set(NULL, &conf); if (rc != VTSS_OK) { T_EG(TRACE_GRP_FORWARD, "Failed to set packet_rx_conf (%s)", error_txt(rc)); } return rc; }
ENT-UG1060 User Guide Revision 1.1 24 Applications and API Usage Examples
static const u8 dmac[6] = {0x00, 0x01, 0xc1, 0x11, 0x22, 0x33}; static const vtss_vid_t vid = 1; // --- Here we register specific on destination MAC 00:01:C1:11:22:33 (see dmac in demo_packet.c) // to be forwarded to the CPU, some bits in the chip ANA:PORT:CPU_FWD_GARP_CFG // must be set. // static vtss_rc forward_frame_to_cpu_method2(BOOL enable) { vtss_rc rc; int i; vtss_mac_table_entry_t entry; // (1) --- Clear everything in entry. Set the // destination MAC address and VID. bzero(&entry, sizeof(entry)); entry.vid_mac.vid = vid; for (i=0; i<6; ++i) { entry.vid_mac.mac.addr[i] = dmac[i]; } // --- Frames shall go to the CPU, and // the entry shall be static. entry.copy_to_cpu = TRUE; entry.locked = TRUE; // (2) --- Add or delete entry from MAC table. if (enable) { rc = vtss_mac_table_add(NULL, &entry); } else { rc = vtss_mac_table_del(NULL, &entry.vid_mac); } if (rc != VTSS_OK) { T_EG(TRACE_GRP_FORWARD, "vtss_mac_table_add() failed (%s)", error_txt(rc)); } return rc; } #if 1 static vtss_rc forward_frame_to_cpu_method3(BOOL enable) { vtss_rc rc = VTSS_RC_OK; vtss_ace_type_t type; vtss_ace_t ace; // Lets make an ethernet match, and initialyze 'ace'. type = VTSS_ACE_TYPE_ETYPE; rc = vtss_ace_init(NULL, type, &ace); if (rc) return rc; #if 0 // Set relevant fields. ace.frame.etype.dmac = ace.frame.etype.smac = ace.frame.etype.etype = ace.frame.etype.data = // and make it effective rc = vtss_ace_add(NULL, id, &ace); #endif return rc; } #else static vtss_rc forward_frame_to_cpu_method3(BOOL enable)
ENT-UG1060 User Guide Revision 1.1 25 Applications and API Usage Examples
{ vtss_rc rc = VTSS_RC_OK; acl_entry_conf_t conf; // (1) --- IPv4 entry if (acl_mgmt_ace_init(VTSS_ACE_TYPE_IPV4, &conf) != VTSS_OK) { return rc; } conf.id = 1;//DHCP_HELPER_BOOTPS_ACE_ID; // (2) --- Port for which this apply #if defined(VTSS_FEATURE_ACL_V2) conf.action.port_action = VTSS_ACL_PORT_ACTION_FILTER; memset(conf.action.port_list, 0, sizeof(conf.action.port_list)); #else conf.action.permit = FALSE; #endif /* VTSS_FEATURE_ACL_V2 */ conf.action.force_cpu = TRUE; conf.action.cpu_once = FALSE; conf.isid = VTSS_ISID_LOCAL; // (3) --- march 192.168.x.x conf.frame.ipv4.dip.value=0xC0A80000; conf.frame.ipv4.dip.mask =0xFFFF0000; if (acl_mgmt_ace_add(ACL_USER_NAT, ACL_MGMT_ACE_ID_NONE, &conf) != VTSS_OK) { // T_D("Add DHCP helper reserved ACE (BOOTPS) fail.\n"); } return rc; } #endif 5.3 EVC Setup The following example sets up an EVC with hard-coded values. The evc_main function in the following code shows an overview of the setup steps. • Create the EVC • Configure UNI port to generate appropriate key • Insert a packet classification rule in the IS1 table • Add the UNI and NNI port to a VLAN static vtss_rc evc_main() { vtss_rc rc; printf("Create EVC object\n"); rc = create_evc(); if (rc!=VTSS_RC_OK) return rc; printf("Configure UNI port to generate appropriate key\n"); rc = config_port_key(); if (rc!=VTSS_RC_OK) return rc; printf("Insert rule in IS1 for assigning packets to EVC\n"); rc = create_ece(); if (rc!=VTSS_RC_OK) return rc; printf("Create VLAN\n"); rc = create_vlan(); return rc; } The following code shows the create_evc function to create an EVC. • (1.1) The evc_conf must be set up. Start by making sure that the config structure is clean. • (1.2) The EVC may be associated with a policer. Some special values are defined in vtss_evc_api.h. Valid values are: 0,...,VTSS_EVC_POLICERS-1,
ENT-UG1060 User Guide Revision 1.1 26 Applications and API Usage Examples
VTSS_EVC_POLICER_ID_DISCARD, VTSS_EVC_POLICER_ID_NONE. In this example no policer is associated with the EVC. • (1.3) No learning. • (1.4) Select which port should be NNI port for this EVC. In this example nni_port is the only NNI port. • (1.5) Select the S-VID for this EVC. • (1.6) The IVID is the VID the switch chip uses internally to differentiate traffic for this EVC from other traffic. Most often the VID and IVID is set to the same number, but that is not a requirement. • (1.7) Finally add this to the API. const vtss_evc_id_t evc_id = 1; const vtss_ece_id_t ece_id = 0; const int uni_port = 2-1; const int nni_port = 3-1; const int vlan_no = 1234;
static vtss_rc create_evc() { vtss_rc rc; vtss_inst_t inst = NULL; vtss_evc_conf_t evc_conf; bzero(&evc_conf, sizeof(evc_conf)); // (1.1) evc_conf.policer_id = VTSS_EVC_POLICER_ID_NONE; // (1.2) evc_conf.learning = FALSE; // (1.3) if ( !(nni_port ENT-UG1060 User Guide Revision 1.1 27 Applications and API Usage Examples port_conf.key_type = VTSS_VCAP_KEY_TYPE_NORMAL; // (2.2) port_conf.dmac_dip = FALSE; rc = vtss_evc_port_conf_set(inst, port_no, &port_conf); // (2.3) return rc; } The following code shows the create_ece function. • (3) Create an ECE/UNI. • (3.1) In this example the key.type is set to VTSS_ECE_TYPE_IPV4 to filter on IPv4 frames. This means that key.frame.ipv4 must also be set up correctly. Different switch chips support different key.typ values. If key.type = VTSS_ECE_TYPE_XX, then key.frame.xx must also be set. The only exception is if key.type = VTSS_ECE_TYPE_ANY. • (3.2) Create an ECE with vtss_ece_init(). • (3.3) The key determines which frames are subject to this ECE. • (3.4) The key.port_list specify which port ingress frames should come from. In this example uni_port is the only ingress port. Any number of ports can be specified. • (3.5) Lets say we dont care about any field in the IPv4 packet except for the source IP address, where we want addresses 10.11.X.X • (3.5a) In Serval1, three lookups can be performed in the IS1; the first two are used for ECE. • (3.6) So now the keys specify that ingress packets on port uni_port that are IPv4 frames with source IP address 10.11.X.X is subject to this rule. Keep in mind that the ingress port has to be configured to generate a key that conforms with this key. • Configure the action for frames that have the property above. When an ECE is configured, the focus is on the UNI->NNI direction or the ingress rules on the UNI. Eventually, a bidirectional connection is desirable: frames that ingress on the NNI(s) of the EVC also need to egress the UNI. It is not possible to ensure that frames with S-VID=1234 that ingress on port nni_port should egress on port uni_port if it is an IPv4 frame with destination IP address 10.11.X.X. Use the API to automatically generate the appropriate rule in the NNI->UNI direction: • (3.7) This is a UNI->NNI (Rx) direction specification that can be extended to take care of the UNI- >NNI (Tx) direction. Both rules or either one of them can be set up with action.rule: VTSS_ECE_RULE_BOTH, VTSS_ECE_RULE_RX, or VTSS_ECE_RULE_TX. The example sets up both rules. • (3.8) Finally, set action.dir VTSS_ECE_DIR_UNI_TO_NNI or VTSS_ECE_DIR_NNI_TO_UNI. In the first case, the key is specified with the UNI in mind and the UNI->NNI rule will be configured. It does not matter if action.rule is VTSS_ECE_RULE_RX or VTSS_ECE_RULE_BOTH. But if action.rule is VTSS_ECE_RULE_TX, then no rule will be configured because there is no reverse direction in the unidirectional set. • (3.9) add vtss_ece_add() static vtss_rc create_ece() { vtss_rc rc; vtss_inst_t inst = NULL; vtss_ece_type_t ece_type = VTSS_ECE_TYPE_IPV4; // (3.1) vtss_ece_t ece_conf; rc = vtss_ece_init(inst, ece_type, &ece_conf); // (3.2) if (rc) return rc; ece_conf.id=10; // (3.3) if ( !(uni_port ece_conf.key.frame.ipv4.sip.value = 0x0a0b0000; // (3.5) ece_conf.key.frame.ipv4.sip.mask = 0xffff0000; ece_conf.key.lookup = 0; // (3.6) ece_conf.action.dir = VTSS_ECE_DIR_BOTH; // (3.7) ece_conf.action.rule = VTSS_ECE_RULE_BOTH; // (3.8) ece_conf.action.evc_id = evc_id; ENT-UG1060 User Guide Revision 1.1 28 Applications and API Usage Examples ece_conf.action.policer_id = VTSS_EVC_POLICER_ID_NONE; rc = vtss_ece_add(inst, ece_id, &ece_conf); // (3.9) return rc; } Adding VLAN • (4.1) Get the member list for VLAN vlan_no (in this example 1234) • (4.2) Add the UNI and NNI port as members to this VLAN • (4.3) Set the VLAN member list static vtss_rc create_vlan() { vtss_rc rc; BOOL member[VTSS_PORT_ARRAY_SIZE]; vtss_inst_t inst = NULL; rc = vtss_vlan_port_members_get(inst, vlan_no, member); // (4.1) if (rc!=VTSS_RC_OK) return rc; member[nni_port]=member[uni_port]=TRUE; // (4.2) rc = vtss_vlan_port_members_set(inst, vlan_no, member); // (4.3) return rc; } For information about testing the EVC setup, see Testing Applications, page 51. In this simple test example, the packets are generated with ostinato and captured with wireshark. The following illustration shows captured packets at the UNI interface. Note that the packets have no tag. Figure 10 • Packets Captured UNI The following illustration shows captured packets at the NNI interface. Note that the packets have a C-tag with TPID=0x8100 and VID=1234 (0x04d2). ENT-UG1060 User Guide Revision 1.1 29 Applications and API Usage Examples Figure 11 • Packets Captured NNI If the vtss_miniapp Linux application is used for test, add in the file appl/tvss_appl.c: static vtss_rc my_debug_test(u32 value){ printf("%s, value: %d\n", __FUNCTION__, value); return evc_main(); } Add in main() (after the board pointer is initialized) in the file appl/tvss_appl.c: board->debug_test = my_debug_test; The function can be called from the vtss_miniapp promt by typing: debug test [ ENT-UG1060 User Guide Revision 1.1 30 Applications and API Usage Examples The Atom12 evaluation board uses an add-on Rabbit CPU board to communicate with the PC and the PHY. An IP address is required for the socket-based communication between the rabbit board and the PC. The IP address is set as an argument when running the API program. Example : vtss_api.exe 10.10.132.59 5.5 OTN Mapper Application Functionality The mapper application portion of the file, appl/vtss_appl.c, demonstrates the following basic functionality. • Trace system integration • Initialization • Port map setup • Port reset and configuration The board specific portion of the file appl/vtss_appl_board_*.c, includes the following functionality. • Register access. • Access to external components on the EVAL board through the MDIO interface (VSC8486 PHY), and I2C (SFP+). • Access to other external components on the EVAL board through the rabbit module. The backplane AE (IEEE 802.3 clause 72) file, appl/ae/*.c, includes a process for controlling the AE using the API interface primitives for AE. The application includes a CLI from the file appl/vtss_appl_cli.c for configuration and monitoring the system. CLI commands are implemented for all the API functions, so all API functions can be exercised from external scripts. 5.5.1 Port and Channel Numbering Daytona (VSC8492) has two channels that connect a client side port with a line side port. Each channel is nearly symmetrical as the same features are available towards both client and line side, centered about the rate adaptation buffer (RAB). The API treats Daytona as 4 ports numbered 0 through 3, as shown in the following illustration. Figure 12 • Port and Channel Numbering Inst 0 Inst 0 RAB Port 0 Port 2 Channel 0 Inst 0 Inst 0 RAB Port 1 Port 3 Channel 1 Inst 1 Inst 1 Port 0 RAB Port 2 RAB Port 0 Port 2 Channel 0 Channel 2 Inst 1 Inst 1 Port 1 RAB Port 3 RAB Port 1 Port 3 Channel 1 Channel 3 VSC8492 VSC8494 The API calls are converted to one or more register reads or writes implemented as callouts from the API. The following code shows an example read callout function declaration. ENT-UG1060 User Guide Revision 1.1 31 Applications and API Usage Examples /** * \brief Read value from target register. * * \param chip_no [IN] Chip number (if multi-chip instance). * \param addr [IN] Address to read. Byte offset from chip address base. * \param value [OUT] Register value. * \return Return code. **/ static vtss_rc reg_read(const vtss_chip_no_t chip_no, const u32 addr, u32 *const value); chip_no is not used (always 0) and addr is the register offset within the chip. Talladega (VSC8494) is treated as two Daytona devices. Two API instances are created and separate callouts are defined per instance with one callout for channel 0 and 1 and another callout for channel 2 and 3. The port_number from the API call is reflected in the addr parameter. Stated another way, the API converts the port_number and function block to the proper register address. 5.5.2 Register Access The mapper test application is made for both the Daytona evaluation board and the Talladega evaluation board. The Talladega application creates two instances of the API, one for channel 0 and 1 (die 0) and another for channel 2 and 3 (die 1). In the reg_read and reg_write callout functions, the functions handling die 0 uses the addr parameter directly. The callout functions handling die 1 sets bit 22 in the addr parameter and uses the same register access function. The following code shows an example read callout function implementation for die 1. static vtss_rc reg_read_die_1(const vtss_chip_no_t chip_no, const u32 addr, u32 *const value) { /* chip die 1 is accessed by setting bit 22 in the address */ addr |= 0x400000; reg_read(chip_no, addr, value); return rc; } ENT-UG1060 User Guide Revision 1.1 32 API Usage 6API Usage This section provides guidelines and information for general API usage. 6.1 Directory Structure The following table shows the directories into which the API source is organized. The source code includes application example code in a separate directory. Table 11 • API Directory Structure Directory Description vtss_api/doc Automatically generated Doxygen documentation of the public header files. The directory includes a document for each product family. vtss_api/include Public (external) header files. The application must include only vtss_api.h, which includes all other required header files. vtss_api/base API implementation and private (internal) header files. The application build system such as makefile should compile all C files in this directory. Sub directories contain API implementation, private (internal) header files, register definitions and similar information. Each switch and OTN chipset has its own separate directory containing the chip function. The phys are all included in the phy directory. The ail directory contains the generic API entry-points. The following is an example structure. ail: Common functions daytona: Daytona architecture part of the API. The Daytona architecture includes both Daytona (VSC8492) and Talladega (VSC8494) devices jaguar1: Jaguar1 switch chip functions jaguar2: Jaguar2 switch chip functions luton26: Jaguar1 switch chip functions phy: PHY chip functions serval: Serval1 switch chip functions vtss_api/boards Reference implementations of board specific code. vtss_api/appl Application example implementations, running mainly as user-space Linux applications. Adaptive equalization example: vtss_api/appl/ae Application mini_appl (use cmake to generate): vtss_api/appl/hostsim vtss_api/linux_support UIO (User IO) driver to be used when running Linux. The mini_app use the UIO driver for register access. 6.2 Common Data Structures The common data structures are defined in the include file include/vtss/api/types.h. A detailed description of the data structures can be found in the Doxygen documentation. 6.2.1 Initialization The following initialization sequence must be used for each target instance controlled by the application, with differences between switch/OTN mapper targets and PHY-only targets. The application example includes initialization code demonstrating this sequence. When the sequence has been completed, the application can start controlling ports, QoS etc. on the target. 1. Create target instance using vtss_inst_get() and vtss_inst_create(). 2. Initialize target instance using vtss_init_conf_get() and vtss_init_conf_set(). ENT-UG1060 User Guide Revision 1.1 33 API Usage 3. For switch/OTN/PHY mapper targets, register read/write callback functions must be provided by the application. • For PHY-only targets, MII management read/write callback functions must be provided by the application. • For switch/OTN targets, port map table must be set up using vtss_port_map_set(). 6.2.2 Instance References The API supports control of multiple target instances from one application. To facilitate this, the API provides a create function, vtss_inst_create, which must be called for each target instance during initialization. The create function returns an instance reference that must be used for subsequent API calls on the same target. Most applications use a single instance switch chip. For applications controlling a single target instance, the create function may be called with a NULL instance reference pointer and subsequent API calls on the target may use a NULL instance reference. 6.2.2.1 Multiple Switch Instances The following illustration shows how the instance references are used to select target instances for an application controlling a Jaguar-1 switch and a Serval-1 switch, both of which control multiple PHYs. The API internally associates a state block with each created target. The illustration uses (1) and (2) to indicate interface call references. 1. The first instance created is the Jaguar-1 target. Subsequent API function calls using the returned instance reference are directed to the Jaguar-1 device for switch and PHY control. 2. The second instance created is the Serval-1 target. Subsequent API function calls using the returned instance reference are directed to the Serval-1 device for switch and PHY control. Figure 13 • Instance References Application (1) (1) (2) (2) API StateJaguar-1 PHYs Serval-1 State Software Hardware Jaguar-1 Serval-1 Octal Octal Octal Quad Quad Single PHY PHY PHY PHY PHY PHY ENT-UG1060 User Guide Revision 1.1 34 Guidelines for Applications 7 Guidelines for Applications This section describes recommendations for customer applications. 7.1 High-Level Design Recommendations Top-down approach for system design. • Identify system requirements and functional requirements • Test requirements and test configurations • System design (integration level, cost, performance) • Software and hardware architecture. • OS selection and other functions For new software functionality and applications consider the following implementation options. • Integration of new functionality in the existing WebStaX application • Port existing costumer application to the API • Write an application from scratch 7.2 Recommended API Calling Sequence The following is a recommended API calling sequence that helps prevent the passing of structures from the application to the API with uninitialized or incorrectly initialized variables. In general, the API does not perform boundary checking of elements within a given structure passed into the API. 1. Declare the structure to be passed into the API. Example: vtss_init_conf_t init_conf 2. Initialize the data structure • Initialize all parameters in the declared structure to 0 using memset or equivalent OS function OR 3. Execute the get function call so that the structure that was previously declared and passed in gets set to the existing values in the API. Example: vtss_init_conf_get 4. Modify only the values within the structure where a change is desired. Example: init.conf.two_lane_upi = 2 5. Execute the set function call so that the structure passed in, gets set in the hardware configuration registers by the API. Example: vtss_init_conf_set 7.3 Checklist for API Configuration Use the following checklist as a guideline when porting the API. Some initialization can be done on the compilation line. 1. Initialize VTSS_OPT_PORT_COUNT macro. Example: -DVTSS_OPT_PORT_COUNT=4 2. Initialize operating system type and OS specific functions (OS specific functions are defined for eCOS and Linux). Example: -DVTSS_OPSYS_LINUX=1 3. Initialize for PHY chip type. Example: -DVTSS_CHIP_CU_PHY ENT-UG1060 User Guide Revision 1.1 35 Device Families 8 Device Families The API supports the following four different device families. 8.1 1GE PHY The API supports a number of Microsemi PHY products. Each device may include multiple PHYs (ports). For each target instance, the individual PHYs are identified using a port number. The following illustration shows two PHY applications: 1. One single PHY connected to a MAC inside a CPU. Both the MAC interface and the MII management interface of the PHY are connected to the CPU. 2. Three octal PHYs connected to a VTSS switch/MAC chip. Both the MAC interfaces and the MII management interfaces of the PHYs are connected to the switch/MAC device. The API contains examples of both application types. Figure 14 • 1GE PHY CPU Switch/MAC MAC Interface MAC Interface MAC Interface MAC Interface PHY PHY PHY PHY Media Interface Media Interface Media Interface Media Interface 8.1.1 PHY Initialization PHY initialization must be performed using the following steps. 1. Initialize the device by calling the vtss_phy_pre_reset function. This will perform initialization needed for the entire device (e.g., load the internal 8 051 CPU). The vtss_phy_pre_reset function must be called with the lowest PHY (port) number within the device. 2. Initialize each PHY within the device by calling the vtss_phy_reset function for each PHY (port). 3. Start up the device by calling the vtss_phy_post_reset function. This will perform the device setup, which is needed after the first time all PHYs within the device have been reset (e.g., set the coma pin). The vtss_phy_post_reset function can be called with any PHY (port) number within the device. 8.1.2 PHY Control after Initialization After the main initialization, the normal PHY control sequence for each port is as follows: 1. Configure the PHY using vtss_phy_conf_set. 2. Periodically poll the PHY status to detect link change events: • For PHY-only applications, use vtss_phy_status_get. • For switch/MAC applications, use vtss_port_status_get. 3. If link state events are detected, the application must take appropriate action. If auto-negotiation is enabled, the switch/MAC must normally configure speed, duplex, and flow control at link-up events. ENT-UG1060 User Guide Revision 1.1 36 Device Families 8.2 10G PHY The 10G PHY family includes products listed for VTSS_CHIP_10G_PHY. The individual PHYs are identified using a port number. The following illustration shows two PHY applications: 1. One single 10G PHY connected to a XAUI interface of a MAC inside a CPU. Both the MAC interface and the MDIO management interface of the PHY are connected to the CPU. 2. Multiple 10G PHYs connected to a switch/MAC chip. Both the MAC interfaces and the MDIO management interfaces of the PHYs are connected to the switch/MAC devices. The API contains examples of both application types. Figure 15 • 10G PHY CPU Switch/MAC XAUI Interface XAUI Interface XAUI Interface 10G PHY PHY PHY XFP/SFP+ XFP/SFP+ XFP/SFP+ The normal 10G PHY control sequence for each port is to set the PHY operating mode using vtss_phy_10g_mode_set. This function detects, resets, and sets the operating mode of the PHY type. 8.3 Switch Families The following illustration shows an example of a switch based on the Jaguar-1 product. The system is a Layer 2 switch with 16 Cu ports and 4 SFP ports. Figure 16 • Switch Jaguar-1 S S S S Octal Octal F F F F PHY PHY P P P P For switch families, the initialization sequence is as follows: 1. Create a target using vtss_inst_get and vtss_inst_create. 2. Initialize a target instance using vtss_init_conf_get and vtss_init_conf_set. 3. Set up the port map table using vtss_port_map_set. 4. Configure the switch ports • If PHYs are present, reset and configure PHYs • Configure ports using vtss_port_conf_get and vtss_port_conf_set. 8.4 OTN Mapper Families The following illustration shows a mapper application example based on the VSC8492 Daytona product. The line interfaces operate in XFI/SFI mode. The client interfaces may operate in XAUI/SFI-4.2/TFI-5 host interface mode or XFI/SFI mode, depending on the configuration mode of the device. ENT-UG1060 User Guide Revision 1.1 37 Device Families Figure 17 • OTN Mapper XAUI XAUI XFI XFI XFI XFI SFI4.2 SFI4.2 SFI SFI SFI SFI TFI5 TFI5 Client Interfaces VSC8492 Line Interfaces XFI XFI XFI XFI SFI SFI SFI SFI For mapper families, the initialization sequence is as follows: 1. Create a target using vtss_inst_get and vtss_inst_create. 2. Initialize a target instance using vtss_init_conf_get and vtss_init_conf_set. • Set the mode of operation for each of the two channels. 3. Set up the port map table using vtss_port_map_set. The Daytona mapper family can operate in one of many different modes. Changing this mode will cause a re-initialization of the channel. The VSC8494 Talladega product is actually two VSC8492 Daytona dies in one chip. Therefore this chip is treated as two separate chips, and as a consequence also implemented using two instances of the API as shown in the following illustration. Figure 18 • VSC8489 Application (1) (2) VSC8492 API VSC8492 Software Hardware CPU i/f VSC8494 CPU i/f Channel 0,1 Channel 2,3 ENT-UG1060 User Guide Revision 1.1 38 API Function Groups 9 API Function Groups This section describes the API functional groups and provides a high level overview of the implemented functions. Detailed descriptions of the API functions are available in the Doxygen files included with the source code. The API supports multiple chip generations and architectures. All functions are not applicable to a given chip. The Doxygen generated documents show only the supported functions for a given chip architecture, see chapter 9. The header files include detailed descriptions on the data types and functions while the documentation directory includes a document for each product family. These resources provide information about the API for a specific product. The following general definitions are listed in the include/vtss_options.h file. • Feature defines The selection of one or more targets at compile time causes a number of #define directives (VTSS_FEATURE_*) to be defined. These are used to specify the available functions and data fields, see chapter 3.2 • Options Default values are assigned to compile time options (VTSS_OPT_*). These default values may be overridden when building the API. The options supported are listed in chapter 3.2.2. The following table shows the API include files and the target (switch, PHY, and OTN). The files can be found in the include directory. Table 12 • API Include Files File (vtss_api/include/*.h) Description Switch PHY OTN vtss_ae_api.h Adaptive equalization API functions. vtss_afi_api.h Automatic frame injector API functions. x vtss_aneg_api.h Auto negotiation API functions. vtss_api_config.h.in Cmake defines. vtss_api.h General include file for other relevant includes, xxx depending on the VTSS_FEATURE_ * defines. vtss_evc_api.h Ethernet virtual connection (EVC) API functions. x vtss_fdma_api.h Frame DMA (FDMA) API functions. x vtss_gfp_api.h Generic framing protocol (GFP) API. x vtss_hqos_api.h Hierarchical quality of service (HQoS) API x functions. vtss_i2c_api.h I2C API functions. x vtss_init_api.h Initialization API. Functions used to create and xx initialize targets. vtss_l2_api.h Layer 2 functions used to control basic switching x features. vtss_l3_api.h Layer 3 routing API. L3 IPv4/IPv6 hardware x assisted routing functions. vtss_mac10g_api.h MAC10G API functions. x vtss_macsec_api.h IEEE 802.1AE MacSec API functions. x ENT-UG1060 User Guide Revision 1.1 39 API Function Groups Table 12 • API Include Files (continued) vtss_misc_api.h Miscellaneous API. Describes miscellaneous API xxx functions (trace, debug, lock, GPIO, LED, IRQ, fan, EEE, time stamp, register). vtss_mpls_api.h MPLS API functions. x vtss_oam_api.h Operations, administration and maintenance x (OAM) API. Describes Y.1731/IEEE802.1ag OAM functions. vtss_oha_api.h OH Add/Drop for OTN/WIS (OHA) API functions. x vtss_os_custom.h Operating system custom header file. Skeleton to xxx be replaced by customer specific OS. vtss_os_ecos.h eCos OS API. Describes OS functions for eCos. x x x vtss_os.h OS layer API. Includes the OS specific header file. x x x vtss_os_linux.h Linux OS API. OS functions for Linux. x x x vtss_otn_api.h Optical transport network (OTN) API functions. x vtss_packet_api.h Packet API. CPU Rx/Tx packet functions. x vtss_pcs_10gbase_r_api.h 10GBASE_R Physical coding sublayer (PCS) API xx functions. vtss_phy_10g_api.h 10G PHY API functions. x x vtss_phy_api.h 1G PHY API functions. x x vtss_phy_ts_api.h PHY time stamping API. Precision time protocol xx (PTP)/OAM Time stamping API functions. vtss_port_api.h Port API functions. x vtss_qos_api.h Quality of service (QoS) API functions. x vtss_rab_api.h Rate adaptation buffer (RAB) API functions. x vtss_security_api.h Security API functions. x vtss_sfi4_api.h SERDES frames Interface level 4 (SFI4) API x functions. vtss_sync_api.h Synchronization API functions. x vtss_tfi5_api.h TFI5 API. TFI5 is a TDM fabric to framer Interface x defined by OIF. vtss_ts_api.h Time stamping API stamping API functions and x associated types. vtss_upi_api.h Universal PHY interface (UPI) API interface. x vtss_wis_api.h Extended-WIS (E-WIS) layer API functions. x x vtss_xaui_api.h XAUI API functions. x vtss_xfi_api.h XFI (Electrical 10G interface to XFP/SFP) API x functions. 9.1 Initialization (vtss_init_api.h) The following initialization functions are defined in include/vtss_init_api.h. • Target creation • Target initialization • Configuration of queue system ENT-UG1060 User Guide Revision 1.1 40 API Function Groups These functions must be called before calling other functions for the target. When a target instance in created a pointers to read and write functions for SPI, MII, and MMD must be provided. For targets supporting warm start (OTN devices), restart functions are also defined. 9.2 Miscellaneous (vtss_misc_api.h) Miscellaneous functions are defined in include/vtss_misc_api.h. • Trace configuration and callback functions • Debug print functions (for showing API internal information) • API lock/unlock callback functions • Register read/write (for debugging switch and OTN mapper targets) • Chip ID access (switch targets/OTN mapper) • GPIO and serial GPIO (SGPIO) control (switch targets/OTN mapper) • Interrupt control (switch targets/OTN mapper) •LED • Temperature • Pulse width modulation (PWM) • Energy Efficient Ethernet (EEE) • Poll functions (OTN) • OTN functions such as forward error correction (FEC) 9.3 Port Control (vtss_port_api.h) The file include/vtss_port_api.h defines port control functions for switch, PHY, and OTN mapper targets. Defined functions include the following: • Port map (must be called after initializing switch and OTN mapper) • MMD management for 10G PHYs • Auto negotiation, IEEE 802.3 clause 37 • Port configuration (speed, duplex, flow control etc.) (switch targets) • Port status (switch targets) • Port statistics (switch targets) In mapper targets, the configuration, status, and statics are organized per layer because the relevant layer depends on the mode of operation. 9.4 PHY (vtss_phy_api.h) The file include/vtss_phy_api.h defines PHY control functions that include the following: • PHY reset • PHY configuration and status • PHY power configuration and status • Recovered clock configuration • PHY register read/write functions • VeriPHY (cable diagnostics) • GPIO configuration • Event configuration • Loopback • Farend Fault Indication 9.5 PHY 10G (vtss_phy_10g_api.h) The file include/vtss_phy_10g_api.h defines 10G PHY control functions that include the following: • 10G PHY operating mode and status • 10G PHY sublayer status • 10G PHY reset • 10G PHY power on/off • 10G PHY loopback • 10G PHY counters ENT-UG1060 User Guide Revision 1.1 41 API Function Groups 9.6 Security (vtss_security_api.h) Security functions are used to control port authentication and access control list for switch targets. The API functions implement the following functionality: • 802.1X state (switch targets) • Access Control List (switch targets) 9.7 Layer 2 (vtss_l2_api.h) Layer 2 functions are defined in vtss_l2_api.h, which is used with switch and MAC targets. • MAC address table to control the Layer 2 forwarding database in the chip (switch targets) • Learning mode (switch targets) • RSTP and MSTP state (switch targets) • VLAN membership and port configuration (switch targets) • VCL: Advanced VLAN classification (switch targets) • VLAN translation (switch targets) • Port isolation (switch targets) • Private VLANs (switch targets) • Link aggregation (switch targets) • Port Mirroring (switch targets) • IPv4 multicast control (switch targets) • IPv6 multicast control (switch targets) • Port protection switching (EPS Ethernet Protection Switching) (switch targets) • Ring protection switching (ERPS Ethernet Ring Protection Switching) (switch targets) • Port forwarding state (switch targets) • VLAN map functions (MAC target) • VStaX stacking configuration, port configuration, UPSID and topology (switch targets) 9.8 Layer 3 (vtss_l3_api.h) Layer 3 functions are defined in vtss_l3_api.h. • rleg (get, get_specific, add) • route (get, add, del) • neighbor functions (get, add, del) • Counters 9.9 QOS, Quality of Service (vtss_qos_api.h) The file include/vtss_qos_api.h defines QoS functions for switch targets. Defined functions control the following: • QCL: QoS classification rules • QOS and port configuration • MEP policer configuration • QCE administration • Bandwidth control (policing and shaping) • Egress scheduler 9.10 HQOS, Hierarchical QoS (vtss_hqos_api.h) Hierarchical QoS features are defined in vtss_hqos_api.h • HQOS port configuration • HQOS entity administration • Rate calculation (to calculate guaranteed bandwidth for HQoS, for example) 9.11 EVC, Ethernet Virtual Connection (vtss_evc_api.h) Ethernet virtual connection functions are defined in the file vtss_evc_api.h. • EVC port configuration ENT-UG1060 User Guide Revision 1.1 42 API Function Groups • EVC policers (Ingress Bandwidth Profiles applied to frames classified to an EVC) • EVC administration • EVC Control Entry (ECE) • EVC and ECE statistics (per EVC ID and UNI/NNI port) 9.12 FDMA, Frame DMA (vtss_fdma_api.h) Frame DMA functions are defined in include/vtss_fdma_api.h. These can only be used from the internal CPU of the switch. • FDMA initialization, configuration and channel configuration. • CPU Rx functions (frame extraction) • CPU Tx functions (frame injection) • DMA handle administration, throttling of traffic • Interrupt handler • FDMA statistics 9.13 Packet Control (vtss_packet_api.h) The file include/vtss_packet_api.h defines packet control functions for switch targets. Defined functions control the following: • CPU Rx packet registration and CPU queue mappings • CPU Rx functions (configuration, port configuration, frame receive functions, header decode function) • CPU Tx functions (header encode function) • DMA configuration • NPI configuration •AFI • Frame filter 9.14 AFI, Automatic Frame Injection (vtss_afi_api.h) AFI injects the same packet periodically. VTSS_AFI_V2 support also automatic injections of sequence of packets. 9.15 OAM (vtss_oam_api.h) OAM functions are defined in vtss_oam_api.h. The OAM functions are implemented in two groups: • The Microsemi OAM Processor (VOP) is responsible for handling certain global settings across all hardware OAM instances • The Microsemi OAM Engines (VOE) implement functionality for supporting an OAM MIP or MEP. OAM functions • VOP configuration (switch and port OAM configuration) • OAM MIP (Maintenance Intermediate Point) or MEP (Maintenance Entity Point) setup • Poll or event configuration • Stat counters 9.16 MPLS (vtss_mpls_api.h) The MPLS API is made up of the following main elements: • Segments • Cross-connects • Layer-2 configuration Together, these elements allow for the creation of MPLS label-swap LSPs, PWE3 pseudo-wire head and tail ends and LSP tunnel head and tail ends. The available facilities are oriented towards the transportation of MPLS encapsulated Ethernet frames, including Ethernet OAM, and MPLS encapsulated MPLS OAM frames. ENT-UG1060 User Guide Revision 1.1 43 API Function Groups 9.17 Synchronization, SyncE (vtss_sync_api.h) Synchronization functions are defined in vtss_sync_api.h. • Get and set the configuration of a selected output clock port - against external clock controller • Get and set the configuration of input port for a selected output clock port Time Stamping, PTP support (vtss_ts_api.h, vtss_phy_ts_api.h) The file vtss_ts_api.h defines time stamping functions at the MAC layer for the Caracal and Jaguar-1 switch families. Main timing functional areas in switch chips (API functions are declared in vtss_ts_api.h): • Timing function. Time stamps in IFH • Packet analyzer. Packet get time stamped in switch chip. Packet analyzing in software at internal or external CPU. The file vtss_phy_ts_api.h defines time stamping functions at the PHY layer for devices that support IEEE 1588v2, such as the VSC8487-15 , VSC8574, and VSC8492. Functions control the following: • 1-step and 2-step time stamping feature • Tx time stamp FIFO interface • Set/Get/Synchronize time of day • Adjust clock rate Main timing functional areas in PHY chips (API functions are declared in vtss_phy_ts_api.h): • Timing function. Time stamps in registers or in packet • Packet analyzer. 9.18 OTN Mapper Layers (vtss_otn_api.h) The API defines functions such as the following to control OTN mappers. • Interface control and monitoring (XFI and UPI layers) • MAC control and monitoring (MAC and PCS layers) • OTU/FEC control and monitoring • WIS/SONET/SDH layer control and monitoring • GFP mapping control and monitoring • Backplane auto negotiation, IEEE 802.3 clause 73 • Backplane adaptive equalization, IEEE 802.3 clause 72 • Rate adaptation buffer (RAB) functions are defined in vtss_rab_api.h. ENT-UG1060 User Guide Revision 1.1 44 API Call Descriptions 10 API Call Descriptions This section describes the contents of the documentation for API calls and data structures. It also describes the following: • How to generate the Doxygen HTML files • How to browse and find information Detailed call and parameter descriptions are available in Doxygen generated format both as pdf file and HTML files. The Doxygen documentation is generated per chip architecture. For information about the differences between architecture, see the C header files. To generate the Doxygen HTML file add -DGENERATE_DOC=ON to the cmake. Execute cmake in a build directory at the same directory level as the the vtss_api directory. Doxygen generates the documentation in HTML and pdf formats. The HTML files are generated first. Generating pdf files may fail if all the required latex libraries are not available. Separate build directories are recommended for the code generation (such as the vtss_miniapp) and the build directory to generate the doxygen HTML files. Use the following code to generate the HTML files. mkdir build_doc cd build_doc cmake -DVTSS_PHY_API_ONLY=OFF -DVTSS_FEATURE_MACSEC=OFF -DVTSS_OPT_FDMA=OFF \ -DVTSS_APPL_MINI=ON -DVTSS_PRODUCT_CHIP=SERVAL -DVTSS_OPT_PORT_COUNT=12 \ -DVTSS_PRODUCT_HW=BOARD_SERVAL_REF -DVTSS_CHIP_10G_PHY=OFF -DGENERATE_DOC=ON ../vtss_api/ make Use the following command to view the Doxygen information. firefox doxygen/html/index.html The Related Pages section shows pages describing the API function groups. The Files section show the active functions, data structures and defines per include file. Figure 19 • API Call Descriptions ENT-UG1060 User Guide Revision 1.1 45 API Call Descriptions A generated version of the Doxygen pdf file based upon the chip is distributed as part of the API release. The context is the same in HTML and PDF versions. Detailed API call and parameter descriptions are also included in the pdf files. The following table shows the contents of the documentation. Table 13 • Doxygen File Contents Section Description Chapter 1: Ethernet Virtual Ethernet virtual connections (EVCs) are based on provider bridging. It Connections is possible to set up MEF-compliant EVCs including ingress bandwidth profiles. Chapter 2: Layer 2 Layer 2 functions are used to control basic switching features. Chapter 3: MPLS API The available facilities are oriented toward the transportation of MPLS- Overview encapsulated Ethernet frames, including Ethernet OAM and MPLS- encapsulated MPLS OAM frames. Chapter 4: OAM features in hardware, either completely or with CPU assist. Y.1731/IEEE802.1ag OAM Chapter 5: Automatic Frame The automatic frame injector allows for periodic transmission of frames Injector from within the switch core. Chapter 6: Security The security functions are used to control port authentication and the access control list. 10.11: vtss api/include/vtss Frame DMA description including a FAQ section. fdma api.h File Reference 10.11.3: Typedef Documentation ENT-UG1060 User Guide Revision 1.1 46 Operating System Support 11 Operating System Support This section describes the supported OS and API interaction. 11.1 OS Layer The OS layer implements functions required by the API, such as timer functions, endian, locks, and memory allocation and deallocation. An OS-specific header file is needed for each OS type. The API supports Linux and eCos, but can be extended to support any OS with basic timer functionality. The following table shows the entities defined by the OS-specific header. Table 14 • Defined Entities Name Description vtss_mtimer_t (typedef) Data type used to implement timers. VTSS_NSLEEP (nsec) Macro to sleep for nsec nanoseconds. VTSS_MSLEEP (msec) Macro to sleep for msec microseconds. VTSS_MTIMER_START (timer, msec) Macro to start a timer by initializing the timeout to msec microseconds, where timer is a variable declared of the type vtss_mtimer_t. If the timer has already been started it must be restarted with the new timeout value. VTSS_MTIMER_TIMEOUT (timer) Macro used to determine if the timer, timer, has expired, where timer is a variable declared of type vtss_mtimer_t. VTSS_MTIMER_CANCEL (timer) Macro used to cancel a timer after use. VTSS_OS_BIG_ENDIAN If undefined, little endian is assumed. If defined, big endian is assumed. VTSS_OS_NTOHL (x) Convert a 32-bit unsigned integer from network to host order. VTSS_TIME_OF_DAY (tod) Return time-of-day value. VTSS_OS_SCHEDULER_FLAGS (optional) - depends on kernel/user context. Data type (int) required to hold the value of the scheduler flags. VTSS_OS_SCHEDULER_LOCK (optional) - depends on kernel/user context. Macro used to lock the scheduler. (flags) VTSS_OS_SCHEDULER_UNLOCK (optional) - depends on kernel/user context. Macro used to restore scheduler (flags) state (from flags). VTSS_DIV64 (dividend, divisor) Perform 64-bit integer division. VTSS_MOD64 (dividend, divisor) Perform 64-bit integer modulus. VTSS_LABS (arg) Convert argument to unsigned 32-bit absolute value. VTSS_LLABS (arg) Convert argument to unsigned 64-bit absolute value. VTSS_OS_CTZ (val32) Count trailing zeroes (ctz) of a 32-bit unsigned integer argument. Returns the bit position of the first non-zero bit in argument. VTSS_OS_CTZ64 (val64) Count trailing zeroes (ctz) of a 64-bit unsigned integer argument. Returns the bit position of the first non-zero bit in argument. VTSS_OS_MALLOC (size, flags) Allocate dynamic memory. Flags argument is used to designate specific properties of allocated memory. Generally Flags is zero, but in some cases can express requesting DMA-capable memory, for example. ENT-UG1060 User Guide Revision 1.1 47 Operating System Support Table 14 • Defined Entities (continued) VTSS_OS_FREE (ptr, flags) Release previously allocated memory. 11.2 API Concurrency Protection The API functions are not re-entrant due to an internal state in the targets and the API. To protect API accesses for multi-threaded applications, two callback functions must be implemented by the application using a semaphore. • vtss_callout_lock - This function is called by the API when entering an API function. • vtss_callout_unlock - This function is called by the API when exiting an API function. For single-threaded applications, these functions may be left empty. 11.3 Trace Layer The API code includes trace macros, in the style of the C function printf, for debugging and troubleshooting. The application must implement the following callback functions for mapping the trace macros. • vtss_callout_trace_printf - Print or log a trace message. • vtss_callout_trace_hex_dump - Print or log a dump of data in hexadecimal. Trace macros are organized in groups with levels that may be changed at run-time. By default, only the error trace is enabled. The trace system may be disabled by setting VTSS_OPT_TRACE to zero at compile-time. The callback function must not be implemented if trace is disabled. 11.4 ECOS OS ECOS is supported at the internal CPU. The Microsemi Application Software application note describes eCos usages and Microsemi standard switch application such as WebStaX, SMBStax, and CEService. 11.5 Linux OS Linux is supported on both internal and external CPU. 11.6 External CPU Configuration The linux_support/misc directory contains example UIO drivers demonstrating the providing of register and interrupt access for running the API and the example application described in the Applications and API Usage Examples section. The drivers can be used to run the API on a Linux system with PCIe connections, for example from a x86 Ubuntu 12.04/14.04 LTS system. Other systems configurations and can be constructed in a similar fashion, replacing PCIe with other bus options available on your target platforms. The following code shows how to compile the UIO driver. cd linux_support/misc make clean make -C /usr/src/linux-headers-`uname -r` ARCH=x86_64 M=`pwd` The following code shows how to compile the mini_app for Linux # install the needed packets #sudo apt-get install cmake g++ #for serval1: cmake -DVTSS_PHY_API_ONLY=OFF -DVTSS_FEATURE_MACSEC=OFF -DVTSS_OPT_FDMA=OFF - DVTSS_APPL_MINI=ON -DVTSS_PRODUCT_CHIP=SERVAL \ -DVTSS_OPT_PORT_COUNT=12 -DVTSS_PRODUCT_HW=BOARD_SERVAL_REF - DVTSS_CHIP_10G_PHY=OFF ../API_4_64m/vtss_api/ ENT-UG1060 User Guide Revision 1.1 48 Operating System Support 11.6.1 Internal CPU Configuration Microsemi provides a Yocto-based Linux BSP. This includes an embedded Linux system to run on the internal CPU. For more information about the BSP and how to generate the Linux kernel and root file system, see the application note “Microsemi Linux BSP Yocto.” Once you have the basic BSP compiling, add the meta-vtss-switch layer, available from https://github.com/vtss/meta-vtss-switch. You will also need to obtain a suitable API release tarball, which should be placed in recipes-applications/vtss-api/files/. You will need API release 4.60a or later. See the application note “Microsemi Linux BSP Yocto” and https://www.yoctoproject.org/ for more information about Yocto and how to deploy the image on a target system. The tool bitbake is used to generate the boot image and root file system. For further information about bitbake, see http://www.openembedded.org,/wiki/Bitbake_cheat_sheet, and http://docs.openembedded.org/bitbake/html/. ENT-UG1060 User Guide Revision 1.1 49 Porting Steps 12 Porting Steps This section summarizes the requirements to port the API to a given platform. 12.1 Board Support Package For a given CPU system and OS, a BSP must be developed. Microsemi currently provides the following BSPs: • VCore-III/eCos for SparX-III/Caracal/Jaguar/Serval reference systems • VCore-III/Linux for SparX-III/Caracal/Jaguar/Serval reference systems 12.2 Build System Create a build system to compile the OS, application, and Microsemi API. All C-files in the vtss_api/base directory, including sub directories, must be compiled. Also set the appropriate OS (VTSS_OPSYS_ECOS, VTSS_OPSYS_LINUX or VTSS_OS_CUSTOM) and target (VTSS_CHIP_*) defines for the platform. The file vtss_api/CMakeLists.txt is available to support the cmake tool. 12.3 OS Layer When compiling for other than supported OS types, the Makefile must define the VTSS_OS_CUSTOM C preprocessor symbol. By doing so, the include file ENT-UG1060 User Guide Revision 1.1 50 Testing Applications 13 Testing Applications This section describes a simple test configuration for testing the application using the Microsemi switch API with packet traffic using a basic PC-based test system with standard open source tools. The test configuration can test most functions, but dedicated conformance, load, and performance tests require more specialized test equipment. Useful and free tools: • tcpdump for packet capture • tcpreplay for sending packets to a Linux network port from a pcap file. Can be installed at Ubuntu 14.04 LTS by "apt-get install tcpreplay". • https://code.google.com/p/ostinato/ - a network packet crafter/traffic generator and analyzer with a friendly GUI. Craft and send packets of several streams with different protocols at different rates. It is a convenient tool to create packets and inject packets at one or more network ports. However the GUI is not always intuitive and requires some adaptation to its behavior. Can be installed at Ubuntu 14.04 LTS by "apt-get install ostinato". • Wireshark is an excellent tool for viewing pcap files and for packet capture. It can decode many types of protocols. Can be installed at Ubuntu 14.04 LTS by "apt-get install wireshark". • iperf for TCP connection performance testing. Very useful tool for simple and advanced throughput performance test. Can be installed at Ubuntu 14.04 LTS by "apt-get install iperf". • http://powereditpcap.sourceforge.net/ (Windows-based Pcap editor) • http://sourceforge.net/projects/bittwist/ Bit-Twist is a free libpcap-based Ethernet packet generator for OS X, Linux, and Windows. The command line tool is useful to changes values in pcap file. • iptraf is a tool to display packet rate at Linux network ports. Can be installed at Ubuntu 14.04 LTS by "apt-get install iptraf". Installation of tools at Ubuntu 14.04 LTS : sudo apt-get install tcpreplay ostinato wireshark iperf iptraf 13.1 Basic Test Flow Examples of test flow with some recommended tools. 1. Set up the application (run the vtss_miniapp at external CPU or internal CPU). 2. Set up packet capture. • for GUI, use wireshark. • for command line, use tcpdump. 3. Send traffic. The ostinato packet generator program is an interactive GUI based. It is possible to use Wireshark to capture the generated packets in pcap files and replay the pcap files with tcpreplay (or other tools). 4. Display received traffic and Switch/PHY stat info. • Port stat •Mac table • Stat counters in cli at vtss_miniapp The test system can be extended in the following ways. • Regression test • Performance test • More network nodes • Separate system for application and test execution 13.2 Status Information from the vtss_miniapp Examples of useful status commands in the vtss_miniapp. • "port configuration" displays the port configuration ENT-UG1060 User Guide Revision 1.1 51 Testing Applications • "mac dump" dumps the mac forwarding table • "port statistics" displays port statistical counters • "port statistics 1-2 packet" displays packet statistical counters for port 1 and 2 13.3 Single Switch and PC Test Configuration A test configuration with one switch and one PC is good for a basic packet forwarding test where the test application sends and receives packets without using the OS network stack. When the PC has multiple IP addresses and data is transmitted between them, the data will be transferred by the internal loop interface and not on the Ethernet ports. Figure 20 • Switch and PC Test Configuration 13.4 Single Switch and Two PC Test Configuration The LInux OS stack can be used easily with a two-PC configuration test system.To use the Linux network stack, the IP address on the PC must be configured. ENT-UG1060 User Guide Revision 1.1 52 Testing Applications Figure 21 • Switch and Two PC Test Configuration Use the following code to set up IPv4 address. Ethernet port naming at the Linux PCs may be different from this example. Update the commands to use the actual configuration. sudo ip a a 10.10.10.1 dev eth1# at PC1 sudo ip a a 10.10.10.2 dev eth2# at PC2 Use the following code to check connectivity with ping. ping 10.10.10.2 -c4 13.4.1 Simple Throughput Performance Test The iperf tool is an easy-to-use tool to check basic throughput performance. For information about available options, see the iperf man page. Use the following command to start the iperf server at one PC. iperf -s ENT-UG1060 User Guide Revision 1.1 53 Testing Applications Use the following command to run the iperf client at the other PC. iperf -c 10.10.10.2 On a 1G Ethernet link you should get a TCP performance close to 940Mb/s with standard setup. 13.4.2 Packet Generation For test of layer 2 and layer 3 network function is often useful to build Ethernet packets. For basic test it is recommended to use the ostinato tool. You can view the transmitted Ethernet packet with wireshark or tcpdump. The following illustrations show the ostinato main window and the GUI to build Ethernet packet. Figure 22 • Ethernet Packet Build Options 13.4.3 Packet Replay For repeated test and regression test it is useful to replay pcap files on a interface. The tcpreplay and tcpdump utilities can be used to replay (transmit) Ethernet packets from a pcap file to a Linux network device. sudo tcpreplay -i eth2 uni_packet.pcap 13.4.4 Packet Capture Some useful packet capture tools are tcpdump and wireshark. Wireshark is GUI-based and tcpdump uses scripts and command lines. The following command is an example of packet capture at network interface eth1 with tcpdump. sudo tcpdump -i eth1 -w network_capture_file.pcap ENT-UG1060 User Guide Revision 1.1 54 Testing Applications 13.4.5 Two Switch Test Configuration Some functions, such as the following, require a test configuration with two or more switches. • SyncE and IEEE1588 timing protocol test. • OAM functions require two switches or two VLAN domains set up on one switch. A loop between two ports at the same switch requires special setup (link separate VLAN domains) to avoid protocol errors such as broadcast traffic replicated forever. Figure 23 • Two Switch and Two PC Test Configuration ENT-UG1060 User Guide Revision 1.1 55 Frequently Asked Questions 14 Frequently Asked Questions This section lists some frequently asked questions and answers related to API and usage. 1. Is it possible to generate one target to support two or more Microsemi switch chips? Yes if the use same feature versions. For example, VTSS_OPT_FDMA_VER must be the same for the switch chips 2. What happens if the hardware resources are used? The API call returns error and no resources are allocated. 3. Can the API support multiple applications at the same time? Yes. The API must be protected by a lock. For more information, see Porting Steps, page 50. 4. Is warm start supported? Warm start is supported for the PHY and OTN chips, but is not supported by the API for switch chips. 5. Is FDMA to an external CPU possible? Use NPI port or register access to injection/extraction buffers over PCIe/SPI. FDMA is only to local DDR3 RAM with the internal CPU. 6. What are the steps to follow to change 10G port mode? Power configurations are not necessary when changing 10G port mode. Get to the existing mode (vtss_phy_10g_mode_get) Change the parameters corresponding to the new mode Set the new mode (vtss_phy_10g_mode_set ) To change the mode from 10G LAN mode to 1G, set clause 37 control configuration. In all the cases, the switch side port configurations need to be set according to the changes. 7. Any sample makefile to compile the API alone into a package or library? Refer to the cmake system and API and Device Configurations (see page 18). 8. What files to include in the application for calling the API? Only include vtss_api.h which is the API include file. 9. Are there any functions that are not covered by the lock/unlock feature? Yes, the functions called during initialization are not protected. Care should be taken in the application to call these first before calling any other API from the application. 10. It is possible to have customer applications together with the WebStaX/.../CEStaX applications?Yes. However, many of the debug utilities to dump switch tables etc, only display the setup done by the WebStaX/.../CEStaX applications. The setup done by the API is not always visible. ENT-UG1060 User Guide Revision 1.1 56