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