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