path: root/src/vnet/l2/l2.api

/* Hey Emacs use -*- mode: C -*- */
/*
 * Copyright (c) 2016 Cisco and/or its affiliates.
 * Copyright (c) 2022 Nordix Foundation.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at:
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

option version = "3.2.0";

import "vnet/ip/ip_types.api";
import "vnet/ethernet/ethernet_types.api";
import "vnet/interface_types.api";

/** \brief Reply to l2_xconnect_dump
    @param context - sender context which was passed in the request
    @param rx_sw_if_index - Receive interface index
    @param tx_sw_if_index - Transmit interface index
 */
define l2_xconnect_details
{
  u32 context;
  vl_api_interface_index_t rx_sw_if_index;
  vl_api_interface_index_t tx_sw_if_index;
};

/** \brief Dump L2 XConnects
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
*/
define l2_xconnect_dump
{
  u32 client_index;
  u32 context;
};

/** \brief l2 fib table details structure
    @param bd_id - the l2 fib / bridge domain table id
    @param mac - the entry's mac address
    @param sw_if_index - index of the interface
    @param static_mac - the entry is statically configured.
    @param filter_mac - the entry is a mac filter entry.
    @param bvi_mac - the mac address is a bridge virtual interface
*/
define l2_fib_table_details
{
  u32 context;
  u32 bd_id;
  vl_api_mac_address_t mac;
  vl_api_interface_index_t sw_if_index;
  bool static_mac;
  bool filter_mac;
  bool bvi_mac;
};

/** \brief Dump l2 fib (aka bridge domain) table
    @param client_index - opaque cookie to identify the sender
    @param bd_id - the l2 fib / bridge domain table identifier
*/
define l2_fib_table_dump
{
  u32 client_index;
  u32 context;
  u32 bd_id;
};

/** \brief L2 fib clear table request, clear all mac entries in the l2 fib
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
*/
autoreply define l2_fib_clear_table
{
  u32 client_index;
  u32 context;
};

/** \brief L2 FIB flush all  entries
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
*/
autoreply define l2fib_flush_all
{
  u32 client_index;
  u32 context;
};

/** \brief L2 FIB flush bridge domain entries
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param bd_id - the entry's bridge domain id
*/
autoreply define l2fib_flush_bd
{
  u32 client_index;
  u32 context;
  u32 bd_id;
};

/** \brief L2 FIB flush interface entries
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param bd_id - the entry's bridge domain id
*/
autoreply define l2fib_flush_int
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
};

/** \brief L2 FIB add entry request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param mac - the entry's mac address
    @param bd_id - the entry's bridge domain id
    @param sw_if_index - the interface
    @param is_add - If non zero add the entry, else delete it
    @param static_mac -
    @param filter_mac -
    @param bvi_mac -
*/
autoreply define l2fib_add_del
{
  u32 client_index;
  u32 context;
  vl_api_mac_address_t mac;
  u32 bd_id;
  vl_api_interface_index_t sw_if_index;
  bool is_add [default=true];
  bool static_mac;
  bool filter_mac;
  bool bvi_mac;
};

/** \brief Register to receive L2 MAC events for learned and aged MAC
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param learn_limit - MAC learn limit
    @param scan_delay - event scan delay in 10 msec unit
    @param max_macs_in_event - in units of 10 mac entries
    @param enable_disable - 1 => register for MAC events, 0 => cancel registration
    @param pid - sender's pid
*/
autoreply define want_l2_macs_events
{
  option deprecated;
  u32 client_index;
  u32 context;
  u32 learn_limit [default=1000];
  u8  scan_delay [default=10];
  u8  max_macs_in_event [default=10];
  bool enable_disable [default=true];
  u32 pid;
};

/** \brief Register to receive L2 MAC events for learned and aged MAC
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param max_macs_in_event - in units of 10 mac entries
    @param enable_disable - 1 => register for MAC events, 0 => cancel registration
    @param pid - sender's pid
*/
autoreply define want_l2_macs_events2
{
  u32 client_index;
  u32 context;
  u8  max_macs_in_event [default=10];
  bool enable_disable [default=true];
  u32 pid;
};

/** \brief set l2 table scan delay
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param scan_delay - event scan delay in 10 msec unit
*/
autoreply define l2fib_set_scan_delay
{
  u32 client_index;
  u32 context;
  u16 scan_delay [default=10];
};


enum mac_event_action
{
	MAC_EVENT_ACTION_API_ADD = 0,
	MAC_EVENT_ACTION_API_DELETE = 1,
	MAC_EVENT_ACTION_API_MOVE = 2,
};

/** \brief Entry for learned or aged MAC in L2 MAC Events
    @param sw_if_index - sw_if_index in the domain
    @param mac_addr - mac_address
    @param action - 0 => newly learned MAC, 1 => MAC deleted by ager
                    2 => MAC move (sw_if_index changed)
    @param flags - flag bits to provide other info, not yet used
*/
typedef mac_entry
{
  vl_api_interface_index_t sw_if_index;
  vl_api_mac_address_t mac_addr;
  vl_api_mac_event_action_t action;
  u8 flags;
};

/** \brief L2 MAC event for a list of learned or aged MACs
    @param client_index - opaque cookie to identify the sender
    @param pid - client pid registered to receive notification
    @param n_macs - number of learned/aged MAC entries
    @param mac - array of learned/aged MAC entries
*/
define l2_macs_event
{
  u32 client_index;
  u32 pid;
  u32 n_macs;
  vl_api_mac_entry_t mac[n_macs];
};

service {
  rpc want_l2_macs_events returns want_l2_macs_events_reply
    events l2_macs_event;
};

/** \brief Set interface L2 flags (such as L2_LEARN, L2_FWD,
    L2_FLOOD, L2_UU_FLOOD, or L2_ARP_TERM bits). This can be used
    to disable one or more of the features represented by the
    flag bits on an interface to override what is set as default
    for all interfaces in the bridge domain
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - interface
    @param is_set - if non-zero, set the bits, else clear them
    @param feature_bitmap - non-zero bits (as above) to set or clear
*/
define l2_flags
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  bool is_set;
  u32 feature_bitmap;
};

/** \brief Set interface L2 flags response
    @param context - sender context, to match reply w/ request
    @param retval - return code for the set l2 bits request
    @param resulting_feature_bitmap - the internal l2 feature bitmap after the request is implemented
*/
define l2_flags_reply
{
  u32 context;
  i32 retval;
  u32 resulting_feature_bitmap;
};

/** \brief L2 bridge domain set mac age
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param bd_id - the bridge domain to create
    @param mac_age - mac aging time in min, 0 for disabled
*/
autoreply define bridge_domain_set_mac_age
{
  u32 client_index;
  u32 context;
  u32 bd_id;
  u8 mac_age;
};

/** \brief L2 bridge domain set default learn limit
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param learn limit - maximum number of entries by default for bridge domains
*/
autoreply define bridge_domain_set_default_learn_limit
{
  u32 client_index;
  u32 context;
  u32 learn_limit;
};


/** \brief L2 bridge domain set learn limit
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param bd_id - the bridge domain idenntifier
    @param learn limit - maximum number of entries for this bd
*/
autoreply define bridge_domain_set_learn_limit
{
  u32 client_index;
  u32 context;
  u32 bd_id;
  u32 learn_limit;
};

/** \brief L2 bridge domain add or delete request - will be deprecated
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param bd_id - the bridge domain to create
    @param flood - enable/disable bcast/mcast flooding in the bd
    @param uu_flood - enable/disable unknown unicast flood in the bd
    @param forward - enable/disable forwarding on all interfaces in the bd
    @param learn - enable/disable learning on all interfaces in the bd
    @param arp_term - enable/disable arp termination in the bd
    @param arp_ufwd - enable/disable arp unicast forwarding in the bd
    @param mac_age - mac aging time in min, 0 for disabled
    @param is_add - add or delete flag
*/
autoreply define bridge_domain_add_del
{
  option deprecated;
  u32 client_index;
  u32 context;
  u32 bd_id;
  bool flood;
  bool uu_flood;
  bool forward;
  bool learn;
  bool arp_term;
  bool arp_ufwd;
  u8 mac_age;
  string bd_tag[64];
  bool is_add [default=true];
};

/** \brief L2 bridge domain add delete request version 2
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param bd_id -  if the id == ~0 creates a bridge domain with an unused id
              if the id != ~0 the id of the bridge domain to create/delete
    @param flood - enable/disable bcast/mcast flooding in the bd
    @param uu_flood - enable/disable unknown unicast flood in the bd
    @param forward - enable/disable forwarding on all interfaces in the bd
    @param learn - enable/disable learning on all interfaces in the bd
    @param arp_term - enable/disable arp termination in the bd
    @param arp_ufwd - enable/disable arp unicast forwarding in the bd
    @param mac_age - mac aging time in min, 0 for disabled
    @param is_add - add or delete flag
*/
define bridge_domain_add_del_v2
{
  u32 client_index;
  u32 context;
  u32 bd_id;
  bool flood;
  bool uu_flood;
  bool forward;
  bool learn;
  bool arp_term;
  bool arp_ufwd;
  u8 mac_age;
  string bd_tag[64];
  bool is_add [default=true];
};

/** \brief L2 bridge domain add delete version 2 response
    @param context - sender context, to match reply w/ request
    @param retval - return code for the set bridge flags request
    @param resulting_id - the id for the new bridge domain
*/
define bridge_domain_add_del_v2_reply
{
  u32 context;
  i32 retval;
  u32 bd_id;
};


/** \brief L2 bridge domain request operational state details
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param bd_id - the bridge domain id desired or ~0 to request all bds
    @param sw_if_index - filter by sw_if_index UNIMPLEMENTED
*/
define bridge_domain_dump
{
  u32 client_index;
  u32 context;
  u32 bd_id [default=0xffffffff];
  vl_api_interface_index_t sw_if_index [default=0xffffffff];
};

/** \brief L2 bridge domain sw interface operational state response
    @param bd_id - the bridge domain id
    @param sw_if_index - sw_if_index in the domain
    @param shg - split horizon group for the interface
*/
typedef bridge_domain_sw_if
{
  u32 context;
  vl_api_interface_index_t sw_if_index;
  /* FIXME: set_int_l2_mode() u32/ api u8 */
  u8 shg;
};

/** \brief L2 bridge domain operational state response
    @param bd_id - the bridge domain id
    @param flood - bcast/mcast flooding state on all interfaces in the bd
    @param uu_flood - unknown unicast flooding state on all interfaces in the bd
    @param forward - forwarding state on all interfaces in the bd
    @param learn - learning state on all interfaces in the bd
    @param arp_term - arp termination state on all interfaces in the bd
    @param arp_ufwd - arp unicast forwarding state on all interfaces in the bd
    @param mac_age - mac aging time in min, 0 for disabled
    @param bd_tag - optional textual tag for the bridge domain
    @param n_sw_ifs - number of sw_if_index's in the domain
*/
define bridge_domain_details
{
  u32 context;
  u32 bd_id;
  bool flood;
  bool uu_flood;
  bool forward;
  bool learn;
  bool arp_term;
  bool arp_ufwd;
  u8 mac_age;
  string bd_tag[64];
  vl_api_interface_index_t bvi_sw_if_index;
  vl_api_interface_index_t uu_fwd_sw_if_index;
  u32 n_sw_ifs;
  vl_api_bridge_domain_sw_if_t sw_if_details[n_sw_ifs];
};

/** \brief Flags that can be changed on a bridge domain */
enum bd_flags
{
  BRIDGE_API_FLAG_NONE = 0x0,
  BRIDGE_API_FLAG_LEARN = 0x1,
  BRIDGE_API_FLAG_FWD = 0x2,
  BRIDGE_API_FLAG_FLOOD = 0x4,
  BRIDGE_API_FLAG_UU_FLOOD = 0x8,
  BRIDGE_API_FLAG_ARP_TERM = 0x10,
  BRIDGE_API_FLAG_ARP_UFWD = 0x20,
};

/** \brief Set bridge flags request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param bd_id - the bridge domain to set the flags for
    @param is_set - if non-zero, set the flags, else clear them
    @param flags - flags that are non-zero to set or clear
*/
define bridge_flags
{
  u32 client_index;
  u32 context;
  u32 bd_id;
  bool is_set;
  vl_api_bd_flags_t flags;
};

/** \brief Set bridge flags response
    @param context - sender context, to match reply w/ request
    @param retval - return code for the set bridge flags request
    @param resulting_feature_bitmap - the internal L2 feature bitmap after the request is implemented
*/
define bridge_flags_reply
{
  u32 context;
  i32 retval;
  u32 resulting_feature_bitmap;
};

/** \brief L2 interface vlan tag rewrite configure request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - interface the operation is applied to
    @param vtr_op - Choose from l2_vtr_op_t enum values
    @param push_dot1q - first pushed flag dot1q id set, else dot1ad
    @param tag1 - Needed for any push or translate vtr op
    @param tag2 - Needed for any push 2 or translate x-2 vtr ops
*/
autoreply define l2_interface_vlan_tag_rewrite
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  u32 vtr_op;
  u32 push_dot1q;		// ethertype of first pushed tag is dot1q/dot1ad
  u32 tag1;			// first pushed tag
  u32 tag2;			// second pushed tag
};

/** \brief L2 interface pbb tag rewrite configure request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - interface the operation is applied to
    @param vtr_op - Choose from l2_vtr_op_t enum values
    @param inner_tag - needed for translate_qinq vtr op only
    @param outer_tag - needed for translate_qinq vtr op only
    @param b_dmac - B-tag remote mac address, needed for any push or translate_qinq vtr op
    @param b_smac - B-tag local mac address, needed for any push or translate qinq vtr op
    @param b_vlanid - B-tag vlanid, needed for any push or translate qinq vtr op
    @param i_sid - I-tag service id, needed for any push or translate qinq vtr op
*/
autoreply define l2_interface_pbb_tag_rewrite
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  u32 vtr_op;
  u16 outer_tag;
  vl_api_mac_address_t b_dmac;
  vl_api_mac_address_t b_smac;
  u16 b_vlanid;
  u32 i_sid;
};

/** \brief L2 interface patch add / del request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param rx_sw_if_index - receive side interface
    @param tx_sw_if_index - transmit side interface
    @param is_add - if non-zero set up the interface patch, else remove it
*/
autoreply define l2_patch_add_del
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t rx_sw_if_index;
  vl_api_interface_index_t tx_sw_if_index;
  bool is_add [default=true];
};

/** \brief Set L2 XConnect between two interfaces request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param rx_sw_if_index - Receive interface index
    @param tx_sw_if_index - Transmit interface index
    @param enable - enable xconnect if not 0, else set to L3 mode
*/
autoreply define sw_interface_set_l2_xconnect
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t rx_sw_if_index;
  vl_api_interface_index_t tx_sw_if_index;
  bool enable [default=true];
};

/**
 * @brief An enumeration of the type of ports that can be added
 *        to a bridge domain
 */
enum l2_port_type
{
  /* a 'normal' interface, i.e. not BVI or UU-Flood */
  L2_API_PORT_TYPE_NORMAL = 0,
  /* a BVI interface in the BD */
  L2_API_PORT_TYPE_BVI = 1,
  /* The interface on which to forward unknown unicast packets
   * If this is not set for a BD then UU is flooded */
  L2_API_PORT_TYPE_UU_FWD = 2,
};

/** \brief Interface bridge mode request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param rx_sw_if_index - the interface
    @param bd_id - bridge domain id
    @param port_type - port_mode, see #l2_port_type
    @param shg - Split horizon group, for bridge mode only
    @param enable - Enable beige mode if not 0, else set to L3 mode
*/

autoreply define sw_interface_set_l2_bridge
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t rx_sw_if_index;
  u32 bd_id;
  vl_api_l2_port_type_t port_type;
  u8 shg;
  bool enable [default=true];
};

/** \brief Set bridge domain ip to mac entry request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param bd_id - the bridge domain to set the flags for
    @param is_add - if non-zero, add the entry, else clear it
    @param ip - ipv4 or ipv6 address
    @param mac - MAC address
*/

typedef bd_ip_mac
{
  u32 bd_id;
  vl_api_address_t ip;
  vl_api_mac_address_t mac;
};

autoreply define bd_ip_mac_add_del
{
  u32 client_index;
  u32 context;
  bool is_add [default=true];
  vl_api_bd_ip_mac_t entry;
};

/** \brief Flush bridge domain IP to MAC entries
    @param client_index - opaque cookie to identify the sender
    @param bd_id - bridge domain identifier
*/
autoreply define bd_ip_mac_flush
{
  u32 client_index;
  u32 context;
  u32 bd_id;
};

/** \brief bridge domain IP to MAC entry details structure
    @param bd_id - bridge domain table id
    @param is_ipv6 - if non-zero, ipv6 address, else ipv4 address
    @param ip_address - ipv4 or ipv6 address
    @param mac_address - MAC address
*/
define bd_ip_mac_details
{
  u32 context;
  vl_api_bd_ip_mac_t entry;
};

/** \brief Dump bridge domain IP to MAC entries
    @param client_index - opaque cookie to identify the sender
    @param bd_id - bridge domain identifier
*/
define bd_ip_mac_dump
{
  u32 client_index;
  u32 context;
  u32 bd_id;
};

/** \brief L2 interface ethernet flow point filtering enable/disable request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - interface to enable/disable filtering on
    @param enable_disable - if non-zero enable filtering, else disable
*/
autoreply define l2_interface_efp_filter
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  bool enable_disable [default=true];
};

/** \brief Interface set vpath request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - interface used to reach neighbor
    @param enable - if non-zero enable, else disable
*/
autoreply define sw_interface_set_vpath
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  bool enable [default=0xffffffff];
};

/** \brief Create BVI interface instance request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param mac_address - mac addr to assign to the interface if none-zero
    @param user_instance - requested instance, ~0 => dynamically allocate
*/
define bvi_create
{
  u32 client_index;
  u32 context;
  vl_api_mac_address_t mac;
  u32 user_instance [default=0xffffffff];
};

/** \brief Create BVI interface instance response
    @param context - sender context, to match reply w/ request
    @param sw_if_index - sw index of the interface that was created
    @param retval - return code for the request
*/
define bvi_create_reply
{
  u32 context;
  i32 retval;
  vl_api_interface_index_t sw_if_index;
};

/** \brief Delete BVI interface request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - sw index of the interface that was created
*/
autoreply define bvi_delete
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
};

/** \brief Register for IP4 ARP resolution event on receiving ARP reply or
           MAC/IP info from ARP requests in L2 BDs
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param enable - 1 => register for events, 0 => cancel registration
    @param pid - sender's pid
*/
autoreply define want_l2_arp_term_events
{
  u32 client_index;
  u32 context;
  bool enable;
  u32 pid;
};

/** \brief Tell client about an IP4 ARP resolution event or
           MAC/IP info from ARP requests in L2 BDs
    @param client_index - opaque cookie to identify the sender
    @param pid - client pid registered to receive notification
    @param ip - IP address of new ARP term entry
    @param sw_if_index - interface of new ARP term entry
    @param mac - MAC address of new ARP term entry
*/
define l2_arp_term_event
{
  u32 client_index;
  u32 pid;
  vl_api_address_t ip;
  vl_api_interface_index_t sw_if_index;
  vl_api_mac_address_t mac;
};

service {
  rpc want_l2_arp_term_events returns want_l2_arp_term_events_reply
    events l2_arp_term_event;
};

/*
 * Local Variables:
 * eval: (c-set-style "gnu")
 * End:
 */