1/* 2 * Copyright (c) 2004 Apple Computer, 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#include <sys/kernel_types.h> 38 39#ifndef _SA_FAMILY_T 40#define _SA_FAMILY_T 41typedef __uint8_t sa_family_t; 42#endif 43 44struct timeval; 45struct sockaddr; 46struct sockaddr_dl; 47struct kern_event_msg; 48struct kev_msg; 49struct ifnet_demux_desc; 50 51/*! 52 @enum Interface Families 53 @abstract Constants defining interface families. 54 @constant IFNET_FAMILY_ANY Match interface of any family type. 55 @constant IFNET_FAMILY_LOOPBACK A software loopback interface. 56 @constant IFNET_FAMILY_ETHERNET An Ethernet interface. 57 @constant IFNET_FAMILY_SLIP A SLIP interface. 58 @constant IFNET_FAMILY_TUN A tunnel interface. 59 @constant IFNET_FAMILY_VLAN A virtual LAN interface. 60 @constant IFNET_FAMILY_PPP A PPP interface. 61 @constant IFNET_FAMILY_PVC A PVC interface. 62 @constant IFNET_FAMILY_DISC A DISC interface. 63 @constant IFNET_FAMILY_MDECAP A MDECAP interface. 64 @constant IFNET_FAMILY_GIF A generic tunnel interface. 65 @constant IFNET_FAMILY_FAITH A FAITH (IPv4/IPv6 translation) interface. 66 @constant IFNET_FAMILY_STF A 6to4 interface. 67 @constant IFNET_FAMILY_FIREWIRE An IEEE 1394 (firewire) interface. 68 @constant IFNET_FAMILY_BOND A virtual bonded interface. 69*/ 70 71enum { 72 IFNET_FAMILY_ANY = 0, 73 IFNET_FAMILY_LOOPBACK = 1, 74 IFNET_FAMILY_ETHERNET = 2, 75 IFNET_FAMILY_SLIP = 3, 76 IFNET_FAMILY_TUN = 4, 77 IFNET_FAMILY_VLAN = 5, 78 IFNET_FAMILY_PPP = 6, 79 IFNET_FAMILY_PVC = 7, 80 IFNET_FAMILY_DISC = 8, 81 IFNET_FAMILY_MDECAP = 9, 82 IFNET_FAMILY_GIF = 10, 83 IFNET_FAMILY_FAITH = 11, 84 IFNET_FAMILY_STF = 12, 85 IFNET_FAMILY_FIREWIRE = 13, 86 IFNET_FAMILY_BOND = 14 87}; 88/*! 89 @typedef ifnet_family_t 90 @abstract Storage type for the interface family. 91*/ 92typedef u_int32_t ifnet_family_t; 93 94#ifndef BPF_TAP_MODE_T 95#define BPF_TAP_MODE_T 96/*! 97 @enum BPF tap mode 98 @abstract Constants defining interface families. 99 @constant BPF_MODE_DISABLED Disable bpf. 100 @constant BPF_MODE_INPUT Enable input only. 101 @constant BPF_MODE_OUTPUT Enable output only. 102 @constant BPF_MODE_INPUT_OUTPUT Enable input and output. 103*/ 104 105enum { 106 BPF_MODE_DISABLED = 0, 107 BPF_MODE_INPUT = 1, 108 BPF_MODE_OUTPUT = 2, 109 BPF_MODE_INPUT_OUTPUT = 3 110}; 111/*! 112 @typedef bpf_tap_mode 113 @abstract Mode for tapping. BPF_MODE_DISABLED/BPF_MODE_INPUT_OUTPUT etc. 114*/ 115typedef u_int32_t bpf_tap_mode; 116#endif /* !BPF_TAP_MODE_T */ 117 118/*! 119 @typedef protocol_family_t 120 @abstract Storage type for the protocol family. 121*/ 122typedef u_int32_t protocol_family_t; 123 124/*! 125 @enum Interface Abilities 126 @abstract Constants defining interface offload support. 127 @constant IFNET_CSUM_IP Hardware will calculate IPv4 checksums. 128 @constant IFNET_CSUM_TCP Hardware will calculate TCP checksums. 129 @constant IFNET_CSUM_UDP Hardware will calculate UDP checksums. 130 @constant IFNET_CSUM_FRAGMENT Hardware will checksum IP fragments. 131 @constant IFNET_IP_FRAGMENT Hardware will fragment IP packets. 132 @constant IFNET_VLAN_TAGGING Hardware will generate VLAN headers. 133 @constant IFNET_VLAN_MTU Hardware supports VLAN MTU. 134 @constant IFNET_MULTIPAGES Driver is capable of handling packets 135 coming down from the network stack that reside in virtually, 136 but not in physically contiguous span of the external mbuf 137 clusters. In this case, the data area of a packet in the 138 external mbuf cluster might cross one or more physical 139 pages that are disjoint, depending on the interface MTU 140 and the packet size. Such a use of larger than system page 141 size clusters by the network stack is done for better system 142 efficiency. Drivers that utilize the IOMbufNaturalMemoryCursor 143 with the getPhysicalSegmentsWithCoalesce interfaces and 144 enumerate the list of vectors should set this flag for 145 possible gain in performance during bulk data transfer. 146*/ 147 148enum { 149 IFNET_CSUM_IP = 0x00000001, 150 IFNET_CSUM_TCP = 0x00000002, 151 IFNET_CSUM_UDP = 0x00000004, 152 IFNET_CSUM_FRAGMENT = 0x00000008, 153 IFNET_IP_FRAGMENT = 0x00000010, 154#ifdef KERNEL_PRIVATE 155 IFNET_CSUM_SUM16 = 0x00001000, 156#endif 157 IFNET_VLAN_TAGGING = 0x00010000, 158 IFNET_VLAN_MTU = 0x00020000, 159 IFNET_MULTIPAGES = 0x00100000, 160}; 161/*! 162 @typedef ifnet_offload_t 163 @abstract Flags indicating the offload support of the interface. 164*/ 165typedef u_int32_t ifnet_offload_t; 166 167/* 168 * Callbacks 169 * 170 * These are function pointers you supply to the kernel in the interface. 171 */ 172/*! 173 @typedef bpf_packet_func 174 175 @discussion bpf_packet_func The bpf_packet_func is used to intercept 176 inbound and outbound packets. The tap function will never free 177 the mbuf. The tap function will only copy the mbuf in to various 178 bpf file descriptors tapping this interface. 179 @param interface The interface being sent or received on. 180 @param data The packet to be transmitted or received. 181 @result An errno value or zero upon success. 182 */ 183/* Fast path - do not block or spend excessive amounts of time */ 184typedef errno_t (*bpf_packet_func)(ifnet_t interface, mbuf_t data); 185 186/*! 187 @typedef ifnet_output_func 188 189 @discussion ifnet_output_func is used to transmit packets. The stack 190 will pass fully formed packets, including frame header, to the 191 ifnet_output function for an interface. The driver is 192 responsible for freeing the mbuf. 193 @param interface The interface being sent on. 194 @param data The packet to be sent. 195 */ 196/* Fast path - do not block or spend excessive amounts of time */ 197typedef errno_t (*ifnet_output_func)(ifnet_t interface, mbuf_t data); 198 199/*! 200 @typedef ifnet_ioctl_func 201 @discussion ifnet_ioctl_func is used to communicate ioctls from the 202 stack to the driver. 203 204 All undefined ioctls are reserved for future use by Apple. If 205 you need to communicate with your kext using an ioctl, please 206 use SIOCSIFKPI and SIOCGIFKPI. 207 @param interface The interface the ioctl is being sent to. 208 @param proto_family The protocol family to handle the ioctl, may be 209 zero for no protocol_family. 210 @param cmd The ioctl command. 211 @param data A pointer to any data related to the ioctl. 212 */ 213typedef errno_t (*ifnet_ioctl_func)(ifnet_t interface, u_int32_t cmd, void *data); 214 215/*! 216 @typedef ifnet_set_bpf_tap 217 @discussion Deprecated. Specify NULL. Call bpf_tap_in/bpf_tap_out 218 for all packets. 219 */ 220typedef errno_t (*ifnet_set_bpf_tap)(ifnet_t interface, bpf_tap_mode mode, 221 bpf_packet_func callback); 222 223/*! 224 @typedef ifnet_detached_func 225 @discussion ifnet_detached_func is called an interface is detached 226 from the list of interfaces. When ifnet_detach is called, it may 227 not detach the interface immediately if protocols are attached. 228 ifnet_detached_func is used to notify the interface that it has 229 been detached from the networking stack. This is the last 230 function that will be called on an interface. Until this 231 function returns, you must not unload a kext supplying function 232 pointers to this interface, even if ifnet_detacah has been 233 called. Your detach function may be called during your call to 234 ifnet_detach. 235 @param interface The interface that has been detached. 236 event. 237 */ 238typedef void (*ifnet_detached_func)(ifnet_t interface); 239 240/*! 241 @typedef ifnet_demux_func 242 @discussion ifnet_demux_func is called for each inbound packet to determine 243 which protocol family the packet belongs to. This information is then 244 used by the stack to determine which protocol to pass the packet to. 245 This function may return protocol families for protocols that are 246 not attached. If the protocol family has not been attached to the 247 interface, the packet will be discarded. 248 @param interface The interface the packet was received on. 249 @param packet The mbuf containing the packet. 250 @param frame_header A pointer to the frame header. 251 @param protocol_family Upon return, the protocol family matching the 252 packet should be stored here. 253 @result 254 If the result is zero, processing will continue normally. 255 If the result is EJUSTRETURN, processing will stop but the packet will not be freed. 256 If the result is anything else, the processing will stop and the packet will be freed. 257 */ 258typedef errno_t (*ifnet_demux_func)(ifnet_t interface, mbuf_t packet, 259 char *frame_header, 260 protocol_family_t *protocol_family); 261 262/*! 263 @typedef ifnet_event_func 264 @discussion ifnet_event_func is called when an event occurs on a 265 specific interface. 266 @param interface The interface the event occurred on. 267 @param event_ptr Pointer to a kern_event structure describing the 268 event. 269 */ 270typedef void (*ifnet_event_func)(ifnet_t interface, const struct kev_msg *msg); 271 272/*! 273 @typedef ifnet_framer_func 274 @discussion ifnet_framer_func is called for each outbound packet to 275 give the interface an opportunity to prepend interface specific 276 headers. 277 @param interface The interface the packet is being sent on. 278 @param packet Pointer to the mbuf containing the packet, caller may 279 set this to a different mbuf upon return. This can happen if the 280 frameout function needs to prepend another mbuf to the chain to 281 have enough space for the header. 282 @param dest The higher layer protocol destination (i.e. IP address). 283 @param dest_linkaddr The link layer address as determined by the 284 protocol's pre-output function. 285 @param frame_type The frame type as determined by the protocol's 286 pre-output function. 287 @result 288 If the result is zero, processing will continue normally. 289 If the result is EJUSTRETURN, processing will stop but the packet will not be freed. 290 If the result is anything else, the processing will stop and the packet will be freed. 291 */ 292typedef errno_t (*ifnet_framer_func)(ifnet_t interface, mbuf_t *packet, 293 const struct sockaddr *dest, 294 const char *desk_linkaddr, 295 const char *frame_type); 296 297/*! 298 @typedef ifnet_add_proto_func 299 @discussion if_add_proto_func is called by the stack when a protocol 300 is attached to an interface. This gives the interface an 301 opportunity to get a list of protocol description structures 302 for demuxing packets to this protocol (demux descriptors). 303 @param interface The interface the protocol will be attached to. 304 @param protocol_family The family of the protocol being attached. 305 @param demux_array An array of demux descriptors that describe 306 the interface specific ways of identifying packets belonging 307 to this protocol family. 308 @param demux_count The number of demux descriptors in the array. 309 @result 310 If the result is zero, processing will continue normally. 311 If the result is anything else, the add protocol will be aborted. 312 */ 313typedef errno_t (*ifnet_add_proto_func)(ifnet_t interface, 314 protocol_family_t protocol_family, 315 const struct ifnet_demux_desc *demux_array, 316 u_int32_t demux_count); 317 318/*! 319 @typedef if_del_proto_func 320 @discussion if_del_proto_func is called by the stack when a protocol 321 is being detached from an interface. This gives the interface an 322 opportunity to free any storage related to this specific 323 protocol being attached to this interface. 324 @param interface The interface the protocol will be detached from. 325 @param protocol_family The family of the protocol being detached. 326 @result 327 If the result is zero, processing will continue normally. 328 If the result is anything else, the detach will continue 329 and the error will be returned to the caller. 330 */ 331typedef errno_t (*ifnet_del_proto_func)(ifnet_t interface, 332 protocol_family_t protocol_family); 333 334/*! 335 @typedef ifnet_check_multi 336 @discussion ifnet_check_multi is called for each multicast address 337 added to an interface. This gives the interface an opportunity 338 to reject invalid multicast addresses before they are attached 339 to the interface. 340 341 To prevent an address from being added to your multicast list, 342 return EADDRNOTAVAIL. If you don't know how to parse/translate 343 the address, return EOPNOTSUPP. 344 @param The interface. 345 @param mcast The multicast address. 346 @result 347 Zero upon success, EADDRNOTAVAIL on invalid multicast, 348 EOPNOTSUPP for addresses the interface does not understand. 349 */ 350typedef errno_t (*ifnet_check_multi)(ifnet_t interface, 351 const struct sockaddr* mcast); 352 353/*! 354 @typedef proto_media_input 355 @discussion proto_media_input is called for all inbound packets for 356 a specific protocol on a specific interface. This function is 357 registered on an interface using ifnet_attach_protocol. 358 @param ifp The interface the packet was received on. 359 @param protocol_family The protocol of the packet received. 360 @param packet The packet being input. 361 @param header The frame header. 362 @result 363 If the result is zero, the caller will assume the packet was passed 364 to the protocol. 365 If the result is non-zero and not EJUSTRETURN, the caller will free 366 the packet. 367 */ 368typedef errno_t (*proto_media_input)(ifnet_t ifp, protocol_family_t protocol, 369 mbuf_t packet, char* header); 370 371/*! 372 @typedef proto_media_input_v2 373 @discussion proto_media_input_v2 is called for all inbound packets for 374 a specific protocol on a specific interface. This function is 375 registered on an interface using ifnet_attach_protocolv2. 376 proto_media_input_v2 differs from proto_media_input in that it will 377 be called for a list of packets instead of once for each individual 378 packet. The frame header can be retrieved using mbuf_pkthdr_header. 379 @param ifp The interface the packet was received on. 380 @param protocol_family The protocol of the packet received. 381 @param packet The packet being input. 382 @result 383 If the result is zero, the caller will assume the packets were passed 384 to the protocol. 385 If the result is non-zero and not EJUSTRETURN, the caller will free 386 the packets. 387 */ 388typedef errno_t (*proto_media_input_v2)(ifnet_t ifp, protocol_family_t protocol, 389 mbuf_t packet); 390 391/*! 392 @typedef proto_media_preout 393 @discussion proto_media_preout is called just before the packet 394 is transmitted. This gives the proto_media_preout function an 395 opportunity to specify the media specific frame type and 396 destination. 397 @param ifp The interface the packet will be sent on. 398 @param protocol_family The protocol of the packet being sent 399 (PF_INET/etc...). 400 @param packet The packet being sent. 401 @param dest The protocol level destination address. 402 @param route A pointer to the routing structure for the packet. 403 @param frame_type The media specific frame type. 404 @param link_layer_dest The media specific destination. 405 @result 406 If the result is zero, processing will continue normally. If the 407 result is non-zero, processing will stop. If the result is 408 non-zero and not EJUSTRETURN, the packet will be freed by the 409 caller. 410 */ 411typedef errno_t (*proto_media_preout)(ifnet_t ifp, protocol_family_t protocol, 412 mbuf_t *packet, const struct sockaddr *dest, 413 void *route, char *frame_type, char *link_layer_dest); 414 415/*! 416 @typedef proto_media_event 417 @discussion proto_media_event is called to notify this layer of 418 interface specific events. 419 @param ifp The interface. 420 @param protocol_family The protocol family. 421 @param kev_msg The event. 422 */ 423typedef void (*proto_media_event)(ifnet_t ifp, protocol_family_t protocol, 424 const struct kev_msg *event); 425 426/*! 427 @typedef proto_media_ioctl 428 @discussion proto_media_event allows this layer to handle ioctls. 429 When an ioctl is handled, it is passed to the interface filters, 430 protocol filters, protocol, and interface. If you do not support 431 this ioctl, return EOPNOTSUPP. If you successfully handle the 432 ioctl, return zero. If you return any error other than 433 EOPNOTSUPP, other parts of the stack may not get an opportunity 434 to process the ioctl. If you return EJUSTRETURN, processing will 435 stop and a result of zero will be returned to the caller. 436 437 All undefined ioctls are reserved for future use by Apple. If 438 you need to communicate with your kext using an ioctl, please 439 use SIOCSIFKPI and SIOCGIFKPI. 440 @param ifp The interface. 441 @param protocol_family The protocol family. 442 @param command The ioctl command. 443 @param argument The argument to the ioctl. 444 @result 445 See the discussion. 446 */ 447typedef errno_t (*proto_media_ioctl)(ifnet_t ifp, protocol_family_t protocol, 448 u_int32_t command, void* argument); 449 450/*! 451 @typedef proto_media_detached 452 @discussion proto_media_detached notifies you that your protocol 453 has been detached. 454 @param ifp The interface. 455 @param protocol_family The protocol family. 456 @result 457 See the discussion. 458 */ 459typedef errno_t (*proto_media_detached)(ifnet_t ifp, protocol_family_t protocol); 460 461 462/*! 463 @typedef proto_media_resolve_multi 464 @discussion proto_media_resolve_multi is called to resolve a 465 protocol layer mulitcast address to a link layer multicast 466 address. 467 @param ifp The interface. 468 @param proto_addr The protocol address. 469 @param out_ll A sockaddr_dl to copy the link layer multicast in to. 470 @param ll_len The length of data allocated for out_ll. 471 @result Return zero on success or an errno error value on failure. 472 */ 473typedef errno_t (*proto_media_resolve_multi)(ifnet_t ifp, 474 const struct sockaddr *proto_addr, 475 struct sockaddr_dl *out_ll, size_t ll_len); 476 477/*! 478 @typedef proto_media_send_arp 479 @discussion proto_media_send_arp is called by the stack to generate 480 an ARP packet. This field is currently only used with IP. This 481 function should inspect the parameters and transmit an arp 482 packet using the information passed in. 483 @param ifp The interface the arp packet should be sent on. 484 @param protocol_family The protocol family of the addresses 485 (PF_INET). 486 @param arpop The arp operation (usually ARPOP_REQUEST or 487 ARPOP_REPLY). 488 @param sender_hw The value to use for the sender hardware 489 address field. If this is NULL, use the hardware address 490 of the interface. 491 @param sender_proto The value to use for the sender protocol 492 address field. This will not be NULL. 493 @param target_hw The value to use for the target hardware address. 494 If this is NULL, the target hardware address in the ARP packet 495 should be NULL and the link-layer destination for the back 496 should be a broadcast. If this is not NULL, this value should be 497 used for both the link-layer destination and the target hardware 498 address. 499 @param target_proto The target protocol address. This will not be 500 NULL. 501 @result Return zero on success or an errno error value on failure. 502 */ 503typedef errno_t (*proto_media_send_arp)(ifnet_t ifp, 504 u_short arpop, 505 const struct sockaddr_dl* sender_hw, 506 const struct sockaddr* sender_proto, 507 const struct sockaddr_dl* target_hw, 508 const struct sockaddr* target_proto); 509 510/*! 511 @struct ifnet_stat_increment_param 512 @discussion This structure is used increment the counters on a 513 network interface. 514 @field packets_in The number of packets received. 515 @field bytes_in The number of bytes received. 516 @field errors_in The number of receive errors. 517 @field packets_out The number of packets transmitted. 518 @field bytes_out The number of bytes transmitted. 519 @field errors_out The number of transmission errors. 520 @field collisions The number of collisions seen by this interface. 521 @field dropped The number of packets dropped. 522*/ 523 524struct ifnet_stat_increment_param { 525 u_int32_t packets_in; 526 u_int32_t bytes_in; 527 u_int32_t errors_in; 528 529 u_int32_t packets_out; 530 u_int32_t bytes_out; 531 u_int32_t errors_out; 532 533 u_int32_t collisions; 534 u_int32_t dropped; 535}; 536 537/*! 538 @struct ifnet_init_params 539 @discussion This structure is used to define various properties of 540 the interface when calling ifnet_init. A copy of these values 541 will be stored in the ifnet and can not be modified while the 542 interface is attached. 543 @field uniqueid An identifier unique to this instance of the 544 interface. 545 @field uniqueid_len The length, in bytes, of the uniqueid. 546 @field name The interface name (i.e. en). 547 @field unit The interface unit number (en0's unit number is 0). 548 @field family The interface family. 549 @field type The interface type (see sys/if_types.h). Must be less 550 than 256. For new types, use IFT_OTHER. 551 @field output The output function for the interface. Every packet the 552 stack attempts to send through this interface will go out through 553 this function. 554 @field demux The function used to determine the protocol family of an 555 incoming packet. 556 @field add_proto The function used to attach a protocol to this interface. 557 @field del_proto The function used to remove a protocol from this interface. 558 @field framer The function used to frame outbound packets, may be NULL. 559 @field softc Driver specific storage. This value can be retrieved from the 560 ifnet using the ifnet_softc function. 561 @field ioctl The function used to handle ioctls. 562 @field set_bpf_tap The function used to set the bpf_tap function. 563 @field detach The function called to let the driver know the interface has been detached. 564 @field event The function to notify the interface of various interface specific kernel events. 565 @field broadcast_addr The link-layer broadcast address for this interface. 566 @field broadcast_len The length of the link-layer broadcast address. 567*/ 568 569struct ifnet_init_params { 570 /* used to match recycled interface */ 571 const void* uniqueid; /* optional */ 572 u_int32_t uniqueid_len; /* optional */ 573 574 /* used to fill out initial values for interface */ 575 const char* name; /* required */ 576 u_int32_t unit; /* required */ 577 ifnet_family_t family; /* required */ 578 u_int32_t type; /* required */ 579 ifnet_output_func output; /* required */ 580 ifnet_demux_func demux; /* required */ 581 ifnet_add_proto_func add_proto; /* required */ 582 ifnet_del_proto_func del_proto; /* required */ 583 ifnet_check_multi check_multi; /* required for non point-to-point interfaces */ 584 ifnet_framer_func framer; /* optional */ 585 void* softc; /* optional */ 586 ifnet_ioctl_func ioctl; /* optional */ 587 ifnet_set_bpf_tap set_bpf_tap; /* deprecated */ 588 ifnet_detached_func detach; /* optional */ 589 ifnet_event_func event; /* optional */ 590 const void *broadcast_addr;/* required for non point-to-point interfaces */ 591 u_int32_t broadcast_len; /* required for non point-to-point interfaces */ 592}; 593 594/*! 595 @struct ifnet_stats_param 596 @discussion This structure is used get and set the interface 597 statistics. 598 @field packets_in The number of packets received. 599 @field bytes_in The number of bytes received. 600 @field errors_in The number of receive errors. 601 @field packets_out The number of packets transmitted. 602 @field bytes_out The number of bytes transmitted. 603 @field errors_out The number of transmission errors. 604 @field collisions The number of collisions seen by this interface. 605 @field dropped The number of packets dropped. 606*/ 607 608struct ifnet_stats_param { 609 u_int64_t packets_in; 610 u_int64_t bytes_in; 611 u_int64_t multicasts_in; 612 u_int64_t errors_in; 613 614 u_int64_t packets_out; 615 u_int64_t bytes_out; 616 u_int64_t multicasts_out; 617 u_int64_t errors_out; 618 619 u_int64_t collisions; 620 u_int64_t dropped; 621 u_int64_t no_protocol; 622}; 623 624/*! 625 @struct ifnet_demux_desc 626 @discussion This structure is to identify packets that belong to a 627 specific protocol. The types supported are interface specific. 628 Ethernet supports ETHER_DESC_ETYPE2, ETHER_DESC_SAP, and 629 ETHER_DESC_SNAP. The type defines the offset in the packet where 630 the data will be matched as well as context. For example, if 631 ETHER_DESC_SNAP is specified, the only valid datalen is 5 and 632 only in the 5 bytes will only be matched when the packet header 633 indicates that the packet is a SNAP packet. 634 @field type The type of identifier data (i.e. ETHER_DESC_ETYPE2) 635 @field data A pointer to an entry of type (i.e. pointer to 0x0800). 636 @field datalen The number of bytes of data used to describe the 637 packet. 638*/ 639 640struct ifnet_demux_desc { 641 u_int32_t type; 642 void* data; 643 u_int32_t datalen; 644}; 645 646/*! 647 @struct ifnet_attach_proto_param 648 @discussion This structure is used to attach a protocol to an 649 interface. This structure provides the various functions for 650 handling operations related to the protocol on the interface as 651 well as information for how to demux packets for this protocol. 652 @field demux_array An array of ifnet_demux_desc structures 653 describing the protocol. 654 @field demux_count The number of entries in the demux_array array. 655 @field input The function to be called for inbound packets. 656 @field pre_output The function to be called for outbound packets. 657 @field event The function to be called for interface events. 658 @field ioctl The function to be called for ioctls. 659 @field detached The function to be called for handling the detach. 660*/ 661#ifdef KERNEL_PRIVATE 662#define demux_list demux_array 663#endif /* KERNEL_PRIVATE */ 664 665struct ifnet_attach_proto_param { 666 struct ifnet_demux_desc *demux_array; /* interface may/may not require */ 667 u_int32_t demux_count; /* interface may/may not require */ 668 669 proto_media_input input; /* required */ 670 proto_media_preout pre_output; /* required */ 671 proto_media_event event; /* optional */ 672 proto_media_ioctl ioctl; /* optional */ 673 proto_media_detached detached; /* optional */ 674 proto_media_resolve_multi resolve; /* optional */ 675 proto_media_send_arp send_arp; /* optional */ 676}; 677 678struct ifnet_attach_proto_param_v2 { 679 struct ifnet_demux_desc *demux_array; /* interface may/may not require */ 680 u_int32_t demux_count; /* interface may/may not require */ 681 682 proto_media_input_v2 input; /* required */ 683 proto_media_preout pre_output; /* required */ 684 proto_media_event event; /* optional */ 685 proto_media_ioctl ioctl; /* optional */ 686 proto_media_detached detached; /* optional */ 687 proto_media_resolve_multi resolve; /* optional */ 688 proto_media_send_arp send_arp; /* optional */ 689}; 690 691__BEGIN_DECLS 692 693/* 694 * Ifnet creation and reference counting 695 */ 696 697/*! 698 @function ifnet_allocate 699 @discussion Allocate an ifnet_t with an initial refcount of 1. Many 700 parts of the stack do not properly refcount the ifnet_t. In 701 order to avoid freeing the ifnet_t while some parts of the stack 702 may contain a reference to it, the ifnet_ts are only recycled, 703 never freed. A unique id is used to try and recycle the same 704 ifnet_t when allocating an interface. For example, for an 705 ethernet interface, the hardware address of the ethernet card is 706 usually used for the uniqueid. If a PC Card is removed and 707 inserted again, if the ethernet address of the PC card is used, 708 the same ifnet_t will be used for the card the second time it is 709 inserted. In the future, when the ifnet_t is correctly 710 refcounted by all of the stack, the interfaces may be freed and 711 the unique ids ignored. 712 @param init The initial values for the interface. These values can 713 not be changed after the interface has been allocated. 714 @param interface The interface allocated upon success. 715 @result May return ENOMEM if there is insufficient memory or EEXIST 716 if an interface with the same uniqueid and family has already 717 been allocated and is in use. 718 */ 719errno_t ifnet_allocate(const struct ifnet_init_params *init, ifnet_t *interface); 720 721/*! 722 @function ifnet_reference 723 @discussion Increment the reference count of the ifnet to assure 724 that it will not go away. The interface must already have at 725 least one reference. 726 @param interface The interface to increment the reference count of. 727 @result May return EINVAL if the interface is not valid. 728 */ 729errno_t ifnet_reference(ifnet_t interface); 730 731/*! 732 @function ifnet_release 733 @discussion Release a reference of the ifnet, this may trigger a 734 free if the reference count reaches 0. 735 @param interface The interface to decrement the reference count of 736 and possibly free. 737 @result May return EINVAL if the interface is not valid. 738 */ 739errno_t ifnet_release(ifnet_t interface); 740 741/*! 742 @function ifnet_attach 743 @discussion Attaches an interface to the global interface list. The 744 interface must be setup properly before calling attach. The 745 stack will take a reference on the interface and hold it until 746 ifnet_detach is called. 747 748 This function is intended to be called by the driver. A kext 749 must not call this function on an interface the kext does not 750 own. 751 @param interface The interface to attach. 752 @param ll_addr The link layer address of the interface. This is used 753 to fill out the first ifaddr in the list of addresses for the 754 interface. This parameter is not required for interfaces such as 755 PPP that have no link-layer address. 756 @result Will return an error if there is anything wrong with the 757 interface. 758 */ 759errno_t ifnet_attach(ifnet_t interface, const struct sockaddr_dl *ll_addr); 760 761/*! 762 @function ifnet_detach 763 @discussion Detaches the interface. 764 765 Call this to indicate this interface is no longer valid (i.e. PC 766 Card was removed). This function will begin the process of 767 removing knowledge of this interface from the stack. 768 769 The function will return before the interface is detached. The 770 functions you supplied in to the interface may continue to be 771 called. When the detach has been completed, your detached 772 function will be called. Your kext must not unload until the 773 detached function has been called. The interface will be 774 properly freed when the reference count reaches zero. 775 776 An interface may not be attached again. You must call 777 ifnet_allocate to create a new interface to attach. 778 779 This function is intended to be called by the driver. A kext 780 must not call this function on an interface the kext does not 781 own. 782 @param interface The interface to detach. 783 @result 0 on success, otherwise errno error. 784 */ 785errno_t ifnet_detach(ifnet_t interface); 786 787/* 788 * Interface manipulation. 789 */ 790 791/*! 792 @function ifnet_softc 793 @discussion Returns the driver's private storage on the interface. 794 @param interface Interface to retrieve the storage from. 795 @result Driver's private storage. 796 */ 797void* ifnet_softc(ifnet_t interface); 798 799/*! 800 @function ifnet_name 801 @discussion Returns a pointer to the name of the interface. 802 @param interface Interface to retrieve the name from. 803 @result Pointer to the name. 804 */ 805const char* ifnet_name(ifnet_t interface); 806 807/*! 808 @function ifnet_family 809 @discussion Returns the family of the interface. 810 @param interface Interface to retrieve the unit number from. 811 @result Unit number. 812 */ 813ifnet_family_t ifnet_family(ifnet_t interface); 814 815/*! 816 @function ifnet_unit 817 @discussion Returns the unit number of the interface. 818 @param interface Interface to retrieve the unit number from. 819 @result Unit number. 820 */ 821u_int32_t ifnet_unit(ifnet_t interface); 822 823/*! 824 @function ifnet_index 825 @discussion Returns the index of the interface. This index value 826 will match the index you would find in a sockaddr_dl or using 827 if_nametoindex or if_indextoname in user space. The value of the 828 interface index is undefined for an interface that is not 829 currently attached. 830 @param interface Interface to retrieve the index of. 831 @result Index. 832 */ 833u_int32_t ifnet_index(ifnet_t interface); 834 835/*! 836 @function ifnet_set_flags 837 @discussion Sets the interface flags to match new_flags. 838 @discussion Sets the interface flags to new_flags. This function 839 lets you specify which flags you want to change using the mask. 840 The kernel will effectively take the lock, then set the 841 interface's flags to (if_flags & ~mask) | (new_flags & mask). 842 @param interface Interface to set the flags on. 843 @param new_flags The new set of flags that should be set. These 844 flags are defined in net/if.h 845 @result 0 on success otherwise the errno error. 846 */ 847errno_t ifnet_set_flags(ifnet_t interface, u_int16_t new_flags, u_int16_t mask); 848 849/*! 850 @function ifnet_flags 851 @discussion Returns the interface flags that are set. 852 @param interface Interface to retrieve the flags from. 853 @result Flags. These flags are defined in net/if.h 854 */ 855u_int16_t ifnet_flags(ifnet_t interface); 856 857 858#ifdef KERNEL_PRIVATE 859/*! 860 @function ifnet_set_eflags 861 @discussion Sets the extended interface flags to new_flags. This 862 function lets you specify which flags you want to change using 863 the mask. The kernel will effectively take the lock, then set 864 the interface's extended flags to (if_eflags & ~mask) | 865 (new_flags & mask). 866 @param interface The interface. 867 @param new_flags The new set of flags that should be set. These 868 flags are defined in net/if.h 869 @param mask The mask of flags to be modified. 870 @result 0 on success otherwise the errno error. 871 */ 872errno_t ifnet_set_eflags(ifnet_t interface, u_int32_t new_flags, u_int32_t mask); 873 874/*! 875 @function ifnet_eflags 876 @discussion Returns the extended interface flags that are set. 877 @param interface Interface to retrieve the flags from. 878 @result Extended flags. These flags are defined in net/if.h 879 */ 880u_int32_t ifnet_eflags(ifnet_t interface); 881#endif 882 883/*! 884 @function ifnet_set_offload 885 @discussion Sets a bitfield to indicate special hardware offload 886 support provided by the interface such as hardware checksums and 887 VLAN. This replaces the if_hwassist flags field. Any flags 888 unrecognized by the stack will not be set. 889 @param interface The interface. 890 @param offload The new set of flags indicating which offload options 891 the device supports. 892 @param mask The mask of flags to be modified. 893 @result 0 on success otherwise the errno error. 894 */ 895errno_t ifnet_set_offload(ifnet_t interface, ifnet_offload_t offload); 896 897/*! 898 @function ifnet_offload 899 @discussion Returns flags indicating which operations can be 900 offloaded to the interface. 901 @param interface Interface to retrieve the offload from. 902 @result Abilities flags, see ifnet_offload_t. 903 */ 904ifnet_offload_t ifnet_offload(ifnet_t interface); 905 906/*! 907 @function ifnet_set_link_mib_data 908 @discussion Sets the mib link data. The ifnet_t will store the 909 pointer you supply and copy mibLen bytes from the pointer 910 whenever the sysctl for getting interface specific MIB data is 911 used. Since the ifnet_t stores a pointer to your data instead of 912 a copy, you may update the data at the address at any time. 913 914 This function is intended to be called by the driver. A kext 915 must not call this function on an interface the kext does not 916 own. 917 @param interface Interface to set the unit number of. 918 @param mibData A pointer to the data. 919 @param mibLen Length of data pointed to. 920 @result 0 on success otherwise the errno error. 921 */ 922errno_t ifnet_set_link_mib_data(ifnet_t interface, void *mibData, u_int32_t mibLen); 923 924/*! 925 @function ifnet_get_link_mib_data 926 @discussion Copies the link MIB data in to mibData, up to mibLen 927 bytes. Returns error if the buffer is too small to hold all of 928 the MIB data. 929 @param interface The interface. 930 @param mibData A pointer to space for the mibData to be copied in 931 to. 932 @param mibLen When calling, this should be the size of the buffer 933 passed in mibData. Upon return, this will be the size of data 934 copied in to mibData. 935 @result Returns an error if the buffer size is too small or there is 936 no data. 937 */ 938errno_t ifnet_get_link_mib_data(ifnet_t interface, void *mibData, u_int32_t *mibLen); 939 940/*! 941 @function ifnet_get_link_mib_data_length 942 @discussion Retrieve the size of the mib data. 943 @param interface The interface. 944 @result Returns the number of bytes of mib data associated with the 945 interface. 946 */ 947u_int32_t ifnet_get_link_mib_data_length(ifnet_t interface); 948 949/*! 950 @function ifnet_attach_protocol 951 @discussion Attaches a protocol to an interface. 952 @param interface The interface. 953 @param protocol_family The protocol family being attached 954 (PF_INET/PF_APPLETALK/etc...). 955 @param proto_details Details of the protocol being attached. 956 @result 0 on success otherwise the errno error. 957 */ 958errno_t ifnet_attach_protocol(ifnet_t interface, protocol_family_t protocol_family, 959 const struct ifnet_attach_proto_param *proto_details); 960 961/*! 962 @function ifnet_attach_protocol_v2 963 @discussion Attaches a protocol to an interface using the newer version 2 964 style interface. So far the only difference is support for packet 965 chains which improve performance. 966 @param interface The interface. 967 @param protocol_family The protocol family being attached 968 (PF_INET/PF_APPLETALK/etc...). 969 @param proto_details Details of the protocol being attached. 970 @result 0 on success otherwise the errno error. 971 */ 972errno_t ifnet_attach_protocol_v2(ifnet_t interface, protocol_family_t protocol_family, 973 const struct ifnet_attach_proto_param_v2 *proto_details); 974 975/*! 976 @function ifnet_detach_protocol 977 @discussion Detaches a protocol from an interface. 978 @param interface The interface. 979 @param protocol_family The protocol family of the protocol to 980 detach. 981 @result 0 on success otherwise the errno error. 982 */ 983errno_t ifnet_detach_protocol(ifnet_t interface, protocol_family_t protocol_family); 984 985/*! 986 @function ifnet_output 987 @discussion Handles an outbound packet on the interface by calling 988 any filters, a protocol preoutput function, the interface framer 989 function, and finally the interface's output function. The 990 protocol_family will be used to apply protocol filters and 991 determine which preoutput function to call. The route and dest 992 parameters will be passed to the preoutput function defined for 993 the attachment of the specified protocol to the specified 994 interface. ifnet_output will always free the mbuf chain. 995 @param interface The interface. 996 @param protocol_family The family of the protocol generating this 997 packet (i.e. AF_INET). 998 @param packet The packet to be transmitted. 999 @param route A pointer to a routing structure for this packet. The 1000 preoutput function determines whether this value may be NULL or 1001 not. 1002 @param dest The destination address of protocol_family type. This 1003 will be passed to the preoutput function. If the preoutput 1004 function does not require this value, you may pass NULL. 1005 @result 0 on success otherwise the errno error. 1006 */ 1007errno_t ifnet_output(ifnet_t interface, protocol_family_t protocol_family, mbuf_t packet, 1008 void* route, const struct sockaddr *dest); 1009 1010/*! 1011 @function ifnet_output_raw 1012 @discussion Handles and outbond raw packet on the interface by 1013 calling any filters followed by the interface's output function. 1014 protocol_family may be zero. If the packet is from a specific 1015 protocol the protocol_family will be used to apply protocol 1016 filters. All interface filters will be applied to the outgoing 1017 packet. Processing, such as calling the protocol preoutput and 1018 interface framer functions will be bypassed. The packet will 1019 pass through the filters and be sent on the interface as is. 1020 ifnet_output_raw will always free the packet chain. 1021 @param interface The interface. 1022 @param protocol_family The family of the protocol generating this 1023 packet (i.e. AF_INET). 1024 @param packet The fully formed packet to be transmitted. 1025 @result 0 on success otherwise the errno error. 1026 */ 1027errno_t ifnet_output_raw(ifnet_t interface, protocol_family_t protocol_family, mbuf_t packet); 1028 1029/*! 1030 @function ifnet_input 1031 @discussion Inputs packets from the interface. The interface's demux 1032 will be called to determine the protocol. Once the protocol is 1033 determined, the interface filters and protocol filters will be 1034 called. From there, the packet will be passed to the registered 1035 protocol. If there is an error, the mbuf chain will be freed. 1036 @param interface The interface. 1037 @param first_packet The first packet in a chain of packets. 1038 @param stats Counts to be integrated in to the stats. The interface 1039 statistics will be incremented by the amounts specified in 1040 stats. This parameter may be NULL. 1041 @result 0 on success otherwise the errno error. 1042 */ 1043errno_t ifnet_input(ifnet_t interface, mbuf_t first_packet, 1044 const struct ifnet_stat_increment_param *stats); 1045 1046/*! 1047 @function ifnet_ioctl 1048 @discussion Calls the interface's ioctl function with the parameters 1049 passed. 1050 1051 All undefined ioctls are reserved for future use by Apple. If 1052 you need to communicate with your kext using an ioctl, please 1053 use SIOCSIFKPI and SIOCGIFKPI. 1054 @param interface The interface. 1055 @param protocol The protocol family of the protocol to send the 1056 ioctl to (may be zero). Some ioctls apply to a protocol while 1057 other ioctls apply to just an interface. 1058 @param ioctl_code The ioctl to perform. 1059 @param ioctl_arg Any parameters to the ioctl. 1060 @result 0 on success otherwise the errno error. 1061 */ 1062errno_t ifnet_ioctl(ifnet_t interface, protocol_family_t protocol, 1063 u_int32_t ioctl_code, void *ioctl_arg); 1064 1065/*! 1066 @function ifnet_event 1067 @discussion Calls the interface's event function. 1068 @param interface The interface. 1069 @param event_ptr Pointer to an kern_event structure describing the 1070 event. 1071 @result 0 on success otherwise the errno error. 1072 */ 1073errno_t ifnet_event(ifnet_t interface, struct kern_event_msg* event_ptr); 1074 1075/*! 1076 @function ifnet_set_mtu 1077 @discussion Sets the value of the MTU in the interface structure. 1078 Calling this function will not notify the driver that the MTU 1079 should be changed. Use the appropriate ioctl. 1080 1081 This function is intended to be called by the driver. A kext 1082 must not call this function on an interface the kext does not 1083 own. 1084 @param interface The interface. 1085 @param mtu The new MTU. 1086 @result 0 on success otherwise the errno error. 1087 */ 1088errno_t ifnet_set_mtu(ifnet_t interface, u_int32_t mtu); 1089 1090/*! 1091 @function ifnet_mtu 1092 @param interface The interface. 1093 @result The MTU. 1094 */ 1095u_int32_t ifnet_mtu(ifnet_t interface); 1096 1097/*! 1098 @function ifnet_type 1099 @param interface The interface. 1100 @result The type. See net/if_types.h. 1101 */ 1102u_int8_t ifnet_type(ifnet_t interface); 1103 1104/*! 1105 @function ifnet_set_addrlen 1106 @discussion 1107 This function is intended to be called by the driver. A kext 1108 must not call this function on an interface the kext does not 1109 own. 1110 @param interface The interface. 1111 @param addrlen The new address length. 1112 @result 0 on success otherwise the errno error. 1113 */ 1114errno_t ifnet_set_addrlen(ifnet_t interface, u_int8_t addrlen); 1115 1116/*! 1117 @function ifnet_addrlen 1118 @param interface The interface. 1119 @result The address length. 1120 */ 1121u_int8_t ifnet_addrlen(ifnet_t interface); 1122 1123/*! 1124 @function ifnet_set_hdrlen 1125 @discussion 1126 This function is intended to be called by the driver. A kext 1127 must not call this function on an interface the kext does not 1128 own. 1129 @param interface The interface. 1130 @param hdrlen The new header length. 1131 @result 0 on success otherwise the errno error. 1132 */ 1133errno_t ifnet_set_hdrlen(ifnet_t interface, u_int8_t hdrlen); 1134 1135/*! 1136 @function ifnet_hdrlen 1137 @param interface The interface. 1138 @result The header length. 1139 */ 1140u_int8_t ifnet_hdrlen(ifnet_t interface); 1141 1142/*! 1143 @function ifnet_set_metric 1144 @discussion 1145 This function is intended to be called by the driver. A kext 1146 must not call this function on an interface the kext does not 1147 own. 1148 @param interface The interface. 1149 @param metric The new metric. 1150 @result 0 on success otherwise the errno error. 1151 */ 1152errno_t ifnet_set_metric(ifnet_t interface, u_int32_t metric); 1153 1154/*! 1155 @function ifnet_metric 1156 @param interface The interface. 1157 @result The metric. 1158 */ 1159u_int32_t ifnet_metric(ifnet_t interface); 1160 1161/*! 1162 @function ifnet_set_baudrate 1163 @discussion 1164 This function is intended to be called by the driver. A kext 1165 must not call this function on an interface the kext does not 1166 own. 1167 @param interface The interface. 1168 @param baudrate The new baudrate. 1169 @result 0 on success otherwise the errno error. 1170 */ 1171errno_t ifnet_set_baudrate(ifnet_t interface, u_int64_t baudrate); 1172 1173/*! 1174 @function ifnet_baudrate 1175 @param interface The interface. 1176 @result The baudrate. 1177 */ 1178u_int64_t ifnet_baudrate(ifnet_t interface); 1179 1180/*! 1181 @function ifnet_stat_increment 1182 @discussion 1183 This function is intended to be called by the driver. A kext 1184 must not call this function on an interface the kext does not 1185 own. 1186 @param interface The interface. 1187 @param counts A pointer to a structure containing the amount to 1188 increment each counter by. Any counts not appearing in the 1189 ifnet_counter_increment structure are handled in the stack. 1190 @result 0 on success otherwise the errno error. 1191 */ 1192errno_t ifnet_stat_increment(ifnet_t interface, 1193 const struct ifnet_stat_increment_param *counts); 1194 1195/*! 1196 @function ifnet_stat_increment_in 1197 @discussion 1198 This function is intended to be called by the driver. This 1199 function allows a driver to update the inbound interface counts. 1200 The most efficient time to update these counts is when calling 1201 ifnet_input. 1202 1203 A lock protects the counts, this makes the increment functions 1204 expensive. The increment function will update the lastchanged 1205 value. 1206 @param interface The interface. 1207 @param packets_in The number of additional packets received. 1208 @param bytes_in The number of additional bytes received. 1209 @param errors_in The number of additional receive errors. 1210 @result 0 on success otherwise the errno error. 1211 */ 1212errno_t ifnet_stat_increment_in(ifnet_t interface, 1213 u_int32_t packets_in, u_int32_t bytes_in, 1214 u_int32_t errors_in); 1215 1216/*! 1217 @function ifnet_stat_increment_out 1218 @discussion 1219 This function is intended to be called by the driver. This 1220 function allows a driver to update the outbound interface counts. 1221 1222 A lock protects the counts, this makes the increment functions 1223 expensive. The increment function will update the lastchanged 1224 value. 1225 @param interface The interface. 1226 @param packets_out The number of additional packets sent. 1227 @param bytes_out The number of additional bytes sent. 1228 @param errors_out The number of additional send errors. 1229 @result 0 on success otherwise the errno error. 1230 */ 1231errno_t ifnet_stat_increment_out(ifnet_t interface, 1232 u_int32_t packets_out, u_int32_t bytes_out, 1233 u_int32_t errors_out); 1234 1235/*! 1236 @function ifnet_set_stat 1237 @discussion 1238 This function is intended to be called by the driver. A kext 1239 must not call this function on an interface the kext does not 1240 own. 1241 1242 The one exception would be the case where a kext wants to zero 1243 all of the counters. 1244 @param interface The interface. 1245 @param counts The new stats values. 1246 @result 0 on success otherwise the errno error. 1247 */ 1248errno_t ifnet_set_stat(ifnet_t interface, 1249 const struct ifnet_stats_param *stats); 1250 1251/*! 1252 @function ifnet_stat 1253 @param interface The interface. 1254 @param out_stats Storage for the values. 1255 @result 0 on success otherwise the errno error. 1256 */ 1257errno_t ifnet_stat(ifnet_t interface, 1258 struct ifnet_stats_param *out_stats); 1259 1260/*! 1261 @function ifnet_set_promiscuous 1262 @discussion Enable or disable promiscuous mode on the interface. The 1263 interface keeps an internal count of the number of times 1264 promiscuous mode has been enabled. Promiscuous mode is only 1265 disabled when this count reaches zero. Be sure to disable 1266 promiscuous mode only once for every time you enable it. 1267 @param interface The interface to toggle promiscuous mode on. 1268 @param on If set, the number of promicuous on requests will be 1269 incremented. If this is the first requrest, promiscuous mode 1270 will be enabled. If this is not set, the number of promiscous 1271 clients will be decremented. If this causes the number to reach 1272 zero, promiscuous mode will be disabled. 1273 @result 0 on success otherwise the errno error. 1274 */ 1275errno_t ifnet_set_promiscuous(ifnet_t interface, int on); 1276 1277/*! 1278 @function ifnet_touch_lastchange 1279 @discussion Updates the lastchange value to now. 1280 @param interface The interface. 1281 @result 0 on success otherwise the errno error. 1282 */ 1283errno_t ifnet_touch_lastchange(ifnet_t interface); 1284 1285/*! 1286 @function ifnet_lastchange 1287 @param interface The interface. 1288 @param last_change A timeval struct to copy the last time changed in 1289 to. 1290 */ 1291errno_t ifnet_lastchange(ifnet_t interface, struct timeval *last_change); 1292 1293/*! 1294 @function ifnet_get_address_list 1295 @discussion Get a list of addresses on the interface. Passing NULL 1296 for the interface will return a list of all addresses. The 1297 addresses will have their reference count bumped so they will 1298 not go away. Calling ifnet_free_address_list will decrement the 1299 refcount and free the array. If you wish to hold on to a 1300 reference to an ifaddr_t, be sure to bump the reference count 1301 before calling ifnet_free_address_list. 1302 @param interface The interface. 1303 @param addresses A pointer to a NULL terminated array of ifaddr_ts. 1304 @result 0 on success otherwise the errno error. 1305 */ 1306errno_t ifnet_get_address_list(ifnet_t interface, ifaddr_t **addresses); 1307 1308/*! 1309 @function ifnet_get_address_list_family 1310 @discussion Get a list of addresses on the interface. Passing NULL 1311 for the interface will return a list of all addresses. The 1312 addresses will have their reference count bumped so they will 1313 not go away. Calling ifnet_free_address_list will decrement the 1314 refcount and free the array. If you wish to hold on to a 1315 reference to an ifaddr_t, be sure to bump the reference count 1316 before calling ifnet_free_address_list. Unlike 1317 ifnet_get_address_list, this function lets the caller specify 1318 the address family to get a list of only a specific address type. 1319 @param interface The interface. 1320 @param addresses A pointer to a NULL terminated array of ifaddr_ts. 1321 @result 0 on success otherwise the errno error. 1322 */ 1323errno_t ifnet_get_address_list_family(ifnet_t interface, ifaddr_t **addresses, sa_family_t family); 1324 1325/*! 1326 @function ifnet_free_address_list 1327 @discussion Free a list of addresses returned from 1328 ifnet_get_address_list. Decrements the refcounts and frees the 1329 memory used for the array of references. 1330 @param addresses An array of ifaddr_ts. 1331 */ 1332void ifnet_free_address_list(ifaddr_t *addresses); 1333 1334/*! 1335 @function ifnet_set_lladdr 1336 @discussion Sets the link-layer address for this interface. 1337 @param interface The interface the link layer address is being 1338 changed on. 1339 @param lladdr A pointer to the raw link layer address (pointer to 1340 the 6 byte ethernet address for ethernet). 1341 @param lladdr_len The length, in bytes, of the link layer address. 1342 */ 1343errno_t ifnet_set_lladdr(ifnet_t interface, const void* lladdr, size_t lladdr_len); 1344 1345/*! 1346 @function ifnet_lladdr_copy_bytes 1347 @discussion Copies the bytes of the link-layer address in to the 1348 specified buffer. 1349 @param interface The interface to copy the link-layer address from. 1350 @param lladdr The buffer to copy the link-layer address in to. 1351 @param length The length of the buffer. This value must match the 1352 length of the link-layer address. 1353 */ 1354errno_t ifnet_lladdr_copy_bytes(ifnet_t interface, void* lladdr, size_t length); 1355 1356#ifdef KERNEL_PRIVATE 1357/*! 1358 @function ifnet_lladdr 1359 @discussion Returns a pointer to the link-layer address. 1360 @param interface The interface the link-layer address is on. 1361 */ 1362void* ifnet_lladdr(ifnet_t interface); 1363#endif KERNEL_PRIVATE 1364 1365/*! 1366 @function ifnet_llbroadcast_copy_bytes 1367 @discussion Retrieves the link-layer broadcast address for this 1368 interface. 1369 @param interface The interface. 1370 @param addr A buffer to copy the broadcast address in to. 1371 @param bufferlen The length of the buffer at addr. 1372 @param addr_len On return, the length of the broadcast address. 1373 @param lladdr_len The length, in bytes, of the link layer address. 1374 */ 1375errno_t ifnet_llbroadcast_copy_bytes(ifnet_t interface, void* addr, 1376 size_t bufferlen, size_t* addr_len); 1377 1378#ifdef KERNEL_PRIVATE 1379/*! 1380 @function ifnet_set_lladdr_and_type 1381 @discussion Sets the link-layer address as well as the type field in 1382 the sockaddr_dl. Support for setting the type was added for vlan 1383 and bond interfaces. 1384 @param interface The interface the link layer address is being 1385 changed on. 1386 @param lladdr A pointer to the raw link layer address (pointer to 1387 the 6 byte ethernet address for ethernet). 1388 @param lladdr_len The length, in bytes, of the link layer address. 1389 @param type The link-layer address type. 1390 */ 1391errno_t ifnet_set_lladdr_and_type(ifnet_t interface, const void* lladdr, size_t length, u_char type); 1392#endif KERNEL_PRIVATE 1393 1394/*! 1395 @function ifnet_resolve_multicast 1396 @discussion Resolves a multicast address for an attached protocol to 1397 a link-layer address. If a link-layer address is passed in, the 1398 interface will verify that it is a valid multicast address. 1399 @param interface The interface. 1400 @param proto_addr A protocol address to be converted to a link-layer 1401 address. 1402 @param ll_addr Storage for the resulting link-layer address. 1403 @param ll_len Length of the storage for the link-layer address. 1404 @result 0 on success. EOPNOTSUPP indicates the multicast address was 1405 not supported or could not be translated. Other errors may 1406 indicate other failures. 1407 */ 1408errno_t ifnet_resolve_multicast(ifnet_t ifp, const struct sockaddr *proto_addr, 1409 struct sockaddr *ll_addr, size_t ll_len); 1410 1411/*! 1412 @function ifnet_add_multicast 1413 @discussion Joins a multicast and returns an ifmultiaddr_t with the 1414 reference count incremented for you. You are responsible for 1415 decrementing the reference count after calling 1416 ifnet_remove_multicast and making sure you no longer have any 1417 references to the multicast. 1418 @param interface The interface. 1419 @param maddr The multicast address to join. Either a physical 1420 address or logical address to be translated to a physical 1421 address. 1422 @param multicast The resulting ifmultiaddr_t multicast address. 1423 @result 0 on success otherwise the errno error. 1424 */ 1425errno_t ifnet_add_multicast(ifnet_t interface, const struct sockaddr *maddr, 1426 ifmultiaddr_t *multicast); 1427 1428/*! 1429 @function ifnet_remove_multicast 1430 @discussion Causes the interface to leave the multicast group. The 1431 stack keeps track of how many times ifnet_add_multicast has been 1432 called for a given multicast address. The multicast will only be 1433 removed when the number of times ifnet_remove_multicast has been 1434 called matches the number of times ifnet_add_multicast has been 1435 called. 1436 1437 The memory for the multicast address is not actually freed until 1438 the separate reference count has reached zero. Some parts of the 1439 stack may keep a pointer to the multicast even after that 1440 multicast has been removed from the interface. 1441 1442 When an interface is detached, all of the multicasts are 1443 removed. If the interface of the multicast passed in is no 1444 longer attached, this function will gracefully return, 1445 performing no work. 1446 1447 It is the callers responsibility to release the multicast 1448 address after calling this function. 1449 @param multicast The multicast to be removed. 1450 @result 0 on success otherwise the errno error. 1451 */ 1452errno_t ifnet_remove_multicast(ifmultiaddr_t multicast); 1453 1454/*! 1455 @function ifnet_get_multicast_list 1456 @discussion Retrieves a list of multicast address the interface is 1457 set to receive. This function allocates and returns an array of 1458 references to the various multicast addresses. The multicasts 1459 have their reference counts bumped on your behalf. Calling 1460 ifnet_free_multicast_list will decrement the reference counts 1461 and free the array. 1462 @param interface The interface. 1463 @param multicasts A pointer to a NULL terminated array of references 1464 to the multicast addresses. 1465 @result 0 on success otherwise the errno error. 1466 */ 1467errno_t ifnet_get_multicast_list(ifnet_t interface, ifmultiaddr_t **addresses); 1468 1469/*! 1470 @function ifnet_free_multicast_list 1471 @discussion Frees a list of multicasts returned by 1472 ifnet_get_multicast_list. Decrements the refcount on each 1473 multicast address and frees the array. 1474 @param multicasts An array of references to the multicast addresses. 1475 @result 0 on success otherwise the errno error. 1476 */ 1477void ifnet_free_multicast_list(ifmultiaddr_t *multicasts); 1478 1479/*! 1480 @function ifnet_find_by_name 1481 @discussion Find an interface by the name including the unit number. 1482 Caller must call ifnet_release on any non-null interface return 1483 value. 1484 @param name The name of the interface, including any unit number 1485 (i.e. "en0"). 1486 @param interface A pointer to an interface reference. This will be 1487 filled in if a matching interface is found. 1488 @result 0 on success otherwise the errno error. 1489 */ 1490errno_t ifnet_find_by_name(const char *ifname, ifnet_t *interface); 1491 1492/*! 1493 @function ifnet_list_get 1494 @discussion Get a list of attached interfaces. List will be set to 1495 point to an array allocated by ifnet_list_get. The interfaces 1496 are refcounted and the counts will be incremented before the 1497 function returns. The list of interfaces must be freed using 1498 ifnet_list_free. 1499 @param family The interface family (i.e. IFNET_FAMILY_ETHERNET). To 1500 find interfaces of all families, use IFNET_FAMILY_ANY. 1501 @param interfaces A pointer to an array of interface references. 1502 @param count A pointer that will be filled in with the number of 1503 matching interfaces in the array. 1504 @result 0 on success otherwise the errno error. 1505 */ 1506errno_t ifnet_list_get(ifnet_family_t family, ifnet_t **interfaces, u_int32_t *count); 1507 1508#ifdef KERNEL_PRIVATE 1509/*! 1510 @function ifnet_list_get_all 1511 @discussion Get a list of attached interfaces. List will be set to 1512 point to an array allocated by ifnet_list_get. The interfaces 1513 are refcounted and the counts will be incremented before the 1514 function returns. The list of interfaces must be freed using 1515 ifnet_list_free. This is similar to ifnet_list_get, except 1516 that it includes interfaces that are detaching. 1517 @param family The interface family (i.e. IFNET_FAMILY_ETHERNET). To 1518 find interfaces of all families, use IFNET_FAMILY_ANY. 1519 @param interfaces A pointer to an array of interface references. 1520 @param count A pointer that will be filled in with the number of 1521 matching interfaces in the array. 1522 @result 0 on success otherwise the errno error. 1523 */ 1524errno_t ifnet_list_get_all(ifnet_family_t family, ifnet_t **interfaces, u_int32_t *count); 1525#endif /* KERNEL_PRIVATE */ 1526 1527/*! 1528 @function ifnet_list_free 1529 @discussion Free a list of interfaces returned by ifnet_list_get. 1530 Decrements the reference count on each interface and frees the 1531 array of references. If you keep a reference to an interface, be 1532 sure to increment the reference count before calling 1533 ifnet_list_free. 1534 @param interfaces An array of interface references from ifnet_list_get. 1535 */ 1536void ifnet_list_free(ifnet_t *interfaces); 1537 1538/********************************************************************************************/ 1539/* ifaddr_t accessors */ 1540/********************************************************************************************/ 1541 1542/*! 1543 @function ifaddr_reference 1544 @discussion Increment the reference count of an address tied to an 1545 interface. 1546 @param ifaddr The interface address. 1547 @result 0 upon success 1548 */ 1549errno_t ifaddr_reference(ifaddr_t ifaddr); 1550 1551/*! 1552 @function ifaddr_release 1553 @discussion Decrements the reference count of and possibly frees an 1554 address tied to an interface. 1555 @param ifaddr The interface address. 1556 @result 0 upon success 1557 */ 1558errno_t ifaddr_release(ifaddr_t ifaddr); 1559 1560/*! 1561 @function ifaddr_address 1562 @discussion Copies the address out of the ifaddr. 1563 @param ifaddr The interface address. 1564 @param out_addr The sockaddr storage for the address. 1565 @param addr_size The size of the storage for the address. 1566 @result 0 upon success 1567 */ 1568errno_t ifaddr_address(ifaddr_t ifaddr, struct sockaddr *out_addr, u_int32_t addr_size); 1569 1570/*! 1571 @function ifaddr_address 1572 @discussion Returns the address family of the address. 1573 @param ifaddr The interface address. 1574 @result 0 on failure, address family on success. 1575 */ 1576sa_family_t ifaddr_address_family(ifaddr_t ifaddr); 1577 1578/*! 1579 @function ifaddr_dstaddress 1580 @discussion Copies the destination address out of the ifaddr. 1581 @param ifaddr The interface address. 1582 @param out_dstaddr The sockaddr storage for the destination address. 1583 @param dstaddr_size The size of the storage for the destination address. 1584 @result 0 upon success 1585 */ 1586errno_t ifaddr_dstaddress(ifaddr_t ifaddr, struct sockaddr *out_dstaddr, u_int32_t dstaddr_size); 1587 1588/*! 1589 @function ifaddr_netmask 1590 @discussion Copies the netmask out of the ifaddr. 1591 @param ifaddr The interface address. 1592 @param out_netmask The sockaddr storage for the netmask. 1593 @param netmask_size The size of the storage for the netmask. 1594 @result 0 upon success 1595 */ 1596errno_t ifaddr_netmask(ifaddr_t ifaddr, struct sockaddr *out_netmask, u_int32_t netmask_size); 1597 1598/*! 1599 @function ifaddr_ifnet 1600 @discussion Returns the interface the address is attached to. The 1601 reference is only valid until the ifaddr is released. If you 1602 need to hold a reference to the ifnet for longer than you hold a 1603 reference to the ifaddr, increment the reference using 1604 ifnet_reference. 1605 @param ifaddr The interface address. 1606 @result A reference to the interface the address is attached to. 1607 */ 1608ifnet_t ifaddr_ifnet(ifaddr_t ifaddr); 1609 1610/*! 1611 @function ifaddr_withaddr 1612 @discussion Returns an interface address with the address specified. 1613 Increments the reference count on the ifaddr before returning to 1614 the caller. Caller is responsible for calling ifaddr_release. 1615 @param address The address to search for. 1616 @result A reference to the interface address. 1617 */ 1618ifaddr_t ifaddr_withaddr(const struct sockaddr* address); 1619 1620/*! 1621 @function ifaddr_withdstaddr 1622 @discussion Returns an interface address for the interface address 1623 that matches the destination when the netmask is applied. 1624 Increments the reference count on the ifaddr before returning to 1625 the caller. Caller is responsible for calling ifaddr_release. 1626 @param destination The destination to search for. 1627 @result A reference to the interface address. 1628 */ 1629ifaddr_t ifaddr_withdstaddr(const struct sockaddr* destination); 1630 1631/*! 1632 @function ifaddr_withnet 1633 @discussion Returns an interface address for the interface with the 1634 network described by net. Increments the reference count on the 1635 ifaddr before returning to the caller. Caller is responsible for 1636 calling ifaddr_release. 1637 @param net The network to search for. 1638 @result A reference to the interface address. 1639 */ 1640ifaddr_t ifaddr_withnet(const struct sockaddr* net); 1641 1642/*! 1643 @function ifaddr_withroute 1644 @discussion Returns an interface address given a destination and 1645 gateway. Increments the reference count on the ifaddr before 1646 returning to the caller. Caller is responsible for calling 1647 ifaddr_release. 1648 @param flags Routing flags. See net/route.h, RTF_GATEWAY etc. 1649 @param destination The destination to search for. 1650 @param gateway A gateway to search for. 1651 @result A reference to the interface address. 1652 */ 1653ifaddr_t ifaddr_withroute(int flags, const struct sockaddr* destination, 1654 const struct sockaddr* gateway); 1655 1656/*! 1657 @function ifaddr_findbestforaddr 1658 @discussion Finds the best local address assigned to a specific 1659 interface to use when communicating with another address. 1660 Increments the reference count on the ifaddr before returning to 1661 the caller. Caller is responsible for calling ifaddr_release. 1662 @param addr The remote address. 1663 @param interface The local interface. 1664 @result A reference to the interface address. 1665 */ 1666ifaddr_t ifaddr_findbestforaddr(const struct sockaddr *addr, ifnet_t interface); 1667 1668/********************************************************************************************/ 1669/* ifmultiaddr_t accessors */ 1670/********************************************************************************************/ 1671 1672/*! 1673 @function ifmaddr_reference 1674 @discussion Increment the reference count of an interface multicast 1675 address. 1676 @param ifmaddr The interface multicast address. 1677 @result 0 on success. Only error will be EINVAL if ifmaddr is not valid. 1678 */ 1679errno_t ifmaddr_reference(ifmultiaddr_t ifmaddr); 1680 1681/*! 1682 @function ifmaddr_release 1683 @discussion Decrement the reference count of an interface multicast 1684 address. If the reference count reaches zero, the ifmultiaddr 1685 will be removed from the interface and the ifmultiaddr will be 1686 freed. 1687 @param ifmaddr The interface multicast address. 1688 @result 0 on success. Only error will be EINVAL if ifmaddr is not valid. 1689 */ 1690errno_t ifmaddr_release(ifmultiaddr_t ifmaddr); 1691 1692/*! 1693 @function ifmaddr_address 1694 @discussion Copies the multicast address to out_multicast. 1695 @param out_multicast Storage for a sockaddr. 1696 @param addr_size Size of the storage. 1697 @result 0 on success. 1698 */ 1699errno_t ifmaddr_address(ifmultiaddr_t ifmaddr, struct sockaddr *out_multicast, u_int32_t addr_size); 1700 1701/*! 1702 @function ifmaddr_lladdress 1703 @discussion Copies the link layer multicast address to 1704 out_link_layer_multicast. 1705 @param out_link_layer_multicast Storage for a sockaddr. 1706 @param addr_size Size of the storage. 1707 @result 0 on success. 1708 */ 1709errno_t ifmaddr_lladdress(ifmultiaddr_t ifmaddr, struct sockaddr *out_link_layer_multicast, 1710 u_int32_t addr_size); 1711 1712/*! 1713 @function ifmaddr_ifnet 1714 @discussion Returns the interface this multicast address is attached 1715 to. The interface reference count is not bumped by this 1716 function. The interface is only valid as long as you don't 1717 release the refernece to the multiast address. If you need to 1718 maintain your pointer to the ifnet, call ifnet_reference 1719 followed by ifnet_release when you're finished. 1720 @param ifmaddr The interface multicast address. 1721 @result A reference to the interface. 1722 */ 1723ifnet_t ifmaddr_ifnet(ifmultiaddr_t ifmaddr); 1724 1725__END_DECLS 1726 1727#endif 1728