path: root/src/vnet/interface.api

/* Hey Emacs use -*- mode: C -*- */
/*
 * Copyright (c) 2018 Cisco and/or its affiliates.
 * 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.3";

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

service {
  rpc want_interface_events returns want_interface_events_reply
    events sw_interface_event;
};

/** \brief Set flags on the interface
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - index of the interface to set flags on
    @param flags - interface_status flags
        (only IF_STATUS_API_FLAG_ADMIN_UP used in config)
*/
autoreply define sw_interface_set_flags
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  vl_api_if_status_flags_t flags;
};

/** \brief Set interface promiscuous mode
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - index of the interface to set flags on
    @param promisc_on - promiscuous mode is on ?
*/
autoreply define sw_interface_set_promisc
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  bool promisc_on;
};

/** \brief Set interface physical MTU
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - index of the interface to set MTU on
    @param mtu - MTU
*/
autoreply define hw_interface_set_mtu
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  u16 mtu;
};

/** \brief Set interface L3 MTU */
autoreply define sw_interface_set_mtu
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  u32 mtu[4]; /* vl_api_mtu_proto_t 0 - L3, 1 - IP4, 2 - IP6, 3 - MPLS */
};

/** \brief Set IP4 directed broadcast
    The directed broadcast enabled a packet sent to the interface's
    subnet address will be broadcast on the interface
    @param sw_if_index
    @param enable
*/
autoreply define sw_interface_set_ip_directed_broadcast
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  bool  enable;
};

/** \brief Interface Event generated by want_interface_events
    @param client_index - opaque cookie to identify the sender
    @param pid - client pid registered to receive notification
    @param sw_if_index - index of the interface of the event
    @param flags - interface_status flags
    @param deleted - interface was deleted
*/
define sw_interface_event
{
  u32 client_index;
  u32 pid;
  vl_api_interface_index_t sw_if_index;
  vl_api_if_status_flags_t flags;
  bool deleted;
};

/** \brief Register for interface events
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param enable_disable - 1 => register for events, 0 => cancel registration
    @param pid - sender's pid
*/
autoreply define want_interface_events
{
  u32 client_index;
  u32 context;
  u32 enable_disable;
  u32 pid;
};

/** \brief Interface details structure (fix this)
    @param sw_if_index - index of the interface
    @param sup_sw_if_index - index of parent interface if any, else same as sw_if_index
    @param l2_address - the interface's l2 address
    @param flags - interface_status flags
    @param type - interface type
    @param link_duplex - 1 if half duplex, 2 if full duplex
    @param link_speed - value in kbps
    @param link_MTU - max. transmission unit
    @param sub_id - A number 0-N to uniquely identify this subif on super if
    @param sub_number_of_tags - Number of tags (0 - 2)
    @param sub_outer_vlan_id
    @param sub_inner_vlan_id
    @param sub_if_flags - sub interface flags
    @param vtr_op - vlan tag rewrite operation
    @param vtr_push_dot1q
    @param vtr_tag1
    @param vtr_tag2
    @param pbb_outer_tag - translate pbb s-tag
    @param pbb_b_dmac[6] - B-tag remote mac address
    @param pbb_b_smac[6] - B-tag local mac address
    @param pbb_b_vlanid - B-tag vlanid
    @param pbb_i_sid - I-tag service id
    @param interface_name - name of the interface
    @param interface_dev_type - device type of the interface
    @param tag - an ascii tag
*/
define sw_interface_details
{
  u32 context;
  vl_api_interface_index_t sw_if_index;

  /* index of sup interface (e.g. hw interface).
     equal to sw_if_index for super hw interface. */
  u32 sup_sw_if_index;

  /* Layer 2 address, if applicable */
  vl_api_mac_address_t l2_address;

  vl_api_if_status_flags_t flags;

  vl_api_if_type_t type;

  /* 1 = half duplex, 2 = full duplex */
  vl_api_link_duplex_t link_duplex;

  /* link speed in kbps */
  u32 link_speed;

  /* MTU */
  u16 link_mtu;

  /* Per protocol MTUs */
  u32 mtu[4]; /* vl_api_mtu_proto_t 0 - L3, 1 - IP4, 2 - IP6, 3 - MPLS */

  /* Subinterface ID. A number 0-N to uniquely identify this subinterface under the super interface */
  u32 sub_id;

  /* Number of tags 0-2 */
  u8 sub_number_of_tags;
  u16 sub_outer_vlan_id;
  u16 sub_inner_vlan_id;

  vl_api_sub_if_flags_t sub_if_flags;

  /* vlan tag rewrite state */
  u32 vtr_op;
  u32 vtr_push_dot1q;		// ethertype of first pushed tag is dot1q/dot1ad
  u32 vtr_tag1;			// first pushed tag
  u32 vtr_tag2;			// second pushed tag

  /* pbb tag rewrite info */
  u16 outer_tag;
  vl_api_mac_address_t  b_dmac;
  vl_api_mac_address_t  b_smac;
  u16 b_vlanid;
  u32 i_sid;

  /* Interface name */
  string interface_name[64];
  string interface_dev_type[64];
  string tag[64];
};

/** \brief Request all or filtered subset of sw_interface_details
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - index of the interface to dump info on, 0 or ~0 if on all
      TODO: Support selecting only index==0 when CSIT is ready.
    @param name_filter_valid - 1 if requesting a filtered subset of records else 0
      if name filter is set as valid, sw_if_index value is ignored and all interfaces are examined
    @param name_filter - interface name substring filter. Eg. loop1 returns [loop1, loop10]
*/
define sw_interface_dump
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index [default=0xFFFFFFFF];
  bool name_filter_valid;
  string name_filter[];
};

/** \brief Set or delete one or all ip addresses on a specified interface
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - index of the interface to add/del addresses
    @param is_add - add address if non-zero, else delete
    @param del_all - if non-zero delete all addresses on the interface
    @param prefix - address + a prefix length for the implied connected route
*/
autoreply define sw_interface_add_del_address
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  bool is_add;

  bool del_all;
  vl_api_address_with_prefix_t prefix;
};

/** \brief IP interface address replace begin

    The use-case is that, for some unspecified reason, the control plane
    has a different set of interface addresses than VPP
    currently has. The CP would thus like to 'replace' VPP's set
    only by specifying what the new set shall be, i.e. it is not
    going to delete anything that already eixts, rather, is wants any
    unspecified interface addresses to be deleted implicitly.
    The CP declares the start of this procedure with this replace_begin
    API Call, and when it has populated all addresses it wants, it calls
    the below replace_end API. From this point on it is of course free
    to add and delete interface addresses as usual.
    The underlying mechanism by which VPP implements this replace is
    intentionally left unspecified.

    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
*/
autoreply define sw_interface_address_replace_begin
{
  u32 client_index;
  u32 context;
};

/** \brief IP interface address replace end

    see ip_interface_address_replace_begin description.

    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
*/
autoreply define sw_interface_address_replace_end
{
  u32 client_index;
  u32 context;
};

/** \brief Associate the specified interface with a fib table
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - index of the interface
    @param is_ipv6 - if non-zero ipv6, else ipv4
    @param vrf_id - fib table/vrf id to associate the interface with
*/
autoreply define sw_interface_set_table
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  bool is_ipv6;
  u32 vrf_id;
};

/** \brief Get VRF id assigned to interface
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - index of the interface
*/
define sw_interface_get_table
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  bool is_ipv6;
};

/** \brief Reply to get_sw_interface_vrf
    @param context - sender context which was passed in the request
    @param vrf_id - VRF id assigned to the interface
*/
define sw_interface_get_table_reply
{
  u32 context;
  i32 retval;
  u32 vrf_id;
};

/** \brief Set unnumbered interface add / del request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - interface with an IP address
    @param unnumbered_sw_if_index - interface which will use the address
    @param is_add - if non-zero set the association, else unset it
*/
autoreply define sw_interface_set_unnumbered
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;		/* use this intfc address */
  vl_api_interface_index_t unnumbered_sw_if_index;	/* on this interface */
  bool is_add;
};

/** \brief Clear interface statistics
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - index of the interface to clear statistics
*/
autoreply define sw_interface_clear_stats
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
};

/** \brief Set / clear software interface tag
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - the interface
    @param add_del - 1 = add, 0 = delete
    @param tag - an ascii tag
*/
autoreply define sw_interface_tag_add_del
{
  u32 client_index;
  u32 context;
  bool is_add;
  vl_api_interface_index_t sw_if_index;
  string tag[64];
};

/** \brief Add or delete a secondary MAC address on an interface
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - the interface whose MAC will be set
    @param mac_addr - the new MAC address
    @param is_add - 0 to delete, != 0 to add
*/
autoreply define sw_interface_add_del_mac_address
{
    u32 client_index;
    u32 context;
    u32 sw_if_index;
    vl_api_mac_address_t addr;
    u8 is_add;
};

/** \brief Set an interface's MAC address
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - the interface whose MAC will be set
    @param mac_addr - the new MAC address
*/
autoreply define sw_interface_set_mac_address
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  vl_api_mac_address_t mac_address;
};

/** \brief Get interface's MAC address
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - the interface whose MAC will be returned
*/
define sw_interface_get_mac_address
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
};

/** \brief Reply for get interface's MAC address request
    @param context - returned sender context, to match reply w/ request
    @param retval - return code
    @param mac_addr - returned interface's MAC address
*/
define sw_interface_get_mac_address_reply
{
  u32 context;
  i32 retval;
  vl_api_mac_address_t mac_address;
};

/** \brief Set an interface's rx-mode
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - the interface whose rx-mode will be set
    @param queue_id_valid - 1 = the queue_id field is valid. 0 means all
      queue_id's
    @param queue_id - the queue number whose rx-mode will be set. Only valid
      if queue_id_valid is 1
    @param mode - polling=1, interrupt=2, adaptive=3
*/
autoreply define sw_interface_set_rx_mode
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  bool queue_id_valid;
  u32 queue_id;
  vl_api_rx_mode_t mode;
};

/** \brief Set an interface's rx-placement
    Rx-Queue placement on specific thread is operational for only hardware
    interface. It will not set queue - thread placement for sub-interfaces,
    p2p and pipe interfaces.
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - the interface whose rx-placement will be set
    @param queue_id - the queue number whose rx-placement will be set.
    @param worker_id - the worker number whom rx-placement will be at.
    @param is_main - flag to set rx-placement to main thread
*/
autoreply define sw_interface_set_rx_placement
{
    u32 client_index;
    u32 context;
    vl_api_interface_index_t sw_if_index;
    u32 queue_id;
    u32 worker_id;
    bool is_main;
};

/** \brief Set an interface's tx-placement
    Tx-Queue placement on specific thread is operational for only hardware
    interface. It will not set queue - thread placement for sub-interfaces,
    p2p and pipe interfaces.
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - the interface whose tx-placement will be set
    @param queue_id - the queue number whose tx-placement will be set.
    @param array_size - the size of the thread indexes array
    @param threads - the thread indexes of main and worker(s) threads
                     whom tx-placement will be at.
*/
autoendian autoreply define sw_interface_set_tx_placement
{
    u32 client_index;
    u32 context;
    vl_api_interface_index_t sw_if_index;
    u32 queue_id;
    u32 array_size;
    u32 threads[array_size];
    option vat_help = "<interface | sw_if_index <index>> queue <n> [threads <list> | mask <hex>]";
};

/** \brief Set custom interface name
    Set custom interface name for the interface.
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - the interface whose name will be set
    @param name - the custom interface name to be set
k
*/
autoreply define sw_interface_set_interface_name
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  string name[64];
};

/** \brief dump the rx queue placement of interface(s)
    @param sw_if_index - optional interface index for which queue placement to
      be requested. sw_if_index = ~0 will dump placement information for all
      interfaces. It will not dump information related to sub-interfaces, p2p
      and pipe interfaces.
*/
define sw_interface_rx_placement_dump
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
};

/** \brief show the interface's queue - thread placement
    This api is used to display the interface and queue worker
    thread placement. One message per rx-queue per interface will
    be sent to client.
    Each message will contain information about rx-queue id of an
    interface, interface index, thread on which this rx-queue is
    placed and mode of rx-queue.
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - the interface whose rx-placement will be dumped
    @param queue_id - the queue id
    @param worker_id - the worker id on which queue_id is placed,
                       worker_id = 0 means main thread.
    @param mode - polling=1, interrupt=2, adaptive=3
*/
define sw_interface_rx_placement_details
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  u32 queue_id;
  u32 worker_id;
  vl_api_rx_mode_t mode;
};

service {
  rpc sw_interface_tx_placement_get returns sw_interface_tx_placement_get_reply
    stream sw_interface_tx_placement_details;
};

/** \brief get the tx queue placement of interface(s)
    @param cursor - optional, it allows client to continue a dump
    @param sw_if_index - optional interface index for which queue placement to
      be requested. sw_if_index = ~0 will get the placement information for all
      interfaces. It will not get information related to sub-interfaces, p2p
      and pipe interfaces.
*/
autoendian define sw_interface_tx_placement_get
{
  u32 client_index;
  u32 context;
  u32 cursor;
  vl_api_interface_index_t sw_if_index;
  option vat_help = "[interface | sw_if_index <index>]";
};

autoendian define sw_interface_tx_placement_get_reply
{
  u32 context;
  i32 retval;
  u32 cursor;
};

/** \brief show the interface's queue - thread placement
    This api is used to display the interface and queue worker
    thread placement. One message per tx-queue per interface will
    be sent to client.
    Each message will contain information about tx-queue id of an
    interface, interface index, thread on which this tx-queue is
    placed and mode of tx-queue.
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - the interface whose tx-placement will be dumped
    @param queue_id - the queue id
    @param shared - the queue is shared on other threads
    @param array_size - the size of the threads array
    @param threads - the main and worker(s) thread index(es) whom tx-placement are at.
*/
autoendian define sw_interface_tx_placement_details
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  u32 queue_id;
  u8 shared;
  u32 array_size;
  u32 threads[array_size];
};

/* Gross kludge, DGMS */
autoreply define interface_name_renumber
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  u32 new_show_dev_instance;
};

define create_subif
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  u32 sub_id;

  vl_api_sub_if_flags_t sub_if_flags;
  u16 outer_vlan_id;
  u16 inner_vlan_id;
};

define create_subif_reply
{
  u32 context;
  i32 retval;
  vl_api_interface_index_t sw_if_index;
};

/** \brief Create a new subinterface with the given vlan id
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - software index of the new vlan's parent interface
    @param vlan_id - vlan tag of the new interface
*/
define create_vlan_subif
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  u32 vlan_id;
};

/** \brief Reply for the vlan subinterface create request
    @param context - returned sender context, to match reply w/ request
    @param retval - return code
    @param sw_if_index - software index allocated for the new subinterface
*/
define create_vlan_subif_reply
{
  u32 context;
  i32 retval;
  vl_api_interface_index_t sw_if_index;
};

/** \brief Delete sub 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 by create_subif
*/
autoreply define delete_subif {
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
};

/** \brief Create loopback interface 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
*/
define create_loopback
{
  u32 client_index;
  u32 context;
  vl_api_mac_address_t mac_address;
};

/** \brief Create loopback interface 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 create_loopback_reply
{
  u32 context;
  i32 retval;
  vl_api_interface_index_t sw_if_index;
};

/** \brief Create loopback 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 is_specified - if non-0, a specific user_instance is being requested
    @param user_instance - requested instance, ~0 => dynamically allocate
*/
define create_loopback_instance
{
  u32 client_index;
  u32 context;
  vl_api_mac_address_t mac_address;
  bool is_specified;
  u32 user_instance;
};

/** \brief Create loopback 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 create_loopback_instance_reply
{
  u32 context;
  i32 retval;
  vl_api_interface_index_t sw_if_index;
};

/** \brief Delete loopback 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 delete_loopback
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
};

/** \brief Enable or disable detailed interface stats
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - The interface to collect detail stats on. ~0 implies
                         all interfaces.
    @param enable_disable - set to 1 to enable, 0 to disable detailed stats
*/
autoreply define collect_detailed_interface_stats
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  bool  enable_disable;
};

/** \brief pcap_set_filter_function
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param filter_function_name - the name of the filter function
                                  to set for pcap capture
*/
autoreply define pcap_set_filter_function
{
    u32 client_index;
    u32 context;

    string filter_function_name[];
};

/** \brief pcap_trace_on
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param capture_rx - capture received packets
    @param capture_tx - capture transmitted packets
    @param capture_drop - capture dropped packets
    @param filter - is a filter is being used on this capture
    @param preallocate_data - preallocate the data buffer
    @param free_data - free the data buffer
    @param max_packets - depth of local buffer
    @param max_bytes_per_packet - maximum number of bytes to capture
                                  for each packet
    @param sw_if_index - specify a given interface, or 0 for any
    @param error - filter packets based on a specific error.
    @param filename - output filename, will be placed in /tmp
*/
autoreply define pcap_trace_on
{
    u32 client_index;
    u32 context;
    bool capture_rx;
    bool capture_tx;
    bool capture_drop;
    bool filter;
    bool preallocate_data;
    bool free_data;
    u32 max_packets [default=1000];
    u32 max_bytes_per_packet [default=512];
    vl_api_interface_index_t sw_if_index;
    string error[128];
    string filename[64];

    option vat_help = "pcap_trace_on [capture_rx] [capture_tx] [capture_drop] [max_packets <nn>] [sw_if_index <sw_if_index>|0 for any] [error <node>.<error>] [filename <name>] [max_bytes_per_packet <nnnn>] [filter] [preallocate_data] [free_data]";
};

autoreply define pcap_trace_off
{
  u32 client_index;
  u32 context;
};

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