![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IONetworkController.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / XNU / iokit / IOKit / network|
Return to IONetworkController.h CVS log | Up to [Apple XNU] / XNU / iokit / IOKit / network |
1.1 root 1: /*
2: * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
3: *
4: * @APPLE_LICENSE_HEADER_START@
5: *
6: * The contents of this file constitute Original Code as defined in and
7: * are subject to the Apple Public Source License Version 1.1 (the
8: * "License"). You may not use this file except in compliance with the
9: * License. Please obtain a copy of the License at
10: * http://www.apple.com/publicsource and read it before using this file.
11: *
12: * This Original Code and all software distributed under the License are
13: * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
14: * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
15: * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
16: * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
17: * License for the specific language governing rights and limitations
18: * under the License.
19: *
20: * @APPLE_LICENSE_HEADER_END@
21: */
22: /*
23: * Copyright (c) 1999 Apple Computer, Inc. All rights reserved.
24: *
25: * IONetworkController.h
26: *
27: * Network controller driver superclass.
28: *
29: * HISTORY
30: * 9-Dec-1998 Joe Liu (jliu) created.
31: *
32: */
33:
34: #ifndef _IONETWORKCONTROLLER_H
35: #define _IONETWORKCONTROLLER_H
36:
37: #include <IOKit/IOService.h>
38: #include <IOKit/IOWorkLoop.h>
39: #include <IOKit/network/IONetworkInterface.h>
40: #include <IOKit/network/IOKernelDebugger.h>
41:
42: struct mbuf; // forward declarations
43: class IOCommandGate;
44: class IOOutputQueue;
45: class IONetworkMedium;
46:
47: // Keys for property table entries.
48: //
49: #define kIOVendor "IOVendor" // OSString
50: #define kIOModel "IOModel" // OSString
51: #define kIORevision "IORevision" // OSString
52: #define kIOInfo "IOInfo" // OSString
53: #define kIOControllerIndex "IOControllerIndex" // OSNumber:32
54: #define kIOFeatureSet "IOFeatureSet" // OSNumber:32
55: #define kIOFamilyFeatureSet "IOFamilyFeatureSet" // OSNumber:32
56: #define kIOMediumDictionary "IOMediumDictionary" // OSDictionary
57: #define kIODefaultMedium "IODefaultMedium" // OSString
58: #define kIOCurrentMedium "IOCurrentMedium" // OSSymbol
59: #define kIOActiveMedium "IOActiveMedium" // OSSymbol
60: #define kIOEnableDebugger "IOEnableDebugger" // OSString (Yes/No)
61: #define kIOLinkSpeed "IOLinkSpeed" // OSNumber:64
62: #define kIOLinkStatus "IOLinkStatus" // OSNumber:32
63: #define kIOLinkData "IOLinkData" // OSData
64: #define kIOPacketFilters "IOPacketFilters" // OSNumber:32
65: #define kIOActivePacketFilters "IOActivePacketFilters" // OSNumber:32
66:
67: /*! @typedef IOPacketBufferConstraints
68: @discussion Constraint parameters used by allocatePacket() to
69: align the memory buffer associated with a mbuf.
70: @field alignStart Alignment for the buffer's starting address.
71: @field alignLength Buffer length alignment.
72: @field maxLength Maximum buffer size (not implemented).
73: */
74:
75: typedef struct {
76: UInt32 alignStart;
77: UInt32 alignLength;
78: UInt32 maxLength;
79: } IOPacketBufferConstraints;
80:
81: // Some frequently used alignment constants.
82: //
83: enum {
84: kIOPacketBufferAlign1 = 1,
85: kIOPacketBufferAlign2 = 2,
86: kIOPacketBufferAlign4 = 4,
87: kIOPacketBufferAlign8 = 8,
88: kIOPacketBufferAlign16 = 16,
89: kIOPacketBufferAlign32 = 32,
90: };
91:
92: // Packet filters. Upper 16-bits are family specific.
93: //
94: enum {
95: kIOPacketFilterUnicast = 0x1,
96: kIOPacketFilterBroadcast = 0x2,
97: kIOPacketFilterMulticast = 0x10,
98: kIOPacketFilterMulticastAll = 0x20,
99: kIOPacketFilterPromiscuous = 0x100,
100: kIOPacketFilterPromiscuousAll = 0x200,
101: kIOPacketFilterFamilyMask = 0xffff0000,
102: };
103:
104: // Generic controller features.
105: //
106: enum {
107: kIONetworkFeatureNoBSDWait = 0x01, // start() should not wait for BSD.
108: };
109:
110:
111: /*! @class IONetworkController
112: @abstract IONetworkController implements the framework for a generic
113: network controller. A subclass of IONetworkController must provide
114: additional functionality specific for a particular network family.
115: In addition, the driver must implement (override) a basic set of
116: hardware dependent methods to create a working driver.
117:
118: IONetworkController attaches itself to the network layer via an
119: IONetworkInterface object. A controller object without a companion
120: interface is not known to the networking system. The controller
121: interacts with the network layer by calling methods defined by
122: the interface object. And conversely, the network layer issues
123: command and packets to the controller through its interface object.
124:
125: IONetworkController allocates an IOWorkLoop and an IOCommandGate object.
126: Most commands (requests) sent from the interface object are handled
127: by instructing the IOCommandGate instance to call one or more methods,
128: usually implemented by the driver, that may require hardware access.
129: Thus interface requests are always serialized. Outbound packets sent
130: from the interface to the controller have no implicit serialization.
131: Drivers must implement an output function that is thread safe, or use
132: an IOOutputQueue object which will provide a serialization model.
133: */
134:
135: class IONetworkController : public IOService
136: {
137: OSDeclareAbstractStructors(IONetworkController)
138:
139: public:
140:
141: /*! @typedef RequestAction
142: @discussion Prototype for an action to be called through syncRequest().
143: See syncRequest().
144: @param arg0 Action argument.
145: @param arg1 Action argument.
146: @param arg2 Action argument.
147: @param arg3 Action argument.
148: */
149:
150: typedef UInt32 (OSObject::*RequestAction)(void * arg0,
151: void * arg1,
152: void * arg2,
153: void * arg3);
154:
155: private:
156:
157: IOWorkLoop * _workLoop;
158: IOCommandGate * _cmdGate;
159: IOOutputQueue * _outputQueue;
160: OSSet * _clientSet;
161: OSObject * _reqClient;
162: UInt32 _alignStart;
163: UInt32 _alignLength;
164: UInt32 _alignPadding;
165: bool _handleReady;
166: bool _requestEnabled;
167: IOLock * _mediumLock;
168: IODebuggerLockState _debugLockState;
169: UInt32 _linkStatus;
170: UInt64 _linkSpeed;
171: OSData * _linkData;
172: const IONetworkMedium * _activeMedium;
173: const IONetworkMedium * _currentMedium;
174:
175: bool _controllerIsReady();
176: IOReturn _enable(IOService * client);
177: IOReturn _disable(IOService * client);
178: void commandHandler(void *, void *, void *, void *);
179: IOReturn selectMediumWithName(const OSSymbol * mediumName);
180:
181: bool setMediumProperty(const OSSymbol * key,
182: const IONetworkMedium * medium,
183: const IONetworkMedium ** cache,
184: bool force = false,
185: bool * changed = 0);
186:
187: bool setLink64Property(const char * key,
188: UInt64 value,
189: UInt64 * cache,
190: bool force = false,
191: bool * changed = 0);
192:
193: bool setLink32Property(const char * key,
194: UInt32 value,
195: UInt32 * cache,
196: bool force = false,
197: bool * changed = 0);
198:
199: bool verifyMediumDictionary(const OSDictionary * mediumDict);
200:
201: static void _logMbuf(struct mbuf * m);
202:
203: static void _enableSyncRequestFilter(IONetworkController *, bool);
204:
205: static void debugRxHandler(IOService * handler,
206: void * buffer,
207: UInt * length,
208: UInt timeout);
209:
210: static void debugTxHandler(IOService * handler,
211: void * buffer,
212: UInt length);
213:
214: public:
215:
216: /*! @function initialize
217: @abstract IONetworkController class initializer.
218: @discussion Create often used OSSymbol objects that are used as keys.
219: This method is called explicitly by a line in IOStartIOKit.cpp and not
220: by the OSDefineMetaClassAndInit() mechanism, since the OSSymbol class
221: is not guaranteed to be initialized first, and likewise for the
222: OSSymbol pool. */
223:
224: static void initialize();
225:
226: /*! @function init
227: @abstract Initialize the IONetworkController instance.
228: @discussion Instance variables are initialized to their default values,
229: then super::init() is called.
230: @param properties A dictionary object containing a property table.
231: @result true on success, false otherwise. */
232:
233: virtual bool init(OSDictionary * properties);
234:
235: /*! @function start
236: @abstract Start the controller driver.
237: @discussion Called when the controller was matched to a provider and
238: has been selected to start running. IONetworkController will allocate
239: resources and gather the controller's properties. No I/O will be
240: triggered until the subclass attaches a client object from its own
241: start method. Subclasses must override this method and call
242: super::start() at the beginning of its implementation. They should
243: also check the return value to make sure their superclass was
244: started successfully. The resources allocated by IONetworkController
245: include: An IOWorkLoop object, an IOCommandGate object to handle
246: synchronous requests, an OSSet to track our clients, and an optional
247: IOOutputQueue object for output queueing.
248:
249: Tasks that are usually performed by a driver's start method are;
250: resource allocation, hardware initialization, allocation of
251: IOEventSources and attaching them to an IOWorkLoop object,
252: publishing a medium dictionary, and finally, attaching an
253: interface object when the driver is ready to handle client
254: requests.
255: @param provider The provider that the controller was matched
256: (and attached) to.
257: @result true on success, false otherwise. */
258:
259: virtual bool start(IOService * provider);
260:
261: /*! @function stop
262: @abstract Stop the controller driver.
263: @discussion The opposite of start(). The controller has been
264: instructed to stop running. This method is called when the
265: driver has been terminated. The stop() method should release
266: resources and undo actions performed by start(). Subclasses
267: must override this method and call super::stop() at the end
268: of its implementation.
269: @param provider The provider that the controller was matched
270: (and attached) to. */
271:
272: void stop(IOService * provider);
273:
274: /*! @function outputPacket
275: @abstract Transmit a packet mbuf.
276: @discussion If an IOOutputQueue was allocated and returned by
277: createOutputQueue(), then this method will be called by the queue object.
278: Otherwise, an interface object will call this method directly upon
279: receiving an output packet from the network layer. When a queue object
280: is not present, this method must be safe from multiple client threads,
281: each pushing a packet to be sent on the wire.
282:
283: There is no upper limit on the number of mbufs, hence the number of
284: memory fragments, in the mbuf chain provided. Drivers must be able to
285: handle cases when the chain might exceed the limit supported by their
286: DMA engines, and perform coalescing to copy the various memory fragments
287: into a lesser number of fragments. This complexity can be hidden from
288: a driver when an IOMBufMemoryCursor is used, which is able to convert
289: a mbuf chain into a physical address scatter-gather list that will not
290: exceed a specified number of physically contiguous memory segments.
291: See IOMBufMemoryCursor.
292:
293: Packets may also be chained to form a packet chain. Although the
294: network layer, through the interface object, will currently only
295: send a single mbuf packet to the controller for each outputPacket()
296: call, it is possible for this to change. When a queue object is used,
297: the queue will automatically accept a single packet or a packet chain,
298: but it will call outputPacket() for each packet removed from the queue.
299:
300: The implementation in IONetworkController performs no useful action
301: and will drop all packets. A driver must always override this method.
302:
303: @param m The packet mbuf.
304: @result A return code defined by the caller. */
305:
306: virtual UInt32 outputPacket(struct mbuf * m);
307:
308: /*! @function getFeatureSet
309: @discussion Report features supported by the controller.
310: @result Returns 0. Drivers may override this method and return a mask
311: containing all supported feature bits. */
312:
313: virtual UInt32 getFeatureSet() const;
314:
315: /*! @function getFamilyFeatureSet
316: @discussion Report family specific features supported by the controller.
317: @result Drivers may override this method and return a mask containing
318: all supported family feature bits. */
319:
320: virtual UInt32 getFamilyFeatureSet() const = 0;
321:
322: /*! @function getVendorString
323: @result Return a vendor string. i.e. "Apple" */
324:
325: virtual const char * getVendorString() const = 0;
326:
327: /*! @function getModelString
328: @result Return a string describing the model of the network controller.
329: i.e. "BMac Ethernet" */
330:
331: virtual const char * getModelString() const = 0;
332:
333: /*! @function getRevisionString
334: @result Return a string describing the revision level of the
335: controller. */
336:
337: virtual const char * getRevisionString() const;
338:
339: /*! @function getInfoString
340: @result Return a string containing any additional information about
341: the controller and/or driver. */
342:
343: virtual const char * getInfoString() const;
344:
345: /*! @function getCurrentMedium
346: @abstract Get the currently selected medium.
347: @discussion Returns the currently selected medium object. If the driver
348: has yet to assign an entry in its medium dictionary as the current medium
349: using the setCurrentMedium() method, then the driver's property table is
350: consulted and a default medium property (can be set by the user), is
351: looked up and the corresponding entry in the medium dictionary is returned.
352: Therefore, drivers can always call getCurrentMedium() to either get
353: the current medium selected by the driver, or the default
354: medium chosen by the user.
355: @result The current medium entry from the medium dictionary, or 0
356: if a matching entry was not found. */
357:
358: virtual const IONetworkMedium * getCurrentMedium() const;
359:
360: /*! @function getMediumDictionary
361: @abstract Returns the medium dictionary published by the driver.
362: @discussion Returns the medium dictionary published by the driver
363: through publishMediumDictionary(). Use copyMediumDictionary() to
364: get a copy of the medium dictionary.
365: @result The published medium dictionary, or 0 if the driver has not
366: yet published a medium dictionary using publishMediumDictionary(). */
367:
368: virtual const OSDictionary * getMediumDictionary() const;
369:
370: /*! @function copyMediumDictionary
371: @abstract Returns a copy of the medium dictionary published by the driver.
372: @discussion The caller is responsible for releasing the dictionary
373: object returned. Use getMediumDictionary() to get a reference to the
374: published medium dictionary instead of creating a copy.
375: @result A copy of the medium dictionary, or 0 if the driver has not
376: published a medium dictionary using publishMediumDictionary(). */
377:
378: virtual OSDictionary * copyMediumDictionary() const;
379:
380: /*! @function syncRequest
381: @abstract Perform a request action synchronously.
382: @discussion Used both internally and also by clients to execute an
383: arbitrary request action using the IOCommandGate's runAction()
384: method. For client requests, where the client field is not equal to
385: 'this', the request is filtered by calling syncRequestFilter() to
386: qualify the client request. This filter function must return true
387: in order for the request to be accepted and the request action called.
388: @param client The client (caller) of the synchronous request.
389: @param target The target object that implements the request action.
390: @param action The action to perform.
391: @param ret The return value from the action is written to the
392: integer with the provided address. The result is
393: not written if the request was rejected by the request
394: filter.
395: @param arg0 Optional action argument.
396: @param arg1 Optional action argument.
397: @param arg2 Optional action argument.
398: @param arg3 Optional action argument.
399: @result kIOReturnNotReady if the client request was rejected by the filter.
400: Otherwise kIOReturnSuccess is returned. */
401:
402: virtual IOReturn syncRequest(OSObject * client,
403: OSObject * target,
404: RequestAction action,
405: UInt32 * ret = 0,
406: void * arg0 = 0,
407: void * arg1 = 0,
408: void * arg2 = 0,
409: void * arg3 = 0);
410:
411: /*! @function getOutputHandler
412: @abstract Get the address of the method designated to handle output
413: packets.
414: @result the address of the outputPacket() method. */
415:
416: virtual IOOutputAction getOutputHandler() const;
417:
418: /*! @function doEnablePacketFilters
419: @discussion Call enablePacketFilters() through syncRequest().
420: See enablePacketFilters(). */
421:
422: virtual IOReturn doEnablePacketFilters(IOService * client,
423: UInt32 filters,
424: UInt32 * activeFiltersP = 0);
425:
426: /*! @function doGetPacketFilters
427: @discussion Call getPacketFilters() through syncRequest().
428: See getPacketFilters(). */
429:
430: virtual IOReturn doGetPacketFilters(IOService * client, UInt32 * filtersP);
431:
432: /*! @function doEnable
433: @discussion Call enable(IOService *) through syncRequest().
434: See enable(). */
435:
436: virtual IOReturn doEnable(IOService * client);
437:
438: /*! @function doDisable
439: @discussion Call disable(IOService *) through syncRequest().
440: See disable(). */
441:
442: virtual IOReturn doDisable(IOService * client);
443:
444: /*! @function doGetControllerIndex
445: @discussion Call getControllerIndex(IOService *) through syncRequest().
446: See getControllerIndex(). */
447:
448: virtual IOReturn doGetControllerIndex(IOService * client,
449: UInt32 * index);
450:
451: /*! @function doSetMaxTransferUnit
452: @discussion Call setMaxTransferUnit() through syncRequest().
453: See setMaxTransferUnit(). */
454:
455: virtual IOReturn doSetMaxTransferUnit(IOService * client, UInt32 mtu);
456:
457: /*! @function doSelectMedium
458: @discussion Call selectMedium() through syncRequest().
459: See selectMedium(). */
460:
461: virtual IOReturn doSelectMedium(IOService * client,
462: const OSSymbol * mediumName);
463:
464: /*! @function doSetOutputQueueCapacity
465: @discussion Call setOutputQueueCapacity() through syncRequest().
466: See setOutputQueueCapacity(). */
467:
468: virtual IOReturn doSetOutputQueueCapacity(IOService * client,
469: UInt32 capacity);
470:
471: /*! @function doGetOutputQueueCapacity
472: @discussion Call getOutputQueueCapacity() through syncRequest().
473: See getOutputQueueCapacity(). */
474:
475: virtual IOReturn doGetOutputQueueCapacity(IOService * client,
476: UInt32 * capacityP);
477:
478: /*! @function doGetOutputQueueSize
479: @discussion Call getOutputQueueSize() through syncRequest().
480: See getOutputQueueSize(). */
481:
482: virtual IOReturn doGetOutputQueueSize(IOService * client,
483: UInt32 * sizeP);
484:
485: /*! @function doFlushOutputQueue
486: @discussion Call flushOutputQueue() through syncRequest().
487: See flushOutputQueue(). */
488:
489: virtual IOReturn doFlushOutputQueue(IOService * client,
490: UInt32 * flushCountP);
491:
492: /*! @function doPerformDiagnostics
493: @discussion Call performDiagnostics() through syncRequest().
494: See performDiagnostics(). */
495:
496: virtual IOReturn doPerformDiagnostics(IOService * client,
497: UInt32 * failureCode);
498:
499: protected:
500:
501: /*! @function free
502: @abstract Free the IONetworkController instance.
503: @discussion Free the IONetworkController instance and all allocated
504: resources, then call super::free(). */
505:
506: virtual void free();
507:
508: /*! @function setOutputQueueCapacity
509: @abstract Adjust the capacity of the output queue.
510: @discussion A client request to adjust the capacity of the driver's
511: output queue (number of packets the queue can hold). If a driver does
512: not override this method, then the default action is to forward the
513: request to an IOOutputQueue object if it was created. Otherwise return
514: kIOReturnUnsupported.
515: @param capacity The new capacity of the output queue.
516: @result kIOReturnSuccess on success, kIOReturnBadArgument if the
517: specified capacity is invalid, or kIOReturnUnsupported if the
518: function is not supported. */
519:
520: virtual IOReturn setOutputQueueCapacity(UInt32 capacity);
521:
522: /*! @function getOutputQueueCapacity
523: @abstract Get the capacity of the output queue.
524: @discussion A client request to get the capacity of the driver's
525: output queue. If a driver does not override this method, then the
526: default action is to forward the request to an IOOutputQueue object
527: if it was created. Otherwise return kIOReturnUnsupported.
528: @param capacityP Address of an integer where the capacity
529: shall be written to.
530: @result kIOReturnSuccess on success, or kIOReturnUnsupported if an
531: IOOutputQueue object was not created. */
532:
533: virtual IOReturn getOutputQueueCapacity(UInt32 * capacityP) const;
534:
535: /*! @function getOutputQueueSize
536: @abstract Get the number of packets in the output queue.
537: @discussion A client request to get the number of packets currently held
538: by the queue. If a driver does not override this method, then the default
539: action is to forward the request to an IOOutputQueue object if it was
540: created. Otherwise return kIOReturnUnsupported.
541: @param sizeP Address of an integer where the queue size shall be
542: written to.
543: @result kIOReturnSuccess on success, or kIOReturnUnsupported if an
544: IOOutputQueue object was not created. */
545:
546: virtual IOReturn getOutputQueueSize(UInt32 * sizeP) const;
547:
548: /*! @function flushOutputQueue
549: @abstract Discard all packets in the output queue.
550: @discussion A client request to flush all packets currently held by the
551: queue, and return the number of packets discarded. If a driver does not
552: override this method, then the default action is to forward the request
553: to an IOOutputQueue object if it was created. Otherwise return
554: kIOReturnUnsupported.
555: @param flushCountP Address of an integer where the number of
556: discarded packets shall be written to.
557: @result kIOReturnSuccess on success, or kIOReturnUnsupported if an
558: IOOutputQueue object was not created. */
559:
560: virtual IOReturn flushOutputQueue(UInt32 * flushCountP);
561:
562: /*! @function ready
563: @abstract An indication that the controller is ready to service
564: clients.
565: @discussion This method is called the first time that a controller
566: driver calls attachInterface() or attachDebuggerClient(), which is
567: an indication that the driver has been started and is ready to
568: service client requests. IONetworkController uses this method to
569: complete its initialization before any client objects are attached.
570: @param provider The controller's provider.
571: @result true on success, false otherwise. */
572:
573: virtual bool ready(IOService * provider);
574:
575: /*! @function enable
576: @abstract An enable request from an interface client.
577: @discussion Called by an interface client to enable the controller.
578: This method must bring up the hardware and enable event sources
579: to prepare for packet transmission and reception. A driver should
580: delay the allocation of most runtime resources until this method is
581: called to conserve shared system resources.
582: @param interface The interface client object that requested the enable.
583: @result kIOReturnUnsupported. Driver may override this method and
584: return kIOReturnSuccess on success, or an error code otherwise. */
585:
586: virtual IOReturn enable(IONetworkInterface * interface);
587:
588: /*! @function disable
589: @abstract A disable request from an interface client.
590: @discussion Called by an interface object to disable the controller.
591: This method should quiesce the hardware and disable event sources.
592: Any resources allocated in enable() should also be deallocated.
593: @param interface The interface object that requested the disable.
594: @result kIOReturnUnsupported. Driver may override this method and
595: return kIOReturnSuccess on success, or an error code otherwise. */
596:
597: virtual IOReturn disable(IONetworkInterface * interface);
598:
599: /*! @function enable
600: @abstract An enable request from a client.
601: @discussion Handle an enable request from a client. The client
602: object is typecasted using OSDynamicCast, and if the client is an
603: IOKernelDebugger or an IONetworkInterface, then an overloaded enable
604: method that takes a more specific argument is called. If the client
605: matches neither type, a kIOReturnBadArgument is returned.
606: A driver has the option of override this generic enable method,
607: or the derived version.
608: @param client The client object requesting the enable.
609: @result The return value from the derived enable method, or
610: kIOReturnBadArgument if the client's type is unknown. */
611:
612: virtual IOReturn enable(IOService * client);
613:
614: /*! @function disable
615: @abstract A disable request from a client.
616: @discussion Handle an enable request from a client. The client
617: object is typecasted using OSDynamicCast, and if the client is an
618: IOKernelDebugger or an IONetworkInterface, then an overloaded disable
619: method that takes a more specific argument is called. If the client
620: matches neither type, a kIOReturnBadArgument is returned.
621: A driver has the option of override this generic enable method,
622: or the derived version.
623: @param client The client object requesting the disable.
624: @result The return from the derived disable method, or
625: kIOReturnBadArgument if the client's type is unknown. */
626:
627: virtual IOReturn disable(IOService * client);
628:
629: /*! @function getControllerIndex
630: @abstract Return an ordinal number for multiport adapters.
631: @discussion Return an ordinal number for multiport network adapters.
632: The implementation in IONetworkController will work for PCI controllers
633: behind a PCI-PCI bridge. This method exists solely to support the
634: current interface naming scheme, and is likely to
635: undergo changes or may disappear in the future.
636: @param indexP The oridinal number should be written to the
637: integer at this address.
638: @result kIOReturnSuccess. */
639:
640: virtual IOReturn getControllerIndex(UInt32 * indexP) const;
641:
642: /*! @function setMaxTransferUnit
643: @abstract Change the controller's MTU size.
644: @discussion A client request for the controller to change to
645: a new MTU size.
646: @param mtu The new MTU size requested.
647: @result kIOReturnUnsupported. Drivers may override this method
648: and return either kIOReturnSuccess to indicate that the new MTU size
649: was accepted and is in effect, or an error to indicate failure. */
650:
651: virtual IOReturn setMaxTransferUnit(UInt32 mtu);
652:
653: /*! @function performDiagnostics
654: @abstract A request for the driver to perform hardware diagnostics.
655: @discussion A client request for the driver to perform hardware
656: diagnostics and return the test result after completion.
657: @param resultCodeP In addition to the return code, drivers may
658: write a hardware specific result code to the integer at this
659: address.
660:
661: @result kIOReturnSuccess if hardware passed all test, otherwise
662: an appropriate error code should be returned. The default return
663: is always kIOReturnUnsupported. */
664:
665: virtual IOReturn performDiagnostics(UInt32 * resultCodeP);
666:
667: /*! @function publishCapabilities
668: @abstract Publish controller's properties and capabilities.
669: @discussion Discover and publish controller capabilities to the
670: property table. This method is called by ready().
671: @result true if all capabilities were discovered and published
672: successfully, false otherwise. Returning false will prevent client
673: objects from attaching to the controller since a property that
674: a client depends on may be missing. */
675:
676: virtual bool publishCapabilities();
677:
678: /*! @function publishMediumDictionary
679: @abstract Publish a medium dictionary.
680: @discussion Called by drivers to publish their medium dictionary.
681: The dictionary consist of IONetworkMedium entries that represent
682: the entire media selection supported by the hardware. This method
683: will make a copy of the provided dictionary, then add the copy to
684: the driver's property table. The dictionary provided can be
685: released after this call returns. It is permissible to call
686: this method multiple times, which may be necessary if the hardware's
687: media capability changes dynamically. However, if this were not
688: so, then drivers will typically call this method from its start()
689: implementation, after the hardware capability is discovered.
690:
691: Several methods depends on the presence of a medium dictionary.
692: They should be called after the dictionary has been published.
693: Those are:
694: selectMedium()
695: setCurrentMedium()
696: getCurrentMedium()
697: getMediumDictionary()
698: copyMediumDictionary()
699:
700: Calling publishMediumDictionary() will cause a media change event
701: to be delivered to all attached interface clients.
702: @param mediumDict A dictionary containing IONetworkMedium objects.
703: @result true if the dictionary is valid, and was successfully
704: added to the property table, false otherwise. */
705:
706: virtual bool publishMediumDictionary(const OSDictionary * mediumDict);
707:
708: /*! @function setCurrentMedium
709: @abstract Designate an entry in the published medium dictionary as
710: the currently selected medium.
711: @discussion From the set of medium objects in the medium dictionary
712: published by the driver, one of them can be designated as the
713: currently selected medium. Drivers should call this method whenever
714: their media selection changes. An entry in the driver's property
715: table is updated to advertise the current medium.
716:
717: A media change event will be broadcasted to all attached interface
718: clients when the current medium property changes.
719:
720: @param medium A medium object to promote as the current medium.
721: @result true if the medium dictionary exists, the medium object
722: provided matches an entry in this dictionary, and the property
723: table update was successful, false otherwise. */
724:
725: virtual bool setCurrentMedium(const IONetworkMedium * medium);
726:
727: /*! @function selectMedium
728: @abstract Change the controller's medium selection.
729: @discussion A client request for the controller to change the
730: selected medium. Drivers may override this method and provide
731: an implementation appropriate for its hardware, then call
732: setCurrentMedium() to update the current medium property if
733: a change occurred.
734: @param medium An entry in the published medium dictionary.
735: @result kIOReturnUnsupported. Drivers may override this method and
736: return kIOReturnSuccess if the selected medium was activated,
737: or an error code otherwise. */
738:
739: virtual IOReturn selectMedium(const IONetworkMedium * medium);
740:
741: /*! @function setLinkStatus
742: @abstract Report the link status and the active medium.
743: @discussion Update the link status parameters published by the
744: controller. Drivers should call this method whenever the link
745: status changes. Never call this method from interrupt context
746: since this method may block. An event will be sent to all
747: attached interface objects when a change is detected.
748: @param status Link status bits.
749: See IONetworkMedium.h for defined link status bits.
750: @param speed Link speed in units of bits per second.
751: @param activeMedium A medium entry in the published medium dictionary
752: where the link was established. This may not be the same as the
753: current medium. See setCurrentMedium().
754: @param data An OSData containing any additional link information.
755: @result true if all link properties were successfully updated,
756: false otherwise. */
757:
758: virtual bool setLinkStatus(UInt32 status,
759: UInt64 speed,
760: const IONetworkMedium * activeMedium,
761: OSData * data = 0);
762:
763: /*! @function syncRequestFilter
764: @abstract Filter client requests sent to syncRequest().
765: @discussion This method is called to qualify all client requests
766: sent to syncRequest(). This implementation will either allow or
767: refuse all requests, and this behavior is set by calling the
768: enableSyncRequest() or disableSyncRequest() methods. By default,
769: all requests are allowed.
770: @param client The client of the synchronous request.
771: @param target The target object that implements the request action.
772: @param action The action to perform.
773: @param arg0 Action argument.
774: @param arg1 Action argument.
775: @param arg2 Action argument.
776: @param arg3 Action argument.
777: @result true to accept the request and allow the request action to be
778: called, or false to refuse it. */
779:
780: virtual bool syncRequestFilter(OSObject * client,
781: OSObject * target,
782: RequestAction action,
783: void * arg0,
784: void * arg1,
785: void * arg2,
786: void * arg3);
787:
788: /*! @function enableSyncRequest
789: @abstract Set syncRequestFilter() to accept all client requests.
790: @discussion Enable all client requests sent to the syncRequest() method.
791: Don't use this method if the driver overrides syncRequestFilter(). */
792:
793: virtual void enableSyncRequest();
794:
795: /*! @function disableSyncRequest
796: @abstract Set syncRequestFilter() to refuse all client requests.
797: @discussion Disable all client requests sent to the syncRequest() method.
798: Don't use this method if the driver overrides syncRequestFilter(). */
799:
800: virtual void disableSyncRequest();
801:
802: /*! @function getSyncRequestClient
803: @abstract Get request client.
804: @discussion Methods that are called by syncRequest() can call this
805: to get the client object which initiated the request.
806: @result The request client. If the caller's context does not indicate
807: that it is running through syncRequest(), then 0 is returned. */
808:
809: virtual OSObject * getSyncRequestClient() const;
810:
811: /*! @function handleOpen
812: @abstract Handle a client open.
813: @discussion Handle a client open on the controller object. IOService
814: calls this method with the arbitration lock held. Subclasses
815: should not override this method.
816: @param client The client that is trying to open the controller.
817: @param options Not used. See IOService.
818: @param argument Not used. See IOService.
819: @result true to accept the client open, false to refuse the open. */
820:
821: virtual bool handleOpen(IOService * client,
822: IOOptionBits options,
823: void * argument);
824:
825: /*! @function handleClose
826: @abstract Handle a client close.
827: @discussion Handle a close from one of our client objects. IOService
828: calls this method with the arbitration lock held. Subclasses
829: should not override this method.
830: @param client The client that has closed the controller.
831: @param options Not used. See IOService. */
832:
833: virtual void handleClose(IOService * client, IOOptionBits options);
834:
835: /*! @function handleIsOpen
836: @abstract Query a client that has an open on the controller.
837: @discussion This method is always called by IOService with the
838: arbitration lock held. Subclasses should not override this method.
839: @result true if the specified client, or any client if none is
840: specified, presently has an open on this object. */
841:
842: virtual bool handleIsOpen(const IOService * client) const;
843:
844: /*! @function attachInterface
845: @abstract Attach a new interface client object.
846: @discussion Create a new interface client object and attach it
847: to the controller. The createInterface() method is called to
848: perform the allocation and initialization, followed by a call to
849: configureInterface() to configure the interface. Both of these
850: methods can be overridden by subclasses to customize the
851: interface client attached. Drivers must call attachInterface()
852: from its start() method, after it is ready to service client requests.
853: @param interfaceP If successful (return value is true), then the
854: interface object will be written to the handle provided.
855: @param doRegister If true, then registerService() is called to register
856: the interface, which will trigger the matching process, and cause the
857: interface to become registered with the network layer. For drivers that
858: wish to delay the registration, and hold off servicing requests and data
859: packets from the network layer, set doRegister to false and call
860: registerService() on the interface client when the controller becomes
861: ready.
862: @result true on success, false otherwise. */
863:
864: virtual bool attachInterface(IONetworkInterface ** interface,
865: bool doRegister = true);
866:
867: virtual bool attachNetworkInterface(IONetworkInterface ** interface,
868: bool doRegister = true); // obsolete
869:
870: /*! @function detachInterface
871: @abstract Detach an interface client object.
872: @discussion This method will check that the object provided is indeed
873: an IONetworkInterface, and if so its terminate() method is called.
874: The interface object will close and detach from its controller only
875: after the network layer has removed all references to the data
876: structures exposed by the interface.
877: @param interface An interface object to be detached.
878: @param sync If true, the interface is terminated synchronously.
879: Note that this may cause detachInterface() to block
880: for an indefinite period of time. */
881:
882: virtual void detachInterface(IONetworkInterface * interface,
883: bool sync = false);
884:
885: /*! @function getPacketBufferConstraints
886: @abstract Get controller's packet buffer constraints.
887: @discussion Called by start() to obtain the constraints on the
888: memory buffer associated with each mbuf allocated through
889: allocatePacket(). Drivers can override this method to specify
890: their buffer constraints imposed by their bus master hardware.
891: Note that outbound packets, those that originate from the
892: network stack, are not subject to the constraints reported here.
893: @param constraintsP A pointer to an IOPacketBufferConstraints
894: structure that that this method is expected to initialize.
895: See IOPacketBufferConstraints structure definition.
896: */
897:
898: virtual void getPacketBufferConstraints(
899: IOPacketBufferConstraints * constraintsP) const;
900:
901: /*! @function allocatePacket
902: @discussion Allocate a mbuf packet with the given size. This method
903: will always return a single mbuf unless the size requested (plus the
904: alignment padding) is greater than MCLBYTES. The mbuf (or a mbuf
905: chain) returned is aligned according to the constraints reported
906: by getPacketBufferConstraints().
907:
908: The m_len and pkthdr.len fields in the mbuf is updated by this
909: method, thus allowing the packet to be passed directly to an
910: IOMbufMemoryCursor object in order to convert the mbuf to a
911: scatter-gather list.
912:
913: @param size The desired size of the mbuf packet.
914: @result The allocated mbuf packet, or 0 if allocation failed. */
915:
916: virtual struct mbuf * allocatePacket(UInt size);
917:
918: /*! @function copyPacket
919: @discussion Make a copy of a mbuf, and return the copy.
920: The source mbuf is not modified.
921: @param m The source mbuf.
922: @param size The number of bytes to copy. If set to 0, then the entire
923: source mbuf is copied (source length is taken from the m_pkthdr.len).
924: @result A new mbuf created from the source packet. */
925:
926: virtual struct mbuf * copyPacket(const struct mbuf * m, UInt size = 0);
927:
928: /*! @function replacePacket
929: @discussion Replace the mbuf pointed by the given pointer with
930: another mbuf. Drivers can call this method to replace a mbuf before
931: passing the original mbuf, which contains a received frame, to the
932: network layer.
933: @param mp A pointer to the original mbuf that shall be updated by this
934: method to point to the new mbuf.
935: @param size If size is 0, then the new mbuf shall have the same size
936: as the original mbuf that is being replaced. Otherwise, the new
937: mbuf shall have the size specified here.
938: @result If mbuf allocation was successful, then the replacement will
939: take place and the original mbuf will be returned. Otherwise, a NULL
940: is returned. */
941:
942: virtual struct mbuf * replacePacket(struct mbuf ** mp, UInt size = 0);
943:
944: /*! @function replaceOrCopyPacket
945: @discussion Either replace or copy the source mbuf given depending
946: on the amount of data in the source mbuf. This method will either
947: perform a copy or replace the source mbuf, whichever is more
948: time efficient. If replaced, then the original mbuf is returned, and
949: a new mbuf is allocated to take its place. If copied, the source mbuf is
950: left intact, while a copy is returned that is just big enough to hold
951: all the data from the source mbuf.
952: @param mp A pointer to the source mbuf that may be updated by this
953: method to point to the new mbuf if replaced.
954: @param rcvlen The number of data bytes in the source mbuf.
955: @param replacedP Pointer to a bool that is set to true if the
956: source mbuf was replaced, or set to false if the
957: source mbuf was copied.
958: @result A replacement or a copy of the source mbuf, 0 if mbuf
959: allocation failed. */
960:
961: virtual struct mbuf * replaceOrCopyPacket(struct mbuf ** mp,
962: UInt rcvlen,
963: bool * replacedP);
964:
965: /*! @function freePacket
966: @discussion Release the mbuf back to the free pool.
967: @param m The mbuf to be freed. */
968:
969: virtual void freePacket(struct mbuf * m);
970:
971: /*! @function createInterface
972: @abstract Create an interface client object.
973: @discussion Create a new IONetworkInterface instance.
974: This method is called by attachInterface() to perform the
975: allocation and initialization of a new interface client object.
976: A family specific subclass of IONetworkController must implement
977: this method and return a matching interface instance. For example,
978: IOEthernetController implements this method and returns an
979: IOEthernetInterface instance.
980: @result The allocated interface object. */
981:
982: virtual IONetworkInterface * createInterface() = 0;
983:
984: /*! @function configureInterface
985: @abstract Configure an interface client object.
986: @discussion Configure an interface object created through
987: createInterface(). IONetworkController will register
988: its output handler with the interface object provided.
989: Subclasses may override this method to customize the interface object.
990: Once the interface is registered and opened by a client, it will
991: refuse changes to its properties. And since this method is called
992: before the interface has become registered, this is a final
993: opportunity for the controller to configure the interface.
994: @param interface The interface object to be configured.
995: @result true if configuration was successful, false otherwise
996: (this will cause attachInterface() to fail). */
997:
998: virtual bool configureInterface(IONetworkInterface * interface);
999:
1000: // obsolete
1001: virtual bool configureNetworkInterface(IONetworkInterface * interface);
1002:
1003: /*! @function createOutputQueue
1004: @abstract Create an IOOutputQueue to handle output queueing.
1005: @discussion Called by start() to create an IOOutputQueue instance
1006: to handle output queueing. The default implementation will always
1007: return 0, hence no output queue will be created. A driver may override
1008: this method and return a subclass of IOOutputQueue. IONetworkController
1009: will keep a reference to the queue created, and will release the
1010: object when IONetworkController is freed. Also see getOutputQueue().
1011: @result A newly allocated and initialized IOOutputQueue instance. */
1012:
1013: virtual IOOutputQueue * createOutputQueue();
1014: virtual IOOutputQueue * allocateOutputQueue(); // obsolete
1015:
1016: /*! @function getOutputQueue
1017: @abstract Get the IOOutputQueue object created by createOutputQueue().
1018: @result Return the output queue created by createOutputQueue(). */
1019:
1020: virtual IOOutputQueue * getOutputQueue() const;
1021:
1022: /*! @function getWorkLoop
1023: @abstract Get the IOWorkLoop object created by IONetworkController.
1024: @discussion An IOWorkLoop object is created by the start() method.
1025: Drivers can call getWorkLoop() to obtain a reference to the
1026: IOWorkLoop object, and attach their event sources, such
1027: as IOTimerEventSource or IOInterruptEventSource.
1028: See IOWorkLoop.
1029: @result The IOWorkLoop object created by IONetworkController. */
1030:
1031: virtual IOWorkLoop * getWorkLoop() const;
1032:
1033: /*! @function getCommandGate
1034: @abstract Get the IOCommandGate object created by IONetworkController.
1035: @discussion An IOCommandGate is created and attached to an
1036: IOWorkLoop by the start() method. This IOCommandGate object is used
1037: to handle client requests issued through the syncRequest() method.
1038: Subclasses that need an IOCommandGate should try to use the object
1039: returned by this method, rather than creating a new instance.
1040: See IOCommandGate.
1041: @result The IOCommandGate object created by IONetworkController. */
1042:
1043: virtual IOCommandGate * getCommandGate() const;
1044:
1045: /*! @function broadcastEvent
1046: @abstract Send an event to all interface client objects.
1047: @discussion Broadcast an event to all attached interface objects.
1048: This is equivalent to calling the IONetworkInterface::inputEvent()
1049: method for all interfaces.
1050:
1051: IONetworkController uses this method to broadcast link and media
1052: events. Drivers will usually call the inputEvent() method directly
1053: since it is more efficient, and most drivers will only attach a
1054: single interface client.
1055:
1056: @param type Event type.
1057: @param arg Event argument.
1058: @result true if the event was delivered, false if an error occurred
1059: (unable to perform object allocation) and the event was not delivered. */
1060:
1061: virtual bool broadcastEvent(UInt32 type, void * arg = 0);
1062:
1063: /*! @function getPacketFilters
1064: @abstract Get the set of packet filters supported by the controller.
1065: @discussion A subclass must implement this method and report its
1066: supported filter set. See IOPacketFilter enum for the list of defined
1067: packet filters.
1068: @param filtersP A mask of supported filters should be written to the
1069: integer with this address.
1070: @result kIOReturnSuccess on success, or an error to indicate
1071: failure to discover the hardware supported filters. */
1072:
1073: virtual IOReturn getPacketFilters(UInt32 * filtersP) = 0;
1074:
1075: /*! @function enablePacketFilters
1076: @abstract Enable a set of packet filters supported by the controller.
1077: @discussion After calling getPacketFilters() to gather the set of
1078: supported packet filters, a client may issue a request to enable a
1079: (sub)set of filters from the supported set.
1080: @param filters Each bit that is set indicates a particular filter that
1081: should be enabled. Filter bits that cleared should be disabled.
1082: @param activeFiltersP Must be updated by this method to contain the filter
1083: set that was activated. Ideally, it should be the same as the filter
1084: set specified by the first argument.
1085: @result kIOReturnSuccess on success, otherwise an error code is
1086: returned. If (*activeFiltersP != filters), then an error is expected. */
1087:
1088: virtual IOReturn enablePacketFilters(UInt32 filters,
1089: UInt32 * activeFiltersP) = 0;
1090:
1091: /*! @function attachDebuggerClient
1092: @abstract Attach a new IOKernelDebugger client object. Attaching
1093: a debugger client implies that the driver supports the kernel
1094: debugging interface, and must implement the two polled-mode entry
1095: points. See sendPacket() and receivePacket().
1096: @discussion Allocate and attach a new IOKernelDebugger client object.
1097: @param debuggerP An IOKernelDebugger handle that is updated by this
1098: method to contain the allocated IOKernelDebugger instance.
1099: @result true on success, false otherwise. */
1100:
1101: virtual bool attachDebuggerClient(IOKernelDebugger ** debuggerP);
1102:
1103: /*! @function detachDebuggerClient
1104: @abstract Detach an IOKernelDebugger client object.
1105: @discussion Detach and terminate the IOKernelDebugger client object
1106: provided. A synchronous termination is issued, and this method returns
1107: after the client has been terminated.
1108: @param debugger The IOKernelDebugger instance to be detached and
1109: terminated. If the argument provided is NULL or is not an
1110: IOKernelDebugger, this method will return immediately. */
1111:
1112: virtual void detachDebuggerClient(IOKernelDebugger * debugger);
1113:
1114: /*! @function enable
1115: @abstract An enable request from an IOKernelDebugger client.
1116: @discussion This method is called when an open is received from an
1117: IOKernelDebugger client. Drivers that wish to provide debugging
1118: services must override this method and setup the hardware to
1119: support the polled-mode send and receive methods; receivePacket()
1120: and sendPacket(). Debug capable drivers may also override the
1121: more generic enable/disable calls that take an IOService argument.
1122: @param debugger The IOKernelDebugger client that issued the open.
1123: @result kIOReturnSuccess. The driver method must return kIOReturnSuccess
1124: to allow the debugger open, anything else will cause the debugger open
1125: to fail and the attachDebuggerClient() method will return false. */
1126:
1127: virtual IOReturn enable(IOKernelDebugger * debugger);
1128: virtual IOReturn handleDebuggerOpen(IOKernelDebugger * debugger);
1129:
1130: /*! @function disable
1131: @abstract A disable request from an IOKernelDebugger client.
1132: @discussion This method is called when a close is received from an
1133: IOKernelDebugger client. A driver which implements
1134: enable(IOKernelDebugger *) should also implement this method to
1135: disable hardware support for the polled-mode send and receive methods.
1136: @param debugger The IOKernelDebugger client that issued the close.
1137: @result kIOReturnSuccess. The driver method should return a status
1138: from the disable operation. */
1139:
1140: virtual IOReturn disable(IOKernelDebugger * debugger);
1141: virtual IOReturn handleDebuggerClose(IOKernelDebugger * debugger);
1142:
1143: /*! @function reserveDebuggerLock
1144: @abstract Take the global debugger lock.
1145: @discussion This method should not be used. Call the
1146: lock() method provided by IOKernelDebugger instead. */
1147:
1148: void reserveDebuggerLock();
1149:
1150: /*! @function releaseDebuggerLock
1151: @abstract Release the global debugger lock.
1152: @discussion This method should not be used. Call the
1153: unlock() method provided by IOKernelDebugger instead. */
1154:
1155: void releaseDebuggerLock();
1156:
1157: /*! @function receivePacket
1158: @abstract Debugger polled-mode receive handler.
1159: @discussion This method must be implemented by a driver that supports
1160: kernel debugging. After a debugger client is attached through
1161: attachDebuggerClient(), this method will be called by the debugger
1162: object to poll for a incoming packet when the debugger is active.
1163: This method can be called from an interrupt context, and the
1164: driver must never block or perform any memory allocation. The
1165: receivePacket() method in IONetworkController is used as a placeholder
1166: and should never be called. A driver that attaches a debugger client
1167: must override this method.
1168: @param pkt Pointer to a receive buffer where the received packet should
1169: be stored to. The buffer has room for 1518 bytes.
1170: @param pkt_len The length of the received packet must be written to the
1171: integer pointed by pkt_len.
1172: @param timeout The maximum amount of time in milliseconds to poll for
1173: a packet to arrive before this method must return. */
1174:
1175: virtual void receivePacket(void * pkt, UInt * pkt_len, UInt timeout);
1176:
1177: /*! @function sendPacket
1178: @abstract Debugger polled-mode transmit handler.
1179: @discussion This method must be implemented by a driver that supports
1180: kernel debugging. After a debugger client is attached through
1181: attachDebuggerClient(), this method will be called by the debugger
1182: object to send an outbound packet generated by the debugger.
1183: This method can be called from an interrupt context, and the
1184: driver must never block or perform any memory allocation. The
1185: sendPacket() method in IONetworkController is used as a placeholder
1186: and should never be called. A driver that attaches a debugger client
1187: must override this method.
1188: @param pkt Pointer to a transmit buffer containing the packet to be sent.
1189: @param pkt_len The amount of data in the transmit buffer. */
1190:
1191: virtual void sendPacket(void * pkt, UInt pkt_len);
1192: };
1193:
1194: #define IONetworkAction IONetworkController::RequestAction
1195:
1196: inline bool
1197: IONetworkController::attachNetworkInterface(IONetworkInterface ** interface,
1198: bool doRegister = true)
1199: {
1200: return attachInterface(interface, doRegister);
1201: }
1202:
1203: #endif /* !_IONETWORKCONTROLLER_H */
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.