Open Ethernet Networking (OpEN) API Guide and Reference Manual  3.6.0.3
Ternary Content Addressable Memory (TCAM)

The TCAM API allows the user to create policies directly in the TCAM. These policies co-exist with those created by the ICOS image and can be configured to have a priority higher or lower than them. The current version of TCAM-API adds the policies to the Egress Field Processor (EFP) or the Ingress Field Processor (IFP) based on the policy type.

The TCAM API also supports reporting the current number of rules used in the TCAM hardware and the number of rules still available. The TCAM usage is reported per stack unit per ASIC. The usage information is available for all policies in the system, including the policies created by the TCAM API and policies created by other applications.

TCAM OpEN API

This document provides a brief description of the TCAM OpEN API. The TCAM OpEN API allows processes outside of the ICOS main process (switchdrvr) to create policies directly to TCAM. It provides the following services:

Policy

The openapiTcamPolicyCreate() API takes as parameter the open_tcamApiPolicy_t structure which details the policy information. Each policy consists of

Policy Version 2.0

The openapiTcamPolicyCreateV2() API takes as parameter the open_tcamApiPolicy_v2_t structure which details the policy information. Each policy consists of

Policy Header

The header should be populated with the current major and minor version of the TCAM API. The policy type determines the classification and action types that can be used with that policy. The types of policy supported in TCAM API version 1.0 are

The OpenFlow policy type is for general Layer2/Layer3 selection action criterion. If the policy has any IPv6 classification, the user should use IPv6 policy type. The Egress policy type is for policy that has any Egress action. The only Egress action supported in this release is to set new ether type for the packet.

Policy Header Version 2.0

The header should be populated with the current major and minor version of the TCAM API. The policy type determines the classification and action types that can be used with that policy. The types of policy supported in TCAM API version 2.0 are

The OpenFlow policy type is for general Layer2/Layer3 selection action criterion. If the policy has any IPv6 classification, the user should use IPv6 policy type. The Egress policy type is for policy that has any Egress action. The only Egress action supported in this release is to set new ether type for the packet.

Classification

Classification criterion supported for version 1.0 are

Classification Version 2.0

Classification criterion supported for version 2.0 are

Actions supported

Actions supported in version 1.0 are

Usage

A typical usage is to

Initialize TCAM Service using openapiTcamApiInit()
Create Policies by calling openapiTcamPolicyCreate()
Create version 2 based policies by calling openapiTcamPolicyCreateV2()
Apply the created policy to interfaces. openapiTcamPolicyIntfAdd()
Remove it from interfaces if needed. openapiTcamPolicyIntfRem()
Destroy the policy openapiTcamPolicyDestroy()
Un-initialize the resources. openapiTcamApiFini()
View hardware utilization by TCAM stage. openapiTcamHardwareGroupUsageGetNext()
View hardware utilization by policy. openapiTcamHardwarePolicyUsageGetNext()

Example C Application tcam_example

tcam_example.c is a sample application that demonstrates the use of the TCAM OpEN API's. tcam_example is started from the command line.

It exercises all the TCAM OpEN APIs with appropriate arguments to create/manipulate policies in the ICOS main process (switchdrvr). In its main function, tcam_example initializes the OpEN API RPC service by calling openapiClientRegister() and waits for the RPC service in switchdrvr to start. A Client Handle is returned by openapiClientRegister() which is used while invoking all the TCAM OpEN APIs.

The tcam_example application builds the open_tcamApiPolicy_t structure or open_tcamApiPolicy_v2_t structure based on the user input and calls the TCAM OpEN API to create/manipulate the policies. Functions openBuildHeader()/openBuildHeaderV2(), openAddClassifiers()/openAddClassifiersV2() and openAddPolicyAction()/openAddPolicyActionV2() provide examples of the same.

tcam_usage.c is an example application that shows the content of the TCAM hardware for the three stages. The "Lookup" stage corresponds to the hardware VCAP table, the "Ingress" stage corresponds to the ICAP, and the "Egress" stage corresponds to the ECAP.

The TCAM usage and the number of available rules are reported for each hardware group. The hardware group may span multiple slices within the TCAM stage.

The number of free entries in the group is reported assuming that entries are added only to this group. In other words adding entries to one hardware group may reduce the number of free entries entries in another hardware group when the expanded group crosses the slice boundary.

The example program works on single-chip, multi-chip, and stackable platforms.

tcam_policy.c is an example application that shows the TCAM resources consumed by the ACLs.

The example application also reports the number of available rules in the hardware to hold additional ACLs of each type. Keep in mind that adding ACLs of one type may reduce the resources available for other ACLs. Also other applications which consume the TCAM resources may reduce the number of available hardware rules for the ACLs.