1/* 2 * Copyright (c) 2004-2012 Apple 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 38#ifndef XNU_KERNEL_PRIVATE 39#include <TargetConditionals.h> 40#endif 41 42#include <sys/kernel_types.h> 43 44#ifdef KERNEL_PRIVATE 45#include <sys/kpi_mbuf.h> 46#endif /* KERNEL_PRIVATE */ 47 48#ifndef _SA_FAMILY_T 49#define _SA_FAMILY_T 50typedef __uint8_t sa_family_t; 51#endif 52 53#ifdef XNU_KERNEL_PRIVATE 54#if CONFIG_EMBEDDED 55 #define KPI_INTERFACE_EMBEDDED 1 56#else 57 #define KPI_INTERFACE_EMBEDDED 0 58#endif 59#else 60#if TARGET_OS_EMBEDDED 61 #define KPI_INTERFACE_EMBEDDED 1 62#else 63 #define KPI_INTERFACE_EMBEDDED 0 64#endif 65#endif 66 67struct timeval; 68struct sockaddr; 69struct sockaddr_dl; 70struct kern_event_msg; 71struct kev_msg; 72struct ifnet_demux_desc; 73 74/*! 75 @enum Interface Families 76 @abstract Constants defining interface families. 77 @constant IFNET_FAMILY_ANY Match interface of any family type. 78 @constant IFNET_FAMILY_LOOPBACK A software loopback interface. 79 @constant IFNET_FAMILY_ETHERNET An Ethernet interface. 80 @constant IFNET_FAMILY_SLIP A SLIP interface. 81 @constant IFNET_FAMILY_TUN A tunnel interface. 82 @constant IFNET_FAMILY_VLAN A virtual LAN interface. 83 @constant IFNET_FAMILY_PPP A PPP interface. 84 @constant IFNET_FAMILY_PVC A PVC interface. 85 @constant IFNET_FAMILY_DISC A DISC interface. 86 @constant IFNET_FAMILY_MDECAP A MDECAP interface. 87 @constant IFNET_FAMILY_GIF A generic tunnel interface. 88 @constant IFNET_FAMILY_FAITH A FAITH (IPv4/IPv6 translation) interface. 89 @constant IFNET_FAMILY_STF A 6to4 interface. 90 @constant IFNET_FAMILY_FIREWIRE An IEEE 1394 (firewire) interface. 91 @constant IFNET_FAMILY_BOND A virtual bonded interface. 92 @constant IFNET_FAMILY_CELLULAR A cellular interface. 93*/ 94 95enum { 96 IFNET_FAMILY_ANY = 0, 97 IFNET_FAMILY_LOOPBACK = 1, 98 IFNET_FAMILY_ETHERNET = 2, 99 IFNET_FAMILY_SLIP = 3, 100 IFNET_FAMILY_TUN = 4, 101 IFNET_FAMILY_VLAN = 5, 102 IFNET_FAMILY_PPP = 6, 103 IFNET_FAMILY_PVC = 7, 104 IFNET_FAMILY_DISC = 8, 105 IFNET_FAMILY_MDECAP = 9, 106 IFNET_FAMILY_GIF = 10, 107 IFNET_FAMILY_FAITH = 11, /* deprecated */ 108 IFNET_FAMILY_STF = 12, 109 IFNET_FAMILY_FIREWIRE = 13, 110 IFNET_FAMILY_BOND = 14, 111 IFNET_FAMILY_CELLULAR = 15 112}; 113/*! 114 @typedef ifnet_family_t 115 @abstract Storage type for the interface family. 116*/ 117typedef u_int32_t ifnet_family_t; 118 119#ifndef BPF_TAP_MODE_T 120#define BPF_TAP_MODE_T 121/*! 122 @enum BPF tap mode 123 @abstract Constants defining interface families. 124 @constant BPF_MODE_DISABLED Disable bpf. 125 @constant BPF_MODE_INPUT Enable input only. 126 @constant BPF_MODE_OUTPUT Enable output only. 127 @constant BPF_MODE_INPUT_OUTPUT Enable input and output. 128*/ 129 130enum { 131 BPF_MODE_DISABLED = 0, 132 BPF_MODE_INPUT = 1, 133 BPF_MODE_OUTPUT = 2, 134 BPF_MODE_INPUT_OUTPUT = 3 135}; 136/*! 137 @typedef bpf_tap_mode 138 @abstract Mode for tapping. BPF_MODE_DISABLED/BPF_MODE_INPUT_OUTPUT etc. 139*/ 140typedef u_int32_t bpf_tap_mode; 141#endif /* !BPF_TAP_MODE_T */ 142 143/*! 144 @typedef protocol_family_t 145 @abstract Storage type for the protocol family. 146*/ 147typedef u_int32_t protocol_family_t; 148 149/*! 150 @enum Interface Abilities 151 @abstract Constants defining interface offload support. 152 @constant IFNET_CSUM_IP Hardware will calculate IPv4 checksums. 153 @constant IFNET_CSUM_TCP Hardware will calculate TCP checksums. 154 @constant IFNET_CSUM_UDP Hardware will calculate UDP checksums. 155 @constant IFNET_CSUM_FRAGMENT Hardware will checksum IP fragments. 156 @constant IFNET_IP_FRAGMENT Hardware will fragment IP packets. 157 @constant IFNET_CSUM_TCPIPV6 Hardware will calculate TCP IPv6 checksums. 158 @constant IFNET_CSUM_UDPIPV6 Hardware will calculate UDP IPv6 checksums. 159 @constant IFNET_IPV6_FRAGMENT Hardware will fragment IPv6 packets. 160 @constant IFNET_VLAN_TAGGING Hardware will generate VLAN headers. 161 @constant IFNET_VLAN_MTU Hardware supports VLAN MTU. 162 @constant IFNET_MULTIPAGES Driver is capable of handling packets 163 coming down from the network stack that reside in virtually, 164 but not in physically contiguous span of the external mbuf 165 clusters. In this case, the data area of a packet in the 166 external mbuf cluster might cross one or more physical 167 pages that are disjoint, depending on the interface MTU 168 and the packet size. Such a use of larger than system page 169 size clusters by the network stack is done for better system 170 efficiency. Drivers that utilize the IOMbufNaturalMemoryCursor 171 with the getPhysicalSegmentsWithCoalesce interfaces and 172 enumerate the list of vectors should set this flag for 173 possible gain in performance during bulk data transfer. 174 @constant IFNET_TSO_IPV4 Hardware supports IPv4 TCP Segment Offloading. 175 If the Interface driver sets this flag, TCP will send larger frames (up to 64KB) as one 176 frame to the adapter which will perform the final packetization. The maximum TSO segment 177 supported by the interface can be set with "ifnet_set_tso_mtu". To retreive the real MTU 178 for the TCP connection the function "mbuf_get_tso_requested" is used by the driver. Note 179 that if TSO is active, all the packets will be flagged for TSO, not just large packets. 180 @constant IFNET_TSO_IPV6 Hardware supports IPv6 TCP Segment Offloading. 181 If the Interface driver sets this flag, TCP IPv6 will send larger frames (up to 64KB) as one 182 frame to the adapter which will perform the final packetization. The maximum TSO segment 183 supported by the interface can be set with "ifnet_set_tso_mtu". To retreive the real MTU 184 for the TCP IPv6 connection the function "mbuf_get_tso_requested" is used by the driver. 185 Note that if TSO is active, all the packets will be flagged for TSO, not just large packets. 186 187*/ 188 189enum { 190 IFNET_CSUM_IP = 0x00000001, 191 IFNET_CSUM_TCP = 0x00000002, 192 IFNET_CSUM_UDP = 0x00000004, 193 IFNET_CSUM_FRAGMENT = 0x00000008, 194 IFNET_IP_FRAGMENT = 0x00000010, 195 IFNET_CSUM_TCPIPV6 = 0x00000020, 196 IFNET_CSUM_UDPIPV6 = 0x00000040, 197 IFNET_IPV6_FRAGMENT = 0x00000080, 198#ifdef KERNEL_PRIVATE 199 IFNET_CSUM_SUM16 = 0x00001000, 200#endif /* KERNEL_PRIVATE */ 201 IFNET_VLAN_TAGGING = 0x00010000, 202 IFNET_VLAN_MTU = 0x00020000, 203 IFNET_MULTIPAGES = 0x00100000, 204 IFNET_TSO_IPV4 = 0x00200000, 205 IFNET_TSO_IPV6 = 0x00400000, 206}; 207/*! 208 @typedef ifnet_offload_t 209 @abstract Flags indicating the offload support of the interface. 210*/ 211typedef u_int32_t ifnet_offload_t; 212 213/* 214 * Callbacks 215 * 216 * These are function pointers you supply to the kernel in the interface. 217 */ 218/*! 219 @typedef bpf_packet_func 220 221 @discussion bpf_packet_func The bpf_packet_func is used to intercept 222 inbound and outbound packets. The tap function will never free 223 the mbuf. The tap function will only copy the mbuf in to various 224 bpf file descriptors tapping this interface. 225 @param interface The interface being sent or received on. 226 @param data The packet to be transmitted or received. 227 @result An errno value or zero upon success. 228 */ 229/* Fast path - do not block or spend excessive amounts of time */ 230typedef errno_t (*bpf_packet_func)(ifnet_t interface, mbuf_t data); 231 232/*! 233 @typedef ifnet_output_func 234 235 @discussion ifnet_output_func is used to transmit packets. The stack 236 will pass fully formed packets, including frame header, to the 237 ifnet_output function for an interface. The driver is 238 responsible for freeing the mbuf. 239 @param interface The interface being sent on. 240 @param data The packet to be sent. 241 */ 242/* Fast path - do not block or spend excessive amounts of time */ 243typedef errno_t (*ifnet_output_func)(ifnet_t interface, mbuf_t data); 244 245/*! 246 @typedef ifnet_ioctl_func 247 @discussion ifnet_ioctl_func is used to communicate ioctls from the 248 stack to the driver. 249 250 All undefined ioctls are reserved for future use by Apple. If 251 you need to communicate with your kext using an ioctl, please 252 use SIOCSIFKPI and SIOCGIFKPI. 253 @param interface The interface the ioctl is being sent to. 254 @param proto_family The protocol family to handle the ioctl, may be 255 zero for no protocol_family. 256 @param cmd The ioctl command. 257 @param data A pointer to any data related to the ioctl. 258 */ 259typedef errno_t (*ifnet_ioctl_func)(ifnet_t interface, unsigned long cmd, 260 void *data); 261 262/*! 263 @typedef ifnet_set_bpf_tap 264 @discussion Deprecated. Specify NULL. Call bpf_tap_in/bpf_tap_out 265 for all packets. 266 */ 267typedef errno_t (*ifnet_set_bpf_tap)(ifnet_t interface, bpf_tap_mode mode, 268 bpf_packet_func callback); 269 270/*! 271 @typedef ifnet_detached_func 272 @discussion ifnet_detached_func is called an interface is detached 273 from the list of interfaces. When ifnet_detach is called, it may 274 not detach the interface immediately if protocols are attached. 275 ifnet_detached_func is used to notify the interface that it has 276 been detached from the networking stack. This is the last 277 function that will be called on an interface. Until this 278 function returns, you must not unload a kext supplying function 279 pointers to this interface, even if ifnet_detacah has been 280 called. Your detach function may be called during your call to 281 ifnet_detach. 282 @param interface The interface that has been detached. 283 event. 284 */ 285typedef void (*ifnet_detached_func)(ifnet_t interface); 286 287/*! 288 @typedef ifnet_demux_func 289 @discussion ifnet_demux_func is called for each inbound packet to 290 determine which protocol family the packet belongs to. This 291 information is then used by the stack to determine which 292 protocol to pass the packet to. This function may return 293 protocol families for protocols that are not attached. If the 294 protocol family has not been attached to the interface, the 295 packet will be discarded. 296 @param interface The interface the packet was received on. 297 @param packet The mbuf containing the packet. 298 @param frame_header A pointer to the frame header. 299 @param protocol_family Upon return, the protocol family matching the 300 packet should be stored here. 301 @result 302 If the result is zero, processing will continue normally. 303 If the result is EJUSTRETURN, processing will stop but the 304 packet will not be freed. 305 If the result is anything else, the processing will stop and 306 the packet will be freed. 307 */ 308typedef errno_t (*ifnet_demux_func)(ifnet_t interface, mbuf_t packet, 309 char *frame_header, protocol_family_t *protocol_family); 310 311/*! 312 @typedef ifnet_event_func 313 @discussion ifnet_event_func is called when an event occurs on a 314 specific interface. 315 @param interface The interface the event occurred on. 316 @param event_ptr Pointer to a kern_event structure describing the 317 event. 318 */ 319typedef void (*ifnet_event_func)(ifnet_t interface, const struct kev_msg *msg); 320 321/*! 322 @typedef ifnet_framer_func 323 @discussion ifnet_framer_func is called for each outbound packet to 324 give the interface an opportunity to prepend interface specific 325 headers. 326 @param interface The interface the packet is being sent on. 327 @param packet Pointer to the mbuf containing the packet, caller may 328 set this to a different mbuf upon return. This can happen if the 329 frameout function needs to prepend another mbuf to the chain to 330 have enough space for the header. 331 @param dest The higher layer protocol destination (i.e. IP address). 332 @param dest_linkaddr The link layer address as determined by the 333 protocol's pre-output function. 334 @param frame_type The frame type as determined by the protocol's 335 pre-output function. 336 @param prepend_len The length of prepended bytes to the mbuf. 337 (ONLY used if KPI_INTERFACE_EMBEDDED is defined to 1) 338 @param postpend_len The length of the postpended bytes to the mbuf. 339 (ONLY used if KPI_INTERFACE_EMBEDDED is defined to 1) 340 @result 341 If the result is zero, processing will continue normally. 342 If the result is EJUSTRETURN, processing will stop but the 343 packet will not be freed. 344 If the result is anything else, the processing will stop and 345 the packet will be freed. 346 */ 347typedef errno_t (*ifnet_framer_func)(ifnet_t interface, mbuf_t *packet, 348 const struct sockaddr *dest, const char *desk_linkaddr, const char *frame_type 349#if KPI_INTERFACE_EMBEDDED 350 , u_int32_t *prepend_len, u_int32_t *postpend_len 351#endif /* KPI_INTERFACE_EMBEDDED */ 352 ); 353 354/*! 355 @typedef ifnet_add_proto_func 356 @discussion if_add_proto_func is called by the stack when a protocol 357 is attached to an interface. This gives the interface an 358 opportunity to get a list of protocol description structures 359 for demuxing packets to this protocol (demux descriptors). 360 @param interface The interface the protocol will be attached to. 361 @param protocol_family The family of the protocol being attached. 362 @param demux_array An array of demux descriptors that describe 363 the interface specific ways of identifying packets belonging 364 to this protocol family. 365 @param demux_count The number of demux descriptors in the array. 366 @result 367 If the result is zero, processing will continue normally. 368 If the result is anything else, the add protocol will be 369 aborted. 370 */ 371typedef errno_t (*ifnet_add_proto_func)(ifnet_t interface, 372 protocol_family_t protocol_family, 373 const struct ifnet_demux_desc *demux_array, u_int32_t demux_count); 374 375/*! 376 @typedef if_del_proto_func 377 @discussion if_del_proto_func is called by the stack when a protocol 378 is being detached from an interface. This gives the interface an 379 opportunity to free any storage related to this specific 380 protocol being attached to this interface. 381 @param interface The interface the protocol will be detached from. 382 @param protocol_family The family of the protocol being detached. 383 @result 384 If the result is zero, processing will continue normally. 385 If the result is anything else, the detach will continue 386 and the error will be returned to the caller. 387 */ 388typedef errno_t (*ifnet_del_proto_func)(ifnet_t interface, 389 protocol_family_t protocol_family); 390 391/*! 392 @typedef ifnet_check_multi 393 @discussion ifnet_check_multi is called for each multicast address 394 added to an interface. This gives the interface an opportunity 395 to reject invalid multicast addresses before they are attached 396 to the interface. 397 398 To prevent an address from being added to your multicast list, 399 return EADDRNOTAVAIL. If you don't know how to parse/translate 400 the address, return EOPNOTSUPP. 401 @param The interface. 402 @param mcast The multicast address. 403 @result 404 Zero upon success, EADDRNOTAVAIL on invalid multicast, 405 EOPNOTSUPP for addresses the interface does not understand. 406 */ 407typedef errno_t (*ifnet_check_multi)(ifnet_t interface, 408 const struct sockaddr *mcast); 409 410/*! 411 @typedef proto_media_input 412 @discussion proto_media_input is called for all inbound packets for 413 a specific protocol on a specific interface. This function is 414 registered on an interface using ifnet_attach_protocol. 415 @param ifp The interface the packet was received on. 416 @param protocol_family The protocol of the packet received. 417 @param packet The packet being input. 418 @param header The frame header. 419 @result 420 If the result is zero, the caller will assume the packet was 421 passed to the protocol. 422 If the result is non-zero and not EJUSTRETURN, the caller will 423 free the packet. 424 */ 425typedef errno_t (*proto_media_input)(ifnet_t ifp, protocol_family_t protocol, 426 mbuf_t packet, char *header); 427 428/*! 429 @typedef proto_media_input_v2 430 @discussion proto_media_input_v2 is called for all inbound packets for 431 a specific protocol on a specific interface. This function is 432 registered on an interface using ifnet_attach_protocolv2. 433 proto_media_input_v2 differs from proto_media_input in that it 434 will be called for a list of packets instead of once for each 435 individual packet. The frame header can be retrieved using 436 mbuf_pkthdr_header. 437 @param ifp The interface the packet was received on. 438 @param protocol_family The protocol of the packet received. 439 @param packet The packet being input. 440 @result 441 If the result is zero, the caller will assume the packets were 442 passed to the protocol. 443 If the result is non-zero and not EJUSTRETURN, the caller will 444 free the packets. 445 */ 446typedef errno_t (*proto_media_input_v2)(ifnet_t ifp, protocol_family_t protocol, 447 mbuf_t packet); 448 449/*! 450 @typedef proto_media_preout 451 @discussion proto_media_preout is called just before the packet 452 is transmitted. This gives the proto_media_preout function an 453 opportunity to specify the media specific frame type and 454 destination. 455 @param ifp The interface the packet will be sent on. 456 @param protocol_family The protocol of the packet being sent 457 (PF_INET/etc...). 458 @param packet The packet being sent. 459 @param dest The protocol level destination address. 460 @param route A pointer to the routing structure for the packet. 461 @param frame_type The media specific frame type. 462 @param link_layer_dest The media specific destination. 463 @result 464 If the result is zero, processing will continue normally. If the 465 result is non-zero, processing will stop. If the result is 466 non-zero and not EJUSTRETURN, the packet will be freed by the 467 caller. 468 */ 469typedef errno_t (*proto_media_preout)(ifnet_t ifp, protocol_family_t protocol, 470 mbuf_t *packet, const struct sockaddr *dest, void *route, char *frame_type, 471 char *link_layer_dest); 472 473/*! 474 @typedef proto_media_event 475 @discussion proto_media_event is called to notify this layer of 476 interface specific events. 477 @param ifp The interface. 478 @param protocol_family The protocol family. 479 @param kev_msg The event. 480 */ 481typedef void (*proto_media_event)(ifnet_t ifp, protocol_family_t protocol, 482 const struct kev_msg *event); 483 484/*! 485 @typedef proto_media_ioctl 486 @discussion proto_media_event allows this layer to handle ioctls. 487 When an ioctl is handled, it is passed to the interface filters, 488 protocol filters, protocol, and interface. If you do not support 489 this ioctl, return EOPNOTSUPP. If you successfully handle the 490 ioctl, return zero. If you return any error other than 491 EOPNOTSUPP, other parts of the stack may not get an opportunity 492 to process the ioctl. If you return EJUSTRETURN, processing will 493 stop and a result of zero will be returned to the caller. 494 495 All undefined ioctls are reserved for future use by Apple. If 496 you need to communicate with your kext using an ioctl, please 497 use SIOCSIFKPI and SIOCGIFKPI. 498 @param ifp The interface. 499 @param protocol_family The protocol family. 500 @param command The ioctl command. 501 @param argument The argument to the ioctl. 502 @result 503 See the discussion. 504 */ 505typedef errno_t (*proto_media_ioctl)(ifnet_t ifp, protocol_family_t protocol, 506 unsigned long command, void *argument); 507 508/*! 509 @typedef proto_media_detached 510 @discussion proto_media_detached notifies you that your protocol 511 has been detached. 512 @param ifp The interface. 513 @param protocol_family The protocol family. 514 @result 515 See the discussion. 516 */ 517typedef errno_t (*proto_media_detached)(ifnet_t ifp, protocol_family_t protocol); 518 519/*! 520 @typedef proto_media_resolve_multi 521 @discussion proto_media_resolve_multi is called to resolve a 522 protocol layer mulitcast address to a link layer multicast 523 address. 524 @param ifp The interface. 525 @param proto_addr The protocol address. 526 @param out_ll A sockaddr_dl to copy the link layer multicast in to. 527 @param ll_len The length of data allocated for out_ll. 528 @result Return zero on success or an errno error value on failure. 529 */ 530typedef errno_t (*proto_media_resolve_multi)(ifnet_t ifp, 531 const struct sockaddr *proto_addr, struct sockaddr_dl *out_ll, 532 size_t ll_len); 533 534/*! 535 @typedef proto_media_send_arp 536 @discussion proto_media_send_arp is called by the stack to generate 537 an ARP packet. This field is currently only used with IP. This 538 function should inspect the parameters and transmit an arp 539 packet using the information passed in. 540 @param ifp The interface the arp packet should be sent on. 541 @param protocol_family The protocol family of the addresses 542 (PF_INET). 543 @param arpop The arp operation (usually ARPOP_REQUEST or 544 ARPOP_REPLY). 545 @param sender_hw The value to use for the sender hardware 546 address field. If this is NULL, use the hardware address 547 of the interface. 548 @param sender_proto The value to use for the sender protocol 549 address field. This will not be NULL. 550 @param target_hw The value to use for the target hardware address. 551 If this is NULL, the target hardware address in the ARP packet 552 should be NULL and the link-layer destination for the back 553 should be a broadcast. If this is not NULL, this value should be 554 used for both the link-layer destination and the target hardware 555 address. 556 @param target_proto The target protocol address. This will not be 557 NULL. 558 @result Return zero on success or an errno error value on failure. 559 */ 560typedef errno_t (*proto_media_send_arp)(ifnet_t ifp, u_short arpop, 561 const struct sockaddr_dl *sender_hw, const struct sockaddr *sender_proto, 562 const struct sockaddr_dl *target_hw, const struct sockaddr *target_proto); 563 564/*! 565 @struct ifnet_stat_increment_param 566 @discussion This structure is used increment the counters on a 567 network interface. 568 @field packets_in The number of packets received. 569 @field bytes_in The number of bytes received. 570 @field errors_in The number of receive errors. 571 @field packets_out The number of packets transmitted. 572 @field bytes_out The number of bytes transmitted. 573 @field errors_out The number of transmission errors. 574 @field collisions The number of collisions seen by this interface. 575 @field dropped The number of packets dropped. 576*/ 577struct ifnet_stat_increment_param { 578 u_int32_t packets_in; 579 u_int32_t bytes_in; 580 u_int32_t errors_in; 581 582 u_int32_t packets_out; 583 u_int32_t bytes_out; 584 u_int32_t errors_out; 585 586 u_int32_t collisions; 587 u_int32_t dropped; 588}; 589 590/*! 591 @struct ifnet_init_params 592 @discussion This structure is used to define various properties of 593 the interface when calling ifnet_allocate. A copy of these 594 values will be stored in the ifnet and cannot be modified 595 while the interface is attached. 596 @field uniqueid An identifier unique to this instance of the 597 interface. 598 @field uniqueid_len The length, in bytes, of the uniqueid. 599 @field name The interface name (i.e. en). 600 @field unit The interface unit number (en0's unit number is 0). 601 @field family The interface family. 602 @field type The interface type (see sys/if_types.h). Must be less 603 than 256. For new types, use IFT_OTHER. 604 @field output The output function for the interface. Every packet the 605 stack attempts to send through this interface will go out 606 through this function. 607 @field demux The function used to determine the protocol family of an 608 incoming packet. 609 @field add_proto The function used to attach a protocol to this 610 interface. 611 @field del_proto The function used to remove a protocol from this 612 interface. 613 @field framer The function used to frame outbound packets, may be NULL. 614 @field softc Driver specific storage. This value can be retrieved from 615 the ifnet using the ifnet_softc function. 616 @field ioctl The function used to handle ioctls. 617 @field set_bpf_tap The function used to set the bpf_tap function. 618 @field detach The function called to let the driver know the interface 619 has been detached. 620 @field event The function to notify the interface of various interface 621 specific kernel events. 622 @field broadcast_addr The link-layer broadcast address for this 623 interface. 624 @field broadcast_len The length of the link-layer broadcast address. 625*/ 626struct ifnet_init_params { 627 /* used to match recycled interface */ 628 const void *uniqueid; /* optional */ 629 u_int32_t uniqueid_len; /* optional */ 630 631 /* used to fill out initial values for interface */ 632 const char *name; /* required */ 633 u_int32_t unit; /* required */ 634 ifnet_family_t family; /* required */ 635 u_int32_t type; /* required */ 636 ifnet_output_func output; /* required */ 637 ifnet_demux_func demux; /* required */ 638 ifnet_add_proto_func add_proto; /* required */ 639 ifnet_del_proto_func del_proto; /* required */ 640 ifnet_check_multi check_multi; /* required for non point-to-point interfaces */ 641 ifnet_framer_func framer; /* optional */ 642 void *softc; /* optional */ 643 ifnet_ioctl_func ioctl; /* optional */ 644 ifnet_set_bpf_tap set_bpf_tap; /* deprecated */ 645 ifnet_detached_func detach; /* optional */ 646 ifnet_event_func event; /* optional */ 647 const void *broadcast_addr; /* required for non point-to-point interfaces */ 648 u_int32_t broadcast_len; /* required for non point-to-point interfaces */ 649}; 650 651#ifdef KERNEL_PRIVATE 652/* Valid values for version */ 653#define IFNET_INIT_VERSION_2 2 654#define IFNET_INIT_CURRENT_VERSION IFNET_INIT_VERSION_2 655 656/* Valid values for flags */ 657#define IFNET_INIT_LEGACY 0x1 /* legacy network interface model */ 658#define IFNET_INIT_INPUT_POLL 0x2 /* opportunistic input polling model */ 659 660/* 661 @typedef ifnet_pre_enqueue_func 662 @discussion ifnet_pre_enqueue_func is called for each outgoing packet 663 for the interface. The driver may perform last-minute changes 664 on the (fully formed) packet, but it is responsible for calling 665 ifnet_enqueue() to enqueue the packet upon completion. 666 @param interface The interface being sent on. 667 @param data The packet to be sent. 668 */ 669typedef errno_t (*ifnet_pre_enqueue_func)(ifnet_t interface, mbuf_t data); 670 671/* 672 @typedef ifnet_start_func 673 @discussion ifnet_start_func is used to indicate to the driver that 674 one or more packets may be dequeued by calling ifnet_dequeue() 675 or ifnet_dequeue_multi(). This routine gets invoked when 676 ifnet_start() is called; the ifnet_start_func callback will 677 be executed within the context of a dedicated kernel thread, 678 hence it is guaranteed to be single threaded. The driver must 679 employ additional serializations if this callback routine is 680 to be called directly from another context, in order to prevent 681 race condition related issues (e.g. out-of-order packets.) 682 The dequeued packets will be fully formed packets (including 683 frame headers). The packets must be freed by the driver. 684 @param interface The interface being sent on. 685 */ 686typedef void (*ifnet_start_func)(ifnet_t interface); 687 688/* 689 @typedef ifnet_input_poll_func 690 @discussion ifnet_input_poll_func is called by the network stack to 691 retrieve one or more packets from the driver which implements 692 the new driver input model. 693 @param interface The interface to retrieve the packets from. 694 @param flags For future use. 695 @param max_count The maximum number of packets to be dequeued. 696 @param first_packet Pointer to the first packet being dequeued. 697 @param last_packet Pointer to the last packet being dequeued. 698 @param cnt Pointer to a storage for the number of packets dequeued. 699 @param len Pointer to a storage for the total length (in bytes) 700 of the dequeued packets. 701 */ 702typedef void (*ifnet_input_poll_func)(ifnet_t interface, u_int32_t flags, 703 u_int32_t max_count, mbuf_t *first_packet, mbuf_t *last_packet, 704 u_int32_t *cnt, u_int32_t *len); 705 706/* 707 @enum Interface control commands 708 @abstract Constants defining control commands. 709 @constant IFNET_CTL_SET_INPUT_MODEL Set input model. 710 @constant IFNET_CTL_GET_INPUT_MODEL Get input model. 711 */ 712enum { 713 IFNET_CTL_SET_INPUT_MODEL = 1, 714 IFNET_CTL_GET_INPUT_MODEL = 2, 715}; 716 717/* 718 @typedef ifnet_ctl_cmd_t 719 @abstract Storage type for the interface control command. 720 */ 721typedef u_int32_t ifnet_ctl_cmd_t; 722 723/* 724 @enum Interface model sub-commands 725 @abstract Constants defining model sub-commands. 726 @constant IFNET_MODEL_INPUT_POLL_OFF Polling is inactive. When set, 727 the network stack will no longer invoke the input_poll callback 728 until the next time polling is turned on; the driver should 729 proceed to pushing the packets up to the network stack as in 730 the legacy input model, and if applicable, the driver should 731 also enable receive interrupt for the hardware. During get, 732 this indicates that the driver is currently operating in 733 the legacy/push input model. 734 @constant IFNET_MODEL_INPUT_POLL_ON Polling is active. When set, the 735 network stack will begin to invoke the input_poll callback to 736 retrieve packets from the driver until the next time polling 737 is turned off; the driver should no longer be pushing packets 738 up to the network stack, and if applicable, the driver should 739 also disable receive interrupt for the hardware. During get, 740 this indicates that the driver is currently operating in 741 the new/pull input model. 742 */ 743enum { 744 IFNET_MODEL_INPUT_POLL_OFF = 0, 745 IFNET_MODEL_INPUT_POLL_ON = 1, 746}; 747 748/* 749 @typedef ifnet_model_t 750 @abstract Storage type for the interface model sub-command. 751 */ 752typedef u_int32_t ifnet_model_t; 753 754/* 755 @struct ifnet_model_params 756 @discussion This structure is used as parameter to the ifnet model 757 sub-commands. 758 @field model The interface model. 759 */ 760struct ifnet_model_params { 761 ifnet_model_t model; 762 u_int32_t reserved[3]; 763}; 764 765/* 766 @typedef ifnet_ctl_func 767 @discussion ifnet_ctl_func is called by the network stack to inform 768 about changes in parameters, or retrieve the parameters 769 related to the output or input processing or capabilities. 770 @param interface The interface. 771 @param cmd The ifnet_ctl_cmd_t interface control command. 772 @param arglen The length of the command argument. 773 @param arg The command argument. 774 @result 0 upon success, otherwise errno error. 775 */ 776typedef errno_t (*ifnet_ctl_func)(ifnet_t interface, ifnet_ctl_cmd_t cmd, 777 u_int32_t arglen, void *arg); 778 779/* 780 @struct ifnet_init_eparams 781 @discussion This structure is used to define various properties of 782 the interface when calling ifnet_allocate_extended. A copy of 783 these values will be stored in the ifnet and cannot be modified 784 while the interface is attached. 785 @field ver The current structure version (IFNET_INIT_CURRENT_VERSION) 786 @field len The length of this structure. 787 @field flags See above values for flags. 788 @field uniqueid An identifier unique to this instance of the 789 interface. 790 @field uniqueid_len The length, in bytes, of the uniqueid. 791 @field name The interface name (i.e. en). 792 @field unit The interface unit number (en0's unit number is 0). 793 @field family The interface family. 794 @field type The interface type (see sys/if_types.h). Must be less 795 than 256. For new types, use IFT_OTHER. 796 @field sndq_maxlen The maximum size of the output queue; valid only 797 if IFNET_INIT_LEGACY is not set. 798 @field output The output function for the interface. Every packet the 799 stack attempts to send through this interface will go out 800 through this function. 801 @field pre_enqueue The pre_enqueue function for the interface, valid 802 only if IFNET_INIT_LEGACY is not set, and optional if it is set. 803 @field start The start function for the interface, valid only if 804 IFNET_INIT_LEGACY is not set, and required if it is set. 805 @field output_ctl The output control function for the interface, valid 806 only if IFNET_INIT_LEGACY is not set. 807 @field output_sched_model The IFNET_SCHED_MODEL value for the output 808 queue, as defined in net/if.h 809 @field output_bw The effective output bandwidth (in bits per second.) 810 @field output_bw_max The maximum theoretical output bandwidth 811 (in bits per second.) 812 @field input_poll The poll function for the interface, valid only if 813 IFNET_INIT_LEGACY is not set and only if IFNET_INIT_INPUT_POLL 814 is set. 815 @field input_ctl The input control function for the interface, valid 816 only if IFNET_INIT_LEGACY is not set and only if opportunistic 817 input polling is enabled via IFNET_INIT_INPUT_POLL flag. 818 @field rcvq_maxlen The size of the driver's receive ring or the total 819 count of descriptors used in the receive path; valid only if 820 IFNET_INIT_INPUT_POLL is set. 821 @field input_bw The effective input bandwidth (in bits per second.) 822 @field input_bw_max The maximum theoretical input bandwidth 823 (in bits per second.) 824 @field demux The function used to determine the protocol family of an 825 incoming packet. 826 @field add_proto The function used to attach a protocol to this 827 interface. 828 @field del_proto The function used to remove a protocol from this 829 interface. 830 @field framer The function used to frame outbound packets, may be NULL. 831 @field softc Driver specific storage. This value can be retrieved from 832 the ifnet using the ifnet_softc function. 833 @field ioctl The function used to handle ioctls. 834 @field set_bpf_tap The function used to set the bpf_tap function. 835 @field detach The function called to let the driver know the interface 836 has been detached. 837 @field event The function to notify the interface of various interface 838 specific kernel events. 839 @field broadcast_addr The link-layer broadcast address for this 840 interface. 841 @field broadcast_len The length of the link-layer broadcast address. 842*/ 843struct ifnet_init_eparams { 844 u_int32_t ver; /* required */ 845 u_int32_t len; /* required */ 846 u_int32_t flags; /* optional */ 847 848 /* used to match recycled interface */ 849 const void *uniqueid; /* optional */ 850 u_int32_t uniqueid_len; /* optional */ 851 852 /* used to fill out initial values for interface */ 853 const char *name; /* required */ 854 u_int32_t unit; /* required */ 855 ifnet_family_t family; /* required */ 856 u_int32_t type; /* required */ 857 u_int32_t sndq_maxlen; /* optional, only for new model */ 858 ifnet_output_func output; /* required only for legacy model */ 859 ifnet_pre_enqueue_func pre_enqueue; /* optional, only for new model */ 860 ifnet_start_func start; /* required only for new model */ 861 ifnet_ctl_func output_ctl; /* optional, only for new model */ 862 u_int32_t output_sched_model; /* optional, only for new model */ 863 u_int32_t reserved; /* for future use */ 864 u_int64_t output_bw; /* optional */ 865 u_int64_t output_bw_max; /* optional */ 866 u_int64_t _reserved[4]; /* for future use */ 867 ifnet_input_poll_func input_poll; /* optional, ignored for legacy model */ 868 ifnet_ctl_func input_ctl; /* required for opportunistic polling */ 869 u_int32_t rcvq_maxlen; /* optional, only for opportunistic polling */ 870 u_int32_t __reserved; /* for future use */ 871 u_int64_t input_bw; /* optional */ 872 u_int64_t input_bw_max; /* optional */ 873 u_int64_t ___reserved[4]; /* for future use */ 874 ifnet_demux_func demux; /* required */ 875 ifnet_add_proto_func add_proto; /* required */ 876 ifnet_del_proto_func del_proto; /* required */ 877 ifnet_check_multi check_multi; /* required for non point-to-point interfaces */ 878 ifnet_framer_func framer; /* optional */ 879 void *softc; /* optional */ 880 ifnet_ioctl_func ioctl; /* optional */ 881 ifnet_set_bpf_tap set_bpf_tap; /* deprecated */ 882 ifnet_detached_func detach; /* optional */ 883 ifnet_event_func event; /* optional */ 884 const void *broadcast_addr; /* required for non point-to-point interfaces */ 885 u_int32_t broadcast_len; /* required for non point-to-point interfaces */ 886 u_int64_t ____reserved[4]; /* for future use */ 887}; 888#endif /* KERNEL_PRIVATE */ 889 890/*! 891 @struct ifnet_stats_param 892 @discussion This structure is used get and set the interface 893 statistics. 894 @field packets_in The number of packets received. 895 @field bytes_in The number of bytes received. 896 @field errors_in The number of receive errors. 897 @field packets_out The number of packets transmitted. 898 @field bytes_out The number of bytes transmitted. 899 @field errors_out The number of transmission errors. 900 @field collisions The number of collisions seen by this interface. 901 @field dropped The number of packets dropped. 902*/ 903struct ifnet_stats_param { 904 u_int64_t packets_in; 905 u_int64_t bytes_in; 906 u_int64_t multicasts_in; 907 u_int64_t errors_in; 908 909 u_int64_t packets_out; 910 u_int64_t bytes_out; 911 u_int64_t multicasts_out; 912 u_int64_t errors_out; 913 914 u_int64_t collisions; 915 u_int64_t dropped; 916 u_int64_t no_protocol; 917}; 918 919/*! 920 @struct ifnet_demux_desc 921 @discussion This structure is to identify packets that belong to a 922 specific protocol. The types supported are interface specific. 923 Ethernet supports ETHER_DESC_ETYPE2, ETHER_DESC_SAP, and 924 ETHER_DESC_SNAP. The type defines the offset in the packet where 925 the data will be matched as well as context. For example, if 926 ETHER_DESC_SNAP is specified, the only valid datalen is 5 and 927 only in the 5 bytes will only be matched when the packet header 928 indicates that the packet is a SNAP packet. 929 @field type The type of identifier data (i.e. ETHER_DESC_ETYPE2) 930 @field data A pointer to an entry of type (i.e. pointer to 0x0800). 931 @field datalen The number of bytes of data used to describe the 932 packet. 933*/ 934struct ifnet_demux_desc { 935 u_int32_t type; 936 void *data; 937 u_int32_t datalen; 938}; 939 940/*! 941 @struct ifnet_attach_proto_param 942 @discussion This structure is used to attach a protocol to an 943 interface. This structure provides the various functions for 944 handling operations related to the protocol on the interface as 945 well as information for how to demux packets for this protocol. 946 @field demux_array An array of ifnet_demux_desc structures 947 describing the protocol. 948 @field demux_count The number of entries in the demux_array array. 949 @field input The function to be called for inbound packets. 950 @field pre_output The function to be called for outbound packets. 951 @field event The function to be called for interface events. 952 @field ioctl The function to be called for ioctls. 953 @field detached The function to be called for handling the detach. 954*/ 955#ifdef KERNEL_PRIVATE 956#define demux_list demux_array 957#endif /* KERNEL_PRIVATE */ 958 959struct ifnet_attach_proto_param { 960 struct ifnet_demux_desc *demux_array; /* interface may/may not require */ 961 u_int32_t demux_count; /* interface may/may not require */ 962 963 proto_media_input input; /* required */ 964 proto_media_preout pre_output; /* required */ 965 proto_media_event event; /* optional */ 966 proto_media_ioctl ioctl; /* optional */ 967 proto_media_detached detached; /* optional */ 968 proto_media_resolve_multi resolve; /* optional */ 969 proto_media_send_arp send_arp; /* optional */ 970}; 971 972struct ifnet_attach_proto_param_v2 { 973 struct ifnet_demux_desc *demux_array; /* interface may/may not require */ 974 u_int32_t demux_count; /* interface may/may not require */ 975 976 proto_media_input_v2 input; /* required */ 977 proto_media_preout pre_output; /* required */ 978 proto_media_event event; /* optional */ 979 proto_media_ioctl ioctl; /* optional */ 980 proto_media_detached detached; /* optional */ 981 proto_media_resolve_multi resolve; /* optional */ 982 proto_media_send_arp send_arp; /* optional */ 983}; 984 985__BEGIN_DECLS 986 987/* 988 * Ifnet creation and reference counting 989 */ 990 991/*! 992 @function ifnet_allocate 993 @discussion Allocate an ifnet_t with an initial refcount of 1. Many 994 parts of the stack do not properly refcount the ifnet_t. In 995 order to avoid freeing the ifnet_t while some parts of the stack 996 may contain a reference to it, the ifnet_ts are only recycled, 997 never freed. A unique id is used to try and recycle the same 998 ifnet_t when allocating an interface. For example, for an 999 ethernet interface, the hardware address of the ethernet card is 1000 usually used for the uniqueid. If a PC Card is removed and 1001 inserted again, if the ethernet address of the PC card is used, 1002 the same ifnet_t will be used for the card the second time it is 1003 inserted. In the future, when the ifnet_t is correctly 1004 refcounted by all of the stack, the interfaces may be freed and 1005 the unique ids ignored. 1006 @param init The initial values for the interface. These values can 1007 not be changed after the interface has been allocated. 1008 @param interface The interface allocated upon success. 1009 @result May return ENOMEM if there is insufficient memory or EEXIST 1010 if an interface with the same uniqueid and family has already 1011 been allocated and is in use. 1012 */ 1013extern errno_t ifnet_allocate(const struct ifnet_init_params *init, 1014 ifnet_t *interface); 1015 1016#ifdef KERNEL_PRIVATE 1017/* 1018 @function ifnet_allocate_extended 1019 @discussion An extended/newer variant of ifnet_allocate, with additional 1020 support for the new output and input driver models. 1021 @param init The initial values for the interface. These values can 1022 not be changed after the interface has been allocated. 1023 @param interface The interface allocated upon success. 1024 @result May return ENOMEM if there is insufficient memory or EEXIST 1025 if an interface with the same uniqueid and family has already 1026 been allocated and is in use. 1027 */ 1028extern errno_t ifnet_allocate_extended(const struct ifnet_init_eparams *init, 1029 ifnet_t *interface); 1030 1031/* 1032 @function ifnet_purge 1033 @discussion Purge the output queue of an interface which implements 1034 the new driver output model. 1035 @param interface The interface to purge. 1036 */ 1037extern void ifnet_purge(ifnet_t interface); 1038 1039/* 1040 @function ifnet_enqueue 1041 @discussion Enqueue a packet to the output queue of an interface 1042 which implements the new driver output model. 1043 @param interface The interface to enqueue the packet to. 1044 @param packet The packet being enqueued; only one packet is allowed 1045 to be enqueued at a time. 1046 @result May return EINVAL if the parameters are invalid; ENXIO if 1047 the interface doesn't implement the new driver output model; 1048 EQFULL if the output queue is flow-controlled; or EQSUSPENDED 1049 if the output queue is suspended. This routine either frees 1050 or consumes the packet; the caller must not modify or free 1051 it after calling this routine. Any attempt to enqueue more 1052 than one packet will cause the entire packet chain to be freed. 1053 */ 1054extern errno_t ifnet_enqueue(ifnet_t interface, mbuf_t packet); 1055 1056/* 1057 @function ifnet_dequeue 1058 @discussion Dequeue a packet from the output queue of an interface 1059 which implements the new driver output model, and that the 1060 output scheduling model is set to IFNET_SCHED_MODEL_NORMAL. 1061 @param interface The interface to dequeue the packet from. 1062 @param packet Pointer to the packet being dequeued. 1063 @result May return EINVAL if the parameters are invalid, ENXIO if 1064 the interface doesn't implement the new driver output model 1065 or the output scheduling model isn't IFNET_SCHED_MODEL_NORMAL, 1066 or EAGAIN if there is currently no packet available to 1067 be dequeued. 1068 */ 1069extern errno_t ifnet_dequeue(ifnet_t interface, mbuf_t *packet); 1070 1071/* 1072 @function ifnet_dequeue_service_class 1073 @discussion Dequeue a packet of a particular service class from the 1074 appropriate output queue of an interface which implements the 1075 new driver output model, and that the output scheduling model 1076 is set to IFNET_SCHED_MODEL_DRIVER_MANAGED. 1077 @param interface The interface to dequeue the packet from. 1078 @param tc The service class. 1079 @param packet Pointer to the packet being dequeued. 1080 @result May return EINVAL if the parameters are invalid, ENXIO if 1081 the interface doesn't implement the new driver output model 1082 or if the output scheduling model isn't configured to 1083 IFNET_SCHED_MODEL_DRIVER_MANAGED, or EAGAIN if there 1084 is currently no packet available to be dequeued. 1085 */ 1086extern errno_t ifnet_dequeue_service_class(ifnet_t interface, 1087 mbuf_svc_class_t tc, mbuf_t *packet); 1088 1089/* 1090 @function ifnet_dequeue_multi 1091 @discussion Dequeue one or more packets from the output queue of an 1092 interface which implements the new driver output model, and that 1093 the output scheduling model is set to IFNET_SCHED_MODEL_NORMAL. 1094 The returned packet chain is traversable with mbuf_nextpkt(). 1095 @param interface The interface to dequeue the packets from. 1096 @param first_packet Pointer to the first packet being dequeued. 1097 @param last_packet Pointer to the last packet being dequeued. Caller 1098 may supply NULL if not interested in value. 1099 @param cnt Pointer to a storage for the number of packets dequeued. 1100 Caller may supply NULL if not interested in value. 1101 @param len Pointer to a storage for the total length (in bytes) 1102 of the dequeued packets. Caller may supply NULL if not 1103 interested in value. 1104 @result May return EINVAL if the parameters are invalid, ENXIO if 1105 the interface doesn't implement the new driver output model 1106 or the output scheduling model isn't IFNET_SCHED_MODEL_NORMAL, 1107 or EAGAIN if there is currently no packet available to 1108 be dequeued. 1109 */ 1110extern errno_t ifnet_dequeue_multi(ifnet_t interface, u_int32_t max, 1111 mbuf_t *first_packet, mbuf_t *last_packet, u_int32_t *cnt, u_int32_t *len); 1112 1113/* 1114 @function ifnet_dequeue_service_class_multi 1115 @discussion Dequeue one or more packets of a particular service class 1116 from the appropriate output queue of an interface which 1117 implements the new driver output model, and that the output 1118 scheduling model is set to IFNET_SCHED_MODEL_DRIVER_MANAGED. 1119 The returned packet chain is traversable with mbuf_nextpkt(). 1120 @param interface The interface to dequeue the packets from. 1121 @param tc The service class. 1122 @param first_packet Pointer to the first packet being dequeued. 1123 @param last_packet Pointer to the last packet being dequeued. Caller 1124 may supply NULL if not interested in value. 1125 @param cnt Pointer to a storage for the number of packets dequeued. 1126 Caller may supply NULL if not interested in value. 1127 @param len Pointer to a storage for the total length (in bytes) 1128 of the dequeued packets. Caller may supply NULL if not 1129 interested in value. 1130 @result May return EINVAL if the parameters are invalid, ENXIO if 1131 the interface doesn't implement the new driver output model 1132 or if the output scheduling model isn't configured to 1133 IFNET_SCHED_MODEL_DRIVER_MANAGED, or EAGAIN if there 1134 is currently no packet available to be dequeued. 1135 */ 1136extern errno_t ifnet_dequeue_service_class_multi(ifnet_t interface, 1137 mbuf_svc_class_t tc, u_int32_t max, mbuf_t *first_packet, 1138 mbuf_t *last_packet, u_int32_t *cnt, u_int32_t *len); 1139 1140/* 1141 @function ifnet_set_output_sched_model 1142 @discussion Set the output scheduling model of an interface which 1143 implements the new driver output model. 1144 @param interface The interface to set scheduling model on. 1145 @param model The IFNET_SCHED_MODEL value as defined in net/if.h 1146 @result May return EINVAL if the parameters are invalid or ENXIO if 1147 the interface doesn't implement the new driver output model. 1148 */ 1149extern errno_t ifnet_set_output_sched_model(ifnet_t interface, 1150 u_int32_t model); 1151 1152/* 1153 @function ifnet_set_sndq_maxlen 1154 @discussion Set the maximum length of the output queue of an 1155 interface which implements the new driver output model. 1156 This call may be issued post ifnet_allocate_extended in 1157 order to modify the maximum output queue length previously 1158 set at registration time. 1159 @param interface The interface to set the max queue length on. 1160 @param maxqlen The maximum number of packets in the output queue. 1161 @result May return EINVAL if the parameters are invalid or ENXIO if 1162 the interface doesn't implement the new driver output model. 1163 */ 1164extern errno_t ifnet_set_sndq_maxlen(ifnet_t interface, u_int32_t maxqlen); 1165 1166/* 1167 @function ifnet_get_sndq_maxlen 1168 @discussion Get the maximum length of the output queue of an 1169 interface which implements the new driver output model. 1170 @param interface The interface to get the max queue length on. 1171 @param maxqlen Pointer to a storage for the maximum number of packets 1172 in the output queue. 1173 @result May return EINVAL if the parameters are invalid or ENXIO if 1174 the interface doesn't implement the new driver output model. 1175 */ 1176extern errno_t ifnet_get_sndq_maxlen(ifnet_t interface, u_int32_t *maxqlen); 1177 1178/* 1179 @function ifnet_get_sndq_len 1180 @discussion Get the current length of the output queue of an 1181 interface which implements the new driver output model. 1182 @param interface The interface to get the current queue length on. 1183 @param qlen Pointer to a storage for the current number of packets 1184 in the output queue. 1185 @result May return EINVAL if the parameters are invalid or ENXIO if 1186 the interface doesn't implement the new driver output model. 1187 */ 1188extern errno_t ifnet_get_sndq_len(ifnet_t interface, u_int32_t *qlen); 1189 1190/* 1191 @function ifnet_set_rcvq_maxlen 1192 @discussion Set the maximum length of the input queue of an 1193 interface which implements the new driver input model. 1194 This call may be issued post ifnet_allocate_extended in 1195 order to modify the maximum input queue length previously 1196 set at registration time. 1197 @param interface The interface to set the max queue length on. 1198 @param maxqlen The maximum number of packets in the input queue. 1199 Drivers typically set this to the size of the receive ring 1200 or the total number of descriptors used for the input path. 1201 @result May return EINVAL if the parameters are invalid or ENXIO if 1202 the interface doesn't implement the new driver input model. 1203 */ 1204extern errno_t ifnet_set_rcvq_maxlen(ifnet_t interface, u_int32_t maxqlen); 1205 1206/* 1207 @function ifnet_get_rcvq_maxlen 1208 @discussion Get the maximum length of the input queue of an 1209 interface which implements the new driver input model. 1210 @param interface The interface to get the max queue length on. 1211 @param maxqlen Pointer to a storage for the maximum number of packets 1212 in the input queue. 1213 @result May return EINVAL if the parameters are invalid or ENXIO if 1214 the interface doesn't implement the new driver input model. 1215 */ 1216extern errno_t ifnet_get_rcvq_maxlen(ifnet_t interface, u_int32_t *maxqlen); 1217 1218/* 1219 @function ifnet_start 1220 @discussion Trigger the transmission at the driver layer on an 1221 interface which implements the new driver output model. 1222 @param interface The interface to start the transmission on. 1223 */ 1224extern void ifnet_start(ifnet_t interface); 1225 1226/* 1227 @function ifnet_transmit_burst_start 1228 @discussion Inform the kernel about the beginning of transmission 1229 of a burst. This function should be called when a burst of 1230 packets are scheduled to get transmitted over the link. The 1231 callback will be used by the system to start measuring 1232 bandwidth available on that link. The driver may choose to 1233 adopt this scheme for uplink bandwidth measurement, in case 1234 the information can't be obtained from the hardware. Else 1235 it may alternatively inform the network stack about the 1236 information using ifnet_set_bandwidths. 1237 @param interface The interface. 1238 @param mbuf_t The first packet in a burst of packets that has been 1239 scheduled to transmit. 1240*/ 1241extern void ifnet_transmit_burst_start(ifnet_t interface, mbuf_t pkt); 1242 1243/* 1244 @function ifnet_transmit_burst_end 1245 @discussion Inform the kernel about the end of transmission of a burst. 1246 This function should be called when the transmission of a burst 1247 of packets is done. This information will be used by the 1248 system to estimate bandwidth available on that link. The 1249 driver may choose to adopt this scheme for uplink bandwidth 1250 measurement, in case the information can't be obtained from 1251 the hardware. Else it may alternatively inform the network 1252 stack about the information using ifnet_set_bandwidths. 1253 @param interface The interface. 1254 @param mbuf_t The last packet in the burst that has been successfully 1255 transmitted. 1256*/ 1257extern void ifnet_transmit_burst_end(ifnet_t interface, mbuf_t pkt); 1258#endif /* KERNEL_PRIVATE */ 1259 1260/*! 1261 @function ifnet_reference 1262 @discussion Increment the reference count of the ifnet to assure 1263 that it will not go away. The interface must already have at 1264 least one reference. 1265 @param interface The interface to increment the reference count of. 1266 @result May return EINVAL if the interface is not valid. 1267 */ 1268extern errno_t ifnet_reference(ifnet_t interface); 1269 1270/*! 1271 @function ifnet_release 1272 @discussion Release a reference of the ifnet, this may trigger a 1273 free if the reference count reaches 0. 1274 @param interface The interface to decrement the reference count of 1275 and possibly free. 1276 @result May return EINVAL if the interface is not valid. 1277 */ 1278extern errno_t ifnet_release(ifnet_t interface); 1279 1280/*! 1281 @function ifnet_attach 1282 @discussion Attaches an interface to the global interface list. The 1283 interface must be setup properly before calling attach. The 1284 stack will take a reference on the interface and hold it until 1285 ifnet_detach is called. 1286 1287 This function is intended to be called by the driver. A kext 1288 must not call this function on an interface the kext does not 1289 own. 1290 @param interface The interface to attach. 1291 @param ll_addr The link layer address of the interface. This is used 1292 to fill out the first ifaddr in the list of addresses for the 1293 interface. This parameter is not required for interfaces such as 1294 PPP that have no link-layer address. 1295 @result Will return an error if there is anything wrong with the 1296 interface. 1297 */ 1298extern errno_t ifnet_attach(ifnet_t interface, 1299 const struct sockaddr_dl *ll_addr); 1300 1301/*! 1302 @function ifnet_detach 1303 @discussion Detaches the interface. 1304 1305 Call this to indicate this interface is no longer valid (i.e. PC 1306 Card was removed). This function will begin the process of 1307 removing knowledge of this interface from the stack. 1308 1309 The function will return before the interface is detached. The 1310 functions you supplied in to the interface may continue to be 1311 called. When the detach has been completed, your detached 1312 function will be called. Your kext must not unload until the 1313 detached function has been called. The interface will be 1314 properly freed when the reference count reaches zero. 1315 1316 An interface may not be attached again. You must call 1317 ifnet_allocate to create a new interface to attach. 1318 1319 This function is intended to be called by the driver. A kext 1320 must not call this function on an interface the kext does not 1321 own. 1322 @param interface The interface to detach. 1323 @result 0 on success, otherwise errno error. 1324 */ 1325extern errno_t ifnet_detach(ifnet_t interface); 1326 1327/*! 1328 @function ifnet_interface_family_find 1329 @discussion Look up the interface family identifier for a string. 1330 If there is no interface family identifier assigned for this string 1331 a new interface family identifier is created and assigned. 1332 It is recommended to use the bundle id of the KEXT as the string 1333 to avoid collisions with other KEXTs. 1334 The lookup operation is not optimized so a module should call this 1335 function once during startup and cache the interface family identifier. 1336 The interface family identifier for a string will not be re-assigned until 1337 the system reboots. 1338 @param module_string A unique string identifying your interface family 1339 @param family_id Upon return, a unique interface family identifier for use with 1340 ifnet_* functions. This identifier is valid until the system 1341 is rebooted. 1342 @result 0 on success, otherwise errno error. 1343*/ 1344extern errno_t ifnet_interface_family_find(const char *module_string, ifnet_family_t *family_id); 1345 1346/* 1347 * Interface manipulation. 1348 */ 1349 1350/*! 1351 @function ifnet_softc 1352 @discussion Returns the driver's private storage on the interface. 1353 @param interface Interface to retrieve the storage from. 1354 @result Driver's private storage. 1355 */ 1356extern void *ifnet_softc(ifnet_t interface); 1357 1358/*! 1359 @function ifnet_name 1360 @discussion Returns a pointer to the name of the interface. 1361 @param interface Interface to retrieve the name from. 1362 @result Pointer to the name. 1363 */ 1364extern const char *ifnet_name(ifnet_t interface); 1365 1366/*! 1367 @function ifnet_family 1368 @discussion Returns the family of the interface. 1369 @param interface Interface to retrieve the unit number from. 1370 @result Interface family type. 1371 */ 1372extern ifnet_family_t ifnet_family(ifnet_t interface); 1373 1374/*! 1375 @function ifnet_unit 1376 @discussion Returns the unit number of the interface. 1377 @param interface Interface to retrieve the unit number from. 1378 @result Unit number. 1379 */ 1380extern u_int32_t ifnet_unit(ifnet_t interface); 1381 1382/*! 1383 @function ifnet_index 1384 @discussion Returns the index of the interface. This index value 1385 will match the index you would find in a sockaddr_dl or using 1386 if_nametoindex or if_indextoname in user space. The value of the 1387 interface index is undefined for an interface that is not 1388 currently attached. 1389 @param interface Interface to retrieve the index of. 1390 @result Index. 1391 */ 1392extern u_int32_t ifnet_index(ifnet_t interface); 1393 1394/*! 1395 @function ifnet_set_flags 1396 @discussion Sets the interface flags to match new_flags. 1397 @discussion Sets the interface flags to new_flags. This function 1398 lets you specify which flags you want to change using the mask. 1399 The kernel will effectively take the lock, then set the 1400 interface's flags to (if_flags & ~mask) | (new_flags & mask). 1401 @param interface Interface to set the flags on. 1402 @param new_flags The new set of flags that should be set. These 1403 flags are defined in net/if.h 1404 @result 0 on success otherwise the errno error. 1405 */ 1406extern errno_t ifnet_set_flags(ifnet_t interface, u_int16_t new_flags, 1407 u_int16_t mask); 1408 1409/*! 1410 @function ifnet_flags 1411 @discussion Returns the interface flags that are set. 1412 @param interface Interface to retrieve the flags from. 1413 @result Flags. These flags are defined in net/if.h 1414 */ 1415extern u_int16_t ifnet_flags(ifnet_t interface); 1416 1417 1418#ifdef KERNEL_PRIVATE 1419/* 1420 @function ifnet_set_eflags 1421 @discussion Sets the extended interface flags to new_flags. This 1422 function lets you specify which flags you want to change using 1423 the mask. The kernel will effectively take the lock, then set 1424 the interface's extended flags to (if_eflags & ~mask) | 1425 (new_flags & mask). 1426 @param interface The interface. 1427 @param new_flags The new set of flags that should be set. These 1428 flags are defined in net/if.h 1429 @param mask The mask of flags to be modified. 1430 @result 0 on success otherwise the errno error. 1431 */ 1432extern errno_t ifnet_set_eflags(ifnet_t interface, u_int32_t new_flags, 1433 u_int32_t mask); 1434 1435/* 1436 @function ifnet_eflags 1437 @discussion Returns the extended interface flags that are set. 1438 @param interface Interface to retrieve the flags from. 1439 @result Extended flags. These flags are defined in net/if.h 1440 */ 1441extern u_int32_t ifnet_eflags(ifnet_t interface); 1442 1443/* 1444 @function ifnet_set_idle_flags 1445 @discussion Sets the if_idle_flags to new_flags. This function 1446 lets you specify which flags you want to change using the 1447 mask. The kernel will effectively take the lock, then set 1448 the interface's idle flags to: 1449 (if_idle_flags & ~mask) | (new_flags & mask). 1450 Setting the flags to any non-zero value will cause the 1451 networking stack to aggressively purge expired objects, 1452 such as route entries, etc. 1453 @param interface The interface. 1454 @param new_flags The new set of flags that should be set. These 1455 flags are defined in net/if.h 1456 @param mask The mask of flags to be modified. 1457 @result 0 on success otherwise the errno error. ENOTSUP is returned 1458 when this call is made on non-supporting platforms. 1459*/ 1460extern errno_t ifnet_set_idle_flags(ifnet_t interface, u_int32_t new_flags, 1461 u_int32_t mask); 1462 1463/* 1464 @function ifnet_idle_flags 1465 @discussion Returns the value of if_idle_flags. 1466 @param interface Interface to retrieve the flags from. 1467 @result if_idle_flags. These flags are defined in net/if.h 1468*/ 1469extern u_int32_t ifnet_idle_flags(ifnet_t interface); 1470 1471/* 1472 @function ifnet_set_link_quality 1473 @discussion Sets the Link Quality Metric for the ifnet. 1474 @param interface Interface for which the Link Quality Metric should 1475 be associated to. 1476 @param quality IFNET_LQM value as defined in net/if.h. 1477 @result 0 on success otherwise the errno error. EINVAL if quality 1478 is not a valid value. ENXIO if the interface is not attached. 1479*/ 1480extern errno_t ifnet_set_link_quality(ifnet_t interface, int quality); 1481 1482/* 1483 @function ifnet_link_quality 1484 @discussion Returns the Link Quality Metric for the ifnet. 1485 @param interface Interface to retrieve the value from. 1486 @result IFNET_LQM as defined in net/if.h 1487*/ 1488extern int ifnet_link_quality(ifnet_t interface); 1489 1490/* 1491 @struct ifnet_llreach_info 1492 @discussion This structure is used to describe the link-layer 1493 reachability information of an on-link node. 1494 @field iflri_refcnt The number of network-layer objects referring 1495 to this link-layer reachability record. 1496 @field iflri_probes The total number of outstanding probes. 1497 @field iflri_snd_expire The send expiration time. This is calculated 1498 based on the last time the system transmitted a packet to the 1499 node. A zero value indicates that a packet has not been sent 1500 to the node. A non-zero value indicates the time before the 1501 record is determined to be invalid. When the record is no 1502 longer valid, the system will send probe(s) to resolve the 1503 node again. This value is relative to the current time 1504 specified in iflri_curtime. 1505 @field iflri_rcv_expire The receive expiriation time. This is 1506 calculated based on the last time the system received a packet 1507 from the node. A zero value indicates that a packet has not 1508 been received from the node. A non-zero value indicates the 1509 time before the record is determined to be invalid. When the 1510 record is no longer valid, the system will send probe(s) to 1511 resolve the node again. This value is relative to the current 1512 time specified in iflri_curtime. 1513 @field iflri_curtime The current time when this record was retrieved. 1514 @field iflri_netproto The protocol number of the network-layer object. 1515 @field iflri_addr The link-layer address of the node. 1516 @field iflri_rssi The received signal strength indication (RSSI) of the 1517 node in dBm. The special value IFNET_RSSI_UNKNOWN is used when 1518 the RSSI is either unknown or inapplicable for the interface. 1519 @field iflri_lqm The link quality metric (LQM) to the node. The 1520 special value IFNET_LQM_UNKNOWN is used when the LQM is not 1521 currently known. The special value IFNET_LQM_OFF is used when 1522 the link quality metric is inapplicable to nodes at this 1523 attached to the network at this interface. 1524 @field iflri_npm The node proximity metric (NPM) to the node. The 1525 special value IFNET_NPM_UNKNOWN is used when the NPM is not 1526 currently known. 1527 */ 1528#define IFNET_LLREACHINFO_ADDRLEN 64 /* max ll addr len */ 1529 1530struct ifnet_llreach_info { 1531 u_int32_t iflri_refcnt; 1532 u_int32_t iflri_probes; 1533 u_int64_t iflri_snd_expire; 1534 u_int64_t iflri_rcv_expire; 1535 u_int64_t iflri_curtime; 1536 u_int32_t iflri_netproto; 1537 u_int8_t iflri_addr[IFNET_LLREACHINFO_ADDRLEN]; 1538 int32_t iflri_rssi; 1539 int32_t iflri_lqm; 1540 int32_t iflri_npm; 1541}; 1542 1543/* 1544 @function ifnet_inet_defrouter_llreachinfo 1545 @discussion Retrieve link-layer reachability information of the 1546 default IPv4 router specific to the interface. 1547 @param interface The interface associated with the default IPv4 router. 1548 @param pinfo Pointer to the ifnet_llreach_info structure where the 1549 information will be returned to, upon success. 1550 @result 0 upon success, otherwise errno error. 1551 */ 1552extern errno_t ifnet_inet_defrouter_llreachinfo(ifnet_t interface, 1553 struct ifnet_llreach_info *pinfo); 1554 1555/* 1556 @function ifnet_inet6_defrouter_llreachinfo 1557 @discussion Retrieve link-layer reachability information of the 1558 default IPv6 router specific to the interface. 1559 @param interface The interface associated with the default IPv6 router. 1560 @param pinfo Pointer to the ifnet_llreach_info structure where the 1561 information will be returned to, upon success. 1562 @result 0 upon success, otherwise errno error. 1563 */ 1564extern errno_t ifnet_inet6_defrouter_llreachinfo(ifnet_t interface, 1565 struct ifnet_llreach_info *pinfo); 1566#endif /* KERNEL_PRIVATE */ 1567 1568/*! 1569 @function ifnet_set_capabilities_supported 1570 @discussion Specify the capabilities supported by the interface. 1571 @discussion This function lets you specify which capabilities are supported 1572 by the interface. Typically this function is called by the driver when 1573 the interface gets attached to the system. 1574 The mask allows to control which capability to set or unset. 1575 The kernel will effectively take the lock, then set the 1576 interface's flags to (if_capabilities & ~mask) | (new_caps & mask). 1577 1578 This function is intended to be called by the driver. A kext 1579 must not call this function on an interface the kext does not 1580 own. 1581 @param interface Interface to set the capabilities on. 1582 @param new_caps The value of the capabilities that should be set or unset. These 1583 flags are defined in net/if.h 1584 @param mask Which capabilities that should be affected. These 1585 flags are defined in net/if.h 1586 @result 0 on success otherwise the errno error. 1587 */ 1588extern errno_t ifnet_set_capabilities_supported(ifnet_t interface, u_int32_t new_caps, 1589 u_int32_t mask); 1590 1591/*! 1592 @function ifnet_capabilities_supported 1593 @discussion Retrieve the interface capabilities supported by the interface. 1594 @param interface Interface to retrieve the capabilities from. 1595 @result Flags. Capabilities flags are defined in net/if.h 1596 */ 1597extern u_int32_t ifnet_capabilities_supported(ifnet_t interface); 1598 1599/*! 1600 @function ifnet_set_capabilities_enabled 1601 @discussion Enable and/or disable the interface capabilities to match new_caps. 1602 @discussion Sets the interface capabilities to new_caps. This function 1603 lets you specify which capabilities you want to change using the mask. 1604 The kernel will effectively take the lock, then set the 1605 interface's flags to (if_capenable & ~mask) | (new_caps & mask). 1606 1607 This function is intended to be called by the driver. A kext 1608 must not call this function on an interface the kext does not 1609 own. 1610 1611 Typically this function is called by the driver when the interface is 1612 created to specify which of the supported capabilities are enabled by 1613 default. This function is also meant to be called when the driver handles 1614 the interface ioctl SIOCSIFCAP. 1615 1616 The driver should call ifnet_set_offlad() to indicate the corresponding 1617 hardware offload bits that will be used by the networking stack. 1618 1619 It is an error to enable a capability that is not marked as 1620 supported by the interface. 1621 @param interface Interface to set the capabilities on. 1622 @param new_caps The value of the capabilities that should be set or unset. These 1623 flags are defined in net/if.h 1624 @param mask Which capabilities that should be affected. These 1625 flags are defined in net/if.h 1626 @result 0 on success otherwise the errno error. 1627 */ 1628extern errno_t ifnet_set_capabilities_enabled(ifnet_t interface, u_int32_t new_caps, 1629 u_int32_t mask); 1630 1631/*! 1632 @function ifnet_capabilities_enabled 1633 @discussion Retrieve the interface capabilities enabled on the interface. 1634 @param interface Interface to retrieve the capabilities from. 1635 @result Flags. Capabilities flags are defined in net/if.h 1636 */ 1637extern u_int32_t ifnet_capabilities_enabled(ifnet_t interface); 1638 1639 1640/*! 1641 @function ifnet_set_offload 1642 @discussion Sets a bitfield to indicate special hardware offload 1643 support provided by the interface such as hardware checksums and 1644 VLAN. This replaces the if_hwassist flags field. Any flags 1645 unrecognized by the stack will not be set. 1646 1647 Note the system will automatically set the interface capabilities 1648 that correspond to the offload flags modified -- i.e. the driver 1649 does not have to call ifnet_set_capabilities_enabled() and 1650 ifnet_set_capabilities_supported(). 1651 @param interface The interface. 1652 @param offload The new set of flags indicating which offload options 1653 the device supports. 1654 @result 0 on success otherwise the errno error. 1655 */ 1656extern errno_t ifnet_set_offload(ifnet_t interface, ifnet_offload_t offload); 1657 1658/*! 1659 @function ifnet_offload 1660 @discussion Returns flags indicating which operations can be 1661 offloaded to the interface. 1662 @param interface Interface to retrieve the offload from. 1663 @result Abilities flags, see ifnet_offload_t. 1664 */ 1665extern ifnet_offload_t ifnet_offload(ifnet_t interface); 1666 1667/*! 1668 @function ifnet_set_tso_mtu 1669 @discussion Sets maximum TCP Segmentation Offload segment size for 1670 the interface 1671 @param interface The interface. 1672 @param family The family for which the offload MTU is provided for 1673 (AF_INET or AF_INET6) 1674 @param mtuLen Maximum segment size supported by the interface 1675 @result 0 on success otherwise the errno error. 1676*/ 1677extern errno_t ifnet_set_tso_mtu(ifnet_t interface, sa_family_t family, 1678 u_int32_t mtuLen); 1679 1680/*! 1681 @function ifnet_get_tso_mtu 1682 @discussion Returns maximum TCP Segmentation Offload segment size for 1683 the interface 1684 @param interface The interface. 1685 @param family The family for which the offload MTU is provided for 1686 (AF_INET or AF_INET6) 1687 @param mtuLen Value of the maximum MTU supported for the interface 1688 and family provided. 1689 @result 0 on success otherwise the errno error. 1690 */ 1691extern errno_t ifnet_get_tso_mtu(ifnet_t interface, sa_family_t family, 1692 u_int32_t *mtuLen); 1693 1694/*! 1695 @enum Interface wake properties 1696 @abstract Constants defining Interface wake properties. 1697 @constant IFNET_WAKE_ON_MAGIC_PACKET Wake on Magic Packet. 1698*/ 1699enum { 1700 IFNET_WAKE_ON_MAGIC_PACKET = 0x01 1701}; 1702 1703/*! 1704 @function ifnet_set_wake_flags 1705 @discussion Sets the wake properties of the underlying hardware. These are 1706 typically set by the driver. 1707 @param interface The interface. 1708 @param properties Properties to set or unset. 1709 @param mask Mask of the properties to set of unset. 1710 @result 0 on success otherwise the errno error. 1711*/ 1712extern errno_t ifnet_set_wake_flags(ifnet_t interface, u_int32_t properties, u_int32_t mask); 1713 1714/*! 1715 @function ifnet_get_wake_flags 1716 @discussion Returns the wake properties set on the interface. 1717 @param interface The interface. 1718 @result The wake properties 1719*/ 1720extern u_int32_t ifnet_get_wake_flags(ifnet_t interface); 1721 1722/*! 1723 @function ifnet_set_link_mib_data 1724 @discussion Sets the mib link data. The ifnet_t will store the 1725 pointer you supply and copy mibLen bytes from the pointer 1726 whenever the sysctl for getting interface specific MIB data is 1727 used. Since the ifnet_t stores a pointer to your data instead of 1728 a copy, you may update the data at the address at any time. 1729 1730 This function is intended to be called by the driver. A kext 1731 must not call this function on an interface the kext does not 1732 own. 1733 @param interface Interface to set the unit number of. 1734 @param mibData A pointer to the data. 1735 @param mibLen Length of data pointed to. 1736 @result 0 on success otherwise the errno error. 1737*/ 1738extern errno_t ifnet_set_link_mib_data(ifnet_t interface, void *mibData, 1739 u_int32_t mibLen); 1740 1741/*! 1742 @function ifnet_get_link_mib_data 1743 @discussion Copies the link MIB data in to mibData, up to mibLen 1744 bytes. Returns error if the buffer is too small to hold all of 1745 the MIB data. 1746 @param interface The interface. 1747 @param mibData A pointer to space for the mibData to be copied in 1748 to. 1749 @param mibLen When calling, this should be the size of the buffer 1750 passed in mibData. Upon return, this will be the size of data 1751 copied in to mibData. 1752 @result Returns an error if the buffer size is too small or there is 1753 no data. 1754 */ 1755extern errno_t ifnet_get_link_mib_data(ifnet_t interface, void *mibData, 1756 u_int32_t *mibLen); 1757 1758/*! 1759 @function ifnet_get_link_mib_data_length 1760 @discussion Retrieve the size of the mib data. 1761 @param interface The interface. 1762 @result Returns the number of bytes of mib data associated with the 1763 interface. 1764 */ 1765extern u_int32_t ifnet_get_link_mib_data_length(ifnet_t interface); 1766 1767/*! 1768 @function ifnet_attach_protocol 1769 @discussion Attaches a protocol to an interface. 1770 @param interface The interface. 1771 @param protocol_family The protocol family being attached 1772 (PF_INET/PF_APPLETALK/etc...). 1773 @param proto_details Details of the protocol being attached. 1774 @result 0 on success otherwise the errno error. 1775 */ 1776extern errno_t ifnet_attach_protocol(ifnet_t interface, 1777 protocol_family_t protocol_family, 1778 const struct ifnet_attach_proto_param *proto_details); 1779 1780/*! 1781 @function ifnet_attach_protocol_v2 1782 @discussion Attaches a protocol to an interface using the newer 1783 version 2 style interface. So far the only difference is support 1784 for packet chains which improve performance. 1785 @param interface The interface. 1786 @param protocol_family The protocol family being attached 1787 (PF_INET/PF_APPLETALK/etc...). 1788 @param proto_details Details of the protocol being attached. 1789 @result 0 on success otherwise the errno error. 1790 */ 1791extern errno_t ifnet_attach_protocol_v2(ifnet_t interface, 1792 protocol_family_t protocol_family, 1793 const struct ifnet_attach_proto_param_v2 *proto_details); 1794 1795/*! 1796 @function ifnet_detach_protocol 1797 @discussion Detaches a protocol from an interface. 1798 @param interface The interface. 1799 @param protocol_family The protocol family of the protocol to 1800 detach. 1801 @result 0 on success otherwise the errno error. 1802 */ 1803extern errno_t ifnet_detach_protocol(ifnet_t interface, 1804 protocol_family_t protocol_family); 1805 1806/*! 1807 @function ifnet_output 1808 @discussion Handles an outbound packet on the interface by calling 1809 any filters, a protocol preoutput function, the interface framer 1810 function, and finally the interface's output function. The 1811 protocol_family will be used to apply protocol filters and 1812 determine which preoutput function to call. The route and dest 1813 parameters will be passed to the preoutput function defined for 1814 the attachment of the specified protocol to the specified 1815 interface. ifnet_output will always free the mbuf chain. 1816 @param interface The interface. 1817 @param protocol_family The family of the protocol generating this 1818 packet (i.e. AF_INET). 1819 @param packet The packet to be transmitted. 1820 @param route A pointer to a routing structure for this packet. The 1821 preoutput function determines whether this value may be NULL or 1822 not. 1823 @param dest The destination address of protocol_family type. This 1824 will be passed to the preoutput function. If the preoutput 1825 function does not require this value, you may pass NULL. 1826 @result 0 on success otherwise the errno error. 1827 */ 1828extern errno_t ifnet_output(ifnet_t interface, 1829 protocol_family_t protocol_family, mbuf_t packet, void *route, 1830 const struct sockaddr *dest); 1831 1832/*! 1833 @function ifnet_output_raw 1834 @discussion Handles and outbond raw packet on the interface by 1835 calling any filters followed by the interface's output function. 1836 protocol_family may be zero. If the packet is from a specific 1837 protocol the protocol_family will be used to apply protocol 1838 filters. All interface filters will be applied to the outgoing 1839 packet. Processing, such as calling the protocol preoutput and 1840 interface framer functions will be bypassed. The packet will 1841 pass through the filters and be sent on the interface as is. 1842 ifnet_output_raw will always free the packet chain. 1843 @param interface The interface. 1844 @param protocol_family The family of the protocol generating this 1845 packet (i.e. AF_INET). 1846 @param packet The fully formed packet to be transmitted. 1847 @result 0 on success otherwise the errno error. 1848 */ 1849extern errno_t ifnet_output_raw(ifnet_t interface, 1850 protocol_family_t protocol_family, mbuf_t packet); 1851 1852/*! 1853 @function ifnet_input 1854 @discussion Inputs packets from the interface. The interface's demux 1855 will be called to determine the protocol. Once the protocol is 1856 determined, the interface filters and protocol filters will be 1857 called. From there, the packet will be passed to the registered 1858 protocol. If there is an error, the mbuf chain will be freed. 1859 @param interface The interface. 1860 @param first_packet The first packet in a chain of packets. 1861 @param stats Counts to be integrated in to the stats. The interface 1862 statistics will be incremented by the amounts specified in 1863 stats. This parameter may be NULL. 1864 @result 0 on success otherwise the errno error. 1865 */ 1866extern errno_t ifnet_input(ifnet_t interface, mbuf_t first_packet, 1867 const struct ifnet_stat_increment_param *stats); 1868 1869#ifdef KERNEL_PRIVATE 1870/* 1871 @function ifnet_input_extended 1872 @discussion Inputs packets from the interface. The interface's demux 1873 will be called to determine the protocol. Once the protocol is 1874 determined, the interface filters and protocol filters will be 1875 called. From there, the packet will be passed to the registered 1876 protocol. If there is an error, the mbuf chain will be freed. 1877 @param interface The interface. 1878 @param first_packet The first packet in a chain of packets. 1879 @param last_packet The last packet in a chain of packets. This may be 1880 set to NULL if the driver does not have the information. 1881 @param stats Counts to be integrated in to the stats. The interface 1882 statistics will be incremented by the amounts specified in 1883 stats. Unlike ifnet_input(), this parameter is required by 1884 this extended variant. 1885 @result 0 on success otherwise the errno error. 1886 */ 1887extern errno_t ifnet_input_extended(ifnet_t interface, mbuf_t first_packet, 1888 mbuf_t last_packet, const struct ifnet_stat_increment_param *stats); 1889#endif /* KERNEL_PRIVATE */ 1890 1891/*! 1892 @function ifnet_ioctl 1893 @discussion Calls the interface's ioctl function with the parameters 1894 passed. 1895 1896 All undefined ioctls are reserved for future use by Apple. If 1897 you need to communicate with your kext using an ioctl, please 1898 use SIOCSIFKPI and SIOCGIFKPI. 1899 @param interface The interface. 1900 @param protocol The protocol family of the protocol to send the 1901 ioctl to (may be zero). Some ioctls apply to a protocol while 1902 other ioctls apply to just an interface. 1903 @param ioctl_code The ioctl to perform. 1904 @param ioctl_arg Any parameters to the ioctl. 1905 @result 0 on success otherwise the errno error. 1906 */ 1907extern errno_t ifnet_ioctl(ifnet_t interface, protocol_family_t protocol, 1908 unsigned long ioctl_code, void *ioctl_arg); 1909 1910/*! 1911 @function ifnet_event 1912 @discussion Calls the interface's event function. 1913 @param interface The interface. 1914 @param event_ptr Pointer to an kern_event structure describing the 1915 event. 1916 @result 0 on success otherwise the errno error. 1917 */ 1918extern errno_t ifnet_event(ifnet_t interface, struct kern_event_msg *event_ptr); 1919 1920/*! 1921 @function ifnet_set_mtu 1922 @discussion Sets the value of the MTU in the interface structure. 1923 Calling this function will not notify the driver that the MTU 1924 should be changed. Use the appropriate ioctl. 1925 1926 This function is intended to be called by the driver. A kext 1927 must not call this function on an interface the kext does not 1928 own. 1929 @param interface The interface. 1930 @param mtu The new MTU. 1931 @result 0 on success otherwise the errno error. 1932 */ 1933extern errno_t ifnet_set_mtu(ifnet_t interface, u_int32_t mtu); 1934 1935/*! 1936 @function ifnet_mtu 1937 @param interface The interface. 1938 @result The MTU. 1939 */ 1940extern u_int32_t ifnet_mtu(ifnet_t interface); 1941 1942/*! 1943 @function ifnet_type 1944 @param interface The interface. 1945 @result The type. See net/if_types.h. 1946 */ 1947extern u_int8_t ifnet_type(ifnet_t interface); 1948 1949/*! 1950 @function ifnet_set_addrlen 1951 @discussion 1952 This function is intended to be called by the driver. A kext 1953 must not call this function on an interface the kext does not 1954 own. 1955 @param interface The interface. 1956 @param addrlen The new address length. 1957 @result 0 on success otherwise the errno error. 1958 */ 1959extern errno_t ifnet_set_addrlen(ifnet_t interface, u_int8_t addrlen); 1960 1961/*! 1962 @function ifnet_addrlen 1963 @param interface The interface. 1964 @result The address length. 1965 */ 1966extern u_int8_t ifnet_addrlen(ifnet_t interface); 1967 1968/*! 1969 @function ifnet_set_hdrlen 1970 @discussion 1971 This function is intended to be called by the driver. A kext 1972 must not call this function on an interface the kext does not 1973 own. 1974 @param interface The interface. 1975 @param hdrlen The new header length. 1976 @result 0 on success otherwise the errno error. 1977 */ 1978extern errno_t ifnet_set_hdrlen(ifnet_t interface, u_int8_t hdrlen); 1979 1980/*! 1981 @function ifnet_hdrlen 1982 @param interface The interface. 1983 @result The header length. 1984 */ 1985extern u_int8_t ifnet_hdrlen(ifnet_t interface); 1986 1987/*! 1988 @function ifnet_set_metric 1989 @discussion 1990 This function is intended to be called by the driver. A kext 1991 must not call this function on an interface the kext does not 1992 own. 1993 @param interface The interface. 1994 @param metric The new metric. 1995 @result 0 on success otherwise the errno error. 1996 */ 1997extern errno_t ifnet_set_metric(ifnet_t interface, u_int32_t metric); 1998 1999/*! 2000 @function ifnet_metric 2001 @param interface The interface. 2002 @result The metric. 2003 */ 2004extern u_int32_t ifnet_metric(ifnet_t interface); 2005 2006/*! 2007 @function ifnet_set_baudrate 2008 @discussion 2009 This function is intended to be called by the driver. A kext 2010 must not call this function on an interface the kext does not 2011 own. 2012 @param interface The interface. 2013 @param baudrate The new baudrate. 2014 @result 0 on success otherwise the errno error. 2015 */ 2016extern errno_t ifnet_set_baudrate(ifnet_t interface, u_int64_t baudrate); 2017 2018/*! 2019 @function ifnet_baudrate 2020 @param interface The interface. 2021 @result The baudrate. 2022 */ 2023extern u_int64_t ifnet_baudrate(ifnet_t interface); 2024 2025#ifdef KERNEL_PRIVATE 2026typedef struct if_bandwidths if_bandwidths_t; 2027 2028/* 2029 @function ifnet_set_bandwidths 2030 @param interface The interface. 2031 @param output_bw The output bandwidth values (in bits per second). 2032 May be set to NULL if the caller does not want to alter the 2033 existing output bandwidth values. 2034 @param input_bw The input bandwidth values (in bits per second). 2035 May be set to NULL if the caller does not want to alter the 2036 existing input bandwidth values. 2037 @result 0 on success otherwise the errno error. 2038 */ 2039extern errno_t ifnet_set_bandwidths(ifnet_t interface, 2040 if_bandwidths_t *output_bw, if_bandwidths_t *input_bw); 2041 2042/* 2043 @function ifnet_bandwidths 2044 @param interface The interface. 2045 @param output_bw The output bandwidth values (in bits per second). 2046 May be set to NULL if the caller does not want to retrieve the 2047 output bandwidth value. 2048 @param input_bw The input bandwidth values (in bits per second). 2049 May be set to NULL if the caller does not want to retrieve the 2050 input bandwidth value. 2051 @result 0 on success otherwise the errno error. 2052 */ 2053extern errno_t ifnet_bandwidths(ifnet_t interface, if_bandwidths_t *output_bw, 2054 if_bandwidths_t *input_bw); 2055#endif /* KERNEL_PRIVATE */ 2056 2057/*! 2058 @function ifnet_stat_increment 2059 @discussion 2060 This function is intended to be called by the driver. A kext 2061 must not call this function on an interface the kext does not 2062 own. 2063 @param interface The interface. 2064 @param counts A pointer to a structure containing the amount to 2065 increment each counter by. Any counts not appearing in the 2066 ifnet_counter_increment structure are handled in the stack. 2067 @result 0 on success otherwise the errno error. 2068 */ 2069extern errno_t ifnet_stat_increment(ifnet_t interface, 2070 const struct ifnet_stat_increment_param *counts); 2071 2072/*! 2073 @function ifnet_stat_increment_in 2074 @discussion 2075 This function is intended to be called by the driver. This 2076 function allows a driver to update the inbound interface counts. 2077 The most efficient time to update these counts is when calling 2078 ifnet_input. 2079 2080 A lock protects the counts, this makes the increment functions 2081 expensive. The increment function will update the lastchanged 2082 value. 2083 @param interface The interface. 2084 @param packets_in The number of additional packets received. 2085 @param bytes_in The number of additional bytes received. 2086 @param errors_in The number of additional receive errors. 2087 @result 0 on success otherwise the errno error. 2088 */ 2089extern errno_t ifnet_stat_increment_in(ifnet_t interface, 2090 u_int32_t packets_in, u_int32_t bytes_in, u_int32_t errors_in); 2091 2092/*! 2093 @function ifnet_stat_increment_out 2094 @discussion 2095 This function is intended to be called by the driver. This 2096 function allows a driver to update the outbound interface 2097 counts. 2098 2099 A lock protects the counts, this makes the increment functions 2100 expensive. The increment function will update the lastchanged 2101 value. 2102 @param interface The interface. 2103 @param packets_out The number of additional packets sent. 2104 @param bytes_out The number of additional bytes sent. 2105 @param errors_out The number of additional send errors. 2106 @result 0 on success otherwise the errno error. 2107 */ 2108extern errno_t ifnet_stat_increment_out(ifnet_t interface, 2109u_int32_t packets_out, u_int32_t bytes_out, u_int32_t errors_out); 2110 2111/*! 2112 @function ifnet_set_stat 2113 @discussion 2114 This function is intended to be called by the driver. A kext 2115 must not call this function on an interface the kext does not 2116 own. 2117 2118 The one exception would be the case where a kext wants to zero 2119 all of the counters. 2120 @param interface The interface. 2121 @param counts The new stats values. 2122 @result 0 on success otherwise the errno error. 2123 */ 2124extern errno_t ifnet_set_stat(ifnet_t interface, 2125 const struct ifnet_stats_param *stats); 2126 2127/*! 2128 @function ifnet_stat 2129 @param interface The interface. 2130 @param out_stats Storage for the values. 2131 @result 0 on success otherwise the errno error. 2132 */ 2133extern errno_t ifnet_stat(ifnet_t interface, 2134 struct ifnet_stats_param *out_stats); 2135 2136/*! 2137 @function ifnet_set_promiscuous 2138 @discussion Enable or disable promiscuous mode on the interface. The 2139 interface keeps an internal count of the number of times 2140 promiscuous mode has been enabled. Promiscuous mode is only 2141 disabled when this count reaches zero. Be sure to disable 2142 promiscuous mode only once for every time you enable it. 2143 @param interface The interface to toggle promiscuous mode on. 2144 @param on If set, the number of promicuous on requests will be 2145 incremented. If this is the first requrest, promiscuous mode 2146 will be enabled. If this is not set, the number of promiscous 2147 clients will be decremented. If this causes the number to reach 2148 zero, promiscuous mode will be disabled. 2149 @result 0 on success otherwise the errno error. 2150 */ 2151extern errno_t ifnet_set_promiscuous(ifnet_t interface, int on); 2152 2153/*! 2154 @function ifnet_touch_lastchange 2155 @discussion Updates the lastchange value to now. 2156 @param interface The interface. 2157 @result 0 on success otherwise the errno error. 2158 */ 2159extern errno_t ifnet_touch_lastchange(ifnet_t interface); 2160 2161/*! 2162 @function ifnet_lastchange 2163 @param interface The interface. 2164 @param last_change A timeval struct to copy the last time changed in 2165 to. 2166 */ 2167extern errno_t ifnet_lastchange(ifnet_t interface, struct timeval *last_change); 2168 2169/*! 2170 @function ifnet_get_address_list 2171 @discussion Get a list of addresses on the interface. Passing NULL 2172 for the interface will return a list of all addresses. The 2173 addresses will have their reference count bumped so they will 2174 not go away. Calling ifnet_free_address_list will decrement the 2175 refcount and free the array. If you wish to hold on to a 2176 reference to an ifaddr_t, be sure to bump the reference count 2177 before calling ifnet_free_address_list. 2178 @param interface The interface. 2179 @param addresses A pointer to a NULL terminated array of ifaddr_ts. 2180 @result 0 on success otherwise the errno error. 2181 */ 2182extern errno_t ifnet_get_address_list(ifnet_t interface, ifaddr_t **addresses); 2183 2184/*! 2185 @function ifnet_get_address_list_family 2186 @discussion Get a list of addresses on the interface. Passing NULL 2187 for the interface will return a list of all addresses. The 2188 addresses will have their reference count bumped so they will 2189 not go away. Calling ifnet_free_address_list will decrement the 2190 refcount and free the array. If you wish to hold on to a 2191 reference to an ifaddr_t, be sure to bump the reference count 2192 before calling ifnet_free_address_list. Unlike 2193 ifnet_get_address_list, this function lets the caller specify 2194 the address family to get a list of only a specific address type. 2195 @param interface The interface. 2196 @param addresses A pointer to a NULL terminated array of ifaddr_ts. 2197 @result 0 on success otherwise the errno error. 2198 */ 2199extern errno_t ifnet_get_address_list_family(ifnet_t interface, 2200 ifaddr_t **addresses, sa_family_t family); 2201 2202#ifdef KERNEL_PRIVATE 2203__private_extern__ errno_t ifnet_get_address_list_family_internal(ifnet_t, 2204 ifaddr_t **, sa_family_t, int, int); 2205#endif /* KERNEL_PRIVATE */ 2206 2207/*! 2208 @function ifnet_free_address_list 2209 @discussion Free a list of addresses returned from 2210 ifnet_get_address_list. Decrements the refcounts and frees the 2211 memory used for the array of references. 2212 @param addresses An array of ifaddr_ts. 2213 */ 2214extern void ifnet_free_address_list(ifaddr_t *addresses); 2215 2216/*! 2217 @function ifnet_set_lladdr 2218 @discussion Sets the link-layer address for this interface. 2219 @param interface The interface the link layer address is being 2220 changed on. 2221 @param lladdr A pointer to the raw link layer address (pointer to 2222 the 6 byte ethernet address for ethernet). 2223 @param lladdr_len The length, in bytes, of the link layer address. 2224 */ 2225extern errno_t ifnet_set_lladdr(ifnet_t interface, const void *lladdr, 2226 size_t lladdr_len); 2227 2228/*! 2229 @function ifnet_lladdr_copy_bytes 2230 @discussion Copies the bytes of the link-layer address in to the 2231 specified buffer. 2232 @param interface The interface to copy the link-layer address from. 2233 @param lladdr The buffer to copy the link-layer address in to. 2234 @param length The length of the buffer. This value must match the 2235 length of the link-layer address. 2236 */ 2237extern errno_t ifnet_lladdr_copy_bytes(ifnet_t interface, void *lladdr, 2238 size_t length); 2239 2240#ifdef KERNEL_PRIVATE 2241/*! 2242 @function ifnet_lladdr 2243 @discussion Returns a pointer to the link-layer address. 2244 @param interface The interface the link-layer address is on. 2245 */ 2246extern void *ifnet_lladdr(ifnet_t interface); 2247#endif /* KERNEL_PRIVATE */ 2248 2249/*! 2250 @function ifnet_llbroadcast_copy_bytes 2251 @discussion Retrieves the link-layer broadcast address for this 2252 interface. 2253 @param interface The interface. 2254 @param addr A buffer to copy the broadcast address in to. 2255 @param bufferlen The length of the buffer at addr. 2256 @param addr_len On return, the length of the broadcast address. 2257 @param lladdr_len The length, in bytes, of the link layer address. 2258 */ 2259extern errno_t ifnet_llbroadcast_copy_bytes(ifnet_t interface, void *addr, 2260 size_t bufferlen, size_t *addr_len); 2261 2262#ifdef KERNEL_PRIVATE 2263/*! 2264 @function ifnet_set_lladdr_and_type 2265 @discussion Sets the link-layer address as well as the type field in 2266 the sockaddr_dl. Support for setting the type was added for vlan 2267 and bond interfaces. 2268 @param interface The interface the link layer address is being 2269 changed on. 2270 @param lladdr A pointer to the raw link layer address (pointer to 2271 the 6 byte ethernet address for ethernet). 2272 @param lladdr_len The length, in bytes, of the link layer address. 2273 @param type The link-layer address type. 2274 */ 2275extern errno_t ifnet_set_lladdr_and_type(ifnet_t interface, const void *lladdr, 2276 size_t length, u_char type); 2277#endif /* KERNEL_PRIVATE */ 2278 2279/*! 2280 @function ifnet_resolve_multicast 2281 @discussion Resolves a multicast address for an attached protocol to 2282 a link-layer address. If a link-layer address is passed in, the 2283 interface will verify that it is a valid multicast address. 2284 @param interface The interface. 2285 @param proto_addr A protocol address to be converted to a link-layer 2286 address. 2287 @param ll_addr Storage for the resulting link-layer address. 2288 @param ll_len Length of the storage for the link-layer address. 2289 @result 0 on success. EOPNOTSUPP indicates the multicast address was 2290 not supported or could not be translated. Other errors may 2291 indicate other failures. 2292 */ 2293extern errno_t ifnet_resolve_multicast(ifnet_t ifp, 2294 const struct sockaddr *proto_addr, struct sockaddr *ll_addr, size_t ll_len); 2295 2296/*! 2297 @function ifnet_add_multicast 2298 @discussion Joins a multicast and returns an ifmultiaddr_t with the 2299 reference count incremented for you. You are responsible for 2300 decrementing the reference count after calling 2301 ifnet_remove_multicast and making sure you no longer have any 2302 references to the multicast. 2303 @param interface The interface. 2304 @param maddr The multicast address (AF_UNSPEC/AF_LINK) to join. Either 2305 a physical address or logical address to be translated to a 2306 physical address. 2307 @param multicast The resulting ifmultiaddr_t multicast address. 2308 @result 0 on success otherwise the errno error. 2309 */ 2310extern errno_t ifnet_add_multicast(ifnet_t interface, 2311 const struct sockaddr *maddr, ifmultiaddr_t *multicast); 2312 2313/*! 2314 @function ifnet_remove_multicast 2315 @discussion Causes the interface to leave the multicast group. The 2316 stack keeps track of how many times ifnet_add_multicast has been 2317 called for a given multicast address. The multicast will only be 2318 removed when the number of times ifnet_remove_multicast has been 2319 called matches the number of times ifnet_add_multicast has been 2320 called. 2321 2322 The memory for the multicast address is not actually freed until 2323 the separate reference count has reached zero. Some parts of the 2324 stack may keep a pointer to the multicast even after that 2325 multicast has been removed from the interface. 2326 2327 When an interface is detached, all of the multicasts are 2328 removed. If the interface of the multicast passed in is no 2329 longer attached, this function will gracefully return, 2330 performing no work. 2331 2332 It is the callers responsibility to release the multicast 2333 address after calling this function. 2334 @param multicast The multicast to be removed. 2335 @result 0 on success otherwise the errno error. 2336 */ 2337extern errno_t ifnet_remove_multicast(ifmultiaddr_t multicast); 2338 2339/*! 2340 @function ifnet_get_multicast_list 2341 @discussion Retrieves a list of multicast address the interface is 2342 set to receive. This function allocates and returns an array of 2343 references to the various multicast addresses. The multicasts 2344 have their reference counts bumped on your behalf. Calling 2345 ifnet_free_multicast_list will decrement the reference counts 2346 and free the array. 2347 @param interface The interface. 2348 @param multicasts A pointer to a NULL terminated array of references 2349 to the multicast addresses. 2350 @result 0 on success otherwise the errno error. 2351 */ 2352extern errno_t ifnet_get_multicast_list(ifnet_t interface, 2353 ifmultiaddr_t **addresses); 2354 2355/*! 2356 @function ifnet_free_multicast_list 2357 @discussion Frees a list of multicasts returned by 2358 ifnet_get_multicast_list. Decrements the refcount on each 2359 multicast address and frees the array. 2360 @param multicasts An array of references to the multicast addresses. 2361 @result 0 on success otherwise the errno error. 2362 */ 2363extern void ifnet_free_multicast_list(ifmultiaddr_t *multicasts); 2364 2365/*! 2366 @function ifnet_find_by_name 2367 @discussion Find an interface by the name including the unit number. 2368 Caller must call ifnet_release on any non-null interface return 2369 value. 2370 @param name The name of the interface, including any unit number 2371 (i.e. "en0"). 2372 @param interface A pointer to an interface reference. This will be 2373 filled in if a matching interface is found. 2374 @result 0 on success otherwise the errno error. 2375 */ 2376extern errno_t ifnet_find_by_name(const char *ifname, ifnet_t *interface); 2377 2378/*! 2379 @function ifnet_list_get 2380 @discussion Get a list of attached interfaces. List will be set to 2381 point to an array allocated by ifnet_list_get. The interfaces 2382 are refcounted and the counts will be incremented before the 2383 function returns. The list of interfaces must be freed using 2384 ifnet_list_free. 2385 @param family The interface family (i.e. IFNET_FAMILY_ETHERNET). To 2386 find interfaces of all families, use IFNET_FAMILY_ANY. 2387 @param interfaces A pointer to an array of interface references. 2388 @param count A pointer that will be filled in with the number of 2389 matching interfaces in the array. 2390 @result 0 on success otherwise the errno error. 2391 */ 2392extern errno_t ifnet_list_get(ifnet_family_t family, ifnet_t **interfaces, 2393 u_int32_t *count); 2394 2395#ifdef KERNEL_PRIVATE 2396/*! 2397 @function ifnet_list_get_all 2398 @discussion Get a list of attached interfaces. List will be set to 2399 point to an array allocated by ifnet_list_get. The interfaces 2400 are refcounted and the counts will be incremented before the 2401 function returns. The list of interfaces must be freed using 2402 ifnet_list_free. This is similar to ifnet_list_get, except 2403 that it includes interfaces that are detaching. 2404 @param family The interface family (i.e. IFNET_FAMILY_ETHERNET). To 2405 find interfaces of all families, use IFNET_FAMILY_ANY. 2406 @param interfaces A pointer to an array of interface references. 2407 @param count A pointer that will be filled in with the number of 2408 matching interfaces in the array. 2409 @result 0 on success otherwise the errno error. 2410 */ 2411extern errno_t ifnet_list_get_all(ifnet_family_t family, ifnet_t **interfaces, 2412 u_int32_t *count); 2413#endif /* KERNEL_PRIVATE */ 2414 2415/*! 2416 @function ifnet_list_free 2417 @discussion Free a list of interfaces returned by ifnet_list_get. 2418 Decrements the reference count on each interface and frees the 2419 array of references. If you keep a reference to an interface, be 2420 sure to increment the reference count before calling 2421 ifnet_list_free. 2422 @param interfaces An array of interface references from ifnet_list_get. 2423 */ 2424extern void ifnet_list_free(ifnet_t *interfaces); 2425 2426/******************************************************************************/ 2427/* ifaddr_t accessors */ 2428/******************************************************************************/ 2429 2430/*! 2431 @function ifaddr_reference 2432 @discussion Increment the reference count of an address tied to an 2433 interface. 2434 @param ifaddr The interface address. 2435 @result 0 upon success 2436 */ 2437extern errno_t ifaddr_reference(ifaddr_t ifaddr); 2438 2439/*! 2440 @function ifaddr_release 2441 @discussion Decrements the reference count of and possibly frees an 2442 address tied to an interface. 2443 @param ifaddr The interface address. 2444 @result 0 upon success 2445 */ 2446extern errno_t ifaddr_release(ifaddr_t ifaddr); 2447 2448/*! 2449 @function ifaddr_address 2450 @discussion Copies the address out of the ifaddr. 2451 @param ifaddr The interface address. 2452 @param out_addr The sockaddr storage for the address. 2453 @param addr_size The size of the storage for the address. 2454 @result 0 upon success 2455 */ 2456extern errno_t ifaddr_address(ifaddr_t ifaddr, struct sockaddr *out_addr, 2457 u_int32_t addr_size); 2458 2459/*! 2460 @function ifaddr_address 2461 @discussion Returns the address family of the address. 2462 @param ifaddr The interface address. 2463 @result 0 on failure, address family on success. 2464 */ 2465extern sa_family_t ifaddr_address_family(ifaddr_t ifaddr); 2466 2467/*! 2468 @function ifaddr_dstaddress 2469 @discussion Copies the destination address out of the ifaddr. 2470 @param ifaddr The interface address. 2471 @param out_dstaddr The sockaddr storage for the destination address. 2472 @param dstaddr_size The size of the storage for the destination address. 2473 @result 0 upon success 2474 */ 2475extern errno_t ifaddr_dstaddress(ifaddr_t ifaddr, struct sockaddr *out_dstaddr, 2476 u_int32_t dstaddr_size); 2477 2478/*! 2479 @function ifaddr_netmask 2480 @discussion Copies the netmask out of the ifaddr. 2481 @param ifaddr The interface address. 2482 @param out_netmask The sockaddr storage for the netmask. 2483 @param netmask_size The size of the storage for the netmask. 2484 @result 0 upon success 2485 */ 2486extern errno_t ifaddr_netmask(ifaddr_t ifaddr, struct sockaddr *out_netmask, 2487 u_int32_t netmask_size); 2488 2489/*! 2490 @function ifaddr_ifnet 2491 @discussion Returns the interface the address is attached to. The 2492 reference is only valid until the ifaddr is released. If you 2493 need to hold a reference to the ifnet for longer than you hold a 2494 reference to the ifaddr, increment the reference using 2495 ifnet_reference. 2496 @param ifaddr The interface address. 2497 @result A reference to the interface the address is attached to. 2498 */ 2499extern ifnet_t ifaddr_ifnet(ifaddr_t ifaddr); 2500 2501/*! 2502 @function ifaddr_withaddr 2503 @discussion Returns an interface address with the address specified. 2504 Increments the reference count on the ifaddr before returning to 2505 the caller. Caller is responsible for calling ifaddr_release. 2506 @param address The address to search for. 2507 @result A reference to the interface address. 2508 */ 2509extern ifaddr_t ifaddr_withaddr(const struct sockaddr *address); 2510 2511/*! 2512 @function ifaddr_withdstaddr 2513 @discussion Returns an interface address for the interface address 2514 that matches the destination when the netmask is applied. 2515 Increments the reference count on the ifaddr before returning to 2516 the caller. Caller is responsible for calling ifaddr_release. 2517 @param destination The destination to search for. 2518 @result A reference to the interface address. 2519 */ 2520extern ifaddr_t ifaddr_withdstaddr(const struct sockaddr *destination); 2521 2522/*! 2523 @function ifaddr_withnet 2524 @discussion Returns an interface address for the interface with the 2525 network described by net. Increments the reference count on the 2526 ifaddr before returning to the caller. Caller is responsible for 2527 calling ifaddr_release. 2528 @param net The network to search for. 2529 @result A reference to the interface address. 2530 */ 2531extern ifaddr_t ifaddr_withnet(const struct sockaddr *net); 2532 2533/*! 2534 @function ifaddr_withroute 2535 @discussion Returns an interface address given a destination and 2536 gateway. Increments the reference count on the ifaddr before 2537 returning to the caller. Caller is responsible for calling 2538 ifaddr_release. 2539 @param flags Routing flags. See net/route.h, RTF_GATEWAY etc. 2540 @param destination The destination to search for. 2541 @param gateway A gateway to search for. 2542 @result A reference to the interface address. 2543 */ 2544extern ifaddr_t ifaddr_withroute(int flags, const struct sockaddr *destination, 2545 const struct sockaddr *gateway); 2546 2547/*! 2548 @function ifaddr_findbestforaddr 2549 @discussion Finds the best local address assigned to a specific 2550 interface to use when communicating with another address. 2551 Increments the reference count on the ifaddr before returning to 2552 the caller. Caller is responsible for calling ifaddr_release. 2553 @param addr The remote address. 2554 @param interface The local interface. 2555 @result A reference to the interface address. 2556 */ 2557extern ifaddr_t ifaddr_findbestforaddr(const struct sockaddr *addr, 2558 ifnet_t interface); 2559 2560/******************************************************************************/ 2561/* ifmultiaddr_t accessors */ 2562/******************************************************************************/ 2563 2564/*! 2565 @function ifmaddr_reference 2566 @discussion Increment the reference count of an interface multicast 2567 address. 2568 @param ifmaddr The interface multicast address. 2569 @result 0 on success. Only error will be EINVAL if ifmaddr is not valid. 2570 */ 2571extern errno_t ifmaddr_reference(ifmultiaddr_t ifmaddr); 2572 2573/*! 2574 @function ifmaddr_release 2575 @discussion Decrement the reference count of an interface multicast 2576 address. If the reference count reaches zero, the ifmultiaddr 2577 will be removed from the interface and the ifmultiaddr will be 2578 freed. 2579 @param ifmaddr The interface multicast address. 2580 @result 0 on success. Only error will be EINVAL if ifmaddr is not valid. 2581 */ 2582extern errno_t ifmaddr_release(ifmultiaddr_t ifmaddr); 2583 2584/*! 2585 @function ifmaddr_address 2586 @discussion Copies the multicast address to out_multicast. 2587 @param out_multicast Storage for a sockaddr. 2588 @param addr_size Size of the storage. 2589 @result 0 on success. 2590 */ 2591extern errno_t ifmaddr_address(ifmultiaddr_t ifmaddr, 2592 struct sockaddr *out_multicast, u_int32_t addr_size); 2593 2594/*! 2595 @function ifmaddr_lladdress 2596 @discussion Copies the link layer multicast address to 2597 out_link_layer_multicast. 2598 @param out_link_layer_multicast Storage for a sockaddr. 2599 @param addr_size Size of the storage. 2600 @result 0 on success. 2601 */ 2602extern errno_t ifmaddr_lladdress(ifmultiaddr_t ifmaddr, 2603 struct sockaddr *out_link_layer_multicast, u_int32_t addr_size); 2604 2605/*! 2606 @function ifmaddr_ifnet 2607 @discussion Returns the interface this multicast address is attached 2608 to. The interface reference count is not bumped by this 2609 function. The interface is only valid as long as you don't 2610 release the refernece to the multiast address. If you need to 2611 maintain your pointer to the ifnet, call ifnet_reference 2612 followed by ifnet_release when you're finished. 2613 @param ifmaddr The interface multicast address. 2614 @result A reference to the interface. 2615 */ 2616extern ifnet_t ifmaddr_ifnet(ifmultiaddr_t ifmaddr); 2617 2618#ifdef KERNEL_PRIVATE 2619/******************************************************************************/ 2620/* interface cloner */ 2621/******************************************************************************/ 2622 2623/* 2624 @typedef ifnet_clone_create_func 2625 @discussion ifnet_clone_create_func is called to create an interface. 2626 @param ifcloner The interface cloner. 2627 @param unit The interface unit number to create. 2628 @param params Additional information specific to the interface cloner. 2629 @result Return zero on success or an errno error value on failure. 2630 */ 2631typedef errno_t (*ifnet_clone_create_func)(if_clone_t ifcloner, u_int32_t unit, void *params); 2632 2633/* 2634 @typedef ifnet_clone_destroy_func 2635 @discussion ifnet_clone_create_func is called to destroy an interface created 2636 by an interface cloner. 2637 @param interface The interface to destroy. 2638 @result Return zero on success or an errno error value on failure. 2639 */ 2640typedef errno_t (*ifnet_clone_destroy_func)(ifnet_t interface); 2641 2642/* 2643 @struct ifnet_clone_params 2644 @discussion This structure is used to represent an interface cloner. 2645 @field ifc_name The interface name handled by this interface cloner. 2646 @field ifc_create The function to create an interface. 2647 @field ifc_destroy The function to destroy an interface. 2648*/ 2649struct ifnet_clone_params { 2650 const char *ifc_name; 2651 ifnet_clone_create_func ifc_create; 2652 ifnet_clone_destroy_func ifc_destroy; 2653}; 2654 2655/* 2656 @function ifnet_clone_attach 2657 @discussion Attaches a new interface cloner. 2658 @param cloner_params The structure that defines an interface cloner. 2659 @param interface A pointer to an opaque handle that represent the interface cloner 2660 that is attached upon success. 2661 @result Returns 0 on success. 2662 May return ENOBUFS if there is insufficient memory. 2663 May return EEXIST if an interface cloner with the same name is already attached. 2664 */ 2665extern errno_t ifnet_clone_attach(struct ifnet_clone_params *cloner_params, if_clone_t *ifcloner); 2666 2667/* 2668 @function ifnet_clone_detach 2669 @discussion Detaches a previously attached interface cloner. 2670 @param ifcloner The opaque handle returned when the interface cloner was attached. 2671 @result Returns 0 on success. 2672 */ 2673extern errno_t ifnet_clone_detach(if_clone_t ifcloner); 2674 2675/******************************************************************************/ 2676/* misc */ 2677/******************************************************************************/ 2678 2679/* 2680 @function ifnet_get_local_ports 2681 @discussion Returns a bitfield indicating which ports have sockets 2682 open. An interface that supports waking the host on unicast traffic may 2683 use this information to discard incoming unicast packets that don't have 2684 a corresponding bit set instead of waking up the host. For port 0x0001, 2685 bit 1 of the first byte would be set. For port n, bit 1 << (n % 8) of 2686 the (n / 8)'th byte would be set. 2687 @param ifp The interface in question. 2688 @param bitfield A pointer to 8192 bytes. 2689 @result Returns 0 on success. 2690 */ 2691extern errno_t ifnet_get_local_ports(ifnet_t ifp, uint8_t *bitfield); 2692/******************************************************************************/ 2693/* for interfaces that support dynamic node absence/presence events */ 2694/******************************************************************************/ 2695 2696/* 2697 @function ifnet_notice_node_presence 2698 @discussion Provided for network interface drivers to notify the 2699 system of a change detected in the presence of the specified 2700 node. 2701 @param ifp The interface attached to the link where the specified node 2702 is present. 2703 @param sa The AF_LINK family address of the node whose presence is 2704 changing. 2705 @param rssi The received signal strength indication as measured in 2706 dBm by a radio receiver. 2707 @param lqm A link quality metric associated with the specified node. 2708 @param npm A node proximity metric associated with the specified node. 2709 @param srvinfo A fixed-size array of octets containing opaque service 2710 information data used by the mDNS responder subsystem. 2711 @result Returns 0 on success, or EINVAL if arguments are invalid. 2712 */ 2713extern errno_t 2714ifnet_notice_node_presence(ifnet_t ifp, struct sockaddr* sa, int32_t rssi, 2715 int lqm, int npm, u_int8_t srvinfo[48]); 2716 2717/* 2718 @function ifnet_notice_node_absence 2719 @discussion Provided for network interface drivers to notify the 2720 system that the absence of the specified node has been detected. 2721 @param ifp The interface attached to the link where the absence of the 2722 specified node has been detected. 2723 @param sa The AF_LINK family address of the node whose absence has been 2724 detected. 2725 @result Returns 0 on success, or EINVAL if arguments are invalid. 2726 */ 2727extern errno_t ifnet_notice_node_absence(ifnet_t ifp, struct sockaddr* sa); 2728 2729/* 2730 @function ifnet_notice_master_elected 2731 @discussion Provided for network interface drivers to notify the system 2732 that the nodes with a locally detected presence on the attached 2733 link have elected a new master. 2734 @param ifp The interface attached to the link where the new master has 2735 been elected. 2736 @result Returns 0 on success, or EINVAL if arguments are invalid. 2737 */ 2738extern errno_t ifnet_notice_master_elected(ifnet_t ifp); 2739 2740#endif /* KERNEL_PRIVATE */ 2741 2742__END_DECLS 2743 2744#endif /* __KPI_INTERFACE__ */ 2745 2746