Getting Started

Introduction

The SDK is packaged as a Windows® installer (MSI) for Windows systems and an installable package, either RPM or DEB, for Linux® systems. The distribution includes object libraries, header files, online documentation, driver source code and command-line tools, and a visual development tool, called the AP Workbench.

Many development tasks can be completed using the executable command line tools for compilation and emulation.

The driver is distributed as source code to enable compilation against the Linux® kernel used on the target platform. The driver is compiled and installed automatically if GCC and the kernel headers are present on the target platform - see Linux® installation for details on compiling and installing the driver. Once the driver has been successfully compiled and installed the Runtime API may be used by deployed applications.

The Automata Processor (AP) may be programmed to recognize patterns through the use of expressions. Expressions are statements which describe the patterns. The SDK has built-in support for Perl-Compatible Regular Expressions (PCRE). PCRE expressions can be compiled by using the PCRE API and they can also be compiled using the command-line compiler.

The PCRE expression parser supports most of the PCRE syntax but has limitations in the areas of look-ahead, look-behind, back references, and named patterns. A complete list of syntax restrictions is provided here.

The Automata Processor (AP) may also be programmed to recognize patterns through the use of the "Automata Network Markup Language," or ANML. ANML allows the software programmer to explicitly describe how automata processing resources are connected together to recognize patterns. Based on XML, ANML contains a set of tags, i.e. elements and properties that represent each of the automata processing resources. Element properties describe, for instance, the states in the automata graph, their transitions, and their response to input.

The process of executing a search is outlined by 2 phases: compile-time and run-time. These phases can be further reduced as below:

  1. Compile time (devel package)
    • Parsing of regular expressions to create an Abstract Syntax Tree (AST).
    • Building a theoretical Non-deterministic Finite Automata (NFA) from the AST.
    • Alternatively, parsing an ANML file directly into a theoretical Non-deterministic Finite Automata (NFA).
    • Compilation, with optimizations into one or more subgraphs.
    • Placement and routing of the subgraphs and packaging into a container automaton.
    • Save the resultant automaton to a file for loading into the AP hardware.
  2. Runtime (base package)
    • Hardware initialization.
    • Loading of an automaton into the AP hardware.
    • Writing of data to the hardware (the data being searched against the regular expressions or ANML definition).
    • Responding to matches.

In most deployment scenarios the runtime package is the only item deployed in equipment using an AP. The restrictions on deployment of SDK components are detailed in the license section of this document.

Throughout the API the prefix "ap" or "AP" is used for function names and constants. This acronym stands for "Automata Processor". You will also see the term FRIO in the driver source, which is the codename for the first generation silicon AP device.

Installation

The Automata Processor SDK is licensed per machine. Per user installation is not possible on any of the supported platforms.

System Requirements

The SDK currently supports Intel processors. The minimum system requirements are:

  • Linux (CentOS v6, Ubuntu 14, SUSE 11) or the Windows 7 Operating systems
  • 64 bit kernel
  • 1Gbyte of disk space
  • 16Gbyte memory

Windows® Installation

Copy the apsdk MSI file onto the target machine, then double click on the MSI file to install all elements the SDK. Follow the prompts to install and activate the SDK.

Linux® Installation

The SDK is split over five packages, base, devel, Python bindings, Java bindings, and workbench. The base and devel packages are the only ones required for the runtime system or to develop AP applications in C. The others are optional, as described below.

The base package contains the runtime environment:

  • User-space shared libraries for linking to applications accessing the Runtime API Runtime API.
  • Private shared libraries.

The developer package contains:

  • User-space shared libraries (DLL in Windows) for linking to applications accessing the PCRE API, and ANML API.
  • User-space command line applications for: compiling regular expressions or ANML files, hardware emulation, and automata administration.
  • Help files in HTML and PDF format.
  • Header files for C++ and C programming languages.
  • Driver source. End users may redistribute a pre-built driver object but under no circumstances is the source redistributable. See the licensing section for further details.

The Python bindings package contains:

  • Python bindings for a subset of APIs.
  • Note that this package is only needed if you plan to create AP applications using Python instead of C.

The Java bindings package contains:

  • Java bindings for a subset of APIs.
  • An interface used by the workbench.
  • Note that this package is only needed for the workbench.

The workbench package contains:

  • A visual development environment.
  • A visual simulation tool.
  • Note that this package is only needed if you want to work in a visual development environment.

For RHEL6 or Centos distributions, copy the RPM packages onto the target machine and type:

1 yum -y install ap*.rpm

For Debian or Ubuntu distributions, copy the .deb packages onto the target machine and type:

1 sudo dpkg -i ap*.deb
2 sudo apt-get install -f

Notes:

  • Due to inter-package dependencies, the packages must be installed in the order shown above.
  • Installation of Linux package from a GUI is not supported.
  • If the installation fails due to missing dependencies, you can install the missing packages and configuring the APSDK by typing:
1 apt-get -f install

The devel package should install and compile the driver correctly provided the kernel build tree is present for the currently running kernel. You can build the driver anytime by executing the following commands from a root shell (not a user shell using sudo):

1 cd /usr/share/micron/ap/driver
2 make clean
3 make
4 make install

The default behavior of the driver is to dynamically allocate its major device number. This precludes use of mknod for a one time setup of the system node under /dev. The devel package includes the script apinsmod to correctly setup /dev. To load the driver and create the system node simply execute the script, with or without parameters, from a root shell.

If you wish to statically allocate the major device number then this can be done by the following module parameter:

1 mknod /dev/frio0 c <static-major-number> 0
2 modprobe -a ap major=<static-major-number>

Additionally, after the above static setup you may need to change group ownership and permissions for /dev/frio0 to ensure it is read/writeable by everyone. The apinsmod script does this automatically. Also make sure you use system node name /dev/frio0 as the runtime library assumes this to be the case.

After loading the driver you can verify driver setup by inspection of /proc/ap.

Linux® SDK Activation

Once the SDK has been installed, it must be activated. The SDK is activated by first acquiring a product key from Micron. A product key is acquired by going to the Micron AP Developer Portal where you will be able to create a Micron account and request a product key which will be returned via email. Once a product key has been acquired, use that key to register the SDK by using one of two utilities, either the helper script, apsdk_activate, or the apregister command line tool. NOTE: If there is no access to the internet from the system on which the SDK is installed, the SDK can be activated off-line. Refer to the apregister command line tool documentation for a description of how to register the SDK off-line.

Once a license is activated, it is valid for a predetermined amount of time based on the terms of the license. However, the license must be refreshed every 7 days. For both Windows and Linux, this refresh task is automatically scheduled when the SDK is installed. For Linux, this automatic refresh will only occur if the proxy configuration file, /etc/apsdk/proxy.conf, exists. As described below, this file can be created automatically using the apsdk_activate helper script method of activation. It is highly suggested that the helper script be used to activate the license. If apregister is used to activate the license, the proxy configuration file must be created by hand. It is important to note that if this file is not created, the automatic license refresh will not occur, and the license will become deactivated and must explicitly be refreshed via apregister.

The apsdk_activate helper script is an automated way to register the SDK and is recommended for most users. It is invoked as follows:

1 apsdk_activate

It will lead the user through the registration process by using the most appropriate method of registration, as follows.

  1. If there is an existing valid license, the user is informed as such and queried as to whether they wish to continue to use it. If not, a different product key can be specified.
  2. If a network proxy is not required, or a proxy has already been configured, or Web Proxy Auto Detect (WPAD) is supported, the user is simply queried for the product key.
  3. If a proxy must be configured, the user is queried as to whether the network supports Proxy Auto Configuration (PAC). If so, the user is queried for the URL of the PAC file. Otherwise, the user is queried for the URL of the proxy. After the proxy is configured, the user is queried for the product key.

Once the license is activated, this script will create the necessary proxy configuration file, /etc/apsdk/proxy.conf. No other action is required by the user.

The apregister command line tool can be used to activate or deactivate the SDK and allows proxy configuration to be specified on the command line. Note: Using apregister to configure proxy settings does not save any proxy configuration and is only recommended for advanced users. The proxy configuration file, /etc/apsdk/proxy.conf, must be manually created. See the sample, /etc/apsdk/proxy.conf.sample and follow the insructions in the file to specify proxy configuration.

Use apregister to configure the proxy, as follows.

If a network proxy is not required, register the SDK as follows:

1 apregister -v <productkey>

If a proxy is required then register the SDK using one of the following methods:

  1. Proxy auto configuration using WPAD (same as "Automatically detect settings" in Internet Explorer) – Note: WPAD is only supported via DNS:
    1 apregister -v \--wpad <productkey>
  2. Proxy auto configuration by specifying URL to PAC file (same as "Use automatic configuration script" in Internet Explorer):
    1 apregister -v \--autocfg=<PAC URL> <productkey>
  3. Proxy manual configuration
    1 apregister -v \--proxy=<url[:port]> <productkey>

    An optional user and password may be necessary for any of the methods of specifying a proxy
    1 apregister -v <proxy setting> \--proxy-user=<username> \--proxy-passwd=<password> <productkey>

Automatic Updates

Included with the SDK is an application that keeps your SDK installation current with the latest release. The application is installed to run as a service and will automatically download the most recent SDK if the current license is active. The update is not installed automatically. To check if an update is available run:

1 apupdate -Vv

Getting the latest update on Linux®

On Linux updates are stored in a local repository called apsdk. This repository is added to the distribution's package manager repo list during installation. To install the update follow the procedure for your Linux distribution.

Updating the SDK on CentOS or RHEL

1 yum update
2 yum upgrade apsdk

Updating the SDK on Ubuntu

1 apt-get update apsdk

Updating the SDK on SuSE

1 zypper ref apsdk
2 zypper update apsdk

Getting the latest update on Windows®

On Windows updates are stored in a local directory, "%ProgramData%\Micron\Automata Processor SDK". You can install the latest update, assuming it exists, by running apupdate with the install option:

1 apupdate -v --install