-
Notifications
You must be signed in to change notification settings - Fork 0
/
IONetworkController.h
1682 lines (1451 loc) · 79.1 KB
/
IONetworkController.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
* Copyright (c) 1998-2008 Apple Inc. All rights reserved.
*
* @APPLE_LICENSE_HEADER_START@
*
* The contents of this file constitute Original Code as defined in and
* are subject to the Apple Public Source License Version 1.1 (the
* "License"). You may not use this file except in compliance with the
* License. Please obtain a copy of the License at
* http://www.apple.com/publicsource and read it before using this file.
*
* This Original Code and all software distributed under the License are
* distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
* License for the specific language governing rights and limitations
* under the License.
*
* @APPLE_LICENSE_HEADER_END@
*/
#ifndef _IONETWORKCONTROLLER_H
#define _IONETWORKCONTROLLER_H
/*! @defined kIONetworkControllerClass
@abstract The name of the IONetworkController class. */
#define kIONetworkControllerClass "IONetworkController"
/*! @defined kIOVendor
@abstract A property of IONetworkController objects.
@discussion The kIOVendor property is a property of IONetworkController objects. It has an OSString value that describes the vendor of the network controller. */
#define kIOVendor "IOVendor"
/*! @defined kIOModel
@abstract A property of IONetworkController objects.
@discussion The kIOModel property is a property of IONetworkController objects. It has an OSString value that describes the model of the network controller. */
#define kIOModel "IOModel"
/*! @defined kIORevision
@abstract A property of IONetworkController objects.
@discussion The kIORevision property is a property of IONetworkController objects. It has an OSString value that describes the revision level of the network controller. */
#define kIORevision "IORevision"
/*! @defined kIOFeatures
@abstract A property of IONetworkController objects.
@discussion The kIOFeatures property is a property of IONetworkController objects. It has an OSNumber value that describes generic features defined by IONetworkController that are supported by the
network controller. */
#define kIOFeatures "IOFeatures"
/*! @defined kIOMediumDictionary
@abstract A property of IONetworkController objects.
@discussion The kIOMediumDictionary property is a property of IONetworkController
objects. It has an OSDictionary value that is a container for the
collection of IONetworkMedium objects that represent the media
types supported by the network controller.
Each entry in the dictionary is a key/value pair consisting of
the medium name, and a dictionary value that contains the
properties for that medium entry. */
#define kIOMediumDictionary "IOMediumDictionary"
/*! @defined kIODefaultMedium
@abstract A property of IONetworkController objects.
@discussion The kIODefaultMedium property is a property of IONetworkController
objects. It has an OSString value that describes the name of the
default medium. This definition may change or disappear in the
future. */
#define kIODefaultMedium "IODefaultMedium"
/*! @defined kIOSelectedMedium
@abstract A property of IONetworkController objects.
@discussion The kIOSelectedMedium property is a property of IONetworkController
objects. It has an OSSymbol value that describes the name of the
current selected medium. This name can be used as a key into the
medium dictionary to gather additional information about the
selected medium. */
#define kIOSelectedMedium "IOSelectedMedium"
/*! @defined kIOActiveMedium
@abstract A property of IONetworkController objects.
@discussion The kIOActiveMedium property is a property of IONetworkController
objects. It has an OSSymbol value that describes the name of the
active medium. This is the name of the medium where an active
link has been established. This name can be used as a key into
the medium dictionary to gather additional information about the
active medium. */
#define kIOActiveMedium "IOActiveMedium"
/*! @defined kIOLinkSpeed
@abstract A property of IONetworkController objects.
@discussion The kIOLinkSpeed property is a property of IONetworkController
objects. It has an OSNumber value that describes the speed of the
link established over the active medium in bits per second. */
#define kIOLinkSpeed "IOLinkSpeed"
/*! @defined kIOLinkStatus
@abstract A property of IONetworkController objects.
@discussion The kIOLinkStatus property is a property of IONetworkController
objects. It has an OSNumber value that describes the current network
link status. See IONetworkMedium for the definition of the link
status bits. */
#define kIOLinkStatus "IOLinkStatus"
/*! @defined kIOLinkData
@abstract A property of IONetworkController objects.
@discussion The kIOLinkData property is a property of IONetworkController
objects. It has an OSData value that contains additional information
describing the active link that was established.
Its interpretation is not defined. */
#define kIOLinkData "IOLinkData"
/*! @defined kIOPacketFilters
@abstract A property of IONetworkController objects.
@discussion The kIOPacketFilters property is a property of IONetworkController
objects. It has an OSDictionary value that describes the entire
set of packet filters supported by the controller. Each entry
in the dictionary is a key/value pair consisting of the filter
group name, and an OSNumber describing the set of supported
filters for that group. */
#define kIOPacketFilters "IOPacketFilters"
/*! @defined kIOMACAddress
@abstract A property of IONetworkController objects.
@discussion The kIOMACAddress property is a property of IONetworkController
objects. It has an OSData value that describes the hardware
MAC (media access controller) address, or station address,
of the network controller. */
#define kIOMACAddress "IOMACAddress"
/*! @defined kIOMaxPacketSize
@abstract A property of IONetworkController objects.
@discussion The kIOMaxPacketSize property is a property of IONetworkController
objects. It has an OSNumber value that describes the maximum
packet size supported by the controller. */
#define kIOMaxPacketSize "IOMaxPacketSize"
/*! @defined kIOMinPacketSize
@abstract A property of IONetworkController objects.
@discussion The kIOMinPacketSize property is a property of IONetworkController
objects. It has an OSNumber value that describes the minimum
packet size supported by the controller. */
#define kIOMinPacketSize "IOMinPacketSize"
/*! @defined kIONetworkFilterGroup
@abstract The name assigned to the standard network filter group. */
#define kIONetworkFilterGroup "IONetworkFilterGroup"
/*! @enum StandardPacketFilters
@abstract All standard packet filters.
@discussion Each filter will allow the reception of certain class of packets
depending on its destination MAC address.
@constant kIOPacketFilterUnicast Reception of unicast packets.
@constant kIOPacketFilterBroadcast Reception of broadcast packets.
@constant kIOPacketFilterMulticast Reception of multicast packets
addressed to a set of multicast addresses.
@constant kIOPacketFilterMulticastAll Reception of all multicast
packets.
@constant kIOPacketFilterPromiscuous Reception of all packets.
@constant kIOPacketFilterPromiscuousAll Reception of all packets,
including bad packets. */
enum {
kIOPacketFilterUnicast = 0x1,
kIOPacketFilterBroadcast = 0x2,
kIOPacketFilterMulticast = 0x10,
kIOPacketFilterMulticastAll = 0x20,
kIOPacketFilterPromiscuous = 0x100,
kIOPacketFilterPromiscuousAll = 0x200
};
/*! @enum Network Feature Flags
@abstract Feature flags returned by the getFeatures() method.
@constant kIONetworkFeatureNoBSDWait Set this bit in the value
returned by getFeatures() to disable the automatic wait for
"IOBSD" resource by the IONetworkController::start() method.
@constant kIONetworkFeatureHardwareVlan Set this bit in the value
returned by getFeatures() to indicate the controller supports hardware
stripping and stuffing of 802.1q vlan tags. If the controller supports
this feature it must enable it when initializing so that all received
packets delivered to higher layers have the tag stripped. The controller
should use setVlanTag() to provide the tag information out of band.
@constant kIONetworkFeatureSoftwareVlan Set this bit in the value
returned by getFeatures() to indicate that the controller can support software
based vlan by transmitting and receiving packets 4 bytes longer that normal.
@constant kIONetworkFeatureMultiPages Set this bit if the driver is
capable of handling packets coming down from the network stack that
reside in virtually, but not in physically contiguous span of the
external mbuf clusters. In this case, the data area of a packet in
the external mbuf cluster might cross one or more physical pages that
are disjoint, depending on the interface MTU and the packet size.
Such a use of larger than system page size clusters by the network
stack is done for better system efficiency. Drivers that utilize the
IOMbufNaturalMemoryCursor with the getPhysicalSegmentsWithCoalesce
interfaces and enumerate the list of vectors should set this flag
for possible gain in performance during bulk data transfer.
@constant kIONetworkFeatureTSOIPv4 Set this bit to advertise support
for TCP/IPv4 segmentation offload.
@constant kIONetworkFeatureTSOIPv6 Set this bit to advertise support
for TCP/IPv6 segmentation offload.
@constant kIONetworkFeatureTransmitCompletionStatus Set this bit to
advertise the capability to report per-packet transmit completion status.
See <code>IONetworkInterface::reportTransmitCompletionStatus</code>.
*/
enum {
kIONetworkFeatureNoBSDWait = 0x01,
kIONetworkFeatureHardwareVlan = 0x02,
kIONetworkFeatureSoftwareVlan = 0x04,
kIONetworkFeatureMultiPages = 0x08,
kIONetworkFeatureTSOIPv4 = 0x10,
kIONetworkFeatureTSOIPv6 = 0x20,
kIONetworkFeatureTransmitCompletionStatus = 0x40
};
#ifdef KERNEL
#ifdef __cplusplus
#include <IOKit/IOService.h>
#include <IOKit/IOWorkLoop.h>
#include <IOKit/network/IONetworkInterface.h>
#include <IOKit/network/IOKernelDebugger.h>
class IOCommandGate;
class IOOutputQueue;
class IONetworkMedium;
/*! @typedef IOPacketBufferConstraints
@discussion Constraint parameters, specified by a driver,
for the data buffer in a packet mbuf. This is observed by
allocatePacket() to satisfy the stated requirements.
@field alignStart Starting address byte alignment.
@field alignLength Buffer length byte alignment. */
typedef struct {
UInt32 alignStart;
UInt32 alignLength;
UInt32 reserved[6];
} IOPacketBufferConstraints;
// Some frequently used alignment constants.
//
enum {
kIOPacketBufferAlign1 = 1,
kIOPacketBufferAlign2 = 2,
kIOPacketBufferAlign4 = 4,
kIOPacketBufferAlign8 = 8,
kIOPacketBufferAlign16 = 16,
kIOPacketBufferAlign32 = 32
};
/*! @const gIONetworkFilterGroup
@discussion gIONetworkFilterGroup is an OSSymbol object that contains
the name of the standard network filter group as defined by
kIONetworkFilterGroup. */
extern const OSSymbol * gIONetworkFilterGroup;
/*! @class IONetworkController
@abstract Implements the framework for a generic
network controller.
@discussion A subclass of IONetworkController must provide
additional functionality specific for a particular networking type.
In addition, the driver must implement (override) a basic set of
hardware dependent methods to create a working driver.
IONetworkController attaches itself to the data link layer (DLIL) via
an IONetworkInterface object. A controller object without a companion
interface is not accessible to the networking system. The controller
interacts with DLIL by calling methods defined by the interface object.
And conversely, DLIL will issue commands and packets to the controller
through the interface object.
IONetworkController will create an IOCommandGate and attach this
event source to an IOWorkLoop object. All commands sent from the
interface object are handled through the IOCommandGate object,
which will serialize access to the controller. Outbound packets sent
from the interface to the controller have no implicit serialization.
Drivers must implement an output function that is thread safe, or use
an IOOutputQueue object which will provide a serialization model.
Note: IONetworkController internally uses some private messaging constants
in the sys_iokit | sub_iokit_networking range defined in
"IONetworkControllerPrivate.h". If you create a client for your controller
(for example an IOUserClient), and it overrides the IOService::message
method, your client may receive these messages. It should ignore these
messages and pass them to super::message()
*/
class IONetworkController : public IOService
{
OSDeclareAbstractStructors( IONetworkController )
private:
IOWorkLoop * _workLoop;
IOCommandGate * _cmdGate;
IOOutputQueue * _outputQueue;
OSSet * _clientSet;
OSCollectionIterator * _clientSetIter;
OSObject * _cmdClient;
UInt32 _alignStart;
UInt32 _alignLength;
UInt32 _alignPadding;
bool _propertiesPublished;
IOLock * _mediumLock;
IODebuggerLockState _debugLockState;
SInt32 _debugLockCount;
OSNumber * _linkStatus;
OSNumber * _linkSpeed;
const OSData * _lastLinkData;
const OSSymbol * _lastActiveMediumName;
const OSSymbol * _lastCurrentMediumName;
mbuf_t _freeList;
struct ExpansionData { };
/*! @var reserved
Reserved for future use. (Internal use only) */
ExpansionData * _reserved;
bool _broadcastEvent(UInt32 type, void * data = 0);
static void debugRxHandler(IOService * handler,
void * buffer,
UInt32 * length,
UInt32 timeout);
static void debugTxHandler(IOService * handler,
void * buffer,
UInt32 length);
static UInt32 debugLinkStatusHandler(IOService * handler);
static bool debugSetModeHandler(IOService * handler, bool active);
static IOReturn executeCommandAction(OSObject * owner,
void * arg0,
void * arg1,
void * arg2,
void * arg3);
static IOReturn handleCommand(void * target,
void * param0,
void * param1,
void * param2,
void * param3);
public:
/*! @function init
@abstract Initializes the IONetworkController object.
@discussion Instance variables are initialized, then super::init()
is called.
@param properties A dictionary object containing a property table
associated with this instance.
@result Returns true on success, false otherwise.
*/
virtual bool init(OSDictionary * properties);
/*! @function start
@abstract Starts the network controller.
@discussion After the controller driver has successfully matched
to a provider, this method is called to start the network controller.
IONetworkController will allocate resources and gather controller
properties in its implementation. No I/O will be performed until
the subclass tries to attach a client object. A driver must override
this method, and call super::start() at the beginning of its own
implementation. Then check the return value to make sure that its
superclass was started successfully before proceeding. Tasks that
are usually performed by a driver's start method are: resource
allocation, hardware initialization, allocation of IOEventSources
and attaching them to a workloop, publishing a medium dictionary,
and finally, attaching an interface object when it is ready to
handle client requests.
@param provider The provider that the controller was matched
(and attached) to.
@result Returns true on success, false otherwise.
*/
virtual bool start(IOService * provider);
/*! @function stop
@abstract Stops the network controller.
@discussion The counterpart of start(). The controller has been
instructed to stop running. The stop() method should release
resources and undo actions performed by the start() method.
Subclasses must override this method and call super::stop()
at the end of its implementation.
@param provider The provider that the controller was matched
(and attached) to. */
virtual void stop(IOService * provider);
/*! @function message
@abstract Receives messages delivered from an attached provider.
@discussion Handles the <code>kIOMessageDeviceSignaledWakeup</code> message
from a provider identifying the IONetworkController as the wakeup source.
@param type A type defined in <code>IOMessage.h</code>.
@param provider The provider from which the message originates.
@param argument An argument defined by the message type.
@result An IOReturn code defined by the message type.
*/
virtual IOReturn message(
UInt32 type, IOService * provider, void * argument );
/*! @typedef IONetworkController::Action
@discussion Definition of a C function that can be called
through executeCommand().
@param target The first argument passed to action.
@param param0 Action parameter 0.
@param param1 Action parameter 1.
@param param2 Action parameter 2.
@param param3 Action parameter 3. */
typedef IOReturn (*Action)(void * target, void * param0,
void * param1,
void * param2,
void * param3);
/*! @function executeCommand
@abstract Makes a C function call through the command gate.
@discussion This method makes a call to a C function that will be synchronized
with the workloop thread, and any other threads that are called
with the workloop's gate closed.
@param client The client requesting the action. This parameter is not
passed to the function.
@param action Pointer to a C function to be executed.
@param target The first parameter in the action callout.
@param param0 Action parameter 0.
@param param1 Action parameter 1.
@param param2 Action parameter 2.
@param param3 Action parameter 3.
@result Returns the value returned by the action.
*/
virtual IOReturn executeCommand(OSObject * client,
Action action,
void * target,
void * param0 = 0,
void * param1 = 0,
void * param2 = 0,
void * param3 = 0);
/*! @function outputPacket
@abstract Transmits an output packet.
@discussion If an IOOutputQueue was created by createOutputQueue(),
then this method will be called by the output queue object.
Otherwise, an interface object will call this method directly when
it receives an output packet from the data link layer.
There is no upper limit on the number of mbufs, hence the number of
memory fragments, in the mbuf chain provided. Drivers must be able to
handle cases when the mbuf count might exceed the limit supported by their
DMA engines, and perform coalescing to copy the various memory fragments
into a lesser number of fragments. This complexity can be hidden from
the driver when an IOMbufMemoryCursor is used, which is able to convert
an mbuf chain into a physical address scatter-gather list that will not
exceed a specified number of physically contiguous memory segments.
See IOMbufMemoryCursor.
The implementation in IONetworkController performs no useful action
and will drop all packets. A driver must override this method and
process the output packet provided. The implementation in the driver
must not block, since this may cause the network stack to be reentered
from an unsafe point.
@param mbuf_t An mbuf chain containing the output packet to be sent on
the network.
@param param A parameter provided by the caller.
@result Returns a return code defined by the caller.
*/
virtual UInt32 outputPacket(mbuf_t, void * param);
/*! @function getFeatures
@abstract Reports generic features supported by the controller and/or
the driver.
@result This method will always return 0. Subclasses may override
this method and return a bit mask of all supported features. */
virtual UInt32 getFeatures() const;
/*! @function newVendorString
@result Returns a string describing the vendor of the network controller.
The caller is responsible for releasing the string object returned. */
virtual const OSString * newVendorString() const;
/*! @function newModelString
@result Returns a string describing the model of the network controller.
The caller is responsible for releasing the string object returned. */
virtual const OSString * newModelString() const;
/*! @function newRevisionString
@result Returns a string describing the hardware revision of the
network controller. The caller is responsible for releasing the
string object returned. */
virtual const OSString * newRevisionString() const;
/*! @function getSelectedMedium
@abstract Gets the current selected medium.
@discussion If the driver has previously called setSelectedMedium()
to indicate its current media selection, then this method will return
that medium object. Otherwise, the driver's property table is
consulted and a default medium property is examined, and the
corresponding entry in the medium dictionary is returned.
@result Returns the current selected medium, the default medium, or 0.
*/
virtual const IONetworkMedium * getSelectedMedium() const;
const IONetworkMedium * getCurrentMedium() const;
/*! @function getMediumDictionary
@abstract Returns the medium dictionary published by the driver.
@discussion Returns the medium dictionary published by the driver
through publishMediumDictionary(). Use copyMediumDictionary() to
create and get a copy of the medium dictionary.
@result Returns the published medium dictionary, or 0 if the driver has not
yet published a medium dictionary through publishMediumDictionary().
*/
virtual const OSDictionary * getMediumDictionary() const;
/*! @function copyMediumDictionary
@abstract Returns a copy of the medium dictionary published by the
driver.
@discussion The caller is responsible for releasing the dictionary
object returned. Use getMediumDictionary() to get a reference to the
published medium dictionary instead of creating a copy.
@result Returns a copy of the medium dictionary, or 0 if the driver has not
published a medium dictionary through publishMediumDictionary().
*/
virtual OSDictionary * copyMediumDictionary() const;
/*! @function getOutputHandler
@abstract Gets the address of the method designated to handle output
packets for the network controller.
@result Returns a pointer to the outputPacket() method.
*/
virtual IOOutputAction getOutputHandler() const;
/*! @function doEnable
@abstract Makes a synchronized call to enable() through executeCommand().
@discussion Do not use this method, it may be removed in the future.
See enable().
*/
virtual IOReturn doEnable(IOService * client);
/*! @function doDisable
@abstract Makes a synchronized call to disable() through executeCommand().
@discussion Do not use this method, it may be removed in the future.
See disable().
*/
virtual IOReturn doDisable(IOService * client);
/*! @function getCommandGate
@abstract Gets the IOCommandGate object created by IONetworkController.
@discussion When IONetworkController is started, an IOCommandGate object
is instantiated and attached to the workloop returned by getWorkLoop().
This IOCommandGate object is used internally to synchronize client
commands handled through executeCommand(). Subclasses that need an
IOCommandGate should try to reuse the object returned by this method,
rather than creating a new instance. See IOCommandGate documentation.
@result Returns the IOCommandGate object created by IONetworkController.
*/
virtual IOCommandGate * getCommandGate() const;
/*! @function getHardwareAddress
@abstract Gets the network controller's permanent hardware/station
address.
@discussion This method call is synchronized by the workloop's gate.
@param addr The buffer where the controller's hardware address should
be stored.
@param inOutAddrBytes The size of the address buffer provided by the
client, and replaced by this method with the actual size of
the hardware address in bytes.
@result Returns kIOReturnSuccess on success, or an error otherwise.
*/
virtual IOReturn getHardwareAddress(void * addr,
UInt32 * inOutAddrBytes) = 0;
/*! @function setHardwareAddress
@abstract Sets or changes the station address used by the network
controller.
@discussion This method call is synchronized by the workloop's gate.
@param addr The buffer containing the hardware address provided by
the client.
@param addrBytes The size of the address buffer provided by the
client in bytes.
@result Returns kIOReturnSuccess on success, or an error otherwise.
*/
virtual IOReturn setHardwareAddress(const void * addr,
UInt32 addrBytes) = 0;
/*! @function enable
@abstract Handles an enable request from a client.
@discussion This method handles an enable request from a client. A client will call
enable after it has opened the controller, and before it starts to use
the controller to send and to receive packets over the network. The
client object provided is typecasted using OSDynamicCast, and depending
on whether the client is an IOKernelDebugger or an IONetworkInterface,
then an overloaded enable method that takes a more specific argument
type is called. If the client matches neither type, then
kIOReturnBadArgument is returned. A driver has the option of overriding
this base enable method, or the overloaded form. This method call is
synchronized by the workloop's gate.
@param client The client object requesting the enable.
@result Returns the return value from the overloaded enable() method, or
kIOReturnBadArgument if the client type is unknown.
*/
virtual IOReturn enable(IOService * client);
/*! @function disable
@abstract Handles a disable request from a client.
@discussion This method handles a disable request from a client. A client will call
disable if it has previously enabled the controller, and it no longer
needs to transport packets or perform I/O using the controller.
The client object is typecasted using OSDynamicCast, and depending on
whether the client is an IOKernelDebugger or an IONetworkInterface,
then an overloaded disable method that takes a more specific argument
type is called. If the client matches neither type, then
kIOReturnBadArgument is returned. A driver has the option of overriding
this base disable method, or the overloaded form. This method call is
synchronized by the workloop's gate.
@param client The client object requesting the disable.
@result Returns the return from the overloaded disable() method, or
kIOReturnBadArgument if the client type is unknown.
*/
virtual IOReturn disable(IOService * client);
/*! @function setMaxPacketSize
@abstract A client request to change the maximum packet size.
@discussion This method call is synchronized by the workloop's gate.
@param maxSize The new maximum packet size.
@result Returns kIOReturnUnsupported. Drivers may override this method
and return either kIOReturnSuccess to indicate that the new size
was accepted and is in effect, or an error code to indicate failure.
*/
virtual IOReturn setMaxPacketSize(UInt32 maxSize);
/*! @function getMaxPacketSize
@abstract Gets the maximum packet size supported by the controller.
@param maxSize Pointer to the return value.
@result Returns kIOReturnSuccess on success, or an error code otherwise.
*/
virtual IOReturn getMaxPacketSize(UInt32 * maxSize) const = 0;
/*! @function getMinPacketSize
@abstract Gets the minimum packet size supported by the controller.
@param minSize Pointer to the return value.
@result Returns kIOReturnSuccess on success, or an error code otherwise.
*/
virtual IOReturn getMinPacketSize(UInt32 * minSize) const = 0;
/*! @function selectMedium
@abstract A client request to change the medium selection.
@discussion This method is called when a client issues a command
for the controller to change its current medium selection.
The implementation must call setSelectedMedium() after the change
has occurred. This method call is synchronized by the workloop's
gate.
@param medium An entry from the published medium dictionary that
represents the selection chosen by the client.
@result Returns kIOReturnUnsupported. Drivers may override this method and
return kIOReturnSuccess if the selection was successful,
or an error code otherwise.
*/
virtual IOReturn selectMedium(const IONetworkMedium * medium);
/*! @function selectMediumWithName
@abstract A client request to change the medium selection.
@discussion This method is called when a client issues a command
for the controller to change its current medium selection.
This implementation will look for an entry in the medium
dictionary published by the driver that is associated with the
key given. If a match is found, then selectMedium() is called to
perform the selection, otherwise an error is reported back to the
client. Subclasses should override selectMedium() and not this
method. This method call is synchronized by the workloop's gate.
@param mediumName An OSSymbol object that describes the name of the
new medium selected by the client.
@result Returns the return from selectMedium() if a matching entry was found
from the medium dictionary. Returns kIOReturnUnsupported if a medium
dictionary does not exist, or kIOReturnBadArgument if the name given
does not match any entry in the medium dictionary.
*/
virtual IOReturn selectMediumWithName(const OSSymbol * mediumName);
/*! @function getPacketFilters
@abstract Gets the set of packet filters supported by the network
controller for the given filter group.
@discussion A subclass must implement this method and report the
set of filters that are supported for the given filter group.
This method call is synchronized by the workloop's gate.
@param group The name of the filter group.
@param filters Pointer to the mask of supported filters returned by
this method.
@result Returns kIOReturnSuccess on success, or an error to indicate a
failure to discover the set of supported filters.
*/
virtual IOReturn getPacketFilters(const OSSymbol * group,
UInt32 * filters) const = 0;
/*! @function enablePacketFilter
@abstract Enables one of the supported packet filters from the
given filter group.
@discussion A client will call this method to enable a supported filter
from the filter group specified. If the client wishes to enable more
than one filter, it must call this method multiple times to enable the
desired set of filters. This method call is synchronized by the
workloop's gate.
@param group The name of the filter group containing the filter to be
enabled.
@param aFilter The filter to enable.
@param enabledFilters All filters currently enabled by the client.
@param options Optional flags for the enable request.
@result Returns kIOReturnSuccess on success, or an error otherwise.
*/
virtual IOReturn enablePacketFilter(const OSSymbol * group,
UInt32 aFilter,
UInt32 enabledFilters,
IOOptionBits options = 0) = 0;
/*! @function disablePacketFilter
@abstract Disables a packet filter that is currently enabled from the
given filter group.
@discussion After a supported filter has been successfully enabled,
a client can call this method to disable that filter. This method call
is synchronized by the workloop's gate.
@param group The name of the filter group containing the filter to be
disabled.
@param aFilter The filter to disable.
@param enabledFilters All filters currently enabled by the client.
@param options Optional flags for the disable request.
@result Returns kIOReturnSuccess on success, or an error otherwise.
*/
virtual IOReturn disablePacketFilter(const OSSymbol * group,
UInt32 aFilter,
UInt32 enabledFilters,
IOOptionBits options = 0) = 0;
/*! @function getOutputQueue
@abstract Gets the IOOutputQueue object created by createOutputQueue().
@result Returns a reference to the output queue object created by
createOutputQueue().
*/
virtual IOOutputQueue * getOutputQueue() const;
/*! @function getPacketBufferConstraints
@abstract Gets the controller's packet buffer constraints.
@discussion Called by start() to obtain the constraints on the
memory buffer for each mbuf packet allocated through allocatePacket().
Drivers can override this method to specify the buffer constraints
imposed by their bus master hardware. Note that outbound packets,
those that originate from the network stack, are not currently
subject to the constraints reported here.
@param constraints A pointer to an IOPacketBufferConstraints
structure that this method is expected to initialize.
See IOPacketBufferConstraints structure definition.
*/
virtual void getPacketBufferConstraints(
IOPacketBufferConstraints * constraints) const;
/*! @function allocatePacket
@abstract Allocates a packet with a data buffer that is larger than
or equal to the size specified.
@discussion This method will always return a single mbuf unless the
size requested (plus the alignment padding) is greater than MCLBYTES.
The data buffer for the mbuf (or an mbuf chain) returned is aligned
according to the constraints reported by getPacketBufferConstraints().
The length fields in each mbuf returned are set by this method, thus
allowing the mbuf to be passed directly to an IOMbufMemoryCursor object
in order to convert the mbuf to a physical address scatter-gather list.
@param size The minimum size of the data buffer for the mbuf
packet allocated.
@result Returns an mbuf packet, or 0 if allocation failed.
*/
virtual mbuf_t allocatePacket(UInt32 size);
/*! @function copyPacket
@abstract Allocates a new packet, containing data copied from an
existing source packet.
@discussion The source packet is not modified by this method.
@param m The source packet.
@param size The number of bytes to copy. If set to 0, then the
entire data buffer from the source packet is copied.
@result Returns a new packet containing the same data as the source packet.
*/
virtual mbuf_t copyPacket(const mbuf_t m, UInt32 size = 0);
/*! @function replacePacket
@abstract Allocates a new packet to replace an existing packet, the
existing packet is then returned.
@param mp A handle to the existing packet.
@param size If size is 0, then the new packet shall have the same buffer
size as the original packet that is being replaced. Otherwise, the new
packet shall have the buffer size specified by this value.
@result If packet allocation was successful, then a replacement will
take place and the original packet will be returned. Otherwise, 0
is returned, and the original packet will be left untouched.
*/
virtual mbuf_t replacePacket(mbuf_t * mp, UInt32 size = 0);
/*! @function replaceOrCopyPacket
@abstract A helper method that combines the functionality of
copyPacket() and replacePacket() to process a packet containing
a received frame.
@discussion This method will either make a copy or replace the existing
packet, whichever is more time efficient. Packets containing small frames
are copied, otherwise they are replaced. If replaced, then the existing
packet is returned, and a new packet with the same buffer size is created
to take its place. If copied, the existing packet is left intact, while a
copy is returned that will hold a copy of the data from the source packet.
@param mp A handle to the existing packet that may be replaced.
@param length The number of bytes received held in the packet.
Must be greater than zero.
@param replaced Pointer to a return value that is set to true to indicate
that the existing packet was replaced, or false to indicate that the
existing packet was not replaced, and a copy was created.
@result Returns a replacement or a copy of the existing packet, or 0 if packet
allocation failed.
*/
virtual mbuf_t replaceOrCopyPacket(mbuf_t * mp,
UInt32 length,
bool * replaced);
enum {
kDelayFree = 0x01
};
/*! @function freePacket
@abstract Releases the packet given back to the free pool.
@param mbuf_t The packet to be freed.
@param options When kDelayFree option is set, then the packet
provided to this function will be queued on the free packet queue.
A subsequent call to releaseFreePackets() will release all queued
packets by making a single BSD function call. Without the kDelayFree
option, the packet provided will be released immediately.
*/
virtual void freePacket(mbuf_t, IOOptionBits options = 0);
/*! @function releaseFreePackets
@abstract Releases all packets held in the free packet queue.
@discussion The free packet queue is not protected by a lock. This
function must be called in a single-threaded manner with respect to
all calls to freePacket() with the kDelayFree option set.
@result Returns the number of packets queued and released.
*/
virtual UInt32 releaseFreePackets();
/*! @enum TCP/IP Checksums
@abstract TCP/IP checksums that may be supported by the
hardware.
@constant kChecksumFamilyTCPIP A value that describes the collection
of TCP/IP checksums.
@constant kChecksumIP An IP header checksum.
@constant kChecksumTCP A TCP checksum that covers the TCP header and TCP
data.
@constant kChecksumUDP A UDP checksum that covers the UDP header and UDP
data.
@constant kChecksumTCPIPv6 A TCP checksum that covers the IPv6 pseudo header,
TCP header and TCP data.
@constant kChecksumUDPIPv6 A UDP checksum that covers the IPv6 pseudo header,
UDP header and UDP data.
@constant kChecksumTCPNoPseudoHeader A TCP checksum that covers the TCP
header and the TCP data, but the pseudo header is not included in the
checksum computation. A partial 16-bit checksum value must be provided
to allow the protocol stacks to calculate and verify the final checksum.
This type of checksum is not currently supported on the output path.
@constant kChecksumUDPNoPseudoHeader A UDP checksum that covers the UDP
header and the UDP data, but the pseudo header is not included in the
checksum computation. A partial 16-bit checksum value must be provided
to allow the protocol stacks to calculate and verify the final checksum.
This type of checksum is not currently supported on the output path.
@constant kChecksumTCPSum16 The hardware has a simple checksum engine
that can perform a TCP style ones complement sum of 16-bit words over
a certain range of bytes in a packet. The hardware does not have the
ability to scan for IP or TCP headers, and the driver must pass/get
additional parameter(s) to or from the protocol stack to coordinate
the checksumming effort.
*/
enum {
kChecksumFamilyTCPIP = 0x00000001,
kChecksumIP = 0x0001,
kChecksumTCP = 0x0002,
kChecksumUDP = 0x0004,
kChecksumTCPIPv6 = 0x0020,
kChecksumUDPIPv6 = 0x0040,
kChecksumTCPNoPseudoHeader = 0x0100,
kChecksumUDPNoPseudoHeader = 0x0200,
kChecksumTCPSum16 = 0x1000
};
/*! @function getChecksumSupport
@abstract Gets checksums that are supported by the network controller for
the given checksum family.
@discussion A network controller that is capable of inserting and verifying
checksums on output and input packets, should override this method and
advertise its capability in order to assist or offload the software checksum
calculations performed by the protocol stacks.
@param checksumMask A pointer to the mask of supported checksums returned
by this method.
@param checksumFamily A value that specifies the checksum family.
@param isOutput Set to true to query the support for checksum insertion on
output packets, or false to query the support for checksum verification
on input packets. Controllers that have symmetric hardware checksum support
can return a fixed checksum mask value, and ignore this argument.
@result Default return is kIOReturnUnsupported. Controllers that override
this method must return kIOReturnSuccess. Any other return value will be
interpretated as a lack of checksum support, regardless of the value
returned through the first argument.
*/
virtual IOReturn getChecksumSupport( UInt32 * checksumMask,
UInt32 checksumFamily,
bool isOutput );
/*! @function setChecksumResult
@abstract Encodes a received packet with the checksum result reported
by the hardware.
@discussion A network controller that can verify the checksum(s) for a
received packet, should call this method to encode the result on the
packet, before passing it up towards the protocol stacks.
@param packet An mbuf containing a packet that has been checksummed by
the hardware.
@param checksumFamily A value that specifies the checksum family.
@param resultMask A mask of all checksums that were checked or computed.
Setting a bit implies that the driver is able to report the result of
the checksum computation, by asserting the validity of the checksum,
or by returning a partial checksum value.
@param validMask A mask of all checksums are were computed and verified
by the hardware as valid. Certain types of checksum performed by the
hardware are inheritely incomplete, and therefore should never be marked
as valid. A checksum cannot be marked valid unless it has also been
checked.
@param param0 Optional parameter 0, defaults to 0.
@param param1 Optional parameter 1, defaults to 0.
@result Returns true if the checksum family is valid and the packet has been
encoded with the checksum result provided, false otherwise.
*/
virtual bool setChecksumResult( mbuf_t packet,
UInt32 checksumFamily,
UInt32 resultMask,
UInt32 validMask,
UInt32 param0 = 0,
UInt32 param1 = 0 );
/*! @function getChecksumDemand
@abstract Fetches the demand for hardware checksum computation and insertion
for the given packet before it is transmitted on the network.
@discussion A network controller that can insert a checksum for output
packets must call this method to obtain the set of checksums that it must
compute, and insert into the appropriate fields in the given output packet.
@param packet An mbuf containing a packet that may be missing one or more