Overview

The CDSTCAM combines a small, fast "cache" STCAM (typically implemented in hard logic) with a much larger DRAM-based "miss handler" CAM (typically implemented in FPGA fabric with off-chip memory) to achieve higher performance than a pure DRAM STCAM can provide.

This driver manages both hardware blocks in a unified fashion, hiding the implementation details so that the caller can treat the CDSTCAM as a single memory device.

To initialise this driver it is necessary to pass two sets of hardware read/write functions, one for the cache and one for the miss handler:

void init() {
    ...
    cam_arg_set_hw_io(cam_arg, CDSTCAM_REG_CACHE, cache_write, cache_read);
    cam_arg_set_hw_io(cam_arg, CDSTCAM_REG_MISS_HANDLER, miss_handler_write, miss_handler_read);
    ...
}

Inserts are performed by first allocating a mask and then inserting entries that reference it:

void insert(...) {
    ...
    cdstcam_mask_id_t mask_id;
    cdstcam_mask_alloc(cam, mask, &mask_id);
    cdstcam_insert(cam, key, mask_id, 0, response);
    ...
}

Data Structures
union	cdstcam_stats

Typedefs
typedef uint16_t	cdstcam_mask_id_t

Enumerations
enum	cdstcam_registers { CDSTCAM_REG_MISS_HANDLER, CDSTCAM_REG_CACHE }

Functions
int	cdstcam_create (const cam_arg_t cam_arg, struct cdstcam *out_cdstcam)

int	cdstcam_mask_alloc (struct cdstcam cdstcam, const uint8_t mask[], cdstcam_mask_id_t id)

int	cdstcam_mask_free (struct cdstcam *cdstcam, cdstcam_mask_id_t id)

int	cdstcam_insert (struct cdstcam *cdstcam, const uint8_t key[], cdstcam_mask_id_t mask, uint32_t priority, const uint8_t response[])

int	cdstcam_update (struct cdstcam *cdstcam, const uint8_t key[], cdstcam_mask_id_t mask, const uint8_t response[])

int	cdstcam_iterate (struct cdstcam cdstcam, const uint8_t key[], const uint8_t key_mask[], const uint8_t response[], const uint8_t response_mask[], cdstcam_mask_id_t mask, uint32_t pos, uint8_t out_key[], uint8_t out_response[], cdstcam_mask_id_t out_mask, uint32_t out_priority)

int	cdstcam_delete (struct cdstcam *cdstcam, const uint8_t key[], cdstcam_mask_id_t mask)

int	cdstcam_lookup (struct cdstcam *cdstcam, const uint8_t key[], uint8_t response[])

int	cdstcam_read_and_clear_ecc_counters (struct cdstcam cdstcam, uint32_t corrected_single_bit_errors, uint32_t *detected_double_bit_errors)

int	cdstcam_read_and_clear_ecc_addresses (struct cdstcam cdstcam, uint32_t failing_address_single_bit_error, uint32_t *failing_address_double_bit_error)

int	cdstcam_set_ecc_test (struct cdstcam *cdstcam, bool inject_single_bit_errors, bool inject_double_bit_errors)

int	cdstcam_get_stats (const struct cdstcam cdstcam, uint64_t stats_group, union cdstcam_stats stats)

void	cdstcam_destroy (struct cdstcam *cdstcam)

void	cdstcam_poll (struct cdstcam *cdstcam)

Data Structure Documentation

union cdstcam_stats

Structure used to return statistics to the caller. The CDSTCAM_STATS_* constants determine which member of the union will be filled in by cdstcam_get_stats().

Typedef Documentation

typedef uint16_t cdstcam_mask_id_t

The CDSTCAM supports a limited number of masks. Masks are identified by small integers from 0 to N-1 where N is the maximum number of masks supported by the instance.

Enumeration Type Documentation

enum cdstcam_registers

Register block numbers.

Used as arguments to cam_arg_set_hw_io() when configuring the instance.

Enumerator
CDSTCAM_REG_MISS_HANDLER	Miss handler register interface
CDSTCAM_REG_CACHE	Cache register interface

Function Documentation

int cdstcam_create	(	const cam_arg_t *	cam_arg,
		struct cdstcam **	out_cdstcam
	)

Creates a CAM 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 instance. cam_arg is copied to the stcam instance, and can be destroyed immediately after this call.
[out]	out_cdstcam	Returns the newly created instance. Memory is allocated using malloc. If cdstcam_create returns an error the instance is not created. In this case no memory is allocated, and out_cdstcam is left unchanged.

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

int cdstcam_mask_alloc	(	struct cdstcam *	cdstcam,
		const uint8_t	mask[],
		cdstcam_mask_id_t *	id
	)

Allocate a mask.

Parameters

[in]	cdstcam	Pointer to the instance
[in]	mask	The ternary mask to allocate. The width is specified when the instance is created.
[out]	id	On success, the newly assigned ID.

Return values

0	Success.
CAM_ERROR_FULL	All available IDs are allocated.

int cdstcam_mask_free	(	struct cdstcam *	cdstcam,
		cdstcam_mask_id_t	id
	)

Free an allocated mask.

This operation is only permitted if the CDSTCAM contains no entries for the given mask.

Parameters

[in]	cdstcam	Pointer to the instance
[in]	id	The mask ID to deallocate.

Return values

0	Success.
CAM_ERROR_INVALID_ARG	The mask ID was not allocated.
CAM_ERROR_NOT_EMPTY	There are entries in the CDSTCAM for this mask.

int cdstcam_insert	(	struct cdstcam *	cdstcam,
		const uint8_t	key[],
		cdstcam_mask_id_t	mask,
		uint32_t	priority,
		const uint8_t	response[]
	)

Inserts an entry. If the key is already present, the function fails by returning error code CAM_ERROR_DUPLICATE_FOUND. If the key is not found, then it is inserted.

Parameters

[in]	cdstcam	Pointer to the instance
[in]	key	The key. The key width (in bits) of the instance specifies the number of bits which will be copied from the argument. Any content 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.
[in]	mask	The mask associated with this key, as returned by cdstcam_mask_alloc().
[in]	priority	The priority of the entry. Not used in this implementation.
[in]	response	The response of the entry. The response width of the instance specifies how many bits are copied and stored as response. The response is in little-endian format.

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

int cdstcam_update	(	struct cdstcam *	cdstcam,
		const uint8_t	key[],
		cdstcam_mask_id_t	mask,
		const uint8_t	response[]
	)

Updates an entry's response. If the entry is found, the response is updated. For an entry to be found, both the key and mask must match the "old entry". 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]	cdstcam	Pointer to the instance
[in]	key	The key. The key width (in bits) of the instance specifies the number of bits which will be used from the argument. Any content 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.
[in]	mask	The mask associated with this key, as returned by cdstcam_mask_alloc().
[in]	response	The response of the entry. The response width of the instance specifies the number of bits copied from the argument. Any content outside the scope of the response width is ignored. The response is in little-endian format.

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

int cdstcam_iterate	(	struct cdstcam *	cdstcam,
		const uint8_t	key[],
		const uint8_t	key_mask[],
		const uint8_t	response[],
		const uint8_t	response_mask[],
		cdstcam_mask_id_t	mask,
		uint32_t *	pos,
		uint8_t	out_key[],
		uint8_t	out_response[],
		cdstcam_mask_id_t *	out_mask,
		uint32_t *	out_priority
	)

Iterate over entries in the CDSTCAM.

The key, key_mask, response and response_mask allow the returned values to be limited to those which contain particular bit values in particular positions.

The pos argument should be set to zero when the function is first called. If it returns success, it can be called again with the same pos value to find the next matching entry. The search is complete when it returns CAM_ERROR_KEY_NOT_FOUND.

Any of the output parameters may be NULL if the caller is not interested in the corresponding value.

Parameters

[in]	cdstcam	Pointer to instance
[in]	key	The key value to search for. May be NULL to specify that any stored key should match.
[in]	key_mask	Mask limiting the search to certain subfields of the key. Set bits in this mask specify bits of the key which should be matched against the stored entry; clear bits in this mask will match against any value in the stored entry. May be NULL to specify that any stored key should match.
[in]	response	The response value to search for. May be NULL to specify that any stored response should match.
[in]	response_mask	Mask limiting the search to certain subfields of the response. Set bits in this mask specify bits of the response which should be matched against the stored entry; clear bits in this mask will match against any value in the stored entry. May be NULL to specify that any stored response should match.
[in]	mask	Which ternary mask to search for, as returned by cdstcam_mask_alloc(). May be CDSTCAM_MASK_ID_NONE to specify that any ternary mask should match.
[in,out]	pos	Current position of the iteration. Use 0 for the first call.
[out]	out_key	The matched key.
[out]	out_response	The matched response.
[out]	out_mask	The ternary mask of the matched entry.
[out]	out_priority	The priority of the matched entry. Always zero in this implementation.

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

int cdstcam_delete	(	struct cdstcam *	cdstcam,
		const uint8_t	key[],
		cdstcam_mask_id_t	mask
	)

Delete an entry from the instance. If the entry is found, the function returns 0. For an entry to be found both the key and mask must match an "old" entry. If an entry is not found, the function fails with error code CAM_ERROR_KEY_NOT_FOUND.

Parameters

[in]	cdstcam	Pointer to instance
[in]	key	The key to delete. The key. The key width (in bits) of the instance specifies the number of bits which will be copied from the argument. Any content 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.
[in]	mask	The mask associated with this key, as returned by cdstcam_mask_alloc().

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

int cdstcam_lookup	(	struct cdstcam *	cdstcam,
		const uint8_t	key[],
		uint8_t	response[]
	)

Looks up an entry in the 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.

This function is intended for testing and debugging, and is not designed for particularly high performance.

Parameters

[in]	cdstcam	Pointer to instance
[in]	key	The key to lookup. The key. The key width (in bits) of the instance specifies the number of bits in the key. Any content 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.
[out]	response	The response from the lookup. The response is in little-endian format.

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

int cdstcam_read_and_clear_ecc_counters	(	struct cdstcam *	cdstcam,
		uint32_t *	corrected_single_bit_errors,
		uint32_t *	detected_double_bit_errors
	)

Reads and clears the ECC counters of the instance. When the instance is created the ECC counters are automatically cleared. This function always returns zero.

Parameters

[in]	cdstcam	Pointer to 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 cdstcam_read_and_clear_ecc_addresses	(	struct cdstcam *	cdstcam,
		uint32_t *	failing_address_single_bit_error,
		uint32_t *	failing_address_double_bit_error
	)

Reads and clears the ECC address registers of the instance. The ECC adresses registers are automatically cleared when the instance is created. This function always returns zero.

Parameters

[in]	cdstcam	Pointer to 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 reflect 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 cdstcam_set_ecc_test	(	struct cdstcam *	cdstcam,
		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]	cdstcam	Pointer to 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 cdstcam_get_stats	(	const struct cdstcam *	cdstcam,
		uint64_t	stats_group,
		union cdstcam_stats *	stats
	)

Reads statistics information. The statistics information is organized into different groups. The statistics associated with a certain group are read from the instance. See documentation for the members of the cdstcam_stats union for further information.

If this function returns an error, the contents of the cdstcam_stats union are undefined.

Parameters

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

Return values

0	Success.
CAM_ERROR_INVALID_ARG	The value of 'stats_group' was not recognised, or one of the pointer arguments is NULL.
CAM_ERROR_ENVIRONMENT	Reading from the hardware failed in some way.

void cdstcam_destroy ( struct cdstcam * cdstcam )

Destroy instance. Release all memory previously allocated by cdstcam_create.

The driver will ensure that any lookups received prior to invoking this function will complete normally before the deletion takes effect. The behaviour is undefined if lookups arrive after this function has been invoked.

Parameters

[in] cdstcam Pointer to instance.

void cdstcam_poll ( struct cdstcam * cdstcam )

Poll the hardware and perform internal optimisations.

This function reads the hit counters from the hardware and takes steps to respond to changes in the distribution of received lookup requests.

User code should call this function at a frequency of greater than 1 Hz. This frequency is a best guess for now and it may be increased if it is found not to be sufficient in practice.

If this function is not called, lookups will still operate correctly, however the performance may suffer and some of the values returned by cdstcam_get_stats() may be inaccurate.

This function cannot fail, and will never fail in future driver versions, because it is anticipated that callers will want to invoke it from a context in which handling errors is difficult or impossible.

Parameters

[in] cdstcam Pointer to instance.

Overview

Data Structures

Typedefs

Enumerations

Functions

Data Structure Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation