Runtime API

Modules

 Constants
 
 Compile Time Reporting
 Used for reporting compile time statistics to the caller of API's.
 
 Runtime Error Codes
 All functions within the Runtime API, with the exception of AP_GetVersionString() and AP_GetMatches(), return zero on success or a negative integer on error.
 
 Automaton Status Codes
 

Data Structures

struct  ap_device_metrics
 Parameters describing a physical device. More...
 
struct  ap_load_region
 A load region is a partition of D480 on the physical device where automata can be loaded. More...
 
struct  ap_device_config
 The load region configuration for the physical device. More...
 
struct  ap_load_region_info
 Query load region information for the physical device. More...
 
struct  ap_flow_chunk
 A segment of data pertaining to a particular flow. More...
 
struct  ap_flow_data
 Vectorized data input used as the subject of a search. More...
 
struct  ap_match_result
 Information relating to a ANML or PCRE match result. More...
 
struct  ap_pattern_match
 The structure to store match results for an approximate string match. More...
 
struct  ap_completion
 Opaque structure used for wait operations. More...
 
struct  ap_performance_info
 Performance information for a match group. More...
 
struct  ap_automaton_info
 Automaton information. More...
 
struct  ap_rto_share_list
 Structure for holding share names. More...
 
struct  ap_symbol_change
 Symbol change specification. More...
 
struct  ap_counter_change
 Counter change specification. More...
 

Typedefs

typedef struct ap_device_objref * ap_device_t
 Opaque object for a logical device.
 
typedef struct ap_rto_objref * ap_rto_t
 Opaque object for storing a runtime object.
 
typedef struct ap_flow_objref * ap_flow_t
 Opaque flow object mapping disjoint data chunks to a contiguous array of bytes.
 
typedef struct ap_match_group_objref * ap_match_group_t
 Opaque object for monitoring the performance of match event processing. More...
 

Enumerations

enum  ap_load_mode_t { AP_STANDARD_LOAD = 0x00, AP_REPLICATE_LOAD = 0x01, AP_HOTSWAP_LOAD = 0x81 }
 Load region mode. More...
 
enum  ap_device_type_t {
  DEVICE_TYPE_UNKNOWN = 0, DEVICE_TYPE_LB = 1, DEVICE_TYPE_PCIE = 2, DEVICE_TYPE_USB = 3,
  DEVICE_TYPE_LB_SIM = 4, DEVICE_TYPE_PCIE_SIM = 5
}
 Physical device types. More...
 

Functions

AP_API int AP_QueryDeviceCount (unsigned *count)
 Query the number of physical devices on the system. More...
 
AP_API int AP_QueryDeviceMetrics (struct ap_device_metrics *metrics, const char *devName)
 Query the metrics for all physical devices. More...
 
AP_API int AP_ConfigureDevice (const char *dev_name, const struct ap_device_config *config)
 Configure the physical device by partitioning the ranks of D480 into load regions. More...
 
AP_API int AP_QueryDeviceConfig (const char *dev_name, struct ap_device_config *config)
 Get the number of load regions defined for physical devices. More...
 
AP_API int AP_GetLoadRegionInfo (ap_device_t dev, unsigned loadRegionId, struct ap_load_region_info *inf)
 Query information relating to a load region. More...
 
AP_API int AP_OpenDevice (ap_device_t *dev, const char *dev_name, int sv_reserve)
 Open a logical device connecting the running application and the configured physical device. More...
 
AP_API int AP_CloseDevice (ap_device_t dev)
 Close a logical device. More...
 
AP_API int AP_OpenFlow (ap_device_t dev, ap_flow_t *flow, ap_rto_t rto, void *uparam)
 Open a flow against the runtime object. More...
 
AP_API int AP_CloseFlow (ap_device_t dev, ap_flow_t flow)
 Close a flow. More...
 
AP_API int AP_ScanFlows (ap_device_t dev, struct ap_flow_data *flow_data, unsigned flow_data_count, struct ap_completion *complete)
 Perform a vectored search on a logical device. More...
 
AP_API int AP_GetMatches (ap_device_t dev, struct ap_match_result *results, unsigned max_results)
 Get match results due to a call to AP_ScanFlows(). More...
 
AP_API int AP_Wait (ap_device_t dev, struct ap_completion *complete, unsigned timeout)
 Sleep until the operation referenced by complete has completed. More...
 
AP_API int AP_GetDeviceFd (ap_device_t dev, int *fd)
 Get the file descriptor for the logical device. More...
 
AP_API int AP_ProcessStringMatch (ap_device_t dev, ap_encode_info_t encode_info, struct ap_flow_data *flow_data, unsigned flow_data_count, struct ap_completion *complete)
 Process input string through search automaton loaded device. More...
 
AP_API int AP_GetStringMatches (ap_device_t dev, ap_encode_info_t encode_info, struct ap_pattern_match *results, unsigned max_results)
 Get string matches from processed device. More...
 
AP_API int AP_GetInfo (ap_automaton_t amton, struct ap_automaton_info *inf, int subgraphId)
 Get the status information of an automaton. More...
 
AP_API int AP_Destroy (ap_automaton_t amton)
 Destroy an automaton and free all internal resources. More...
 
AP_API int AP_Save (const ap_automaton_t amton, file_descriptor_t fd)
 Save the automaton to a file referenced by the file descriptor 'fd'. More...
 
AP_API int AP_Restore (ap_automaton_t *amton, file_descriptor_t fd)
 Restore a automaton from a file referenced by the file descriptor 'fd'. More...
 
AP_API int AP_Load (ap_device_t dev, ap_rto_t *rto, unsigned load_region, ap_automaton_t amton, void *aparam, const char *share_name)
 Load an automaton into a load region. More...
 
AP_API int AP_LoadEx (ap_device_t dev, ap_rto_t *rto, unsigned load_region, ap_automaton_t *amta, unsigned amta_count, void *aparam, const char *share_name)
 Load the automaton into a load region. More...
 
AP_API int AP_Unload (ap_device_t dev, ap_rto_t rto)
 Unload the runtime object referenced by rto. More...
 
AP_API int AP_ReleaseShare (ap_device_t dev, ap_rto_t rto)
 Unshare the runtime object referenced by rto. More...
 
AP_API int AP_GetShareNames (ap_device_t dev, struct ap_rto_share_list *share_list)
 Get the list of RTO shares currently available. More...
 
AP_API int AP_CalcLoadSize (unsigned *load_size, ap_automaton_t *amta, unsigned amta_count)
 Calculate the number of D480 required for a given set of automata. More...
 
AP_API int AP_Duplicate (ap_automaton_t amton, ap_automaton_t *amtondup, int subgraphId)
 Duplicate an automaton. More...
 
AP_API int AP_UnionRto (ap_device_t dev, ap_rto_t *rto, ap_rto_t *rtos, unsigned rto_count, void *aparam, const char *share_name)
 Create a new runtime object that contains other runtime objects. More...
 
AP_API int AP_Find (ap_device_t dev, ap_rto_t *rto, void *aparam, const char *share_name)
 Locate the runtime object by using the unique system wide name. More...
 
AP_API int AP_SetSymbol (ap_automaton_t fsm, ap_element_map_t map, struct ap_symbol_change *changes, unsigned changeCount)
 Sets the symbols for each element reference in the changes array. More...
 
AP_API int AP_SetSymbolSame (ap_automaton_t fsm, ap_element_map_t map, ap_anml_element_ref_t *element_refs, unsigned elementCount, const char *symbol_set, ap_macro_param_ref_t *param_refs)
 Sets the symbols for each element reference in the element_refs array. More...
 
AP_API int AP_SetCounterTarget (ap_automaton_t fsm, ap_element_map_t map, struct ap_counter_change *changes, unsigned changeCount)
 Sets the counter targets for each element reference in the changes array. More...
 
AP_API int AP_SetCounterTargetSame (ap_automaton_t fsm, ap_element_map_t map, ap_anml_element_ref_t *element_refs, unsigned elementCount, unsigned target, ap_macro_param_ref_t *param_refs)
 Sets the counter target for each element reference in the element_refs array. More...
 
AP_API int AP_Reload (ap_device_t dev, ap_rto_t rto, ap_automaton_t fsm)
 Reloads the automaton onto a device. More...
 

Detailed Description

The programming interface for executing Automata.

All functions within the Runtime API, with the exception of AP_GetVersionString() and AP_GetMatches(), return zero on success or a negative integer on error.

#include <micron/ap/ap_error.h>
#include <micron/ap/ap_exec.h>
#include <micron/ap/ap_load.h>
#include <micron/ap/ap_element_map.h>

All functions operating on a logical device require the logical device as the first parameter to the function. No function within the Runtime API operates on multiple logical devices.

It is recommended the programmer read the Runtime Programmers Reference before attempting to use the API.

All API functions are thread safe and reentrant, however for performance reasons not all API objects are thread safe. This restriction does not limit use of the API in a multi-threaded environment, it merely enforces sane rules which the programmer would have most likely followed without guidance. Please refer to the section on thread safety for more information.