Security-IP-197 DDK v5.5 User-Guide RevA

Security IP
Protocol-IP-197
Driver Development Kit v5.5
User Guide
Document Revision: A
Document Date: 2021-11-16
Document Number: 007-197550-308
Document Status: Accepted
© Rambus Inc. • rambus.com CONFIDENTIAL

Copyright 2011-2021 Rambus Inc. This document contains information which is proprietary and confidential, and
which is protected under patents, copyrights, and/or other IP rights of Rambus Inc. If you are not the intended
recipient of this material, please destroy this document and inform Rambus at +1 408 463 8000 or
sipsupport@rambus.com immediately.
Rambus Inc. Corporate Headquarters

4453 North First Street, Suite 100
San Jose, CA 95134
Phone: +1 408-462-8000
Website : https://www.rambus.com/
Contact : sipsupport@rambus.com
Rambus ROTW Holding B.V.

Boxtelseweg 26A
5261 NE Vught
The Netherlands
Phone: +31-73-6581900
© Rambus Inc. • rambus.com CONFIDENTIAL 2

Security IP Protocol-IP-197 Driver Development Kit v5.5
007-197550-308
User Guide Rev. A
Table of Contents
Table of Contents ................................................................................... 3

List of Tables........................................................................................... 6
List of Figures ......................................................................................... 6
Document Revision History .................................................................... 7
1 Introduction .................................................................................... 8
Purpose ..................................................................................................... 8
Related Documents ................................................................................... 8
Target Audience ........................................................................................ 8
Acronyms .................................................................................................. 9
2 DDK Concept ................................................................................. 10
Goal......................................................................................................... 10
Terminology ............................................................................................ 10
Contents.................................................................................................. 12
Driver Development Difficulties .............................................................. 12
2.4.1 DDK Problem-Solution Map .................................................................................... 13
DDK Installation ...................................................................................... 15
Main Components Overview ................................................................... 17
3 Driver Customization Instructions ................................................ 19
Interrupt Functionality Customization .................................................... 19
3.1.1 AMP use case .......................................................................................................... 20
3.1.2 SMP use case ........................................................................................................... 20
3.1.3 Customizing combined driver ................................................................................. 21
3.1.4 Customizing separate drivers .................................................................................. 21
Driver Framework Customization ............................................................ 22
3.2.1 DMA-safe buffer allocation for kernel-space drivers.............................................. 23
Firmware download ................................................................................ 23
Kernel Support Driver.............................................................................. 23
3.4.1 DMA-safe buffer allocation for user-space drivers ................................................. 24
3.4.2 Shared device access protection for multiple applications .................................... 24
Customization for ARM platform ............................................................ 24
3.5.1 Device registration in Linux kernel.......................................................................... 24
3.5.2 DMA buffers allocation and mapping to user space ............................................... 25

007-197550-308
User Guide Rev. A
4 Driver Deployments ...................................................................... 26

Kernel-space Driver ................................................................................. 27
User-space Driver .................................................................................... 28
5 Packet Flows ................................................................................. 29
Packet flows without classification and without token building offload. . 29
Packet flows without classification and with token building offload. ...... 30
Packet flows with classification and with token building offload. ............ 30
6 Application Support ...................................................................... 31
Single Application Support ...................................................................... 31
Multiple Application Support .................................................................. 32
7 Driver Build and Test Instructions ................................................. 34
Build Instructions for a single configuration ............................................ 34
Test Instructions...................................................................................... 35
Build and Test Instructions for Multiple Configurations .......................... 35
8 Driver API ...................................................................................... 36
Combined Driver Initialization API........................................................... 36
Global Control Driver Initialization API .................................................... 36
PEC Driver Initialization API ..................................................................... 36
PEC-PCL Driver Initialization API .............................................................. 36
Packet Engine Control (PEC) API .............................................................. 37
Global Control API ................................................................................... 37
Packet Classification (PCL) API ................................................................. 37
DMA Buffers Allocation (DMABuf) API .................................................... 37
Memory Access API ................................................................................. 38
IOToken API ............................................................................................ 38
9 Data Structures ............................................................................. 39
Dynamic Resource (DMA) Data Structures .............................................. 39
Security Association (SA) Data Structures ............................................... 40
Transform Data Structures ...................................................................... 41
Packet Token Data Structures ................................................................. 42
IO Token Data Structures ........................................................................ 42
Packet Data Structures ............................................................................ 42
Packet Descriptor Data Structures .......................................................... 43
Flow Data Structures ............................................................................... 43

007-197550-308
User Guide Rev. A
10 Driver Configuration Parameters .................................................. 46

DDK-wide configuration parameters ....................................................... 46
Top-level Driver configuration parameters ............................................. 47
Top-level Adapter configuration parameters .......................................... 50
Top-level Driver Framework (HWPAL) configuration parameters ........... 52
Other top-level configuration parameters .............................................. 55
10.5.1 EIP Driver Libraries .................................................................................................. 55
10.5.2 List component........................................................................................................ 55
10.5.3 Interrupt Dispatcher................................................................................................ 55
Default Driver Configuration ................................................................... 55
Driver Traces (Logging) Configuration ..................................................... 56

007-197550-308
User Guide Rev. A
List of Tables
Table 1 Typical driver development problems .................................................................................................. 13
Table 2 DDK folders after installation ................................................................................................................ 15
List of Figures
Figure 1 EIP-197 Driver Kernel-Space and User-Space Deployments ................................................................. 26
Figure 2 MemXS and Driver Framework user-space deployment ...................................................................... 27
Figure 3 Multiple application support example .................................................................................................. 33
Figure 4 Driver Data Structure Relationships, look-aside use case..................................................................... 40
Figure 5 PCL Data Structure Relationships.......................................................................................................... 45

007-197550-308
User Guide Rev. A
Document Revision History

Doc Page(s) Date Author Purpose of Revision
Rev Section(s)
A All 2021-11-16 LB First version created for DDK v5.5

007-197550-308
User Guide Rev. A
1 Introduction
Purpose
The Security-IP-197 Engine (also referred to as the EIP-197) contains an engine that incorporates a number
of cryptographic hardware modules used to accelerate security protocols such as IPSec, SSL and SRTP as
well as block cipher crypto and hash algorithms. The protocol functions and operations are performed
within the EIP-197 Engine as well as on the host CPU. Security functions on the host CPU relate to key
management, maintenance of the Security Association Database (SAD) and the control of the EIP-197
Engine. The EIP-96 Packet Engine is one of the main functional blocks within the EIP-197 hardware that
performs encryption, hashing and various protocol processing. Another important functional block of the
EIP-197 Engine is the EIP-207 Classification Engine. The EIP-207 block with its dedicated firmware can be
used to offload the host CPU for the packet classification and network protocol header processing.
Please see the “Dependencies and Compatibility” section of the corresponding release notes for hardware
version specific compatibility information.
The Driver Development Kit (DDK) provides a set of solutions required to develop drivers for this engine for
systems built according to the Von Neumann architecture and its derivatives such as Harvard architecture
and Modified Harvard architecture. Solutions for typical driver development problems are provided in
various forms such as documentation, API specification and example code.
Note: The DDK contains Example Drivers for the EIP-197 hardware for the x86 PC and RISC ARM Linux
platforms. However, the main purpose of this toolkit is to provide support for the customized
driver development for HW platforms and OSes chosen by the DDK users.
The purpose of this document is to provide:
• High level overview of DDK components;
• Description of typical driver development problems and solutions provided in the DDK;
• References to APIs that can be used in customized drivers;
• References to example code that can be used as a base for customized drivers;
• Reference to the other documents useful for the understanding of driver development.
Related Documents
Ref Document Document Number
[1] Security-IP Driver Framework Porting Guide 007-900440-304
[2] Security-IP-PEC SLAD Test Tool User Guide 007-903110-302
[3] Security-IP-197 DDK Test Specification 007-197550-310
[4] Security-IP-197 Firmware Reference Manual 007-197340-204
[5] Security-IP-197 Driver Software Block Diagram N/A
[6] Security-IP-197 Driver Library User Guide 007-197290-307
[7] Security-IP-201 Driver Library User Guide 007-201310-307
[8] Security-IP-197 Regression System README N/A
[9] Security-IP-197 PEC PCL Test Tool README N/A
This information is correct at the time of document release. Rambus reserves the right to update the related
documents without updating this document. Please contact Rambus for the latest document revisions.
The preferred method for getting technical support is to use our online support system at
https://sipsupport.rambus.com. If you do not have an account yet for this system, please contact Rambus
technical support (sipsupport@rambus.com).
Target Audience
This document is for software developers who want to create customized drivers for the EIP-197 hardware.

007-197550-308
User Guide Rev. A
Acronyms
Acronym Description
API Application Program Interface
CCS Concurrent Context Synchronization
CDS Concurrent Device Synchronization
CPU Central Processing Unit
DDK Driver Development Kit
DMA Direct Memory Access
EIP Embedded Intellectual Property
FW Firmware
HW Hardware
I/O Input/Output
IDE Integrated Development Environment
OCE Output Classification Engine
OS Operating System
PE Packet Engine
PEC Packet Engine Control
PCL Packet Classification
RTT RealTime Trace Tool
SATB SA and Token Builder
SLAD Security Look-aside Accelerator Driver
SW Software

007-197550-308
User Guide Rev. A
2 DDK Concept
Goal
The goal of the DDK is to reduce the development effort of customized drivers for the EIP-197 hardware and
enable faster integration into the customer’s system applications. Example Drivers for the EIP-197 hardware
are provided which can be used as a starting point for development of a customized driver.
Note: The provided Example Drivers are tested only with the HW platform and OS indicated in its test
report. The DDK can be used to develop a driver for other HW platforms and OSes.
Terminology
The table below describes various terms used throughout the document.
Term Description
Adapter Software component that needs to be customized for specific hardware platform, OS, use
cases, system application and required driver API.
SLAD Adapter PEC Adapter used in EIP-197 Example Combined Driver and PEC Driver for the packet I/O
functionality implemented as the PEC API used in all packet flows that perform packet I/O
via the ring interface.
PCL Adapter Adapter used in EIP-197 Example Combined Driver and PEC-PCL Driver for the packet
classification functionality implemented as the PCL API used only in packet flows that
require classification.
Global Adapter Adapter used in EIP-197 Example Combined Driver and Global Control Driver for the
packet I/O functionality implemented as the PEC API used all packet flows.
Kernel-space Driver with its API is deployed in the application kernel-space memory domain, e.g. the
deployment application with the driver runs in the kernel-space.
User-space Driver with its API is deployed in the application user-space memory domain, e.g. the
deployment application with the driver runs in the user-space.
Driver Framework Collection of software interface (API) specifications typically used by EIP Driver Libraries
and other driver components. This framework defines how to use EIP Driver Libraries in a
driver.
EIP Driver Library Software library that contains control functionality for a given EIP hardware block only and
is free of any other hardware or software functionality not related to this EIP hardware
block.
EIP-197 Kernel An Example Driver which implements the support functionality for the EIP-197 driver(s)
Support Driver deployed in Linux user-space. It also implements the support functionality for the shared
device access (for example, EIP-207 Record Cache used from different applications) for
drivers deployed in Linux user-space as well as in the Linux kernel-space.
EIP-197 Combined An Example Driver which implements the Global Control API, SLAD PEC API (with SLAD
Driver DMABuf API).
It may be used to verify EIP-197 Driver Library including Global Control, Flow Control (EIP-
207) and Ring Control (EIP-202) functionality on one driver and other DDK software
components.
Some customization effort may be required from users to start using the driver in their
system application.
EIP-197 Global Control An Example Driver that implements the Global Control API. This API allows to initialize the
Driver EIP-197 engine which includes the firmware download and to get the engine status
information. Only on instance of this API is supported.
It may be used to verify EIP-197 Driver Library including only the Global Control
functionality in one driver and other DDK software components.
system application.

007-197550-308
User Guide Rev. A
EIP-197 An Example Driver which implements the SLAD PEC API, IOToken API with SLAD DMABuf
PEC Driver API. The DMABuf API allows for allocation of DMA-safe buffers which can be used
subsequently with the PEC. The PEC API allows for packet I/O between the host CPU and
the EIP-197 engine for the Look-Aside packet flows. This API is also used for the record
invalidation in the EIP-197 engine internal record cache for the Look-Aside as well as for
the In-Line packet flows. Multiple instances of this API are supported. The maximum
number of this API instances is equal to the maximum number of the EIP-202 hardware
rings supported by the EIP-197 engine.
This Driver also provides the implementation of the IOToken API which allows for IO
tokens creation, standard ones for EIP-96 as well as extended ones for the EIP-207
firmware.
This Driver may be used to verify EIP-197 Driver Library including only the Ring Control
functionality in one driver and other DDK software components. This driver must be used
together with the EIP-197 Global Control Driver.
system application.
EIP-197 An Example Driver which implements the SLAD PEC API (with SLAD DMABuf API), IOToken
PEC PCL Driver API and PCL API. The PCL API allows setting the packet classification rules so that the
engine can match the packet to the keys (transform record) for the protocol crypto
operation for the Look-aside and In-Line packet flows. Only one instance of this API is
supported. For the Inline packet flows the external Hosts system can provide the
transform (SA) record pointer to the EIP-197. In this case the EIP-197 will skip the packet
classification step and proceed with the packet and transform record using the provided
pointer.
This Driver also provides the implementation of the IOToken API.
This Driver must be used together with the EIP-197 Global Control Driver and can be used
together with the EIP-197 PEC Driver.
This Driver may be used to verify EIP-197 Driver Library including only the Flow Control
and Ring Control functionality in one driver and other DDK software components.
system application.
SLAD PEC Test Tool Application used to verify the functionality of the Driver with the integrated EIP-197 Driver
Library that implements the SLAD PEC API, IOToken API and the SLAD DMABuf API.
Classification (PCL) Application used to verify the functionality of the driver with the integrated EIP-197 Driver
Test Tool Library that implements the PCL API, SLAD PEC API, IOToken API and the SLAD DMABuf
API.
Real-Time Trace Tool Application used to trace the packet processing inside the EIP-197 Engine using the Global
(RTT) Control API. This application can be used to poll the Engine registers as well as the EIP-207
firmware state transitions which the firmware undergoes during packet processing.
Customized Driver EIP-197 driver customized for specific use cases in a system application. Usually requires
(C-Driver) significant development effort. After the customization, the driver is ready to use in a
customer’s system application.
SA Builder Software component that creates SA data structures that are specific to a particular
(standalone) packet engine, e.g. the EIP-96 Packet Engine. This component via its SA Builder (SAB) API
allows for building SA’s (transform records) with the key material in the format specific to
the EIP-96 Packet Engine for the Look-Aside packet flows. This API can be instantiated as
many times as required.
This component is not a part of the Driver, but is provided as a part of the DDK.
Extended SA Builder SA Builder that contains functionality to offload token building to the firmware. This
component via its SA Builder API allows for building SA’s (transform records) with the key
material in the format specific to the EIP-96 Packet Engine with the EIP-207 firmware
specific extensions for the Look-Aside and In-line packet flows. This API can be instantiated
as many times as required.
This component is not a part of the Driver, but is provided as a part of the DDK. This is
used for all packet flows that employ token building offload.

007-197550-308
User Guide Rev. A
Token Builder Software component that creates packet tokens, as required by some packet engine types,
such as the EIP-96 Packet Engine. This component via its Token Builder (TB) API allows for
building packet processing instructions (EIP-96 Tokens) in the format specific to the EIP-96
Packet Engine for the Look-Aside packet flows. This API is used together with the SA
Builder API and can be instantiated as many times as required.
This component is not a part of the Driver, but is provided as a part of the DDK. This is
used for all packet flows that do not employ token building offload.
Packet flow A set of operations performed by the host that interacts with the EIP-197 Engine in a
specific way to process packets. Some of these packet processing operations the host can
offload to the EIP-197 Engine. The packet flow type determines which packet processing
operations can be offloaded to the EIP-197 Engine. The EIP-197 Engine together with the
DDK software and EIP-207 firmware support several packet flow types. For more details
about the supported packet flow types refer to the DDK Test Specification [3] and
Firmware Reference Manual [4].
Contents
The DDK provides a set of re-usable software components used to solve typical problems encountered by C-
Driver development. The DDK includes re-usable software components, EIP Driver Libraries that allows full
utilization of all EIP hardware features, along with extensive documentation for the provided SW
components and EIP Driver Libraries.
Note: The DDK is designed to reduce the required driver development effort, but cannot entirely
eliminate it.
Solutions are provided in the DDK in the form of:
• Re-usable driver architecture and design principles (see Driver Framework Porting Guide [1]);
• Re-usable APIs (see Driver Framework Porting Guide [1] and C header-files);
• Documentation with guidelines on how to implement the provided APIs in a customer-specific way, e.g.
guidelines for the customization effort (Porting guidelines and implementation notes);
• Re-usable SW components (C source code, user documentation):
• Re-usable software libraries (SA and Token Builders);
• Required EIP-197 Driver Library;
• Test Tool with tests formalized in ASCII-format sltf- and vp-files;
• Other re-usable SW modules;
• Example Drivers for demonstrating how to use various DDK software components for making
customized drivers specific to the EIP-197 hardware.
The EIP-197 Driver Library together with the SA and Token Builders are the most important software
components included in the DDK. The DDK targets driver development for this EIP HW block integrated in a
chip. The DDK does not include development tools such as C compiler, linker, debugger, profiler or IDE.
Driver Development Difficulties

This section lists typical difficulties that a device driver developer must address and how the DDK addresses
them. Some of these problems may be irrelevant, depending on the type of the device.
• Map driver API onto HW block SW interface so that high level SW application can utilize the
functionality implemented in the EIP HW block;
• Compatibility with native OS Driver Model and OS API so the driver can be used with that OS;
• Concurrent context synchronization (CCS), e.g. synchronizing access to resources (including EIP HW
block resources) shared between concurrent execution contexts such as threads and interrupts;
• Concurrent device synchronization (CDS), e.g. synchronizing access to resources shared between EIP
HW block and the host CPU;

007-197550-308
User Guide Rev. A
• EIP HW block control functionality for data I/O that includes all required operations on the EIP HW
block before it can start to input and output data, as well as operations related to data input and
output;
• Provide access to static resources such EIP HW ‘memory mapped’ I/O registers and internal memories
shared between host CPU and EIP HW block:
• Resolve endianness differences between the host CPU and the EIP HW block;
• Read and write static device resources via the appropriate hardware paths;
• Map static device resources into memory domain of the application requiring the EIP-197 Engine
services;
• Provide access to dynamic resources such as DMA buffers shared between host CPU and EIP HW block:
• Dynamic resource (buffer) allocation, buffer address and size alignment;
• Dynamic resource (buffer) address-translation when a system uses several types of addresses such
as virtual, logical, physical;
• Data-cache coherency management, when required;
• Interrupt dispatching and servicing across heterogeneous memory domains (from kernel- to user-
space);
• Compatibility with C compiler, its C Run-Time Library and basic type definitions.
The DDK provides a set of solutions for these problems in various forms as well as guidelines for integrating
these solutions in a device driver. Although the DDK attempts to solve these problems, driver development
remains a creative and challenging task requiring solid experience and skills in the field.
Other considerations:
The EIP-197 Engine contains a DMA engine. All the EIP HW blocks are Little Endian devices.
During the DDK verification
• Two different hosts were used for verification: Little Endian x86 PC and Little Endian ARMv7 on a Zynq
ZC706 FPGA board;
• The Linux OS with SLUB/SLAB as buffer allocator was used for DMA buffer allocation on both hosts;
• Different addresses were used to access the DMA buffers from the device (using DMA) and from the
host (from Linux kernel space as well as from user space), requiring proper address translation (kernel-
virtual / user-virtual to PCI bus);
• The used ARM HW platform required software-controlled data cache coherency for DMA buffers.
2.4.1 DDK Problem-Solution Map

The table below provides an overview of the typical driver development problems described earlier, with
solutions offered by the DDK.
Table 1 Typical driver development problems
Typical driver DDK Solution DDK Deliverables

development problem
Map driver API to HW block • PEC API • Driver API Specification as C header-files
SW interface • PCL API • Driver API Implementation Notes
• Driver API (PEC API, PCL API)
• SLAD PEC Test Tool with test cases and test vectors
in sltf- and vp-files for the PEC API
• PCL Test Tool for the PCL API
Compatibility with OS • Adapter • PEC and PCL Adapter C source code
Driver Model and OS API • Driver Framework • Driver Framework Device & DMA Resource API
implementation C source code

007-197550-308
User Guide Rev. A
Concurrent context • Adapter • PEC and PCL Adapter C source code

synchronization (CCS) • EIP-Driver Library User • EIP-197/-201 Driver Libraries C source code
Guides
Concurrent device EIP Driver Library • EIP-197/-201 Driver Libraries C source code
synchronization (CDS)
EIP HW block control EIP Driver Library • EIP-197/-201 Driver Libraries C source code
functionality for data I/O
Big Endian host vs. Little Driver Framework: • Driver Framework Porting guidelines
Endian HW block • Device API • Driver Framework Device & DMA Resource API
• DMA Resource API implementation in C source code.
Read and write static device Driver Framework: • Driver Framework Porting guidelines
resources • Device API • Driver Framework: Device API implementation C
source code
Dynamic resource • DMA Resource API • Driver Framework Porting Guide
allocation, address and size • DMABuf API • Driver Framework: DMA Resource API
alignment implementation C source code
• DMABuf Adapter C source code
Address translation for • DMA Resource API • Driver Framework Porting Guide
dynamic resource • Adapter • Driver Framework: DMA Resource API
implementation C source code
• PEC, PCL and DMABuf Adapter C source code
Data cache coherency Driver Framework: • Driver Framework Porting Guide
control • DMA Resource API • Driver Framework: DMA Resource API
(PreDMA / PostDMA) implementation C source code
Compatibility with C- Driver Framework: • Driver Framework Porting Guide
compiler, its Run-Time • C Run-Time API • Driver Framework C Run-Time API C header files
Library and basic types • Basic Types API and implementation C source code
• Driver Framework Basic Types API C header files
and implementation C source code
Static device resources UMDevXS • Kernel support driver and its user-space proxy
mapping into user-space implementation C source code
memory domain
Interrupt servicing in user- • Interrupt Dispatcher • Interrupt Dispatcher API and its user-space
space • Worker Thread implementation C source code
• Worker Thread API and its implementation C
source code
These DDK deliverables can be found in the DDK package after the installation, refer to Chapter 2.5.
The Adapter SW components as well as the Driver Framework APIs are implemented for the example driver
APIs (PEC API, PCL API and DMABuf API), hardware platform (x86 and ARM) and OS (Linux) used in the DDK
verification environment.
The same applies for the UMDevXS, Interrupt Dispatcher and Worker Thread SW components.
The EIP Driver Libraries are by design independent from the host HW and OS.

007-197550-308
User Guide Rev. A
DDK Installation
Unpack the DDK archive then run the install_ddk.sh script once.
Note: The EIP-207 firmware must be installed in the same directory where the DDK will be installed
before running the DDK installation script.
# tar -zxf Security-IP-197_DDK_vx.y.tar.gz

# cd Security-IP-197_DDK_vx.y
# ./install_ddk.sh
{INSTALL] Please check for availability of recent DDK patches!
[INSTALL] Installing the DDK packages

[INSTALL] Do you want to build the DDK components now [y/n]?
Y
...
[INSTALL] Installation completed successfully
#
This script will first ask whether the DDK packages must be built. If the question is answered with “y”, then
this script will prompt for the environment variables required to build the DDK and will build the Example
Drivers, SLAD Test Tool, PCL Test Tool, Demo Applications, SA Builder and Token Builder. Otherwise, the
script will just unpack and install all the software packages included in the DDK. This table shows folders
that are available after installation:
Table 2 DDK folders after installation
Folder name Folder content

Examples/Driver_KernelSupport • Kernel Support Driver including the user-space device access
(UMDevXS) and shared device access (SHDevXS) functionality
Examples/Driver • EIP-197 Example Combined Driver for the EIP-197 Engine
Examples/Driver_GlobalControl • EIP-197 Example Global Control Driver for the EIP-197 Engine
Examples/Driver_PEC • EIP-197 Example PEC Driver for the EIP-197 Engine
Examples/Driver_PEC_PCL • EIP-197 Example PEC-PCL Driver for the EIP-197 Engine
Examples/DemoApp_GlobalControl • Demo Application for the Global Control API, demonstrates
how to use this API
Examples/DemoApp_PEC • Demo Application for the PEC and DMABuf APIs. Demonstrates
how to use the PEC and DMABuf APIs as well as the SA Builder
and Token Builder APIs.
Examples/DemoApp_PEC_PCL • Demo Application for the PCL, PEC and DMABuf APIs.
Demonstrates how to use the PCL, PEC and DMABuf APIs as
well as the SA Builder and Token Builder APIs.
Examples/DemoApp_Eip74 • Demo Application to show how to validate the EIP-74 DRBG
using standard vectors.
TestTools/Regress_197 • Regression test system that runs Demo Applications and a
regression test set using the SLAD Test Tool and PEC PCL Test
Tool on the EIP-197 driver for a set of pre-defined
configurations. The provided regression scripts automate the
build process and the regression.
• Test Specification and Test Report for the PCL, PEC and
DMABuf APIs implementation in the EIP-197 driver
TestTools/TestTool_PEC_PCL • PCL Test Tool source code for the PCL, PEC and DMABuf APIs
TestTools/SLAD_TestTool • SLAD Test Tool source code for the PEC and DMABuf APIs
• Test vectors as sltf- and vp-files

007-197550-308
User Guide Rev. A
TestTools/TestSAToken • Test program for the SA Builder and Token Builder

TestTools/MemXS • Diagnostics tool that can be used to read and write the EIP-197
device registers. This tool can also be used to verify the
correctness of the Driver Framework Device API
implementation for user-space deployment (located in
Kit/DriverFramework/src/UMDevXS).
TestTools/RealTimeTraceTool • Test program for tracing packet processing in the EIP-197
Engine
Kit/DriverFramework • Driver Framework Porting Guide describing the general driver
architecture used in the EIP-197 driver and the specification of
the Driver Framework APIs.
Kit/EIP197 • EIP-197 Driver Library, contains Global Control, Flow Control
and Ring Control modules
• EIP-197 Driver Library User Guide
Kit/EIP74 • EIP-74 Driver Library for DRBG
Kit/Log • Logging API Specification as C header-files
• Example implementation of the API as used in the EIP-197
driver
Kit/List • Reusable linked list component
Kit/RingHelper • Ring Helper API as C header-files
• Ring Helper API implementation, a SW module managing the
ring-based EIP-202 Host Interface Adapter HW module, used
by the EIP-197 Driver Library.
Kit/EIP201 • EIP-201 Driver Library for AIC
• EIP-201 Driver Library User Guide
Kit/SABuilder • SA Builder API specification as C header files
• Implementation of the SA Builder for the EIP-96
• Implementation of the Extended SA Builder for the EIP-207
Kit/TokenBuilder • Token Builder API specification as C header files
• Implementation of the Token Builder for the EIP-96
Kit/IOToken • Standard IOToken API specification as C header files
• Implementation of the standard IOToken for the EIP-96
• Extended IOToken API specification as C header files
• Implementation for the Extended IOToken for the EIP-207
Firmware
Integration/SLAD_Adapter • Global, PEC, PCL and DMaBuf Adapter components that
integrate the DDK components (from the Kit folder) in one
driver, for Linux on x86 and RISC hosts.
• Global Control, PEC, PCL and DMABuf APIs specifications as C
header-files and implementation notes
Integration/DriverFramework/src • Generic Driver Framework implementation code (common to
all implementations)
Integration/DriverFramework/src/LKM • Device API implementation for PCI- attached devices for Linux
kernel-space x86 and RISC HW platforms.
• DMA Resource API implementation for Linux kernel-space x86
and RISC HW platforms.
Integration/DriverFramework/src/UMDevXS • Device API implementation for PCI- attached devices for Linux
user-space x86 and RISC HW platforms.
• DMA Resource API implementation for Linux user-space x86
and RISC HW platforms.

007-197550-308
User Guide Rev. A
Integration/SHDevXS • The SHDevXS part of the Linux Kernel Support Driver and its
user-space module that provides the shared EIP-197 device
access services to the Global Control, PEC and PEC-PCL Drivers.
This Kernel Support Driver functionality is used for the Linux
user-space and kernel-space deployments of the mentioned
above drivers.
Integration/UMDevXS • The UMDevXS part of the Linux Kernel Support Driver and its
user-space module that provides the required kernel services
to the EIP-197 user-space drivers. This Kernel Support Driver
functionality is mainly used for the Linux user-space driver
deployment. This part of the driver also provides support for
the SHDevXS part of the Kernel Support Driver and centralized
PCI device registration for all other drivers, except the
Combined driver.
Integration/InterruptDispatcher • A module that allows the user mode driver to work in interrupt
mode. This component is used for the Linux user-space
deployment of the EIP-197 driver only
Integration/WorkerThread • A module that allows the user mode driver to work in interrupt
mode; the interrupt handling code runs in a separate thread.
This component is used for the Linux user-space deployment
of the EIP-197 driver only.
Main Components Overview

The EIP-197 Driver is composed of components listed below. It can be built as a Linux kernel module and
needs to be loaded as a module in the Linux kernel. Alternatively, the Driver can be built as a Linux user-
space statically linkable library that can be linked with a Linux user-space application. A number of APIs,
which is collectively called SLAD API, as well as other APIs are public interfaces provided by the Driver.
Component Remarks
Examples/Driver/build Makefile to build the Combined Driver
Examples/Driver/docs Documentation, including this document
Examples/Driver_GlobalControl/build Makefile to build the Global Control Driver
Examples/Driver_PEC/build Makefile to build the PEC Driver
Examples/Driver_PEC_PCL/build Makefile to build the PEC-PCL Driver
Integration/SLAD_Adapter/src SLAD Adapter provides the implementation of the Driver API (SLAD API).
PCL Adapter provides the implementation of the PCL API.
Global Control Adapter provides the implementation of the Global Control
API.
Integration/SLAD_Adapter/incl/ API to initialize and de-initialize the Combined Driver. Please refer to
api_driver197_init.h included header file for details of the API.
Integration/SLAD_Adapter/incl/ API to initialize and de-initialize the PEC Driver. Please refer to included
api_driver197_pec_init.h header file for details of the API.
Integration/SLAD_Adapter/incl/ API to initialize and de-initialize the Global Control Driver. Please refer to
api_global_driver197_init.h included header file for details of the API.
Integration/SLAD_Adapter/incl/ API exposed by Driver to read the global status of the Packet Engine and to
api_global_status_eip97.h reseed the Pseudo Random Number Generator for IV generation. Part of the
Global Control API
Integration/SLAD_Adapter/incl API exposed by Driver to read the global status of the Packet Classification
api_global_status_eip207.h hardware. Part of the Global Control API.
Integration/SLAD_Adapter/incl/api_gl API exposed by Driver to control the Deterministic Random Bit Generator.
obal_eip74.h Part of the Global Control API.
Integration/SLAD_Adapter/incl/ SLAD PEC API exposed by Driver to use EIP-197 Packet Engine. Please refer
api_pec.h to included header file for details of the API.

007-197550-308
User Guide Rev. A
Integration/SLAD_Adapter/incl/ SLAD PEC SG API exposed by Driver to use EIP-197 Packet Engine in scatter-
api_pec_sg.h gather mode. Please refer to included header file for details of the API.
Integration/SLAD_Adapter/incl/ PCL API, exposed by the Driver to use the EIP-207 Packet Classification
api_pcl.h Engine. Please refer to the included header file for details of the API.
Integration/SLAD_Adapter/incl/ DMABuf API for allocating and freeing DMA buffers. Used by the Driver.
api_dmabuf.h Please refer to the included header file for details.
Integration/SLAD_Adapter/incl/ MemXS API for accessing the internal EIP HW registers and memory, mostly
api_memxs.h designed for use from test tools.
The Driver depends on several other software components, which are included in the Kit directory (see [5])
for a diagram showing these components):
• The RingHelper component for ring buffer management;
• The Log component for outputting informational messages;
• The List component for managing linked lists.
• The EIP-197 Driver Library, for low level access to the Security-IP-197 Engine. This library contains the
Global Control (EIP-197, EIP-207 and EIP-202), Flow Control (EIP-207) and Ring Control (EIP-202)
functionality;
• The EIP-74 Driver Library, for low level access to the EIP-74 Deterministic Random Bit Generator;
• The EIP-201 Driver Library, for low level access to the EIP-201 Advanced Interrupt Controller;
• The IOToken component for creating input and parsing output tokens for the Security-IP-197 Engine;
• The Driver Framework.
Further, the Driver depends on the following software components under the Integration directory:
• The Driver Framework implementation, consisting of a generic part and several parts that depend on
the driver deployment.
In addition, the Driver uses several more software components when it is deployed in the Linux user space
and is accessed by user mode applications. These are included from the Integration directory.
• Linux_UMDevXS (Kernel Support Driver for the user-space device access with its user-space
component), which provides the required Linux kernel services to the Combined Driver deployed in the
user-space.
• KernelSupport_EIP197 (Kernel Support Driver for the shared device access with its user-space
component), which provides the shared devices access to the Global Control Driver, PEC Driver and the
PEC-PCL Driver both in the user-space and in the kernel-space.
• The InterruptDispatcher and WorkerThread components that implement the interrupt dispatching
functionality for the EIP-197 Driver in the Linux user space.
Finally, the Driver depends on the EIP-197 Firmware package, which is not supplied as part of the Driver but
is supplied separately. The firmware package contains both a set of APIs that define firmware-dependent
data structures (e.g. for flow and transform records) and an image of the firmware that is to downloaded by
the driver from a file and that will subsequently be written into the EIP-197.

007-197550-308
User Guide Rev. A
3 Driver Customization Instructions

This chapter describes several important customization areas in the EIP-197 Driver. The EIP-197 Driver is
delivered as an Example Driver that must be customized for a host chip or chipset with the integrated EIP-
197 hardware. Such customization may include the implementation of interrupt functionality specific to the
chip and customization of the Driver Framework implementation specific to the chip. For more information
refer to the Driver Framework Porting Guide [1].
The EIP-197 Driver is delivered with example code either for the Xilinx VCU118 platform with PCI-Express or
for Xilinx Zynq ZC706 Cortex-A9 FPGA platform or the ARMv8 V2M Juno FPGA platform programmed with
the EIP-197 logic. The VCU118 FPGA platform has been used with the x86 host for this Example Driver
verification. The Zynq ZC706 FPGA platform has an ARM CPU running Linux with the packet engine directly
attached to the AXI system bus. The V2M Juno FPGA platform has an AMv8 CPU running 64-bit Linux with
the packet engine directly attached to the AXI system bus.
The following sections describe how such customization work can be done in these areas.
Interrupt Functionality Customization

The EIP-197 Engine contains several internal EIP-201 Advanced Interrupt Controllers: one global interrupt
controller and one for each ring manager. Depending on the hardware integration of the EIP-197, there may
be either a single external interrupt output (from the Global AIC) or multiple external interrupt outputs
(from the Global AIC and from each of the four Ring AICs). External interrupt outputs must be connected to
the System Interrupt Controller (SIC). The outputs of the Ring AICs are internally connected as inputs to the
Global AIC and are also provided as external interrupt signals. This way it is always possible to configure the
driver to use a single external interrupt from the Global AIC output only. The provided Example Driver uses
registers of the (several instances of) the AIC to check for individual interrupt sources and to selectively
enable or disable them.
Notes: The Xilinx VCU118 FPGA platform with PCIe provides MSI interrupts from the Global AIC only and
ring AICs. The Linux Driver (and kernel) are configured to use the MSI interrupts for this FPGA
board, but the current version uses a single global AIC interrupt only.
Notes: For the Xilinx Zynq ZC706 board the Linux kernel device tree (zynq-zc706.dts) file must be modified
to include a record describing the packet engine resources including the interrupt assignment. Refer
to section 3.5.1 for an example device tree for the packet engine. It contains dedicated interrupt
outputs for the Global AIC and each of the four ring AICs.
Notes: For the V2M Juno board the Linux kernel device tree (juno.dts) file must be modified to include a
record describing the packet engine resources including the interrupt assignment. Refer to section
3.5.1 for an example device tree for the packet engine. It contains a single interrupt output for Ring
AIC 0.
For other hardware platforms, the interrupt handling code must be customized with the relevant code to
access the SIC, either directly or indirectly by accessing high level kernel functions. At the very least this
code must be customized to select the correct interrupt line on the SIC or the correct interrupt number in
the kernel. Most of the SLAD adapter interrupt handling code can be used unchanged on all Linux platforms.
The SLAD Adapter uses the Security-IP-197 Driver Library API (see Security-IP-197 Driver Library User Guide
[6] for details) in the interrupt handling module for masking the interrupts at the EIP-197 internal interrupt
controllers.

007-197550-308
User Guide Rev. A
The EIP-197 Driver interrupt handling code can be found in these files:
• Interface:
Integration/SLAD_Adapter/src/adapter_interrupts.h
• Example implementation for Combined Driver:
• Kernel Space Deployment
Integration/SLAD_Adapter/src/lkm/adapter_interrupts.c
• User Space Deployment
Integration/InterruptDispatcher/src/UMDevXS/$HOST_HW_PLATFORM/intdispatch_umdevx
s.c
Integration/WorkerThread/src/workerthread_linuxusermode.cIntegration/SLAD_Adapte
r/src/um/adapter_intdispatch.c
• Example implementation for PEC Driver both kernel and user space deployment:
Integration/SLAD_Adapter/src/adapter_int_shdevxs.c
Example implementation for Kernel Support Driver:
• Kernel-space part
Integration/SHDevXS/KernelPart/src/shdevxs_irq.cIntegration/SLAD_Adapter/src/lkm
/adapter_interrupts.c
• User-space proxy
Integration/WorkerThread/src/workerthread_linuxusermode.cIntegration/SHDevXS/Use
rPart/src/shdevxs_irq.c
For the architecture, functional decomposition and design principles of the Driver and SLAD Adapter
module, refer to the Driver Framework Porting Guide [1]and the Security-IP-197 Driver Software Block
Diagram [5].
Several guidelines are provided below for the driver interrupt functionality customization for Symmetric
Multi-Processor (SMP) and Asymmetric Multi-Processor (AMP) use cases.
3.1.1 AMP use case

If multiple CPU's must be used independently (this means each CPU has its own independent OS) then each
CPU performing the packet I/O using a separate EIP-197 ring interface must have a dedicated IRQ to the
respective EIP-197 RDR descriptor done interrupt. However, in this use case only one Global Control Driver
must be used that will run on a CPU that has access to the entire EIP-197 register set (master CPU), and one
instance of the PEC Driver for each CPU doing packet I/O (Ring CPU). Each PEC Driver on each Ring CPU
would use its own ISR installed via the adapter_interrupts.c:Adapter_Interrupts_Init() function for
a dedicated Ring IRQ routed from the respective EIP-197 ring_irq signal to their system Interrupt
Controller (SIC).
Note: The Combined Driver cannot be used for the AMP use case.
3.1.2 SMP use case

If all the CPU's are used as one processor pool under control of a single OS then there are two options.
Either use the Combined (combines the Global Control and the PEC drivers in one) Driver, or still use
separate Global Control and PEC Drivers. Note that the Global Control Driver does not use interrupts.
Independent of which driver option is chosen the RDR descriptor done interrupt handling would be the
same.
It is possible to connect just the global EIP-197 out_irq signal to the SIC similar to the way it is
implemented for the Xilinx VCU118 and Zynq ZC706 FPGA boards. Alternatively, it is possible to connect
each EIP-197 ring_irq signal to a dedicated Ring IRQ in their SIC. In the latter case it is necessary to install a
dedicated ISR for each Ring IRQ for the SIC via the adapter_interrupts.c:Adapter_Interrupts_Init()
function. The Example Driver interrupt handling functionality would need to be customized for this,
however.

007-197550-308
User Guide Rev. A
3.1.3 Customizing combined driver

The Combined Driver (Examples/Driver/build) always uses a single external interrupt. If Ring AIC outputs
are available as external interrupt signals, this is usually the output of the Ring0 AIC, otherwise it is the
output of the Global AIC. A different external interrupt can be selected though. To configure the Combined
Driver for use with a different AIC, take the following steps:
• In cs_hwpal_ext.h, change HWPAL_PLATFORM_IRQ_IDX to a different value, for instance to 2 when
using EIP201_RING1 or to 0 when using EIP201_GLOBAL.
• In Examples/Driver_KernelSupport/UMDevXS/build/FPGA_Zynq_ZC706/cs_umdevxs_ext.h,
change UMDEVXS_PLATFORM_IRQ_IDX to the same value. This specifies the IRQ that will be used by the
UMDevXS driver.
• When selecting the Global AIC, comment out the definition of DRIVER_AIC_SEPARATE_IRQ in
cs_driver_ext.h. This will select a different set of definitions for ADAPTER_AICS and ADAPTER_IRQS in
cs_adapter_ext.h.
• When selecting a different Ring AIC, change the definition of ADAPTER_AICS in cs_adapter_ext.h to
contain a different AIC, which has to have a real IRQ output (flag set to ‘1’).
• When selecting a different Ring AIC, change the definition of ADAPTER_IRQS in cs_adapter_ext.h to
refer to the changed Ring AIC.
By default, the Combined Driver is configured to use the maximum number of ring pairs supported by the
hardware: It is possible to configure the Combined Driver for use with a different number of ring pairs, for
instance one ring pair. To do this, take the following steps:
• In cs_driver_ext2.h, set DRIVER_MAX_NOF_RING_TO_USE to the desired value and precede it with
#undef DRIVER_MAX_NOF_RING_TO_USE to remove the default definition as passed by the make file.
3.1.4 Customizing separate drivers

The separate drivers for multiple application support (Kernel Support Driver, Global Control Driver, PEC and
PEC_PCL Driver) are configured to use four rings and to take advantage of multiple external interrupts on
hardware platforms that support them.
The high-level configuration parameter DRIVER_AIC_SEPARATE_IRQ in cs_driver_ext.h selects one set of
ADAPTER_AICS and ADAPTER_IRQS in cs_adapter_ext.h. The configurations for the Kernel Support Driver
(Examples/KernelSupport/SHDevXS/build), the PEC Driver (Examples/Driver_PEC/build) and the PEC
PCL Driver (Examples/Driver_PEC_PCL/build) must agree. The number of AIC devices must be specified
correctly in the UMDEVXS_INTERRUPT_IC_DEVICE_COUNT definition in cs_umdevxs_ext.h for the Kernel
Support Driver.
The definitions of ADAPTER_AICS and ADAPTER_IRQS can be customized directly. All ring IRQs of all four
rings can be used on each of the four ring AICs. In the current configuration, IRQ_CDR0/IRQ_RDR0 are
connected to EIP201_RING0, IRQ_CDR1/IRQ_RDR1 are connected to EIP201_RING1 and so on, but this can
be configured differently.

007-197550-308
User Guide Rev. A
Driver Framework Customization

The Driver Framework implementation module implements the Device API (see also the Driver Framework
Porting Guide [1] for details) such as register and internal memory read and write functions specific to the
host chip hardware with the integrated EIP-197 hardware. This component also implements the
DMAResource API.
The Driver Framework component contains an example code for the EIP-197 hardware access via the PCI (or
PCI-Express) bus implemented for the Xilinx VCU118 FPGA platform. The Driver Framework component
contains an example code for the EIP-197 hardware access via the Linux OpenFirmware API for the
situations when the EIP-197 Engine is directly attached to the system bus which is the case for the Zynq
ZC706 FPGA platform. The bus attachment type of the EIP-197 Engine determines the implementation of
the Driver Framework Device API, but not the DMAResource API.
If the EIP-197 hardware is integrated in a host chip with different bus architecture, or the Linux kernel
interfaces to the bus in a different way, then this implementation must be customized.
• Interface:
Kit/DriverFramework/Device_API/incl
Kit/DriverFramework/DMAResource_API/incl
• Example implementation:
• Generic code (common to all driver deployments)
• Integration/DriverFramework/src/dmares_gen.c
• Integration/DriverFramework/src/dmares_hwpal.h
• Configuration file can be found here
 Examples/Driver(_PEC,_PEC_PCL,_GlobalControl)/build/cs_hwpal_lkm.h
• FPGA board specific configuration file can be found here
 Examples/Driver(_PEC,
_PEC_PCL,_GlobalControl)/build/$HOST_HW_PLATFORM/cs_hwpal_ext.h
• Kernel-space Driver deployment
• Integration/DriverFramework/src/LKM/dmares_lkm.c
• For PCI-attached EIP devices
 Integration/DriverFramework/src/LKM/PCI/device_lkm.c
 Integration/DriverFramework/src/LKM/PCI/lkm.c
• For directly bus-attached EIP devices
 Integration/DriverFramework/src/LKM/OF/device_lkm.c
 Integration/DriverFramework/src/LKM/OF/lkm.c
• User-space Driver deployment
• Integration/DriverFramework/src/UMDevXS/hwpal_dmares_umdevxs.c
• Integration/DriverFramework/src/UMDevXS/hwpal_device_umdevxs.c
• Driver Framework configuration file can be found here
 Examples/Driver(_PEC, _PEC_PCL,_GlobalControl)/build/cs_hwpal_umdevxs.h
• Integration/UMDevXS/UserPart/src/umdevxsproxy.c
• Integration/UMDevXS/KernelPart/src/umdevxs_*.c
• Kernel Support Driver configuration file can be found here
 General configuration file can be found here
 Examples/Driver_KernelSupport/UMDevXS/build/cs_umdevxs.h
 FPGA board specific configuration file can be found here
 Examples/Driver_KernelSupport/UMDevXS/build/$HOST_HW_PLATFORM/cs_umdev
xs_ext.h

007-197550-308
User Guide Rev. A
3.2.1 DMA-safe buffer allocation for kernel-space drivers

The kernel-space Driver Framework DMAResource API implementation can be configured for allocating
DMA-safe buffers either in non-cached (via defining HWPAL_DMARESOURCE_ALLOC_CACHE_COHERENT) or in
cached memory. In the latter case the functionality can be further tuned via the
HWPAL_DMARESOURCE_MINIMUM_CACHE_CONTROL configuration parameter. This driver functionality relies on
the correct Linux kernel DMA API implementation for the used platform.
Note: The HWPAL_DMARESOURCE_ALLOC_CACHE_COHERENT and
HWPAL_DMARESOURCE_MINIMUM_CACHE_CONTROL configuration parameters cannot be used on
some platforms.
Firmware download
The Security-IP-197 contains several programmable engines, each of which requires firmware to run. These
firmware images are provided by the Firmware package and they are normally stored in binary files, which
are loaded by the driver when it is loaded.
The SLAD Adapter contains the firmware download API in the file
Integration/SLAD_Adapter/src/adapter_firmware.h. An implementation of this API receives an image
name as input and it has to provide a reference to the firmware image in an array of 32-bit words as output.
The image name is a null-terminated string and it is typically a file name.
There are two implementations of the firmware download API:
• For kernel space deployment, the implementation is in
Integration/SLAD_Adapter/src/lkm/adapter_firmware.c. It uses the Linux kernel firmware
download API to retrieve files stored under /lib/firmware.
• For user space deployment, the implementation is in
Integration/SLAD_Adapter/src/um/adapter_firmware.c. It uses the standard C library to load files
into memory. These files are stored under /lib/firmware by default, but the patch name can be
configured at compile time via the ADAPTER_FIRMWARE_PATH_PREFIX parameter.
Alternatively, it is possible to create a custom implementation of this API that does not require a file system.
The firmware package contains each of the required firmware images in the form of a C file containing an
initialized array. These C files can be linked into the driver. A customized implementation of the firmware
download API must select a reference to the correct array, depending on the supplied image name.
Kernel Support Driver

The Kernel Support Driver (UMDevXS API only) is required for the Linux user-space deployment of the EIP-
197 Combined Driver. This driver set can be used for the uni-processor and symmetric multi-processor
kernel configuration.
The Kernel Support Driver (both UMDevXS and SHDevXS APIs) is required for both user-space and kernel-
space deployment of the Global Control and PEC Driver. The Kernel Support Driver is not required for OSes,
which do not have kernel-user-space separation. This driver set can be used for the asymmetric multi-
processor kernel configuration, but it also can be used for the uni-processor and symmetric multi-processor
kernel configuration.
The Kernel Support Driver implementation for user-space device access (UMDevXS):
Kernel modules
Integration/UMDevXS/KernelPart/src
User-space Proxy
Integration/UMDevXS/UserPart/src
The Kernel Support Driver implementation for shared device access (SHDevXS):

007-197550-308
User Guide Rev. A
Kernel module
Integration/SHDevXS/KernelPart/src
User-space Proxy
Integration/SHDevXS/UserPart/src
Kernel Support Driver UMDevXS configuration files can be found here:

• General configuration file
• Examples/Driver_KernelSupport/UMDevXS/build/cs_umdevxs.h
• FPGA board specific configuration file
• Examples/Driver_KernelSupport/UMDevXS/build/$HOST_HW_PLATFORM/cs_umdevxs_ext.h
Kernel Support Driver SHDevXS (also UMDevXS) configuration files can be found here:
General configuration file
• Examples/Driver_KernelSupport/SHDevXS/build/cs_*.h
• FPGA board specific configuration file
• Examples/Driver_KernelSupport/SHDevXS/build/$HOST_HW_PLATFORM/cs_*.h
3.4.1 DMA-safe buffer allocation for user-space drivers

The Kernel Support Driver supports allocation of DMA-safe buffers and mapping them to the user space via
its UMDevXS SMBuf API. For the x86 and arm/arm64 host CPU’s the DMA buffers will be mapped to the
user space as non-cached. For PowerPC/PowerPC64 host CPU’s the DMA buffers will be mapped to the user
space as cached. See also section 3.5.2.
Kernel Support Driver UMDevXS SMBuf implementation can be found here:

• Integration/UMDevXS/KernelPart/src/umdevxs_smbuf.c
3.4.2 Shared device access protection for multiple applications

When concurrent applications access the EIP-197 hardware registers and memories it can happen that the
same register is accessed concurrently from different applications. The SHDevXS API implementation
provides synchronization mechanisms to prevent race conditions for concurrent EIP hardware access.
Moreover, this API allows only one privileged application, such as Global Control Application using the
Global Control Driver, that can access all the EIP-197 hardware. This is required for the EIP hardware
initialization and status monitoring. The Kernel Support Driver will ensure that the user-space PEC
applications do not use overlapping EIP-197 hardware registers. Such an overlap is, however allowed for the
Global Control Application and a user-space PEC application. This protection mechanism is yet to be
implemented for the kernel-space PEC applications.
Customization for ARM platform

This section contains guidelines for the driver customization for an ARM platform.
3.5.1 Device registration in Linux kernel

In case the Security-IP-197 Engine is integrated in a platform as a non-PCI device then it will need to be
made known to the Linux kernel. One method would be to use the Linux kernel
platform_device_register() function. This function takes as an argument a pointer to the device data
structure that describes the device’s resources such as memory-mapped I/O, interrupts, device name.
For example, the Zynq ZC706 Cortex-A9 FPGA platform was used for the driver verification. The Linux kernel
platform-specific code can be found in the arch/arm/mach-zynq folder. These files can be customized in
order to register the Security-IP-197 Engine with the Linux kernel so that the kernel driver can probe the

007-197550-308
User Guide Rev. A
device for its resources. The driver will have to register itself in the kernel using the kernel
platform_driver_register() function using the same device name as used in the device resource data
structure while registering the device.
An alternative method would be to use the Linux kernel Device Tree Structure file in the
arch/arm/boot/dts folder where a new record for the Security-IP-197 Engine could be added. Refer to the
Linux kernel documentation for details about the device tree structure files. The driver can use the Linux
kernel OpenFirmware API (exported under GPL) to read the registered device resources, such as its register
mapping and interrupt assignments. An example of such device record in the zynq-zc706.dts device tree
file is provided below. Refer to [8]for the entire file example.
ps7_pe: eip-197@40000000 {
#address-cells = <1>;
#size-cells = <1>;
compatible = "security-ip-197-srv";
interrupt-parent = <&ps7_scugic_0>;
interrupts = <0 29 0>, <0 30 0>, <0 31 0>, <0 32 0>, <0 33 0>;
reg = <0x40000000 0x100000>;
} ;
Note: The Security-IP-197 Engine interrupt numbers will be increased by 32, so in this example 29 + 32
gives the IRQ number 61, that will be assigned for the Engine at the system’s interrupt controller.
3.5.2 DMA buffers allocation and mapping to user space

On recent ARM designs multiple memory page mappings with different attributes (for example, cached or
non-cached) can cause system issues such as memory corruption. These mappings are used by the EIP-197
Engine for the user-space deployment where the DMA buffers must be accessible directly to the user-space
application and the EIP-197 Engine. In order to avoid conflicting memory mappings for the DMA buffers the
DMA memory in the kernel is allocated by means of the kernel DMA API dma_alloc_coherent() function
before mapping this memory to the user-space as non-cached via the remap_pfn_range() function. See
umdevxs_smbuf.c file for details. This workaround can be enabled via the
UMDEVXS_SMBUF_UNCACHED_MAPPING and UMDEVXS_SMBUF_CACHE_COHERENT configuration parameters in
the Kernel Support Driver and it is required for the user-space deployment only. For the kernel-space
deployment, the standard cacheable DMA buffer allocation can be used.

007-197550-308
User Guide Rev. A
4 Driver Deployments
The EIP-197 Driver can be deployed in two different ways:
• Both the Driver and the application using it run in the Linux kernel space.
• Both the Driver and the application using it run in the Linux user space.
The software block diagrams below show how various DDK components are used in case of the kernel-space
and user-space EIP-197 driver deployment. The following notation is used in these diagrams
DDK Kit Component DDK Integration Component
EIP-197 Combined Driver User-Space Deployment

Linux user space
Classification Test Tool Executable

SLAD Test Tool Parser
PCL Test Tool (sltf-files and vp-files)
EIP-197 Combined Driver Kernel-Space Deployment Token Ext. SA
Builder Builder SLAD PEC Test Tool
Linux user space
SLAD Test Tool Parser
Executable EIP-197 Combined Driver Static User Library (.a)
(sltf-files and vp-files)
Global Adapter PCL Adapter PEC Adapter
Linux kernel space

EIP-201 EIP-74 EIP-197
IOToken
Drv Lib Drv Lib Drv Lib
PCL Test Tool (.ko)
Token Ext. SA SLAD PEC Test Tool (.ko)

Driver Framework User EIP-207
Builder Builder
(uses /dev character device driver interface) Firmware
EIP-197 Combined Driver (.ko) Interrupt

Log User List Ring Helper
Dispatcher
Worker
Thread
EIP-201 EIP-74 EIP-197
IOToken
EIP-207
Driver Framework Kernel
Firmware Linux kernel space
Log Kernel List Ring Helper

Kernel Support Driver (UMDevXS only)
(implements /dev character device driver interface)
Figure 1 EIP-197 Driver Kernel-Space and User-Space Deployments
The Classification (PCL) Test Tool can be used for the verification of all packet flows and the following APIs
• Global Control API,
• Classification (PCL) API,
• SLAD PEC API,
• SLAD DMABuf API,
• SA Builder API,
• Token Builder API and
• IOToken API.
This Classification Test tool can be deployed in the kernel-space as well as in the user-space. The same is
true for the Demo Applications. The Classification Test Tool will not use the Token Builder API and PCL API
all in the same test, but will use only some of these APIs in any given test, depending on the packet flow.
The SLAD Test Tool verifies the packet flows that do not require classification and the following APIs

007-197550-308
User Guide Rev. A
• Global Control API,

• SLAD PEC API,
• SLAD DMABuf API,
• IOToken API.
Note that although the SA Builder API and the Token Builder API are normally used for the packet flows
tested, these two APIs are not used by the SLAD Test Tool, because the SLAD Test Tool uses pre-made SA
and Token data structures. These APIs are used, however, by the Demo Application for the PEC API.
MemXS & Driver Framework User-Space Deployment

Linux user space
MemXS Executable
MemXS
Driver Framework Static User Library (.a)
Driver Framework User

(uses /dev character device driver interface)
Log User
Linux kernel space
Kernel Support Driver (UMDevXS only)

Figure 2 MemXS and Driver Framework user-space deployment

There can be only one Combined Driver deployment active at a time, e.g. either kernel-space driver or user-
space driver, and the Combined Driver cannot be used concurrently with Global Control Driver, PEC-PCL
Driver or PEC Driver. The Combined Driver must be used together with the Kernel Support Driver (only
UMDevXS functionality) for the user-space deployment and without it for the kernel-space deployment. The
Combined Driver can support only one application at a time, e.g. either the SLAD Test Tool with the built-in
EIP-197 Example Combined Driver (user-space driver deployment) or the MemXS Tool. The MemXS Tool
does not use the entire EIP-197 Example Driver but only the Driver Framework implementation for the user
space.
Kernel-space Driver
The kernel Driver is a Linux kernel module (driver_197_k.ko) that exports all functions of the Driver
Initialization API, the SLAD PEC API, the PCL API, the Global Control API and the SLAD DMABuf API to other
kernel modules. An application can be built as a kernel module and if it is loaded after the Driver, it can use
these APIs exported by the Driver

007-197550-308
User Guide Rev. A
User-space Driver
The EIP-197 Driver can be compiled as a Linux user-space statically linkable library instead of a kernel
module. In this case, the user-space applications must link with libdriver_197_u.a and with the standard
pthread library. In this deployment, the Driver provides the same APIs as in the kernel-spacer deployment.
Three additional components from the Integration directory are required to build the user-space Driver:
1. WorkerThread: component that manages a separate thread for interrupt handling.
2. InterruptDispatcher: component that delivers hardware interrupts to the user-space.
3. Linux_UMDevXS: support kernel Driver that provides the required Linux kernel services to the user
space. The user-space part of this support Driver umdevxs_proxy.o is part of the user-space EIP-197
Example Driver.
The user-space EIP-197 Driver requires the support kernel Driver that can be found in the
Integration/Linux_UMDevXS directory. This support kernel Driver can be built as the umpci_k.ko module
for PCI and as the umdevxs_k.ko module for non-PCI. It requires a suitable character device node (for
example, /dev/umpci_c for PCI and /dev/umdevxs_c for non-PCI), which can be created as follows:
$ mknod /dev/umpci_c c 254 0

or
$ mknod /dev/umdevxs_c c 254 0
Check the /proc/devices file to find the correct major device number for this device.

007-197550-308
User Guide Rev. A
5 Packet Flows
The EIP-197 hardware can process packets in many different ways and the supported set of operations is
largely determined by the internal firmware. Most types of operations require the use of external software
running on the host, e.g. the SA and Token Builder. Different types of operation usually require the use of
different driver APIs and different external software components.
A set of packet operations that interacts with the Packet Engine in a specific way is called a Packet
Processing Flow. The EIP-197 Driver supports different packet flows. Three characteristics of a packet flow
are directly relevant to the EIP-197 Driver:
• The interface on which packet I/O is performed. This can either be the Ring Interface (called look-aside
operation) or a dedicated FIFO interface (called inline operation). The EIP-197 Driver supports packet
I/O for look-aside operation only, any packet I/O for inline packet flows is outside the scope of the
Driver. However, the Global Control and Classification Drivers can still be used for inline packet flows.
For look-aside operation, the application supplies (DMABuf handles) of the source and destination
buffers of each packet, possibly along with references to SA and Token data structures.
• Whether EIP-96 instruction token building is offloaded to the firmware. If this is the case, the
application does not need to supply a Packet Token Data structure for each packet.
• Whether the classification hardware is used. If this use case, the host installs one or more transforms
and flows. The hardware will classify each packet and then it will automatically perform the required
transform. The token for the packet processing by the EIP-96 Packet Engine will be constructed by the
firmware running inside the EIP-197 hardware. Therefore, token building is always offloaded when
classification is used. If classification is not used, the application must supply the correct SA pointer for
each packet.
Packets for different packet flows can be combined in a single application. A driver that contains all the
required APIs for one packet flow, can also be used for any other packet flow that requires a subset of these
APIs. However, the application must take care to use the APIs in the correct way for each packet flow. An
application may not use an SA intended for non-classification use in a packet flow with classification.
Neither may it use a hardware transform intended for a packet flow with classification in a packet flow
without classification. For each packet, the application must use the PEC API consistently with the intended
packet flow.
The IOToken API should be used by applications to provide additional information for a specific packet flow,
such as flow type, address of the transform record (SA) and receive information required for the packet
header post-processing. Also, other information specific for a packet flow can be exchanged between
applications and the EIP-207 firmware, if present, via the extended IOToken API.
Note: The Driver for its internal purposes uses the standard IOToken API only and does not use its
extension. Applications can use both the standard as well as the extended IOToken API.
Packet flows without classification and without token building offload.

In these packet flows, the application determines for every single packet exactly how it must be processed.
It does this by supplying (DMABuf handles of) both an SA data structure and a Packet Token data structure.
• For these packet flows, the PCL API is never used.
• For these packet flows, each PEC Command descriptor contains both a valid SA handle and a valid EIP-
96 Token handle.
• The SA buffers that are to be used with these packet flows must be registered before use with the
PEC_SA_Register() function and must be de-registered after use with the PEC_SA_UnRegister()
function.

007-197550-308
User Guide Rev. A
Packet flows without classification and with token building offload.

In these packet flows, the application determines for every single packet how it must be processed (which
SA to use), but the application offloads the creation of a Packet Token data structure to the firmware. The
application does supply the DMABuf handle for the SA data structure, but it does not supply a Packet Token
data structure.
• For these packet flows, the PCL API is never used.
• For these packet flows, each PEC Command descriptor contains a valid SA handle, but no EIP-96 Token
handle.
• The SA buffers that are to be used with these packet flows must be registered before use with the
PEC_SA_Register() function and must be de-registered after use with the PEC_SA_UnRegister()
function. SA records must be generated with a properly configured version of the SA Builder (Extended
SA Builder), as the SA records must contain additional information to direct processing by the firmware.
• In these packet flows, packet tokens are generated internally by the firmware running on the
Classification Engine and they are never visible to the Driver or to the application.
Packet flows with classification and with token building offload.

In these packet flows, the packet classification hardware determines how each packet must be handled. The
Application prepares several hardware transform records and registers them via the PCL API. Next, the
application prepares several flow records and adds them (again using the PCL API) to the flow table.
Alternatively, the transform records can be added to the lookup table via Direct Transform Lookup using the
PCL DTL API. The hardware can now look-up each packet in the flow table and handle it automatically.
• For these packet flows, the PEC_SA_Register() and PEC_SA_UnRegister() functions are not used.
Use PCL_Transform_Register() and PCL_Transform_UnRegister() instead. We refer to the
registered records as Transform records instead of SA records. A specially configured version of the SA
Builder (called the Extended SA Builder) can be used to generate them as the Transform records must
contain additional information to direct processing by the firmware.
• For these packet flows, each PEC command descriptor contains a null handle for both the SA and the
EIP-96 Token. The EIP-96 Token length is also set to zero. As a special case, the SA Handle field may
contain the DMABuf handle of a flow record or an SA record. In that specific case, the firmware will not
perform classification for that specific packet.
• For any packet to be handled successfully in these packet flows, a flow record or a DTL entry must exist
that matches the packet. In a real-world situation where IP packets with unpredictable addresses or
port numbers will typically be received, some packets are expected to fail lookup (as is reported in the
status). The application is expected to determine how these packets must be processed (according to
the IPsec policy) and to create new flow records or DTL entries for them and then to re-submit those
packets.
• In these packet flows, packet tokens are generated internally by the firmware running on the
Classification Engine and they are never visible to the Driver or to the application.

007-197550-308
User Guide Rev. A
6 Application Support
The application is defined as a separate memory domain such as a Linux user-space process or the entire
Linux kernel space. The EIP-197 Driver functionality can be built to support a single application for any of the
packet flows. The Driver can also be built to support multiple applications for packet flows without
classification with one application supporting a packet flow with classification. The Driver can support only
one application for with classification at a time. The table below gives an overview of the Driver build
options and the support APIs.
Driver Build Supported API Supported Supported

Option Packet Flow Deployment
Driver Combined • Driver Combined Init API All • User-space
• Global Control API • Kernel-space
• SLAD PEC API
• SLAD DMABuf API
• PCL API
• IOToken API
Driver • Driver Global Control Init API All • User-space
Global Control • Global Control API • Kernel-space
Driver • Driver PEC Init API All not requiring • User-space
PEC • SLAD PEC API classification. • Kernel-space
• SLAD DMABuf API
• IOToken API
Driver • Driver PEC-PCL Init API All • User-space
PEC-PCL • SLAD PEC API • Kernel-space
• SLAD DMABuf API
• PCL API
• IOToken API
Note that the Combined Driver cannot be used together with any of the other Drivers from this table.
Single Application Support

If only one application requires the Security-IP-197 Engine services then the simplest solution is to use the
Combined Driver. Refer to the table above for details about the supported APIs.
If the application runs in the user-space then the Kernel Support Driver must be deployed next to the
Combined Driver. In this case, the Combined Driver is statically linked with the application and the Kernel
Support Driver runs as a kernel module. In order to support the Combined Driver the Kernel Support Driver
must be built using the Makefile in the Examples/Driver_KernelSupport/UMDevXS/build directory. It can
be convenient to use the Combined Driver in the user-space deployment for application development and
debugging, for example, and later switch over to the kernel-space deployment for the final deployment in
the real system.
If the application runs in the kernel-space then the Kernel Support Driver is not required.

007-197550-308
User Guide Rev. A
Multiple Application Support

For the multiple application support, the Combined Driver must not be used and the Global Control Driver,
PEC Driver and /or PEC-PCL Driver must be used instead. The Global Control Driver as well as the PEC-PCL
Driver can be instantiated only once. The PEC Driver can be instantiated once in the kernel-space and per
user-space application.
Some Global Control applications must be used to control the global Security-IP-197 Engine settings and
read the status information via the Global Control API. The Demo Application Global Control can be used as
a starting point, for example. The application requiring the packet transformation offload to the Security-IP-
197 Engine must use the PEC Driver. The application that needs to offload to the Security-IP-197 Engine not
only the packet transformation but also the packet classification functionality must use the PEC-PCL Driver.
Both types of applications can be used at the same time.
It is also possible to use the Global Control Driver, PEC Driver and/or the PEC-PCL Driver for a single
application instead of the Combined Driver. The Global Control Driver must be loaded first. Note that the
PEC-PCL Driver is required for packet flows that require packet classification support. For packet flows that
do not use packet classification, the PEC Driver is sufficient with the Global Control Driver. The Kernel
Support Driver must be deployed with these drivers for both user-space and kernel-space and it must be
built in the Examples/Driver_KernelSupport/SHDevXS/build directory.
This DDK provides solutions for supporting multiple concurrent applications. There can be only one
application accessing the EIP-197 packet classification hardware at a time. This application can be
concurrent with one application also accessing the EIP-197 hardware, but without using classification. This
also applies to the PCL Test Tool and SLAD PEC Test Tool and they can be running concurrently. This DDK
supports multiple concurrent driver deployments, e.g. Kernel Support Driver, Global Control Driver, PEC-PCL
Driver and PEC Driver can be used simultaneously. The block diagram below shows how the EIP-197 Drivers
as well as the Kernel Support Driver can be deployed to support multiple concurrent applications.

007-197550-308
User Guide Rev. A
Linux user space

Demo Application Executable
Demo Application PEC

SA Token
Builder Builder
EIP-197 PEC Driver Static User Library (.a)
PEC Adapter
EIP-201 EIP-207 EIP-202

IOToken
Driver Framework User

(uses /dev character device driver interface)
Interrupt
Log User List Ring Helper
Dispatcher
Worker
Thread
Linux kernel space

Demo Application PEC-PCL (.ko)
Extended SA
Demo Application Global Control (.ko) Builder
EIP-197 Global Control Driver (.ko) EIP-197 PEC-PCL Driver (.ko)
EIP-197 EIP-201 EIP-207

EIP-74 EIP-202
Global Control Drv Lib Drv Lib IOToken
Drv Lib Drv Lib
Drv Lib
Driver Framework EIP-207 Driver Framework

Kernel Firmware Kernel
Log Kernel Log Kernel List Ring Helper
Kernel Support Driver (SHDevXS + UMDevXS)

Figure 3 Multiple application support example

007-197550-308
User Guide Rev. A
7 Driver Build and Test Instructions

Build Instructions for a single configuration
If needed, set the required Driver parameters in Examples/$DRIVER/build/cs_*.h
configuration files where $DRIVER can be set to one of the following depending on what driver needs to be
built:
Driver
Driver_GlobalControl
Driver_PEC
Driver_PEC_PCL
These high-level parameters can be modified in cs_driver.h. The other cs_*.h files in this directory
contain detailed fine-tuning parameters that normally do not require user edits.
1. Make sure the Linux kernel for the host hardware platform is correctly configured. Refer to [8] for the
example Linux kernel configuration files.
2. Change directory to Examples/$DRIVER/build, for example:
$ cd Examples/$DRIVER/build
3. Set KERNEL_DIR and ARCH in the user-editable section of Makefile or as shell variables, for example:
$ export KERNEL_DIR=/usr/src/linux
$ export ARCH=x86
or
$ export ARCH=arm
or
$ export ARCH=arm64
4. If building for ARM, set cross compilation variable and the cross library path variable, for example:
$ export CROSS_COMPILE=arm-non-linux-gnueabi-
$ export CROSS_LIB_PATH=/opt/arm/arm-non-linux-gnueabi/libc/usr/lib
5. If running on a 64-bit platform, set DDK_HOST64 to “y”, when using 64-bit DMA addresses, set
DDK_DEVICE64 to “y”, for example:
$ export DDK_HOST64=y
$ export DDK_DEVICE64=y
6. Set the HOST_HW_PLATFORM variable to the appropriate hardware platform (only FPGA is supported), for
example:
$ export HOST_HW_PLATFORM=FPGA_Zynq_ZC706

007-197550-308
User Guide Rev. A
7. Set the EIP197_NOF_RINGS variable to the number of ring pairs for which to create multi-application
tests.
$ export EIP197_NOF_RINGS=4
8. Set the EIP197_BUS_VERSION variable to the appropriate bus type (PLB, AXI3 or AXI4) connected to
the system bus or to the FPGA PCIe bridge, for example:
$ export EIP197_BUS_VERSION=AXI4
9. Set the paths to the required firmware directories assuming the firmware is installed in the
FW_INSTALL_DIR directory.
$ export FW_EIP207_API_DIR=$FW_INSTALL_DIR/Firmware207/incl
$ export FW_EIP207_SRC_DIR=$FW_INSTALL_DIR/Firmware207/src
10. Invoke make from Examples/$DRIVER/build, for example:
$ make
This will produce both the kernel module binary (driver_197_k.ko for the Combined Driver) and the user
mode Driver in the form of a static library (libdriver_197_u.a for the Combined Driver) in the same
directory.
In order to use the user-space Combined Driver deployment Kernel Support Driver in the
Examples/Driver_KernelSupport/UMDevXS/build
directory must be built. In order to use the Global Control Driver with the PEC(-PCL) Driver, the Kernel
Support Driver in the
Examples/Driver_KernelSupport/SHDevXS/build
directory must be built.
Test Instructions
The Driver can be tested with the SLAD Test Tool as well as with the PCL Test Tool. For the detailed Test
Specification refer to document [3]. Refer also to documents [2] and [9] for testing the Driver.
Build and Test Instructions for Multiple Configurations

For building and testing multiple or all configurations, go to the TestTools/Regress_197 directory. In this
directory, there are scripts for doing regression tests.
Documentation on how to use these scripts is found in document [8], which can be found in the /docs
directory.

007-197550-308
User Guide Rev. A
8 Driver API
Combined Driver Initialization API
Reference: Integration/SLAD_Adapter/incl/api_driver197_init.h
Purpose: Interface to initialize and un-initialize the Combined Driver.
This API contains functions to initialize and un-initialize the Combined Driver. The Driver must be initialized
via this API before any of its other functions can be called.
Global Control Driver Initialization API
Reference: Integration/SLAD_Adapter/incl/api_global_driver197_init.h
Purpose: Interface to initialize and un-initialize the Global Control Driver.
This API contains functions to initialize and un-initialize the Global Control Driver. The Driver must be
initialized via this API before any of its other functions can be called.
PEC Driver Initialization API
Reference: Integration/SLAD_Adapter/incl/api_driver197_pec_init.h
Purpose: Interface to initialize and un-initialize the PEC Driver.
This API contains functions to initialize and un-initialize the PEC Driver. The Driver must be initialized via this
API before any of its other functions can be called.
PEC-PCL Driver Initialization API
Reference: Integration/SLAD_Adapter/incl/api_driver197_pec_pcl_init.h
Purpose: Interface to initialize and un-initialize the PEC-PCL Driver.
This API contains functions to initialize and un-initialize the PEC-PCL Driver.

007-197550-308
User Guide Rev. A
Packet Engine Control (PEC) API
Reference: Integration/SLAD_Adapter/incl/ - api_pec.h and api_pec_sg.h
Purpose: Interface for the packet engine functionality of the device.
This API contains functions to initialize, un-initialize, submit and receive one or multiple packets, registering
callbacks for getting a processed packet and submitting a new packet.
Functions for creating, reading and writing fragmented buffers for source and destination data; registering
callback for backfilling scatter buffers.
Please also refer to “Implementation Notes” files in Integration/SLAD_Adapter/src for specific
implementation details of this API.
Global Control API
Reference: Integration/SLAD_Adapter/incl/ api_global_status_eip97.h

api_global_status_eip207.h and api_global_eip74.h
Purpose: Interface to obtain global status of the device.
This API contains functions to obtain global status information of the hardware. It can also reseed the PRNG
(Pseudo Random Number Generator) used to generate random IVs in some protocols.
Packet Classification (PCL) API
Reference: Integration/SLAD_Adapter/incl/api_pcl.h
Integration/SLAD_Adapter/incl/api_pcl_dtl.h
Purpose: Interface for the packet classification functionality of the device.
This API contains functions to initialize, un-initialize the classification engine, to add and remove flow record
and to register and unregister hardware transform records. In addition there are functions to install and
remove entries for Direct Transform Lookup. Please also refer to “Implementation Notes” files in
Integration/SLAD_Adapter/src for specific implementation details of this API.
DMA Buffers Allocation (DMABuf) API
Reference: Integration/SLAD_Adapter/incl/api_dmabuf.h
Purpose: The Example Driver depends on an implementation of the DMABuf API. Please refer to
“Implementation Notes” for specific implementation details of this API.

007-197550-308
User Guide Rev. A
Memory Access API
Reference: Integration/SLAD_Adapter/incl/api_memxs.h
Purpose: Interface to read and write internal EIP device memory and registers.
This API contains functions for the low-level EIP device internal memory and registers access. This interface
should be used for debugging purposes only. It is available in the Global Control Driver for the user-space
driver deployment only.
IOToken API
Reference: Kit/IOToken/incl/iotoken.h
Purpose: Interface to create input and parse output tokens of the engine.
This API contains functions for creation and parsing tokens that are used for the IO operations for the
Security-IP-197 Engine.
This interface can have an extension specific to the EIP-207 firmware IO token format determined by the
firmware configuration and supported packet flows. Typically the name of such an extended IOToken API
would be iotoken_ext_*.h.

007-197550-308
User Guide Rev. A
9 Data Structures
This chapter describes the most important data structures used in the EIP-197 Example Driver. It also shows
how they are used in packet flows with or without packet classification.
Dynamic Resource (DMA) Data Structures

One of the features of the EIP-197 Engine is its DMA engine. When the engine is used in the Autonomous
Ring Mode (ARM) it uses the DMA engine to read a number of data structures from the host system
memory to its internal memory and write the result data back to the system memory. The data structures
accessed by the EIP-197 Engine DMA are referred to as dynamic resources. These resources are located in
the host system memory, they are shared between the host processor and the packet engine and are
dynamic in the sense that their location in memory is not known in advance. These resources must be
allocated run-time by the host software such as application and Driver and assigned addresses that can be
used by the host processor and packet engine to access them. Depending on the used OS and MMU
hardware the address used by the host processor and the packet engine for the same dynamic resource
may be different. In this case the Driver is responsible for the address translation before the resources is
handed over from the host to the packet engine and vice versa.
The internal Driver Framework DMAResource API (see dmares_*.h as well as [1]) defines the way the Driver
works with the dynamic resources. Each dynamic resource is identified inside the Driver by the handle
(DMAResource_Handle_t data type) and is described by its record (DMAResource_Record_t data type, see
dmares_record.h). The implementation of the DMAResource API in the Driver pre-allocates a compile-time
configurable number of the DMAResource records during the Driver initialization. Later these records are
used by the implementation of the Driver external (available for applications) SLAD DMABuf API for the
DMA-safe buffer allocation. Each DMA buffer requires one DMAResource_Record_t data structure for its
description. The DMAResource_Record_t data structure contains such information about DMA buffer as
requested size, allocated size, alignment, host (virtual) address, DMA (physical) address and other. These
DMAResource records remain internal to the Driver and are not exposed to the applications.
The implementation of the SLAD DMABuf API in this Example Driver is based on the DMAResource API. The
DMABuf API as well as the PEC API require the applications to use the DMA buffer handle
(DMABuf_Handle_t data type) as an identifier. The Driver can match the DMABuf_Handle_t handle to the
corresponding DMAResource_Handle_t handle and thus the DMAResource_Record_t record that contains
all the needed information about the dynamic resource.
Examples of dynamic resources used by the EIP-197 Engine Driver are the descriptor ring buffer, SA record
buffers, packet data buffers and token buffers. These data structures are described in the following
sections. Also refer to Figure 4 for the graphical representation of the data structure relationships in the
Example Driver.

007-197550-308
User Guide Rev. A
EIP-96 Intruction Token #1

(DMA Buffer)
DMAResource record #5
Main SA Record #1
(DMA Buffer)
Command Descriptor Ring

(DMA Buffer)
Physical Command Descriptor #1 Conversion Logical Command Descriptor #1 DMAResource record #4

Co
nve
Physical Command Descriptor #2 r si o
n
Generic Command Descriptor #1
n
rsio
nve DMAResource record #3
Co
FIFO
ordering
Logical Prepared Result Descriptor
#1 Packet Input/Output Data #1
n
io (DMA Buffer)
e rs
Result Descriptor Ring
nv
(DMA Buffer) Co
Physical Result Descriptor #1

Con
ve r s
Physical Result Descriptor #2 ion
Logical Result Descriptor #1
Con
vers
ion
Generic Result Descriptor #1
Figure 4 Driver Data Structure Relationships, look-aside use case
Security Association (SA) Data Structures

SA data structures are only used for packet flows without classification support. For packet flows with
classification support, use transform data structures (and their associated APIs) instead.
The SLAD PEC API defines references to the SA records as the DMA buffer handles (DMABuf_Handle_t data
type from the SLAD DMABuf API, see api_dmabuf.h) but not the format of the SA records. The EIP-197
contains the EIP-96 packet engine and hence the format of the SA data structures is defined by the EIP-96
hardware. The SA data structure format as such is unknown to the Driver and therefore must be filled in
with data by the application that uses the Driver (possibly using the SA Builder).
For some operations, the EIP-96 requires an ARC4 state record in addition to the main SA record. The SA
Builder will locate the ARC4 state record in a memory location adjacent to the main SA record in the same
memory buffer and the reference from the main SA record to the ARC4 state record is a relative offset, so
no address translation will be required when setting the ARC4 state record reference in the SA. However,
the application still needs to supply a separate DMA resource, representing the ARC4 state record as a
subset of the SA buffer. The application must use the function DMABuf_Register (with the AllocatorRef
parameter “R”) to register a subset of the SA Buffer to obtain a DMABuf handle for the ARC4 state record.
This is necessary because the Driver must be able to remove the SA and the ARC4 state record from the
correct caches.
The application must fill in the EIP-96 SA record as an array of 32-bit words using the endianness format
native to the host processor. The Driver will take care of the endianness conversion to the format native to
the EIP-96.

007-197550-308
User Guide Rev. A
The EIP-96SA records are dynamic resources (DMA buffers). This means that the packet engine reads and
writes data from and to these buffers using its DMA engine in the ARM. Therefore, these buffers must be
allocated by the applications that use the packet engine Driver in a DMA-safe way. To do that, the
applications must use the Driver’s SLAD DMABuf API.
Once the application has allocated the EIP-96 SA record buffers and filled them in with the data for the
required packet operation it can register these SA buffers with the Driver using the PEC_SA_Register()
function. After this the application may not change (read or write) the content of the SA buffers anymore
and it can start submitting packets to the packet engine for processing using the PEC_Packet_Put()
function and retrieving the results using the PEC_Packet_Get() function. When the SA record is not
needed anymore, which means that there are no more packets to process for this SA, it can be destroyed.
To do this, the application must first call the PEC_SA_UnRegister() function. One of the tasks of the
PEC_SA_UnRegister() function is to remove the SA record (and any associated ARC4 state) from any
internal caches of the EIP-197. After this, the application can read the SA buffer content if needed. The DMA
buffer corresponding with the SA must be freed using the SLAD DMABuf API.
There can be multiple co-existing SA records created by the application for the same packet engine. Refer to
“PEC API Implementation Notes” file in the Integration/SLAD_Adapter/src directory for the API
implementation details and further description of the SA data structures. Refer also to “DMABuf API
Implementation Notes” in the Integration/SLAD_Adapter/src directory for the implementation details of
this API.
Transform Data Structures

Transform data structures are only used for packet flows that use packet classification and use different API
functions from SA records.
The PCL API defines references to the transform records as the DMA buffer handles (DMABuf_Handle_t data
type from the SLAD DMABuf API, see api_dmabuf.h) but not the format of the transform records. The
Transform records are accessed both by the EIP-96 Packet Engine and the EIP-207 Firmware and hence the
format of the Transform data structures is defined by the EIP-96 hardware plus the EIP207 Firmware. The
Transform data structure format as such is unknown to the Driver and therefore must be filled in with data
by the application that uses the Driver (possibly using the Extended SA Builder).
The application must fill in the Transform record as an array of 32-bit words using the endianness format
native to the host processor. The Driver will take care of the endianness conversion to the format native to
the hardware.
The Transform records are dynamic resources (DMA buffers). This means that the packet engine reads and
writes data from and to these buffers using its DMA engine in the ARM. Therefore, these buffers must be
allocated by the applications that use the packet engine Driver in a DMA-safe way. To do that, the
applications must use the Driver’s SLAD DMABuf API.
Once the application has allocated the Transform record buffers and filled them in with the data for the
required packet operation it can register these Transform buffers with the Driver using the
PCL_Transform_Register() function. After this, the application may not change (read or write) the
content of the Transform buffers anymore (but it is allowed to use PCL_Transform_Get_ReadOnly() to
read some fields of the record) and it can start adding flows that reference these transform records. When
the record is not needed anymore, which means that there are no more flows referencing it, it can be
destroyed. To do this, the application must first call the PCL_Transform_UnRegister() function. One of
the tasks of the PCL_Transform_UnRegister() function is to remove the Transform record from any
internal caches of the EIP-197. After this, the application can read the Transform buffer content if needed.
The Transform DMA buffer must be freed using the SLAD DMABuf API.
There can be multiple co-existing Transform records created by the application for the same packet engine.
Refer to “PCL API Implementation Notes” file in the Example/Driver/src directory for the API
implementation details and further description of the SA data structures. Refer also to “DMABuf API
Implementation Notes” in the Kit/DMABuf/src directory for the implementation details of this API.

007-197550-308
User Guide Rev. A
Packet Token Data Structures

Packet Token data structures are only used in packet flows that do not offload token building and these
flows never use classification.
The SLAD PEC API defines references to the packet Tokens as the DMA buffer handles (DMABuf_Handle_t
data type from the SLAD DMABuf API, see api_dmabuf.h) but not the format of the packet tokens. The
token data structure format as such is unknown to the Driver and therefore must be filled in with data by
the application that uses the Driver (possibly using the Token Builder).
The application must fill in the EIP-96 packet instruction token as an array of 32-bit words using the
endianness format native to the host processor. The Driver will take care of the endianness conversion to
the format native to the EIP-96 Packet Engine. Each packet processed by the Driver needs its own unique
packet token. The same packet token may not be used by multiple packets.
The application is responsible for allocating the dynamic resource containing the packet token. Once
PEC_Packet_Put() is called, the application may not access this dynamic resource anymore until the
PEC_Packet_Get() function for that packet is finished. After that, the application can use the dynamic
resource for a different purpose or to free it.
IO Token Data Structures

IO Token data structures are always used with the SLAD PEC API.
The SLAD PEC API defines references to the IO tokens as the data pointers but not the format of the IO
tokens. The IO token data structure format as such is unknown to the Driver and therefore must be filled in
with data by the application that uses the Driver (possibly using the IOToken API).
The application must fill in the IO token as an array of 32-bit words using the endianness format native to
the host processor. The Driver will take care of the endianness conversion to the format native to the EIP-
197 Engine. Each packet processed by the Driver needs its own IO token. The same IO token may be used
for multiple packets.
The application is responsible for allocating the data buffer containing the IO token. Once
PEC_Packet_Put() is called, the application may not access this data buffer anymore until the
PEC_Packet_Put() function for that packet returns. After that, the application can use the IO token data
buffer for a different purpose or to free it.
Packet Data Structures

The buffers for the packet data are considered dynamic resources (DMA buffers) in the ARM because the
packet engine uses its DMA engine to read this data and write the result packet data back to the system
memory where these buffers must be allocated. The application must use the SLAD DMABuf API to allocate
the DMA-safe buffers for the packet data and free them. Alternatively, the application can register an
already allocated packet buffer using the DMABuf_Register() function in case this buffer is DMA-safe. The
DMABuf_Register() function allows for re-use of already allocated packet buffers and helps avoiding
allocating bounce buffers and copying the packet data between the old and new buffers.
The format of the packet data is transparent to the Driver. The Driver neither writes nor reads the packet
data. The Driver sees the packet data as a byte stream and it will not perform endianness conversion for this
data structure.
There can be multiple packets submitted for processing to the packet engine for the same SA record. This
SA record may not be destroyed until all these packets are processed.
The EIP-197 Engine and its Driver are both capable of performing in-place packet transform in the ARM
when the same input (source) packet buffer is also used as output (destination) packet buffer. The
application must ensure that in this case the buffer is large enough for the output data, which may be larger
than the input data. In addition, the application should ensure that the DRIVER_PE_HOLD_OUTPUT_DATA
parameter (see Chapter 10) is set in such a way that output does not overwrite unread input.

007-197550-308
User Guide Rev. A
Packet Descriptor Data Structures

The SLAD PEC API defines Command Descriptor (PEC_CommandDescriptor_t) and Result Descriptor
(PEC_ResultDescriptor_t) data structures (see api_pec.h). Their PEC API descriptor format is defined in a
generic way that allows using this API with various types of packet engines. The PEC Command Descriptor
data structure contains two fields whose format is specific to the packet engine type, namely the Control1
and Control2 fields. These fields contain control information that must be passed via a command
descriptor to the packet engine. Similarly, the PEC Result Descriptor data structure contains two fields
specific to the packet engine type, Status1 and Status2. These fields contain error and status information
that can be passed from the packet engine to the software application.
The EIP-197 Driver Library API defines logical command descriptor and result descriptor data structures. The
format of these data structures is called logical because it does not match exactly the format of the packet
descriptors used by the packet engine. The EIP-197 Driver Library converts the logical descriptor format into
the physical descriptor format and the other way around. The EIP-197 Driver Library API defines the
EIP202_ARM_CommandDescriptor_t, EIP202_ARM_PreparedResultDescriptor_t and
EIP202_ARM_ResultDescriptor_t data structures for the ARM (see eip202_*.h). The Driver fills in part of
the logical result descriptor containing the packet destination address.
The physical descriptors are written by the EIP-197 Driver Library to the ring buffer in the ARM. The ring
buffer is a DMA buffer that is allocated by the Adapter module for the ARM using the internal Driver
Framework DMAResource API (see dmares_*.h). The ring can contain multiple physical packet descriptors.
The Driver can be configured compile-time to use one ring for the command and result descriptors
(overlapping rings) or separate rings. The ring buffer is not visible to the applications that use the Driver and
this buffer is fully under the Driver control.
The Driver Adapter module for the ARM will convert the PEC API generic Command Descriptor data
structure PEC_CommandDescriptor_t to the EIP-197 Driver Library API logical data structure
EIP202_ARM_CommandDescriptor_t for each packet submitted to the Driver via the PEC_Packet_Put()
function. The Adapter module for the ARM also performs a similar conversion from the EIP-197 Driver
Library API logical data structure EIP202_ARM_ResultDescriptor_t for each packet retrieved from the
Driver via the PEC_Packet_Get() function.
All command descriptor data structures for a certain packet must exist at least for as long as the host
processor executes the PEC_Packet_Put() function for that packet. All result descriptor data structures for
a certain packet must exist at least for as long as the host processor executes the PEC_Packet_Get()
function for that packet.
There is always one packet command descriptor and result descriptor pair per packet.
Flow Data Structures

Flow data structures are used only for the Inbound Inline IPsec and Fast-Path IPsec flows, never for the
Look-aside IPsec flow. The PCL API is the only Driver API that supports them.
While Flow data structures (Flow record and Hash Bucket) do make use of dynamic resources internally, this
use is not visible for the application. From the application’s point of view, each Flow record is represented
by a handle of type PCL_FlowHandle_t. The required resources for Flow records are allocated via the PCL
API. This allocation is done in a special DMA memory bank which is allocated once for each Flow Hash Table.
The application can create Flow records using resources from that DMA bank without the need to allocate
additional memory buffers or DMA-safe buffers at that time. The function PCL_Flow_Alloc() allocates the
resources for a Flow record (and the returned handle represents the allocated resources of a flow record),
but the Flow record is not added to the Flow Hash Table at this stage yet. These resources can later be
released with PCL_Flow_Release().
The EIP-207 Classification Engine uses a 128-bit hash (of certain fields in the headers of the IP packet) to
look up a flow record or a transform record. Before adding the record to the Hash Table, the application
must compute the correct 128-bit hash using the PCL_Flow_Hash() function, which takes as input a data
structure of type PCL_SelectorParams_t, which contains fields such as source and destination address, IP
protocol, SPI and port numbers. The PCL_Flow_Hash() function will compute the hash from the applicable

007-197550-308
User Guide Rev. A
fields (depending on the protocol) in the same way the hardware would with packets containing these fields
in their headers.
Once the hash is computed, the application can create a PCL_FlowParams_t data structure, which contains
the hash and the DMABuf handle of the transform record and add a flow record to the Hash Table with
PCL_Flow_Add(). This function will also allocate the Flow descriptor for the Hash Bucket and in case this is
an overflow bucket (does not reside in the Hash Table due to Hash ID or record type mismatch) it will also
allocate the DMA–safe buffer for this bucket in the DMA bank. Once the Flow is added to the Hash Table,
the Classification Engine can look it up. Note that each combination of source address, destination address,
IP protocol (and for certain protocols, the source and destination port as well) has a unique hash and a
separate flow record must be created for each one. This means that for outbound IPsec traffic, many flows
typically exist for one transform record.
The application can also create a transform record for direct lookup to the Hash Table by using the
PCL_DTL_Transform_Add() function.
If a Flow record is no longer needed, it can be removed from the Hash Table with PCL_Flow_Remove(). Its
resources remain allocated. The same Flow handle can now be reused for a different flow or it could be
released completely with PCL_Flow_Release(). The PCL_DTL_Transform_Remove() function can be used
to remove the transform record from the Hash Table.
The Driver maintains the lookup data structures of the Hash Table in two representations:
• An internal representation for its own administration in memory that is not DMA-safe. Any pointers
linking parts of the table together are in a form suitable for use by the Driver software (host addresses).
The host endianness is used. Each Flow record in the internal representation is represented by a
structure of type EIP207_Flow_FR_Dscr_t. In fact, PCL_FlowHandle_t is a pointer to this data
structure. It contains a reference to the DMA-safe buffer of the Flow record.
• A representation suitable for the Classification Engine. All in-memory data structures are in DMA-safe
buffers. Pointers are bus addresses as used by the hardware. The endianness required by the hardware
is used. Each record has a layout that is dictated by the EIP-207 Engine and firmware.
When the Hash Table is updated, the Driver updates both representations. It uses the internal
representation to find the correct part of the Flow Table and to find the hardware representation.
Figure 5 shows an example where one Flow record and three Transform records are used. The Classification
Engine can directly look up only one of these three Transform records, namely the Transform record
identified by Transform Handle #1. Flow record #1 is associated with its own DMA-safe buffer #1 (where the
Flow data is stored) via its own DMA Resource record #1. The latter contains a pointer to Hash Bucket
Descriptor #1 that references the DMA buffer located in the Flow Hash Table. The Flow Hash Table itself is a
DMA buffer. Hash Bucket #1 references Hash Bucket #2 and vice versa by means of the doubly-linked list
implemented in the Flow Record descriptor data structure. Hash Bucket #2 is an overflow hash bucket for
Hash Bucket #1 in this example. Flow record #1 is associated with Transform record #1 via DMA buffer #1.
Transform record identified by Transform Handle #2 can be directly looked up by the Classification Engine in
the Flow Hash Table. DMA resource record #2 of this transform contains a pointer to the Hash Bucket
descriptor #1 that is also associated with the Flow record. The Hash ID of this Flow record and this
Transform record give the same offset in the Flow Hash Table.
Transform record identified by Transform Handle #3 can also be directly looked up by the Classification
Engine in the Flow Hash Table. However, this record is referenced by the overflow Hash Bucket #2.

007-197550-308
User Guide Rev. A
Hash Bucket
DMA Buffer #2 (in DMA bank)
Transform
Handle #3
Transform Record DMA
Co
Buffer #5 (in DMA bank)
nve
r si o
n DMAResource
Record #4
EIP-207 Transform DMAResource
Record Descriptor #3 Record #5
EIP-207 Hash Bucket

Descriptor #2
DMAResource
EIP-207 Flow Record Flow Record #1
Descriptor #1
n
sio
EIP-207 Hash Bucket

er
Descriptor #1
nv
Co
Flow Record
Flow Record
Handle #1 Hash Bucket
DMA Buffer (in FHT)
EIP-207 Transform
Record Descriptor #1 Transform Record
DMA Buffer #4
n
io
e rs
o nv
C
DMAResource
Transform
Record #3
Handle #1 Transform Record
Transform DMAResource
Handle #2 Record #2
Conversio
n
EIP-207 Transform
Record Descriptor #2
Reference by
PCL_FlowHandle_t DMAResource handle
Reference by host (virtual)

DMABuf_Handle_t and DMA (physical) address
Reference by host
DMA Buffer
(virtual) address
EIP207_Flow_FR_Dscr_t
Reference by DMA
DMAResource_ (physical) address
EIP207_Flow_TR_Dscr_t Record_t
Conversion Data structure format
conversion by driver
Figure 5 PCL Data Structure Relationships

007-197550-308
User Guide Rev. A
10 Driver Configuration Parameters

The Example Driver has been tested in various configurations. This section describes important
configuration parameters (as compile time parameters).
DDK-wide configuration parameters

Several compile-time parameters of the DDK are defined globally in the file cs_ddk197.h. This file is located
under Examples/Driver/build and the install script creates symlinks to this file from the build directories
of all other DDK components. The following parameters are defined:
• DDK_EIP197_FW_IOTOKEN_METADATA_ENABLE
Define this to include 16-byte meta data in each command and result token. Metadata is copied from
the command token to the corresponding result token. This can only be enabled if both hardware and
firmware support this feature.
• DDK_EIP197_FW_CFH_ENABLE
Define this to include a special header in command and result tokens on the look-aside FIFO and the
inline interface. This can only be enabled if both hardware and firmware support this feature.
• DDK_EIP197_EIP97_BLOCK_UPDATE_APPEND
Define this to prevent the update information (length, protocol, checksum) from being appended to the
packet. Update information is generated for IPSec ESP inbound transport packets. If the packet fits into
the output buffer, the header fields can be updated in-place, otherwise the update information is
usually appended to the packet.
• DDK_EIP197_EXTENDED_ERRORS_ENABLE
Define this to support extended error codes. Bit E14 in the result descriptor indicates the presence of
an extended error code. This can only be enabled if both hardware and firmware support this feature.
• DDK_EIP202_CD_OFFSET_BYTE_COUNT
Specify the offset in bytes between command descriptors in the ring buffer in memory.
• DDK_EIP202_RD_OFFSET_BYTE_COUNT
Specify the offset in bytes between result descriptors in the ring buffer in memory.
• DDK_EIP197_FW33_FEATURES
Define this when the DDK is tested on Hardware 3.3 and Firmware 3.3. This setting only influences the
test tools, so they leave out tests for newer features on older hardware.
• DDK_EIP197_SRV_ICEOCE
Define this if the DDK is packaged for the server version of the EIP-197 with both input and output
classification engines.
• DDK_EIP197_SRV_ICE
Define this if the DDK is packaged for the server version of the EIP-197 with input classification engines
only.

007-197550-308
User Guide Rev. A
Note: Exactly one of DDK_EIP197_SRV_ICEOCE or DDK_EIP197_SRV_ICE must be defined. It is not

possible to change this configuration setting as the DDK is packaged for one of the hardware
configurations only.
Top-level Driver configuration parameters

This section describes the top-level Driver compile-time configuration parameters in the cs_driver*.h
files.
• DRIVER_NAME
Specifies the driver name used for reporting in the log files and operating system.
• DRIVER_MAX_NOF_RINGS_TO_USE
Specifies the maximum number of descriptor ring pairs that can be used by the driver. If this is set
higher than the number of ring pairs supported by the hardware, the driver will use the number of rings
supported by the hardware.
• DRIVER_SWAPENDIAN
The EIP-197 Engine is little endian. If the host processor is big endian then the endianness conversion
can be enabled in the Driver. This option causes the Driver software to perform any necessary
endianness conversion. Instead of setting DRIVER_SWAPENDIAN, one can set both
DRIVER_ENABLE_SWAP_SLAVE and DRIVER_ENABLE_SWAP_MASTER to achieve the same effect. The
latter option is more efficient, but it may not be supported in all hardware environments.
• DRIVER_ENABLE_SWAP_SLAVE
This option causes the driver to configure the hardware such that it swaps the byte order of all bus
target accesses to the device.
• DRIVER_ENABLE_SWAP_MASTER
This option causes the driver to configure the hardware such that it swaps the byte order of all bus
master accesses by the device.
• DRIVER_PE_ARM_SEPARATE
The EIP-197 Engine can operate in Autonomous Ring Mode (ARM) with separate rings for command
descriptors and for result descriptor. This parameter must be defined.
• DRIVER_INTERRUPTS
The Driver can be used with or without interrupts. It provides API functions that are registered as
callbacks to be invoked on receiving interrupts. These callbacks typically submit a packet or collect a
processed packet from the device.
When interrupts are off, the Driver is said to be in “polling mode”. In this mode, the caller of the Driver
API should poll the device registers for completion of a packet processing (packet-put and packet-get
API functions) or when the device is free to ‘put’ a new packet.
When interrupts are enabled, result notification callbacks are invoked asynchronously with respect to
the main application. Special care must be taken to make these callbacks work reliably. See the
description of PEC_ResultNotify_Request in the PEC API.

007-197550-308
User Guide Rev. A
• DRIVER_INTERRUPT_COALESCING
If the Driver is used with interrupts, the hardware can generate a separate interrupt for every single
result packet available or it can generate one interrupt when a certain number of packets become
available. The latter case is called interrupt coalescing mode; it is more efficient as the interrupt service
routine is invoked fewer times, but it can cause a slightly longer packet latency.
• DRIVER_SCATTERGATHER
The EIP-197 Engine is capable of processing a non-contiguous packet. It is also capable of writing back
results to non-contiguous buffers. In such a case, each buffer forming one complete input packet is
called a “Gather Particle”, while for output packet, each buffer is called a “Scatter Particle”. By enabling
this parameter, Scatter and Gather support is enabled in the Driver.
• DRIVER_BOUNCEBUFFERS
In ARM mode, the EIP-197 Engine works on DMA buffers in system memory (Descriptor ring, SA and
Data). These buffers must be DMA-safe, i.e. aligned on cache-line size and in the DMA-able address
range.
The caller can create DMA-safe buffers either by using the DMABuf API or can provide such buffers
using operations outside the Driver. If the buffer provided by the application is not DMA-safe, the
Driver can allocate a DMA-safe buffer internally and copy the result of processing back to the user-
provided buffer. Such a buffer allocated by the Driver, is called a “Bounce Buffer”.
Enabling this parameter configures the Driver to create bounce buffers. In this case, the caller does not
have to provide DMA-safe buffers.
• DRIVER_PERFORMANCE
Enabling this parameter in the Driver suppresses informational messages. These messages are helpful in
debugging but otherwise slow-down the Driver.
• DRIVER_PEC_MAX_SAS
Specify the maximum number of SA’s that will be in use at a given time. This parameter and other
parameters determine the maximum number of DMA buffers that can be used by the Driver at any
given time.
• DRIVER_PEC_MAX_PACKETS
Specify the maximum number of packets that can be under processing by the system at any given time.
This parameter determines the size of the descriptor ring or rings. This parameter is also used for
determining the maximum number of DMA buffers that can be used by the Driver at any given time.
• DRIVER_MAX_PECLOGICDESCR
Specify the maximum number of packet descriptors that the PEC_Packet_Put and PEC_Packet_Get
functions can process in a single call. This is usually equal to DRIVER_PEC_MAX_PACKETS.
• DRIVER_PE_HOLD_OUTPUT_DATA
This parameter can be used for the in-place packet transformations when the transformed result
packet is larger than the original packet. In-place means that the same packet buffer is used to store the
original as well as the transformed packet data. In such a case the result packet data can overwrite the
original packet data in the packet buffer that has not been read yet. This parameter value defines the
number of 8-byte blocks that the packet engine will hold in its internal result packet buffer until the
packet processing is completed. The value can be set to match the size of the expected data expansion
(in an encryption or outbound protocol operation) at the start of the packet data.

007-197550-308
User Guide Rev. A
• DRIVER_PCL_FLOW_HASH_ENTRIES_COUNT
Specify the number of entries (hash buckets) in the flow hash table of the Packet Classification Engine.
This must be a power of two, at least 32 and at most 1048576. To make the flow lookup operation
efficient, this parameter should be set higher than the total number of flow records used in the system.
This parameter is also used for determining the maximum number of DMA buffers that can be used by
the Driver at any given time.
• DRIVER_64BIT_HOST
Define this if the Driver is to be compiled for a platform that has 64-bit addresses. Leave this undefined
for a 32-bit platform. This option is normally passed via the make file from the DDK_HOST64
environment variable.
• DRIVER_64BIT_DEVICE
Define this if the Driver must use 64-bit DMA addresses. On the hardware supported by this driver, this
must always be enabled, even on 32-bit platforms. This option is normally passed via the make file from
the DDK_DEVICE64 environment variable.
• DRIVER_MAX_NOF_PE_TO_USE
This configuration parameter determines the maximum number of the Processing Engines that can be
used by the Driver. If this is set higher than the number of PEs supported by the hardware, the driver
will use the number of PEs supported by the hardware.
• DRIVER_DMARESOURCE_BANKS_ENABLE
Define this if special DMA banks must be allocated for Transform/SA records and for Flow records. This
is required when DRIVER_64_DEVICE is set, because the hardware requires all transform records to
reside in a 4GB address range. Flow records must also reside in a 4GB address range, which may have a
different base address. The special DMA banks specified by this option are designed to satisfy these
hardware requirements.
• DRIVER_ALLOW_UNALIGNED_DMA
Define this if DMA resource buffers should be allowed at unaligned addresses.
• DRIVER_PEC_BANK_SA
Specifies the DMA resource bank ID to use for SA bouncing by the PEC API implementation.
• DRIVER_PCL_BANK_TRANSFORM
Specifies the DMA resource bank ID for the transform records allocation by the PCL API
implementation. Can be the same as DRIVER_PEC_BANK_SA.
• DRIVER_PCL_BANK_FLOW
Specifies the DMA resource bank ID for the flow records allocation by the PCL API implementation.
• DRIVER_FLOW_RECORD_COUNT
Specifies the maximum number of flow records the driver can allocate. Can be set to
DRIVER_PCL_FLOW_HASH_ENTRIES_COUNT.

007-197550-308
User Guide Rev. A
• DRIVER_FLOW_RECORD_BYTE_COUNT
Specifies the flow record size. For the hybrid use case the transform record size is determined by the
EIP-207 Firmware API. For the look-aside use case the transform record size is determined by the
maximum used SA size.
• DRIVER_TRANSFORM_RECORD_COUNT
Specifies the maximum number of SA or transform records the driver can allocate. Can be set to
DRIVER_PEC_MAX_SAS.
• DRIVER_TRANSFORM_RECORD_BYTE_COUNT
Specifies the transform record size.
• DRIVER_USE_SHDEVXS
Define this if the shared device access functionality must be used by the Driver in which case it must be
either the Global Control Driver or the PEC Driver. This parameter must not be defined for the
Combined Driver.
• DRIVER_DMA_ALIGNMENT_BYTE_COUNT
Set this parameter to the desired DMA buffer address and size alignment value. The Combined Driver
can determine this value from the Engine hardware registers for the Adapter software components. For
the Driver Framework DMA Resource API implementation (namely for the DMA banks allocation) this
parameter must be configured by the user and must be set to a value either equal or greater than what
is required by the Engine hardware (master interface).
• DRIVER_RING_AIC_DISABLE
Define this if the device does not contain a ring AIC, but has the ring IRQ signals directly wired to inputs
of the global AIC instead.
• DRIVER_AIC_SEPARATE_IRQ
Define this if the each AIC (global AIC and ring AICs) have a dedicated system IRQ. If this is not defined,
only the global AIC has a system IRQ, while the ring AICs have their outputs wired to inputs of the global
AIC.
Top-level Adapter configuration parameters

This section describes the top-level Adapter compile-time configuration parameters in the cs_adapter*.h
configuration files. The default values of these configuration parameters with full description can be found
in the default Adapter configuration files c_adapter_*.h. The default configuration file can also contain
other parameters not described in this section.
The top-level configuration file is used to override the default values of some configuration parameters.
Some of the top-level Adapter configuration parameters are derived from the top-level Driver configuration
parameters in cs_driver*.h file.
All the ADAPTER_* parameters derived from the corresponding DRIVER_* parameters are not described
below).

007-197550-308
User Guide Rev. A
• LOG_SEVERITY_MAX
Trace level (for informational messages) for the Adapter module. Default value is LOG_SEVERITY_WARN
(or LOG_SEVERITY_CRITICAL if DRIVER_PERFORMANCE is set). It can be set to LOG_SEVERITY_INFO,
which will give more traces but will also slow down the Driver operation.
• ADAPTER_DESCRIPTORDONECOUNT
Specify the number of result descriptors that must be available before a result descriptor IRQ is
generated. This is used with DRIVER_INTERRUPT_COALESCING.
• ADAPTER_DESCRIPTORDONETIMEOUT
Specify a timeout to generate an interrupt when at least one result descriptor is available, but not the
number specified by ADAPTER_DESCRIPTORDONECOUNT. This is used with
DRIVER_INTERRUPT_COALESCING.
• ADAPTER_MAX_DMARESOURCE_HANDLES
Specify the maximum number of DMA Resources that can be allocated by the driver.
• ADAPTER_EIP202_DEVICES
This is a list of all EIP-202 devices. Each entry in the list specifies a CDR/RDR pair together with their
interrupts.
• ADAPTER_EIP202_AICS
This is a list of all EIP-201 AIC devices and for each device the way its output is connected: either to an
input of another AIC device or to an external interrupt at system level.
• ADAPTER_EIP202_IRQS
This is a list of all interrupts used by the Driver, for each interrupt it lists the AIC by which it is serviced,
the interrupt number within the AIC, whether to use delayed execution of the bottom half handler and
the interrupt type.
• ADAPTER_FIRMWARE_PATH_PREFIX
Specify the directory from which the driver loads firmware images in user space deployment. Specify
this with a trailing slash, for example “/usr/eip197/firmware_images/”. The default is
“/usr/firmware/”.
• ADAPTER_EIP74_GEN_BLK_SIZE
Specify the number of 128-bit pseudo-random IVs generated by the DRBG in a single block.
• ADAPTER_EIP74_RESEED_THR
Specify the maximum number of generate operations of the DRBG before a reseed operation is
absolutely required.
• ADAPTER_EIP74_RESEED_THR_EARLY
Specify the maximum number of generate operations of the DRBG before a reseed warning is given.
This is sufficiently lower than the reseed threshold, so the software has enough time to perform the
reseed.

007-197550-308
User Guide Rev. A
• ADAPTER_CS_GLOBAL_INCREMENT_PKTID
Define this to configure the firmware to generating Packet IDs on outer IPv4 tunnel headers generated
in outbound ESP tunnel transforms. This applies only to hardware that contains an output classification
engine.
• ADAPTER_CS_GLOBAL_ECN_CONTROL
This is a five-bit bitmask that specifies for certain type of ECN conditions when an error result should be
returned. This is a firmware configuration option on hardware versions prior to HW3.3. For these
versions it applies only to hardware that contains an output classification engine. For hardware versions
HW3.3 and later, it is a hardware configuration option and it also applies to hardware configurations
without an output classification engine.
• ADAPTER_CS_GLOBAL_DTLS_HDR_ALIGN
Specify the size of the DTLS record header that occurs in the output packet for inbound DTLS operations
when the SA specifies that DTLS headers must be returned. This is a firmware configuration option.
When it is set to 0, each DTLS header will be 5 bytes, which is the minimum required.
• ADAPTER_CS_GLOBAL_DTLS_DEFER_CCS
If this is defined, defer all incoming DTLS packets with record type Change Cipher Spec to the slow path.
This is a firmware configuration option.
• ADAPTER_CS_GLOBAL_DTLS_DEFER_ALTERT
If this is defined, defer all incoming DTLS packets with record type Alert to the slow path. This is a
firmware configuration option.
• ADAPTER_CS_GLOBAL_DTLS_DEFER_HANDSHAKE
If this is defined, defer all incoming DTLS packets with record type Handshake to the slow path. This is a
• ADAPTER_CS_GLOBAL_DTLS_DEFER_APDATA
If this is defined, defer all incoming DTLS packets with record type Application Data to the slow path.
This is a firmware configuration option.
• ADAPTER_CS_GLOBAL_DTLS_DEFER_CAPWAP
If this is defined, defer all incoming DTLS packets with a CAPWAP header to the slow path. This is a
Top-level Driver Framework (HWPAL) configuration parameters

This section describes the top-level Driver Framework compile-time configuration parameters in the
cs_hwpal*.h configuration files. The default values of these configuration parameters with full description
can be found in the default Driver Framework configuration files c_hwpal_lkm.h (kernel-space specific) and
c_hwpal_device_umdevxs.h (user-space specific). The default configuration files can also contain other
parameters not described in this section.
The top-level configuration file is used to override the default values of some configuration parameters.
Some of the top-level Driver Framework configuration parameters are derived from the top-level Driver
configuration parameters in cs_driver*.h file.

007-197550-308
User Guide Rev. A
Specific for the hardware platform settings can be configured in the cs_hwpal_ext.h configuration file. For
the x86 and PowerPC architectures, a PCI-based kernel integration is used and for any other architectures,
an Open Firmware (Platform) kernel integration is used.
Note: All the HWPAL_* parameters derived from the corresponding DRIVER_* parameters are not
described below.
• LOG_SEVERITY_MAX
Trace level (for informational messages) for the Driver Framework modules. Default value is
LOG_SEVERITY_WARN (or LOG_SEVERITY_CRITICAL if DRIVER_PERFORMANCE is set). It can be set to
LOG_SEVERITY_INFO, which will give more traces but will also slow down the Driver operation.
• HWPAL_STRICT_ARGS_CHECK
Enables strict argument checking for the input parameters in all the Driver Framework API functions.
• HWPAL_DEVICES
List of devices with their names and their addresses ranges. All addresses of all devices accessed by the
driver are assumed to lie in a single address range, e.g. a single BAR on a PCI device or a single address
range as specified in the Open Firmware device tree. The start and end addresses are specified as byte
offsets with respect to the start of that range.
• HWPAL_MAX_DEVICE_NAME_LENGTH
Maximum number of characters (bytes) that can be used for a device name as used in the
HWPAL_DEVICES list of devices.
• HWPAL_DEVICE_MAGIC
Optional magic number used to validate the device administration data.
• HWPAL_DEVICE_DIRECT_MEMIO
Enables direct access to memory mapped registers of the device bypassing the OS I/O functions.
• HWPAL_PLATFORM_IRQ_IDX
Index of the IRQ used to query the physical device interrupt number via the Linux platform kernel API.
• HWPAL_DEVICE_ID and HWPAL_VENDOR_ID

These are only used for a PCI (or PCIe) device and they specify the device and vendor ID of the device.
Note that similar parameters must also be specified in the configuration of the Kernel Support Driver in
cs_umdevxs_ext.h
• HWPAL_USE_MSI
This is only used for a PCI (or PCIe) device. It specifies whether the device must use MSI interrupts. Note
that a similar parameter must also be specified in the configuration of the Kernel Support Driver in
cs_umdevxs_ext.h

007-197550-308
User Guide Rev. A
• HWPAL_PLATFORM_DEVICE_NAME
This is only used for an Open Firmware device. It specifies the name of the device as specified in the
Open Firmware device tree. Note that a similar parameter must also be specified in the configuration of
the Kernel Support Driver in cs_umdevxs_ext.h
• HWPAL_DEVICE_READ_DELAY_US
Device_Read32() function will busy wait for the specified by this parameter number of microseconds
before actually performing the read operation. This is a workaround for posted-writes implementation
of the MMIO register slave interface when too fast write-read sequence does not work.
• HWAL_DMARESOURCE_STRICT_ARGS_CHECKS
Enables strict argument checking for the input parameters of the DMAResource API functions.
• HWAL_DMA_NRESOURCES
Specifies the maximum number of DMA resources available. Change
ADAPTER_MAX_DMARESOURCE_HANDLES instead.
• HWAL_TRACE_DMARESOURCE_LEAKS
Keep track of allocation and deallocation of DMA resources and check that at driver unload time all
allocated DMA resources are freed.
• HWAL_DMARESOURCE_ALLOC_CACHE_COHERENT
Specifies that all DMA resources must be allocated in cache-coherent memory, which does not require
cache invalidate and flush operations from the CPU.
• HWAL_DMARESOURCE_UNCACHED_MAPPING
When defined enables use of ioremap_cache for mapping memory as non-cached. This is used for
static DMA banks.
• HWAL_DMARESOURCE_MINIMUM_CACHE_CONTROL
Enable this parameter in order to use the minimal Linux DMA API, This will also cause the Linux Kernel
to perform fewer sanity checks on the provided DMA buffers.
• HWAL_DMARESOURCE_DCACHE_LINE_SIZE
Specifies the size of a single data cache line in bytes.
• HWAL_DMARESOURCE_BANKS
List of DMA resource banks together with their properties. It is possible to specify banks with a fixed
block size and a number of blocks, so the entire bank will be allocated by the operating system in one
operation, single blocks are subsequently allocated from this bank. It is also possible to specify fixed
static addresses for certain banks.
• HWAL_DMARESOURCE_BANK_STATIC_OFFSET
Specifies an offset seen by the CPU, but not by EIP hardware when accessing static DMA banks,

007-197550-308
User Guide Rev. A
Other top-level configuration parameters

10.5.1 EIP Driver Libraries
The EIP-197 Driver Library top-level configuration parameters are stored in files cs_eip97*.h,
cs_eip96*.h, cs_eip202*.h, cs_eip206*.h and cs_eip207*.h. Refer to [6] for parameters description.
The EIP-201 Driver Library top-level configuration parameters are stored in file cs_eip201.h. Refer to [7]
for parameters description.
The EIP-74 Driver Library top-level configuration parameters are stored in file cs_eip74.h.
Note that all these top-level configuration files override default values specified in the respective default
configuration files c_eip*.h.
10.5.2 List component

The List software component top-level configuration parameters overriding the default values are stored in
file cs_list.h, and its default configuration parameters values are stored in c_list.h. Refer to these files
for the parameters description.
10.5.3 Interrupt Dispatcher

The Interrupt Dispatcher software component top-level configuration parameters overriding the default
values are stored in file cs_intdispatch_umdevxs.h, and its default configuration parameters values are
stored in c_intdispatch_umdevxs.h. Refer to these files for the parameters description.
Default Driver Configuration

The Driver has following default configuration set:
• SWAPENDIAN is set depending on the ARCH switch.
• Maximum number of rings is set to 12.
• Maximum number of processing engines is set to 12.
• ARM Mode with separate rings
• Interrupts enabled
• Interrupt coalescing enabled.
• Scatter/Gather Off
• Bounce Buffers On
• Performance Off
• Maximum number of SA’s: 600.
• Maximum number of packets: 32.
• PE output data to hold: 0.
• Number of flow hash table entries: 1024,
• DMA banks enabled.
• 64-bit device support enabled.
For other configurations, refer to the Security-IP-197 DDK Test Specification [3].

007-197550-308
User Guide Rev. A
Driver Traces (Logging) Configuration

Driver traces can be enabled at a low level to get information about what the driver does. By default, the
trace level is warning for the driver. This can be set to the informational level to get as many traces as
possible. The driver tracing functionality is implemented in the Kit/Log component. The driver traces can
be configured in the Adapter layer (via the Examples/$DRIVER/build/cs_adapter.h file) as well as in the
Driver Framework layer (via the Examples/$DRIVER/build/cs_hwpal.h file).
To enable the informational traces in the driver Adapter layer, ensure that the following is present in the
Examples/$DRIVER/build/cs_adapter.h file
#define LOG_SEVERITY_MAX LOG_SEVERITY_INFO
To enable the informational traces in the Driver Framework layer ensure that the following is present in the
Examples/$DRIVER/build/cs_hwpal.h file
#define HWPAL_LOG_SEVERITY LOG_SEVERITY_INFO
#define HWPAL_TRACE_DEVICE_FIND // Trace

Device_Find()
#define HWPAL_TRACE_DEVICE_READ // Trace
Device_Read32()
#define HWPAL_TRACE_DEVICE_WRITE // Trace
Device_Write32()
#define HWPAL_TRACE_DMARESOURCE_WRITE // Trace
DMAResource_Write32()
#define HWPAL_TRACE_DMARESOURCE_READ // Trace
DMAResource_Read32()
#define HWPAL_TRACE_DMARESOURCE_PREPOSTDMA // Trace
DMAResource_PreDMA() and
DMAResource_PostDMA()
#define HWPAL_TRACE_DMARESOURCE_BUF // Trace DMAResource_Alloc(),
DMAResource_Register(),
DMAResource_Release()
Inspect the cs_adapter.h and cs_hwpal.h files for the details how the traces can be configured. Note how
the DRIVER_PERFORMANCE configuration parameter influences the tracing level in these files.
Note: Configuring the driver for the informational traces in the Adapter and especially in the Driver
Framework layers will result in very long log files produced by the driver when used with
applications performing lots of requests to the driver.
(End of Document)

Security-IP-197 DDK v5.5 User-Guide RevA

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Security-IP-197 DDK v5.5 User-Guide RevA

Uploaded by

Copyright:

Available Formats

Security IP

Driver Development Kit v5.5

© Rambus Inc. • rambus.com CONFIDENTIAL

Rambus Inc. Corporate Headquarters

Rambus ROTW Holding B.V.

© Rambus Inc. • rambus.com CONFIDENTIAL 2

Table of Contents ................................................................................... 3

© Rambus Inc. • rambus.com CONFIDENTIAL 3

4 Driver Deployments ...................................................................... 26

© Rambus Inc. • rambus.com CONFIDENTIAL 4

10 Driver Configuration Parameters .................................................. 46

© Rambus Inc. • rambus.com CONFIDENTIAL 5

© Rambus Inc. • rambus.com CONFIDENTIAL 6

Document Revision History

© Rambus Inc. • rambus.com CONFIDENTIAL 7

© Rambus Inc. • rambus.com CONFIDENTIAL 8

© Rambus Inc. • rambus.com CONFIDENTIAL 9

© Rambus Inc. • rambus.com CONFIDENTIAL 10

© Rambus Inc. • rambus.com CONFIDENTIAL 11

Driver Development Difficulties

© Rambus Inc. • rambus.com CONFIDENTIAL 12

2.4.1 DDK Problem-Solution Map

Typical driver DDK Solution DDK Deliverables

© Rambus Inc. • rambus.com CONFIDENTIAL 13

Concurrent context • Adapter • PEC and PCL Adapter C source code

© Rambus Inc. • rambus.com CONFIDENTIAL 14

# tar -zxf Security-IP-197_DDK_vx.y.tar.gz

[INSTALL] Installing the DDK packages

Folder name Folder content

© Rambus Inc. • rambus.com CONFIDENTIAL 15

TestTools/TestSAToken • Test program for the SA Builder and Token Builder

© Rambus Inc. • rambus.com CONFIDENTIAL 16

Main Components Overview

© Rambus Inc. • rambus.com CONFIDENTIAL 17

© Rambus Inc. • rambus.com CONFIDENTIAL 18

3 Driver Customization Instructions

Interrupt Functionality Customization

© Rambus Inc. • rambus.com CONFIDENTIAL 19

3.1.1 AMP use case

3.1.2 SMP use case

© Rambus Inc. • rambus.com CONFIDENTIAL 20

3.1.3 Customizing combined driver

3.1.4 Customizing separate drivers

© Rambus Inc. • rambus.com CONFIDENTIAL 21

Driver Framework Customization

© Rambus Inc. • rambus.com CONFIDENTIAL 22

3.2.1 DMA-safe buffer allocation for kernel-space drivers

Kernel Support Driver

© Rambus Inc. • rambus.com CONFIDENTIAL 23

Kernel Support Driver UMDevXS configuration files can be found here:

3.4.1 DMA-safe buffer allocation for user-space drivers

Kernel Support Driver UMDevXS SMBuf implementation can be found here:

3.4.2 Shared device access protection for multiple applications

Customization for ARM platform

3.5.1 Device registration in Linux kernel

© Rambus Inc. • rambus.com CONFIDENTIAL 24

3.5.2 DMA buffers allocation and mapping to user space

© Rambus Inc. • rambus.com CONFIDENTIAL 25

DDK Kit Component DDK Integration Component

EIP-197 Combined Driver User-Space Deployment

Classification Test Tool Executable

Global Adapter PCL Adapter PEC Adapter

Linux kernel space