bsd/net/kpi_interface.h

   1 /*
   2  * Copyright (c) 2006 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_OSREFERENCE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License.  The rights granted to you under the
  10  * License may not be used to create, or enable the creation or
  11  * redistribution of, unlawful or unlicensed copies of an Apple operating
  12  * system, or to circumvent, violate, or enable the circumvention or
  13  * violation of, any terms of an Apple operating system software license
  14  * agreement.
  15  *
  16  * Please obtain a copy of the License at
  17  * http://www.opensource.apple.com/apsl/ and read it before using this
  18  * file.
  19  *
  20  * The Original Code and all software distributed under the License are
  21  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25  * Please see the License for the specific language governing rights and
  26  * limitations under the License.
  27  *
  28  * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
  29  */
  30 /*!
  31         @header kpi_interface.h
  32         This header defines an API to interact with network interfaces in
  33         the kernel. The network interface KPI may be used to implement
  34         network interfaces or to attach protocols to existing interfaces.
  35  */
  36
  37 #ifndef __KPI_INTERFACE__
  38 #define __KPI_INTERFACE__
  39 #include <sys/kernel_types.h>
  40
  41 #ifndef _SA_FAMILY_T
  42 #define _SA_FAMILY_T
  43 typedef __uint8_t               sa_family_t;
  44 #endif
  45
  46 struct timeval;
  47 struct sockaddr;
  48 struct sockaddr_dl;
  49 struct kern_event_msg;
  50 struct kev_msg;
  51 struct ifnet_demux_desc;
  52
  53 /*!
  54         @enum Interface Families
  55         @abstract Constants defining interface families.
  56         @constant IFNET_FAMILY_ANY Match interface of any family type.
  57         @constant IFNET_FAMILY_LOOPBACK A software loopback interface.
  58         @constant IFNET_FAMILY_ETHERNET An Ethernet interface.
  59         @constant IFNET_FAMILY_SLIP A SLIP interface.
  60         @constant IFNET_FAMILY_TUN A tunnel interface.
  61         @constant IFNET_FAMILY_VLAN A virtual LAN interface.
  62         @constant IFNET_FAMILY_PPP A PPP interface.
  63         @constant IFNET_FAMILY_PVC A PVC interface.
  64         @constant IFNET_FAMILY_DISC A DISC interface.
  65         @constant IFNET_FAMILY_MDECAP A MDECAP interface.
  66         @constant IFNET_FAMILY_GIF A generic tunnel interface.
  67         @constant IFNET_FAMILY_FAITH A FAITH (IPv4/IPv6 translation) interface.
  68         @constant IFNET_FAMILY_STF A 6to4 interface.
  69         @constant IFNET_FAMILY_FIREWIRE An IEEE 1394 (firewire) interface.
  70         @constant IFNET_FAMILY_BOND A virtual bonded interface.
  71 */
  72
  73 enum {
  74                 IFNET_FAMILY_ANY                = 0,
  75                 IFNET_FAMILY_LOOPBACK   = 1,
  76                 IFNET_FAMILY_ETHERNET   = 2,
  77                 IFNET_FAMILY_SLIP               = 3,
  78                 IFNET_FAMILY_TUN                = 4,
  79                 IFNET_FAMILY_VLAN               = 5,
  80                 IFNET_FAMILY_PPP                = 6,
  81                 IFNET_FAMILY_PVC                = 7,
  82                 IFNET_FAMILY_DISC               = 8,
  83                 IFNET_FAMILY_MDECAP             = 9,
  84                 IFNET_FAMILY_GIF                = 10,
  85                 IFNET_FAMILY_FAITH              = 11,
  86                 IFNET_FAMILY_STF                = 12,
  87                 IFNET_FAMILY_FIREWIRE   = 13,
  88                 IFNET_FAMILY_BOND               = 14
  89 };
  90 /*!
  91         @typedef ifnet_family_t
  92         @abstract Storage type for the interface family.
  93 */
  94 typedef u_int32_t ifnet_family_t;
  95
  96 /*!
  97         @enum BPF tap mode
  98         @abstract Constants defining interface families.
  99         @constant BPF_MODE_DISABLED Disable bpf.
 100         @constant BPF_MODE_INPUT Enable input only.
 101         @constant BPF_MODE_OUTPUT Enable output only.
 102         @constant BPF_MODE_INPUT_OUTPUT Enable input and output.
 103 */
 104
 105 enum {
 106                 BPF_MODE_DISABLED               = 0,
 107                 BPF_MODE_INPUT                  = 1,
 108                 BPF_MODE_OUTPUT                 = 2,
 109                 BPF_MODE_INPUT_OUTPUT   = 3
 110 };
 111 /*!
 112         @typedef bpf_tap_mode
 113         @abstract Mode for tapping. BPF_MODE_DISABLED/BPF_MODE_INPUT_OUTPUT etc.
 114 */
 115 typedef u_int32_t bpf_tap_mode;
 116
 117 /*!
 118         @typedef protocol_family_t
 119         @abstract Storage type for the protocol family.
 120 */
 121 typedef u_int32_t protocol_family_t;
 122
 123 /*!
 124         @enum Interface Abilities
 125         @abstract Constants defining interface offload support.
 126         @constant IFNET_CSUM_IP Hardware will calculate IPv4 checksums.
 127         @constant IFNET_CSUM_TCP Hardware will calculate TCP checksums.
 128         @constant IFNET_CSUM_UDP Hardware will calculate UDP checksums.
 129         @constant IFNET_CSUM_FRAGMENT Hardware will checksum IP fragments.
 130         @constant IFNET_IP_FRAGMENT Hardware will fragment IP packets.
 131         @constant IFNET_VLAN_TAGGING Hardware will generate VLAN headers.
 132         @constant IFNET_VLAN_MTU Hardware supports VLAN MTU.
 133 */
 134
 135 enum {
 136                 IFNET_CSUM_IP           = 0x00000001,
 137                 IFNET_CSUM_TCP          = 0x00000002,
 138                 IFNET_CSUM_UDP          = 0x00000004,
 139                 IFNET_CSUM_FRAGMENT     = 0x00000008,
 140                 IFNET_IP_FRAGMENT       = 0x00000010,
 141 #ifdef KERNEL_PRIVATE
 142                 IFNET_CSUM_SUM16        = 0x00001000,
 143 #endif
 144                 IFNET_VLAN_TAGGING      = 0x00010000,
 145                 IFNET_VLAN_MTU          = 0x00020000,
 146 };
 147 /*!
 148         @typedef ifnet_offload_t
 149         @abstract Flags indicating the offload support of the interface.
 150 */
 151 typedef u_int32_t ifnet_offload_t;
 152
 153 /*
 154  * Callbacks
 155  *
 156  * These are function pointers you supply to the kernel in the interface.
 157  */
 158 /*!
 159         @typedef bpf_packet_func
 160
 161         @discussion bpf_packet_func The bpf_packet_func is used to intercept
 162                 inbound and outbound packets. The tap function will never free
 163                 the mbuf. The tap function will only copy the mbuf in to various
 164                 bpf file descriptors tapping this interface.
 165         @param interface The interface being sent or received on.
 166         @param data The packet to be transmitted or received.
 167         @result An errno value or zero upon success.
 168  */
 169 /* Fast path - do not block or spend excessive amounts of time */
 170 typedef errno_t (*bpf_packet_func)(ifnet_t interface, mbuf_t data);
 171
 172 /*!
 173         @typedef ifnet_output_func
 174
 175         @discussion ifnet_output_func is used to transmit packets. The stack
 176                 will pass fully formed packets, including frame header, to the
 177                 ifnet_output function for an interface. The driver is
 178                 responsible for freeing the mbuf.
 179         @param interface The interface being sent on.
 180         @param data The packet to be sent.
 181  */
 182 /* Fast path - do not block or spend excessive amounts of time */
 183 typedef errno_t (*ifnet_output_func)(ifnet_t interface, mbuf_t data);
 184
 185 /*!
 186         @typedef ifnet_ioctl_func
 187         @discussion ifnet_ioctl_func is used to communicate ioctls from the
 188                 stack to the driver.
 189         @param interface The interface the ioctl is being sent to.
 190         @param proto_family The protocol family to handle the ioctl, may be
 191                 zero for no protocol_family.
 192         @param cmd The ioctl command.
 193         @param data A pointer to any data related to the ioctl.
 194  */
 195 typedef errno_t (*ifnet_ioctl_func)(ifnet_t interface, u_int32_t cmd, void *data);
 196
 197 /*!
 198         @typedef ifnet_set_bpf_tap
 199         @discussion ifnet_set_bpf_tap is used to set the bpf tap function to
 200                 be called when packets are sent and/or received.
 201         @param interface The interface the bpf tap function is being set on.
 202         @param mode Sets the mode of the tap to either disabled, input,
 203                 output, or input/output.
 204         @param callback A function pointer to be called when a packet is
 205                 sent or received.
 206  */
 207 typedef errno_t (*ifnet_set_bpf_tap)(ifnet_t interface, bpf_tap_mode mode,
 208                                 bpf_packet_func callback);
 209
 210 /*!
 211         @typedef ifnet_detached_func
 212         @discussion ifnet_detached_func is called an interface is detached
 213                 from the list of interfaces. When ifnet_detach is called, it may
 214                 not detach the interface immediately if protocols are attached.
 215                 ifnet_detached_func is used to notify the interface that it has
 216                 been detached from the networking stack. This is the last
 217                 function that will be called on an interface. Until this
 218                 function returns, you must not unload a kext supplying function
 219                 pointers to this interface, even if ifnet_detacah has been
 220                 called. Your detach function may be called during your call to
 221                 ifnet_detach.
 222         @param interface The interface that has been detached.
 223                 event.
 224  */
 225 typedef void (*ifnet_detached_func)(ifnet_t interface);
 226
 227 /*!
 228         @typedef ifnet_demux_func
 229         @discussion ifnet_demux_func is called for each inbound packet to determine
 230                 which protocol family the packet belongs to. This information is then
 231                 used by the stack to determine which protocol to pass the packet to.
 232                 This function may return protocol families for protocols that are
 233                 not attached. If the protocol family has not been attached to the
 234                 interface, the packet will be discarded.
 235         @param interface The interface the packet was received on.
 236         @param packet The mbuf containing the packet.
 237         @param frame_header A pointer to the frame header.
 238         @param protocol_family Upon return, the protocol family matching the
 239                 packet should be stored here.
 240         @result
 241                 If the result is zero, processing will continue normally.
 242                 If the result is EJUSTRETURN, processing will stop but the packet will not be freed.
 243                 If the result is anything else, the processing will stop and the packet will be freed.
 244  */
 245 typedef errno_t (*ifnet_demux_func)(ifnet_t interface, mbuf_t packet,
 246                                                                         char *frame_header,
 247                                                                         protocol_family_t *protocol_family);
 248
 249 /*!
 250         @typedef ifnet_event_func
 251         @discussion ifnet_event_func is called when an event occurs on a
 252                 specific interface.
 253         @param interface The interface the event occurred on.
 254         @param event_ptr Pointer to a kern_event structure describing the
 255                 event.
 256  */
 257 typedef void (*ifnet_event_func)(ifnet_t interface, const struct kev_msg *msg);
 258
 259 /*!
 260         @typedef ifnet_framer_func
 261         @discussion ifnet_framer_func is called for each outbound packet to
 262                 give the interface an opportunity to prepend interface specific
 263                 headers.
 264         @param interface The interface the packet is being sent on.
 265         @param packet Pointer to the mbuf containing the packet, caller may
 266                 set this to a different mbuf upon return. This can happen if the
 267                 frameout function needs to prepend another mbuf to the chain to
 268                 have enough space for the header.
 269         @param dest The higher layer protocol destination (i.e. IP address).
 270         @param dest_linkaddr The link layer address as determined by the
 271                 protocol's pre-output function.
 272         @param frame_type The frame type as determined by the protocol's
 273                 pre-output function.
 274         @result
 275                 If the result is zero, processing will continue normally.
 276                 If the result is EJUSTRETURN, processing will stop but the packet will not be freed.
 277                 If the result is anything else, the processing will stop and the packet will be freed.
 278  */
 279 typedef errno_t (*ifnet_framer_func)(ifnet_t interface, mbuf_t *packet,
 280                                                                          const struct sockaddr *dest,
 281                                                                          const char *desk_linkaddr,
 282                                                                          const char *frame_type);
 283
 284 /*!
 285         @typedef ifnet_add_proto_func
 286         @discussion if_add_proto_func is called by the stack when a protocol
 287                 is attached to an interface. This gives the interface an
 288                 opportunity to get a list of protocol description structures
 289                 for demuxing packets to this protocol (demux descriptors).
 290         @param interface The interface the protocol will be attached to.
 291         @param protocol_family The family of the protocol being attached.
 292         @param demux_array An array of demux descriptors that describe
 293                 the interface specific ways of identifying packets belonging
 294                 to this protocol family.
 295         @param demux_count The number of demux descriptors in the array.
 296         @result
 297                 If the result is zero, processing will continue normally.
 298                 If the result is anything else, the add protocol will be aborted.
 299  */
 300 typedef errno_t (*ifnet_add_proto_func)(ifnet_t interface,
 301                                                                                 protocol_family_t protocol_family,
 302                                                                                 const struct ifnet_demux_desc *demux_array,
 303                                                                                 u_int32_t demux_count);
 304
 305 /*!
 306         @typedef if_del_proto_func
 307         @discussion if_del_proto_func is called by the stack when a protocol
 308                 is being detached from an interface. This gives the interface an
 309                 opportunity to free any storage related to this specific
 310                 protocol being attached to this interface.
 311         @param interface The interface the protocol will be detached from.
 312         @param protocol_family The family of the protocol being detached.
 313         @result
 314                 If the result is zero, processing will continue normally.
 315                 If the result is anything else, the detach will continue
 316                         and the error will be returned to the caller.
 317  */
 318 typedef errno_t (*ifnet_del_proto_func)(ifnet_t interface,
 319                                                                                 protocol_family_t protocol_family);
 320
 321 /*!
 322         @typedef ifnet_check_multi
 323         @discussion ifnet_check_multi is called for each multicast address
 324                 added to an interface. This gives the interface an opportunity
 325                 to reject invalid multicast addresses before they are attached
 326                 to the interface.
 327
 328                 To prevent an address from being added to your multicast list,
 329                 return EADDRNOTAVAIL. If you don't know how to parse/translate
 330                 the address, return EOPNOTSUPP.
 331         @param The interface.
 332         @param mcast The multicast address.
 333         @result
 334                 Zero upon success, EADDRNOTAVAIL on invalid multicast,
 335                 EOPNOTSUPP for addresses the interface does not understand.
 336  */
 337 typedef errno_t (*ifnet_check_multi)(ifnet_t interface,
 338                                                                          const struct sockaddr* mcast);
 339
 340 /*!
 341         @typedef proto_media_input
 342         @discussion proto_media_input is called for all inbound packets for
 343                 a specific protocol on a specific interface. This function is
 344                 registered on an interface using ifnet_attach_protocol.
 345         @param ifp The interface the packet was received on.
 346         @param protocol_family The protocol of the packet received.
 347         @param packet The packet being input.
 348         @param header The frame header.
 349         @result
 350                 If the result is zero, the caller will assume the packet was passed
 351                 to the protocol.
 352                 If the result is non-zero and not EJUSTRETURN, the caller will free
 353                 the packet.
 354  */
 355 typedef errno_t (*proto_media_input)(ifnet_t ifp, protocol_family_t protocol,
 356                                                                          mbuf_t packet, char* header);
 357
 358 /*!
 359         @typedef proto_media_preout
 360         @discussion proto_media_preout is called just before the packet
 361                 is transmitted. This gives the proto_media_preout function an
 362                 opportunity to specify the media specific frame type and
 363                 destination.
 364         @param ifp The interface the packet will be sent on.
 365         @param protocol_family The protocol of the packet being sent
 366                 (PF_INET/etc...).
 367         @param packet The packet being sent.
 368         @param dest The protocol level destination address.
 369         @param route A pointer to the routing structure for the packet.
 370         @param frame_type The media specific frame type.
 371         @param link_layer_dest The media specific destination.
 372         @result
 373                 If the result is zero, processing will continue normally. If the
 374                 result is non-zero, processing will stop. If the result is
 375                 non-zero and not EJUSTRETURN, the packet will be freed by the
 376                 caller.
 377  */
 378 typedef errno_t (*proto_media_preout)(ifnet_t ifp, protocol_family_t protocol,
 379                                                                           mbuf_t *packet, const struct sockaddr *dest,
 380                                                                           void *route, char *frame_type, char *link_layer_dest);
 381
 382 /*!
 383         @typedef proto_media_event
 384         @discussion proto_media_event is called to notify this layer of
 385                 interface specific events.
 386         @param ifp The interface.
 387         @param protocol_family The protocol family.
 388         @param kev_msg The event.
 389  */
 390 typedef void (*proto_media_event)(ifnet_t ifp, protocol_family_t protocol,
 391                                                                   const struct kev_msg *event);
 392
 393 /*!
 394         @typedef proto_media_ioctl
 395         @discussion proto_media_event allows this layer to handle ioctls.
 396                 When an ioctl is handled, it is passed to the interface filters,
 397                 protocol filters, protocol, and interface. If you do not support
 398                 this ioctl, return EOPNOTSUPP. If you successfully handle the
 399                 ioctl, return zero. If you return any error other than
 400                 EOPNOTSUPP, other parts of the stack may not get an opportunity
 401                 to process the ioctl. If you return EJUSTRETURN, processing will
 402                 stop and a result of zero will be returned to the caller.
 403         @param ifp The interface.
 404         @param protocol_family The protocol family.
 405         @param command The ioctl command.
 406         @param argument The argument to the ioctl.
 407         @result
 408                 See the discussion.
 409  */
 410 typedef errno_t (*proto_media_ioctl)(ifnet_t ifp, protocol_family_t protocol,
 411                                                                          u_int32_t command, void* argument);
 412
 413 /*!
 414         @typedef proto_media_detached
 415         @discussion proto_media_detached notifies you that your protocol
 416                 has been detached.
 417         @param ifp The interface.
 418         @param protocol_family The protocol family.
 419         @result
 420                 See the discussion.
 421  */
 422 typedef errno_t (*proto_media_detached)(ifnet_t ifp, protocol_family_t protocol);
 423
 424
 425 /*!
 426         @typedef proto_media_resolve_multi
 427         @discussion proto_media_resolve_multi is called to resolve a
 428                 protocol layer mulitcast address to a link layer multicast
 429                 address.
 430         @param ifp The interface.
 431         @param proto_addr The protocol address.
 432         @param out_ll A sockaddr_dl to copy the link layer multicast in to.
 433         @param ll_len The length of data allocated for out_ll.
 434         @result Return zero on success or an errno error value on failure.
 435  */
 436 typedef errno_t (*proto_media_resolve_multi)(ifnet_t ifp,
 437                                                                          const struct sockaddr *proto_addr,
 438                                                                          struct sockaddr_dl *out_ll, size_t ll_len);
 439
 440 /*!
 441         @typedef proto_media_send_arp
 442         @discussion proto_media_send_arp is called by the stack to generate
 443                 an ARP packet. This field is currently only used with IP. This
 444                 function should inspect the parameters and transmit an arp
 445                 packet using the information passed in.
 446         @param ifp The interface the arp packet should be sent on.
 447         @param protocol_family The protocol family of the addresses
 448                 (PF_INET).
 449         @param arpop The arp operation (usually ARPOP_REQUEST or
 450                 ARPOP_REPLY).
 451         @param sender_hw The value to use for the sender hardware
 452                 address field. If this is NULL, use the hardware address
 453                 of the interface.
 454         @param sender_proto The value to use for the sender protocol
 455                 address field. This will not be NULL.
 456         @param target_hw The value to use for the target hardware address.
 457                 If this is NULL, the target hardware address in the ARP packet
 458                 should be NULL and the link-layer destination for the back
 459                 should be a broadcast. If this is not NULL, this value should be
 460                 used for both the link-layer destination and the target hardware
 461                 address.
 462         @param target_proto The target protocol address. This will not be
 463                 NULL.
 464         @result Return zero on success or an errno error value on failure.
 465  */
 466 typedef errno_t (*proto_media_send_arp)(ifnet_t ifp,
 467                                         u_short arpop,
 468                                         const struct sockaddr_dl* sender_hw,
 469                                         const struct sockaddr* sender_proto,
 470                                         const struct sockaddr_dl* target_hw,
 471                                         const struct sockaddr* target_proto);
 472
 473 /*!
 474         @struct ifnet_stat_increment_param
 475         @discussion This structure is used increment the counters on a
 476                 network interface.
 477         @field packets_in The number of packets received.
 478         @field bytes_in The number of bytes received.
 479         @field errors_in The number of receive errors.
 480         @field packets_out The number of packets transmitted.
 481         @field bytes_out The number of bytes transmitted.
 482         @field errors_out The number of transmission errors.
 483         @field collisions The number of collisions seen by this interface.
 484         @field dropped The number of packets dropped.
 485 */
 486
 487 struct ifnet_stat_increment_param {
 488         u_int32_t                               packets_in;
 489         u_int32_t                               bytes_in;
 490         u_int32_t                               errors_in;
 491
 492         u_int32_t                               packets_out;
 493         u_int32_t                               bytes_out;
 494         u_int32_t                               errors_out;
 495
 496         u_int32_t                               collisions;
 497         u_int32_t                               dropped;
 498 };
 499
 500 /*!
 501         @struct ifnet_init_params
 502         @discussion This structure is used to define various properties of
 503                 the interface when calling ifnet_init. A copy of these values
 504                 will be stored in the ifnet and can not be modified while the
 505                 interface is attached.
 506         @field uniqueid An identifier unique to this instance of the
 507                 interface.
 508         @field uniqueid_len The length, in bytes, of the uniqueid.
 509         @field name The interface name (i.e. en).
 510         @field unit The interface unit number (en0's unit number is 0).
 511         @field family The interface family.
 512         @field type The interface type (see sys/if_types.h). Must be less
 513                 than 256. For new types, use IFT_OTHER.
 514         @field output The output function for the interface. Every packet the
 515                 stack attempts to send through this interface will go out through
 516                 this function.
 517         @field demux The function used to determine the protocol family of an
 518                 incoming packet.
 519         @field add_proto The function used to attach a protocol to this interface.
 520         @field del_proto The function used to remove a protocol from this interface.
 521         @field framer The function used to frame outbound packets, may be NULL.
 522         @field softc Driver specific storage. This value can be retrieved from the
 523                 ifnet using the ifnet_softc function.
 524         @field ioctl The function used to handle ioctls.
 525         @field set_bpf_tap The function used to set the bpf_tap function.
 526         @field detach The function called to let the driver know the interface has been detached.
 527         @field event The function to notify the interface of various interface specific kernel events.
 528         @field broadcast_addr The link-layer broadcast address for this interface.
 529         @field broadcast_len The length of the link-layer broadcast address.
 530 */
 531
 532 struct ifnet_init_params {
 533         /* used to match recycled interface */
 534         const void*                             uniqueid;               /* optional */
 535         u_int32_t                               uniqueid_len;   /* optional */
 536
 537         /* used to fill out initial values for interface */
 538         const char*                             name;                   /* required */
 539         u_int32_t                               unit;                   /* required */
 540         ifnet_family_t                  family;                 /* required */
 541         u_int32_t                               type;                   /* required */
 542         ifnet_output_func               output;                 /* required */
 543         ifnet_demux_func                demux;                  /* required  */
 544         ifnet_add_proto_func    add_proto;              /* required  */
 545         ifnet_del_proto_func    del_proto;              /* required  */
 546         ifnet_check_multi               check_multi;    /* required for non point-to-point interfaces */
 547         ifnet_framer_func               framer;                 /* optional */
 548         void*                                   softc;                  /* optional */
 549         ifnet_ioctl_func                ioctl;                  /* optional */
 550         ifnet_set_bpf_tap               set_bpf_tap;    /* optional */
 551         ifnet_detached_func             detach;                 /* optional */
 552         ifnet_event_func                event;                  /* optional */
 553         const void                              *broadcast_addr;/* required for non point-to-point interfaces */
 554         u_int32_t                               broadcast_len;  /* required for non point-to-point interfaces */
 555 };
 556
 557 /*!
 558         @struct ifnet_stats_param
 559         @discussion This structure is used get and set the interface
 560                 statistics.
 561         @field packets_in The number of packets received.
 562         @field bytes_in The number of bytes received.
 563         @field errors_in The number of receive errors.
 564         @field packets_out The number of packets transmitted.
 565         @field bytes_out The number of bytes transmitted.
 566         @field errors_out The number of transmission errors.
 567         @field collisions The number of collisions seen by this interface.
 568         @field dropped The number of packets dropped.
 569 */
 570
 571 struct ifnet_stats_param {
 572         u_int64_t       packets_in;
 573         u_int64_t       bytes_in;
 574         u_int64_t       multicasts_in;
 575         u_int64_t       errors_in;
 576
 577         u_int64_t       packets_out;
 578         u_int64_t       bytes_out;
 579         u_int64_t       multicasts_out;
 580         u_int64_t       errors_out;
 581
 582         u_int64_t       collisions;
 583         u_int64_t       dropped;
 584         u_int64_t       no_protocol;
 585 };
 586
 587 /*!
 588         @struct ifnet_demux_desc
 589         @discussion This structure is to identify packets that belong to a
 590                 specific protocol. The types supported are interface specific.
 591                 Ethernet supports ETHER_DESC_ETYPE2, ETHER_DESC_SAP, and
 592                 ETHER_DESC_SNAP. The type defines the offset in the packet where
 593                 the data will be matched as well as context. For example, if
 594                 ETHER_DESC_SNAP is specified, the only valid datalen is 5 and
 595                 only in the 5 bytes will only be matched when the packet header
 596                 indicates that the packet is a SNAP packet.
 597         @field type The type of identifier data (i.e. ETHER_DESC_ETYPE2)
 598         @field data A pointer to an entry of type (i.e. pointer to 0x0800).
 599         @field datalen The number of bytes of data used to describe the
 600                 packet.
 601 */
 602
 603 struct ifnet_demux_desc {
 604         u_int32_t       type;
 605         void*           data;
 606         u_int32_t       datalen;
 607 };
 608
 609 /*!
 610         @struct ifnet_attach_proto_param
 611         @discussion This structure is used to attach a protocol to an
 612                 interface. This structure provides the various functions for
 613                 handling operations related to the protocol on the interface as
 614                 well as information for how to demux packets for this protocol.
 615         @field demux_array An array of ifnet_demux_desc structures
 616                 describing the protocol.
 617         @field demux_count The number of entries in the demux_array array.
 618         @field input The function to be called for inbound packets.
 619         @field pre_output The function to be called for outbound packets.
 620         @field event The function to be called for interface events.
 621         @field ioctl The function to be called for ioctls.
 622         @field detached The function to be called for handling the detach.
 623 */
 624 #ifdef KERNEL_PRIVATE
 625 #define demux_list demux_array
 626 #endif /* KERNEL_PRIVATE */
 627
 628 struct ifnet_attach_proto_param {
 629         struct ifnet_demux_desc *demux_array;   /* interface may/may not require */
 630         u_int32_t                               demux_count;    /* interface may/may not require */
 631
 632         proto_media_input                       input;          /* required */
 633         proto_media_preout                      pre_output;     /* required */
 634         proto_media_event                       event;          /* optional */
 635         proto_media_ioctl                       ioctl;          /* optional */
 636         proto_media_detached            detached;       /* optional */
 637         proto_media_resolve_multi       resolve;        /* optional */
 638         proto_media_send_arp            send_arp;       /* optional */
 639 };
 640
 641 __BEGIN_DECLS
 642
 643 /*
 644  * Ifnet creation and reference counting
 645  */
 646
 647 /*!
 648         @function ifnet_allocate
 649         @discussion Allocate an ifnet_t with an initial refcount of 1. Many
 650                 parts of the stack do not properly refcount the ifnet_t. In
 651                 order to avoid freeing the ifnet_t while some parts of the stack
 652                 may contain a reference to it, the ifnet_ts are only recycled,
 653                 never freed. A unique id is used to try and recycle the same
 654                 ifnet_t when allocating an interface. For example, for an
 655                 ethernet interface, the hardware address of the ethernet card is
 656                 usually used for the uniqueid. If a PC Card is removed and
 657                 inserted again, if the ethernet address of the PC card is used,
 658                 the same ifnet_t will be used for the card the second time it is
 659                 inserted. In the future, when the ifnet_t is correctly
 660                 refcounted by all of the stack, the interfaces may be freed and
 661                 the unique ids ignored.
 662         @param init The initial values for the interface. These values can
 663                 not be changed after the interface has been allocated.
 664         @param interface The interface allocated upon success.
 665         @result May return ENOMEM if there is insufficient memory or EEXIST
 666                 if an interface with the same uniqueid and family has already
 667                 been allocated and is in use.
 668  */
 669 errno_t ifnet_allocate(const struct ifnet_init_params *init, ifnet_t *interface);
 670
 671 /*!
 672         @function ifnet_reference
 673         @discussion Increment the reference count of the ifnet to assure
 674                 that it will not go away. The interface must already have at
 675                 least one reference.
 676         @param interface The interface to increment the reference count of.
 677         @result May return EINVAL if the interface is not valid.
 678  */
 679 errno_t ifnet_reference(ifnet_t interface);
 680
 681 /*!
 682         @function ifnet_release
 683         @discussion Release a reference of the ifnet, this may trigger a
 684                 free if the reference count reaches 0.
 685         @param interface The interface to decrement the reference count of
 686                 and possibly free.
 687         @result May return EINVAL if the interface is not valid.
 688  */
 689 errno_t ifnet_release(ifnet_t interface);
 690
 691 /*!
 692         @function ifnet_attach
 693         @discussion Attaches an interface to the global interface list. The
 694                 interface must be setup properly before calling attach. The
 695                 stack will take a reference on the interface and hold it until
 696                 ifnet_detach is called.
 697
 698                 This function is intended to be called by the driver. A kext
 699                 must not call this function on an interface the kext does not
 700                 own.
 701         @param interface The interface to attach.
 702         @param ll_addr The link layer address of the interface. This is used
 703                 to fill out the first ifaddr in the list of addresses for the
 704                 interface. This parameter is not required for interfaces such as
 705                 PPP that have no link-layer address.
 706         @result Will return an error if there is anything wrong with the
 707                 interface.
 708  */
 709 errno_t ifnet_attach(ifnet_t interface, const struct sockaddr_dl *ll_addr);
 710
 711 /*!
 712         @function ifnet_detach
 713         @discussion Detaches the interface.
 714
 715                 Call this to indicate this interface is no longer valid (i.e. PC
 716                 Card was removed). This function will begin the process of
 717                 removing knowledge of this interface from the stack.
 718
 719                 The function will return before the interface is detached. The
 720                 functions you supplied in to the interface may continue to be
 721                 called. When the detach has been completed, your detached
 722                 function will be called. Your kext must not unload until the
 723                 detached function has been called. The interface will be
 724                 properly freed when the reference count reaches zero.
 725
 726                 An interface may not be attached again. You must call
 727                 ifnet_allocate to create a new interface to attach.
 728
 729                 This function is intended to be called by the driver. A kext
 730                 must not call this function on an interface the kext does not
 731                 own.
 732         @param interface The interface to detach.
 733         @result 0 on success, otherwise errno error.
 734  */
 735 errno_t ifnet_detach(ifnet_t interface);
 736
 737 /*
 738  * Interface manipulation.
 739  */
 740
 741 /*!
 742         @function ifnet_softc
 743         @discussion Returns the driver's private storage on the interface.
 744         @param interface Interface to retrieve the storage from.
 745         @result Driver's private storage.
 746  */
 747 void* ifnet_softc(ifnet_t interface);
 748
 749 /*!
 750         @function ifnet_name
 751         @discussion Returns a pointer to the name of the interface.
 752         @param interface Interface to retrieve the name from.
 753         @result Pointer to the name.
 754  */
 755 const char* ifnet_name(ifnet_t interface);
 756
 757 /*!
 758         @function ifnet_family
 759         @discussion Returns the family of the interface.
 760         @param interface Interface to retrieve the unit number from.
 761         @result Unit number.
 762  */
 763 ifnet_family_t ifnet_family(ifnet_t interface);
 764
 765 /*!
 766         @function ifnet_unit
 767         @discussion Returns the unit number of the interface.
 768         @param interface Interface to retrieve the unit number from.
 769         @result Unit number.
 770  */
 771 u_int32_t ifnet_unit(ifnet_t interface);
 772
 773 /*!
 774         @function ifnet_index
 775         @discussion Returns the index of the interface. This index value
 776                 will match the index you would find in a sockaddr_dl or using
 777                 if_nametoindex or if_indextoname in user space. The value of the
 778                 interface index is undefined for an interface that is not
 779                 currently attached.
 780         @param interface Interface to retrieve the index of.
 781         @result Index.
 782  */
 783 u_int32_t ifnet_index(ifnet_t interface);
 784
 785 /*!
 786         @function ifnet_set_flags
 787         @discussion Sets the interface flags to match new_flags.
 788         @discussion Sets the interface flags to new_flags. This function
 789                 lets you specify which flags you want to change using the mask.
 790                 The kernel will effectively take the lock, then set the
 791                 interface's flags to (if_flags & ~mask) | (new_flags & mask).
 792         @param interface Interface to set the flags on.
 793         @param new_flags The new set of flags that should be set. These
 794                 flags are defined in net/if.h
 795         @result 0 on success otherwise the errno error.
 796  */
 797 errno_t ifnet_set_flags(ifnet_t interface, u_int16_t new_flags, u_int16_t mask);
 798
 799 /*!
 800         @function ifnet_flags
 801         @discussion Returns the interface flags that are set.
 802         @param interface Interface to retrieve the flags from.
 803         @result Flags. These flags are defined in net/if.h
 804  */
 805 u_int16_t ifnet_flags(ifnet_t interface);
 806
 807
 808 #ifdef KERNEL_PRIVATE
 809 /*!
 810         @function ifnet_set_eflags
 811         @discussion Sets the extended interface flags to new_flags. This
 812                 function lets you specify which flags you want to change using
 813                 the mask. The kernel will effectively take the lock, then set
 814                 the interface's extended flags to (if_eflags & ~mask) |
 815                 (new_flags & mask).
 816         @param interface The interface.
 817         @param new_flags The new set of flags that should be set. These
 818                 flags are defined in net/if.h
 819         @param mask The mask of flags to be modified.
 820         @result 0 on success otherwise the errno error.
 821  */
 822 errno_t ifnet_set_eflags(ifnet_t interface, u_int32_t new_flags, u_int32_t mask);
 823
 824 /*!
 825         @function ifnet_eflags
 826         @discussion Returns the extended interface flags that are set.
 827         @param interface Interface to retrieve the flags from.
 828         @result Extended flags. These flags are defined in net/if.h
 829  */
 830 u_int32_t ifnet_eflags(ifnet_t interface);
 831 #endif
 832
 833 /*!
 834         @function ifnet_set_offload
 835         @discussion Sets a bitfield to indicate special hardware offload
 836                 support provided by the interface such as hardware checksums and
 837                 VLAN. This replaces the if_hwassist flags field. Any flags
 838                 unrecognized by the stack will not be set.
 839         @param interface The interface.
 840         @param offload The new set of flags indicating which offload options
 841                 the device supports.
 842         @param mask The mask of flags to be modified.
 843         @result 0 on success otherwise the errno error.
 844  */
 845 errno_t ifnet_set_offload(ifnet_t interface, ifnet_offload_t offload);
 846
 847 /*!
 848         @function ifnet_offload
 849         @discussion Returns flags indicating which operations can be
 850                 offloaded to the interface.
 851         @param interface Interface to retrieve the offload from.
 852         @result Abilities flags, see ifnet_offload_t.
 853  */
 854 ifnet_offload_t ifnet_offload(ifnet_t interface);
 855
 856 /*!
 857         @function ifnet_set_link_mib_data
 858         @discussion Sets the mib link data. The ifnet_t will store the
 859                 pointer you supply and copy mibLen bytes from the pointer
 860                 whenever the sysctl for getting interface specific MIB data is
 861                 used. Since the ifnet_t stores a pointer to your data instead of
 862                 a copy, you may update the data at the address at any time.
 863
 864                 This function is intended to be called by the driver. A kext
 865                 must not call this function on an interface the kext does not
 866                 own.
 867         @param interface Interface to set the unit number of.
 868         @param mibData A pointer to the data.
 869         @param mibLen Length of data pointed to.
 870         @result 0 on success otherwise the errno error.
 871  */
 872 errno_t ifnet_set_link_mib_data(ifnet_t interface, void *mibData, u_int32_t mibLen);
 873
 874 /*!
 875         @function ifnet_get_link_mib_data
 876         @discussion Copies the link MIB data in to mibData, up to mibLen
 877                 bytes. Returns error if the buffer is too small to hold all of
 878                 the MIB data.
 879         @param interface The interface.
 880         @param mibData A pointer to space for the mibData to be copied in
 881                 to.
 882         @param mibLen When calling, this should be the size of the buffer
 883                 passed in mibData. Upon return, this will be the size of data
 884                 copied in to mibData.
 885         @result Returns an error if the buffer size is too small or there is
 886                 no data.
 887  */
 888 errno_t ifnet_get_link_mib_data(ifnet_t interface, void *mibData, u_int32_t *mibLen);
 889
 890 /*!
 891         @function ifnet_get_link_mib_data_length
 892         @discussion Retrieve the size of the mib data.
 893         @param interface The interface.
 894         @result Returns the number of bytes of mib data associated with the
 895                 interface.
 896  */
 897 u_int32_t ifnet_get_link_mib_data_length(ifnet_t interface);
 898
 899 /*!
 900         @function ifnet_attach_protocol
 901         @discussion Attaches a protocol to an interface.
 902         @param interface The interface.
 903         @param protocol_family The protocol family being attached
 904                 (PF_INET/PF_APPLETALK/etc...).
 905         @param proto_details Details of the protocol being attached.
 906         @result 0 on success otherwise the errno error.
 907  */
 908 errno_t ifnet_attach_protocol(ifnet_t interface, protocol_family_t protocol_family,
 909                         const struct ifnet_attach_proto_param *proto_details);
 910
 911 /*!
 912         @function ifnet_detach_protocol
 913         @discussion Detaches a protocol from an interface.
 914         @param interface The interface.
 915         @param protocol_family The protocol family of the protocol to
 916                 detach.
 917         @result 0 on success otherwise the errno error.
 918  */
 919 errno_t ifnet_detach_protocol(ifnet_t interface, protocol_family_t protocol_family);
 920
 921 /*!
 922         @function ifnet_output
 923         @discussion Handles an outbound packet on the interface by calling
 924                 any filters, a protocol preoutput function, the interface framer
 925                 function, and finally the interface's output function. The
 926                 protocol_family will be used to apply protocol filters and
 927                 determine which preoutput function to call. The route and dest
 928                 parameters will be passed to the preoutput function defined for
 929                 the attachment of the specified protocol to the specified
 930                 interface. ifnet_output will free the mbuf chain in the event of
 931                 an error.
 932         @param interface The interface.
 933         @param protocol_family The family of the protocol generating this
 934                 packet (i.e. AF_INET).
 935         @param packet The packet to be transmitted.
 936         @param route A pointer to a routing structure for this packet. The
 937                 preoutput function determines whether this value may be NULL or
 938                 not.
 939         @param dest The destination address of protocol_family type. This
 940                 will be passed to the preoutput function. If the preoutput
 941                 function does not require this value, you may pass NULL.
 942         @result 0 on success otherwise the errno error.
 943  */
 944 errno_t ifnet_output(ifnet_t interface, protocol_family_t protocol_family, mbuf_t packet,
 945                                         void* route, const struct sockaddr *dest);
 946
 947 /*!
 948         @function ifnet_output_raw
 949         @discussion Handles and outbond raw packet on the interface by
 950                 calling any filters followed by the interface's output function.
 951                 protocol_family may be zero. If the packet is from a specific
 952                 protocol the protocol_family will be used to apply protocol
 953                 filters. All interface filters will be applied to the outgoing
 954                 packet. Processing, such as calling the protocol preoutput and
 955                 interface framer functions will be bypassed. The packet will
 956                 pass through the filters and be sent on the interface as is.
 957                 ifnet_output_raw will free the packet chain in the event of an
 958                 error.
 959         @param interface The interface.
 960         @param protocol_family The family of the protocol generating this
 961                 packet (i.e. AF_INET).
 962         @param packet The fully formed packet to be transmitted.
 963         @result 0 on success otherwise the errno error.
 964  */
 965 errno_t ifnet_output_raw(ifnet_t interface, protocol_family_t protocol_family, mbuf_t packet);
 966
 967 /*!
 968         @function ifnet_input
 969         @discussion Inputs packets from the interface. The interface's demux
 970                 will be called to determine the protocol. Once the protocol is
 971                 determined, the interface filters and protocol filters will be
 972                 called. From there, the packet will be passed to the registered
 973                 protocol. If there is an error, the mbuf chain will be freed.
 974         @param interface The interface.
 975         @param first_packet The first packet in a chain of packets.
 976         @param stats Counts to be integrated in to the stats. The interface
 977                 statistics will be incremented by the amounts specified in
 978                 stats. This parameter may be NULL.
 979         @result 0 on success otherwise the errno error.
 980  */
 981 errno_t ifnet_input(ifnet_t interface, mbuf_t first_packet,
 982                                         const struct ifnet_stat_increment_param *stats);
 983
 984 /*!
 985         @function ifnet_ioctl
 986         @discussion Calls the interface's ioctl function with the parameters
 987                 passed.
 988         @param interface The interface.
 989         @param protocol The protocol family of the protocol to send the
 990                 ioctl to (may be zero). Some ioctls apply to a protocol while
 991                 other ioctls apply to just an interface.
 992         @param ioctl_code The ioctl to perform.
 993         @param ioctl_arg Any parameters to the ioctl.
 994         @result 0 on success otherwise the errno error.
 995  */
 996 errno_t ifnet_ioctl(ifnet_t interface, protocol_family_t protocol,
 997                                         u_int32_t ioctl_code, void *ioctl_arg);
 998
 999 /*!
1000         @function ifnet_event
1001         @discussion Calls the interface's event function.
1002         @param interface The interface.
1003         @param event_ptr Pointer to an kern_event structure describing the
1004                 event.
1005         @result 0 on success otherwise the errno error.
1006  */
1007 errno_t ifnet_event(ifnet_t interface, struct kern_event_msg* event_ptr);
1008
1009 /*!
1010         @function ifnet_set_mtu
1011         @discussion Sets the value of the MTU in the interface structure.
1012                 Calling this function will not notify the driver that the MTU
1013                 should be changed. Use the appropriate ioctl.
1014
1015                 This function is intended to be called by the driver. A kext
1016                 must not call this function on an interface the kext does not
1017                 own.
1018         @param interface The interface.
1019         @param mtu The new MTU.
1020         @result 0 on success otherwise the errno error.
1021  */
1022 errno_t ifnet_set_mtu(ifnet_t interface, u_int32_t mtu);
1023
1024 /*!
1025         @function ifnet_mtu
1026         @param interface The interface.
1027         @result The MTU.
1028  */
1029 u_int32_t       ifnet_mtu(ifnet_t interface);
1030
1031 /*!
1032         @function ifnet_type
1033         @param interface The interface.
1034         @result The type. See net/if_types.h.
1035  */
1036 u_int8_t        ifnet_type(ifnet_t interface);
1037
1038 /*!
1039         @function ifnet_set_addrlen
1040         @discussion
1041                 This function is intended to be called by the driver. A kext
1042                 must not call this function on an interface the kext does not
1043                 own.
1044         @param interface The interface.
1045         @param addrlen The new address length.
1046         @result 0 on success otherwise the errno error.
1047  */
1048 errno_t         ifnet_set_addrlen(ifnet_t interface, u_int8_t addrlen);
1049
1050 /*!
1051         @function ifnet_addrlen
1052         @param interface The interface.
1053         @result The address length.
1054  */
1055 u_int8_t        ifnet_addrlen(ifnet_t interface);
1056
1057 /*!
1058         @function ifnet_set_hdrlen
1059         @discussion
1060                 This function is intended to be called by the driver. A kext
1061                 must not call this function on an interface the kext does not
1062                 own.
1063         @param interface The interface.
1064         @param hdrlen The new header length.
1065         @result 0 on success otherwise the errno error.
1066  */
1067 errno_t         ifnet_set_hdrlen(ifnet_t interface, u_int8_t hdrlen);
1068
1069 /*!
1070         @function ifnet_hdrlen
1071         @param interface The interface.
1072         @result The header length.
1073  */
1074 u_int8_t        ifnet_hdrlen(ifnet_t interface);
1075
1076 /*!
1077         @function ifnet_set_metric
1078         @discussion
1079                 This function is intended to be called by the driver. A kext
1080                 must not call this function on an interface the kext does not
1081                 own.
1082         @param interface The interface.
1083         @param metric The new metric.
1084         @result 0 on success otherwise the errno error.
1085  */
1086 errno_t         ifnet_set_metric(ifnet_t interface, u_int32_t metric);
1087
1088 /*!
1089         @function ifnet_metric
1090         @param interface The interface.
1091         @result The metric.
1092  */
1093 u_int32_t       ifnet_metric(ifnet_t interface);
1094
1095 /*!
1096         @function ifnet_set_baudrate
1097         @discussion
1098                 This function is intended to be called by the driver. A kext
1099                 must not call this function on an interface the kext does not
1100                 own.
1101         @param interface The interface.
1102         @param baudrate The new baudrate.
1103         @result 0 on success otherwise the errno error.
1104  */
1105 errno_t         ifnet_set_baudrate(ifnet_t interface, u_int64_t baudrate);
1106
1107 /*!
1108         @function ifnet_baudrate
1109         @param interface The interface.
1110         @result The baudrate.
1111  */
1112 u_int64_t       ifnet_baudrate(ifnet_t interface);
1113
1114 /*!
1115         @function ifnet_stat_increment
1116         @discussion
1117                 This function is intended to be called by the driver. A kext
1118                 must not call this function on an interface the kext does not
1119                 own.
1120         @param interface The interface.
1121         @param counts A pointer to a structure containing the amount to
1122                 increment each counter by. Any counts not appearing in the
1123                 ifnet_counter_increment structure are handled in the stack.
1124         @result 0 on success otherwise the errno error.
1125  */
1126 errno_t         ifnet_stat_increment(ifnet_t interface,
1127                                 const struct ifnet_stat_increment_param *counts);
1128
1129 /*!
1130         @function ifnet_stat_increment_in
1131         @discussion
1132                 This function is intended to be called by the driver. This
1133                 function allows a driver to update the inbound interface counts.
1134                 The most efficient time to update these counts is when calling
1135                 ifnet_input.
1136
1137                 A lock protects the counts, this makes the increment functions
1138                 expensive. The increment function will update the lastchanged
1139                 value.
1140         @param interface The interface.
1141         @param packets_in The number of additional packets received.
1142         @param bytes_in The number of additional bytes received.
1143         @param errors_in The number of additional receive errors.
1144         @result 0 on success otherwise the errno error.
1145  */
1146 errno_t         ifnet_stat_increment_in(ifnet_t interface,
1147                                 u_int32_t packets_in, u_int32_t bytes_in,
1148                                 u_int32_t errors_in);
1149
1150 /*!
1151         @function ifnet_stat_increment_out
1152         @discussion
1153                 This function is intended to be called by the driver. This
1154                 function allows a driver to update the outbound interface counts.
1155
1156                 A lock protects the counts, this makes the increment functions
1157                 expensive. The increment function will update the lastchanged
1158                 value.
1159         @param interface The interface.
1160         @param packets_out The number of additional packets sent.
1161         @param bytes_out The number of additional bytes sent.
1162         @param errors_out The number of additional send errors.
1163         @result 0 on success otherwise the errno error.
1164  */
1165 errno_t         ifnet_stat_increment_out(ifnet_t interface,
1166                                 u_int32_t packets_out, u_int32_t bytes_out,
1167                                 u_int32_t errors_out);
1168
1169 /*!
1170         @function ifnet_set_stat
1171         @discussion
1172                 This function is intended to be called by the driver. A kext
1173                 must not call this function on an interface the kext does not
1174                 own.
1175
1176                 The one exception would be the case where a kext wants to zero
1177                 all of the counters.
1178         @param interface The interface.
1179         @param counts The new stats values.
1180         @result 0 on success otherwise the errno error.
1181  */
1182 errno_t         ifnet_set_stat(ifnet_t interface,
1183                                 const struct ifnet_stats_param *stats);
1184
1185 /*!
1186         @function ifnet_stat
1187         @param interface The interface.
1188         @param out_stats Storage for the values.
1189         @result 0 on success otherwise the errno error.
1190  */
1191 errno_t         ifnet_stat(ifnet_t interface,
1192                                 struct ifnet_stats_param *out_stats);
1193
1194 /*!
1195         @function ifnet_set_promiscuous
1196         @discussion Enable or disable promiscuous mode on the interface. The
1197                 interface keeps an internal count of the number of times
1198                 promiscuous mode has been enabled. Promiscuous mode is only
1199                 disabled when this count reaches zero. Be sure to disable
1200                 promiscuous mode only once for every time you enable it.
1201         @param interface The interface to toggle promiscuous mode on.
1202         @param on If set, the number of promicuous on requests will be
1203                 incremented. If this is the first requrest, promiscuous mode
1204                 will be enabled. If this is not set, the number of promiscous
1205                 clients will be decremented. If this causes the number to reach
1206                 zero, promiscuous mode will be disabled.
1207         @result 0 on success otherwise the errno error.
1208  */
1209 errno_t         ifnet_set_promiscuous(ifnet_t interface, int on);
1210
1211 /*!
1212         @function ifnet_touch_lastchange
1213         @discussion Updates the lastchange value to now.
1214         @param interface The interface.
1215         @result 0 on success otherwise the errno error.
1216  */
1217 errno_t         ifnet_touch_lastchange(ifnet_t interface);
1218
1219 /*!
1220         @function ifnet_lastchange
1221         @param interface The interface.
1222         @param last_change A timeval struct to copy the last time changed in
1223                 to.
1224  */
1225 errno_t         ifnet_lastchange(ifnet_t interface, struct timeval *last_change);
1226
1227 /*!
1228         @function ifnet_get_address_list
1229         @discussion Get a list of addresses on the interface. Passing NULL
1230                 for the interface will return a list of all addresses. The
1231                 addresses will have their reference count bumped so they will
1232                 not go away. Calling ifnet_free_address_list will decrement the
1233                 refcount and free the array. If you wish to hold on to a
1234                 reference to an ifaddr_t, be sure to bump the reference count
1235                 before calling ifnet_free_address_list.
1236         @param interface The interface.
1237         @param addresses A pointer to a NULL terminated array of ifaddr_ts.
1238         @result 0 on success otherwise the errno error.
1239  */
1240 errno_t ifnet_get_address_list(ifnet_t interface, ifaddr_t **addresses);
1241
1242 /*!
1243         @function ifnet_get_address_list_family
1244         @discussion Get a list of addresses on the interface. Passing NULL
1245                 for the interface will return a list of all addresses. The
1246                 addresses will have their reference count bumped so they will
1247                 not go away. Calling ifnet_free_address_list will decrement the
1248                 refcount and free the array. If you wish to hold on to a
1249                 reference to an ifaddr_t, be sure to bump the reference count
1250                 before calling ifnet_free_address_list. Unlike
1251                 ifnet_get_address_list, this function lets the caller specify
1252                 the address family to get a list of only a specific address type.
1253         @param interface The interface.
1254         @param addresses A pointer to a NULL terminated array of ifaddr_ts.
1255         @result 0 on success otherwise the errno error.
1256  */
1257 errno_t ifnet_get_address_list_family(ifnet_t interface, ifaddr_t **addresses, sa_family_t family);
1258
1259 /*!
1260         @function ifnet_free_address_list
1261         @discussion Free a list of addresses returned from
1262                 ifnet_get_address_list. Decrements the refcounts and frees the
1263                 memory used for the array of references.
1264         @param addresses An array of ifaddr_ts.
1265  */
1266 void ifnet_free_address_list(ifaddr_t *addresses);
1267
1268 /*!
1269         @function ifnet_set_lladdr
1270         @discussion Sets the link-layer address for this interface.
1271         @param interface The interface the link layer address is being
1272                 changed on.
1273         @param lladdr A pointer to the raw link layer address (pointer to
1274                 the 6 byte ethernet address for ethernet).
1275         @param lladdr_len The length, in bytes, of the link layer address.
1276  */
1277 errno_t ifnet_set_lladdr(ifnet_t interface, const void* lladdr, size_t lladdr_len);
1278
1279 /*!
1280         @function ifnet_lladdr_copy_bytes
1281         @discussion Copies the bytes of the link-layer address in to the
1282                 specified buffer.
1283         @param interface The interface to copy the link-layer address from.
1284         @param lladdr The buffer to copy the link-layer address in to.
1285         @param length The length of the buffer. This value must match the
1286                 length of the link-layer address.
1287  */
1288 errno_t ifnet_lladdr_copy_bytes(ifnet_t interface, void* lladdr, size_t length);
1289
1290 #ifdef KERNEL_PRIVATE
1291 /*!
1292         @function ifnet_lladdr
1293         @discussion Returns a pointer to the link-layer address.
1294         @param interface The interface the link-layer address is on.
1295  */
1296 void* ifnet_lladdr(ifnet_t interface);
1297 #endif KERNEL_PRIVATE
1298
1299 /*!
1300         @function ifnet_llbroadcast_copy_bytes
1301         @discussion Retrieves the link-layer broadcast address for this
1302                 interface.
1303         @param interface The interface.
1304         @param addr A buffer to copy the broadcast address in to.
1305         @param bufferlen The length of the buffer at addr.
1306         @param addr_len On return, the length of the broadcast address.
1307         @param lladdr_len The length, in bytes, of the link layer address.
1308  */
1309 errno_t ifnet_llbroadcast_copy_bytes(ifnet_t interface, void* addr,
1310                                                                          size_t bufferlen, size_t* addr_len);
1311
1312 #ifdef KERNEL_PRIVATE
1313 /*!
1314         @function ifnet_set_lladdr_and_type
1315         @discussion Sets the link-layer address as well as the type field in
1316                 the sockaddr_dl. Support for setting the type was added for vlan
1317                 and bond interfaces.
1318         @param interface The interface the link layer address is being
1319                 changed on.
1320         @param lladdr A pointer to the raw link layer address (pointer to
1321                 the 6 byte ethernet address for ethernet).
1322         @param lladdr_len The length, in bytes, of the link layer address.
1323         @param type The link-layer address type.
1324  */
1325 errno_t ifnet_set_lladdr_and_type(ifnet_t interface, const void* lladdr, size_t length, u_char type);
1326 #endif KERNEL_PRIVATE
1327
1328 /*!
1329         @function ifnet_add_multicast
1330         @discussion Joins a multicast and returns an ifmultiaddr_t with the
1331                 reference count incremented for you. You are responsible for
1332                 decrementing the reference count after calling
1333                 ifnet_remove_multicast and making sure you no longer have any
1334                 references to the multicast.
1335         @param interface The interface.
1336         @param maddr The multicast address to join. Either a physical
1337                 address or logical address to be translated to a physical
1338                 address.
1339         @param multicast The resulting ifmultiaddr_t multicast address.
1340         @result 0 on success otherwise the errno error.
1341  */
1342 errno_t ifnet_add_multicast(ifnet_t interface, const struct sockaddr *maddr,
1343                                                         ifmultiaddr_t *multicast);
1344
1345 /*!
1346         @function ifnet_remove_multicast
1347         @discussion Causes the interface to leave the multicast group. The
1348                 stack keeps track of how many times ifnet_add_multicast has been
1349                 called for a given multicast address. The multicast will only be
1350                 removed when the number of times ifnet_remove_multicast has been
1351                 called matches the number of times ifnet_add_multicast has been
1352                 called.
1353
1354                 The memory for the multicast address is not actually freed until
1355                 the separate reference count has reached zero. Some parts of the
1356                 stack may keep a pointer to the multicast even after that
1357                 multicast has been removed from the interface.
1358
1359                 When an interface is detached, all of the multicasts are
1360                 removed. If the interface of the multicast passed in is no
1361                 longer attached, this function will gracefully return,
1362                 performing no work.
1363
1364                 It is the callers responsibility to release the multicast
1365                 address after calling this function.
1366         @param multicast The multicast to be removed.
1367         @result 0 on success otherwise the errno error.
1368  */
1369 errno_t ifnet_remove_multicast(ifmultiaddr_t multicast);
1370
1371 /*!
1372         @function ifnet_get_multicast_list
1373         @discussion Retrieves a list of multicast address the interface is
1374                 set to receive. This function allocates and returns an array of
1375                 references to the various multicast addresses. The multicasts
1376                 have their reference counts bumped on your behalf. Calling
1377                 ifnet_free_multicast_list will decrement the reference counts
1378                 and free the array.
1379         @param interface The interface.
1380         @param multicasts A pointer to a NULL terminated array of references
1381                 to the multicast addresses.
1382         @result 0 on success otherwise the errno error.
1383  */
1384 errno_t ifnet_get_multicast_list(ifnet_t interface, ifmultiaddr_t **addresses);
1385
1386 /*!
1387         @function ifnet_free_multicast_list
1388         @discussion Frees a list of multicasts returned by
1389                 ifnet_get_multicast_list. Decrements the refcount on each
1390                 multicast address and frees the array.
1391         @param multicasts An array of references to the multicast addresses.
1392         @result 0 on success otherwise the errno error.
1393  */
1394 void ifnet_free_multicast_list(ifmultiaddr_t *multicasts);
1395
1396 /*!
1397         @function ifnet_find_by_name
1398         @discussion Find an interface by the name including the unit number.
1399                 Caller must call ifnet_release on any non-null interface return
1400                 value.
1401         @param name The name of the interface, including any unit number
1402                 (i.e. "en0").
1403         @param interface A pointer to an interface reference. This will be
1404                 filled in if a matching interface is found.
1405         @result 0 on success otherwise the errno error.
1406  */
1407 errno_t ifnet_find_by_name(const char *ifname, ifnet_t *interface);
1408
1409 /*!
1410         @function ifnet_list_get
1411         @discussion Get a list of attached interfaces. List will be set to
1412                 point to an array allocated by ifnet_list_get. The interfaces
1413                 are refcounted and the counts will be incremented before the
1414                 function returns. The list of interfaces must be freed using
1415                 ifnet_list_free.
1416         @param family The interface family (i.e. IFNET_FAMILY_ETHERNET). To
1417                 find interfaces of all families, use IFNET_FAMILY_ANY.
1418         @param interfaces A pointer to an array of interface references.
1419         @param count A pointer that will be filled in with the number of
1420                 matching interfaces in the array.
1421         @result 0 on success otherwise the errno error.
1422  */
1423 errno_t ifnet_list_get(ifnet_family_t family, ifnet_t **interfaces, u_int32_t *count);
1424
1425 /*!
1426         @function ifnet_list_free
1427         @discussion Free a list of interfaces returned by ifnet_list_get.
1428                 Decrements the reference count on each interface and frees the
1429                 array of references. If you keep a reference to an interface, be
1430                 sure to increment the reference count before calling
1431                 ifnet_list_free.
1432         @param interfaces An array of interface references from ifnet_list_get.
1433  */
1434 void ifnet_list_free(ifnet_t *interfaces);
1435
1436 /********************************************************************************************/
1437 /* ifaddr_t accessors                                                                                                                                           */
1438 /********************************************************************************************/
1439
1440 /*!
1441         @function ifaddr_reference
1442         @discussion Increment the reference count of an address tied to an
1443                 interface.
1444         @param ifaddr The interface address.
1445         @result 0 upon success
1446  */
1447 errno_t ifaddr_reference(ifaddr_t ifaddr);
1448
1449 /*!
1450         @function ifaddr_release
1451         @discussion Decrements the reference count of and possibly frees an
1452                 address tied to an interface.
1453         @param ifaddr The interface address.
1454         @result 0 upon success
1455  */
1456 errno_t ifaddr_release(ifaddr_t ifaddr);
1457
1458 /*!
1459         @function ifaddr_address
1460         @discussion Copies the address out of the ifaddr.
1461         @param ifaddr The interface address.
1462         @param out_addr The sockaddr storage for the address.
1463         @param addr_size The size of the storage for the address.
1464         @result 0 upon success
1465  */
1466 errno_t ifaddr_address(ifaddr_t ifaddr, struct sockaddr *out_addr, u_int32_t addr_size);
1467
1468 /*!
1469         @function ifaddr_address
1470         @discussion Returns the address family of the address.
1471         @param ifaddr The interface address.
1472         @result 0 on failure, address family on success.
1473  */
1474 sa_family_t     ifaddr_address_family(ifaddr_t ifaddr);
1475
1476 /*!
1477         @function ifaddr_dstaddress
1478         @discussion Copies the destination address out of the ifaddr.
1479         @param ifaddr The interface address.
1480         @param out_dstaddr The sockaddr storage for the destination address.
1481         @param dstaddr_size The size of the storage for the destination address.
1482         @result 0 upon success
1483  */
1484 errno_t ifaddr_dstaddress(ifaddr_t ifaddr, struct sockaddr *out_dstaddr, u_int32_t dstaddr_size);
1485
1486 /*!
1487         @function ifaddr_netmask
1488         @discussion Copies the netmask out of the ifaddr.
1489         @param ifaddr The interface address.
1490         @param out_netmask The sockaddr storage for the netmask.
1491         @param netmask_size The size of the storage for the netmask.
1492         @result 0 upon success
1493  */
1494 errno_t ifaddr_netmask(ifaddr_t ifaddr, struct sockaddr *out_netmask, u_int32_t netmask_size);
1495
1496 /*!
1497         @function ifaddr_ifnet
1498         @discussion Returns the interface the address is attached to. The
1499                 reference is only valid until the ifaddr is released. If you
1500                 need to hold a reference to the ifnet for longer than you hold a
1501                 reference to the ifaddr, increment the reference using
1502                 ifnet_reference.
1503         @param ifaddr The interface address.
1504         @result A reference to the interface the address is attached to.
1505  */
1506 ifnet_t ifaddr_ifnet(ifaddr_t ifaddr);
1507
1508 /*!
1509         @function ifaddr_withaddr
1510         @discussion Returns an interface address with the address specified.
1511                 Increments the reference count on the ifaddr before returning to
1512                 the caller. Caller is responsible for calling ifaddr_release.
1513         @param address The address to search for.
1514         @result A reference to the interface address.
1515  */
1516 ifaddr_t        ifaddr_withaddr(const struct sockaddr* address);
1517
1518 /*!
1519         @function ifaddr_withdstaddr
1520         @discussion Returns an interface address for the interface address
1521                 that matches the destination when the netmask is applied.
1522                 Increments the reference count on the ifaddr before returning to
1523                 the caller. Caller is responsible for calling ifaddr_release.
1524         @param destination The destination to search for.
1525         @result A reference to the interface address.
1526  */
1527 ifaddr_t        ifaddr_withdstaddr(const struct sockaddr* destination);
1528
1529 /*!
1530         @function ifaddr_withnet
1531         @discussion Returns an interface address for the interface with the
1532                 network described by net. Increments the reference count on the
1533                 ifaddr before returning to the caller. Caller is responsible for
1534                 calling ifaddr_release.
1535         @param net The network to search for.
1536         @result A reference to the interface address.
1537  */
1538 ifaddr_t        ifaddr_withnet(const struct sockaddr* net);
1539
1540 /*!
1541         @function ifaddr_withroute
1542         @discussion Returns an interface address given a destination and
1543                 gateway. Increments the reference count on the ifaddr before
1544                 returning to the caller. Caller is responsible for calling
1545                 ifaddr_release.
1546         @param flags Routing flags. See net/route.h, RTF_GATEWAY etc.
1547         @param destination The destination to search for.
1548         @param gateway A gateway to search for.
1549         @result A reference to the interface address.
1550  */
1551 ifaddr_t        ifaddr_withroute(int flags, const struct sockaddr* destination,
1552                                                          const struct sockaddr* gateway);
1553
1554 /*!
1555         @function ifaddr_findbestforaddr
1556         @discussion Finds the best local address assigned to a specific
1557                 interface to use when communicating with another address.
1558                 Increments the reference count on the ifaddr before returning to
1559                 the caller. Caller is responsible for calling ifaddr_release.
1560         @param addr The remote address.
1561         @param interface The local interface.
1562         @result A reference to the interface address.
1563  */
1564 ifaddr_t        ifaddr_findbestforaddr(const struct sockaddr *addr, ifnet_t interface);
1565
1566 /********************************************************************************************/
1567 /* ifmultiaddr_t accessors                                                                                                                                      */
1568 /********************************************************************************************/
1569
1570 /*!
1571         @function ifmaddr_reference
1572         @discussion Increment the reference count of an interface multicast
1573                 address.
1574         @param ifmaddr The interface multicast address.
1575         @result 0 on success. Only error will be EINVAL if ifmaddr is not valid.
1576  */
1577 errno_t ifmaddr_reference(ifmultiaddr_t ifmaddr);
1578
1579 /*!
1580         @function ifmaddr_release
1581         @discussion Decrement the reference count of an interface multicast
1582                 address. If the reference count reaches zero, the ifmultiaddr
1583                 will be removed from the interface and the ifmultiaddr will be
1584                 freed.
1585         @param ifmaddr The interface multicast address.
1586         @result 0 on success. Only error will be EINVAL if ifmaddr is not valid.
1587  */
1588 errno_t ifmaddr_release(ifmultiaddr_t ifmaddr);
1589
1590 /*!
1591         @function ifmaddr_address
1592         @discussion Copies the multicast address to out_multicast.
1593         @param out_multicast Storage for a sockaddr.
1594         @param addr_size Size of the storage.
1595         @result 0 on success.
1596  */
1597 errno_t ifmaddr_address(ifmultiaddr_t ifmaddr, struct sockaddr *out_multicast, u_int32_t addr_size);
1598
1599 /*!
1600         @function ifmaddr_lladdress
1601         @discussion Copies the link layer multicast address to
1602                 out_link_layer_multicast.
1603         @param out_link_layer_multicast Storage for a sockaddr.
1604         @param addr_size Size of the storage.
1605         @result 0 on success.
1606  */
1607 errno_t ifmaddr_lladdress(ifmultiaddr_t ifmaddr, struct sockaddr *out_link_layer_multicast,
1608                                                   u_int32_t addr_size);
1609
1610 /*!
1611         @function ifmaddr_ifnet
1612         @discussion Returns the interface this multicast address is attached
1613                 to. The interface reference count is not bumped by this
1614                 function. The interface is only valid as long as you don't
1615                 release the refernece to the multiast address. If you need to
1616                 maintain your pointer to the ifnet, call ifnet_reference
1617                 followed by ifnet_release when you're finished.
1618         @param ifmaddr The interface multicast address.
1619         @result A reference to the interface.
1620  */
1621 ifnet_t ifmaddr_ifnet(ifmultiaddr_t ifmaddr);
1622
1623 __END_DECLS
1624
1625 #endif