MACsec Intel® FPGA System Design User Guide

Download PDF
ID 767516
Date 10/02/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.7.3.4. Netlink Interface

The MACsec IP driver accesses memory mapped MACsec IP registers over the AXI bus. This module communicates with user-space over netlink socket. The details of netlink structure, family, and API's are as follows:

NETLINK STRUCTURE

The CLI talks with linux kernel module over a netlink communication channel. The netlink family used to establish this communication is "GENERIC_NETLINK". There are 4 main netlink commands used for configuring the MACsec IP. These are:
  1. INTEL_MACSEC_C_GETATTR
  2. INTEL_MACSEC_C_SETATTR
  3. INTEL_MACSEC_C_GETSAATTR
  4. INTEL_MACSEC_C_SETSAATTR

The above netlink commands are responsible for handling macsec_get_attr(), macsec_set_attr(), macsec_get_sa_attr() and macsec_set_sa_attr() APIs based on invokation from the CLI.

The 2 additional commands, which are used to write/read the MACsec PPBB IP device registers directly, are:
  1. INTEL_MACSEC_C_PPBB_READREG
  2. INTEL_MACSEC_C_PPBB_WRITEREG
Apart from the commands above, there are 2 additional commands, which are used to peek-and-poke MACsec IP device registers directly. This read-write functionality is helpful in debugging. These commands are:
  1. INTEL_MACSEC_C_READREG
  2. INTEL_MACSEC_C_WRITEREG
The netlink protocol is a socket based communication. The socket attributes used for exchange of information between the CLI and Kernel are:
  1. INTEL_MACSEC_A_PORT
  2. INTEL_MACSEC_A_ATTR
  3. INTEL_MACSEC_A_RW_VAL
  4. INTEL_MACSEC_A_SC
  5. INTEL_MACSEC_A_SA

The above netlink attributes correspond to the MACsec ip port value, MACsec ip command attribute, read/write value for a particular command attribute, MACsec ip secure channel value, and MACsec ip secure association value.

Apart from the main attributes above there is 1 additional attribute used for debugging. This helps program offset the device register to be programmed. The attribute is:
  • INTEL_MACSEC_A_OFFSET

NETLINK FAMILY

The linux kernel module registers a generic netlink family name, on which the kernel routes any user-space interaction. A Linux kernel can have multiple netlink families registered at a time. A User-space application has to mention the corresponding name to interact with a particular netlink channel.

The MACsec IP kernel module registers with "intel_MACsec" as a netlink family name, which is used by the CLI to interact with the Kernel module.

NETLINK HANDLER FUNCTIONS

The linux kernel module registers 6 handlers for all of the above netlink commands. These handler functions are:
  1. genl_get_attr()
  2. genl_set_attr()
  3. genl_get_sa_attr()
  4. genl_set_sa_attr()
  5. genl_ppbb_read_reg()
  6. genl_ppbb_write_reg()
  7. genl_read_reg()
  8. genl_write_reg()

All of the above handlers receive socket buffer information from the CLI, invoke the respective MACsec IP API, on success return the data received from the API, on failure returns the error code back to the CLI.

Level Two Title