bmv2
Designing your own switch target with bmv2
Public Member Functions | Static Public Attributes | List of all members
bm::Packet Class Referencefinal

Public Member Functions

packet_id_t get_packet_id () const
 
int get_egress_port () const
 
int get_ingress_port () const
 Get the ingress_port of the packet. More...
 
void set_egress_port (int port)
 Set the egress_port of the packet, which is the target responsibility. More...
 
copy_id_t get_copy_id () const
 
const std::string get_unique_id () const
 
int get_ingress_length () const
 
void set_ingress_length (int length)
 
size_t get_data_size () const
 
char * data ()
 
const char * data () const
 
const buffer_state_t save_buffer_state () const
 
void restore_buffer_state (const buffer_state_t &state)
 See save_buffer_state() More...
 
void truncate (size_t length)
 
uint64_t get_signature () const
 Get a 64-bit hash of the incoming packet data. More...
 
PHVget_phv ()
 Get a pointer to the packet's phv. More...
 
const PHVget_phv () const
 Get a pointer to the packet's phv. More...
 
void set_register (size_t idx, uint64_t v)
 Write to general purpose register at index idx. More...
 
uint64_t get_register (size_t idx)
 Read general purpose register at index idx. More...
 
size_t get_entry_index () const
 
ErrorCode get_error_code () const
 
bool get_checksum_error () const
 
void mark_for_exit ()
 
void reset_exit ()
 
bool is_marked_for_exit () const
 
void change_context (cxt_id_t new_cxt)
 
cxt_id_t get_context () const
 Returns the id of the Context this packet currently belongs to. More...
 
Packet clone_with_phv () const
 
std::unique_ptr< Packetclone_with_phv_ptr () const
 
Packet clone_with_phv_reset_metadata () const
 
std::unique_ptr< Packetclone_with_phv_reset_metadata_ptr () const
 
Packet clone_no_phv () const
 
std::unique_ptr< Packetclone_no_phv_ptr () const
 
Packet clone_choose_context (cxt_id_t new_cxt) const
 
std::unique_ptr< Packetclone_choose_context_ptr (cxt_id_t new_cxt) const
 
 Packet (const Packet &other)=delete
 Deleted copy constructor. More...
 
Packetoperator= (const Packet &other)=delete
 Deleted copy assignment operator. More...
 
 Packet (Packet &&other) noexcept
 Move constructor. More...
 
Packetoperator= (Packet &&other) noexcept
 Move assignment operator. More...
 

Static Public Attributes

static constexpr size_t nb_registers = 4u
 Number of general purpose registers per packet. More...
 

Detailed Description

One of the most fundamental classes of bmv2. Used to represent a data packet while it traverses the switch. Even when a packet is parsed / deparsed mutliple times, the same Packet instance is used to represent it. If a Packet needs to be duplicated (for cloning, multicast, ...), a new Packet instance is created, using one of the available clone functions.

This class is final, so if the Packet class needs to be extended in your target, you will need to use composition, not inheritance. We weigh the pros and cons, and in the end we decided that preventing the Packet class from being subclassed was safer. It does come at a cost though (in action primitives, you can access the Packet instance, but not your target-specific packet class).

Note that in your target implementation, Packet instances should be created using SwitchWContexts::new_packet() / SwitchWContexts::new_packet_ptr() or Switch::new_packet() / Switch::new_packet_ptr() depending on your target design.

Constructor & Destructor Documentation

◆ Packet() [1/2]

bm::Packet::Packet ( const Packet other)
delete

Deleted copy constructor.

◆ Packet() [2/2]

bm::Packet::Packet ( Packet &&  other)
noexcept

Move constructor.

Member Function Documentation

◆ change_context()

void bm::Packet::change_context ( cxt_id_t  new_cxt)

Changes the context of the packet. You will only need to call this function if you target switch leverages the Context class and if your Packet instance changes contexts during its lifetime. This is needed because one can configure different contexts to support different header types, and the PHV templates for different contexts will therefore be different. When changing contexts, it is up to the user to 1) deparse the Packet in the old Context 2) call change_context 3) re-parse the Packet in the new Context. For example:

context1->get_deparser("deparser1")->deparse(pkt);
pkt->change_context(2);
context2->get_parser("parser1")->parse(pkt);

if new_cxt == cxt_id, then this is a no-op, otherwise, release the old PHV and replace it with a new one, compatible with the new context

◆ clone_choose_context()

Packet bm::Packet::clone_choose_context ( cxt_id_t  new_cxt) const

Same as clone_no_phv(), but also changes the context id for the clone. See change_context() for more information on how a Packet instance belongs to a specific Context

◆ clone_choose_context_ptr()

std::unique_ptr<Packet> bm::Packet::clone_choose_context_ptr ( cxt_id_t  new_cxt) const

Same as clone_no_phv(), but also changes the context id for the clone. See change_context() for more information on how a Packet instance belongs to a specific Context

◆ clone_no_phv()

Packet bm::Packet::clone_no_phv ( ) const

Clone the current packet, without the PHV. The value of the fields in the clone will be undefined and should not be accessed before setting it first.

◆ clone_no_phv_ptr()

std::unique_ptr<Packet> bm::Packet::clone_no_phv_ptr ( ) const

Clone the current packet, without the PHV. The value of the fields in the clone will be undefined and should not be accessed before setting it first.

◆ clone_with_phv()

Packet bm::Packet::clone_with_phv ( ) const

Clone the current packet, along with its PHV. The value of all the fields (metadata and regular) will remain the same int the clone.

◆ clone_with_phv_ptr()

std::unique_ptr<Packet> bm::Packet::clone_with_phv_ptr ( ) const

Clone the current packet, along with its PHV. The value of all the fields (metadata and regular) will remain the same int the clone.

◆ clone_with_phv_reset_metadata()

Packet bm::Packet::clone_with_phv_reset_metadata ( ) const

Clone the current packet, along with regular headers, but resets all the metadata fields (i.e. sets them to 0) in the clone.

◆ clone_with_phv_reset_metadata_ptr()

std::unique_ptr<Packet> bm::Packet::clone_with_phv_reset_metadata_ptr ( ) const

Clone the current packet, along with regular headers, but resets all the metadata fields (i.e. sets them to 0) in the clone.

◆ data() [1/2]

char* bm::Packet::data ( )
inline

Returns a pointer to the packet data. Just after instantiating the packet, this will point to all the received packet data. After parsing, this will just be the packet payload. After deparsing, this will be data which needs to be sent out.

◆ data() [2/2]

const char* bm::Packet::data ( ) const
inline

Returns a pointer to the packet data. Just after instantiating the packet, this will point to all the received packet data. After parsing, this will just be the packet payload. After deparsing, this will be data which needs to be sent out.

◆ get_checksum_error()

bool bm::Packet::get_checksum_error ( ) const
inline

Get the checksum error flag for this Packet, as set by the most recent Parser object the packet went through. For most packets, this error flag should be set to "false".

◆ get_context()

cxt_id_t bm::Packet::get_context ( ) const
inline

Returns the id of the Context this packet currently belongs to.

◆ get_copy_id()

copy_id_t bm::Packet::get_copy_id ( ) const
inline

Obtains the copy_id of a packet, used to differentiate all the clones generated from the same incoming data packet. See get_packet_id() for more information.

◆ get_data_size()

size_t bm::Packet::get_data_size ( ) const
inline

Returns the amount of packet data in the buffer (in bytes). This function will notably be called after deparsing, when the target is ready to transmit the packet.

◆ get_egress_port()

int bm::Packet::get_egress_port ( ) const
inline

Get the egress_port of this Packet. The egress_port needs to be set by the target using set_egress_port().

◆ get_entry_index()

size_t bm::Packet::get_entry_index ( ) const
inline

Get the index of the entry returned by the last match table lookup, or Packet::INVALID_ENTRY_INDEX if lookup was a miss.

◆ get_error_code()

ErrorCode bm::Packet::get_error_code ( ) const
inline

Get the error code for this Packet, as set by the most recent Parser object the packet went through. For most packets, this error code should be set to "NoError".

◆ get_ingress_length()

int bm::Packet::get_ingress_length ( ) const
inline

Get the ingress_length for the packet, which is set when instantiating the packet. As the name indicates, this is the original length of the packet. This is not updated as headers are marked valid / invalid and the length of the outgoing packet may be different.

◆ get_ingress_port()

int bm::Packet::get_ingress_port ( ) const
inline

Get the ingress_port of the packet.

◆ get_packet_id()

packet_id_t bm::Packet::get_packet_id ( ) const
inline

Obtain the packet_id. The packet_id is the one assigned by the target when the packet was instantiated. We recommend using a counter initialized to 0 and incremented every time a new packet is received "on the wire". Packet instances obtained by cloning a given packet receives the same packet_id as that packet. In other words, this packet_id identifies all Packet instances produced by the switch in response to the same incoming data packet. The clones can be differentiated using the copy_id.

◆ get_phv() [1/2]

PHV* bm::Packet::get_phv ( )
inline

Get a pointer to the packet's phv.

◆ get_phv() [2/2]

const PHV* bm::Packet::get_phv ( ) const
inline

Get a pointer to the packet's phv.

◆ get_register()

uint64_t bm::Packet::get_register ( size_t  idx)
inline

Read general purpose register at index idx.

◆ get_signature()

uint64_t bm::Packet::get_signature ( ) const
inline

Get a 64-bit hash of the incoming packet data.

◆ get_unique_id()

const std::string bm::Packet::get_unique_id ( ) const
inline

Get a unique string id for this packet. It is simply packet_id + "." + copy_id.

◆ is_marked_for_exit()

bool bm::Packet::is_marked_for_exit ( ) const
inline

Returns true iff the packet is marked for exit (i.e. mark_for_exit() was called on the packet).

◆ mark_for_exit()

void bm::Packet::mark_for_exit ( )
inline

Mark the packet for exit by setting an exit flag. If this is called from an action, the current pipeline will be interrupted as soon as the current table is done processing the packet. This effectively skips the rest of the pipeline. Do not forget to call reset_exit() at the end of the pipeline, if you intend the packet to go through another pipeline afterwards; otherwise this other pipeline will just be skipped as well. If this method is called from outside of an action, the flag will take effect at the next pipeline, which will be skipped entirely (not a single table will be applied).

◆ operator=() [1/2]

Packet& bm::Packet::operator= ( const Packet other)
delete

Deleted copy assignment operator.

◆ operator=() [2/2]

Packet& bm::Packet::operator= ( Packet &&  other)
noexcept

Move assignment operator.

◆ reset_exit()

void bm::Packet::reset_exit ( )
inline

Clear the exit flag, which may have been set by an earlier call to mark_for_exit().

◆ restore_buffer_state()

void bm::Packet::restore_buffer_state ( const buffer_state_t &  state)
inline

◆ save_buffer_state()

const buffer_state_t bm::Packet::save_buffer_state ( ) const
inline

Saves the current state of the packet data buffer. Even if the buffer state is then modified, the state can be restored by providing the return value of this function to restore_buffer_state().

◆ set_egress_port()

void bm::Packet::set_egress_port ( int  port)
inline

Set the egress_port of the packet, which is the target responsibility.

◆ set_ingress_length()

void bm::Packet::set_ingress_length ( int  length)
inline

Sets the ingress_length. This may be needed for some architectures, although usually it is better to create a new Packet object. See get_ingress_length() for more information about ingress_length.

◆ set_register()

void bm::Packet::set_register ( size_t  idx,
uint64_t  v 
)
inline

Write to general purpose register at index idx.

◆ truncate()

void bm::Packet::truncate ( size_t  length)
inline

Truncate the packet to the given length. The truncation will only be enforced when calling get_data_size(). When calling truncate multiple times, the smallest provided length value will be used.

Member Data Documentation

◆ nb_registers

constexpr size_t bm::Packet::nb_registers = 4u
staticconstexpr

Number of general purpose registers per packet.


The documentation for this class was generated from the following file: