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