semi-ternary cam search v2.2 logicore ip product guide

Semi-Ternary CAM Searchv2.2

LogiCORE IP Product GuideVivado Design Suite

PG319 (v2.2) July 27, 2021

https://www.xilinx.com

Table of ContentsChapter 1: Introduction.............................................................................................. 4

Features........................................................................................................................................4IP Facts..........................................................................................................................................5

Chapter 2: Overview......................................................................................................6Navigating Content by Design Process.................................................................................... 8Licensing and Ordering.............................................................................................................. 9

Chapter 3: Product Specification......................................................................... 10Scheduling..................................................................................................................................11Lookup Operation..................................................................................................................... 12Table Management................................................................................................................... 12Error Correction Coding (ECC).................................................................................................13Performance.............................................................................................................................. 13Port Descriptions.......................................................................................................................16Register Address Space............................................................................................................ 18

Chapter 4: Designing with the Core................................................................... 19General Design Guidelines.......................................................................................................19Clocking...................................................................................................................................... 22Resets..........................................................................................................................................24

Chapter 5: Design Flow Steps.................................................................................25Customizing and Generating the Core...................................................................................25Constraining the Core...............................................................................................................35Simulation.................................................................................................................................. 37Synthesis and Implementation................................................................................................37

Chapter 6: Example Design..................................................................................... 38Simulating the Example Design.............................................................................................. 39

Chapter 7: Software Application Example Design......................................41

PG319 (v2.2) July 27, 2021 www.xilinx.comSemi-Ternary CAM Search IP 2Send Feedback


https://www.xilinx.com/about/feedback/document-feedback.html?docType=Product_Guide&docId=PG319&Title=Semi-Ternary%20CAM%20Search%20v2.2&releaseVersion=2.2&docPage=2

Running the Software Application Example Design............................................................. 42

Appendix A: Upgrading............................................................................................. 43

Appendix B: Debugging.............................................................................................44Finding Help on Xilinx.com...................................................................................................... 44Debug Tools............................................................................................................................... 45Simulation Debug......................................................................................................................46Hardware Debug....................................................................................................................... 46General Checks..........................................................................................................................47

Appendix C: Additional Resources and Legal Notices............................. 48Xilinx Resources.........................................................................................................................48Documentation Navigator and Design Hubs.........................................................................48References..................................................................................................................................49Training Resources....................................................................................................................49Revision History......................................................................................................................... 49Please Read: Important Legal Notices................................................................................... 50




Chapter 1

IntroductionThe Semi-Ternary CAM Search LogiCORE IP (STCAM) implements an associative array datastructure also known as a content-addressable memory. The STCAM stores (key, mask, priority,response) entries with arbitrary key, mask and response bit strings and allows for the retrieval ofthe response based on ternary matching of the lookup key. Ternary matching allows multipleentries to match the same lookup key. The entry with lowest priority is selected as the winner.The STCAM supports a limited number of unique masks, that is each mask is shared by multipleentries. This allows for a considerable logic and memory reduction compared to TCAMs. TheSTCAM is well suited for applications requiring efficient storage of entries using multiple, but alimited number of masks. For example, longest prefix matching of the IP address for IPforwarding tables or OVS mega-flow lookup tables.

Features• Associative array containing arbitrary (key, mask, priority, response) entries.

• Ternary match key lookup returns hit/miss result and associated response value on hit.

• High throughput: one lookup per clock cycle at 600 MHz.

Note: Achievable clock frequencies will depend on the device being used, the resources used by theCAM configuration, and the congestion in the device.

• Flexible: supports a wide range of key widths, response widths and lookup rates withoptimized resource utilization.

• Supports all key widths up to 992 bits and all response widths up to 1024 bits.

• Supports both UltraRAM (URAM) and block RAM implementations.

• Scalable: supports one or multiple STCAM instances, each instance can use all of the blockRAM/URAM within an SLR allowing very large STCAMs.

• High storage efficiency, 95% of the RAM bits are transformed to CAM bits.

• Supports error correction coding (ECC). Single-bit errors are corrected dynamically duringlookups, and permanently with scrubbing.

• Supports Vivado® IP integrator.

• Supports entry insert, delete, update using standard TCAM like software APIs.

Chapter 1: Introduction




• Can be inferred from within P4 code using the Vitis Networking P4 (VitisNetP4) tool.

IP FactsLogiCORE™ IP Facts Table

Core Specifics

Supported Device Family1 UltraScale+™, UltraScale™, Zynq® UltraScale+™, Versal™ ACAP

Supported User Interfaces AXI4-Stream and AXI4-Lite Interfaces

Resources See the CAM Configuration section in the Main Tab topic.

Provided with Core

Design Files Encrypted Verilog RTL

Example Design Verilog

Test Bench Verilog

Constraints File Xilinx Design Constraint (XDC)

Simulation Model Verilog source code

Supported S/W Driver2 Standalone

Software Example Design Application Standalone, Vivado®IP integrator

Tested Design Flows3

Design Entry4 Standalone, VitisNetP4, Vivado® IP integrator.

Simulation5 For supported simulators, see the Xilinx Design Tools: Release Notes Guide.

Synthesis Xilinx Vivado Synthesis

Support

Release Notes and Known Issues Master Answer Record: N/A

All Vivado IP Change Logs Master Vivado IP Change Logs: 72775

Xilinx Support web page

Notes:1. For a complete list of supported devices, see the Vivado® IP catalog.2. Standalone driver details can be found online.3. For the supported versions of the tools, see the Xilinx Design Tools: Release Notes Guide.4. The CAM IP is only supported in the Vivado IP Catalog running on a Linux operating system (not supported on

Windows).5. Modelsim, Questa, VCS, Xcelium, and Xsim are supported. Refer to Vivado Design Suite User Guide: Release Notes,

Installation, and Licensing (UG973) for information on version compatibility.

Chapter 1: Introduction


https://www.xilinx.com/cgi-bin/docs/rdoc?v=2021.1;t=vivado+release+notes

https://www.xilinx.com/support/answers/72775.html

https://www.xilinx.com/support

https://www.xilinx.com/products/intellectual-property/ef-di-cam.html

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2021.1;t=vivado+release+notes

https://www.xilinx.com/cgi-bin/docs/rdoc?v=latest;t=vivado+install+guide



Chapter 2

OverviewThe Semi-Ternary CAM Search IP core (STCAM) is a member of the family of CAMs provided byXilinx®. The family consists of four members:

• Binary CAM (BCAM): Used for exact matching. See the Binary CAM Search LogiCORE IPProduct Guide (PG317).

• Semi TCAM (STCAM): Described in this document. The STCAM is fully flexible in terms ofnumber, size and position of wildcard (don't care) fields. Every key bit has a correspondingmask bit. The number of allowed unique masks is however limited. This allows forconsiderable memory and logic optimizations.

• Ternary CAM (TCAM): The primary usage of TCAM is tables requiring full flexibility in terms ofsize and position of wildcard (don't care) fields. Every key bit has a corresponding mask bitstored together with the key. All entries can have different masks. TCAMs are used for AccessControl List (ACL) type of lookups, requiring a large number of different masks. See theTernary CAM Search LogiCORE IP Product Guide (PG318).

One or multiple instances of each type can be used inside the same FPGA. Different types canalso be mixed inside the same FPGA. Each CAM type is optimized for its specific task in terms ofhardware resource usage.

The STCAM stores (key, mask, priority, response) entries in either UltraRAM (URAM) or blockRAM. The STCAM provides efficient use of FPGA resources compared to basic TCAMimplementations that store the keys in flip-flops and use logic resources for parallel keycomparison.

The Lookup interface of the STCAM receives a lookup key and outputs a result that contains amatch flag indicating whether the masked lookup key matches the masked key of any entry inthe STCAM. The width of the mask is the same as the key width. A cleared mask bit invalidatesthe corresponding key bit and makes it "don't care". Both the lookup key and the stored key arebit-wise ANDed with the mask prior to the bit-wise matching. The STCAM is pipelined so that itcan process a Lookup Request every clock cycle.

If multiple entries are matched, the response value of the matching entry with the lowest priorityis output. If two entries have the same priority, one of them is arbitrarily picked as winner. TheAPI software ensures that two entries with the same masked key value can not be inserted.

Chapter 2: Overview


https://www.xilinx.com/cgi-bin/docs/ipdoc?c=cam;v=latest;d=pg317-bcam.pdf

https://www.xilinx.com/cgi-bin/docs/ipdoc?c=cam;v=latest;d=pg318-tcam.pdf



The entries are read and written using a set of high-level Application Programming Interface (API)functions. The API functions are written in C and delivered as part of the IP. The APIencapsulates the details of memory management and register access and provides a simple andefficient management interface. The API software with detailed documentation is found on the CAM IP product page. The user only provides the functions for basic hardware reads and writesto the API. This allows for flexible hardware mapping and the communications link between theAPI software and the hardware is designed to the users' specifications. The communication linkcould for instance be AXI4-Lite or PCIe®.

The STCAM design is highly configurable at compile time to make it suitable for a large variety ofapplications. The table below lists the configuration parameters.

Table 1: Configuration Parameters

Parameter Name Valid Range Description

KEY_WIDTH 10-992 bitsThe width of the lookup key.KEY_WIDTH + RESPONSE_WIDTH + PRIORITY_WIDTH + 1cannot exceed 1536/2048 [BRAM/URAM]

RESPONSE_WIDTH 1-1024 bits

The width of the lookup response.RESPONSE_WIDTH + PRIORITY_WIDTH cannot exceed1024.KEY_WIDTH + RESPONSE_WIDTH + PRIORITY_WIDTH + 1cannot exceed 1536/2048 [BRAM/URAM]

PRIORITY_WIDTH 0-32 bitsThe width of the priority assigned to each entry.RESPONSE_WIDTH + PRIORITY_WIDTH cannot exceed1024.

NUM_MASKS 2-255The number of unique masks. The CAM compilergenerates a CAM supporting both the specified numberof unique masks and the specified number of entries atthe same time.

NUM_ENTRIES 1 - 1.25M

The supported number of entries (depth). The numberof entries is only limited by the available amount ofmemory in a FPGA SLR. The CAM compiler generates aCAM supporting both the specified number of uniquemasks and the specified number of entries at the sametime.

MEMORY_PRIMITIVE BLOCK or ULTRA orAUTO

The compiler selects the best suited type automatically.This can however be overridden as a user preference.

LOOKUP_RATE 15 - 600 MlpsThis is the supported lookup rate of the instance(expressed in million lookups per second). In order tosave resources it is important not to set the lookup ratehigher than required.

LOOKUP_INTERFACE_FREQ 15-600 MHzThis is the clock frequency of the Lookup Request andresponse interfaces.LOOKUP_INTERFACE_FREQ >= LOOKUP_RATE

RAM_FREQ 15-600 MHz

This is the clock frequency of the memories and theinternal datapath. An optional, high frequency RAMclock enables time division of the hardware resources,leading to significant savings. See the TDM_FACTORparameter.

Chapter 2: Overview





Table 1: Configuration Parameters (cont'd)

Parameter Name Valid Range Description

TDM_FACTOR 1, 2, 4, 8, 16, or 32

The TDM_FACTOR is calculated as:RAM_FREQ / LOOKUP_RATE = 1, 2, 4, 8, 16, or 32The ratio is rounded downwards to the nearest powerof two.Example:RAM clock frequency = 600, Lookup rate = 150 →TDM_FACTOR = 600 / 150 = 4The RAM can be accessed four times per lookup, savingup to four times the RAM and logic resources for smalltable configurations.

CLOCKING_MODE SINGLE-CLOCK orDUAL_CLOCK

The use of a separate RAM clock is optional. IfRAM_FREQ = LOOKUP_INTERFACE_FREQ, then the singleclock mode is enabled. In single clock mode only thelookup interface clock is used for lookup interfaces,RAM and match logic.

All of these parameters are extracted from the P4 code and VitisNetP4 tool during compilation. Ifthe STCAM is used without P4, these parameters need to be set prior to generating thehardware STCAM or calling the software STCAM API. VitisNetP4 ensures that the parametersused to generate the hardware STCAM and those used to create the software STCAM instanceare synchronized. For standalone usage, the user must guarantee that the parameters used togenerate the hardware STCAM and the parameters used to call the software STCAM API areidentical.

Navigating Content by Design ProcessXilinx® documentation is organized around a set of standard design processes to help you findrelevant content for your current development task. All Versal™ ACAP design process DesignHubs can be found on the Xilinx.com website. This document covers the following designprocesses:

• Hardware, IP, and Platform Development: Creating the PL IP blocks for the hardwareplatform, creating PL kernels, functional simulation, and evaluating the Vivado® timing,resource use, and power closure. Also involves developing the hardware platform for systemintegration. Topics in this document that apply to this design process include:

• Port Descriptions

• Clocking

• Customizing and Generating the Core

Chapter 2: Overview


https://www.xilinx.com/support/documentation-navigation/design-hubs.html

https://www.xilinx.com/support/documentation-navigation/design-hubs.html



Licensing and OrderingThis Xilinx® LogiCORE™ IP module is provided under the terms of the Xilinx Core LicenseAgreement. For full access to all core functionalities in simulation and in hardware, you mustpurchase a license for the core. To generate a full license, visit the product licensing web page.Evaluation licenses and hardware timeout licenses may be granted for this core. Contact your local Xilinx sales representative for information about pricing and availability.

Note: To verify that you need a license, check the License column of the IP Catalog. Included means that alicense is included with the Vivado® Design Suite; Purchase means that you have to purchase a license touse the core.

For more information about this core, visit the Semi-Ternary CAM Search IP product web page.

Information about other Xilinx® LogiCORE™ IP modules is available at the Xilinx IntellectualProperty page. For information about pricing and availability of other Xilinx LogiCORE IP modulesand tools, contact your local Xilinx sales representative.

Licensing information is available on the CAM IP product page.

License CheckersIf the IP requires a license key, the key must be verified. The Vivado® design tools have severallicense checkpoints for gating licensed IP through the flow. If the license check succeeds, the IPcan continue generation. Otherwise, generation halts with an error. License checkpoints areenforced by the following tools:

• Vivado Synthesis

• Vivado Implementation

• write_bitstream (Tcl command)

IMPORTANT! IP license level is ignored at checkpoints. The test confirms a valid license exists. It does notcheck IP license level.

Chapter 2: Overview


https://www.xilinx.com/cgi-bin/docs/ipdoc?t=core+license

https://www.xilinx.com/cgi-bin/docs/ipdoc?t=core+license

https://www.xilinx.com/getlicense

https://www.xilinx.com/about/contact.html


https://www.xilinx.com/products/intellectual-property.html

https://www.xilinx.com/products/intellectual-property.html

https://www.xilinx.com/about/contact.html




Chapter 3

Product SpecificationThe functional block diagram of the core is shown in the following figure.

Figure 1: Core Block Diagram

FIFO

FIFO

AXI4-Slave

FIFO

FIFO

CAM Database

Registers & Memory

Lookup Request Interface

Lookup Response Interface

Lookup Interface Frequency

RAM Frequency

RAM Frequency

AXI4-Lite Frequency

Mgmt Response Interface

Mgmt Request Interface

AXI4-Lite

API Software

Strict Priority Scheduler

AXI4-Stream Slave

AXI4-Stream Master

X21980-062420

Chapter 3: Product Specification




The previous figure contains the following sub-blocks:

• CAM Database: Memory and registers for storage of rules and logic for algorithmic lookupmatching.

• Lookup Request FIFO (Optional): Transfers Lookup Requests from the Lookup Frequencydomain to the RAM Frequency domain.

• Lookup Response FIFO (Optional): Transfers Lookup Responses from the RAM Frequencydomain to the Lookup Frequency domain.

• Management Request FIFO: Buffering queue for input Management Requests.

• Management Response FIFO: Buffering queue for Management Responses.

• Strict Priority Scheduler: Schedules lookup and Management Requests.

• AXI4-Lite interface slave: Protocol handling for accepting read/write requests and generatingresponses. The AXI4-Lite interface uses 13 bits of address and 32 bits of data.

The following clock domains are depicted in the block diagram:

• AXI4-Stream Lookup Interface Frequency: The clock frequency of the Lookup Request/Response interfaces. Depending on configuration parameters a new Lookup Request mayarrive every cycle, every second cycle, every fourth cycle, etc.

• RAM Frequency: The clock frequency of the internal RAM and match logic.

• AXI4-Lite Frequency: The clock frequency of the AXI Lite bus.

The clocking of the CAM can be set to one of two modes:

• Single Clock Mode: If the Lookup Interface Frequency and RAM Frequency are equal, then theRAM clock is not used and the Lookup Request/Response FIFOs are removed completely.

• Dual Clock Mode: If the RAM Frequency is higher than the Lookup Interface Frequency,shallow FIFOs are inserted to bridge the clock domains.

SchedulingThe Strict Priority Scheduler always selects a request from the Lookup Request FIFO first. Arequest can only be scheduled from the Management Request FIFO when the Lookup RequestFIFO is empty.

When the Management Request FIFO becomes full, the AXI4-Slave stops accepting newManagement Requests to prevent loss of Management Requests.





For every Lookup Request processed by the CAM database a Lookup Response is generated. TheLookup Response is sent to the Lookup Response Interface. For a read Management Request, theresponse is sent to the Management Response Interface. Write Management Requests do notgenerate a Management Response. The Management Response Interface can only buffer oneManagement Response. The AXI4-Slave blocks the CPU read operation until the ManagementResponse is available and sent on the AXI4-Lite interface.

Lookup OperationThe CAM Database stores the (key, mask, priority, response) entries and performs matching byprocessing a Lookup Request. If the masked lookup key matches the masked key of any entry,there is a matching entry. If there are multiple matches the entry with the lowest priority winsand outputs its response value. If the priority is the same, the entry is selected arbitrarily. The APIsoftware ensures that two entries using the same masked key can not be inserted.

The number of unique masks is limited to allow for efficient use of logic and memory resources.Since many entries share the same mask, the mask is stored per-memory rather than per-entry.

If the masked lookup key does not match the masked key of any entry, a no match indication isnormally output. The STCAM supports an optional default response. If the default response isused, the STCAM outputs the default response instead of outputting the no match indication.The default response entry is a special entry without any mask part. This is not necessary sincethe entry always matches if no other entry is matched.The number of unique masks is limited toallow for efficient use of logic and memory resources. Since many entries share the same mask,the mask is stored per-memory rather than per-entry.

Table ManagementIn addition to processing Lookup Requests, the CAM Database also processes ManagementRequests. The CAM Database is fully pipelined. If the TDM factor is one, a new Lookup Requestis processed every RAM clock cycle. If the TDM factor is two, a Lookup Request takes two RAMclock cycles to complete, and so on. The CAM Database can process one Management Requestin a single RAM clock cycle, independent of the TDM factor.





Error Correction Coding (ECC)All memories in the CAM database are ECC protected. There are eight additional ECC bits forevery address in a 64-bit wide memory. The eight additional bits are only used for ECC and cannot be used for storage. 64-bit wide memories are always referred in this document (even though72 bits are used).

A scrubbing mechanism starts regularly (approximately 1 ms interval) and reads every memoryaddress of the CAM in the background using idle cycles. If a single-bit error is detected duringscrubbing, the error is corrected permanently by writing the corrected data back to the memory.Single-bit errors detected during lookup operations are corrected dynamically. If a double-biterror is detected during lookup, there will be no match. In general, if double-bit errors aredetected during lookups it is recommended to drop the packet issuing the lookup. There are twostatistic counters for ECC:

• Single-bit errors: This counter increments for errors detected and corrected during scrubbing.

• Double-bit errors: This counter increments for double-bit errors detected during scrubbing.

The address of the first failing RAM location is stored in a register for diagnostic purposes. Thereare two status outputs related to ECC: Single-bit/double-bit error detected. The outputs are validfor one cycle (Lookup Interface clock domain) whenever an error is detected by the ECCscrubber. The status outputs can be used to trigger a CPU interrupt. When the CPU reads thestatistics counters the counters are cleared.

The software API provides a debug function to enable insertion of single-bit/double-bit errorsduring write operations. With the error insertion enabled subsequent insert/update/deleteoperations will store data in memory with errors. Note that it takes up to 2 ms before the ECCscrubber detects the errors which can be observed on the status outputs / error counters.

PerformanceMaximum Frequencies

The Semi-Ternary CAM Search IP is designed to run at up to 600 MHz in UltraScale+™-2 speedgrade devices.





Latency

The STCAM lookup latency depends on the size of the STCAM, the TDM factor and memorytype. The lookup latency is constant and some examples are shown in the following table.

Table 2: Lookup Latency [Block RAM / UltraRAM]

Entries TDM Factor = 1 TDM Factor = 4 TDM Factor = 16 TDM Factor = 32256 29/29 13/13 9/9 9/9

1K 29/29 13/13 9/9 9/9

4K 30/29 13/13 9/9 9/9

16K 32/29 13/13 10/10 NA/9

Note: Latency values are measured in Lookup Interface Frequency cycles.

KEY_WIDTH = 32, RESPONSE_WIDTH = 16, NUM_MASKS = 32, LOOKUP_RATE =LOOKUP_INTERFACE_FREQ.

Throughput

The lookup throughput corresponds to the LOOKUP_RATE parameter. The highest possiblelookup throughput is accomplished when LOOKUP_RATE equals the RAM _FREQ parameter.One Lookup Request can then be issued per RAM clock cycle. The Management Request hasstrictly lower priority than the Lookup Request, consequently the Management Requestthroughput becomes:

Management Request Rate = RAM_FREQ - LOOKUP_RATE*TDM_FACTOR

The ECC scrubbing process has the lowest priority. A memory read followed by a potentialcorrective write is only executed if both the Lookup Request and Management Request FIFOsare empty. Neither the lookup throughput nor the Management Request throughputs areaffected. ECC scrubbing of a new address is only initiated if both FIFOs are empty and a potentialpending corrective write has been executed.

All read and write Management Requests are 32 bits wide. The only exception is for a writeManagement Request of entry data. These Management Requests might be wider as described inthe section below. The Management Request width for entry data is essential for correctdimensioning of the lookup rate and RAM frequency in order to have throughput headroom forManagement Requests.





To perform management updates while maintaining correct state for lookups, the managementoperations need to be atomic. This means that a complete entry must be written to the CAMDatabase before the entry is made active (valid). To accomplish wide writes, an entry is writtenusing multiple Management Requests where the last Management Request sets the valid bit.When an already existing entry is being updated, the valid bit is already set. This means that theresponse data needs to be written using only a single Management Request. For this reason aManagement Request writes at least (priority + response + valid) width bits of data. The totalwidth is rounded upwards to the next 64-bit boundary. For a 160-bit key with 72 bits of priority+ response + valid, assume that the following is written:

• Key, 160 bits

• Priority + Response + Valid, 72 bits

In total, 232 bits are written. The width of priority + response + valid is 72 bits, this will berounded to 128 bits. Each Management Request writes 128 bits. With rounding up, 232/128 = 2write Management Requests are sent.

The AXI4-Lite bus uses 13 bits of address and 32 bits of data, so for every Management Requestmultiple AXI4-Lite writes are issued from the API software. The AXI4-Lite writes are assembledby the AXI4-Slave to a single Management Request. The AXI4-Lite interface is a standard type.Refer to AXI4-Lite IPIF LogiCORE IP Product Guide (PG155).

The table below shows an example calculation for 100Gb Ethernet rate. Keep in mind thecalculated update rate only refers to the hardware resources, the final update rate is most likelylimited by the table management software.

Table 3: 100GbE Update Rate Example Calculation (hardware limit)

Management Request Size [bits] AXI Lite Write Operations[min / max]

Management Update rate[M updates/s]

64 1 / 3 4.8

128 2 / 5 2.4

256 4 / 9 1.2

512 8 / 17 0.6

1024 16 / 33 0.3

Note: Parameters used in this example: LOOKUP_RATE = 148.8, RAM_FREQ = 600, TDM_FACTOR = 4

Note: AXI Lite minimum values apply when the write data is constant (for example initializing to zero).Maximum values apply for general write data patterns.



https://www.xilinx.com/cgi-bin/docs/ipdoc?c=axi_lite_ipif;v=latest;d=pg155-axi-lite-ipif.pdf



Port Descriptions

System Interface PortsTable 4: System Interface

Port Name I/O Clock Description

rstn IAsynchronous reset (active_low). The reset input issynchronized internally to both the ram_clk and key_clkdomains.

rst_busy O s_axi_aclk Reset Busy is an active high indicator that the core iscurrently in reset state.

ram_clk I The ram clock is used for the internal RAM and matchlogic.

sbiterr O key_clkSingle-bit error output status. A single-bit error hasbeen detected and corrected by the ECC scrubbingmechanism.

dbiterr O key_clk Double-bit error output status. A double-bit error hasbeen detected by the ECC scrubbing mechanism.

debug_status[31:0] O Debug status port.

Lookup Interface PortsTable 5: Lookup Interface

Port Name I/O Clock Descriptions_axis_lkup_tdata[S_LKUP_WIDTH-1:0] I key_clk The Lookup Request key. tdata is padded with zeros to

a byte multiple length.

s_axis_lkup_tready O key_clk

tready indicates that the core is ready to accept lookuprequests. The ratio of LOOKUP_INTERFACE_FREQ andLOOKUP_RATE determines how frequently new lookupscan be started. If LOOKUP_INTERFACE_FREQ equalsLOOKUP_RATE than lookups can be started every clockcycle without gaps.

s_axis_lkup_tvalid I key_clkIndicates that the lookup request key is valid. A lookupis initiated when both tready and tvalid are high for oneclock cycle.

m_axis_lkup_tdata[M_LKUP_WIDTH-1:0] O key_clk The response value associated with the matching entry.

m_axis_lkup_tready O key_clktready for M_AXIS_DATA channel. Tie high if thedownstream slave is always able to accept data fromM_AXIS_DATA.

m_axis_lkup_tvalid I key_clk tvalid for M_AXIS_DATA channel.





Figure 2: s_axis_lkup_tdata

ZeroPadding

LookupKeyKEY_WIDTH

MSB 0

S_LKUP_WIDTH-1 S_LKUP_KEY_POS

X24118-061120

S_LKUP_KEY_POS = 0

S_LKUP_WIDTH = 8 x floor((KEY_WIDTH + 7) / 8)

Figure 3: m_axis_lkup_tdata

ZeroPadding

LookupKeyKEY_WIDTH

MSB 0

M_LKUP_WIDTH-1

ZeroPadding

MatchFlag1

ResponsePriorityPRIORITY_WIDTH

M_LKUP_KEY_POS M_LKUP_FLAG_POS

ZeroPadding

M_LKUP_PRIO_POS

ZeroPadding

ResponseValueRESPONSE_WIDTH

M_LKUP_RESP_POS

Double-bit Error

1

X24134-072121

M_LKUP_RESP_POS = 0

M_LKUP_PRIO_POS = 8 x floor((RESPONSE_WIDTH + 7) / 8)

M_LKUP_FLAG_POS = 8 x (floor((PRIORITY_WIDTH + 7) / 8) + floor((RESPONSE_WIDTH + 7) /8))

M_LKUP_KEY_POS = 8 x (1 + floor((PRIORITY_WIDTH + 7) / 8) + floor((RESPONSE_WIDTH +7) / 8))

M_LKUP_WIDTH = 8 x (floor((KEY_WIDTH + 7) / 8) + 2 + floor((PRIORITY_WIDTH + 7) / 8) +floor((RESPONSE_WIDTH + 7) / 8))

New AXI-Stream response flag for lookup ECC double-bit errors, located after the MatchFlag.





Figure 4: Lookup Interface Timing Diagram

Register Address SpaceThe user of the API Software must provide a hardware write and hardware read function for theAPI software to call once it needs to access the hardware. The hardware write and read functionsuse address, data and a user specified context as arguments. The data is 32 bits wide and theaddress is 13 bits wide. The context can be used to differentiate multiple instances, thus allowthe same functions to be used for multiple instances. The user of the API software must map the13-bit wide address space used by each CAM instance to a hardware base address in both thehardware write and read functions. The STCAM is accessed through the API and the registerspace is fully abstracted and therefore not listed. You do not need to directly access the registersin the IP; the driver supplied with the IP interfaces to the hardware under the hood and thereforedirect accesses are not required.





Chapter 4

Designing with the CoreThis chapter includes guidelines and additional information to facilitate designing with the core.

General Design GuidelinesImplementation in Block RAM vs. UltraRAMThe STCAM requires a minimum number of RAM read accesses depending on the number ofmasks. For small STCAMs it is therefore beneficial to use block RAM.

Each RAM has associated logic, therefore as the STCAM size increases, less logic resources willbe used if the total number of RAMs is kept low. This can be accomplished by using deeperRAMs, such as UltraRAM, or depth cascaded block RAMs.

The API software calculates and selects the optimum solution in terms of hardware resources. Ifthe target device has more spare capacity for a certain RAM type, the MEMORY_PRIMITIVEparameter can be forced to this RAM type even if it is less efficient, because it will provide betteroverall device utilization.

QuantificationThe total width of an entry is calculated as:

Entry Width = KEY_WIDTH + RESPONSE_WIDTH + PRIORITY_WIDTH + 1

The valid bit adds one extra bit to the entry width. In order to access the whole entry in parallel anumber of block RAMs or URAMs are used. Block RAMs are allocated in data width incrementsof 64 bits. URAMs are allocated in data width increments of 128 bits (except for entry widths of64 bits and less). To avoid quantification losses it is beneficial if the entry size is close below or ona data width boundary. For example, if the total block RAM entry size is 308 bits, thequantification loss is only 12 bits per entry: 5*64 - 308 = 12.

The maximum supported entry widths are listed in the following table.

Chapter 4: Designing with the Core




Table 6: Maximum Supported Entry Widths

DEPTH MEMORY_PRIMITIVE ENTRY_WIDTH512 BLOCK 1536

1024 BLOCK 7681

2048 BLOCK 3841

2048 ULTRA 2048

4096 ULTRA 1024

8192 ULTRA 512

16384 ULTRA 2561

Notes:1. Not available for RAM_FREQ over 400 MHz.

Storage EfficiencyFor basic STCAM operation a certain number of RAM accesses are required based on the numberof masks and the number of entries. The number of RAM accesses required due to the number ofmasks is fixed and does not depend on the number of entries. For this reason the hardware costis relatively high for small tables with few entries. Due to this, the storage efficiency for smallSTCAMs is lower. For larger STCAMs the cost related to the number of masks gets amortized bya larger number of entries and the storage efficiency increases. For large STCAMs the storageefficiency approaches 95%.

For STCAMs used for Longest Prefix Match (LPM) IP forwarding, it is often beneficial to use anarrow width response for indirection since there are many more forwarding entries than nexthops. For example, if there are 1M IPv4 routes, but only 32K next hops, a 15-bit wide responsewould be sufficient to point out the next hops. Indirection is also useful for other purposes; if anext hop changes, then only the next hop entry needs to be modified instead of thousands offorwarding entries. For LPM, the number of priorities is also limited to the number of prefixlengths. This should be considered when the priority width is configured.

For IPv6 forwarding tables it is beneficial to separate routes and host routes. Routes require a64-bit wide LPM lookup and host routes a 128-bit wide exact match lookup. By separating theroutes and host routes, the cost related to the number of masks is reduced and 64 bits of keydata is saved for every route. One way of doing this is to lookup the 64-bit wide network part ofthe IPv6 packets in a 64-bit wide STCAM. If the lookup matches a host route, the response fromthe routing table could be a compressed IPv6 network part. For example, the 64 bits of thenetwork part is compressed to 16 bits and returned as response data. These 16 bits togetherwith the 64 remaining bits of the host part can be looked up in an 80-bit wide BCAM. If there areroutes with a prefix length between 64 and 128, the second BCAM can be replaced with anSTCAM using 16 bits of exact match and 64 bits of LPM.





Resource Time SharingThe CAM Database is designed to run at a clock frequency of up to 600 MHz and process oneLookup Request every clock cycle. A search operation requires a number of RAM accesses. TheRAM accesses can be performed in parallel using multiple RAM instances, sequentially byperforming multiple accesses in the same RAM, or by a combination of both parallel andsequential access. For example if the RAM Frequency is 600 MHz and the Lookup rate is 300MLookups per second, two accesses can then be performed using the same RAM.

The possible amount of time sharing of the RAM is calculated using integer division:

TDM_FACTOR = RAM_FREQ / LOOKUP_RATE

The TDM_FACTOR is rounded down to the nearest power of two and capped at 32. Thefollowing values are allowed: 1, 2, 4, 8, 16, and 32.

Table 7: Clock Configuration Examples

Ethernet Speed Lookup Rate[Mlps]

LookupInterface

Frequency[MHz]

RAM ClockFrequency

[MHz]Clocking Mode TDM Factor

10G 15 15 15 SINGLE_CLOCK 1

10G 15 30 30 SINGLE_CLOCK 2

10G 15 30 480 DUAL_CLOCK 32

100G 150 150 150 SINGLE_CLOCK 1

100G 150 300 300 SINGLE_CLOCK 2

100G 150 300 600 DUAL_CLOCK 4

400G 600 600 600 SINGLE_CLOCK 1

Registering SignalsTo simplify timing and increase system performance in a programmable device design, keep allinputs and outputs registered between the user application and the core. This means that allinputs and outputs from the user application should come from, or connect to, a flip-flop. Whileregistering signals might not be possible for all paths, it simplifies timing analysis and makes iteasier for the Xilinx® tools to place and route the design.

Make Only Allowed ModificationsYou should not modify the core. Any modifications can have adverse effects on system timingand protocol compliance. Supported user configurations of the core can only be made byselecting the options in the customization IP dialog box when the core is generated.





Update PerformanceThe API software is single threaded and uses one core for its processing.

Changes to the CAM database are made using the insert, update, or delete functions. Therequired processing for these operations increases with the fill level of the CAM database. Therequired processing increases with the CAM width but does not increase with CAM depth. Theinsert function is twice as fast as the update and delete functions.

Configuration Example

The performance of the configuration listed below is 200k inserts per second:

• Key size = 32, number of masks = 32, response size = 16.

• CAM database = 100,000 keys from a synthesized 100,000 key large IPv4 routing table.

• CAM database is empty and then filled with 100,000 keys.

• CPU=i7-7600U, 2.80 GHz. 4 MB 16-way set associative shared cache.

ClockingTable 8: Clocks

Clock Description

s_axi_aclk The AXI clock is used for table management. The AXI management interface has a completelyasynchronous relationship with the lookup interface.

key_clk AXI4-Stream clock for Lookup Request/Response interfaces.

ram_clk

The ram_clk is optional. It provides an option to clock the internal RAM and match logic on a separatehigh frequency clock. In most cases this saves logic and memory resources.Guideline:

• key_clk <= 300 MHz, use ram_clk up to 600 MHz

• key_clk > 300 MHz, ram_clk is not used

Single Clock ModeSingle clock mode is activated by specifying the same value for bothLOOKUP_INTERFACE_FREQ and RAM_FREQ. The ram_clk port is not used in single clockmode. The Lookup interfaces, internal RAM and match logic are all clocked on the key_clk.

Note: Single clock mode is recommended for Lookup rates above 300 Mlps.





Dual Clock ModeIn dual clock mode the internal RAM and match logic is clocked on a separate high frequencyclock ram_clk. This enables a high TDM_FACTOR to be used without increasing the frequencyof the Lookup Interface.

Note: Both ram_clk and key_clk must be derived from the same PLL in order to avoid clock drift.

TDM Factor Settings for Clock ModesTable 9: TDM Factor Settings for Clock Modes

TDM Factor LOOKUP RATE[Mlps]

LOOKUPINTERFACE FREQ

[MHz]RAM CLOCK [MHz] CLOCKING MODE

32 Up to 18.75 Minimum32xLOOKUP_RATE

LOOKUP_IF_FREQ SINGLE CLOCK

32 Up to 18.75 MinimumLOOKUP_RATE

Minimum32xLOOKUP_RATE

DUAL CLOCK

16 Up to 37.5 Minimum16xLOOKUP_RATE


16 Up to 37.5 MinimumLOOKUP_RATE


DUAL CLOCK

8 Up to 75 Minimum8xLOOKUP_RATE


8 Up to 75 MinimumLOOKUP_RATE


DUAL CLOCK





DUAL CLOCK





DUAL CLOCK



Note: Dual clock mode is recommended for lookup rates up to 300 Mlps.





ResetsAt startup, both the AXI reset and the main reset must be asserted simultaneously for four cyclesof the slower of the two clocks (s_axi_aclk and key_clk). As long as the reset assertion timeis met, either reset can be asserted or negated first. The system is not ready to use until the resetphase is finished (indicated by the rst_busy output). The rst_busy output is high forapproximately 30 clock cycles (slowest clock).





Chapter 5

Design Flow StepsThis chapter describes customizing and generating the core, constraining the core, and thesimulation, synthesis and implementation steps that are specific to this IP core. More detailedinformation about the standard Vivado® design flows and the IP integrator can be found in thefollowing Vivado® Design Suite user guides:

• Vivado Design Suite User Guide: Designing IP Subsystems using IP Integrator (UG994)

• Vivado Design Suite User Guide: Designing with IP (UG896)

• Vivado Design Suite User Guide: Getting Started (UG910)

• Vivado Design Suite User Guide: Logic Simulation (UG900)

Customizing and Generating the CoreThis section includes information about using Xilinx® tools to customize and generate the core inthe Vivado Design Suite. Following are instructions on how to deploy the CAMs using the CAMIP standalone. The CAMs can also be deployed as part of VitisNetP4 systems. For instructions onhow to deploy in VitisNetP4, see the Vitis Networking P4 User Guide (UG1308) (registrationrequired).

CAM IP version 2.2 (cam_v2_2) is released as part of the Vivado 2021.1 release. The CAM IPcan be instantiated in Vivado in two different ways; using the IP integrator or using the IPCatalog. CAM IP versions must be used with the equivalent versions of the Vivado tool. Forexample, CAM IP v2.2 must be paired with Vivado version 2021.1.

IP IntegratorIf you are customizing and generating the core in the Vivado IP integrator, see the Vivado DesignSuite User Guide: Designing IP Subsystems using IP Integrator (UG994) for detailed information. IPintegrator will auto-compute certain configuration values when validating or generating thedesign. To check whether the values change, see the description of the parameter in this chapter.To view the parameter value you can run the validate_bd_design command in the TclConsole.

To instantiate the CAM IP in Vivado Design Suite using IP integrator, follow these steps:

Chapter 5: Design Flow Steps


https://www.xilinx.com/cgi-bin/docs/rdoc?v=latest;d=ug994-vivado-ip-subsystems.pdf

https://www.xilinx.com/cgi-bin/docs/rdoc?v=latest;d=ug896-vivado-ip.pdf

https://www.xilinx.com/cgi-bin/docs/rdoc?v=latest;d=ug910-vivado-getting-started.pdf

https://www.xilinx.com/cgi-bin/docs/rdoc?v=latest;d=ug900-vivado-logic-simulation.pdf

https://www.xilinx.com/member/sdnet/




1. Open a project in the Vivado tool.

2. Click Create Block Design in the panel on the left.

3. Right-click in the Diagram window and select Add IP.

4. Search for "cam" in the search box of the window that appears and select CAM IP.

5. The CAM IP can be configured by double-clicking the instantiated IP.





IP CatalogYou can customize the IP for use in your design by specifying values for the various parametersassociated with the IP core using the following steps:

1. Select the IP from the IP catalog.

2. Double-click the selected IP or select the Customize IP command from the toolbar or right-click menu.

For details, see the Vivado Design Suite User Guide: Designing with IP (UG896) and the VivadoDesign Suite User Guide: Getting Started (UG910).

To instantiate the CAM IP using the IP Catalog, follow these steps:

1. Open a project in Vivado.

2. Click IP Catalog in the panel on the left. Search for "cam" in the search box of the IP Catalogwindow and select CAM IP.

3. The CAM IP can be configured by double-clicking the instantiated IP.

The CAM IP core in the Vivado Design Environment (IDE) has several fields used to setparameter values for the particular instantiation required. The following section providesdescriptions for each field.

• Component Name: The name of the core component to be instantiated. The name must beginwith a letter and be composed of the following characters: a to z, A to Z, 0 to 9 and ‘_’.







Main Tab• Lookup Mode: Options available in this pull-down menu are: BCAM, STCAM, and TCAM.

Depending on the option selected, the configuration parameters available will change.

• BCAM: Selects the Binary Content Addressable Memory. Figure 5: BCAM ConfigurationParameters shows the configuration parameters when BCAM is selected. Refer to theBinary CAM Search LogiCORE IP Product Guide (PG317) (Registration required).

• STCAM: Selects the Semi-Ternary Content Addressable Memory. Figure 6: STCAMConfiguration Parameters shows the configuration parameters when STCAM is selected.STCAM is described in this document.

• TCAM: Selects the Ternary Content Addressable Memory. Figure 7: TCAM ConfigurationParameters shows the configuration parameters when TCAM is selected. Refer to theTernary CAM Search LogiCORE IP Product Guide (PG318) (Registration required).

Figure 5: BCAM Configuration Parameters







Figure 6: STCAM Configuration Parameters





Figure 7: TCAM Configuration Parameters

• MEMORY_PRIMITIVE: Options available in this pull-down menu are: AUTO, BLOCK, andULTRA.

• AUTO: The Vivado CAM compiler will select the best suited memory type, either beingblock RAM or URAM, automatically. The respective block RAM/URAM resource usage isshown in the "CAM Configuration Information" section of the GUI.

• BLOCK: User specifies the memory primitive to be block RAM. The block RAM resourceusage is shown in the "CAM Configuration Information" section of the GUI.

• ULTRA: User specifies the memory primitive to be URAM. The URAM resource usage isshown in the "CAM Configuration Information" section of the GUI.

• NUM_ENTRIES: The supported number of entries (depth). The number of entries is limited bythe number of RAM instances used:

• RAM_FREQ <= 480 MHz: 480 BRAM or 320 URAM





• RAM_FREQ > 480 MHz:: 320 BRAM or 160 URAM

Note:

(BCAM only) NUM_ENTRIES represent number of usable entries. When targeting a certain memorydepth for a BCAM, specify 95% of the target. For example, to get a BCAM with memory of depth4K, specify NUM_ENTRIES = 0.95 x 4096 = 3891.

• NUM_MASKS: The number of unique masks. The Vivado CAM compiler generates a STCAMsupporting both the specified number of unique masks and the specified number of entries atthe same time.

Note: This parameter is only available for STCAM.

• KEY_WIDTH: The width of the lookup key.

Note: This parameter is only available for BCAM and STCAM.

• FORMAT_STRING:

Note: This parameter is only available for TCAM.

The format string describes the format of all keys and masks. A key consists of several fieldsand the format string specifies the location and size of the fields. In the format string, fieldsare separated by a colon ':'. The format string is read left to right. The first field corresponds tothe least significant bit of the key. The key is specified as little-endian. Each field is specifiedwith a field length and field type. There are no alignment restrictions for the fields. Thelocation, type, number, and size of fields is fully flexible. The following field types and lengthsare supported:

• b - bit field: The field mask is either all zeroes or all ones; field_len = 1..128 bit, complexity= 2

• t - ternary field: The field mask can have any value; field_len = 2..16 bit, complexity =2^field_len

• c - constant bit field: The mask is all ones; field_len = 1..128 bit, complexity = 1

• u - unused bit field: The mask is all zeroes; field_len = 1..128 bit, complexity = 1

• p - prefix field: The mask has a pattern of consecutive zeroes and ones; field_len = 1..128bit, complexity = field_len + 1

• r - range field: Matching is performed with logic comparators within start/end values

• RESPONSE_WIDTH: The width of the lookup response.

• DEFAULT_RESPONSE_VALUE: Specify the Default Response value when Lookup has nomatch. Valid range between 1 to 1024 bits specified in Hex. The value is set to zero by default.

• TEST_FEATURE: This is a test feature and should be left at the default value of zero.

Note: This parameter is only available for BCAM.





• OPTIMIZATION: Options available in this pull-down menu are: AUTO, RAM, and LOGIC. Thelogic usage is proportional to the number of Physical Memory Units. The RAM usage andnumber of Memory Units are shown in the CAM Configuration Information section of theGUI:

• AUTO: The Vivado CAM generator will balance the usage of logic and RAM resources.

• RAM: Use this option to reduce RAM usage at a potentially higher logic usage.

• LOGIC: Use this option to reduce logic usage at a potentially higher RAM usage.

• OPTIMIZE_ENTRIES: When this check box is selected, use the available memory to insertentries beyond the specified NUM_ENTRIES limit. A side effect for STCAM is that thespecified NUM_MASKS value is no longer guaranteed but is ‘up to’ instead. Refer to the rowBRAM36/URAM Utilization in the Figure 8: CAM Configuration Information table forresulting values based on this selection.

Note: This parameter is only available for BCAM and STCAM.

• OPTIMIZE_MASKS: When this check box is selected, use the available memory to insert moremasks than the specified NUM_MASKS limit. A side effect of this is that the specifiedNUM_ENTRIES value is no longer guaranteed but ‘up to’ instead. Refer to the rows BRAM36/URAM Utilization and Number of Masks in the Figure 8: CAM Configuration Information tablefor resulting values based on this selection.

Note: This parameter is only available for STCAM.

• LOGICAL_MEM_UNITS: Force Number of Logical Memory Units, the value will be rounded upto a multiple of the TDM_FACTOR. This is an Advanced Feature and it is recommended to usethe AUTO selection.

• AUTO: When this check box is selected, the Vivado CAM compiler automatically calculatesthe appropriate value for LOGICAL_MEM_UNITS. You can override this by deselecting thecheck box and specifying the appropriate value.

• PRIORITY_WIDTH:

Note: This parameter is only available for STCAM and TCAM

The priority is usually defined wide enough to support one unique priority value per entry.The width can be larger to facilitate easier STCAM and TCAM management or narrower ifentries are order independent and guaranteed not to overlap.

• AUTO: When this check box is selected, the Vivado CAM compiler automatically calculatesthe appropriate value for PRIORITY_WIDTH based on NUM_ENTRIES for TCAM, andNUM_MASKS for STCAM.. You can override this by deselecting this check box andspecifying the appropriate value.

For STCAM, the PRIORITY_WIDTH is calculated to accomodate NUM_MASKS differentpriorities and for TCAM it is calculated to accomodate NUM_ENTRIES different priorities.





• LOOKUP_RATE: This is the supported lookup rate of the CAM instance (expressed in millionlookups per second). In order to save resources it is important not to set the lookup ratehigher than required.

• CLOCKING_MODE: Options available in this pull-down menu are: SINGLE CLOCK and DUALCLOCK. When SINGLE CLOCK is selected the configuration parameter RAM_FREQ is notavailable.

• LOOKUP_INTERFACE_FREQ: This is the clock frequency for the Lookup Request andResponse Interfaces, specified in MHz.

• RAM_FREQ: This is the clock frequency for the memories (block RAM/URAM) and theinternal datapath, specified in MHz. Specifying a higher frequency RAM clock enables timedivision of the hardware resources, leading to significant resource savings. This configurationparameter is only available when CLOCKING_MODE = DUAL CLOCK is selected.

Note: Note when CLOCKING_MODE = SINGLE CLOCK, RAM_FREQ = LOOKUP_INTERFACE_FREQ.

• CAM Configuration Information: This table provides interactive information based on theconfiguration parameter values entered. It allows a quick way to converge on the requiredCAM settings for the design needs. The information provided is shown in the following figure.

Figure 8: CAM Configuration Information

• Memory Depth: The depth of the resulting memory based on the value of configurationparameter NUM_ENTRIES.

• Memory Width: The width of the resulting memory based on configuration parametervalues entered. The contributing composition of the individual components (which varydepending on the Lookup Mode selected) to the width is also provided. For example, theunused component (if not zero) indicates to the user that the other component sizes can beincreased with no additional memory resource penalty.

• BRAM36/URAM Utilization: The memory utilization efficiency.

• BRAM36 Usage: The number of resulting BRAM36s used to implement the requiredmemory size. A value of 0 indicates no BRAM36s are used.

• URAM Usage: The number of resulting URAMs used to implement the required memorysize. A value of 0 indicates no URAMs are used.





• Memory Units: Each Physical Memory Units requires logic resources. The number ofPhysical Memory Units can be used to compare relative logic resource cost betweendifferent configurations.

• Lookup Latency: The lookup latency value indicated in multiples of theLOOKUP_INTERFACE_FREQ clock cycles.

• Lookup Interface Frequency: The LOOKUP_INTERFACE_FREQ frequency and the numberof lookups occurring per LOOKUP_INTERFACE_FREQ clock cycle.

• RAM Clock Frequency: The RAM_FREQ frequency (note when CLOCKING_MODE =SINGLE CLOCK, RAM_FREQ = LOOKUP_INTERFACE_FREQ). And the way the memorybandwidth is split between Lookup Requests and Management Requests.

• TDM Factor: The time division multiplexing of hardware resources. The value indicateddescribes the number of memory accesses per Lookup Request. When the value isindicated as “capped” then a lower RAM_FREQ can be chosen without additional memoryresource penalty.

• Number of Masks: Displays the number of masks used for STCAM only.

• Debug Flags: The debug flags can be enabled or disabled via selection of the tick-boxes asshown in the following figure, thus enabling /disabling the respective debug functions. Thedebug functions are controlled via the DEBUG_FLAGS parameter, a 32-bit integer, whosevalue is also shown in grey specified as "Debug Flags Value". Details of what each debugfunction does can be found in the Debugging section.

Figure 9: Debug Flags

Note: During HDL simulation the DEBUG_FLAGS values can be modified dynamically as required.

Related Information

Debugging

User Parameters

The following table shows the relationship between the fields in the Vivado IDE and the UserParameters (which can be viewed in the Tcl Console).





Table 10: Vivado IDE Parameter to User Parameter Relationship

Vivado IDE Parameter User Parameter Default ValueLookup Mode MODE BCAM

MEMORY_PRIMITIVE MEM_TYPE AUTO

NUM_ENTRIES NUM_ENTRIES 256

NUM_MASKS NUM_MASKS 2

KEY_WIDTH KEY_WIDTH 104

FORMAT_STRING FORMAT_STRING 32p:32p:16r:16r:8b

RESPONSE_WIDTH RESP_WIDTH 16

PRIORITY_WIDTH PRIO_WIDTH 8

DEFAULT_RESPONSE_VALUE DEFAULT_RESPONSE 0x0000

AUTO PRIO_WIDTH_AUTO_SEL true

LOOKUP_RATE LOOKUP_RATE 15.0

CLOCKING_MODE CLOCKING_MODE DUAL CLOCK

LOOKUP_INTERFACE_FREQ LOOKUP_INTERFACE_FREQ 15.0

RAM_FREQ RAM_FREQ 480.0

OPTIMIZATION OPTIMIZATION AUTO

OPTIMIZATION_ENTRIES OPTIMIZATION_ENTRIES false

OPTIMIZATION_MASKS OPTIMIZATION_MASKS false

LOGICAL_MEM_UNITS L_MEM_UNITS 4

AUTO L_MEM_UNITS_AUTO_SEL true

Debug Flags DEBUG_FLAGS 262242

Output Generation

For details, see the Vivado Design Suite User Guide: Designing with IP (UG896).

Note: When the CAM IP is generated, a simulation SystemVerilog package file is also created with thename <instance-name>_sim_pkg.sv. This file contains the SystemVerilog task create whichcontains the configuration settings used for this particular CAM IP instance. You can use this simulationpackage file and thus the SystemVerilog tasks in it in their own testbench if desired.

Constraining the CoreThis section contains information about constraining the core in the Vivado Design Suite.






Required Constraints

RAM Placement

The constraint file contains macro definitions for the RAM instances. The RAMs are grouped in anumber of placement macros. Each macro is one RAM column wide. The number of createdmacros depend on the CAM instance size.

False Paths

Apply the following false path constraints adjusted accordingly to the user’s design.

# asynchronous resetset_false_path -from [get_ports rstn]set_false_path -from [get_ports s_axi_aresetn]

Device, Package, and Speed Grade SelectionsSupported Device Families are: UltraScale, UltraScale+

Clock FrequenciesThis section is not applicable for this IP core.

Clock ManagementIf CLOCKING_MODE = DUAL CLOCK is selected, then the two clocks:LOOKUP_INTERFACE_FREQ and RAM_FREQ should be sourced/derived from the same clockgenerator (MMCM or PLL).

Clock PlacementThis section is not applicable for this IP core.

BankingThis section is not applicable for this IP core.





SimulationFor comprehensive information about Vivado simulation components, as well as informationabout using supported third party tools, see the Vivado Design Suite User Guide: Logic Simulation(UG900).

Synthesis and ImplementationFor details about synthesis and implementation, see the Vivado Design Suite User Guide: Designingwith IP (UG896).







Chapter 6

Example DesignThe following figure shows the configuration of the example design.

Figure 10: Example Design Configuration

Stimulus(data.sv)

Control

AXM

DUT

LIF

Testbench

example_top_sv

axi_lite_master.sv

CAM IP Instance

lookup_interface.sv

X23608-010720

The example design contains the following:

• An instance of the CAM IP core based on the user configuration settings selected

• An AXI-Lite Master block

• A Lookup Interface block

• Stimulus file (currently restricted to 10 entries to reduce simulation time)

• Clocks and reset generation logic

• Testbench control logic

Chapter 6: Example Design




Simulating the Example DesignThe CAM IP generator core provides a quick way to simulate and observe the behavior of thecore by using the provided example design, which has a self-checking testbench that uses SystemVerilog Direct Programming Interface (DPI). It is recommended that you familiarize yourself withSection 35 of IEEE 1800-2017 to gain a more complete understanding of its functionality.

1. In the new Example Design Vivado project, change the target simulator:

a. Click Settings under the PROJECT MANAGER section in the left-hand panel. The Settingswindow displays.

b. Select Simulation under Project Settings, and select the target simulator you want to use,as shown in the following figure.

2. Verify that the compiled library location is set correctly and points to the correct pre-compiled simulation libraries for the simulator being used. See the Vivado Design Suite UserGuide: Logic Simulation (UG900) for instructions on how to compile simulation libraries.



https://standards.ieee.org/standard/1800-2017.html




Note: When the example design for the CAM IP is generated a simulation SystemVerilog package file is alsocreated with the name <instance-name>_sim_pkg.sv. This file contains the SystemVerilog taskcreate which contains the configuration settings used for this particular CAM IP instance.

Optional Features

• Backdoor feature: This feature speeds up simulation runtime when enabled for behavioralsimulations only. This feature is disabled by default. To enable this feature, perform thefollowing edit to the file:

• axi_lite_master.sv: Set the define CAM_BACKDOOR

• Dump Memory feature: This feature allows memory contents to be dumped at the end of thetest for behavioral simulations only. This feature is disabled by default. To enable this feature,perform the following edit to the file:

• example_top.sv: Set the parameter DUMP = 1;





Chapter 7

Software Application ExampleDesign

The CAM IP generator core provides a quick way to run a C based software example applicationand observe the behavior of the core by using the provided Software Application example design,which has a self-checking testbench. The Software Application example design makes use offunctions defined in the CAM Driver API Description (cam-api-reference_v2.2.zip).

Standalone driver details can be found on the CAM IP product page.

After configuring the CAM IP based on your design requirements, and selecting the GenerateOutput Products… option to generate the core outputs, the Software Application example designis created.

If the default directory location is specified, then a sw directory will be created at the followinglocation:

<user_location>/project_1/project_1.srcs/sources_1/ip/<cam_instance_name>/sw

For example if the CAM IP instance name is cam_0 then the location would be:

<user_location>/project_1/project_1.srcs/sources_1/ip/cam_0/sw

This sw directory contains the sub-directories detailed in the following table:

Table 11: Sub-directory Descriptions

Sub-directory Descriptionsw/cam_src CAM IP obfuscated source code.

sw/dpi DPI cam_dpi.so library generation.Refer to the readme.txt file on instructions on how to use this if customization is required.

Chapter 7: Software Application Example Design






Table 11: Sub-directory Descriptions (cont'd)

Sub-directory Descriptionsw/sw_example Software Application Example Design

The following three file names will be prepended with the CAM IP instance name chosen.For instance, if the CAM IP instance name is cam_0, then the files would be named:

1. cam_0.c

2. cam_0.h

3. cam_0_example.c – top level containing "main"

data_stim.c – the stimulus file restricted to 10 entries only.Makefile – used by make to generate the executable. Name of the executable would becam_0_example.

The Software Application example design performs the following tasks:

• Creates an instance of the CAM, based on the settings selected by the user, via the CAM APIfunctions.

• Based on the input stimulus file data_stim.c.

○ insert entry

○ read entry by key

○ read entry by response

○ delete entry

• Print out the results to the console window.

Running the Software Application ExampleDesign

1. Change directory to the location of the sw_example directory.

2. Run the make command to generate the executable.

3. Run the generated executable. For example, output from "make" would be cam_0_exampleif the instance name cam_0 was chosen

Chapter 7: Software Application Example Design




Appendix A

UpgradingThis appendix is not applicable for the first release of the core.

Appendix A: Upgrading




Appendix B

DebuggingThis appendix includes details about resources available on the Xilinx Support website anddebugging tools.

Finding Help on Xilinx.comTo help in the design and debug process when using the core, the Xilinx Support web pagecontains key resources such as product documentation, release notes, answer records,information about known issues, and links for obtaining further product support. The XilinxCommunity Forums are also available where members can learn, participate, share, and askquestions about Xilinx solutions.

DocumentationThis product guide is the main document associated with the core. This guide, along withdocumentation related to all products that aid in the design process, can be found on the XilinxSupport web page or by using the Xilinx® Documentation Navigator. Download the XilinxDocumentation Navigator from the Downloads page. For more information about this tool andthe features available, open the online help after installation.

Solution CentersSee the Xilinx Solution Centers for support on devices, software tools, and intellectual propertyat all stages of the design cycle. Topics include design assistance, advisories, and troubleshootingtips.

Answer RecordsAnswer Records include information about commonly encountered problems, helpful informationon how to resolve these problems, and any known issues with a Xilinx product. Answer Recordsare created and maintained daily ensuring that users have access to the most accurateinformation available.

Appendix B: Debugging


https://www.xilinx.com/support.html

https://forums.xilinx.com/




https://www.xilinx.com/support/download.html

https://www.xilinx.com/support/solcenters.htm



Answer Records for this core can be located by using the Search Support box on the main Xilinxsupport web page. To maximize your search results, use keywords such as:

• Product name

• Tool message(s)

• Summary of the issue encountered

A filter search is available after results are returned to further target the results.

Technical SupportXilinx provides technical support on the Xilinx Community Forums for this LogiCORE™ IP productwhen used as described in the product documentation. Xilinx cannot guarantee timing,functionality, or support if you do any of the following:

• Implement the solution in devices that are not defined in the documentation.

• Customize the solution beyond that allowed in the product documentation.

• Change any section of the design labeled DO NOT MODIFY.

To ask questions, navigate to the Xilinx Community Forums.

Debug ToolsThere are many tools available to address Semi-Ternary CAM Search IP design issues. It isimportant to know which tools are useful for debugging various situations.

Vivado Design Suite Debug FeatureThe Vivado® Design Suite debug feature inserts logic analyzer and virtual I/O cores directly intoyour design. The debug feature also allows you to set trigger conditions to capture applicationand integrated block port signals in hardware. Captured signals can then be analyzed. Thisfeature in the Vivado IDE is used for logic debugging and validation of a design running in Xilinx®

devices.

The Vivado logic analyzer is used to interact with the logic debug LogiCORE IP cores, including:

• ILA 2.0 (and later versions)

• VIO 2.0 (and later versions)

See the Vivado Design Suite User Guide: Programming and Debugging (UG908).







https://www.xilinx.com/cgi-bin/docs/rdoc?v=latest;d=ug908-vivado-programming-debugging.pdf



Simulation DebugDebug functions are controlled via the DEBUG_FLAGS parameter. DEBUG_FLAGS is a 32-bitinteger where every bit controls a debug function. There are also symbolic names defined forevery debug function in header files.

RECOMMENDED: Declare DEBUG_FLAGS a single time in the testbench and set the same value for bothsoftware and Verilog hardware model. For software use the API function cam_arg_set_debug_flags.For Verilog hardware set the DEBUG_FLAGS parameter on the instance.

Table 12: Debug Flags

Debug Flag DescriptionCAM_DEBUG_NO_ERROR_MSG Disable printout of software error messages.

CAM_DEBUG_ARGS Software echoes input arguments.

CAM_DEBUG_VERIFY_WR Software immediately reads back written data from hardware forverification. Mismatching data is reported with error message.

CAM_DEBUG_VERIFY_SHADOW 'get_by_response' and 'get_by_key' operations read data from hardwareand verifies software shadow data

CAM_DEBUG_VERBOSE_VERIFY Enables printout of all verify operations, including correct compare.Applies to CAM_DEBUG_VERIFY_WR, CAM_DEBUG_VERIFY_SHADOW, andCAM_DEBUG_VERIFY_CONFIG.

CAM_DEBUG_SKIP_MEM_INIT Skip memory initialization, useful to speedup Verilog simulation.

CAM_DEBUG_CONFIG Enable printout of configuration parameters for both software and Veriloghardware simulation.

CAM_DEBUG_KEY_MASKING Enable error check for the presence of key value '1' in masked(wildcarded) bit position. Applies stcam and tcam input arguments.

CAM_DEBUG_STATS Enable statistics printout in the 'bcam_destroy' and 'stcam_destroy'functions.

CAM_DEBUG_SEGMENTS Software prints segment map for virtualized bcam (vbcam).

CAM_DEBUG_SKIP_VERIFY_CONFIG Skip verification of hardware/software configuration parameters.

CAM_DEBUG_SET_COVER Software prints heap and set cover information for tcam.

CAM_DEBUG_CONFIG_ARGS Software prints cam_arg values before creating the instance.

CAM_DEBUG_HW_WR Verilog hardware prints write operations.

CAM_DEBUG_HW_RD Verilog hardware prints read operations.

CAM_DEBUG_HW_LOOKUP Verilog hardware prints lookup operations.

Hardware DebugHardware issues can range from link bring-up to problems seen after hours of testing. Thissection provides debug steps for common issues. The Vivado® debug feature is a valuableresource to use in hardware debug. The signal names mentioned in the following individualsections can be probed using the debug feature for debugging the specific problems.





Table 13: Debug Status Port

Port Name Description

Clock Domain[SINGLE_CLOCK /

DUAL_CLOCK]

debug_status[0] Address decoding failed for write operation (unknown address – possiblycaused by mismatch between software and hardware configurationparameters)

key_clk / ram_clk

debug_status[1] Address decoding failed for read operation (unknown address – possiblycaused by mismatch between software and hardware configurationparameters)

key_clk / ram_clk

debug_status[2] AXI read data FIFO overflow (read data is not accepted fast enough) key_clk / ram_clk

debug_status[3] AXI write response FIFO overflow (write response channel not respondingfast enough)

s_axi_clk

debug_status[4] AXI read/write request FIFO overflow. Read/write operations are notexecuted fast enough. Possible problems:

1. key_clk/ram_clk frequency is too low compared to s_axi_clkfrequency.

2. Not enough idle cycles on the Lookup Request interface (AXI read/write operatons are only executed during idle lookup cycles).

s_axi_clk

debug_status[5] Lookup Request FIFO overflow (ram_clk frequency is too low compared tokey_clk frequency, or actual lookup rate is higher than the configuredlookup rate)

key_clk

debug_status[6] Lookup Response FIFO overflow (ram_clk frequency is too high comparedto key_clk frequency)

key_clk / ram_clk

debug_status[31:7] Unused

General ChecksEnsure that all the timing constraints for the core were properly incorporated and that allconstraints were met during implementation.

• Does it work in post-place and route timing simulation? If problems are seen in hardware butnot in timing simulation, this could indicate a PCB issue. Ensure that all clock sources areactive and clean.

• If using MMCMs in the design, ensure that all MMCMs have obtained lock by monitoring thelocked port.

• If your outputs go to 0, check your licensing.





Appendix C

Additional Resources and LegalNotices

Xilinx ResourcesFor support resources such as Answers, Documentation, Downloads, and Forums, see XilinxSupport.

Documentation Navigator and Design HubsXilinx® Documentation Navigator (DocNav) provides access to Xilinx documents, videos, andsupport resources, which you can filter and search to find information. To open DocNav:

• From the Vivado® IDE, select Help → Documentation and Tutorials.

• On Windows, select Start → All Programs → Xilinx Design Tools → DocNav.

• At the Linux command prompt, enter docnav.

Xilinx Design Hubs provide links to documentation organized by design tasks and other topics,which you can use to learn key concepts and address frequently asked questions. To access theDesign Hubs:

• In DocNav, click the Design Hubs View tab.

• On the Xilinx website, see the Design Hubs page.

Note: For more information on DocNav, see the Documentation Navigator page on the Xilinx website.

Appendix C: Additional Resources and Legal Notices




https://www.xilinx.com/cgi-bin/docs/ndoc?t=design+hubs

https://www.xilinx.com/cgi-bin/docs/rdoc?t=docnav



ReferencesThese documents provide supplemental material useful with this guide:

1. Binary CAM Search LogiCORE IP Product Guide (PG317)

2. Ternary CAM Search LogiCORE IP Product Guide (PG318)

3. HBM/DDR4 Binary CAM Search LogiCORE IP Product Guide (PG336)

4. Vitis Networking P4 User Guide (UG1308) (registration required)

5. Vitis Networking P4 Installation Guide and Release Notes (UG1307) (registration required)

6. Vitis Networking P4 Getting Started Guide (UG1373) (registration required)

7. Vivado Design Suite User Guide: Designing IP Subsystems using IP Integrator (UG994)

8. Vivado Design Suite User Guide: Designing with IP (UG896)

9. Vivado Design Suite User Guide: Getting Started (UG910)

10. Vivado Design Suite User Guide: Logic Simulation (UG900)

11. https://standards.ieee.org/standard/1800-2017.html

12. AXI4-Lite IPIF LogiCORE IP Product Guide (PG155)

Training Resources1. Vivado Design Suite Hands-on Introductory Workshop

Revision HistoryThe following table shows the revision history for this document.

Section Revision Summary07/27/2021 Version 2.2

Initial release. N/A



https://www.xilinx.com/cgi-bin/docs/ipdoc?c=cam;v=latest;d=pg317-bcam.pdf

https://www.xilinx.com/cgi-bin/docs/ipdoc?c=cam;v=latest;d=pg318-tcam.pdf

https://www.xilinx.com/cgi-bin/docs/ipdoc?c=cam;v=latest;d=pg336-hbm-ddr4-bcam.pdf








https://standards.ieee.org/standard/1800-2017.html

https://www.xilinx.com/cgi-bin/docs/ipdoc?c=axi_lite_ipif;v=latest;d=pg155-axi-lite-ipif.pdf

https://www.xilinx.com/training/vivado/vivado-intro-workshop.htm



Please Read: Important Legal NoticesThe information disclosed to you hereunder (the "Materials") is provided solely for the selectionand use of Xilinx products. To the maximum extent permitted by applicable law: (1) Materials aremade available "AS IS" and with all faults, Xilinx hereby DISCLAIMS ALL WARRANTIES ANDCONDITIONS, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TOWARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, OR FITNESS FOR ANYPARTICULAR PURPOSE; and (2) Xilinx shall not be liable (whether in contract or tort, includingnegligence, or under any other theory of liability) for any loss or damage of any kind or naturerelated to, arising under, or in connection with, the Materials (including your use of theMaterials), including for any direct, indirect, special, incidental, or consequential loss or damage(including loss of data, profits, goodwill, or any type of loss or damage suffered as a result of anyaction brought by a third party) even if such damage or loss was reasonably foreseeable or Xilinxhad been advised of the possibility of the same. Xilinx assumes no obligation to correct anyerrors contained in the Materials or to notify you of updates to the Materials or to productspecifications. You may not reproduce, modify, distribute, or publicly display the Materialswithout prior written consent. Certain products are subject to the terms and conditions ofXilinx's limited warranty, please refer to Xilinx's Terms of Sale which can be viewed at https://www.xilinx.com/legal.htm#tos; IP cores may be subject to warranty and support terms containedin a license issued to you by Xilinx. Xilinx products are not designed or intended to be fail-safe orfor use in any application requiring fail-safe performance; you assume sole risk and liability foruse of Xilinx products in such critical applications, please refer to Xilinx's Terms of Sale which canbe viewed at https://www.xilinx.com/legal.htm#tos.

AUTOMOTIVE APPLICATIONS DISCLAIMER

AUTOMOTIVE PRODUCTS (IDENTIFIED AS "XA" IN THE PART NUMBER) ARE NOTWARRANTED FOR USE IN THE DEPLOYMENT OF AIRBAGS OR FOR USE IN APPLICATIONSTHAT AFFECT CONTROL OF A VEHICLE ("SAFETY APPLICATION") UNLESS THERE IS ASAFETY CONCEPT OR REDUNDANCY FEATURE CONSISTENT WITH THE ISO 26262AUTOMOTIVE SAFETY STANDARD ("SAFETY DESIGN"). CUSTOMER SHALL, PRIOR TO USINGOR DISTRIBUTING ANY SYSTEMS THAT INCORPORATE PRODUCTS, THOROUGHLY TESTSUCH SYSTEMS FOR SAFETY PURPOSES. USE OF PRODUCTS IN A SAFETY APPLICATIONWITHOUT A SAFETY DESIGN IS FULLY AT THE RISK OF CUSTOMER, SUBJECT ONLY TOAPPLICABLE LAWS AND REGULATIONS GOVERNING LIMITATIONS ON PRODUCTLIABILITY.



https://www.xilinx.com/legal.htm#tos





Copyright

© Copyright 2021 Xilinx, Inc. Xilinx, the Xilinx logo, Alveo, Artix, Kintex, Spartan, Versal, Virtex,Vivado, Zynq, and other designated brands included herein are trademarks of Xilinx in the UnitedStates and other countries. AMBA, AMBA Designer, Arm, ARM1176JZ-S, CoreSight, Cortex,PrimeCell, Mali, and MPCore are trademarks of Arm Limited in the EU and other countries. PCI,PCIe, and PCI Express are trademarks of PCI-SIG and used under license. All other trademarksare the property of their respective owners.





semi-ternary cam search v2.2 logicore ip product guide

Documents