MACsec Intel® FPGA System Design User Guide

Download PDF
ID 767516
Date 3/31/2024
Public
Document Table of Contents
Document Table of Contents x
1. Introduction 2. Architecture 3. Interface Overview 4. Parameters 5. Configuration Registers 6. Software Architecture 7. Generating the System Design 8. Document Revision History for MACsec System Design User Guide A. Release Notes
1. Introduction x
1.1. Terminology 1.2. Release Information 1.3. System Requirements
2. Architecture x
2.1. System Architecture 2.2. Data Path Between Ethernet MAC and MACsec 2.3. Data Path Between MACsec and MCDMA 2.4. Data Path Between MACsec and Packet Generator/Checker (Packet Client) 2.5. Data Path Illustrations 2.6. Interrupts 2.7. Packet FIFO 2.8. AXI-ST Rate Controller 2.9. Error Handling 2.10. Top Level Signals
2.2. Data Path Between Ethernet MAC and MACsec x
2.2.1. Ethernet Subsystem
2.2.1. Ethernet Subsystem x
2.2.1.1. Data Receiving from MACsec to E/F-Tile Hard IP 2.2.1.2. Data Transmitting from E/F-tile Hard IP to MACsec 2.2.1.3. Order of Ethernet Transmission 2.2.1.4. E/F-Tile Hard IP Reset Sequence
2.3. Data Path Between MACsec and MCDMA x
2.3.1. AXI-ST Multi-Segment to Single-Segment Conversion 2.3.2. MCDMA
2.4. Data Path Between MACsec and Packet Generator/Checker (Packet Client) x
2.4.1. Packet Client 2.4.2. Packet Generation and Check
2.5. Data Path Illustrations x
2.5.1. MACsec Interface Signal Names
2.6. Interrupts x
2.6.1. MCDMA MSI-X Table Configuration
3. Interface Overview x
3.1. Clocking 3.2. Resets
5. Configuration Registers x
5.1. System Register Map
5.1. System Register Map x
5.1.1. Packet Client Register Map 5.1.2. Interrupt Controller Register Map
6. Software Architecture x
6.1. MACsec Key Agreement Protocol 6.2. Driver Functional Requirements 6.3. Software Requirements 6.4. Software Overview 6.5. MACsec IP APIs Sequence 6.6. Functions 6.7. Software Tools
6.4. Software Overview x
6.4.1. McDMA Driver Kernel Module 6.4.2. MACsec IP APIs 6.4.3. Linux MACsec Driver Kernel Module 6.4.4. IP Tool 6.4.5. WPA Supplicant
6.4.2. MACsec IP APIs x
6.4.2.1. SDK
6.5. MACsec IP APIs Sequence x
6.5.1. MACsec Initialization Sequence
6.5.1. MACsec Initialization Sequence x
6.5.1.1. MACsec Reset Sequence 6.5.1.2. TX Configuration Sequence 6.5.1.3. RX Configuration Sequence 6.5.1.4. TX Rekeying Sequence 6.5.1.5. RX Rekeying Sequence 6.5.1.6. Cut Through/Store Forward Mode 6.5.1.7. User Single/Multi Port Settings 6.5.1.8. Encrypt/Decrypt Port 6.5.1.9. Port Priority 6.5.1.10. Interrupt Generation and Register
6.5.1.1. MACsec Reset Sequence x
6.5.1.1.1. GLOBAL Reset 6.5.1.1.2. PORT Reset 6.5.1.1.3. Secure Association (SA) Reset
6.6. Functions x
6.6.1. macsec_initilize 6.6.2. macsec_get_attributes 6.6.3. macsec_get_sa_attributes 6.6.4. macsec_set_attributes 6.6.5. macsec_set_sa_attributes 6.6.6. macsec_read_register 6.6.7. macsec_write_register 6.6.8. macsec_set_port_configuration 6.6.9. macsec_rate_configuration 6.6.10. macsec_single_or_multi_port 6.6.11. macsec_crypto_mode 6.6.12. macsec_port_priority 6.6.13. macsec_register_isr
6.7. Software Tools x
6.7.1. IP Tool 6.7.2. WPA_Supplicant 6.7.3. CLI Debug Tool
6.7.3. CLI Debug Tool x
6.7.3.1. Functional Requirements 6.7.3.2. Features Overview 6.7.3.3. Design with HOST 6.7.3.4. Netlink Interface 6.7.3.5. SDK 6.7.3.6. Design Overview
7. Generating the System Design x
7.1. Software Requirements 7.2. Obtaining the Reference Design 7.3. Reference Design Directory Structure 7.4. Simulation Command Arguments 7.5. Simulation Test Cases 7.6. Complete Simulation Command 7.7. Simulation Requirements 7.8. Running Non-UVM Simulation 7.9. Running UVM Simulation 7.10. Building, Installing, and Running the Software 7.11. Building the Hardware Design
7.4. Simulation Command Arguments x
7.4.1. Simulation -d Options
1. Introduction
2. Architecture
3. Interface Overview
4. Parameters
5. Configuration Registers
6. Software Architecture
7. Generating the System Design
8. Document Revision History for MACsec System Design User Guide
A. Release Notes

7.5. Simulation Test Cases

The following test cases are located in the <project directory>/sim/Testcase directory.
Table 12.  Simulation Test Cases
Test Case Name Test Case Description
The list of testcases below contains the basic tests which include CSR and traffic test (full duplex) on both controlled and uncontrolled ports of the MACsec IP.
basicCSRTest.sv Basic CSR Test: Test runs CSR writes and reads on the MACsec IP and Packet Client module. This is the basic test to be run to ensure that the CSR registers are accessible from the host (here the testbench mimics the host machine with two VM instances). You can modify this test. CSR registers can be added or removed by referring to this testcase.
Note: For any new addition you need to make sure the CSR is declared and mapped to the correct register offsets in /sim/tbTop/common_defines.sv.
basicDynTrafficTest.sv

Basic Dynamic TrafficTest: Enables traffic flow from packet_client_0 -> macsec_ip_0 -> ethernet_p0 -> loopback at qsfp end -> ethernet_p1 -> macsec_ip_1 -> packet_client_1 and from other direction. This works in a full duplex mode.

This test only sends a fixed pattern with minimum packet size.
eapolTrafficTest.sv

EAPol traffic test: Enables MKA traffic from the host. The EAPol traffic flow is host_vm0 -> mcdma -> macsec_ip_0 -> ethernet_p0 -> loopback at qsfp end -> ethernet_p1 -> macsec_ip_1 -> mcdma -> host_vm1.

In this test vm0 initiates MKA packet and vm1 validates the reception of MKA packet within the PCIe RP_BFM.
fullDynTrafficTest.sv Full Dynamic TrafficTest: Enables traffic flow from packet_client_0 -> macsec_ip_0 -> ethernet_p0 -> loopback at qsfp end -> ethernet_p1 -> macsec_ip_1 -> packet_client_1 and from other macsec direction. This works in a full duplex mode.

This test sends various min and max size packets with fixed and incremental data patterns. You can modify this test for different packet sizes and traffic patterns.

combinedTrafficTest.sv Combined Traffic test: Combines both basic dynamic traffic and EAPoL traffic, i.e. both controlled and uncontrolled ports are driven with respective traffic simultaneously. This mimics the real traffic test scenario as it is in a SW+HW test on board.
pcieUserMsixTest.sv PCIe user MSIX test: Checks the interrupt function. Each MACsec IP has its own corresponding interrupt controller. There are 3 registers (i.e. enable, clear, and status) in each controller to manage the interrupt service. In this test case an interrupt is forced and the test scenario is created and tested.
jumboDynTrafficTest.sv Jumbo Traffic test: Verifies the jumbo frame traffic test capability. It enables traffic flow from packet_client_0 -> macsec_ip_0 -> ethernet_p0 -> lpbk at qsfp end -> ethernet_p1 -> macsec_ip_1 -> packet_client_1 and vice versa.

This test sends a fixed pattern with a packet size of maximum 9000 bytes but can be modified by the user for different traffic patterns and sizes.

The list of testcases below recreates the SW+HW validation tests in the RTL simulation in which they mainly check the datapath.
rx_sc1_not_receiving_pckts.sv RX SC1 not receiving packet: Is an IP scenario test where you configure the Tx and Rx with SC1 and SA0, and the RX inuse register is expected to be 0x1.
fullDynTrafficTest_enc_off_pro_on_fail.sv

Full Dynamic TrafficTest with Encryption ON and Protection ON: With SCI not included is an IP scenario test where the MACsec IP is configured with Enc_on, Pro_on, and SCIs disabled and it is expected that the traffic has to pass through without any issue.

Refer to this test case to see the list of MACsec IP registers that needs to be updated.

Traffic flow: packet_client_0 -> macsec_ip_0 -> ethernet_p0 -> loopback at qsfp end -> ethernet_p1 -> macsec_ip_1 -> packet_client_1 and vice versa.

This test sends a basic fixed data pattern traffic.

You can modify this test to support different packet sizes and traffic patterns.
fullDynTrafficTest_enc_on_pro_on.sv

Full Dynamic TrafficTest with Encryption ON and Protection ON: Is an IP scenario test where the MACsec IP is configured with Enc_on and Pro_on and it is expected that the traffic has to pass through without any issue.

Refer to this test case to see the list of MACsec IP registers that needs to be updated.

Traffic flow: packet_client_0 -> macsec_ip_0 -> ethernet_p0 -> loopback at qsfp end -> ethernet_p1 -> macsec_ip_1 -> packet_client_1 and vice versa.

This test sends a basic fixed data pattern traffic. You can modify this test to support different packet sizes and traffic patterns.

Eyn_On_pro_on_outpkt_toolong.sv

Encryption on, protection on and outpacket too long Test: Is a scenario test where the MACsec IP is configured with Enc_on, Pro_on and it is expected that the RX traffic should drop if outpacket too long error is reported.

Refer to this test case to check the list of MACsec IP registers that needs to be updated.

Traffic flow: packet_client_0 -> macsec_ip_0 -> ethernet_p0 -> loopback at qsfp end -> ethernet_p1 -> macsec_ip_1 -> packet_client_1 and vice versa.

This test sends a basic fixed data pattern traffic.
Eyn_off_Pro_Off.sv

Encryption off and protection off Test: Is a scenario test where the MACsec IP is configured with Enc_off, Pro_off and it is expected that the traffic has to pass through without any issue.

Refer to this test case to check the list of MACsec IP registers that needs to be updated.

Traffic flow: packet_client_0 -> macsec_ip_0 -> ethernet_p0 -> loopback at qsfp end -> ethernet_p1 -> macsec_ip_1 -> packet_client_1 and vice versa.

This test sends a basic fixed data pattern traffic.

You can modify this test to support different packet sizes and traffic patterns.
Eyn_off_pro_on_with_end_station_on.sv

TrafficTest with Encryption OFF and Protection ON with end station ON: Is an IP scenario test where the MACsec IP is configured with Enc_off and Pro_on and it is expected that the traffic has to pass through without any issue.

Refer to this test case to see the list of MACsec IP registers that needs to be updated.

Traffic flow: packet_client_0 -> macsec_ip_0 -> ethernet_p0 -> loopback at qsfp end -> ethernet_p1 -> macsec_ip_1 -> packet_client_1 and vice versa.

This test sends a basic fixed data pattern traffic.

You can modify this test to support different packet sizes and traffic patterns.
Eyn_on_pro_on_with_RX_config_only_SCI.sv

Encryption on, protection on with RX config only SCI Test: Is a scenario test where the MACsec IP is configured with Enc_on, Pro_on and RX config only SCI and it is expected that the traffic has to pass through without any issue.

Refer to this test case to check the list of MACsec IP registers that needs to be updated.

Traffic flow: packet_client_0 -> macsec_ip_0 -> ethernet_p0 -> loopback at qsfp end -> ethernet_p1 -> macsec_ip_1 -> packet_client_1 and vice versa.

This test sends a basic fixed data pattern traffic.

You can modify this test to support different packet sizes and traffic patterns.
Eyn_on_pro_on_with_cport_off.sv

Encryption on, protection on with cport off Test: Is a scenario test where the MACsec IP is configured with Enc_on, Pro_on with cport off and it is expected that the traffic has to pass through without any issue.

Refer to this test case to check the list of MACsec IP registers that needs to be updated.

Traffic flow: packet_client_0 -> macsec_ip_0 -> ethernet_p0 -> loopback at qsfp end -> ethernet_p1 -> macsec_ip_1 -> packet_client_1 and vice versa.

This test sends a basic fixed data pattern traffic.

You can modify this test to support different packet sizes and traffic patterns.
FullDynTest_EynON_Pro_Off.sv

TrafficTest with Encryption ON and Protection OFF: Is an IP scenario test where the MACsec IP is configured with Enc_on, Pro_off and it is expected that the traffic has to pass through without any issue.

Refer to this test case to check the list of MACsec IP registers that needs to be updated.

Traffic flow: packet_client_0 -> macsec_ip_0 -> ethernet_p0 -> loopback at qsfp end -> ethernet_p1 -> macsec_ip_1 -> packet_client_1 and vice versa.

This test sends a basic fixed data pattern traffic.

You can modify this test to support different packet sizes and traffic patterns.
FullDynTest_Confidentiality_offset_50bytes.sv

TrafficTest with Confidentiality offset selected 0x32 : Is an IP scenario test where the MACsec IP is configured with cipher confidentiality offset to 50 bytes. It is expected that the traffic has to pass through without any issue.

Refer to this test case to see the list of MACsec IP registers that needs to be updated.

Traffic flow: packet_client_0 -> macsec_ip_0 -> ethernet_p0 -> loopback at qsfp end -> ethernet_p1 -> macsec_ip_1 -> packet_client_1 and vice versa.

This test sends a basic fixed data pattern traffic.

You can modify this test to support different packet sizes and traffic patterns.
Level Two Title