Hardware table usage and capacity statistics
This module exposes the usage statistics for the various hardware tables used by the system. This is useful for agents that want to track how many entries are used or available across the various tables, either for monitoring purposes or so they can take specific actions when a table is close to becoming full. Usage is exposed per unique table, feature, and chip combination. Example tables include ‘TCAM’, ‘LEM’, ‘ECMP’, and ‘LPM’ tables, while the features look like “IPV4”, “ACL”, “MPLS”, or even platform-specific features like “V6Hosts”.
The usage statistics include the number of used, free, committed, maximum available entries, and the high watermark which records the maximum number of entries used by this feature so far and the time-stamp when the last high watermark value was hit. The capacity calculation is triggered every 10 seconds.
For example, hardware table T has 1000 entries, and the allocation block size is 100. Table T is used by feature F1 and F2. 200 entries have been allocated to Feature F1, 101 are in use. 300 entries have been allocated to Feature F2, 299 are in use. 500 entries are still in the shared pool of available entries. Free entries are those that are committed but not used (200-101 for feature F1) and the available entries in the shared pool (500).
table_key used free committed max high_watermark
(T, F1, ) 101 99+500 200 1000 (150, 10) (T, F2, ) 299 1+500 300 1000 (299, 20)
This class provides handler APIs to receive changes of hardware table.
Public Functions
Register this handler to receive usage updates for all features across all tables. To unsubscribe to events, pass ‘false’.
Register this handler to receive usage updates for a single table/feature/chip combination.
If ‘chip’ is specified as “*” in the key, register this handler to receive all updates for the named feature/table combination. If this feature uses different numbers of entries per-chip, the handler will fire for updates on each chip. Otherwise this is equivalent to watching a unique hardware_table_key.
If ‘feature’ is “*” in the key, register this handler to receive all updates for the named chip/table combination.
If ‘chip’ and ‘feature’ are both “*” in the key, register this handler to receive all updates for the specified table.
Handler called when a new table key is created or any of the fields in an existing usage entry changes. The capacity calculation is triggered every 10 seconds.
For example, enabling multicast will allocate space in the TCAM, triggering this callback with the new [‘TCAM’, ‘Multicast’] table key.
The handler can also be triggered because the feature is now using more entries (e.g. the ‘IPv4’ feature learned and added more routes to hardware), because the feature has been allocated more committed entries (e.g. the ‘ACL’ feature now requires a second bank of the TCAM), or because another feature that shares this table has increased it’s used or committed entries, causing this feature’s free entries to decrease.
Handler called when a table key is deleted.
Private Functions
Friends
A manager that exposes information about the hardware table’s capacity and usage.
Create one mgr by calling sdk.get_hardware_mgr() prior to starting the agent main loop. The manager can be used once the agent_handler::on_initialized function is called.
Public Functions
Check whether the hardware table key exists. That is, check whether the specified table key exposes usage data.
If exists returns true, this hardware_table_key_t can be successfully passed into every method of this hardware_table_mgr. If not, these methods will return default data such as 0 or hardware_table_usage_t().
Get an iterator over the existing tables. Yields a hardware_table_key_t for each table, feature, and chip combination that is being tracked by software.
Get the usage statistics for a given hardware_table_key. If the key does not exist, an empty hardware_table_usage_t is returned.
Get the theoretical maximum number of entries available, assuming no other features are using this table. If the key does not exist, 0 is returned.
Protected Functions
Private Members
Friends
The unique identifier for a hardware table.
Public Functions
Getter for ‘table_name’: the name of the hardware resource. For example, this value could be ‘TCAM’, ‘LEM’, ‘ECMP’, ‘LPM’ etc.
Getter for ‘feature’: the name of the feature using the table, such as ‘Multicast’, ‘IPv6’ or ‘MPLS’.
Getter for ‘chip’: which chip this table is located on. If empty, then this feature’s usage is identical across chips.
The hash function for type hardware_table_key_t.
Returns a string representation of the current object’s values.
Private Members
Friends
A utility stream operator that adds a string representation of hardware_table_key_t to the ostream.
The compound high watermark statistics.
Public Functions
Getter for ‘max_entries’: the maximum number of entries used so far.
Getter for ‘timestamp’: the last time when high watermark reached.
The hash function for type hardware_table_high_watermark_t.
Returns a string representation of the current object’s values.
Private Members
Friends
A utility stream operator that adds a string representation of hardware_table_high_watermark_t to the ostream.
The usage statistics for a given table (or partition of a table).
Public Functions
Getter for ‘used_entries’: number of entries used by this feature on this table.
Getter for ‘free_entries’: the number of free entries available for this feature to use. For features that share a table, if a feature increases its used or committed entries, all other features’ free entries will decrease.
Getter for ‘committed_entries’: the number of entries currently allocated for this feature. For tables that have no explicit partitions, this value will be 0.
The hash function for type hardware_table_usage_t.
Returns a string representation of the current object’s values.
Private Members
Friends
A utility stream operator that adds a string representation of hardware_table_usage_t to the ostream.
The hardware table entry for a given table key.
Public Functions
Getter for ‘usage’: the compound usage statistics.
Getter for ‘max_entries’: the theoretical maximum number of entries available.
Getter for ‘high_watermark’: the compound high watermark statistics.
The hash function for type hardware_table_entry_t.
Returns a string representation of the current object’s values.
Private Members
Friends
A utility stream operator that adds a string representation of hardware_table_entry_t to the ostream.