MACsec Intel FPGA System Design User Guide

Download PDF
ID 767516
Date 6/26/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

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

6.4. Software Overview

For MACsec IP, the software stack is shown below. It depicts end-to-end flow of control and data packets from userspace applications to the hardware layer.
Figure 32. MACsec Complete Stack with Control and Data Path

Control Path: Software tools like the CLI, IP route tool and wpa_suppliant are used to trigger control commands to configure the CSRs and initiate static/dynamic key exchanges via the socket interface.

The IP tool uses Rtnllink and Netlink APIs to create the MACsec net interface and configure secure association details into the hardware. These calls are later handled by the Linux MACsec Driver and trigger the macsec_ops() of the McDMA driver to configure the CSR region.

The wpa_supplicant uses a raw packet to send or receive EAPol packets transferred between MACsec peers for authentication/session establishment and key exchange. These packets are directly handled by the base network driver (McDMA) to do xmit() or recv() to/from the hardware queues. The wpa_supplicant also uses Rtnllink and Netlink APIs to set or create the MACsec net interface and configure secure association details into the hardware via Linux MACsec Driver and McDMA Driver(The MACsec IP APIs are integrated with McDMA Driver).

The CLI debug tool uses Rtnllink and Netlink APIs to set or create the MACsec net interface and configure secure association details into the hardware. These calls are later handled by the MACsec IP Driver(with/without McDMA driver based on McDMA IP in hardware) to configure the CSR region.

Data Path: Utilities like ping, sftp, scp, etc. are used to initiate the data transfers from userspace to hardware. Depending upon the associated network protocol used by the data transfer utility, respective protocol handler gets triggered based on send() and recv() calls from application to physical layer or vice versa.

The data path is handled by the MACsec IP and SW modules are used as bypass the data flow to above or below layers.

In case offload is off, the data path is handled by Linux MACsec Driver as Tx and Rx path.

Tx Path: The Linux MACsec Driver adds the MACsec header with 0x88e5 protocol number and other details to the frame. It forwards the encrypted/protected frame to the base network driver. This network driver copies the packet to the HW Queue.

Rx Path: On the arrival of a packet, the base network driver (McDMA) allocates the socket buffer (skb) and forwards it to the Linux MACsec driver. The MACsec Driver takes care of decrypting the packet and delivers it to the upper layers.

The following sections discuss the major modules of software stack.


Section Content
McDMA Driver Kernel Module
MACsec IP APIs
Linux MACsec Driver Kernel Module
IP Tool
WPA Supplicant

Level Two Title