interface.api

Go to the documentation of this file.

/* 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.1.1";

import "vnet/interface_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 admin_up_down - set the admin state, 1 = up, 0 = down
    @param link_up_down - Oper state sent on change event, not used in config.
*/
autoreply define sw_interface_set_flags
{
  u32 client_index;
  u32 context;
  u32 sw_if_index;
  /* 1 = up, 0 = down */
  u8 admin_up_down;
};

/** \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;
  u32 sw_if_index;
  u16 mtu;
};

/** \brief Set interface L3 MTU */
autoreply define sw_interface_set_mtu
{
  u32 client_index;
  u32 context;
  u32 sw_if_index;
  /* $$$$ Replace with enum */
  u32 mtu[4]; /* 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;
  u32 sw_if_index;
  u8  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 admin_up_down - The administrative state; 1 = up, 0 = down
    @param link_up_down - The operational state; 1 = up, 0 = down
    @param deleted - interface was deleted
*/
define sw_interface_event
{
  u32 client_index;
  u32 pid;
  u32 sw_if_index;
  u8 admin_up_down;
  u8 link_up_down;
  u8 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_length - length of the interface's l2 address
    @param l2_address - the interface's l2 address
    @param interface_name - name of the interface
    @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_if_id - A number 0-N to uniquely identify this subif on super if
    @param sub_dot1ad - 0 = dot1q, 1 = dot1ad
    @param sub_dot1ah - 1 = dot1ah, 0 = otherwise
    @param sub_number_of_tags - Number of tags (0 - 2)
    @param sub_outer_vlan_id
    @param sub_inner_vlan_id
    @param sub_exact_match
    @param sub_default
    @param sub_outer_vlan_id_any
    @param sub_inner_vlan_id_any
    @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
*/
define sw_interface_details
{
  u32 context;
  u32 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 */
  u32 l2_address_length;
  u8 l2_address[8];

  /* 1 = up, 0 = down */
  u8 admin_up_down;
  u8 link_up_down;

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

  /* link speed in kbps */
  u32 link_speed;

  /* MTU */
  u16 link_mtu;

  /* Per protocol MTUs */
  u32 mtu[4]; /* 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;

  /* 0 = dot1q, 1=dot1ad */
  u8 sub_dot1ad;
  /* 1 = dot1h, 1=otherwise */
  u8 sub_dot1ah;

  /* Number of tags 0-2 */
  u8 sub_number_of_tags;
  u16 sub_outer_vlan_id;
  u16 sub_inner_vlan_id;
  u8 sub_exact_match;
  u8 sub_default;
  u8 sub_outer_vlan_id_any;
  u8 sub_inner_vlan_id_any;

  /* 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;
  u8  b_dmac[6];
  u8  b_smac[6];
  u16 b_vlanid;
  u32 i_sid;

  /* Interface name */
  string interface_name[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;
  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 is_ipv6 - if non-zero the address is ipv6, else ipv4
    @param del_all - if non-zero delete all addresses on the interface
    @param address_length - address length in bytes, 4 for ip4, 16 for ip6
    @param address - array of address bytes
*/
autoreply define sw_interface_add_del_address
{
  u32 client_index;
  u32 context;
  u32 sw_if_index;
  u8 is_add;
  u8 is_ipv6;
  u8 del_all;
  u8 address_length;
  u8 address[16];
};

/** \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;
  u32 sw_if_index;
  u8 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;
  u32 sw_if_index;
  u8 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;
  u32 sw_if_index;              /* use this intfc address */
  u32 unnumbered_sw_if_index;   /* on this interface */
  u8 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;
  u32 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 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;
    u32 sw_if_index;
    u8 mac_address[6];
};

/** \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;
    u32 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;
    u8 mac_address[6];
};

/** \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;
    u32 sw_if_index;
    u8 queue_id_valid;
    u32 queue_id;
    u8 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;
    u32 sw_if_index;
    u32 queue_id;
    u32 worker_id;
    u8 is_main;
};

/** \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;
  u32 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;
  u32 sw_if_index;
  u32 queue_id;
  u32 worker_id;
  u8 mode;
};

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

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

  /* These fields map directly onto the subif template */
  u8 no_tags;
  u8 one_tag;
  u8 two_tags;
  u8 dot1ad;                    // 0 = dot1q, 1=dot1ad
  u8 exact_match;
  u8 default_sub;
  u8 outer_vlan_id_any;
  u8 inner_vlan_id_any;
  u16 outer_vlan_id;
  u16 inner_vlan_id;
};

define create_subif_reply
{
  u32 context;
  i32 retval;
  u32 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;
  u32 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;
  u32 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;
  u32 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;
  u8 mac_address[6];
};

/** \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;
  u32 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;
  u8 mac_address[6];
  u8 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;
  u32 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;
  u32 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;
  u32 sw_if_index;
  u8  enable_disable;
};

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