hardware_table

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)

namespace eos

class hardware_table_handler

#include <hardware_table.h>

This class provides handler APIs to receive changes of hardware table.

Public Functions

hardware_table_handler(hardware_table_mgr * mgr)

hardware_table_mgr * get_hardware_table_mgr() const

void watch_all_hardware_tables(bool enable)

Register this handler to receive usage updates for all features across all tables. To unsubscribe to events, pass ‘false’.

void watch_hardware_table(hardware_table_key_t const & key, bool enable)

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.

virtual void on_hardware_table_entry_set(hardware_table_key_t const & key, hardware_table_entry_t const & entry)

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.

virtual void on_hardware_table_entry_del(hardware_table_key_t const & key)

Handler called when a table key is deleted.

class hardware_table_iter_t

Private Functions

hardware_table_iter_t(hardware_table_iter_impl * const)

Friends

friend class hardware_table_iter_impl

class hardware_table_mgr

#include <hardware_table.h>

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

virtual ~hardware_table_mgr()

virtual bool exists(hardware_table_key_t const & key) const = 0

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().

virtual hardware_table_iter_t hardware_table_iter() const = 0

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.

virtual hardware_table_usage_t usage(hardware_table_key_t const & key) const = 0

Get the usage statistics for a given hardware_table_key. If the key does not exist, an empty hardware_table_usage_t is returned.

virtual uint32_t max_entries(hardware_table_key_t const & key) const = 0

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.

virtual hardware_table_high_watermark_t high_watermark(hardware_table_key_t const & key) const = 0

Protected Functions

hardware_table_mgr()

Private Members

hardware_table_mgr

Friends

friend class hardware_table_handler

Type definitions in hardware_table

namespace eos

class hardware_table_key_t

#include <hardware_table.h>

The unique identifier for a hardware table.

Public Functions

hardware_table_key_t()

hardware_table_key_t(std::string const & table_name, std::string const & feature, std::string const & chip)

hardware_table_key_t(std::string const & table_name, std::string const & feature)

hardware_table_key_t(std::string const & table_name)

hardware_table_key_t(const hardware_table_key_t & other)

hardware_table_key_t & operator=(hardware_table_key_t const & other)

std::string table_name() const

Getter for ‘table_name’: the name of the hardware resource. For example, this value could be ‘TCAM’, ‘LEM’, ‘ECMP’, ‘LPM’ etc.

std::string feature() const

Getter for ‘feature’: the name of the feature using the table, such as ‘Multicast’, ‘IPv6’ or ‘MPLS’.

std::string chip() const

Getter for ‘chip’: which chip this table is located on. If empty, then this feature’s usage is identical across chips.

bool operator==(hardware_table_key_t const & other) const

bool operator!=(hardware_table_key_t const & other) const

bool operator<(hardware_table_key_t const & other) const

uint32_t hash() const

The hash function for type hardware_table_key_t.

void mix_me(hash_mix & h) const

The hash mix function for type hardware_table_key_t.

std::string to_string() const

Returns a string representation of the current object’s values.

Private Members

std::shared_ptr< hardware_table_key_impl_t > pimpl

Friends

friend std::ostream & operator<<

A utility stream operator that adds a string representation of hardware_table_key_t to the ostream.

class hardware_table_high_watermark_t

#include <hardware_table.h>

The compound high watermark statistics.

Public Functions

hardware_table_high_watermark_t()

hardware_table_high_watermark_t(uint32_t max_entries, time_t timestamp)

hardware_table_high_watermark_t(const hardware_table_high_watermark_t & other)

hardware_table_high_watermark_t & operator=(hardware_table_high_watermark_t const & other)

uint32_t max_entries() const

Getter for ‘max_entries’: the maximum number of entries used so far.

time_t timestamp() const

Getter for ‘timestamp’: the last time when high watermark reached.

bool operator==(hardware_table_high_watermark_t const & other) const

bool operator!=(hardware_table_high_watermark_t const & other) const

bool operator<(hardware_table_high_watermark_t const & other) const

uint32_t hash() const

The hash function for type hardware_table_high_watermark_t.

void mix_me(hash_mix & h) const

The hash mix function for type hardware_table_high_watermark_t.

std::string to_string() const

Returns a string representation of the current object’s values.

Private Members

std::shared_ptr< hardware_table_high_watermark_impl_t > pimpl

Friends

friend std::ostream & operator<<

A utility stream operator that adds a string representation of hardware_table_high_watermark_t to the ostream.

class hardware_table_usage_t

#include <hardware_table.h>

The usage statistics for a given table (or partition of a table).

Public Functions

hardware_table_usage_t()

hardware_table_usage_t(uint32_t used_entries, uint32_t free_entries, uint32_t committed_entries)

hardware_table_usage_t(const hardware_table_usage_t & other)

hardware_table_usage_t & operator=(hardware_table_usage_t const & other)

uint32_t used_entries() const

Getter for ‘used_entries’: number of entries used by this feature on this table.

uint32_t free_entries() const

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.

uint32_t committed_entries() const

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.

bool operator==(hardware_table_usage_t const & other) const

bool operator!=(hardware_table_usage_t const & other) const

bool operator<(hardware_table_usage_t const & other) const

uint32_t hash() const

The hash function for type hardware_table_usage_t.

void mix_me(hash_mix & h) const

The hash mix function for type hardware_table_usage_t.

std::string to_string() const

Returns a string representation of the current object’s values.

Private Members

std::shared_ptr< hardware_table_usage_impl_t > pimpl

Friends

friend std::ostream & operator<<

A utility stream operator that adds a string representation of hardware_table_usage_t to the ostream.

class hardware_table_entry_t

#include <hardware_table.h>

The hardware table entry for a given table key.

Public Functions

hardware_table_entry_t()

hardware_table_entry_t(hardware_table_usage_t const & usage, uint32_t max_entries, hardware_table_high_watermark_t const & high_watermark)

hardware_table_entry_t(const hardware_table_entry_t & other)

hardware_table_entry_t & operator=(hardware_table_entry_t const & other)

hardware_table_usage_t usage() const

Getter for ‘usage’: the compound usage statistics.

uint32_t max_entries() const

Getter for ‘max_entries’: the theoretical maximum number of entries available.

hardware_table_high_watermark_t high_watermark() const

Getter for ‘high_watermark’: the compound high watermark statistics.

bool operator==(hardware_table_entry_t const & other) const

bool operator!=(hardware_table_entry_t const & other) const

bool operator<(hardware_table_entry_t const & other) const

uint32_t hash() const

The hash function for type hardware_table_entry_t.

void mix_me(hash_mix & h) const

The hash mix function for type hardware_table_entry_t.

std::string to_string() const

Returns a string representation of the current object’s values.

Private Members

std::shared_ptr< hardware_table_entry_impl_t > pimpl

Friends

friend std::ostream & operator<<

A utility stream operator that adds a string representation of hardware_table_entry_t to the ostream.