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