Hyperion F1 10G RegEx File Scan v5 - s3.amazonaws.com · Titan IC Getting Started Guide Hyperion F1...

Titan IC Systems Ltd

Northern Ireland Science Park

Unit 8, Innovation Centre

Queen’s Road

Queen’s Island

Belfast

United Kingdom

BT3 9DT

The information contained herein is the property of Titan IC Systems Ltd and is supplied without liability for

errors or omissions. No part may be reproduced or used except by contract or written permission. This is an

unpublished work in which the copyright vests with Titan IC Systems Ltd. All rights reserved.

PRIVATE & CONFIDENTIAL

Hyperion F1 10G RegEx File Scan v5.5

Getting Started Guide

Document Revision: 1.0

19 October 2017

Titan IC Getting Started Guide Hyperion F1 10G RegEx File Scan v5.5

i

Copyrights, Trademarks and Disclaimers

© 2015-2017 Titan IC Systems Ltd. All rights reserved. Titan IC Systems and RXP, and the associated logos are

trademarks or registered trademarks of Titan IC Systems Ltd. All other trademarks and service marks are the

property of their respective owners. All specifications subject to change without notice.

No part of this publication may be reproduced in any form (including photocopying or electronic storage on any

medium) or by any means or used to make any derivative work (such as translation, transformation or adaptation)

without the express written permission of Titan IC Systems Ltd.

Titan IC Systems Ltd reserves the right to revise this documentation and to make changes in content from time to time without obligation on the part of Titan IC Systems Ltd to provide notification of such revision or change.

Titan IC Systems Ltd provides this documentation without warranty of any kind, either implied or expressed,

including but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Titan

IC Systems Ltd may make improvements or changes to the product(s) and/or the program(s) described in this

document at any time.

Titan IC Systems Ltd

The Innovation Centre, Unit 8

Northern Ireland Science Park

Queen’s Road

Queen’s Island

Belfast, UK

BT3 9DT

Tel: +44 (0) 28 90 453512

Email: [email protected]

Web: www.titan-ic.com

mailto:[email protected]

http://www.titan-ic.com/


ii

Table of Contents

1. Introduction .................................................................................................................................................. 1 1.1. Scope .................................................................................................................................................... 1 1.2. Applicable and reference documents ...................................................................................................... 1 1.3. Terms and definitions ............................................................................................................................ 1 1.4. Acronyms .............................................................................................................................................. 1

2. Overview...................................................................................................................................................... 3 2.1. Software ................................................................................................................................................ 4

RXP Compiler ................................................................................................................................ 5 RXP evaluation utilities .................................................................................................................. 5

2.1.2.1. RXP Job Generator .................................................................................................................. 5 2.1.2.2. RXP Expected Match Generator .............................................................................................. 5

RXP API ........................................................................................................................................ 5 Hyperion reference applications ...................................................................................................... 5

2.1.4.1. hra ........................................................................................................................................... 5 2.1.4.2. hra_file_scan ........................................................................................................................... 5 2.1.4.3. hra_lite .................................................................................................................................... 5

RXP Linux kernel driver ................................................................................................................. 5 Tutorials ......................................................................................................................................... 5

2.2. Amazon EC2 instance/AMI ................................................................................................................... 6 2.3. Firmware ............................................................................................................................................... 6

AWS Shell ..................................................................................................................................... 6 RXP ............................................................................................................................................... 6

3. Launch instance and connect ......................................................................................................................... 8 3.1. Launch instance ..................................................................................................................................... 8 3.2. Linux - Connect to instance using a terminal ........................................................................................ 10 3.3. Windows - Connect to instance using PuTTY ...................................................................................... 10

4. System validation ....................................................................................................................................... 13 5. Additional reference applications ................................................................................................................ 16 6. Revision history.......................................................................................................................................... 17

List of Tables

Table 1-1: Terms and definitions. ..................................................................................................................... 1 Table 1-2: Acronyms. ....................................................................................................................................... 2 Table 2-1: Match tuple fields. ........................................................................................................................... 7

List of Figures

Figure 2-1: Hyperion development kit system architecture. ............................................................................... 4 Figure 2-2: RXP data flow diagram................................................................................................................... 6


1

1. Introduction

Hyperion F1 10G RegEx File Scan is the Amazon Web Services F1 instance based accelerator based on Titan

ICs’ Regular eXpression Processor (RXP) technology. Hyperion F1 10G RegEx File Scan is a fully EC2

instantiated version of the RXP targeted at file scanning applications in the cloud.

The RXP is a custom-purpose processor developed to efficiently process data to detect matches for a set of user-

defined string and regular expression (RegEx) based rules.

1.1. Scope

This document describes how to launch an instance using the Hyperion F1 10G RegEx File Scan AMI, connect

via Linux or Windows and validate the hardware platform and software development kit (SDK) supplied with the

Hyperion F1 10G RegEx File Scan release.

1.2. Applicable and reference documents

Hyperion F1 10G RegEx File Scan SDK Programmer’s Reference Manual.

Hyperion F1 10G RegEx File Scan User Guide.

1.3. Terms and definitions

The terms and definitions described in Table 1-1..

Term Definition

Hyperion The AWS F1 based RegEx accelerator based on Titan ICs’ RXP.

Job A unit of data for the RXP to scan. A job can be a packet, packet header, packet

payload, packet header and payload, or a block of user-defined data.

Jobset A set of jobs or packets to be scanned.

RegEx A common abbreviation for regular expression.

Regular expression A regular expression is a concise and flexible means for matching strings of text, such as particular characters, words, or patterns of characters. A common

abbreviation for this is “RegEx”.

ROF file Created by RXP Compiler. Contains object code used to program the rules

memories on the RXP.

ROFF file Created by RXP Compiler. Contains information required by the RXP Job

Generator to create embedded matches for a compiled ruleset.

ROFI file Created by RXP Compiler. Contains the minimum changes required to update

the RXP rules memories from one ruleset to another.

Ruleset A list of regular expressions and strings that can be compiled into object code

by the RXP Compiler and executed on the RXP.

RXP High-speed, hardware-accelerated regular expression accelerator.

Score table Mechanism used to validate matches detected by RXP.

Table 1-1: Terms and definitions.

1.4. Acronyms

The acronyms described in Table 1-2 are used in this document.

Acronym Meaning

AFI Amazon FPGA Image

AMI Amazon Machine Image

API Application Programming Interface

AWS Amazon Web Services

DDR4 Double Data Rate 4th generation

DMA Direct Memory Access

ESD Electrostatic Sensitive Device

FPGA Field Programmable Gate Array

HRA Hyperion Reference Application


2

IP Intellectual Property

LFM Linear Feet per Minute

NGFW Next Generation Firewall

PC Personal Computer

PCAP Packet CAPture

PCIe Peripheral Component Interconnect Express

PCRE Perl Compatible Regular Expression

PMD Poll Mode Driver

POSIX Portable Operating System Interface for uniX

RAM Random Access Memory

RE Regular Expression

ROF RXP Object Format

ROFF RXP Object Format Full

ROFI RXP Object Format Incremental

RXP Regular eXpression Processor

RXPC RXP Compiler

RXPE RXP Expected match generator

RXPF RXP Flash Programmer

RXPI RXP Info

RXPJ RXP Job generator

SDK Software Development Kit

SDN Software Defined Networks

SSH Secure Shell

USB Universal Serial Bus

Table 1-2: Acronyms.


3

2. Overview

The Hyperion regular expression accelerator product is a high-performance, highly versatile content processing

solution for demanding and complex content analysis tasks. Hyperion F1 10G RegEx File Scan is targeted towards

file scanning and can inspect data at a rate of up to 10 Gb/s. It is ideal for big-data analytics applications. 20 Gb/s

and 40 Gb/s variants are available from Titan IC as a Hyperion PCIe card.

The key features of Hyperion F1 10G RegEx File Scan include:

• Up to 10 Gb/s throughput enabled by scalable, special-purpose, multi-character data path.

• Cross packet inspection support (application level).

• POSIX/PCRE regular expressions.

• Hyperion SDK with RXP Compiler, evaluation utilities, RXP API/driver and reference applications.

• Provided as a ready-to-go AMI within the Amazon Marketplace.

At the heart of Hyperion F1 10G RegEx File Scan is the RXP (Regular eXpression Processor) IP block developed

by Titan IC, which provides hardware-based RegEx acceleration.

The Hyperion development kit enables the development of applications around the RXP designed to be hosted on

an AWS F1 instance. Figure 2-1 shows a high-level view of the Hyperion development kit system architecture.

This also highlights the interconnectivity between blocks.


4

Figure 2-1: Hyperion development kit system architecture.

As can be seen from Figure 2-1, the Hyperion development kit is comprised of software, hardware, and firmware

components:

• Software – the Hyperion Software Development Kit (SDK) including reference applications, utilities,

tutorials, and source code examples for the development of user applications using the RXP. For more

information see Section 2.1.

• Hardware – the Amazon EC2 f1.2xlarge instance, a VM partnered with a Xilinx UltraScale+ VU9P

FPGA. For further details see Section 2.2.

• Firmware – an FPGA bitstream implementing the RXP in conjunction with the Amazon F1 Shell. For

more information see Section 2.3.

2.1. Software

The main software blocks in the Hyperion development kit are discussed in the following sections.


5

RXP Compiler

The RXP Compiler (rxpc) is used to convert a set of RegExes in a rules file into a RXP Object Format (ROF)

file which is used to program the rules memories on the RXP.

RXP evaluation utilities

Two evaluation utilities are provided that can be used to validate the operation and performance of the RXP.

2.1.2.1. RXP Job Generator

The RXP Job Generator (rxpj) is used to create a set of sample jobs containing embedded matches for a set of

rules. These manufactured jobs can be dispatched to the RXP and the responses examined to ensure that matches

are detected.

2.1.2.2. RXP Expected Match Generator

The RXP Expected Match Generator (rxpe) is used to identify all the matches in a jobset. The rxpj embeds

matches for specific rules in jobs. However, when there are similar rules, a single job may contain matches for

multiple rules. The rxpe uses PCRE to examine the jobs and identify all the matches that should be detected.

Due to slight differences in the way that PCRE and the RXP are implemented, it is possible that the expected

matches generated by rxpe may not entirely reflect the matches returned by the RXP.

RXP API

A lightweight user space API is provided which allows an application to communicate with the RXP. The API

functions are implemented in the librxpapi library. This library and the associated development files are pre-

installed in the Hyperion AMI. Additionally, the source code and RPMs are provided, which allows customization

if required.

Hyperion reference applications

Several reference applications have been supplied that can be used to validate the operation of the RXP. These

show how to use the RXP API to submit jobs and receive responses detailing any matches found.

2.1.4.1. hra

The Hyperion Reference Application (hra) programs the RXP rules memories using a ROF file created by rxpj.

It dispatches jobs created by rxpj to the RXP and compares matches with expected matches generated by rxpe.

2.1.4.2. hra_file_scan

The hra_file_scan application is used to examine a large file for matches. The RXP supports jobs with a

maximum length of 16384 bytes. To inspect a large file, the file is broken into overlapping jobs.

2.1.4.3. hra_lite

This is a simple application that shows the basic steps required to configure the RXP, dispatch jobs to the RXP

and receive responses. Random sized jobs are created and dispatched to the RXP in a loop.

RXP Linux kernel driver

The RXP API communicates with the RXP via a kernel driver. This driver is provided as a pre-installed DKMS

RPM package, allowing for automatic rebuilding when the base kernel in the AMI needs to be updated, e.g. for

security fixes. The driver handles communication over the PCIe bus to the EDMA block contained within the

AWS Shell. It is responsible for efficiently transferring jobs to the RXP and receiving the responses for the

application to process.

Tutorials

Several tutorials are provided which explain the usage of the rxpc, evaluation utilities and Hyperion reference

applications. Some of these tutorials use complex rulesets to demonstrate the capabilities of the RXP.


6

2.2. Amazon EC2 instance/AMI

The Hyperion development kit is supplied as a EC2 AMI with the appropriate driver and development packages

pre-installed. This is designed to run on an EC2 f1.2xlarge instance and is built on top of the Amazon Linux

2017.09.0 AMI.

Amazon’s f1.2xlarge EC2 instance has the following features:

• Xilinx UltraScale+ VU9P FPGA

• 64GB DDR4 FPGA memory

• Dedicated PCIe x16 interface to CPU

• 8 E5-2686 v4 cores

• 122GB CPU memory

2.3. Firmware

The main blocks within the firmware are discussed in the following sections.

AWS Shell

The AWS Shell is the part of the FPGA image that is provided and managed by AWS. It includes portions such

as dealing with the PCIe interface, FPGA image download and the EDMA engine.

RXP

The RXP comprises multiple customized pipelined engines to scan data against a user-defined set of regular

expression and/or string-based rules. The rules are compiled using the RXP Compiler, and programmed/loaded

into the RXP’s rules memories. Data to be scanned is provided as jobs, and a response is returned for every

scanned job (see Figure 2-2).

Figure 2-2: RXP data flow diagram.

The term job refers to a block of data and can be one of the following: a packet payload, a packet header, a complete packet, or a document file. A job is presented to the device with a job identifier (JOB_ID), a

JOB_LENGTH field to indicate how many bytes are in the job, and the job data to be scanned. The RXP provides

a response for each scanned job with a JOB_ID so that the response can be cross-referenced in the calling

application. The RXP can scan up to 128 jobs simultaneously and support thousands of searches (or threads) active

at any one time.

Each rule is split into a prefix and a factor. For example, if a rule is /ABCDEF.*XYZ/, ABCD is considered the

prefix, and EF.*XYZ is considered the factor. The prefix is a literal string, while the factor can contain complex

regular expression constructs. Thus, rule matching occurs in two stages: prefix matching and factor matching.

Prefix matching is performed by the prefix engine, which can detect prefixes at any byte offset within the incoming

job data words. On detecting a prefix match, a thread is spawned in an available thread control engine, consisting

of a series of RISC-like instructions by the thread control engine's associated thread processing engine to confirm the job data matches a rule's factor to become a full match. Some instructions are stored in the device's embedded


7

memories, while others are stored in external DDR4 memory and cached into the embedded memory when

required. The instructions can consume up to 8 bytes at-a-time, thus enabling very high-performance matching.

The response indicates how many matches (MATCH_COUNT) were detected in the job for the rules programmed

into the RXP’s rules memories and a list of match tuples, where a match tuple consists of the following fields

given in Table 2-1.

Field Description

JOB_ID Job identifier.

RULE_ID RXP rule identifier for match rule.

START_PTR Byte position in job where match started.

LENGTH Length of match in bytes.

Table 2-1: Match tuple fields.


8

3. Launch instance and connect

The Hyperion SDK will be supplied pre-installed and configured in the Hyperion F1 10G RegEx File Scan AMI.

The steps required to setup, validate, and execute a Hyperion F1 10G RegEx File Scan AMI can be found below.

NOTE: The “1-Click Launch” will NOT work, please use the “Manual Launch” instead as detailed below.

3.1. Launch instance

1. Open the AWS Marketplace in a web browser and login.

2. Navigate to the Hyperion F1 10G RegEx File Scan page and click “Continue”.

3. When you agree to the terms click “Manual Launch” and then “Launch with EC2 Console” in your

desired region.


9

4. Select the f1.2xlarge instance and click “Review and Launch”.

5. Review the instance launch details and click “Launch”.


10

6. Create and download a SSH key to use when connecting to the instance.

7. Ensure to note down your instance ID as you will need it to identify your instance.

3.2. Linux - Connect to instance using a terminal

1. Navigate to the EC2 Dashboard and click the “Running Instances” link.

a. This will list all the running instances.

2. Locate the IP address to use for SSH for your instance in the “IPv4 Public IP” column.

a. Note down this IP address to use to connect to the instance.

3. Open a terminal and run the following command to SSH into your instance:

ssh -i my-key-pair.pem ec2-user@IP_ADDRESS

3.3. Windows - Connect to instance using PuTTY

To complete the following steps you need to install PuTTY and PuTTYgen. The installer can be found at the

following location:

https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html


11

1. Navigate to the EC2 Dashboard and click the “Running Instances” link.

a. This will list all the running instances.

2. Locate the IP address to use for SSH for your instance in the “IPv4 Public IP” column.

a. Note down this IP address to use to connect to the instance.

3. Launch PuTTYgen, click the “Load” button and filter by “All files”. Load the key downloaded in step

6 in section 3.1.

4. Click “Save private key” and select yes to save it without a passphrase.


12

5. Launch PuTTY and navigate to Connection -> SSH -> Auth. Click the “Browse” button and load the

private key saved in the previous step.

6. Navigate to Session and type the IP address obtained in step 2 into the “Host Name (or IP address)”

box.

7. When prompted “login as:” type “ec2-user” and press return.


13

4. System validation

The Hyperion SDK contains a simple script that demonstrates basic utilization of the RXP Compiler, tools and

hra. It is in the hra folder. To run the script, use the following commands:

The script is a shell script with the following contents:

The script first deletes any files left over from previous runs. It then creates the folders necessary for running the

tests:

A rules file will be created and placed in the ruleset folder. The rules file will be compiled and the output files

will be placed in the rof folder. A set of jobs will be created with embedded matches for the rules file and these

will be placed in the jobset folder.

The script then creates a rules file called ruleset/synthetic.rules using this command:

echo "1,/hello\s+world/" > ruleset/synthetic.rules

The rules file contains a single rule that matches the RegEx:

hello\s+world

The RXP Compiler (rxpc) is then called to convert the rules file into a RXP Object Format (ROF) file that can

be used to program the rules memories on the RXP. The command used is:

[ec2-user@ip-172-31-67-22 ~]$ cd rxp-api-examples/hra

[ec2-user@ip-172-31-67-22 hra]$ make

[ec2-user@ip-172-31-67-22 hra]$ ./run.sh

#!/bin/bash -e

# Copyright (C) 2015-2017 Titan IC Systems Ltd. All rights reserved.

rm -rf ruleset/ rof/ jobset/

mkdir -p ruleset

mkdir -p rof

mkdir -p jobset

# If HYPERION_PORT is set as an environment variable then use it.

# Else use the default port (0).

: ${HYPERION_PORT=0}

# Create a simple rules file, with a single rule "hello\s+world"

echo "1,/hello\s+world/" > ruleset/synthetic.rules

# Compile the rules file. All output files will be prefixed by "rof/synthetic"

rxpc -f ruleset/synthetic.rules -o rof/synthetic

# Using the rules, generate a jobset with 1000 jobs (-j 1000), each with an embedded match

# (-m 1000). The jobs will have a fixed length of 16384 bytes (-f -l 16384). Put the jobs

in

# the jobset/synthetic/ folder.

rxpj -r rof/synthetic.roff -o jobset/synthetic -f -l 16384 -j 100 -m 100

# Use PCRE to establish the expected matches for the job

rxpe -l rof/synthetic_rule_id_lookup_table.csv -j jobset/synthetic

# Run the hra application on a single thread (-c 1). Use the Hyperion port (-p

${HYPERION_PORT}).

# Program the RXP rules memories using the ROF file created by rxpc (-f rof/synthetic.rof)

# Scan the jobs in the created jobset (-j jobset/synthetic) with the RXP 10000 times (-i

10000).

sudo ./hra -c 1 -p ${HYPERION_PORT} -i 10000 -j jobset/synthetic -f rof/synthetic.rof

jobset/

rof/

ruleset/


14

rxpc -f ruleset/synthetic.rules -o rof/synthetic

The -f ruleset/synthetic.rules option tells rxpc which rules file to compile. The -o

rof/synthetic option tells rxpc to prefix all files it creates with rof/synthetic. The rxpc creates

several output files, including synthetic.rof. This is a RXP Object Format file, which is used to program

the RXP rules memories

The rxpj utility is then used to generate a jobset which can be used to test the RXP. A job set consists of a

number of jobs containing matches for the rules in the rules file. The command used to create the job set is:

rxpj -r rof/synthetic.roff -o jobset/synthetic -f -l 16384 -j 100 -m 100

The –j 100 argument tells rxpj to create a jobset with 100 jobs. The -r rof/synthetic.roff argument

tells rxpj which Rules Object Format Full (ROFF) file it should use to generate the jobset. The ROFF file is

created by rxpc and contains information which rxpj requires to embed matches. The -o

jobset/synthetic argument tells rxpj which directory to put the jobset in. The -l 16384 options tells

rxpj to create jobs of 16384 bytes in length. The -f option tells rxpj to use jobs of a fixed length. Without this

option random length jobs would be created with an average length specified by the -l option. Finally the -m

1000 option tells rxpj to embed a match in every job.

Each job created by rxpj consists of a job data file (.pkt), a descriptor file (.des) and an embedded matches

file (.emb).

After the jobset has been created the rxpe utility is used to scan the jobs created by rxpj using PCRE. The

rxpj application embeds a single match in each job. However, individual jobs may contain multiple matches

including some that were not deliberately embedded. The rxpe application identifies all matches that the RXP

should find in the jobs.

rxpe -l rof/synthetic_rule_id_lookup_table.csv -j jobset/synthetic

The -l rof/synthetic_rules_id_lookup_table.csv tells rxpe where it can find a lookup file

required in the match generation. The file is an output of rxpc. The -j jobset/synthetic option tells

rxpe where the job files are located. For each job rxpe creates a .exp file containing a list of expected matches.

Finally, the hra application is run as follows:

sudo ./hra -c 1 -i 10000 -j jobset/synthetic -f rof/synthetic.rof

The hra programs the RXP using the ROF file generated by rxpc. It loads the jobs created by rxpj and

dispatches these to the RXP. The RXP returns responses containing matches and these are compared with the

expected matches generated by rxpe.

When the hra is run the tail of the output should be like the following:


15

The most significant lines are:

Info: Score_table(7:0) = {1000000, 0, 0, 0, 0, 0, 0, 0}, unexpected_matches = 0

And:

Info: Throughput : 10.661 Gbps

These lines show that all expected matches were detected, and the throughput achieved by the RXP. The throughput is the rate at which the RXP can process job data. For further information please consult the Hyperion

F1 10G RegEx File Scan User Guide.

Info: HRA statistics ==================================================================

Info: Statistics for queue 0 ----------------------------------------------------------

Info: Jobs scanned : 1000000 Tx busy : 320784

Info: Valid responses : 1000000 Invalid responses : 0

Info: Job retransmits : 0 Job timeouts : 0

Info: Latency min (s) : 67416.000000 Latency max (s) : 624601.000000

Info: Latency avg (s) : 445795.030281


=======================================================================================

Info: Aggregate HRA statistics --------------------------------------------------------

Info: Jobs scanned : 1000000 Tx busy : 320784

Info: Valid responses : 1000000 Invalid responses : 0

Info: Job retransmits : 0 Job timeouts : 0


=======================================================================================

=======================================================================================

Info: Statistics read from RXP

Info: The number of jobs, responses, matches and errors are 32 bit values and may wrap

Info: The number of job_bytes is a 64 bit value

Info: Number of jobs : 1000000

Info: Number of responses : 1000000

Info: Number of matches : 1000000

Info: Number of job bytes : 16384000000

Info: Number of job errors : 0

Info: Byte match ratio : 0.0013

Info: Elapsed time : 12.294 seconds

Info: Throughput : 10.661 Gbps

=======================================================================================


16

5. Additional reference applications

Several additional reference applications are provided as part of the SDK. These are documented in the Hyperion

F1 10G RegEx File Scan SDK Programmer’s Reference Manual.

cd ~/rxp-api-examples

cd ./hra_file_scan

make

cd ../hra_lite

make


17

6. Revision history

Date Revision Description of change Originator Reference

2017/10/13 0.9 Initial document structure and template. TICS N/A

2017/10/19 0.91 Added details on launching connecting to instance. TICS N/A

2017/10/19 1.0 Official release. TICS N/A

Hyperion F1 10G RegEx File Scan v5 - s3.amazonaws.com · Titan IC Getting Started Guide Hyperion F1...

Documents

Transcript of Hyperion F1 10G RegEx File Scan v5 - s3.amazonaws.com · Titan IC Getting Started Guide Hyperion F1...