CAM API Documentation
Loading...
Searching...
No Matches
Overview

Table of Contents

The CAM API is a set of functions that provides an easy-to-use interface between the user application and the CAM hardware. The CAM API is implemented in the C programming language. The CAM API executes on little-endian machines

There are three types of CAMs:

  • Binary CAM (BCAM)
  • Ternary CAM (TCAM)
  • Semi-TCAM (STCAM)

BCAMs are used for binary matching also known as exact matching. The input key is matched with the stored keys and if one stored key matches, the response data associated with the matching stored key is returned. Only one stored key matches the input key. A no match is returned if no stored key matches the input key. BCAMs are used for exact match tables. A typical application is a MAC address table or flow table. BCAMs do not support wildcards. BCAMs are supported for both URAM/BRAM and HBM. BCAMs using HBM allows for very large tables. The BCAM supports virtualization and multi-threading. The virtual BCAM (VBCAM) supports flexible partitioning of memory as well as traffic isolation for up to 128 VBCAMs/containers. The hardware managed BCAM (CBCAM) operates without software shadow memory. Entries can be inserted, updated, and deleted either via the Hardware Update Interface, or the software API.

TCAMs are used for ternary matching. Every stored key has an associated mask. Every key bit has a corresponding mask bit. If the mask bit is cleared it means that the corresponding key bit is handled as a don't care bit. The input key is matched with the stored key and mask and if all the non-wildcarded key bits match the corresponding bits of the input key, there is a match. Multiple stored entries can match the input key, therefore each stored entry has also an associated priority. The matching entry with the lowest priority wins if there are multiple matches. The response data of the winning entry is returned. A no match is returned if no stored key matches the input key. TCAMs are used for wildcard matching where entries contain multiple fields which can be wholly or partially wildcarded. A typical application is Access Control Lists (ACLs)

The STCAM is also used for ternary matching. The STCAM is a hybrid between BCAM and TCAM. The BCAM uses no mask bits while the TCAM uses one mask bit per key bit. In terms of hardware cost, the TCAM is twice as expensive as the BCAM due to the mask bits. The STCAM uses shared masks. That is a number of entries share the same mask. This reduces the hardware cost significantly, but also limits the number available masks. The STCAM is perfect for applications using a limited number of masks such as OVS applications and Longest Prefix Matching (LPM). The number of masks is specified when the STCAM is created. The masks can be selected arbitrarily and dynamically. The STCAM implements memory management, all entries can use the same mask, entries can be distributed evenly between the masks or the distribution could be heavily skewed with a few entries using a few masks while most entries use the same mask. The dimensioning of the stcam is based on the worst case distribution. Multiple stored entries can match the input key, therefore each stored entry has an associated priority. The matching entry with the lowest priority wins if there are multiple matches. The response data of the winning entry is returned. A no match is returned if no stored key matches the input key.

One or many instances of each CAM type can be created. Each type has its own API. Before the CAM is created, the configuration arguments need to be set. These arguments are common for all three types of CAMs and defines the configuration. It is important that the software configuration corresponds to the configuration of the actual hardware. This is not a problem if VitisNetP4 is used. VitisNetP4 generates both the hardware and software. For every API function, VitisNetP4 generates wrapper functions. The generated wrapper functions contains code which sets the software configuration parameters to correspond to the generated hardware.

The API contains the following files:

  • bcam.h, used for BCAM instances
  • tcam.h, used for TCAM instances
  • stcam.h, used for STCAM instances
  • vbcam.h, used for VBCAM instances
  • cbcam.h, used for CBCAM instances
  • cam.h, used for all three CAM types in order to set the creation arguments. The file also contains all the error codes
  • ccam.h, used for CCAM types (eg. CBCAM) in order to set the creation arguments. The file also contains all the error codes
  • cam_obf.c, the obfuscated source code
  • ccam_obf.c, the obfuscated source code for CBCAM

VitisNetP4

When VitisNetP4 is used, both the hardware and the software are generated when VitisNetP4 is compiled. VitisNetP4 generates a new *.h header file and *.c source file for every table defined in VitisNetP4. The files are named after the table name. Every function in the corresponding header file is wrapped by a new function. The new wrapper functions do not use the pointer to the instance anymore since every wrapper function has a unique name. Furthermore the configuration arguments are removed from the new wrapper API since this is all handled by the new wrapper create function.

Standalone

When the API is used without VitisNetP4 the hardware is generated from Vivado or is provided as a bitstream. In the standalone mode the raw API is used and no wrappers exists.

Configuration Arguments

To create a CAM instance bcam_create, cbcam_init, vbcam_create, tcam_create or stcam_create needs to be called. The CAM is highly configurable and scalable both in terms of size and performance. The software needs to know a number of configuration parameters for correct operation. This includes but is not limited to:

  • Type, BCAM, CBCAM, TCAM or STCAM
  • Memory, URAM, BRAM or HBM
  • Psuedo channels (PCs), the number of PCs in the HBM a BCAM uses
  • Depth, number of entries
  • Key width, key width in bits
  • Response width, the width of the response in bits
  • Priority width, the width of the priority in bits. Priority is only used for TCAM and STCAM
  • Lookup rate, the number of supported lookups in millons of lookups/s
  • Lookup interface frequency, the frequency of the lookup request/response interface (Not for BCAM using HBM)
  • RAM frequency, optional high frequency clock for RAM and internal datapath (Not for BCAM using HBM)
  • HW read function, the read function the CAM uses to read from the hardware. The final mapping to hardware is made here
  • HW write function, the write function the CAM uses to write to the hardware. The final mapping to hardware is made here
  • Key Format, this is a string specifying the size and position of the fields in the key. The format string is only used for TCAM
  • Key Width, this is only used for BCAM or STCAM. The key size is obtained from the format string for TCAM.
  • Number of masks, this is only used for STCAM and used together with Depth for dimensioning
  • VBCAM id, the id a of VBCAM
  • Segments, the memory segments a VBCAM uses
    The argument to the create functions contains all this information. The functions to create and set these parameters are provided in cam.h

Key Format

Only for TCAM. The key format string is used for generating the right hardware. The Key format is used by the software to validate in arguments and guide the software algorithms. Fields can be of arbitrary size, have an arbitrary position and be of any number.