bsd/net/kpi_interface.h

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