The TCAM API allows the user to create policies directly in the TCAM. These policies co-exist with those created by the EFOS 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 EFOS main process (switchdrvr) to create policies directly to TCAM. It provides the following services:
- Iterate through all the policies in the switch.
- Initialize/Un-initialize the TCAM API services.
- Get the current version of the TCAM API.
- Create a new policy.
- Apply policy to an interface.
- Remove policy from an interface.
- Destroy a policy.
- Destroy all policies created by TCAM API.
- Get the first policy created by TCAM API.
- Get the next policy created by TCAM API.
- Get the TCAM usage for the next policy in the system.
- Get the TCAM usage for the next Unit/ASIC/Stage/Group.
All operations affect the Switch behavior but not the configuration. This implies that the policies created by the TCAM API are ephemeral and would be lost upon switch reboot.
Policy
The openapiTcamPolicyCreate() API takes as parameter the open_tcamApiPolicy_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.
Classification
Classification criterion supported for version 1.0 are
- VLAN ID.
- VLAN priority.
- Destination MAC.
- Source MAC.
- Protocol.
- Destination IP address.
- Source IP address.
- Ether type.
- DSCP.
- IPv6 source address.
- IPv6 destination address.
Based on the policy type the user can set multiple match criterion. A field with a non zero value is assumed to have been set for classification. The user can select multiple classification criterion. Any value that is not selected is considered as a don't care.
Actions supported
Actions supported in version 1.0 are
- Drop the packet.
- Set new destination MAC address.
- Set new source MAC address.
- Add new VLAN tag.
- Set new VLAN priority.
- Redirect packet to an interface
- Add new ether type/TPID to the packet.
Based on the policy type a user can specify multiple actions for a given policy. The actionType field in the open_tcamApiPolicy_t should be set and the corresponding value in the structure OPEN_TCAM_ACTION_t should be updated. The user can set multiple actions at once. The actions, however, have to be consistent e.g. one cannot have an action to drop as well as to redirect the packets to a port.
Usage
A typical usage is to
Initialize TCAM Service using openapiTcamApiInit()
Create Policies by calling openapiTcamPolicyCreate()
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 EFOS 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 based on the user input and calls the TCAM OpEN API to create/manipulate the policies. Functions openBuildHeader() , openAddClassifiers() and openAddPolicyAction() 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.
