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