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 bcam. The cam_arg handle is then passed to bcam_create(). bcam_create() copies all the information in the cam_arg allowing the cam_arg to be destroyed after the bcam_create() call. bcam_create() returns a bcam handle which is used for the other API functions. bcam_create() allocates memory. The memory is released by calling bcam_destroy().

Functions
int	bcam_create (const cam_arg_t cam_arg, struct bcam *out_bcam)

int	bcam_insert (struct bcam *bcam, const uint8_t key[], const uint8_t response[],...)

int	bcam_update (struct bcam *bcam, const uint8_t key[], const uint8_t response[],...)

int	bcam_get_by_response (struct bcam bcam, const uint8_t response[], const uint8_t response_mask[], uint32_t pos, uint8_t out_key[],...)

int	bcam_get_by_key_and_response (struct bcam bcam, const uint8_t key[], const uint8_t key_mask[], const uint8_t response[], const uint8_t response_mask[], uint32_t pos, uint8_t out_key[], uint8_t out_response[],...)

int	bcam_get_by_key (struct bcam *bcam, const uint8_t key[], uint8_t response[],...)

int	bcam_delete (struct bcam *bcam, const uint8_t key[],...)

int	bcam_delete_all (struct bcam *bcam,...)

int	bcam_read_and_clear_ecc_counters (struct bcam bcam, uint32_t corrected_single_bit_errors, uint32_t *detected_double_bit_errors)

int	bcam_read_and_clear_ecc_addresses (struct bcam bcam, uint32_t failing_address_single_bit_error, uint32_t *failing_address_double_bit_error)

int	bcam_set_ecc_test (struct bcam *bcam, bool inject_single_bit_errors, bool inject_double_bit_errors)

int	bcam_destroy (struct bcam *bcam)

int	bcam_get_stats (const struct bcam bcam, uint64_t stats_group, union bcam_stats stats,...)

int	bcam_set_stats_interval (struct bcam *bcam, unsigned period)

Function Documentation

◆ bcam_create()

int bcam_create	(	const cam_arg_t *	cam_arg,
		struct bcam **	out_bcam )

Creates a bcam instance. Returns 0 if successful, otherwise an error code. The bcam 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 bcam instance. cam_arg is copied to the bcam instance, and can be destroyed immediately after this call.
[out]	out_bcam	Returns the newly created bcam instance, memory is allocated using malloc. If bcam_create returns an error the instance is not created. In this case no memory is allocated, and out_bcam is left unchanged.

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

◆ bcam_insert()

int bcam_insert	(	struct bcam *	bcam,
		const uint8_t	key[],
		const uint8_t	response[],
			... )

Inserts an entry to the bcam instance. If an entry with the same key 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 bcam instance. Returns 0 if successful, otherwise an error code.

Parameters

[in]	bcam	Pointer to the bcam instance
[in]	key	The key of the entry. The key width is passed in cam_arg to bcam_create. the key width is set using cam_arg_set_key_width. Any contents outside the scope of the 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 bcams using dram , mixed mode is supported. This means that a second key width is supported. In addition to the wide regular key width specified by cam_arg_set_key_width, a new narrow key width specified by cam_set_narrow_key_width is supported. both wide and narrow keys can be inserted in the same bcam. Using narrow keys save dram memory, e.g an IPv6 flow can be stored as a wide key and an IPv4 flow can be stored as narrow key of half the entry size. If the inserted key is wide or narrow is specified by the options argument.
[in]	response	The response of the entry. The response width of the response is the same for all functions calls and was originally passed in the cam_arg to bcam_create when the instance was created. The response width in cam_arg is specified with cam_arg_set_response_width. Any contents outside the scope of the response width is ignored. The response is assumed to be in little-endian format. response[0] bit 0 is the least significant bit of the response. response[1] bit 0 is bit 8 of the response and so on.
[in]	...	This is an optional (variadic) argument available for dram. If the function cam_arg_enable_options was called for the cam_arg passed to bcam_create then the options argument must be present in all API calls. If cam_arg_enable options was not called, then the options argument must not be present in any API calls. The options argument is a pointer to additional control arguments which are set using the cam_options_*** functions. Options is copied inside the function and can therefore be immediately destroyed after the call.

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

◆ bcam_update()

int bcam_update	(	struct bcam *	bcam,
		const uint8_t	key[],
		const uint8_t	response[],
			... )

Updates an entry in the bcam instance. If the entry is found, the response is updated. If the entry is not found, the function fails with error code CAM_ERROR_KEY_NOT_FOUND. Returns 0 if successful, otherwise an error code.

Parameters

[in]	bcam	Pointer to the bcam instance
[in]	key	See key for bcam_insert
[in]	response	See response for bcam_insert
[in]	...	See variadic options for bcam_insert

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

◆ bcam_get_by_response()

int bcam_get_by_response	(	struct bcam *	bcam,
		const uint8_t	response[],
		const uint8_t	response_mask[],
		uint32_t *	pos,
		uint8_t	out_key[],
			... )

Gets an entry with matching response value. If an entry is found, the function returns 0. If an 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 an 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. bcam_get_by_response uses linear search.

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

Parameters

[in]	bcam	Pointer to bcam instance
[in]	response	The response to search for. See response for bcam_insert.
[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 the compare takes place. This efficiently makes cleared bits in the mask to serve as "don't care" bits. The response_mask is in little-endian format.
[in,out]	pos	Position in the database. Used for consecutive get operations, set to 0 for the first get_by_response. If the function returns with an error code, the pos cannot be sent in again. It is unreliable. The exception is for the error code CAM_ERROR_FOUND_IN_SHADOW_BUT_NOT_IN_HW. For this error code pos can be sent in again to resume the search.
[out]	out_key	The read key. Key width bits are copied to the out_key. The key is in little-endian format. If the function returns with an error code, the out_key is left unchanged except for the error code CAM_ERROR_FOUND_IN_SHADOW_BUT_NOT_IN_HW. For this error code the out_key contains the response stored in the shadow
[in]	...	See variadic options for bcam_insert

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

◆ bcam_get_by_key_and_response()

int bcam_get_by_key_and_response	(	struct bcam *	bcam,
		const uint8_t	key[],
		const uint8_t	key_mask[],
		const uint8_t	response[],
		const uint8_t	response_mask[],
		uint32_t *	pos,
		uint8_t	out_key[],
		uint8_t	out_response[],
			... )

Similar to bcam_get_by_response(), but also allows matching against the key.

Parameters

[in]	bcam	Pointer to bcam instance
[in]	key	The key to search for.
[in]	key_mask	Which bits of the key to compare.
[in]	response	The response to search for.
[in]	response_mask	Which bits of the response to compare.
[in,out]	pos	Position in the database. Used for consecutive get operations, set to 0 for the first get.
[out]	out_key	The matched key, if return value was 0, else undefined.
[out]	out_response	The matched response, if return value was 0, else undefined.
[in]	...	See variadic options for bcam_insert

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

◆ bcam_get_by_key()

int bcam_get_by_key	(	struct bcam *	bcam,
		const uint8_t	key[],
		uint8_t	response[],
			... )

Gets an entry with matching key from the bcam instance. If an entry is not found, the response data is copied from the default response and the return code is CAM_ERROR_KEY_NOT_FOUND. If an entry is found in the instance, the function returns 0 and the response associated with the key is passed.

Parameters

[in]	bcam	Pointer to bcam instance
[in]	key	See key for bcam_insert
[out]	response	The response of the entry. The response width was originally passed in the cam_arg to bcam_create when the instance was created. The response width in cam_arg is specified with cam_arg_set_response_width. Any contents outside the scope of the response width is left unchanged. The response is assumed to be in little-endian format. response[0] bit 0 is the least significant bit of the response. response[1] bit 0 is bit 8 of the response and so on. If the function returns with an error code, the response is left unchanged except for the error code CAM_ERROR_FOUND_IN_SHADOW_BUT_NOT_IN_HW. For this error code the response contains the response stored in shadow.
[in]	...	See variadic options for bcam_insert

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

◆ bcam_delete()

int bcam_delete	(	struct bcam *	bcam,
		const uint8_t	key[],
			... )

Deletes an entry from the bcam 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]	bcam	Pointer to bcam instance
[in]	key	See key for bcam_insert
[in]	...	See variadic options for bcam_insert

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

◆ bcam_delete_all()

int bcam_delete_all	(	struct bcam *	bcam,
			... )

Deletes all entries from the bcam instance. The function does not respect max_hw_writes in cam_arg.

Parameters

[in]	bcam	Pointer to bcam instance
[in]	...	See variadic options for bcam_insert

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

◆ bcam_read_and_clear_ecc_counters()

int bcam_read_and_clear_ecc_counters	(	struct bcam *	bcam,
		uint32_t *	corrected_single_bit_errors,
		uint32_t *	detected_double_bit_errors )

Reads and clears the ECC counters of the bcam instance. When the instance is created the ECC counters are automatically cleared. This function is not supported for dram.

Parameters

[in]	bcam	Pointer to bcam instance
[out]	corrected_single_bit_errors	The number of single bit errors the hardware scrubbing process has detected and corrected permanently. Single bit 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 corrected_single_bit_errors counter is only incremented after the error is corrected permanently. The counter is cleared after this function is called.
[out]	detected_double_bit_errors	The number of detected double-bit errors. Double-bit errors are fatal errors and the cam is corrupt. The hardware cannot correct the error. The instance generates an interrupt every time a double bit error is detected. The error is detected by a lookup or scrubbing. Lookups detecting double-bit errors signals double bit error and it is advised to discard the response from such lookups. The detected_double_bit_errors counter is only incremented by the scrubbing process. The counter is cleared after it is read. Double bit errors should not occur and the memory might be defect.

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

◆ bcam_read_and_clear_ecc_addresses()

int bcam_read_and_clear_ecc_addresses	(	struct bcam *	bcam,
		uint32_t *	failing_address_single_bit_error,
		uint32_t *	failing_address_double_bit_error )

Reads and clears the ECC address registers of the bcam instance. The ECC address registers are automatically cleared when the bcam instance is created. This function is not supported for dram.

Parameters

[in]	bcam	Pointer to bcam instance
[out]	failing_address_single_bit_error	The address of the first single bit error detected and corrected by the hardware scrubbing process since the last call of this function. Additional errors might have been detected during a hardware lookup and then corrected dynamically, but the failing_address_single_bit_error only reflects the errors detected by hardware scrubbing. If there are no errors, 0xfffffffff is returned. If the error occurs for the same address frequently, the memory might be defect.
[out]	failing_address_double_bit_error	The address of the first double-bit error detected by the hardware scrubbing process since the last call of this function. If there are no errors, 0xfffffffff is returned. If double bit errors occur, the memory might be defect.

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

◆ bcam_set_ecc_test()

int bcam_set_ecc_test	(	struct bcam *	bcam,
		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. This function is not supported for dram.

Parameters

[in]	bcam	Pointer to bcam 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.

◆ bcam_destroy()

int bcam_destroy ( struct bcam * bcam )

Destroy bcam instance. All memory allocated by bcam_create is released. The bcam HW memory is not cleared, any remaining entries are unmodified. The debug flag CAM_DEBUG_STATS enables a statistics printout.

Parameters

[in] bcam Pointer to bcam instance

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

◆ bcam_get_stats()

int bcam_get_stats	(	const struct bcam *	bcam,
		uint64_t	stats_group,
		union bcam_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 bcam_stats union for further information.

Parameters

[in]	bcam	Pointer to bcam instance
[in]	stats_group	Selects the group of statistics to be read
[out]	stats	The read statistics

Returns

0 for success.

                         CAM_ERROR_NULL_POINTER if either of the pointer arguments is NULL.

                         CAM_ERROR_INVALID_ARG if the value of 'stats_group' was not
                         recognised.

                         CAM_ERROR_STATISTICS_NOT_AVAILABLE if the hardware does not support
                         returning the information.

                         CAM_ERROR_ENVIRONMENT if reading from the hardware failed in some
                         way.

◆ bcam_set_stats_interval()

int bcam_set_stats_interval	(	struct bcam *	bcam,
		unsigned	period )

Set the sampling interval for statistics gathering.

Parameters

[in]	bcam	Pointer to bcam instance
[in]	period	One of the PEC_SAMPLE_RATE_* constants from pec.h

Returns

0 for success.

                         CAM_ERROR_NULL_POINTER the pointer argument is NULL.

                         CAM_ERROR_INVALID_ARG if the value of 'period' was invalid.

Overview

Functions

Function Documentation

◆ bcam_create()

◆ bcam_insert()

◆ bcam_update()

◆ bcam_get_by_response()

◆ bcam_get_by_key_and_response()

◆ bcam_get_by_key()

◆ bcam_delete()

◆ bcam_delete_all()

◆ bcam_read_and_clear_ecc_counters()

◆ bcam_read_and_clear_ecc_addresses()

◆ bcam_set_ecc_test()

◆ bcam_destroy()

◆ bcam_get_stats()

◆ bcam_set_stats_interval()