protected:
virtual IONetworkInterface * allocateNetworkInterface() = 0;
Allocate and return a new IONetworkInterface. This method is called by attachNetworkInterface() to perform the allocation of a new interface client object. A family specific subclass of IONetworkController must implement this method and return a matching interface instance. For example, IOEthernetController implements this method and returns an IOEthernetInterface when called.
Result: The allocated interface object.protected:
virtual IOOutputQueue * allocateOutputQueue();
Called by start() to allocate an IOOutputQueue instance. The default implementation will always return 0, hence no output queue will be created. A driver may override this method and return a subclass of IOOutputQueue. IONetworkController will keep a reference to the queue created, and will also release the object when IONetworkController is freed. Also see getOutputQueue().
Result: A newly allocated and initialized IOOutputQueue instance.protected:
virtual struct mbuf * allocatePacket(UInt size);
Allocate a mbuf packet with the given size. This method
will always return a single mbuf unless the size requested (plus the
alignment padding) is greater than MCLBYTES. The mbuf (or a mbuf
chain) returned is aligned according to the constraints obtained
through getPacketBufferConstraints().
The m_len and pkthdr.len fields in the mbuf is updated by this
function, thus allowing the packet to be directly passed to an
IOMbufMemoryCursor object.
Result: The allocated mbuf packet, or 0 if allocation failed.
Name Description size The size of the mbuf packet.
protected:
virtual bool attachNetworkInterface(IONetworkInterface ** interface, bool doRegister = true);
Allocate a new interface object and attach it to the controller as a client. The allocateNetworkInterface() method is called to allocate the new interface instance, followed by a call to configureNetworkInterface() to configure the interface. Both of these methods can be overridden by subclasses to change the type of interface client attached. Drivers must call this from its start() method, after it is ready to service requests from its soon to be attached interface client.
Result: true on success, false otherwise.
Name Description interface If successful (return value is true), then the interface object will be written to the handle provided by the caller. doRegister If the doRegister argument is true, then the interface's registerService() is called to register the object, which will trigger the matching process, and cause client object to attach to the interface. For drivers that wish to delay the registration, and hold off the interface clients, set doRegister to false and call registerService() when both the controller and interface object are ready to handle client requests.
protected:
virtual bool broadcastEvent(UInt32 type, void * arg = 0);
Broadcast an event to all attached interface objects.
This is equivalent to calling the IONetworkInterface::inputEvent()
method for all interfaces. This method may block.
IONetworkController uses this method to broadcast link and media
events. Drivers will usually call the inputEvent() method directly
since it is more efficient, and most drivers will only attach a
single interface.
Result: true if the event was delivered, false if an error occurred (unable to allocate memory to create objects) and the event was not delivered.
Name Description type Event type. See IONetworkInterface. arg Event argument. See IONetworkInterface.
protected:
virtual bool configureNetworkInterface(IONetworkInterface * netif);
Configure a network interface allocated through allocateNetworkInterface(). IONetworkController will register the output handler with the interface object provided. Subclasses may override this method to customize the interface object. Once the interface is registered and opened by a client, it will refuse changes to its properties. But since this method is called before the interface has been registered, this is an opportunity for the controller to configure the interface.
Result: true if configuration was successful, false otherwise.
Name Description netif The interface object to be configured.
protected:
virtual struct mbuf * copyPacket(const struct mbuf * m, UInt size = 0);
Make a copy of a mbuf, and return the copy. The source mbuf is not modified.
Result: A new mbuf created from the source packet.
Name Description m The source mbuf. size The number of bytes to copy. If set to 0, then the entire source mbuf is copied.
protected:
virtual void detachNetworkInterface(IONetworkInterface * interface);
Detach the interface object asynchronously. This method will check that the object provided is indeed an IONetworkInterface, and if so its terminate() method is called. The interface object will close and detach from its controller only after the network layer has removed all references to the registered interface.
Name Description interface An interface object to be detached.
protected:
virtual IOReturn disable(IOService * client);
Handle a disable request from a client. The client is typecasted using OSDynamicCast(), and depending on the type, an disable(IONetworkInterface *) is called for an interface client, a handleDebuggerClose(IOKernelDebugger *) is called for a debugger client, or an kIOReturnBadArgument is returned for any other type.
Result: The return from the dispatched methods, or kIOReturnBadArgument if the client's type is unknown.
Name Description client The client object that requested the disable.
protected:
virtual IOReturn disable(IONetworkInterface * netif);
Called by the interface object to disable the controller. Drivers must override this method and shutdown the hardware and disable interrupt sources. Any resources allocated in enable() should also be deallocated.
Result: kIOReturnUnsupported. Driver may override this method and return kIOReturnSuccess upon success, or an error code otherwise.
Name Description netif The interface object that requested the disable.
protected:
virtual bool disableSyncRequest();
Prevent syncRequest() from handling synchronous requests.
Result: The previous state.protected:
virtual IOReturn enable(IONetworkInterface * netif);
Called by the interface object to enable the controller. Drivers must override this method and prepare the hardware and interrupt sources to allow packet transmission and reception. The driver should delay the allocation of most runtime resources until this method is called to conserve system resources.
Result: kIOReturnUnsupported. Driver may override this method and return kIOReturnSuccess upon success, or an error code otherwise.
Name Description netif The interface object that requested the enable.
protected:
virtual IOReturn enable(IOService * client);
Handle an enable request from a client. The client is typecasted using OSDynamicCast(), and depending on the type, an enable(IONetworkInterface *) is called for an interface client, a handleDebuggerOpen(IOKernelDebugger *) is called for a debugger client, or an kIOReturnBadArgument is returned for any other type.
Result: The return from the dispatched methods, or kIOReturnBadArgument if the client's type is unknown.
Name Description client The client object that requested the enable.
protected:
virtual IOReturn enablePacketFilters(UInt32 filters, UInt32 * activeFiltersP) = 0;
After calling getPacketFilters() to gather the set of supported packet filters. A client may issue a request to enable a group of filters from the supported set.
Result: kIOReturnSuccess on success, otherwise an error code is returned. If *activeFiltersP != filters, then an error must be retuned.
Name Description filters Each bit set indicates a particular filter that should be enabled. Filter bits that are not turned on must be disabled. activeFiltersP Updated by this method to reflect the real set of active filters. Ideally, it should be the same as the set specified by the first argument.
protected:
virtual bool enableSyncRequest();
Enable syncRequest() to handle synchronous requests. By default, syncRequest() is always enabled unless a call is made to disableSyncRequest().
Result: The previous state.protected:
virtual IOReturn flushOutputQueue(UInt32 * flushCountP);
A client request to flush all packets currently held by the queue, and return the number of packets discarded. If an IOOutputQueue was allocated, and this method does not return kIOReturnSuccess, then this request will be handled by the queue object.
Result: kIOReturnUnsupported. Drivers may override this method and return kIOReturnSuccess.
Name Description flushCountP Pointer to an integer where the number of packets discarded should be written to.
protected:
virtual void free();
Free the IONetworkController instance and all allocated resources, then call super::free().
protected:
virtual void freePacket(struct mbuf * m);
Release the mbuf back to the free pool.
Name Description m The mbuf to be freed.
protected:
virtual IOCommandGate * getCommandGate() const;
An IOCommandGate is created and attached to an IOWorkLoop during start(). This IOCommandGate object is used to handle client commands issued through the syncRequest() method. Subclasses that need a IOCommandGate should use the object returned by this method, rather than creating a new instance.
Result: The internal IOCommandGate object.protected:
virtual IOReturn getControllerIndex(UInt32 * indexP) const;
Return an ordinal for multiport network adapters. The implementation in IONetworkController will work for PCI controllers behind a PCI-PCI bridge. This method exists solely to support the current interface naming scheme, and is likely to undergo changes or may disappear in the future.
Result: kIOReturnSuccess.
Name Description indexP Update the ordinal via this pointer.
public:
virtual const IONetworkMedium * getCurrentMedium() const;
Return the current medium property. If the driver has yet to assign an entry in its medium dictionary as the current medium. Then the driver's property table is consulted and a default medium property, which can be set by the user, is looked up and returned as the current medium. Thus drivers can call getCurrentMedium() after publishing a medium dictionary to get the default medium selected by the user. However, if the medium selected by the user does not match any entries found in the dictionary, then 0 is returned.
Result: An entry in the medium dictionary that is the current medium.public:
virtual UInt32 getFamilyFeatureSet() const = 0;
Report family specific features supported by the controller.
Result: Drivers may override this method and return a mask of all supported family defined feature sets.public:
virtual UInt32 getFeatureSet() const;
Report features supported by the controller.
Result: Returns 0. Drivers may override this method and return a mask of all supported feature sets.Result: Return a string containing any additional information about the controller and/or driver.public:
virtual const char * getInfoString() const;
public:
virtual const OSDictionary * getMediumDictionary() const;
Return the medium dictionary from the property table. See mediumDictionary() to obtain a copy of the dictionary instead.
Result: The medium dictionary, or 0 if the driver never published a medium dictionary through setMediumDictionary().Result: Return a string describing the model of the network controller. i.e. "BMac"public:
virtual const char * getModelString() const = 0;
public:
void getOutputHandler(IOOutputHandler * handlerP) const;
Given a pointer to an IOOutputHandler structure provided by the caller, this method will initialize the structure, and thus exposing the controller method responsible for handling the output packets (outputPacket), and also the method responsible for handling interface requests (requestHandler).
Name Description handlerP Pointer to an IOOutputHandler structure. See IONetworkInterface.
protected:
virtual IOOutputQueue * getOutputQueue() const;
Result: Return the output queue allocated though allocateOutputQueue().
protected:
virtual IOReturn getOutputQueueCapacity(UInt32 * capacityP) const;
A client request to fetch the capacity of the output queue. If an IOOutputQueue was allocated, and this method does not return kIOReturnSuccess, then this request will be handled by the queue object.
Result: kIOReturnUnsupported. Drivers may override this method and return kIOReturnSuccess.
Name Description capacityP Pointer to an integer where the current capacity should be written to.
protected:
virtual IOReturn getOutputQueueSize(UInt32 * size) const;
A client request to fetch the number of packets currently held by the queue. If an IOOutputQueue was allocated, and this method does not return kIOReturnSuccess, then this request will be handled by the queue object.
Result: kIOReturnUnsupported. Drivers may override this method and return kIOReturnSuccess.
Name Description sizeP Pointer to an integer where the size should be written to.
protected:
virtual void getPacketBufferConstraints( IOPacketBufferConstraints * constraintsP) const;
Called by start() to obtain the constraints on the memory buffer associated with each mbuf allocated through allocatePacket(). Drivers can override this method to specify their buffer constraints that are usually imposed by their bus master hardware. Note that outbound packets, originating from the network stack, are not subject to the constraints reported here.
Name Description constraintsP A pointer to an IOPacketBufferConstraints structure allocated by the caller that the receiver is expected to initialize. See IOPacketBufferConstraints structure definition for additional information.
protected:
virtual IOReturn getPacketFilters(UInt32 * filtersP) = 0;
Obtain the set of packet filters supported by the controller. See IOPacketFilter enum for the list of defined packet filters. A subclass must implement this method and write its set of supported filters, formed by OR'ing the defined filter constants.
Result: kIOReturnSuccess on success, or an error code to indicate failure to discover the available filters.
Name Description filtersP Pointer to an integer that the filter set should be written to.
Result: Return a string describing the revision level of the network controller.public:
virtual const char * getRevisionString() const;
protected:
virtual OSObject * getSyncRequestSender() const;
For methods that are called by syncRequest(), return the sender of the request.
Result: The caller of the request is returned.public:
virtual const char * getVendorString() const = 0;
Result: Return a vendor string. i.e. "Apple"
protected:
virtual IOWorkLoop * getWorkLoop() const;
An IOWorkLoop object is created by the start() method. Drivers can use this method to obtain a reference to the IOWorkLoop object created and attach their event sources, such as IOTimerEventSource or IOInterruptEventSource. See IOWorkLoop documentation.
Result: The internal IOWorkLoop object.protected:
virtual void handleClose(IOService * client, IOOptionBits options);
Handle a close from one of our client objects. IOService calls this method with the arbitration lock held. Subclasses should not override this method.
Name Description client The client that has closed the controller. options See IOService.
protected:
virtual bool handleIsOpen(const IOService * client) const;
This method is always called by IOService with the arbitration lock held. Subclasses should not override this method.
Result: true if the specified client, or any client if none is specified, presently has an open on this object.protected:
virtual bool handleOpen(IOService * client, IOOptionBits options, void * argument);
Handle a client open on the controller object. IOService calls this method with the arbitration lock held. Subclasses should not override this method.
Result: true to accept the client open, false to refuse the open.
Name Description client The client that is trying to open the controller. options See IOService. argument See IOService.
public:
virtual bool init(OSDictionary * properties);
Initialize the IONetworkController instance. Instance variables are initialized to their default values, and the init() method in superclass is called.
Result: true on success, false otherwise.
Name Description properties A property table.
public:
static void initialize();
Class initializer for IONetworkController. Create OSSymbol objects ahead of time that are used as keys. This method is called explicitly by a line in IOStartIOKit.cpp and not by the OSDefineMetaClassAndInit() mechanism, since the OSSymbol class is not guaranteed to be initialized first, thus its OSSymbol pool may not be setup.
public:
virtual OSDictionary * mediumDictionary() const;
Return a.copy of the medium dictionary published by the driver. The caller is responsible for releasing the dictionary object returned.
Result: A copy of the medium dictionary, or 0 if the driver never published a medium dictionary through setMediumDictionary().public:
virtual UInt32 outputPacket(struct mbuf * m);
Transmit the given packet mbuf. If an IOOutputQueue was
allocated and returned in allocateOutputQueue(), then this method will
be called by a queue object. Otherwise, an interface object will call
this method directly upon receiving an output packet from the network
layer. When a queue is not present, the controller driver must assume
that several threads may call this method simultaneously, thus it must
implement some form of locking to enforce serialization.
There is no upper limit on the length of the mbuf chain provided.
Drivers must be able to handle cases when the chain exceeds the limit
dictated by their DMA engines, and perform coalescing to copy the
various memory fragments into a smaller number of fragments. All
this complexity can be hidden when an IOMBufMemoryCursor is used,
which will convert a mbuf chain into a scatter-gather list that is
guaranteed never to exceed a given size.
Packets may also be chained to form a packet chain. Although the
interface object (network layer) will currently only send a single
packet to the controller for each outputPacket() call, it is
possible for this to change. When a queue object is used, the queue
will absorb the packet or packet chain, but it will always send a
single packet to the controller. When a queue is not used, drivers
should take this into consideration.
The implementation in IONetworkController performs no useful action
and will drop all packets. Subclasses are expected to override this
method.
Result: A return code defined by the caller.
Name Description m The packet mbuf.
protected:
virtual IOReturn performDiagnostics(UInt32 * failureCode);
Called by clients to request the hardware to perform diagnostics and return the test result.
Result: kIOReturnSuccess if hardware passed all test, otherwise an appropriate error code should be returned.
Name Description failureCode In addition to the return code, drivers may return a hardware specific failure code via the pointer provided.
protected:
virtual bool publishCapabilities();
Discover and publish controller capabilities and publish them to the property table.
Result: true if all capabilities were discovered and published successfully, false otherwise.public:
virtual void publishParameters(OSDictionary * paramDict);
Controller drivers can publish custom network parameters by adding their IONetworkParameter object(s) to the dictionary provided. The interface object will call this method after publishing its own parameters. The implementation in IONetworkController does nothing.
Name Description paramDict Dictionary provided by the interface object.
protected:
virtual bool ready(IOService * provider);
This method is called the first time that a controller driver calls attachNetworkInterface(), which is an indication that the driver has been started and is ready to service client requests. IONetworkController uses this method to complete its initialization before providing services to client objects. This method will always run on the workloop thread.
Result: true on success, false otherwise.
Name Description provider The controller's provider object.
protected:
virtual struct mbuf * replaceOrCopyPacket(struct mbuf ** mp, UInt rcvlen, bool * replacedP);
Either replace or copy the source mbuf given depending on the amount of data in the source mbuf. This method will either perform a copy or replace the source mbuf, whichever is more time efficient. If replaced, then the original mbuf is returned, and a new mbuf is allocated to take its place. If copied, the source mbuf is left intact, while a copy is returned that is just big enough to hold the data from the source mbuf.
Result: A replacement or a copy of the source mbuf, 0 if mbuf allocation failed.
Name Description mp A pointer to the source mbuf that may be updated by this method to point to the new mbuf if replaced. rcvlen The number of data bytes in the source mbuf. replacedP Pointer to a bool that is set by this method to true if the source mbuf was replaced, false if the source mbuf was copied.
protected:
virtual struct mbuf * replacePacket(struct mbuf ** mp, UInt size = 0);
Replace the mbuf pointed by the pointer provided with another mbuf. Drivers can call this method to replace a mbuf before passing the original mbuf, which contains a received frame, to the network layer.
Result: If mbuf allocation was successful, then the replacement will take place and the original mbuf will be returned. Otherwise, a NULL is returned.
Name Description mp A pointer to the original mbuf that shall be updated by this method to point to the new mbuf. size If size is 0, then the new mbuf shall have the same size as the original mbuf that is being replaced. Otherwise, the new mbuf shall have the size specified.
public:
virtual IOReturn requestHandler(OSObject * sender, UInt32 request, void * arg0 = 0, void * arg1 = 0, void * arg2 = 0, void * arg3 = 0);
Handles client requests. Most requests will require participation by the hardware, and thus will cause driver methods to be called via the syncRequest() method, to ensure single threaded access to the hardware.
Result: kIOReturnSuccess if the request was handled successfully, otherwise an error code is returned.
Name Description sender The sender of the request. request The request type. arg0 Request argument. arg1 Request argument. arg2 Request argument. arg3 Request argument.
protected:
virtual bool setCurrentMedium(const IONetworkMedium * medium);
From the set of medium objects in the medium dictionary
published by the driver (through setMediumDictionary), one can be
assigned as the "current" medium, to designate it as the
currently selected medium. Drivers should call this method whenever
the driver changes its media selection.
An media change event will be broadcasted to interface clients
when the current medium property changes.
Result: true if the medium dictionary exists, the medium object provided is the same as an entry in the dictionary, and the update was successful, false otherwise.
Name Description medium A medium object to promote as the current medium.
protected:
virtual bool setLinkStatus(UInt32 status, UInt64 speed, const IONetworkMedium * activeMedium, OSData * data = 0);
Update the link status parameters published by the controller. Drivers should call this method whenever the link status changes. Never call this method from the interrupt context since this method may block. An event will be sent to all attached interface objects when a change is detected.
Result: true if all link properties were successfully updated, false otherwise.
Name Description status See IONetworkMedium.h for defined link status bits. speed Link speed in units of bits per second. activeMedium The medium where the link is established. This may not be the same as the current medium. data An arbitrary OSData object containing additional information about the link status.
protected:
virtual IOReturn setMaxTransferUnit(UInt32 mtu);
A client request for the controller to switch to a new MTU size. This method is called only if the current MTU size advertised by the interface does not match the new size requested.
Result: kIOReturnUnsupported. Drivers that override this method should return kIOReturnSuccess to indicate that the new MTU size was accepted and is in effect.
Name Description mtu The new MTU size requested.
protected:
virtual IOReturn setMedium(const IONetworkMedium * medium);
A client request for the controller to change the medium currently used. Drivers may override this method and provide an implementation appropriate for its hardware, then call setCurrentMedium() to update the current medium property.
Result: kIOReturnUnsupported. Drivers may override this method and return kIOReturnSuccess if the change was performed successfully.
Name Description medium A medium object in the published medium dictionary.
protected:
virtual bool setMediumDictionary(const OSDictionary * mediumDict);
This method is called by drivers to publish a dictionary
containing IONetworkMedium objects. Each entry in this dictionary
corresponds to a medium supported by the controller. The dictionary
is added to the property table, and the caller can release
the dictionary after this method returns. It is permissible to call
this method multiple times, in case the hardware's media capability
changes dynamically. Otherwise, drivers should call this method
only once in its start() implementation.
Several methods depends on the presence of a medium dictionary.
Those methods are:
setMedium()
setCurrentMedium()
getCurrentMedium()
getMediumDictionary()
mediumDictionary()
This method will broadcast a media change event
to all attached interface clients.
Result: true if the dictionary and its entries are valid, and the dictionary was added to the property table, false otherwise.
Name Description mediumDict Dictionary provided by the caller that has been populated with IONetworkMedium objects.
protected:
virtual IOReturn setOutputQueueCapacity(UInt32 capacity);
A client request to adjust the capacity of the driver's output queue (number of packets the queue can hold). If an IOOutputQueue was allocated, and this method does not return kIOReturnSuccess, then this request will be handled by the queue object.
Result: kIOReturnUnsupported. Drivers may override this method and return kIOReturnSuccess if the new capacity was accepted.
Name Description capacity The new capacity of the output queue.
public:
virtual bool start(IOService * provider);
Called when the controller was matched to a provider and has been selected to begin running. IONetworkController will allocate resources and call several methods to gather the controller's characteristics. None of those calls should generate any I/O. Subclasses must override this method and call super::start() at the beginning of its implementation.
Result: true on success, false otherwise.
Name Description provider The provider that the controller was matched (and attached) to.
public:
void stop(IOService * provider);
The opposite of start(). The controller has been instructed to stop running. This method should release resources and undo actions performed by start(). Subclasses must override this method and call super::stop() at the end of its implementation.
Name Description provider The provider that the controller was matched (and attached) to.
public:
virtual IOReturn syncRequest(OSObject * sender, OSObject * target, IONetworkAction action, UInt32 * ret = 0, void * arg0 = 0, void * arg1 = 0, void * arg2 = 0, void * arg3 = 0);
Instruct the internal IOCommandGate object to call the member function provided. The function called by the IOCommandGate and any other actions called by event source attached to the same workloop will run in a mutually exclusive fashion.
Result: kIOReturnSuccess on success, kIOReturnNotReady if syncRequest() was refused to handle the request.
Name Description sender The sender of the synchronous request. target The target object that implements the action. action The action to perform. ret The return value from the action. arg0 Action argument. arg1 Action argument. arg2 Action argument. arg3 Action argument.
© 2000 Apple Computer, Inc. (Last Updated 2/23/2000)