CAM API Documentation
 All Data Structures Files Functions Typedefs Enumerations Enumerator Groups Pages
Macros | Enumerations | Functions
Configuration Parameters and Error Codes

Overview

A cam_arg handle is passed to bcam_create(), vbcam_create(), stcam_create() or tcam_create(). cam_arg contains all the configuration parameters. First cam_arg_create() is called to allocate memory for the cam_arg. cam_arg_create() returns the cam_arg_handle(). The handle is used for all the set and force functions, which sets the parameters. Once all parameters are set, one of bcam_create(), vbcam_create, stcam_create() or tcam_create() is called. The cam_arg is copied by these functions, so cam_arg_destroy() can be called immediately after. VBCAMs and BCAMs support optional arguments. These arguments contains additional control information. These options can be set using the cam_options_set_** functions.

Macros

#define CAM_DEBUG_NONE
 
#define CAM_OPTIMIZE_NONE
 

Enumerations

enum  cam_errnos { ,
  CAM_ERROR_FORMAT_SYNTAX,
  CAM_ERROR_TOO_MANY_FIELDS,
  CAM_ERROR_TOO_MANY_RANGES,
  CAM_ERROR_INVALID_RANGE_LEN,
  CAM_ERROR_INVALID_RANGE_START,
  CAM_ERROR_INVALID_PREFIX_LEN,
  CAM_ERROR_INVALID_PREFIX_START,
  CAM_ERROR_INVALID_PREFIX_KEY,
  CAM_ERROR_INVALID_BIT_FIELD_LEN,
  CAM_ERROR_INVALID_BIT_FIELD_START,
  CAM_ERROR_INVALID_CONST_FIELD_LEN,
  CAM_ERROR_INVALID_CONST_FIELD_START,
  CAM_ERROR_INVALID_UNUSED_FIELD_LEN,
  CAM_ERROR_INVALID_UNUSED_FIELD_START,
  CAM_ERROR_MAX_KEY_LEN_EXCEED,
  CAM_ERROR_INVALID_PRIO_AND_INDEX_WIDTH,
  CAM_ERROR_TOO_MANY_UNITS,
  CAM_ERROR_NO_MASK,
  CAM_ERROR_INVALID_MEMORY_WIDTH,
  CAM_ERROR_UNSUPPORTED_COMMAND,
  CAM_ERROR_ENVIRONMENT,
  CAM_ERROR_UNSUPPORTED_CAM_TYPE,
  CAM_ERROR_NULL_POINTER,
  CAM_ERROR_TOO_MANY_PCS,
  CAM_ERROR_CONFIGURATION,
  CAM_ERROR_ENVIRONMENT_FSMBUSY,
  CAM_ERROR_ENVIRONMENT_POLLED_OUT,
  CAM_ERROR_SEGMENT_COUNT_ZERO,
  CAM_ERROR_VC_UNSUPPORTED_COMMAND,
  CAM_ERROR_WRONG_VIRTUAL_CAM_ID,
  CAM_ERROR_WRONG_SEGMENT_NUMBER,
  CAM_ERROR_TOO_MANY_RAMS,
  CAM_ERROR_FOUND_IN_SHADOW_BUT_NOT_IN_HW,
  CAM_ERROR_TOO_SMALL_HEAP,
  CAM_ERROR_RAM_TOO_SMALL,
  CAM_ERROR_NOT_EMPTY,
  CAM_ERROR_STATISTICS_NOT_AVAILABLE
}
 

Functions

int cam_arg_create (cam_arg_t **out_cam_arg)
 
void cam_arg_init (cam_arg_t *out_cam_arg)
 
size_t cam_arg_size (void)
 
void cam_arg_destroy (cam_arg_t *cam_arg)
 
int cam_arg_set_format (cam_arg_t *cam_arg, char *format)
 
void cam_arg_set_inst_ctx (cam_arg_t *cam_arg, void *inst_ctx)
 
void cam_arg_set_hw_write_function (cam_arg_t *cam_arg, void(*hw_write_function)(void *, uint32_t, uint32_t))
 
void cam_arg_set_hw_read_function (cam_arg_t *cam_arg, void(*hw_read_function)(void *, uint32_t, uint32_t *))
 
int cam_arg_set_hw_io (cam_arg_t *cam_arg, unsigned hw_block, void(*hw_write_function)(void *, uint32_t, uint32_t), void(*hw_read_function)(void *, uint32_t, uint32_t *))
 
void cam_arg_set_num_entries (cam_arg_t *cam_arg, uint32_t num_entries)
 
void cam_arg_set_engine_lookup_rate (struct cam_arg_t *cam_arg, float lookup_rate)
 
void cam_arg_set_lookup_interface_freq (struct cam_arg_t *cam_arg, float freq)
 
void cam_arg_set_ram_freq (struct cam_arg_t *cam_arg, float freq)
 
void cam_arg_set_response_width (struct cam_arg_t *cam_arg, uint16_t response_width)
 
void cam_arg_force_prio_width (struct cam_arg_t *cam_arg, uint8_t prio_width)
 
void cam_arg_set_key_width (struct cam_arg_t *cam_arg, uint16_t key_width)
 
void cam_arg_set_fingerprint_width (struct cam_arg_t *cam_arg, uint16_t fingerprint_width)
 
void cam_arg_set_num_masks (struct cam_arg_t *cam_arg, uint8_t num_masks)
 
void cam_arg_force_num_units (struct cam_arg_t *cam_arg, uint16_t num_units)
 
void cam_arg_force_mem_type (struct cam_arg_t *cam_arg, bool uram)
 
void cam_arg_set_max_num_brams (struct cam_arg_t *cam_arg, uint16_t max_num_brams)
 
void cam_arg_set_max_num_urams (struct cam_arg_t *cam_arg, uint16_t max_num_urams)
 
void cam_arg_set_max_macro_height (struct cam_arg_t *cam_arg, uint8_t max_macro_height)
 
void cam_arg_set_device_arch (struct cam_arg_t *cam_arg, bool versal)
 
void cam_arg_force_hbm (struct cam_arg_t *cam_arg)
 
void cam_arg_set_narrow_key_width (struct cam_arg_t *cam_arg, uint16_t narrow_key_width)
 
void cam_arg_set_max_hw_writes (struct cam_arg_t *cam_arg, uint16_t max_hw_writes)
 
void cam_arg_set_flow_control (struct cam_arg_t *cam_arg, bool flow_control)
 
void cam_arg_set_aging (struct cam_arg_t *cam_arg, bool aging)
 
void cam_arg_set_default_response (struct cam_arg_t *cam_arg, const uint8_t *default_response)
 
void cam_arg_set_narrow_default_response (struct cam_arg_t *cam_arg, const uint8_t *narrow_default_response)
 
void cam_arg_set_vcid (struct cam_arg_t *cam_arg, uint8_t vcid)
 
void cam_arg_set_seg (struct cam_arg_t *cam_arg, uint16_t segment_id)
 
void cam_arg_set_hw_write_sequence_functions (cam_arg_t *cam_arg, void(*start_function)(void *), void(*end_function)(void *))
 
void cam_arg_set_debug_flags (cam_arg_t *cam_arg, uint32_t debug_flags)
 
void cam_arg_set_optimization_flags (cam_arg_t *cam_arg, uint32_t optimization_flags)
 
void cam_arg_enable_options (cam_arg_t *cam_arg)
 
void cam_arg_force_asic_ram (struct cam_arg_t *cam_arg)
 
void cam_arg_force_dram (struct cam_arg_t *cam_arg)
 
void cam_arg_set_ram_size (struct cam_arg_t *cam_arg, uint32_t size)
 
void cam_arg_set_hash_function (struct cam_arg_t *cam_arg, uint8_t function)
 
void cam_arg_set_siphash_key (struct cam_arg_t *cam_arg, uint64_t k0, uint64_t k1)
 
void cam_arg_set_num_banks (struct cam_arg_t *cam_arg, uint8_t num_banks)
 
void cam_arg_set_channel_width (struct cam_arg_t *cam_arg, uint16_t width)
 
void cam_arg_set_generation_number_granularity (struct cam_arg_t *cam_arg, uint16_t granularity)
 
void cam_arg_calc_heap_size (struct cam_arg_t *cam_arg, bool calculate)
 
void cam_arg_set_error_print_function (struct cam_arg_t *cam_arg, void(*error_print_function)(void *, char *))
 
void cam_arg_set_info_print_function (struct cam_arg_t *cam_arg, void(*info_print_function)(void *, char *))
 
void cam_arg_set_malloc_function (struct cam_arg_t *cam_arg, void *(*malloc_function)(size_t size))
 
void cam_arg_set_posix_memalign_function (struct cam_arg_t *cam_arg, int(*posix_memalign_function)(void **ptr, size_t align_size, size_t num))
 
void cam_arg_set_realloc_function (struct cam_arg_t *cam_arg, void *(*realloc_function)(void *ptr, size_t size))
 
void cam_arg_set_calloc_function (struct cam_arg_t *cam_arg, void *(*calloc_function)(size_t num, size_t size))
 
void cam_arg_set_free_function (struct cam_arg_t *cam_arg, void(*free_function)(void *ptr))
 
const char * cam_error_string (int error_code)
 
void cam_print_error (int error_code)
 
int cam_options_create (cam_options_t **out_cam_options)
 
size_t cam_options_size (void)
 
void cam_options_init (cam_options_t *out_options)
 
void cam_options_destroy (cam_options_t *cam_options)
 
void cam_options_set_narrow_key (struct cam_options_t *cam_options, bool narrow)
 
void cam_options_set_precomputed_hash_value (struct cam_options_t *cam_options, uint8_t hash_value[32])
 
void cam_options_clear_precomputed_hash_value (struct cam_options_t *cam_options)
 
void cam_options_set_single_segment_search (struct cam_options_t *options, uint8_t segment)
 
void cam_options_clear_single_segment_search (struct cam_options_t *options)
 
void cam_options_set_debug_flags (struct cam_options_t *options, uint32_t debug_flags)
 
void cam_options_clear_debug_flags (struct cam_options_t *options)
 

Macro Definition Documentation

#define CAM_DEBUG_NONE

Debug flags to enable debug printouts and hardware verification.

#define CAM_OPTIMIZE_NONE

Optimization flags

Enumeration Type Documentation

enum cam_errnos

Error numbers.

These are the return codes from the bcam, tcam and stcam API functions. If zero is returned, the function call was successful.

Similar CCAM_ERROR_* constants are used by the hardware managed CAMs; they are identically numbered.

Enumerator
CAM_ERROR_FORMAT_SYNTAX 

Syntax error in format

CAM_ERROR_TOO_MANY_FIELDS 

Too many fields

CAM_ERROR_TOO_MANY_RANGES 

Too many ranges

CAM_ERROR_INVALID_RANGE_LEN 

Invalid range len

CAM_ERROR_INVALID_RANGE_START 

Range start + len exceeds key len

CAM_ERROR_INVALID_PREFIX_LEN 

Invalid prefix len

CAM_ERROR_INVALID_PREFIX_START 

Prefix start + len exceeds key len

CAM_ERROR_INVALID_PREFIX_KEY 

Prefix key longer than prefix len

CAM_ERROR_INVALID_BIT_FIELD_LEN 

Invalid bit len

CAM_ERROR_INVALID_BIT_FIELD_START 

Bit start + len exceeds key len

CAM_ERROR_INVALID_CONST_FIELD_LEN 

Invalid const len

CAM_ERROR_INVALID_CONST_FIELD_START 

Const start + len exceeds key len

CAM_ERROR_INVALID_UNUSED_FIELD_LEN 

Invalid unused len

CAM_ERROR_INVALID_UNUSED_FIELD_START 

Unused start + len exceeds key len

CAM_ERROR_MAX_KEY_LEN_EXCEED 

Sum of all field lengths exceeds key len

CAM_ERROR_INVALID_PRIO_AND_INDEX_WIDTH 

Prio width is too narrow or too wide

CAM_ERROR_TOO_MANY_UNITS 

Too many logical or physical memory units

CAM_ERROR_NO_MASK 

Error during tcam_insert. The entry has not been inserted since hardware resources are partially depleted. It is possible to continue using the instance, inserting entries using already allocated resources, updating entries, get entries or delete entries.

CAM_ERROR_INVALID_MEMORY_WIDTH 

The memory structure defined by the combined key and response width is too wide

CAM_ERROR_UNSUPPORTED_COMMAND 

Unsupported Computational BCAM command

CAM_ERROR_ENVIRONMENT 

Computational BCAM environment error at transport layer or IP non responsive

CAM_ERROR_UNSUPPORTED_CAM_TYPE 

API request for an unsupported cam type

CAM_ERROR_NULL_POINTER 

Null pointer

CAM_ERROR_TOO_MANY_PCS 

Too many pseudo-channels (PCs) are used

CAM_ERROR_CONFIGURATION 

Hardware configuration parameters do not match software settings

CAM_ERROR_ENVIRONMENT_FSMBUSY 

Computational BCAM FSM reporting busy

CAM_ERROR_ENVIRONMENT_POLLED_OUT 

Computational CAM poll timeout

The hardware managed CAM took too long to execute an operation. The operation is still pending and software should treat this as fatal. This can happen if lookup requests are arriving too quickly and leaving no memory bandwidth available to service requests from software. To guarantee that software operations succeed, do not submit lookups to the CAM more quickly than the rate chosen when the IP block was configured.

CAM_ERROR_SEGMENT_COUNT_ZERO 

Virtual BCAM has zero segments

CAM_ERROR_VC_UNSUPPORTED_COMMAND 

Unsupported Virtual container command

CAM_ERROR_WRONG_VIRTUAL_CAM_ID 

Wrong virtual BCAM identifier

CAM_ERROR_WRONG_SEGMENT_NUMBER 

Wrong segment number

CAM_ERROR_TOO_MANY_RAMS 

Too many RAM instances are used

CAM_ERROR_FOUND_IN_SHADOW_BUT_NOT_IN_HW 

Shadow and HW does not match

CAM_ERROR_TOO_SMALL_HEAP 

The max heap for tcam is not sufficiently large

CAM_ERROR_RAM_TOO_SMALL 

The RAM is not large enough to be divided into virtual segments

CAM_ERROR_NOT_EMPTY 

Still contains entries

CAM_ERROR_STATISTICS_NOT_AVAILABLE 

The hardware was not generated with statistics enabled

Function Documentation

int cam_arg_create ( cam_arg_t **  out_cam_arg)

Creates cam_arg which is used to pass arguments during the creation of a vbcam, bcam, tcam or stcam instance. If the function is successful, 0 is returned. If the function fails an error code is returned. The function uses malloc to allocate memory. The malloc can not be replaced by the function specified by cam_arg_set_malloc_function. If malloc must be replaced use cam_arg_size and cam_arg_init instead of cam_arg_create.

Parameters
[out]out_cam_argThe newly created cam_arg. If successful memory was allocated. If unsuccessful, no memory was allocated and out_cam_arg is left unchanged.
Returns
Returns 0 for success, otherwise the error code.
void cam_arg_init ( cam_arg_t *  out_cam_arg)

This function should only be used if cam_arg_create should be replaced. This would be the case if the standard malloc used by cam_arg_create needs to be replaced. The function sets the same default values to cam_arg as cam_arg_create. out_cam_arg is allocated outside of the function.

Parameters
[out]out_cam_argPointer to cam_arg
size_t cam_arg_size ( void  )

This function should only be used if cam_arg_create should be replaced.

Returns
size Returns the size in bytes of the cam_arg structure. See cam_arg_init for more information.
void cam_arg_destroy ( cam_arg_t *  cam_arg)

Destroy cam_arg. The memory allocated by cam_arg_create is released. The stdlib free function is used. The free function is not replaced by the function specified by the cam_arg_set_free_function.

Parameters
[in]cam_argPointer to cam_arg.
int cam_arg_set_format ( cam_arg_t *  cam_arg,
char *  format 
)

The function is only used for tcam. This function shall not be called for bcam or stcam. The format string is used to specify the location and size of range fields, since ternary matching hardware is replaced by range matching hardware for these fields. Furthermore the format string is used to determine key width and to guide the tcam API software. The key width can not be more than 991 bits. In addition, 2 x key width + response width + priority width + 1 can not exceed 1472/1984 (BRAM/URAM) bits. Sets the format string of cam_arg. If the cam_arg_set_format is unsuccessful, the format is not set. The default format of cam_arg is "/0".

Parameters
[in]cam_argPointer to cam_arg
[in]formatString describing the format of all entries of a tcam instance. An entry consists of several fields. Fields are separated by ':'. The string is read left to right. The first field will correspond to the least significant bits of the key. The key is specified as little-endian. Each field is specified as: <field len> <field type>. The following field types and lengths are supported. There are no alignment restrictions for the fields.
  • r - Range, most significant byte of field is in most significant byte of key. The allowed length of the field is 1 to 16 bits. Maximum 8 ranges per format
  • p - Prefix, most significant byte of field is in most significant byte of key. The allowed length of the field is 1 to 128 bits.
  • b - bit field. The allowed length of the field is 1 to 128 bits.
  • t - Ternary field. The allowed length of the field is 2 to 16 bits.
  • c - Bit field with mask always set. The allowed length of the field is 1 to 128 bits.
  • u - Unused bit field with mask always cleared. The allowed length of the field is 1 to 128 bits.

For example, the format "16r:16r:64p:64p:48b:48b" contains 2 x 16 bit range fields for port numbers, 2 x 64 bit prefix fields for IPv6 addresses and 2 x 48 bit fields for MAC addresses. The 16r field is located in the 16 least significant bits of the key

Returns
Returns 0 for success, otherwise the error code.
void cam_arg_set_inst_ctx ( cam_arg_t *  cam_arg,
void *  inst_ctx 
)

Sets the instance context pointer of cam_arg. The context is user-defined and will always be passed when the following functions are invoked: hw write, hw read, hw_write_sequence_start, hw_write_sequence_end, info print and error print. An example of usage of context could be for addressing multiple cam instances. Each instance would be given a unique base address using cam_arg_set_inst_ctx. The hw read/write functions would then add the base address from the context before accessing the hardware.

Parameters
[in]cam_argPointer to cam_arg.
[in]inst_ctxPointer to the instance context.
void cam_arg_set_hw_write_function ( cam_arg_t *  cam_arg,
void(*)(void *, uint32_t, uint32_t)  hw_write_function 
)

Sets the hardware write function of cam_arg. The hw write function will be called by the cam instance to write to the HW

Parameters
[in]cam_argPointer to cam_arg.
[in]hw_write_functionPointer to the hw write function. This function is provided by the user
void cam_arg_set_hw_read_function ( cam_arg_t *  cam_arg,
void(*)(void *, uint32_t, uint32_t *)  hw_read_function 
)

Sets the hardware read function of cam_arg. The hw read function will be called by the cam instance to read from the HW

Parameters
[in]cam_argPointer to cam_arg.
[in]hw_read_functionPointer to the hw read function. This function is provided by the user
int cam_arg_set_hw_io ( cam_arg_t *  cam_arg,
unsigned  hw_block,
void(*)(void *, uint32_t, uint32_t)  hw_write_function,
void(*)(void *, uint32_t, uint32_t *)  hw_read_function 
)

Sets a pair of hardware read/write functions. This variant is used by drivers which communicate with multiple hardware blocks. Calling this function with hw_block == 0 is equivalent to calling cam_arg_set_hw_write_function() and cam_arg_set_hw_read_function().

Parameters
[in]cam_argPointer to cam_arg.
[in]hw_blockIndex of the hardware block (refer to driver documentation).
[in]hw_write_functionPointer to the hw write function.
[in]hw_read_functionPointer to the hw read function. This function is provided by the user
Returns
0 for success. 
                             CAM_ERROR_INVALID_ARG if the value of 'hw_block' is out of range.
void cam_arg_set_num_entries ( cam_arg_t *  cam_arg,
uint32_t  num_entries 
)

Sets the supported number of entries to cam_arg. This is the number of entries the cam instance supports.

Parameters
[in]cam_argPointer to cam_arg.
[in]num_entriesThe number of supported entries the instance can store before it becomes full
void cam_arg_set_engine_lookup_rate ( struct cam_arg_t *  cam_arg,
float  lookup_rate 
)

Sets the lookup rate of the instance to cam_arg. This is the supported lookup rate of the instance. In order to save resources it is important not to set the lookup rate higher than required.

Parameters
[in]cam_argPointer to cam_arg.
[in]lookup_rateThe lookup rate of the instance expressed in Mlookups/s
void cam_arg_set_lookup_interface_freq ( struct cam_arg_t *  cam_arg,
float  freq 
)

This function should not be used for dram. Sets the frequency of the lookup interface to cam_arg. This is the clock frequency of the lookup request and response interfaces. The frequency of the lookup interface must be at least as high as the lookup rate. Sometimes a higher frequency is used, for example: Lookup interface frequency == Lookup rate (A lookup can be issued every clock cycle) Lookup interface frequency == 2 * Lookup rate (A lookup can be issued every second cycle)

Parameters
[in]cam_argPointer to cam_arg.
[in]freqThe frequency of the instance expressed in MHz
void cam_arg_set_ram_freq ( struct cam_arg_t *  cam_arg,
float  freq 
)

This function should not be used for dram. Sets the RAM clock frequency of the instance to cam_arg.

The RAM clock defines the clock frequency of the memories and the internal data path. A high RAM clock frequency enables time division of the hardware resources, leading to significant savings. The amount of time division possible is calculated as: RAM clock frequency / lookup rate, rounded downwards to the nearest power of two.

Example: Lookup rate = 150, Lookup interface frequency = 330 RAM frequency = 600 -> Time division = 600 / 150 = 4

Parameters
[in]cam_argPointer to cam_arg.
[in]freqThe RAM clock frequency expressed in MHz.
void cam_arg_set_response_width ( struct cam_arg_t *  cam_arg,
uint16_t  response_width 
)

Sets the response width of the instance to cam_arg. This is the supported width of response.

Parameters
[in]cam_argPointer to cam_arg.
[in]response_widthThe response width expressed in number of bits (1-1024). The following limitations apply: For vbcam/bcam, key width + response width + 1 cannot exceed 1024/1536/2048 (dram/bram/uram) bits. For cbcam, key width + response width + 1 cannot exceed 1536/1024 (bram/uram) bits. For stcam, key width + response width + priority width + 1 cannot exceed 1536/2048 (bram/uram) bits. For tcam, 2*key width + response width + priority width + 1 cannot exceed 1472/1984 (bram/uram) bits.
void cam_arg_force_prio_width ( struct cam_arg_t *  cam_arg,
uint8_t  prio_width 
)

Forces a narrower priority width of the instance to cam_arg. This function is not applicable for vbcam/bcam instances. The default value is a priority width corresponding to the number of entries for tcam and the number of masks for stcam. In some scenarios a narrower priority width is sufficient.

Parameters
[in]cam_argPointer to cam_arg.
[in]prio_widthThe prio width is expressed in number of bits (0-32). The priority is used to determine the winning match when multiple matches occurs. To represent the priority value a certain priority width is required. The following limitations apply: For stcam, key width + response width + priority width + 1 cannot exceed 1536/2048 (bram/uram) bits. For tcam, 2*key width + response width + priority width + 1 cannot exceed 1472/1984 (bram/uram) bits.
void cam_arg_set_key_width ( struct cam_arg_t *  cam_arg,
uint16_t  key_width 
)

This function is only used for vbcam, bcam and stcam. For tcam the format string should be used instead.

Parameters
[in]cam_argPointer to cam_arg.
[in]key_widthThe key width expressed in number of bits (10-992). The following limitations apply: For bcam/vbcam, key width + response width + 1 cannot exceed 1024/1536/2048 (dram/bram/uram) bits. For cbcam, key width + response width + 1 cannot exceed 1536/1024 (bram/uram) bits. For stcam, key width + response width + priority width + 1 cannot exceed 1536/2048 (bram/uram) bits.
void cam_arg_set_fingerprint_width ( struct cam_arg_t *  cam_arg,
uint16_t  fingerprint_width 
)

Set fingerprint width (DRAM BCAM only). Defaults to zero (fingerprints disabled).

Parameters
[in]cam_argPointer to cam_arg.
[in]fingerprint_widthThe fingerprint width expressed in number of bits (0-16).
void cam_arg_set_num_masks ( struct cam_arg_t *  cam_arg,
uint8_t  num_masks 
)

This function is only used for stcam. An stcam is dimensioned to support a specific number of unique masks and a specific number of entries. The dimensioning is based on a worst case scenario. The stcam memory management algorithm allocates memory dynamically for each unique mask. All entries can use the same mask or entries can use different masks. The memory dimensioning guarantees that the specified number of masks and the specified number of entries will fit in the memory simultaneously.

Parameters
[in]cam_argPointer to cam_arg.
[in]num_masksThe number of unique masks.
void cam_arg_force_num_units ( struct cam_arg_t *  cam_arg,
uint16_t  num_units 
)

This function is not used for dram. Overrides the automatic memory dimensioning. A cam consists of a number of memory units. The automatic memory dimensioning calculates the number of required memory units to store all entries and masks. This function is used to override the automatic dimensioning and forces the number of memory units to a specified value. This function can be used for optimization in certain cases when the automatic dimensioning provides too much headroom.

Parameters
[in]cam_argPointer to cam_arg.
[in]num_unitsThe number of memory units (1-256).
void cam_arg_force_mem_type ( struct cam_arg_t *  cam_arg,
bool  uram 
)

This function is not used for dram. Forces the instance to use either URAM or BRAM. Based on the cam_arg parameters an optimal solution in terms of hardware resources is calculated. This solution is an instance using either BRAM or URAM. In some scenarios the usage of a certain memory type might be constrained and then the solution can be forced to use a certain memory type even though it is not the optimal solution.

Parameters
[in]cam_argPointer to cam_arg.
[in]uramIf true uram is forced to be used. If false bram is forced to be used.
void cam_arg_set_max_num_brams ( struct cam_arg_t *  cam_arg,
uint16_t  max_num_brams 
)

Set the maximum number of BRAMs available in the chosen target device.

Parameters
[in]cam_argPointer to cam_arg.
[in]max_num_bramsMaximum number of BRAMs in the device.
void cam_arg_set_max_num_urams ( struct cam_arg_t *  cam_arg,
uint16_t  max_num_urams 
)

Set the maximum number of URAMs available in the chosen target device.

Parameters
[in]cam_argPointer to cam_arg.
[in]max_num_uramsMaximum number of URAMs in the device.
void cam_arg_set_max_macro_height ( struct cam_arg_t *  cam_arg,
uint8_t  max_macro_height 
)

Set the maximum height of placement macro (RAM column), measured in clock regions. The maximum RAM column height varies depending on the chosen target devices. This parameter provides control over RAM column height versus number of required RAM columns.

Parameters
[in]cam_argPointer to cam_arg.
[in]max_macro_heightMaximum height of placement macro (1-device limit), measured in clock regions.
void cam_arg_set_device_arch ( struct cam_arg_t *  cam_arg,
bool  versal 
)

Set the target device architecure.

Parameters
[in]cam_argPointer to cam_arg.
[in]versalTarget Versal if true. Target UltraScale if false.
void cam_arg_force_hbm ( struct cam_arg_t *  cam_arg)

This function is only used for a vbcam/bcam using HBM. If this function is called, the bcam uses HBM instead of URAM/BRAM or DDR-DRAM. Both DDR-DRAM and HBM can not be forced.

Parameters
[in]cam_argPointer to cam_arg.
void cam_arg_set_narrow_key_width ( struct cam_arg_t *  cam_arg,
uint16_t  narrow_key_width 
)

This function can only be used for a vbcam/bcam using dram. This function activates mixed mode. In mixed mode, wide and narrow entries are efficiently stored together in the same memory. The wide entry is 1024 or 512 bits wide. The narrow entry is half the width of the wide entry. key_width + response_width + 2 is rounded upwards to 512 or 1024 bits for the wide entry. narrow_key_width + response_width + 2 is rounded upwards to 256 or 512 bits for the narrow entry. Both these conditions must be fulfilled: 1: key_width >= narrow_key_width and 2: narrow entry width = wide entry width / 2 . This function sets the key width of the narrow entry. The key width of the wide entry is specified using cam_arg_set_key_width.

Parameters
[in]cam_argPointer to cam_arg.
[in]narrow_key_widthThe key width for the narrow entry
void cam_arg_set_max_hw_writes ( struct cam_arg_t *  cam_arg,
uint16_t  max_hw_writes 
)

This function can only be used for vbcam/bcam. Sets the maximum number of allowed hw writes for the bcam_insert/vbcam_insert function. A hw write occurs every time the hw write function is called. Sometimes the transport method between the driver and the hw requires that all writes are stored in a packet of limited size. This function can be used to limit the number of hw writes so they fit in a single packet. Limiting the number of allowed HW writes may cause the cam to become full earlier than expected. When the cam becomes full due to the hw writes limit, it might still be possible to insert another entry successfully. If this function is called, the number of hw writes is limited. If this function is not called or called with max_hw_writes = 0, no such hw write limitation exists.

Parameters
[in]cam_argPointer to cam_arg.
[in]max_hw_writesMaximum number of allowed hw writes
void cam_arg_set_flow_control ( struct cam_arg_t *  cam_arg,
bool  flow_control 
)

Sets the lookup response flow control configuration.

Parameters
[in]cam_argPointer to cam_arg.
[in]flow_controlFalse = Response flow control off (fixed lookup rate & latency) True = Response flow control on (variable lookup rate & latency)
void cam_arg_set_aging ( struct cam_arg_t *  cam_arg,
bool  aging 
)

Sets the aging configuration (only used for cbcam and cstcam).

Parameters
[in]cam_argPointer to cam_arg.
[in]agingFalse = Aging disabled (entries can only be removed by deleting them) True = Aging enabled (old entries are invalidated or overwritten)
void cam_arg_set_default_response ( struct cam_arg_t *  cam_arg,
const uint8_t *  default_response 
)

Sets the default response. When a key is looked up in the data plane and there is no match, the default response is output together with a no match indication. If the default response is not set all bits are cleared as default. The width of the default response is specified by the cam_arg_set_response_width function. cam_arg_set_response_width must be called prior to this function otherwise the number of bits t copy from the input argument is unknown and zero bytes will be copied.

Parameters
[in]cam_argPointer to cam_arg.
[in]default_responseThe default response
void cam_arg_set_narrow_default_response ( struct cam_arg_t *  cam_arg,
const uint8_t *  narrow_default_response 
)

This function is only used if mixed mode is activated, see cam_arg_set_narrow_key_width. This function sets the narrow default response. When a narrow key is looked up in the data plane and there is a no match, the narrow default response is output together with a no match indication. If the narrow default response is not set, that is if this function is not called, all bits are cleared as default. The width of the narrow default response is specified by the cam_arg_set_response_width function. cam_arg_set_response_width must be called prior to this function otherwise the number of bits to copy from the input argument is unknown and zero bytes will be copied.

Parameters
[in]cam_argPointer to cam_arg.
[in]narrow_default_responseThe narrow default response
void cam_arg_set_vcid ( struct cam_arg_t *  cam_arg,
uint8_t  vcid 
)

This function can only be used for a vbcam. Sets a uniquie identifer (vcid) for each virtualised bcam (vbcam)

Parameters
[in]cam_argPointer to cam_arg
[in]vcidThe unique identifier of the vbcam
void cam_arg_set_seg ( struct cam_arg_t *  cam_arg,
uint16_t  segment_id 
)

This function can only be used for a vbcam. Each vbcam uses one or multiple address segments. This function should be called multiple times if many segments should be used for the vbcam. A segment can only be used by one vbcam at a time otherwise the behavior is undefined. This needs to be enforced by the user.

Parameters
[in]cam_argPointer to cam_arg
[in]segment_idsegment num (0-255) allocated to the vbcam
void cam_arg_set_hw_write_sequence_functions ( cam_arg_t *  cam_arg,
void(*)(void *)  start_function,
void(*)(void *)  end_function 
)

This function is only applicable for vbcam. Sets the start and end functions for the hw write sequence. The hw registers use indirect addressing since the hw bus is narrow. For this reason, key and response updates require a sequence of multiple hw writes to finish. If the cam is used by multiple threads as would be the typical use case for vbcams, the write sequence must be protected from being interrupted by another thread's write sequence. The start_function and end_function arguments are called when the sequence is started and ended. These functions can for instance be used to lock and unlock a mutex common for all threads. The argument to the start_function and end_function is the context as specified by the cam_arg_set_inst_ctx.

Parameters
[in]cam_argPointer to cam_arg.
[in]start_functionPointer to the start function. This function is provided by the user
[in]end_functionPointer to the end function. This function is provided by the user
void cam_arg_set_debug_flags ( cam_arg_t *  cam_arg,
uint32_t  debug_flags 
)

Sets the debug flags of cam_arg. The debug flags control how much information is displayed for information, warning and error purposes.

Parameters
[in]cam_argPointer to cam_arg.
[in]debug_flagsBit mask value, every bit corresponds to a class of debug messages.
void cam_arg_set_optimization_flags ( cam_arg_t *  cam_arg,
uint32_t  optimization_flags 
)

Sets the optimization flags of cam_arg. The optimization flags specifies how the hardware is optimized. E.g. optimized to reduce either logic or memory

Parameters
[in]cam_argPointer to cam_arg.
[in]optimization_flagsBit mask value.
void cam_arg_enable_options ( cam_arg_t *  cam_arg)

Enable options for bcam. This function is only applicable for bcam. The bcam functions are variadic C functions. If options is enabled, the bcam expects one additional argument containing the options

Parameters
[in]cam_argPointer to cam_arg.
void cam_arg_force_asic_ram ( struct cam_arg_t *  cam_arg)

This function is only used for stcam/bcam using asic ram. The size of the asic ram is set by cam_arg_set_ram_size

Parameters
[in]cam_argPointer to cam_arg.
void cam_arg_force_dram ( struct cam_arg_t *  cam_arg)

This function is only used for a vbcam/bcam using DDR-DRAM. If this function is called, the bcam uses DDR-DRAM instead of URAM/BRAM. Both DDR-DRAM and HBM can not be forced.

Parameters
[in]cam_argPointer to cam_arg.
void cam_arg_set_ram_size ( struct cam_arg_t *  cam_arg,
uint32_t  size 
)

This function is used to specify the size of the ddr-dram in KB or the size of the asic ram in number of addresses per ram.

Parameters
[in]cam_argPointer to cam_arg.
[in]sizeMemory size. The unit is different depending on if it is ddr-dram or asic ram. E.g. size = 1024 = 1MB of dram for ddr-dram. size = 512 corresponds to 512 addresses per ram for asic ram. In both cases the size must be a power of 2.
void cam_arg_set_hash_function ( struct cam_arg_t *  cam_arg,
uint8_t  function 
)

This function is only used for dram bcam. The default hash function is Murmur3. The hash function can be changed by using this function.

Parameters
[in]cam_argPointer to cam_arg.
[in]functionThe hash function
void cam_arg_set_siphash_key ( struct cam_arg_t *  cam_arg,
uint64_t  k0,
uint64_t  k1 
)

Set the SipHash key. Using a secret value for this key offers some protection against hash flooding attacks.

Parameters
[in]cam_argPointer to cam_arg.
[in]k0Least significant 64 bits of key.
[in]k1Most significant 64 bits of key.
void cam_arg_set_num_banks ( struct cam_arg_t *  cam_arg,
uint8_t  num_banks 
)

Only valid for ddr-dram BCAMs. This function is used to specify the number of banks the bcam uses. Default is 8 banks

Parameters
[in]cam_argPointer to cam_arg.
[in]num_banksOnly 8 and 4 are allowed
void cam_arg_set_channel_width ( struct cam_arg_t *  cam_arg,
uint16_t  width 
)

Only valid for ddr-dram BCAMs. This function is used to specify the amount of data (in bits) that are transferred on the dram channel using a single read/write access. The value is the product of the burst length and physical data width. Default is 512 bits.

Parameters
[in]cam_argPointer to cam_arg.
[in]widthOnly 256 and 512 are allowed.
void cam_arg_set_generation_number_granularity ( struct cam_arg_t *  cam_arg,
uint16_t  granularity 
)

This function is only used for dram-bcam. The DRAM controller can not support atomicity for wider data than its transaction size. This function creates atomicity with generation numbers per transaction size or narrower.

Parameters
[in]cam_argPointer to cam_arg.
[in]granularitydefault is 0. Supported values 0 and 256
void cam_arg_calc_heap_size ( struct cam_arg_t *  cam_arg,
bool  calculate 
)

This function is used to let the create function calculate the heap size before allocating it. Instead of creating the driver, the create function calculates the maximum heap size it will use during its lifetime. When a CAM driver is created, all heap allocations are performed by the create function except for the TCAM which performs allocations in other functions as well. For the TCAM, the returned heap size also includes heap size which will be allocated in other functions. The create function returns an error code or the calculated heap size. If it is an error code or the heap size that is returned is determined by comparing with CAM_ERROR_FATAL_BASE_END. If the return code has a greater value, it is the heap size that is returned. The returned heap size is in Bytes.

Parameters
[in]cam_argPointer to cam_arg.
[in]calculatedefault is false
void cam_arg_set_error_print_function ( struct cam_arg_t *  cam_arg,
void(*)(void *, char *)  error_print_function 
)

Sets the error print function of cam_arg. The error print function will be called by the cam instance to print error messages. The default error print function is printing to stderr.

Parameters
[in]cam_argPointer to cam_arg.
[in]error_print_functionPointer to the error print function. This function is provided by the user
void cam_arg_set_info_print_function ( struct cam_arg_t *  cam_arg,
void(*)(void *, char *)  info_print_function 
)

Sets the info print function of cam_arg. The info print function will be called by the cam instance to print informational messages. The default info print function is printing to stdout.

Parameters
[in]cam_argPointer to cam_arg.
[in]info_print_functionPointer to the info print function. This function is provided by the user
void cam_arg_set_malloc_function ( struct cam_arg_t *  cam_arg,
void *(*)(size_t size)  malloc_function 
)

Sets the malloc function of cam_arg. The malloc function will be called by the cam instance to allocate memory on the heap of size bytes. It returns a pointer to this memory. The default malloc is stdlib malloc

Parameters
[in]cam_argPointer to cam_arg.
[in]malloc_functionPointer to the malloc function. This function is provided by the user
void cam_arg_set_posix_memalign_function ( struct cam_arg_t *  cam_arg,
int(*)(void **ptr, size_t align_size, size_t num)  posix_memalign_function 
)

Sets the posix_memalign function of cam_arg. The posix_memalaign function will be called by the cam instance to allocate memory on the heap of size bytes aligned to 64 Bytes which corresponds to a cache line. This might improve the performance of the shadow memory. It returns a result code. If the posix_memalign function is not set, the calloc function will be used instead.

Parameters
[in]cam_argPointer to cam_arg.
[in]posix_memalign_functionPointer to the posix_memalign function. This function is provided by the user
void cam_arg_set_realloc_function ( struct cam_arg_t *  cam_arg,
void *(*)(void *ptr, size_t size)  realloc_function 
)

Sets the realloc function of cam_arg. The realloc function will be called by the cam instance to re-allocate memory on the heap of size bytes. It returns a pointer to this memory. The default realloc is stdlib realloc. Realloc is only used by tcam instances

Parameters
[in]cam_argPointer to cam_arg.
[in]realloc_functionPointer to the realloc function. This function is provided by the user
void cam_arg_set_calloc_function ( struct cam_arg_t *  cam_arg,
void *(*)(size_t num, size_t size)  calloc_function 
)

Sets the calloc function of cam_arg. The calloc function will be called by the cam instance to allocate memory for an array of num elements of size bytes each and returns a pointer to the allocated memory on the heap. The memory is also set to zero and a pointer to this memory is returned. The default calloc is stdlib calloc

Parameters
[in]cam_argPointer to cam_arg.
[in]calloc_functionPointer to the calloc function. This function is provided by the user
void cam_arg_set_free_function ( struct cam_arg_t *  cam_arg,
void(*)(void *ptr)  free_function 
)

Sets the free function of cam_arg. This will be called by the cam instance to free up heap memory that was allocated by the malloc and calloc functions. The default free is stdlib free.

Parameters
[in]cam_argPointer to cam_arg.
[in]free_functionPointer to the free function. This function is provided by the user
const char* cam_error_string ( int  error_code)

This function is only for debug purposes and returns the error code as a string.

Parameters
[in]error_codeerror code to print. The error code is returned from the API functions
Returns
error_string The error code as text.
void cam_print_error ( int  error_code)

This function is only for debug purposes and prints the error code on stderr.

Parameters
[in]error_codeerror code to print. The error code is returned from the API functions
int cam_options_create ( cam_options_t **  out_cam_options)

Creates cam_options which is used to pass additional arguments to insert, delete, update etc. If the function was successful, 0 is returned. If the function fails an error code is returned. The function uses malloc to allocate memory. The malloc can not be replaced by the function specified by cam_arg_set_malloc_function. If malloc must be replaced use cam_options_size and cam_options_init instead of cam_options_create. Options can only be used for dram bcam/vbcam

Parameters
[out]out_cam_optionsThe newly created cam_options. If successful memory was allocated. If unsuccessful, no memory was allocated and out_cam_options is left unchanged.
Returns
Returns 0 for success, otherwise the error code.
size_t cam_options_size ( void  )

Gets the byte size of cam_options_t. This is useful if it it is preferred to allocate memory for cam_options_t using something else than the malloc used inside cam_options_create. E.g. alloca. cam_options_create can be replaced by using cam_options_size, alloca/malloc and cam _options_init. Options can only be used for dram bcam/vbcam

Returns
Returns the byte size of cam_options_t
void cam_options_init ( cam_options_t *  out_options)

Initializes options by setting default values. This function is used together with cam_options_size. out_options is allocated outside of the function. Options can only be used for dram bcam/vbcam

Parameters
[out]out_optionsA pointer to options is passed. The function will modify the content pointed to by the pointer. The content is set to the same default values as if cam_options_create would have been used.
void cam_options_destroy ( cam_options_t *  cam_options)

Destroy cam_options. The memory allocated by cam_options_create is released. The stdlib free function is used. The free function is not replaced by the function specified by the cam_arg_set_free_function. Options can only be used for dram bcam/vbcam

Parameters
[in]cam_optionsPointer to cam_options.
void cam_options_set_narrow_key ( struct cam_options_t *  cam_options,
bool  narrow 
)

This function sets if it is a wide or narrow key. The key is either wide or narrow. Default is wide. Options can only be used for dram bcam/vbcam

Parameters
[in]cam_optionsPointer to cam_options.
[in]narrowIf true, the key is narrow. If false, the key is wide.
void cam_options_set_precomputed_hash_value ( struct cam_options_t *  cam_options,
uint8_t  hash_value[32] 
)

This function sets the pre-computed hash value. When a pre-computed hash-value is passed, a new computation of the hash value is not made thus saving processor cycles.Default is not to use pre-computed hash values. If a key is passed with a non-matching hash value, the behavior is undefined. This function is meant to be used for dram bcams in order to serialize access to segments.

Parameters
[in]cam_optionsPointer to cam_options.
[in]hash_valueA 256 bit wide hash value. Little-endian is used.
void cam_options_clear_precomputed_hash_value ( struct cam_options_t *  cam_options)

This function clears pre-computed hash value. A pre-computed hash-value is not used and a new computation of the hash value will take place.

Parameters
[in]cam_optionsPointer to cam_options.
void cam_options_set_single_segment_search ( struct cam_options_t *  options,
uint8_t  segment 
)

This function is only used for dram vbcams' and provides an option to vbcam_get_by_response. The function specifies a single segment to be searched, instead of searching all segments which is the default behavior. The option provides flexibility in how mutex locking can be performed in a multi-threaded environment. Searching only one segment at a time allows for sequentially locking and releasing segments one at a time instead of locking all segments of the dram vbcam upfront.

Parameters
[in]optionsPointer to cam_options.
[in]segmentThe single segment to be searched
void cam_options_clear_single_segment_search ( struct cam_options_t *  options)

This function clears searching a single segment. The default behavior is restored. That is, vbcam_get_by_response searches all segments.

Parameters
[in]optionsPointer to cam_options.
void cam_options_set_debug_flags ( struct cam_options_t *  options,
uint32_t  debug_flags 
)

The debug flags can be sent as an option. The debug flags passed in the options argument overrides the default debug flags which were passed in cam_arg when the cam instance was created. The debug flags passed as an option argument are only valid for the specific function call. When the function returns, the debug flags are restored to the default debug flags. By default passing debug flags in the options argument is disabled/cleared. Options can only be used for dram bcam/vbcam

Parameters
[in]optionsPointer to cam_options.
[in]debug_flagsThe debug flags.
void cam_options_clear_debug_flags ( struct cam_options_t *  options)

Disables the use of the debug flags in the options argument.

Parameters
[in]optionsPointer to cam_options.