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