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