Overview

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().

Functions
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_all (struct tcam *tcam)

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 (struct tcam tcam, uint64_t stats_group, union tcam_stats stats)

Function Documentation

◆ tcam_create()

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. The tcam HW memory is cleared (unless CAM_DEBUG_SKIP_MEM_INIT is enabled). A software 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.

◆ tcam_insert()

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.

◆ tcam_update()

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. For range values, the minimum value is encoded in the key bits.
[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. For range values, the maximum value is encoded in the mask bits.
[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.

◆ tcam_get_by_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[] )

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.

If tcam_get_by_response is called multiple times using the pos argument it should be noted that tcam_insert or tcam_delete can not be used between the calls since the pos argument then becomes invalid.

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.

◆ tcam_get_by_key()

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.

◆ tcam_lookup()

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.

◆ tcam_delete_all()

int tcam_delete_all ( struct tcam * tcam )

Deletes all entries from the tcam instance

Parameters

[in] tcam Pointer to tcam instance

Returns: Returns 0 for success, otherwise the error code.

◆ tcam_delete()

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.

◆ tcam_read_and_clear_ecc_counters()

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.

◆ tcam_read_and_clear_ecc_addresses()

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.

◆ tcam_set_ecc_test()

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.

◆ tcam_destroy()

int tcam_destroy ( struct tcam * tcam )

Destroy tcam instance. All memory allocated by tcam_create is released. The tcam HW memory is not cleared, any remaining entries are unmodified.

Parameters

[in] tcam Pointer to tcam instance.

Returns: Returns 0 for success, otherwise the error code.

◆ tcam_get_stats()

int tcam_get_stats	(	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.

Overview

Functions

Function Documentation

◆ tcam_create()

◆ tcam_insert()

◆ tcam_update()

◆ tcam_get_by_response()

◆ tcam_get_by_key()

◆ tcam_lookup()

◆ tcam_delete_all()

◆ tcam_delete()

◆ tcam_read_and_clear_ecc_counters()

◆ tcam_read_and_clear_ecc_addresses()

◆ tcam_set_ecc_test()

◆ tcam_destroy()

◆ tcam_get_stats()