src/vnet/ip-neighbor/ip_neighbor.api

   1 /* Hey Emacs use -*- mode: C -*- */
   2 /*
   3  * Copyright (c) 2018 Cisco and/or its affiliates.
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at:
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /** \file
  18
  19     This file defines vpp IP neighbor control-plane API messages which are generally
  20     called through a shared memory interface.
  21 */
  22
  23 option version = "1.0.0";
  24
  25 import "vnet/ip/ip_types.api";
  26 import "vnet/ethernet/ethernet_types.api";
  27 import "vnet/interface_types.api";
  28
  29 /** \brief IP neighbor flags
  30     @param is_static - A static neighbor Entry - there are not flushed
  31                        If the interface goes down.
  32     @param is_no_fib_entry - Do not create a corresponding entry in the FIB
  33                            table for the neighbor.
  34 */
  35 enum ip_neighbor_flags: u8
  36 {
  37   IP_API_NEIGHBOR_FLAG_NONE = 0,
  38   IP_API_NEIGHBOR_FLAG_STATIC = 0x1,
  39   IP_API_NEIGHBOR_FLAG_NO_FIB_ENTRY = 0x2,
  40 };
  41
  42 /** \brief IP neighbor
  43     @param sw_if_index - interface used to reach neighbor
  44     @param flags - flags for the neighbor
  45     @param mac_address - l2 address of the neighbor
  46     @param ip_address - ip4 or ip6 address of the neighbor
  47 */
  48 typedef ip_neighbor {
  49   vl_api_interface_index_t sw_if_index;
  50   vl_api_ip_neighbor_flags_t flags;
  51   vl_api_mac_address_t mac_address;
  52   vl_api_address_t ip_address;
  53 };
  54
  55 /** \brief IP neighbor add / del request
  56     @param client_index - opaque cookie to identify the sender
  57     @param context - sender context, to match reply w/ request
  58     @param is_add - 1 to add neighbor, 0 to delete
  59     @param neighbor - the neighbor to add/remove
  60 */
  61 define ip_neighbor_add_del
  62 {
  63   u32 client_index;
  64   u32 context;
  65   /* 1 = add, 0 = delete */
  66   bool is_add;
  67   vl_api_ip_neighbor_t neighbor;
  68 };
  69 /** \brief IP neighbor add / del reply
  70     @param client_index - opaque cookie to identify the sender
  71     @param context - sender context, to match reply w/ request
  72     @param retval - return value
  73     @param stats_index - the index to use for this neighbor in the stats segment
  74 */
  75 define ip_neighbor_add_del_reply
  76 {
  77   u32 context;
  78   i32 retval;
  79   u32 stats_index;
  80 };
  81
  82 /** \brief Dump IP neighbors
  83     @param client_index - opaque cookie to identify the sender
  84     @param context - sender context, to match reply w/ request
  85     @param sw_if_index - the interface to dump neighbors, ~0 == all
  86     @param af - address family is ipv[6|4]
  87 */
  88 define ip_neighbor_dump
  89 {
  90   u32 client_index;
  91   u32 context;
  92   vl_api_interface_index_t sw_if_index  [default=0xffffffff];
  93   vl_api_address_family_t af;
  94 };
  95
  96 /** \brief IP neighbors dump response
  97     @param context - sender context which was passed in the request
  98     @param age - time between last update and sending this message, in seconds
  99     @param neighbour - the neighbor
 100 */
 101 define ip_neighbor_details {
 102   u32 context;
 103   f64 age;
 104   vl_api_ip_neighbor_t neighbor;
 105 };
 106
 107 /** \brief Enable/disable periodic IP neighbor scan
 108     @param client_index - opaque cookie to identify the sender
 109     @param context - sender context, to match reply w/ request
 110     @param af - Address family v4/v6
 111     @param max_number - The maximum number of neighbours that will be created.
 112                          default 50k
 113     @param max_age - The maximum age (in seconds) before an inactive neighbour
 114                      is flushed
 115                          default 0 => never
 116     @param recycle - If max_number of neighbours is reached and new ones need
 117                       to be created should the oldest neighbour be 'recycled'.
 118 */
 119 autoreply define ip_neighbor_config
 120 {
 121   u32 client_index;
 122   u32 context;
 123   vl_api_address_family_t af;
 124   u32 max_number;
 125   u32 max_age;
 126   bool recycle;
 127 };
 128
 129 /** \brief IP neighbour replace begin
 130
 131     The use-case is that, for some unspecified reason, the control plane
 132     has a different set of neighbours it than VPP
 133     currently has. The CP would thus like to 'replace' VPP's set
 134     only by specifying what the new set shall be, i.e. it is not
 135     going to delete anything that already exists, rather, it wants any
 136     unspecified neighbors deleted implicitly.
 137     The CP declares the start of this procedure with this replace_begin
 138     API Call, and when it has populated all neighbours it wants, it calls
 139     the below replace_end API. From this point on it is of course free
 140     to add and delete neighbours as usual.
 141     The underlying mechanism by which VPP implements this replace is
 142     intentionally left unspecified.
 143
 144     @param client_index - opaque cookie to identify the sender
 145     @param context - sender context, to match reply w/ request
 146 */
 147 autoreply define ip_neighbor_replace_begin
 148 {
 149   u32 client_index;
 150   u32 context;
 151 };
 152
 153 /** \brief IP neighbour replace end
 154
 155     see ip_neighbor_replace_begin description.
 156
 157     @param client_index - opaque cookie to identify the sender
 158     @param context - sender context, to match reply w/ request
 159 */
 160 autoreply define ip_neighbor_replace_end
 161 {
 162   u32 client_index;
 163   u32 context;
 164 };
 165
 166 /** \brief IP neighbor flush request - removes *all* neighbours.
 167      dynamic and static from API/CLI and dynamic from data-plane.
 168
 169     @param client_index - opaque cookie to identify the sender
 170     @param context - sender context, to match reply w/ request
 171     @param af - Flush neighbours of this address family
 172     @param sw_if_index - Flush on this interface (~0 => all interfaces)
 173 */
 174 autoreply define ip_neighbor_flush
 175 {
 176   u32 client_index;
 177   u32 context;
 178   vl_api_address_family_t af;
 179   vl_api_interface_index_t sw_if_index [default=0xffffffff];
 180 };
 181
 182 /** \brief Register for IP neighbour events creation
 183     @param client_index - opaque cookie to identify the sender
 184     @param context - sender context, to match reply w/ request
 185     @param enable - 1 => register for events, 0 => cancel registration
 186     @param pid - sender's pid
 187     @param ip - exact IP address of interested neighbor resolution event
 188     @param sw_if_index - interface on which the IP address is present.
 189 */
 190 autoreply define want_ip_neighbor_events
 191 {
 192   option deprecated;
 193   u32 client_index;
 194   u32 context;
 195   bool enable;
 196   u32 pid;
 197   vl_api_address_t ip;
 198   vl_api_interface_index_t sw_if_index [default=0xffffffff];
 199 };
 200
 201 /** \brief Tell client about an IP4 ARP resolution event or
 202            MAC/IP info from ARP requests in L2 BDs
 203     @param client_index - opaque cookie to identify the sender
 204     @param pid - client pid registered to receive notification
 205     @param neighbor - new neighbor created
 206 */
 207 define ip_neighbor_event
 208 {
 209   option deprecated;
 210   u32 client_index;
 211   u32 pid;
 212   vl_api_ip_neighbor_t neighbor;
 213 };
 214
 215 service {
 216   rpc want_ip_neighbor_events returns want_ip_neighbor_events_reply
 217     events ip_neighbor_event;
 218 };
 219
 220
 221 /** \brief Register for IP neighbour events (creation or deletion)
 222     @param client_index - opaque cookie to identify the sender
 223     @param context - sender context, to match reply w/ request
 224     @param enable - 1 => register for events, 0 => cancel registration
 225     @param pid - sender's pid
 226     @param ip - exact IP address of interested neighbor resolution event
 227     @param sw_if_index - interface on which the IP address is present.
 228 */
 229 autoreply define want_ip_neighbor_events_v2
 230 {
 231   u32 client_index;
 232   u32 context;
 233   bool enable;
 234   u32 pid;
 235   vl_api_address_t ip;
 236   vl_api_interface_index_t sw_if_index [default=0xffffffff];
 237 };
 238
 239 enum ip_neighbor_event_flags
 240 {
 241  /* The neighbor has been added/learned */
 242  IP_NEIGHBOR_API_EVENT_FLAG_ADDED = 0x1,
 243  /* The neighbor has been removed/expired */
 244  IP_NEIGHBOR_API_EVENT_FLAG_REMOVED = 0x2,
 245 };
 246
 247 /** \brief Tell client about an IP4 ARP resolution event or
 248            MAC/IP info from ARP requests in L2 BDs
 249     @param client_index - opaque cookie to identify the sender
 250     @param pid - client pid registered to receive notification
 251     @param flags - Flags
 252     @param neighbor -  neighbor
 253 */
 254 define ip_neighbor_event_v2
 255 {
 256   u32 client_index;
 257   u32 pid;
 258   vl_api_ip_neighbor_event_flags_t flags;
 259   vl_api_ip_neighbor_t neighbor;
 260 };
 261
 262 service {
 263   rpc want_ip_neighbor_events_v2 returns want_ip_neighbor_events_v2_reply
 264     events ip_neighbor_event_v2;
 265 };
 266
 267 /*
 268  * Local Variables:
 269  * eval: (c-set-style "gnu")
 270  * End:
 271  */