Functions



allocateNetworkInterface

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.

allocateOutputQueue

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.

allocatePacket

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.

Parameters

NameDescription
sizeThe size of the mbuf packet.
Result: The allocated mbuf packet, or 0 if allocation failed.

attachNetworkInterface

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.

Parameters

NameDescription
interfaceIf successful (return value is true), then the interface object will be written to the handle provided by the caller.
doRegisterIf 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.
Result: true on success, false otherwise.

broadcastEvent

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.

Parameters

NameDescription
typeEvent type. See IONetworkInterface.
argEvent argument. See IONetworkInterface.
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.

configureNetworkInterface

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.

Parameters

NameDescription
netifThe interface object to be configured.
Result: true if configuration was successful, false otherwise.

copyPacket

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.

Parameters

NameDescription
mThe source mbuf.
sizeThe number of bytes to copy. If set to 0, then the entire source mbuf is copied.
Result: A new mbuf created from the source packet.

detachNetworkInterface

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.

Parameters

NameDescription
interfaceAn interface object to be detached.

disable

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.

Parameters

NameDescription
clientThe client object that requested the disable.
Result: The return from the dispatched methods, or kIOReturnBadArgument if the client's type is unknown.

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.

Parameters

NameDescription
netifThe interface object that requested the disable.
Result: kIOReturnUnsupported. Driver may override this method and return kIOReturnSuccess upon success, or an error code otherwise.

disableSyncRequest

protected:

virtual bool disableSyncRequest();

Prevent syncRequest() from handling synchronous requests.

Result: The previous state.

enable

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.

Parameters

NameDescription
netifThe interface object that requested the enable.
Result: kIOReturnUnsupported. Driver may override this method and return kIOReturnSuccess upon success, or an error code otherwise.

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.

Parameters

NameDescription
clientThe client object that requested the enable.
Result: The return from the dispatched methods, or kIOReturnBadArgument if the client's type is unknown.

enablePacketFilters

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.

Parameters

NameDescription
filtersEach bit set indicates a particular filter that should be enabled. Filter bits that are not turned on must be disabled.
activeFiltersPUpdated 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.
Result: kIOReturnSuccess on success, otherwise an error code is returned. If *activeFiltersP != filters, then an error must be retuned.

enableSyncRequest

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.

flushOutputQueue

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.

Parameters

NameDescription
flushCountPPointer to an integer where the number of packets discarded should be written to.
Result: kIOReturnUnsupported. Drivers may override this method and return kIOReturnSuccess.

free

protected:

virtual void free();

Free the IONetworkController instance and all allocated resources, then call super::free().


freePacket

protected:

virtual void freePacket(struct mbuf * m);

Release the mbuf back to the free pool.

Parameters

NameDescription
mThe mbuf to be freed.

getCommandGate

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.

getControllerIndex

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.

Parameters

NameDescription
indexPUpdate the ordinal via this pointer.
Result: kIOReturnSuccess.

getCurrentMedium

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.

getFamilyFeatureSet

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.

getFeatureSet

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.

getInfoString

public:

virtual const char * getInfoString() const;

Result: Return a string containing any additional information about the controller and/or driver.

getMediumDictionary

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().

getModelString

public:

virtual const char * getModelString() const = 0;

Result: Return a string describing the model of the network controller. i.e. "BMac"

getOutputHandler

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).

Parameters

NameDescription
handlerPPointer to an IOOutputHandler structure. See IONetworkInterface.

getOutputQueue

protected:

virtual IOOutputQueue * getOutputQueue() const;

Result: Return the output queue allocated though allocateOutputQueue().

getOutputQueueCapacity

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.

Parameters

NameDescription
capacityPPointer to an integer where the current capacity should be written to.
Result: kIOReturnUnsupported. Drivers may override this method and return kIOReturnSuccess.

getOutputQueueSize

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.

Parameters

NameDescription
sizePPointer to an integer where the size should be written to.
Result: kIOReturnUnsupported. Drivers may override this method and return kIOReturnSuccess.

getPacketBufferConstraints

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.

Parameters

NameDescription
constraintsPA pointer to an IOPacketBufferConstraints structure allocated by the caller that the receiver is expected to initialize. See IOPacketBufferConstraints structure definition for additional information.

getPacketFilters

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.

Parameters

NameDescription
filtersPPointer to an integer that the filter set should be written to.
Result: kIOReturnSuccess on success, or an error code to indicate failure to discover the available filters.

getRevisionString

public:

virtual const char * getRevisionString() const;

Result: Return a string describing the revision level of the network controller.

getSyncRequestSender

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.

getVendorString

public:

virtual const char * getVendorString() const = 0;

Result: Return a vendor string. i.e. "Apple"

getWorkLoop

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.

handleClose

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.

Parameters

NameDescription
clientThe client that has closed the controller.
optionsSee IOService.

handleIsOpen

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.

handleOpen

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.

Parameters

NameDescription
clientThe client that is trying to open the controller.
optionsSee IOService.
argumentSee IOService.
Result: true to accept the client open, false to refuse the open.

init

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.

Parameters

NameDescription
propertiesA property table.
Result: true on success, false otherwise.

initialize

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.


mediumDictionary

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().

outputPacket

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.

Parameters

NameDescription
mThe packet mbuf.
Result: A return code defined by the caller.

performDiagnostics

protected:

virtual IOReturn performDiagnostics(UInt32 * failureCode);

Called by clients to request the hardware to perform diagnostics and return the test result.

Parameters

NameDescription
failureCodeIn addition to the return code, drivers may return a hardware specific failure code via the pointer provided.
Result: kIOReturnSuccess if hardware passed all test, otherwise an appropriate error code should be returned.

publishCapabilities

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.

publishParameters

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.

Parameters

NameDescription
paramDictDictionary provided by the interface object.

ready

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.

Parameters

NameDescription
providerThe controller's provider object.
Result: true on success, false otherwise.

replaceOrCopyPacket

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.

Parameters

NameDescription
mpA pointer to the source mbuf that may be updated by this method to point to the new mbuf if replaced.
rcvlenThe number of data bytes in the source mbuf.
replacedPPointer to a bool that is set by this method to true if the source mbuf was replaced, false if the source mbuf was copied.
Result: A replacement or a copy of the source mbuf, 0 if mbuf allocation failed.

replacePacket

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.

Parameters

NameDescription
mpA pointer to the original mbuf that shall be updated by this method to point to the new mbuf.
sizeIf 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.
Result: If mbuf allocation was successful, then the replacement will take place and the original mbuf will be returned. Otherwise, a NULL is returned.

requestHandler

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.

Parameters

NameDescription
senderThe sender of the request.
requestThe request type.
arg0Request argument.
arg1Request argument.
arg2Request argument.
arg3Request argument.
Result: kIOReturnSuccess if the request was handled successfully, otherwise an error code is returned.

setCurrentMedium

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.

Parameters

NameDescription
mediumA medium object to promote as the current medium.
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.

setLinkStatus

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.

Parameters

NameDescription
statusSee IONetworkMedium.h for defined link status bits.
speedLink speed in units of bits per second.
activeMediumThe medium where the link is established. This may not be the same as the current medium.
dataAn arbitrary OSData object containing additional information about the link status.
Result: true if all link properties were successfully updated, false otherwise.

setMaxTransferUnit

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.

Parameters

NameDescription
mtuThe new MTU 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.

setMedium

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.

Parameters

NameDescription
mediumA medium object in the published medium dictionary.
Result: kIOReturnUnsupported. Drivers may override this method and return kIOReturnSuccess if the change was performed successfully.

setMediumDictionary

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.

Parameters

NameDescription
mediumDictDictionary provided by the caller that has been populated with IONetworkMedium objects.
Result: true if the dictionary and its entries are valid, and the dictionary was added to the property table, false otherwise.

setOutputQueueCapacity

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.

Parameters

NameDescription
capacityThe new capacity of the output queue.
Result: kIOReturnUnsupported. Drivers may override this method and return kIOReturnSuccess if the new capacity was accepted.

start

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.

Parameters

NameDescription
providerThe provider that the controller was matched (and attached) to.
Result: true on success, false otherwise.

stop

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.

Parameters

NameDescription
providerThe provider that the controller was matched (and attached) to.

syncRequest

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.

Parameters

NameDescription
senderThe sender of the synchronous request.
targetThe target object that implements the action.
actionThe action to perform.
retThe return value from the action.
arg0Action argument.
arg1Action argument.
arg2Action argument.
arg3Action argument.
Result: kIOReturnSuccess on success, kIOReturnNotReady if syncRequest() was refused to handle the request.

© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)