First a cam_arg handle is created using cam_arg_create(). The handle is then used for all cam_arg set and force functions in order to configure the tcam. The cam_arg handle is then passsed to tcam_create(). tcam_create() copies all the information in the cam_arg allowing the cam_arg to be destroyed after the tcam_create() call. tcam_create() returns a tcam handle which is used for the other API functions. tcam_create() allocates memory. The memory is released by calling tcam_destroy().
|
| int | tcam_create (const cam_arg_t *cam_arg, struct tcam **out_tcam) |
| |
| int | tcam_insert (struct tcam *tcam, const uint8_t key[], const uint8_t mask[], uint32_t prio, const uint8_t response[]) |
| |
| int | tcam_update (struct tcam *tcam, const uint8_t key[], const uint8_t mask[], const uint8_t response[]) |
| |
| int | tcam_get_by_response (struct tcam *tcam, const uint8_t response[], const uint8_t response_mask[], uint32_t *pos, uint8_t out_key[], uint8_t out_mask[]) |
| |
| int | tcam_get_by_key (struct tcam *tcam, const uint8_t key[], const uint8_t mask[], uint32_t *prio, uint8_t response[]) |
| |
| int | tcam_lookup (struct tcam *tcam, const uint8_t key[], uint8_t response[]) |
| |
| int | tcam_delete (struct tcam *tcam, const uint8_t key[], const uint8_t mask[]) |
| |
| int | tcam_read_and_clear_ecc_counters (struct tcam *tcam, uint32_t *corrected_single_bit_errors, uint32_t *detected_double_bit_errors) |
| |
| int | tcam_read_and_clear_ecc_addresses (struct tcam *tcam, uint32_t *failing_address_single_bit_error, uint32_t *failing_address_double_bit_error) |
| |
| int | tcam_set_ecc_test (struct tcam *tcam, bool inject_single_bit_errors, bool inject_double_bit_errors) |
| |
| int | tcam_destroy (struct tcam *tcam) |
| |
| int | tcam_get_stats (const struct tcam *tcam, uint64_t stats_group, union tcam_stats *stats) |
| |
| int tcam_create |
( |
const cam_arg_t * |
cam_arg, |
|
|
struct tcam ** |
out_tcam |
|
) |
| |
Creates a tcam instance. Returns 0 if successful, otherwise an error code. A shadow of the HW instance is created.
- Parameters
-
| [in] | cam_arg | Arguments used to create the tcam instance. cam_arg is copied to the tcam instance, and can be destroyed immediately after this call. |
| [out] | out_tcam | Returns the newly created tcam instance, memory is allocated using malloc. If tcam_create returns an error the instance is not created. In this case no memory is allocated, and out_tcam is left unchanged. |
- Returns
- Returns 0 for success, otherwise the error code.
| int tcam_insert |
( |
struct tcam * |
tcam, |
|
|
const uint8_t |
key[], |
|
|
const uint8_t |
mask[], |
|
|
uint32_t |
prio, |
|
|
const uint8_t |
response[] |
|
) |
| |
Inserts an entry to the tcam instance. If the entry is found, the function fails by returning error code CAM_ERROR_DUPLICATE_FOUND. If the entry is not found, then it is inserted in the tcam instance. Returns 0 if successful, otherwise an error code.
- Parameters
-
| [in] | tcam | Pointer to the tcam instance |
| [in] | key | The key. The key width (in bits) is implicitly specified by the format string. The key width specifies how many bits are copied and stored. Any contents outside the scope of the defined key width is ignored. The key is assumed to be in little-endian format. key[0] bit 0 is the least significant bit of the key. key[1] bit 0 is bit 8 of the key and so on. |
| [in] | mask | The ternary mask. The key width (in bits) is implicitly specified by the format string. The key width specifies how many bits are copied and stored. Any contents outside the scope of the defined key width is ignored. The ternary mask is assumed to be in little-endian format. mask[0] bit 0 is the least significant bit of the ternary mask. mask[1] bit 0 is bit 8 of the ternary mask and so on. |
| [in] | prio | The priority of the entry. If multiple matches occur, the winning matching entry is determined based on the priority value. The entry with the lowest priority wins. If there are multiple matches with the same lowest priority, any of them becomes the winner. Prio values greater than what can be represented by the defined prio width generates an error code. |
| [in] | response | The response of the entry. The defined response width specifies how many bits are copied and stored. The response is in little-endian format. |
- Returns
- Returns 0 for success, otherwise the error code.
| int tcam_update |
( |
struct tcam * |
tcam, |
|
|
const uint8_t |
key[], |
|
|
const uint8_t |
mask[], |
|
|
const uint8_t |
response[] |
|
) |
| |
Updates an entry in the tcam instance. If the entry is found, the response is updated. If the entry is not found, the function fails with error code CAM_ERROR_NO_ENTRY. Returns 0 if successful, otherwise an error code.
- Parameters
-
| [in] | tcam | Pointer to the tcam instance |
| [in] | key | The key. The key width (in bits) is implicitly specified by the format string. The key width specifies how many bits of the key to use. Any contents outside the scope of the defined key width is ignored. The key is assumed to be in little-endian format. key[0] bit 0 is the least significant bit of the key. key[1] bit 0 is bit 8 of the key and so on. |
| [in] | mask | The ternary mask. The key width (in bits) is implicitly specified by the format string. The key width specifies how many bits of the mask to use. Any contents outside the scope of the defined key width is ignored. The ternary mask is assumed to be in little-endian format. mask[0] bit 0 is the least significant bit of the ternary mask. mask[1] bit 0 is bit 8 of the ternary mask and so on. |
| [in] | response | The response of the entry. The defined response width specifies how many bits are copied and stored. The response is in little-endian format. |
- Returns
- Returns 0 for success, otherwise the error code.
| int tcam_get_by_response |
( |
struct tcam * |
tcam, |
|
|
const uint8_t |
response[], |
|
|
const uint8_t |
response_mask[], |
|
|
uint32_t * |
pos, |
|
|
uint8_t |
out_key[], |
|
|
uint8_t |
out_mask[] |
|
) |
| |
Gets an entry with matching response value. If an entry is found, the function returns 0. If the entry is not found, the function fails with error code CAM_ERROR_KEY_NOT_FOUND.
The pos argument enables multiple matching entries to be found. The first time the function is called pos should be set to zero. To find all entries matching the response, the function is called multiple times, each call returns one matching entry. For every consecutive call the returned pos value must be used again as input argument. When CAM_ERROR_KEY_NOT_FOUND is returned no more entries matching the response could be found.
The response_mask is used to limit the search to subfields of the response. If the complete, exact response value is searched, then all response_mask bits should be set to one. By setting the response_mask bits to all zeros, any response value will match. This can be used for getting all entries without prior knowledge of the response values.
The get function does not read from the hardware. It reads from the shadow. tcam_get_by_response uses linear search.
- Parameters
-
| [in] | tcam | Pointer to tcam instance |
| [in] | response | The response to search for. The response is in little-endian format. |
| [in] | response_mask | The response and response_mask are ANDed and then searched for. The stored response is also ANDed with the response_mask before compare takes place. The response_mask is in little-endian format. |
| [in,out] | pos | Position in the database. Used for consecutive get operations, set to 0 for first get. |
| [out] | out_key | The read key. Key width bits are copied to the key. The key is in little-endian format. |
| [out] | out_mask | The read ternary mask. Key width bits are copied to the ternary mask. The ternary mask is in little-endian format. |
- Returns
- Returns 0 for success, otherwise the error code.
| int tcam_get_by_key |
( |
struct tcam * |
tcam, |
|
|
const uint8_t |
key[], |
|
|
const uint8_t |
mask[], |
|
|
uint32_t * |
prio, |
|
|
uint8_t |
response[] |
|
) |
| |
Gets an entry with matching key and mask. If an entry with both a matching key and mask is found, the function returns 0. If an entry is not found, the function fails with error code CAM_ERROR_KEY_NOT_FOUND. The function does not read from the hardware, it reads from the shadow. tcam_get_by_key uses a hash table and is fast.
- Parameters
-
| [in] | tcam | Pointer to tcam instance |
| [in] | key | The key to search for. The key width (in bits) is implicitly specified by the format string. The key width specifies the number of bits in the key to use. Any contents outside the scope of the defined key width is ignored. The key is assumed to be in little-endian format. key[0] bit 0 is the least significant bit of the key. key[1] bit 0 is bit 8 of the key and so on. |
| [in] | mask | The ternary mask to search for. The key width (in bits) is implicitly specified by the format string. The key width specifies how many bits of the mask to use. Any contents outside the scope of the defined key width is ignored. The mask is assumed to be in little-endian format. mask[0] bit 0 is the least significant bit of the mask. mask[1] bit 0 is bit 8 of the mask and so on. |
| [out] | prio | The prio of the key |
| [out] | response | The response of the key. The response is in little-endian format. |
- Returns
- Returns 0 for success, otherwise the error code.
| int tcam_lookup |
( |
struct tcam * |
tcam, |
|
|
const uint8_t |
key[], |
|
|
uint8_t |
response[] |
|
) |
| |
Looks up an entry in the tcam instance. This function provides the same response as if a lookup had been performed in hardware. If no match is found in the database, the response value associated with the default response entry is returned and the return code is CAM_ERROR_KEY_NOT_FOUND. If an entry is found in the data base, the function returns 0.
- Parameters
-
| [in] | tcam | Pointer to tcam instance |
| [in] | key | The key to lookup. The key width (in bits) is specified by the key_width. The key width specifies how many bits of the key to use. Any contents outside the scope of the defined key width is ignored. The key is assumed to be in little-endian format. key[0] bit 0 is the least significant bit of the key. key[1] bit 0 is bit 8 of the key and so on. |
| [out] | response | The response from the lookup. The response is in little-endian format. |
- Returns
- Returns 0 for success, otherwise the error code.
| int tcam_delete |
( |
struct tcam * |
tcam, |
|
|
const uint8_t |
key[], |
|
|
const uint8_t |
mask[] |
|
) |
| |
Delete an entry from the tcam instance. If the entry is found, the function returns 0. If an entry is not found, the function fails with error code CAM_ERROR_KEY_NOT_FOUND.
- Parameters
-
| [in] | tcam | Pointer to tcam instance |
| [in] | key | The key to delete. The key width (in bits) is implicitly specified by the format string. The key width specifies how many bits of the key to use. Any contents outside the scope of the defined key width is ignored. The key is assumed to be in little-endian format. key[0] bit 0 is the least significant bit of the key. key[1] bit 0 is bit 8 of the key and so on. |
| [in] | mask | The ternary mask to delete. |
- Returns
- Returns 0 for success, otherwise the error code.
| int tcam_read_and_clear_ecc_counters |
( |
struct tcam * |
tcam, |
|
|
uint32_t * |
corrected_single_bit_errors, |
|
|
uint32_t * |
detected_double_bit_errors |
|
) |
| |
Reads and clears the ECC counters of the tcam instance. When the instance is created the ECC counters are automatically cleared. This function always returns zero.
- Parameters
-
| [in] | tcam | Pointer to tcam instance |
| [out] | corrected_single_bit_errors | The number of single bit errors the hardware scrubbing process has detected and corrected permanently. Errors might have been detected by hardware lookups and then corrected dynamically for the lookups, these errors are not counted. The scrubbing process runs in the background and corrects errors permanently. The counter is only incremented after the error is corrected permanently.The counter is cleared when read. |
| [out] | detected_double_bit_errors | The number of detected double-bit errors. Double-bit errors are fatal errors and the database is corrupt. The hardware cannot correct the error without help from software. When a double bit error is detected either by scrubbing or a lookup, an interrupt signal is asserted. Double bit errors detected by scrubbing are counted by this counter. The counter is cleared when read. Lookups detecting double-bit errors will mark the lookup response with a double-bit-error indication. It is advised to use this indication to discard packets. Double bit errors detected by lookups are not counted. |
- Returns
- Returns 0 for success, otherwise the error code.
| int tcam_read_and_clear_ecc_addresses |
( |
struct tcam * |
tcam, |
|
|
uint32_t * |
failing_address_single_bit_error, |
|
|
uint32_t * |
failing_address_double_bit_error |
|
) |
| |
Reads and clears the ECC address registers of the tcam instance. The ECC adresses registers are automatically cleared when the tcam instance is created. This function always returns zero.
- Parameters
-
| [in] | tcam | Pointer to tcam instance |
| [out] | failing_address_single_bit_error | The address of the first single bit error detected and corrected by the hardware scrubbing process. Additional errors might have been detected during a hardware lookup and then corrected dynamically, but this register only reflects the errors detected by hardware scrubbing. |
| [out] | failing_address_double_bit_error | The address of the first double-bit error detected by the hardware scrubbing process. |
- Returns
- Returns 0 for success, otherwise the error code.
| int tcam_set_ecc_test |
( |
struct tcam * |
tcam, |
|
|
bool |
inject_single_bit_errors, |
|
|
bool |
inject_double_bit_errors |
|
) |
| |
Set error injection for ECC test. Error injection makes subsequently inserted entries to be stored in memory with errors.
- Parameters
-
| [in] | tcam | Pointer to tcam instance |
| [in] | inject_single_bit_errors | Enable insertion of single-bit errors (correctable). |
| [in] | inject_double_bit_errors | Enable insertion of double-bit errors (uncorrectable). |
- Returns
- Returns 0 for success, otherwise the error code.
| int tcam_destroy |
( |
struct tcam * |
tcam | ) |
|
Destroy tcam instance.
- Parameters
-
| [in] | tcam | Pointer to tcam instance. All memory previously allocated by tcam_create is released. |
- Returns
- Returns 0 for success, otherwise the error code.
| int tcam_get_stats |
( |
const struct tcam * |
tcam, |
|
|
uint64_t |
stats_group, |
|
|
union tcam_stats * |
stats |
|
) |
| |
Reads statistics information. The statistics information is organized in different groups. The statistics associated with a certain group is read from the instance. See documentation for the tcam_stats union for further information.
- Parameters
-
| [in] | tcam | Pointer to tcam instance |
| [in] | stats_group | Selects the group of statistics to be read |
| [out] | stats | The read statistics |
- Returns
- Returns 0 for success, otherwise the error code.
