/* * Copyright (c) 1998-2008 Apple Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * * The contents of this file constitute Original Code as defined in and * are subject to the Apple Public Source License Version 1.1 (the * "License"). You may not use this file except in compliance with the * License. Please obtain a copy of the License at * http://www.apple.com/publicsource and read it before using this file. * * This Original Code and all software distributed under the License are * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the * License for the specific language governing rights and limitations * under the License. * * @APPLE_LICENSE_HEADER_END@ */ #ifndef _IONETWORKINTERFACE_H #define _IONETWORKINTERFACE_H /*! @defined kIONetworkInterfaceClass @abstract The name of the IONetworkInterface class. */ #define kIONetworkInterfaceClass "IONetworkInterface" /*! @defined kIONetworkData @abstract A property of IONetworkInterface objects. @discussion The kIONetworkData property has an OSDictionary value and is a container for the set of IONetworkData objects managed by the interface. Each entry in the dictionary is a key/value pair consisting of the network data name, and an OSDictionary describing the contents of the network data. */ #define kIONetworkData "IONetworkData" /*! @defined kIOInterfaceType @abstract A property of IONetworkInterface objects. @discussion The kIOInterfaceType property has an OSNumber value that specifies the type of network interface that this interface represents. The type constants are defined in bsd/net/if_types.h. */ #define kIOInterfaceType "IOInterfaceType" /*! @defined kIOMaxTransferUnit @abstract A property of IONetworkInterface objects. @discussion The kIOMaxTransferUnit property has an OSNumber value that specifies the maximum transfer unit for the interface in bytes. */ #define kIOMaxTransferUnit "IOMaxTransferUnit" /*! @defined kIOMediaAddressLength @abstract A property of IONetworkInterface objects. @discussion The kIOMediaAddressLength property has an OSNumber value that specifies the size of the media address in bytes. */ #define kIOMediaAddressLength "IOMediaAddressLength" /*! @defined kIOMediaHeaderLength @abstract A property of IONetworkInterface objects. @discussion The kIOMediaHeaderLength property has an OSNumber value that specifies the size of the media header in bytes. */ #define kIOMediaHeaderLength "IOMediaHeaderLength" /*! @defined kIOInterfaceFlags @abstract A property of IONetworkInterface objects. @discussion The kIOInterfaceFlags property has an OSNumber value that specifies the current value of the interface flags. The flag constants are defined in bsd/net/if.h. */ #define kIOInterfaceFlags "IOInterfaceFlags" /*! @defined kIOInterfaceExtraFlags @abstract A property of IONetworkInterface objects. @discussion The kIOInterfaceExtraFlags property has an OSNumber value that specifies the current value of the interface eflags. The eflag constants are defined in bsd/net/if.h. */ #define kIOInterfaceExtraFlags "IOInterfaceExtraFlags" /*! @defined kIOInterfaceUnit @abstract A property of IONetworkInterface objects. @discussion The kIOInterfaceUnit property has an OSNumber value that describes the unit number assigned to the interface object. */ #define kIOInterfaceUnit "IOInterfaceUnit" /*! @defined kIOInterfaceState @abstract A property of IONetworkInterface objects. @discussion The kIOInterfaceState property has an OSNumber value that describes the current state of the interface object. This property is not exported to BSD via the ifnet structure. */ #define kIOInterfaceState "IOInterfaceState" /*! @defined kIOInterfaceNamePrefix @abstract A property of IONetworkInterface objects. @discussion The kIOInterfaceNamePrefix property has an OSString value that describes the string prefix for the BSD name assigned to the interface. */ #define kIOInterfaceNamePrefix "IOInterfaceNamePrefix" /*! @defined kIOPrimaryInterface @abstract A property of IONetworkInterface objects. @discussion The kIOInterfaceNamePrefix property has an OSBoolean value that describes whether the interface is the primary or the built-in network interface. */ #define kIOPrimaryInterface "IOPrimaryInterface" /*! @defined kIOBuiltin @abstract kIOBuiltin is a property of IONetworkInterface objects. It has an OSBoolean value. @discussion The kIOBuiltin property describes whether the interface is built-in. */ #define kIOBuiltin "IOBuiltin" /*! @defined kIOLocation @abstract kIOLocation is a property of IONetworkInterface objects. It has an OSString value. @discussion The kIOLocation property describes the physical location of built-in interfaces. */ #define kIOLocation "IOLocation" /*! @defined kIONetworkNoBSDAttachKey @abstract kIONetworkNoBSDAttachKey is a property of IONetworkInterface objects. It has an OSBoolean value. @discussion Adding a property with this key and the value kOSBooleanTrue before the interface is published will hold off the BSD attach. When the interface is ready to attach to BSD, remove the property and then re-publish the interface by calling registerService(). */ #define kIONetworkNoBSDAttachKey "IONetworkNoBSDAttach" /*! @enum InterfaceObjectStates @discussion Constants used to encode the state of the interface object. @constant kIONetworkInterfaceRegisteredState The interface object has registered with the data link layer. @constant kIONetworkInterfaceOpenedState One or more clients have an open on the interface object. @constant kIONetworkInterfaceDisabledState The interface is temporarily unable to service its clients. This will occur when the network controller that is servicing the interface has entered a low power state that renders it unusable. */ enum { kIONetworkInterfaceRegisteredState = 0x1, kIONetworkInterfaceOpenedState = 0x2, kIONetworkInterfaceDisabledState = 0x4 }; #ifdef KERNEL #ifdef __cplusplus #include <IOKit/IOService.h> #include <IOKit/network/IONetworkData.h> #include <IOKit/network/IONetworkStats.h> #include <IOKit/network/IONetworkMedium.h> #include <net/kpi_interface.h> class IONetworkController; class IONetworkStack; class IOCommandGate; struct IOMbufQueue; /*! @typedef IOOutputAction @discussion Prototype for an output packet handler that will process all outbound packets sent to the interface from the data link layer. An output handler is registered with the interface by calling registerOutputHandler(). @param mbuf_t A packet mbuf. @param param A parameter for the output request. */ typedef UInt32 (OSObject::*IOOutputAction)(mbuf_t, void * param); /*! @typedef BPF_FUNC @discussion Prototype for the BPF tap handler. This will disappear when the correct DLIL header file is included. */ typedef int (*BPF_FUNC)(struct ifnet *, struct mbuf *); // Network event types recognized by inputEvent(). // enum { /* DLIL defined event, argument must be a pointer to a kern_event_msg structure. */ kIONetworkEventTypeDLIL = 0xff000001, /* Link up event, no argument */ kIONetworkEventTypeLinkUp = 0xff000002, /* Link down event, no argument */ kIONetworkEventTypeLinkDown = 0xff000003, /* Wake on LAN support changed, no argument */ kIONetworkEventWakeOnLANSupportChanged = 0xff000004, /* Link speed changed */ kIONetworkEventTypeLinkSpeedChange = 0xff000005 }; #ifdef __PRIVATE_SPI__ enum { kIONetworkWorkLoopSynchronous = 0x00000001 }; enum { kIONetworkClientBehaviorLinkStateActiveRegister = 0x00000001, kIONetworkClientBehaviorLinkStateChangeMessage = 0x00000002 }; /*! @enum IOMbufServiceClass @discussion Service class of a mbuf packet. @constant kIOMbufServiceClassBKSYS Background System-Initiated. @constant kIOMbufServiceClassBK Background. @constant kIOMbufServiceClassBE Best Effort. @constant kIOMbufServiceClassRD Responsive Data. @constant kIOMbufServiceClassOAM Operations, Administration, and Management. @constant kIOMbufServiceClassAV Multimedia Audio/Video Streaming. @constant kIOMbufServiceClassRV Responsive Multimedia Audio/Video. @constant kIOMbufServiceClassVI Interactive Video. @constant kIOMbufServiceClassVO Interactive Voice. @constant kIOMbufServiceClassCTL Network Control. */ enum IOMbufServiceClass { kIOMbufServiceClassBKSYS = 100, kIOMbufServiceClassBK = 200, kIOMbufServiceClassBE = 0, kIOMbufServiceClassRD = 300, kIOMbufServiceClassOAM = 400, kIOMbufServiceClassAV = 500, kIOMbufServiceClassRV = 600, kIOMbufServiceClassVI = 700, kIOMbufServiceClassVO = 800, kIOMbufServiceClassCTL = 900 }; /*! @enum IONetworkTransmitStatus @discussion Constants for packet transmit status. @constant kIONetworkTransmitStatusSuccess Packet sent across link. @constant kIONetworkTransmitStatusFailed Failed to send packet across link. @constant kIONetworkTransmitStatusAborted Send aborted, peer was asleep. @constant kIONetworkTransmitStatusQueueFull Driver send queue was full. */ enum { kIONetworkTransmitStatusSuccess = 0, kIONetworkTransmitStatusFailed = 1, kIONetworkTransmitStatusAborted = 2, kIONetworkTransmitStatusQueueFull = 3 }; typedef uint32_t IONetworkTransmitStatus; /*! @typedef IONetworkPacketPollingParameters @discussion Mirrors the definition of <code>ifnet_poll_params()</code>. @field maxPacketCount The maximum number of packets to be dequeued each time the driver's <code>pollInputPackets</code> is invoked. A zero value indicates the use of default maximum defined by the system. @field lowThresholdPackets Low watermark packets threshold. @field highThresholdPackets High watermark packets threshold. @field lowThresholdBytes Low watermark bytes threshold. @field highThresholdBytes High watermark bytes threshold. @field pollIntervalTime The interval time between each invocation of the driver's <code>pollInputPackets</code> in nanoseconds. */ struct IONetworkPacketPollingParameters { uint32_t maxPacketCount; uint32_t lowThresholdPackets; uint32_t highThresholdPackets; uint32_t lowThresholdBytes; uint32_t highThresholdBytes; uint64_t pollIntervalTime; uint64_t reserved[4]; }; #endif /* __PRIVATE_SPI__ */ /*! @class IONetworkInterface @abstract Abstract class that manages the connection between an IONetworkController and the data link interface layer. @discussion An IONetworkInterface object manages the connection between an IONetworkController and the data link interface layer (DLIL). All interactions between the controller and DLIL must go through an interface object. Any data structures that are required by DLIL for a particular interface type shall be allocated and mantained by the interface object. IONetworkInterface is an abstract class that must be extended by a concrete subclass to specialize for a particular network type. Although most drivers will allocate a single interface object, it is possible for multiple interfaces to be attached to a single controller. This controller driver will be responsible for arbitrating access among its multiple interface clients. IONetworkInterface also maintains a dictionary of IONetworkData objects containing statistics structures. Controller drivers can ask for a particular data object by name and update the statistics counters within directly. This dictionary is added to the interface's property table and is visible outside of the kernel. */ class IONetworkInterface : public IOService { OSDeclareAbstractStructors( IONetworkInterface ) friend class IONetworkStack; #ifdef __PRIVATE_SPI__ public: /*! @typedef OutputPreEnqueueHandler @param target Reference supplied when the handler was installed. @param refCon Reference supplied when the handler was installed. @param packet The output packet; may be the head of a chain of packets. Call <code>enqueueOutputPacket()</code> for each packet in the chain to enqueue the packet before returning. The handler executes on the thread context of the sending client. */ typedef errno_t (*OutputPreEnqueueHandler)( void * target, void * refCon, mbuf_t packet ); static IOReturn errnoToIOReturn( errno_t error ); #endif /* __PRIVATE_SPI__ */ private: IONetworkController * _driver; ifnet_t _backingIfnet; IOLock * _privateLock; OSSet * _clientSet; OSNumber * _stateBits; bpf_packet_func _inputFilterFunc; bpf_packet_func _outputFilterFunc; OSObject * _outTarget; IOOutputAction _outAction; UInt32 _clientVar[4]; OSDictionary * _dataDict; IOMbufQueue * _inputPushQueue; void * _unused1; UInt32 _unused2; struct ExpansionData { int unit; int type; int mtu; int flags; int eflags; int addrlen; int hdrlen; int32_t loggingLevel; uint32_t outputQueueModel; IONetworkStats driverStats; IONetworkStats lastDriverStats; ifnet_stat_increment_param inputDeltas; IORecursiveLock * publicLock; char * remote_NMI_pattern; unsigned int remote_NMI_len; IONetworkController * controller; uint32_t configFlags; uint32_t txRingSize; uint32_t txPullOptions; uint32_t txQueueSize; uint32_t txSchedulingModel; uint32_t txTargetQdelay; uint32_t txThreadState; volatile UInt32 txThreadFlags; uint32_t txThreadSignal; uint32_t txThreadSignalLast; thread_t txStartThread; void * txStartAction; IOWorkLoop * txWorkLoop; uint32_t rxRingSize; uint32_t rxPollOptions; uint32_t rxPollModel; void * rxPollAction; void * rxCtlAction; uint64_t rxPollEmpty; uint64_t rxPollTotal; #ifdef __PRIVATE_SPI__ OutputPreEnqueueHandler peqHandler; void * peqTarget; void * peqRefcon; uint32_t subType; #endif uint16_t txStartDelayQueueLength; /* optional */ uint16_t txStartDelayTimeout; /* optional */ IOOptionBits clientBehavior; thread_call_t inputEventThreadCall; // inputEvent() thread call }; ExpansionData * _reserved; bool _syncNetworkDataDict(); SInt32 syncSIOCSIFMEDIA(IONetworkController * ctr, struct ifreq * ifr); SInt32 syncSIOCGIFMEDIA(IONetworkController * ctr, struct ifreq * ifr, unsigned long cmd); SInt32 syncSIOCSIFMTU(IONetworkController * ctr, struct ifreq * ifr); void drainOutputQueue(ifnet_t ifp, IONetworkController * driver); IOReturn haltOutputThread(uint32_t stateBit); #ifdef __PRIVATE_SPI__ void actionInputCtl(IONetworkController * driver, ifnet_ctl_cmd_t cmd, uint32_t arglen, void * arg ); #endif void pushInputQueue( IOMbufQueue * queue ); void pushInputPacket( mbuf_t packet, uint32_t length ); int if_start_precheck( ifnet_t ifp ); static int performGatedCommand(void *, void *, void *, void *, void *); static void powerChangeHandler(void *, void *, void *); static errno_t if_ioctl(ifnet_t ifp, unsigned long cmd, void * data); static int if_output(ifnet_t ifp, mbuf_t); static errno_t if_set_bpf_tap(ifnet_t ifp, bpf_tap_mode, bpf_packet_func); static void if_detach(ifnet_t ifp); static void if_start(ifnet_t ifp); static void if_start_gated(ifnet_t ifp); static void if_input_poll(ifnet_t ifp, uint32_t flags, uint32_t max_count, mbuf_t * first_packet, mbuf_t * last_packet, uint32_t * cnt, uint32_t * len); static void if_input_poll_gated(ifnet_t ifp, uint32_t flags, uint32_t max_count, mbuf_t * first_packet, mbuf_t * last_packet, uint32_t * cnt, uint32_t * len); #ifdef __PRIVATE_SPI__ static errno_t if_input_ctl(ifnet_t ifp, ifnet_ctl_cmd_t cmd, uint32_t arglen, void * arg); static errno_t if_output_pre_enqueue(ifnet_t ifp, mbuf_t packet); static errno_t if_output_ctl(ifnet_t ifp, ifnet_ctl_cmd_t cmd, u_int32_t arglen, void *arg); #endif void notifyDriver( uint32_t type, void * data ); static void handleNetworkInputEvent(thread_call_param_t param0, thread_call_param_t param1); public: /*! @function isPrimaryInterface @abstract Queries whether the interface is the primary network interface on the system. @discussion The definition of a primary interface and its discovery is platform specific. @result Returns true if the interface is the primary interface, false otherwise. */ virtual bool isPrimaryInterface( void ) const; /*! @function init @abstract Initializes the <code>IONetworkInterface</code> object. @discussion Resources are allocated, but an <code>ifnet_t</code> will not be allocated until the interface is assigned a BSD name and attached to the network stack. @param controller A network controller object that will service the the interface. @result Returns true on success, false otherwise. */ virtual bool init( IONetworkController * controller ); /*! @function isRegistered @abstract Queries if the interface has attached to the BSD network stack. @discussion Once attached a <code>kIOBSDNameKey</code> property is added to the interface object with the assigned BSD name. @result Returns true if interface is registered and attached to the network stack, false otherwise. */ virtual bool isRegistered( void ) const; /*! @function getInterfaceState @abstract Reports the current state of the interface object. @result Returns the current interface state flags. */ virtual UInt32 getInterfaceState( void ) const; /*! @function getController @abstract Gets the <code>IONetworkController</code> object that created this interface. @discussion The controller object passed to init() will be retained until the interface closes the controller. Subclasses can safely call this method before the controller is closed. @result Returns the parent <code>IONetworkController</code> object. */ virtual IONetworkController * getController( void ) const; /*! @function inputPacket @abstract For drivers to submit a received packet to the network stack. @discussion The packet provided to this method may be added to an input queue managed by the interface object, which the driver can use to postpone the packet handoff to the network stack, until all received packets have been added to the input queue. A subsequent call to <code>flushInputQueue()</code>, will transfer the entire contents of the input queue to the network stack. This input queue is not protected by a lock. Drivers that leverage this input queue must either access the queue from a single thread, or enforce serialized access. @param mbuf_t The mbuf containing the received packet. @param length Specify the size of the received packet in the mbuf. The mbuf length fields are updated with this value. If zero, then the mbuf length fields are not updated. @param options Pass <code>kInputOptionQueuePacket</code> to enqueue the input packet. Pass zero to bypass the input queue, and immediately submit the packet to the network stack. @param param A parameter provided by the driver. Not used. @result Returns the number of packets that were submitted to the network stack, or zero if the packet was enqueued. */ virtual UInt32 inputPacket( mbuf_t packet, UInt32 length = 0, IOOptionBits options = 0, void * param = 0 ); /*! @enum InputOptionQueuePacket @discussion Options for <code>inputPacket()</code>. @constant kInputOptionQueuePacket Enqueue the input packet provided to the input packet queue. Calls to <code>inputPacket()</code> must be serialized. */ enum { kInputOptionQueuePacket = 0x1 }; /*! @function flushInputQueue @abstract Submit all packets held in the input queue to the network stack. @discussion Allow drivers to remove all packets from the input queue and submit them to the network stack. This method should be used in concert with the <code>inputPacket()</code> method, to flush the input queue after queueing a number of received packets. @result Returns the number of packets that were submitted to the network stack. Returns zero if the queue was empty. */ virtual UInt32 flushInputQueue( void ); /*! @function clearInputQueue @abstract Discards all packets in the input queue. @discussion This method removes all packets from the input queue and releases them back to the free mbuf pool. It is unusual for a driver to call this method. @result Returns the number of packets freed. */ virtual UInt32 clearInputQueue( void ); /*! @function inputEvent @abstract Sends an event to the network stack. @discussion This method can be used by the driver to send an event to the network stack. @param type A constant describing the event type. @param data An optional data associated with the event. @result Returns true if the event was delivered, false if the event type specified is invalid, or if the event delivery failed. */ virtual bool inputEvent( UInt32 type, void * data ); /*! @function registerOutputHandler @abstract Registers a target/action to handle outbound packets. @discussion The interface object will forward all output packets sent from the network stack to the target and action registered using this method. The registration must occur before the interface is registered and opened by <code>IONetworkStack</code>, otherwise the default handler will be used. The default target and action is set by <code>init()</code> as the controller, and the handler returned by the controller's <code>getOutputHandler()</code> method. @param target Object that implements the output handler. @param action The function that will handle output packets. @result Returns true if the target/action provided was accepted, false otherwise. */ virtual bool registerOutputHandler( OSObject * target, IOOutputAction action ); /*! @function getNamePrefix @abstract Returns the BSD name prefix as a C-string. @discussion The BSD name for each interface object is generated by concatenating the string returned by this method, along with an unit number assigned by <code>IONetworkStack</code>. A concrete interface subclass must implement this method and return a distinct name prefix for its instances. @result Returns a pointer to a constant C-string. */ virtual const char * getNamePrefix() const = 0; /*! @function getInterfaceType @abstract Gets the interface type. @discussion This method returns the interface type previously set by <code>setInterfaceType</code>. @result Returns a constant defined in <code>bsd/net/if_types.h</code> that describes the interface type. */ virtual UInt8 getInterfaceType( void ) const; /*! @function getMaxTransferUnit @abstract Gets the maximum transfer unit for this interface. @discussion This method calls <code>ifnet_mtu</code> and returns the maximum transfer unit. @result Returns the interface MTU size in bytes. */ virtual UInt32 getMaxTransferUnit( void ) const; /*! @function getFlags @abstract Gets the current interface flags. @discussion This method calls <code>ifnet_flags</code> and returns the current interface flags. @result Returns the interface flags. */ virtual UInt16 getFlags( void ) const; /*! @function getExtraFlags @abstract Gets the current interface eflags. @discussion This method calls <code>ifnet_eflags</code> and returns the current interface eflags. @result Returns the value of the interface eflags. */ virtual UInt32 getExtraFlags( void ) const; /*! @function getMediaAddressLength @abstract Gets the size of the media (MAC-layer) address. @discussion This method calls <code>ifnet_addrlen</code> and returns the media address length. @result Returns the size of the media address in bytes. */ virtual UInt8 getMediaAddressLength( void ) const; /*! @function getMediaHeaderLength @abstract Gets the size of the media header. @discussion This method calls <code>ifnet_hdrlen</code> and returns the media header length. @result Returns the size of the media header in bytes. */ virtual UInt8 getMediaHeaderLength( void ) const; /*! @function getUnitNumber @abstract Gets the unit number assigned to this interface object. @discussion This method calls <code>ifnet_unit</code> and returns the unit number assigned by <code>IONetworkStack</code>. @result Returns the assigned interface unit number. */ virtual UInt16 getUnitNumber( void ) const; /*! @function addNetworkData @abstract Adds an <code>IONetworkData</code> object to the interface. @discussion The <code>IONetworkData</code> object is added to a collection using the key from <code>IONetworkData::getKey()<code>. The object provided is retained. @param aData The <code>IONetworkData</code> object. @result Returns true if the object was added, false otherwise. */ virtual bool addNetworkData( IONetworkData * aData ); /*! @function removeNetworkData @abstract Removes an <code>IONetworkData</code> object from the interface. @discussion This method removes an <code>IONetworkData</code> object from the collection managed by the interface. The object removed is released. @param aKey An OSSymbol identifying the object to be removed. @result Returns true if the object was found and removed, false otherwise. */ virtual bool removeNetworkData( const OSSymbol * aKey ); /*! @function removeNetworkData @abstract Removes an <code>IONetworkData</code> object from the interface. @discussion This method removes an <code>IONetworkData</code> object from the collection managed by the interface. The object removed is released. @param aKey A C-string identifying the object to be removed. @result Returns true if the object was found and removed, false otherwise. */ virtual bool removeNetworkData( const char * aKey ); /*! @function getNetworkData @abstract Gets an <code>IONetworkData</code> object from the interface. @discussion Returns a reference to an <code>IONetworkData</code> object that was previously added to the interface, and is associated with the provided key. @param aKey A C-string identifying the object. @result Returns a reference to the matching <code>IONetworkData</code> object, or NULL if no match was found. */ virtual IONetworkData * getNetworkData( const char * aKey ) const; /*! @function getNetworkData @abstract Gets an <code>IONetworkData</code> object from the interface. @discussion Returns a reference to an <code>IONetworkData</code> object that was previously added to the interface, and is associated with the provided key. @param aKey An OSSymbol identifying the object. @result Returns a reference to the matching <code>IONetworkData</code> object, or NULL if no match was found. */ virtual IONetworkData * getNetworkData(const OSSymbol * aKey) const; /* Compatibility methods */ IONetworkData * getParameter(const char * aKey) const; bool setExtendedFlags(UInt32 flags, UInt32 clear = 0); /* Override IOService::message() */ virtual IOReturn message( UInt32 type, IOService * provider, void * argument ) APPLE_KEXT_OVERRIDE; /*! @function debuggerRegistered @abstract Tells the <code>IONetworkData</code> that this interface will be used by the debugger. */ void debuggerRegistered( void ); protected: /*! @function setInterfaceType @abstract Sets the interface type. @discussion Sets the interface type before the interface is attached to the network stack. See <code>bsd/net/if_types.h</code> for defined types. The <code>kIOInterfaceType</code> is also updated using the provided type. @param type A constant defined in <code>bsd/net/if_types.h</code> that describes the interface type. @result Returns true to indicate success if the interface has not yet attached to the network stack, otherwise returns false. */ virtual bool setInterfaceType( UInt8 type ); /*! @function setMaxTransferUnit @abstract Sets the maximum transfer unit for this interface. @discussion Calls <code>ifnet_set_mtu</code> if the interface is attached to the network stack, and updates the <code>kIOMaxTransferUnit</code> property using the provided value. @param mtu The interface MTU size in bytes. @result Always returns true. */ virtual bool setMaxTransferUnit( UInt32 mtu ); /*! @function setFlags @abstract Performs a read-modify-write operation on the current interface flags value. @discussion Calls <code>ifnet_set_flags</code> if the interface is attached to the network stack, and updates the <code>kIOInterfaceFlags</code> property using the provided value. See <code>bsd/net/if.h</code> header file for the flag constants. @param flags The bits that should be set. @param clear The bits that should be cleared. If zero, then non of the flags are cleared and the result is formed by OR'ing the original flags value with the new flags. @result Always returns true. */ virtual bool setFlags( UInt16 flags, UInt16 clear = 0 ); /* Deprecated. No replacement. */ virtual bool setExtraFlags( UInt32 flags, UInt32 clear = 0 ); /*! @function setMediaAddressLength @abstract Sets the size of the media (MAC-layer) address. @discussion Calls <code>ifnet_set_addrlen</code> if interface is attached to the network stack, and updates the <code>kIOMediaAddressLength</code> property using the provided value. @param length The size of the media address in bytes. @result Always returns true. */ virtual bool setMediaAddressLength( UInt8 length ); /*! @function setMediaHeaderLength @abstract Sets the size of the media header. @discussion Calls <code>ifnet_set_hdrlen</code> if interface is attached to the network stack, and updates the <code>kIOMediaHeaderLength</code> property using the provided value. @param length The size of the media header in bytes. @result Always returns true. */ virtual bool setMediaHeaderLength( UInt8 length ); /*! @function setUnitNumber @abstract Assigns an unique unit number to this interface. @discussion This method is called internally before the interface is attached to the network stack, to assign an unique unit number to the interface object. The <code>kIOInterfaceUnit</code> property is also updated using the provided value. @param unit The unit number assigned to this interface object. @result Returns true to indicate success if the interface has not yet attached to the network stack, otherwise returns false. */ virtual bool setUnitNumber( UInt16 unit ); /*! @function free @abstract Frees the <code>IONetworkInterface</code> object. @discussion Resource allocated by init() are released, and clearInputQueue() is called to ensure that the input queue is empty. The interface should have already detached from the network stack. */ virtual void free( void ) APPLE_KEXT_OVERRIDE; /* Override IOService::handleOpen() */ virtual bool handleOpen( IOService * client, IOOptionBits options, void * argument ) APPLE_KEXT_OVERRIDE; /* Override IOService::handleClose() */ virtual void handleClose( IOService * client, IOOptionBits options ) APPLE_KEXT_OVERRIDE; /* Override IOService::handleIsOpen() */ virtual bool handleIsOpen( const IOService * client ) const APPLE_KEXT_OVERRIDE; /*! @function lock @abstract Acquires a recursive lock owned by the interface. @discussion A recursive lock is allocated and initialized in <code>init()</code>. This lock is otherwise not used by the <code>IONetworkInterface</code> class. This method call acquires the lock and must be balanced with an <code>unlock()</code>. */ virtual void lock( void ); /*! @function unlock @abstract Releases the recursive lock owned by the interface. @discussion A recursive lock is allocated and initialized in <code>init()</code>. This lock is otherwise not used by the <code>IONetworkInterface</code> class. This method call releases the lock to balance a prior <code>lock()</code>. */ virtual void unlock( void ); /*! @function controllerDidOpen @abstract Sends a notification that the interface has opened the network controller. @discussion This method is called by <code>handleOpen()</code> to notify subclasses that the controller was opened. The open on the controller occurs when the interface receives the initial open request from a client. Subclasses can override this method and inspect the controller before allowing the client open. This method is called with the arbitration lock held, hence issuing I/O to the controller must be avoided to eliminate the possibility of a deadlock. @param controller The controller that was opened. @result Must return true in order for handleOpen() to accept the client open. If the return is false, then the controller will be closed and the client open will fail. */ virtual bool controllerDidOpen( IONetworkController * controller ); /*! @function controllerWillClose @abstract Sends a notification that the interface will close the network controller. @discussion This method is called by <code>handleClose()</code> after receiving a close from the last interface client, and just before the controller is closed. Subclasses can override this method to perform any cleanup action before the controller is closed. This method is called with the arbitration lock held, hence issuing I/O to the controller should be avoided to eliminate the possibility of a deadlock. @param controller The controller that is about to be closed. */ virtual void controllerWillClose( IONetworkController * controller ); /*! @function performCommand @abstract Handles an ioctl command sent to the network interface. @discussion This method handles socket ioctl commands sent to the network interface from DLIL. IONetworkInterface handles commands that are common for all network interface types. A subclass of IONetworkInterface may override this method to override the command handling in IONetworkInterface, or to extend the command processing to handle additional commands. The ioctl commands handled by IONetworkInterface are <code>SIOCGIFMTU</code> (Get interface MTU size), <code>SIOCSIFMTU</code> (Set interface MTU size), <code>SIOCSIFMEDIA</code> (Set media), and <code>SIOCGIFMEDIA</code> (Get media and link status). @param controller The controller object. @param cmd The ioctl command code. @param arg0 Command argument 0. Generally a pointer to an ifnet structure associated with the interface. @param arg1 Command argument 1. @result Returns a BSD return value defined in <code>bsd/sys/errno.h</code>. */ virtual SInt32 performCommand( IONetworkController * controller, unsigned long cmd, void * arg0, void * arg1 ); public: /*! @function getIfnet @abstract Returns the <code>ifnet_t</code> allocated by the interface object. @discussion Gets the interface's <code>ifnet_t</code>, which is managed primarily by <code>IONetworkInterface</code>, however subclasses or drivers can use this method to obtain a reference to the <code>ifnet_t</code> for interface KPI calls. @result Returns the <code>ifnet_t</code> after the interface has attached to the network stack and before the interface is detached, otherwise returns NULL. */ virtual ifnet_t getIfnet( void ) const; protected: /* Deprecated. Use <code>initIfnetParams</code> instead. */ virtual bool initIfnet( struct ifnet * ifp ); /*! @function handleClientOpen @abstract Handles a client open on the interface. @discussion This method is called by <code>handleOpen()</code> to allow a subclass to handle a client close. The arbitration lock is held. @param client The client object requesting the open. @param options Options passed to <code>handleOpen()</code>. @param argument Argument passed to <code>handleOpen()</code>. @result Returns true to accept the client open, false to reject the open. */ virtual bool handleClientOpen( IOService * client, IOOptionBits options, void * argument ); /*! @function handleClientClose @abstract Handles a client close on the interface. @discussion This method is called by <code>handleClose()</code> to allow a subclass to handle a client close. The arbitration lock is held. @param client The client object requesting the close. @param options Options same options passed to <code>handleClose()</code>. */ virtual void handleClientClose( IOService * client, IOOptionBits options ); /* Override IOService::newUserClient() */ virtual IOReturn newUserClient( task_t owningTask, void * security_id, UInt32 type, IOUserClient ** handler ) APPLE_KEXT_OVERRIDE; /*! @function setInterfaceState @abstract Updates the interface object state flags. @discussion The flags reflect the current state of the interface, and is also published through the <code>kIOInterfaceState</code> property. @param set The flags that should be set. @param clear The flags that should be cleared. @result Returns the new interface state flags. */ virtual UInt32 setInterfaceState( UInt32 set, UInt32 clear = 0 ); /*! @function powerStateWillChangeTo @abstract Handles a pre-change power interest notification from the network controller. @discussion The <code>controllerWillChangePowerState()</code> method is called by this handler. Subclasses are not expected to override this method. @param flags Flags that describe the capability of the controller in the new power state. @param stateNumber An index to a state in the network controller's power state array that the controller is switching to. @param policyMaker A reference to the network controller's policy-maker, and is also the originator of this notification. @result Returns <code>IOPMAckImplied</code> to indicate synchronous completion. */ virtual IOReturn powerStateWillChangeTo( IOPMPowerFlags flags, unsigned long stateNumber, IOService * policyMaker ) APPLE_KEXT_OVERRIDE; /*! @function powerStateDidChangeTo @abstract Handles a post-change power interest notification from the network controller. @discussion The <code>controllerDidChangePowerState()</code> method is called by this handler. Subclasses are not expected to override this method. @param flags Flags that describe the capability of the controller in the new power state. @param stateNumber An index to a state in the network controller's power state array that the controller has switched to. @param policyMaker A reference to the network controller's policy-maker, and is also the originator of this notification. @result Returns <code>IOPMAckImplied</code> to indicate synchronous completion. */ virtual IOReturn powerStateDidChangeTo( IOPMPowerFlags flags, unsigned long stateNumber, IOService * policyMaker ) APPLE_KEXT_OVERRIDE; /*! @function controllerWillChangePowerState @abstract Handles a notification that the network controller servicing this interface object will transition to a new power state. @param controller The network controller object. @param flags Flags that describe the capability of the controller in the new power state. @param stateNumber An index to a state in the network controller's power state array that the controller is switching to. @param policyMaker A reference to the network controller's policy-maker, and is also the originator of this notification. @result The return value is always <code>kIOReturnSuccess</code>. */ virtual IOReturn controllerWillChangePowerState( IONetworkController * controller, IOPMPowerFlags flags, UInt32 stateNumber, IOService * policyMaker ); /*! @function controllerDidChangePowerState @abstract Handles a notification that the network controller servicing this interface object has transitioned to a new power state. @param controller The network controller object. @param flags Flags that describe the capability of the controller in the new power state. @param stateNumber An index to a state in the network controller's power state array that the controller has switched to. @param policyMaker A reference to the network controller's policy-maker, and is also the originator of this notification. @result The return value is always <code>kIOReturnSuccess</code>. */ virtual IOReturn controllerDidChangePowerState( IONetworkController * controller, IOPMPowerFlags flags, UInt32 stateNumber, IOService * policyMaker ); public: /* Override IOService::willTerminate() */ virtual bool willTerminate( IOService * provider, IOOptionBits options ) APPLE_KEXT_OVERRIDE; /* Override IOService::requestTerminate() */ virtual bool requestTerminate( IOService * provider, IOOptionBits options ) APPLE_KEXT_OVERRIDE; /* Override IOService::serializeProperties() */ virtual bool serializeProperties( OSSerialize * s ) const APPLE_KEXT_OVERRIDE; /*! @function attachToDataLinkLayer @abstract Attach the network interface to the BSD data link layer. @discussion This method is called internally to attach the network interface to the BSD data link layer, after an unit number has been assigned. The calling context is not synchronized against the driver's work loop. Subclasses may override this method to perform additional setup before the network stack attach. The <code>getIfnet()</code> method will return the BSD interface being attached. @param options Options for the attach call. None are currently defined. @param parameter Parameter for the attach call. Not currently used. @result Returns <code>kIOReturnSuccess</code> on success. */ virtual IOReturn attachToDataLinkLayer( IOOptionBits options, void * parameter ); OSMetaClassDeclareReservedUsed(IONetworkInterface, 0); /*! @function detachFromDataLinkLayer @abstract Detach the network interface from the BSD data link layer. @discussion This method is called internally to detach the network interface from the BSD data link layer, after the interface has been terminated and before the last client close. This method will block until the detach operation is complete. The calling context is not synchronized against the driver's work loop. Subclasses may override this method to perform additional cleanup before or after detaching from the network stack. The <code>getIfnet()</code> method will return NULL after detach. @param options Options for the detach call. None are currently defined. @param parameter Parameter for the detach call. Not currently used. */ virtual void detachFromDataLinkLayer( IOOptionBits options, void * parameter ); OSMetaClassDeclareReservedUsed(IONetworkInterface, 1); protected: /*! @function feedPacketInputTap @abstract Feed received packets to the BPF @discussion This function is called internally to send input packets to the BPF input tap when it is enabled. Subclasses are not expected to override this method. @param mbuf_t Pointer to the input packet. */ virtual void feedPacketInputTap( mbuf_t ); OSMetaClassDeclareReservedUsed(IONetworkInterface, 2); /*! @function feedPacketOutputTap @abstract Feed output packets to the BPF @discussion This function is called internally to send output packets to the BPF output tap when it is enabled. Subclasses are not expected to override this method. @param mbuf_t Pointer to the output packet. */ virtual void feedPacketOutputTap( mbuf_t ); OSMetaClassDeclareReservedUsed(IONetworkInterface, 3); /*! @function initIfnetParams @abstract Allows a subclass to provide ifnet initialization parameters specific to an interface type. @discussion This method initializes the parameters that are common to all network interfaces. An interface subclass is expected to override this method, call the superclass implementation first, then initialize the parameters specific to that interface type. This method is called after an unit number has been assigned to the interface, and just before the interface is attached to BSD. @param params Pointer to an <code>ifnet_init_params</code> allocated by the caller. @result Returns <code>true</code> on success, <code>false</code> otherwise. */ virtual bool initIfnetParams( struct ifnet_init_params * params ); OSMetaClassDeclareReservedUsed(IONetworkInterface, 4); /*! @function configureOutputStartDelay @abstract Configure the output start delay @discussion This optional routine, if used, needs to be called after IONetworkInterface::init() and before IONetworkInterface::attachToDataLinkLayer(). This allows for over-riding ifnet_init_eparams.start_delay_qlen and ifnet_init_eparams.start_delay_timeout. @param outputStartDelayQueueLength, maps to ifnet_init_eparams.start_delay_qlen @param outputStartDelayTimeout, maps to ifnet_init_eparams.start_delay_timeout @result <code>kIOReturnSuccess</code> if interface was successfully configured. */ IOReturn configureOutputStartDelay( uint16_t outputStartDelayQueueLength, uint16_t outputStartDelayTimeout ); public: #ifdef __PRIVATE_SPI__ /*! @function setInterfaceSubType @abstract Sets the interface sub-type. @discussion The sub-type must be set before the interface is attached to the networking stack. The driver's <code>configureInterface()</code> or <code>attachToDataLinkLayer</code> in a subclass are valid call sites. @param subType A constant defined in <code>IONetworkTypesPrivate.h</code>. @result Returns <code>true</code> on success, <code>false</code> otherwise. */ bool setInterfaceSubType( uint32_t subType ); /*! @function isBPFTapEnabled @abstract Query if the BPF tap is enabled. @abstract Allows a driver to poll the BPF tap state after receiving a <code>kIONetworkNotificationBPFTapStateChange</code> notification. @param options No options are currently defined, always pass zero. @result Returns <code>true</code> if BPF tap is enabled, <code>false</code> otherwise. */ bool isBPFTapEnabled( IOOptionBits options = 0 ) const; /*! @function getLoggingLevel @abstract Query the logging level for the interface. @abstract Allows a driver to poll the logging level after receiving a <code>kIONetworkNotificationLoggingLevelChange</code> notification. @param options No options are currently defined, always pass zero. @result Returns the current logging level. */ int32_t getLoggingLevel( IOOptionBits options = 0 ) const; /*! @enum OutputPacketSchedulingModel @discussion Output packet scheduling models. @constant kOutputPacketSchedulingModelNormal The default output packet scheduling model where the driver or media does not require strict scheduling strategy, and that the networking stack is free to choose the most appropriate scheduling and queueing algorithm, including shaping traffics. @constant kOutputPacketSchedulingModelDriverManaged The alternative output packet scheduling model where the driver or media requires strict scheduling strategy (e.g. 802.11 WMM), and that the networking stack is only responsible for creating multiple queues for the corresponding service classes. @constant kOutputPacketSchedulingModelFqCodel The FQ-CoDel packet scheduling model. */ enum { kOutputPacketSchedulingModelNormal = 0, kOutputPacketSchedulingModelDriverManaged = 1, kOutputPacketSchedulingModelFqCodel = 2 }; /*! @function configureOutputPullModel @abstract Configure and use the pull-model to transmit packets. @discussion A driver that supports the pull-model to transmit packets must call this method from <code>configureInterface()</code> to configure the model, and to transition the interface to use the pull-model exclusively. In the pull-model, the interface will manage an output queue that a driver can pull packets from. An output thread will notify the driver through <code>outputStart()</code> when packets are added to the output queue. @param driverQueueSize The number of packets that the driver's transmit queue or ring can hold. This parameter is not currently used by the family, and drivers can pass zero. @param options <code>kIONetworkWorkLoopSynchronous</code> forces the output thread to call <code>outputStart()</code> on the driver's work loop context. @param outputQueueSize The size of the interface output queue. Unless the driver has special requirements, it is advisable to pass zero to let the networking stack choose the output queue size. @param outputSchedulingModel An output packet scheduling model. Pass zero or <code>kOutputPacketSchedulingModelNormal</code> for the default model which lets the network stacking choose the most appropriate scheduling and queueing algorithm. @param outputTargetQdelay Allow drivers to set the default target delay. @result <code>kIOReturnSuccess</code> if interface was successfully configured to use the pull-model for outbound packets. */ virtual IOReturn configureOutputPullModel( uint32_t driverQueueSize, IOOptionBits options = 0, uint32_t outputQueueSize = 0, uint32_t outputSchedulingModel = 0, uint32_t outputTargetQdelay = 0); OSMetaClassDeclareReservedUsed(IONetworkInterface, 5); /*! @function configureInputPacketPolling @abstract Configure and enable polling of input packets. @discussion A driver that supports polled-mode processing of input packets must call this method from <code>configureInterface()</code> to configure input polling. Once configured, the network stack is allowed to dynamically transition the input model from the default push-model where packets are pushed by the driver to the network stack, to the pull-model where a poller thread will periodically pull packets (if any) from the driver. @param driverQueueSize The number of packets that the driver's receive queue or ring can hold when completely full. @param options <code>kIONetworkWorkLoopSynchronous</code> forces the poller thread to call <code>pollInputPackets()</code> on the driver's work loop context. The <code>setInputPacketPollingEnable()</code> method call is always synchronized against the driver's work loop. @result <code>kIOReturnSuccess</code> if input polling was successfully configured. */ virtual IOReturn configureInputPacketPolling( uint32_t driverQueueSize, IOOptionBits options = 0 ); OSMetaClassDeclareReservedUsed(IONetworkInterface, 6); /*! @function reportDataTransferRates @abstract For drivers to report the current data transfer rates. @discussion The rates reported by this method will supersede the single link speed reported by <code>IONetworkController::setLinkStatus</code>. This method allows the driver to report asymmetric input and output data rates, and also the effective data rates when available. @param outputRateMax The maximum output data rate in bit/s. @param inputRateMax The maximum input data rate in bit/s. @param outputRateEffective The effective output data rate in bit/s. If zero, the outputRateMax value is passed to the network stack. @param inputRateEffective The effective input data rate in bit/s. If zero, the inputRateMax value is passed to the network stack. */ virtual void reportDataTransferRates( uint64_t outputRateMax, uint64_t inputRateMax, uint64_t outputRateEffective = 0, uint64_t inputRateEffective = 0 ); OSMetaClassDeclareReservedUsed(IONetworkInterface, 7); /*! @function stopOutputThread @abstract Called by drivers to stop the output thread. @discussion Only drivers that support the pull output model should call this method. In the stop state, the output thread will not invoke the driver's <code>outputStart()</code> method, even when new packets are added to the output queue. This method is synchronous with respect to any <code>outputStart()</code> invocation, so upon returning from this method it is guaranteed that the output thread has stopped executing driver code. The network interface will internally stop the output thread before detaching from the network stack, and also before system shutdown and restart. @param options No options are currently defined, always pass zero. @result <code>kIOReturnSuccess</code> if the thread was stopped, <code>kIOReturnTimeout</code> if the wait for output thread to exit <code>outputStart()</code> timed out. */ IOReturn stopOutputThread( IOOptionBits options = 0 ); /*! @function startOutputThread @abstract Called by drivers to start the output thread. @discussion The output thread is initially in a stop state, and it must be started before it can invoke the driver's <code>outputStart()</code> method. Drivers may also issue start to release a previous stop request. After starting the output thread, if the output queue is not empty, or after a new packet is added to the output queue, the output thread will wakeup and invoke the driver's <code>outputStart()</code> method. @param options No options are currently defined, always pass zero. @result <code>kIOReturnSuccess</code> if start was successful, <code>kIOReturnNotAttached</code> if the network interface has detached from the network stack. */ IOReturn startOutputThread( IOOptionBits options = 0 ); /*! @function signalOutputThread @abstract Informs the output thread that driver has completed packet transmission. @discussion A driver that supports the pull output model must call this method after packet transmission is complete, and driver resources are available to <code>outputStart()</code> to handle additional packets. It is recommended to batch this call when retiring a group of output packets. This method will wake up the output thread if the output queue is not empty, and the output thread is not stopped. @param options No options are currently defined, always pass zero. */ void signalOutputThread( IOOptionBits options = 0 ); /*! @function flushOutputQueue @abstract Flush all packets in the interface output queue. @discussion A driver that supports the pull output model can use this method to free all packets currently held in the interface output queue. @param options No options are currently defined, always pass zero. */ void flushOutputQueue( IOOptionBits options = 0 ); /*! @function dequeueOutputPackets @abstract Dequeue packets from the interface output queue. @discussion A driver that supports the output pull-model will typically call this method from <code>outputStart()</code> after it has calculated the maximum number of packets that can be dequeued based on available resources. Drivers should not dequeue more packets than they can accept since there is no facility to insert a packet to the head of the queue. The only recourse is to drop the packet, or store the packet on a driver managed queue which is not recommended. This method can dequeue a single packet as a mbuf chain, or multiple packets using a linked list of mbuf chains. It is also possible for the queue to not return any packet to the driver in order to throttle the transmit rate. Although typically called from <code>outputStart()</code>, this is not a mandatory requirement. E.g. a driver may choose to dequeue in the transmit completion path to quickly fill an available transmit slot. @param maxCount The maximum number of packets to dequeue. This value must be greater than zero. @param packetHead Pointer to the first packet that was dequeued. @param packetTail Optional pointer to the last packet that was dequeued. @param packetCount Optional pointer to store the number of packets that was dequeued. @param packetBytes Optional pointer to store the total length of packets that was dequeued. The length of each packet is given by <code>mbuf_pkthdr_len()</code>. @result <code>kIOReturnSuccess</code> if at least one packet was dequeued, <code>kIOReturnBadArgument</code> if an argument was invalid, <code>kIOReturnNoFrames</code> if the queue is empty, or the queue is limiting the transmit rate. */ virtual IOReturn dequeueOutputPackets( uint32_t maxCount, mbuf_t * packetHead, mbuf_t * packetTail = 0, uint32_t * packetCount = 0, uint64_t * packetBytes = 0 ); OSMetaClassDeclareReservedUsed(IONetworkInterface, 8); /*! @function dequeueOutputPacketsWithServiceClass @abstract Dequeue packets of a particular service class from the interface output queue. @discussion See <code>dequeueOutputPackets</code>. @param maxCount The maximum number of packets to dequeue. This value must be greater than zero. @param serviceClass A service class specification provided by the caller. Only packets belonging to the specified service class will be dequeued. @param packetHead Pointer to the first packet that was dequeued. @param packetTail Optional pointer to the last packet that was dequeued. @param packetCount Optional pointer to store the number of packets that was dequeued. @param packetBytes Optional pointer to store the total length of packets that was dequeued. The length of each packet is given by <code>mbuf_pkthdr_len()</code>. @result <code>kIOReturnSuccess</code> if at least one packet was dequeued, <code>kIOReturnBadArgument</code> if an argument was invalid, <code>kIOReturnNoFrames</code> if the queue is empty, no packet belongs to the service class or the queue is limiting the transmit rate. */ virtual IOReturn dequeueOutputPacketsWithServiceClass( uint32_t maxCount, IOMbufServiceClass serviceClass, mbuf_t * packetHead, mbuf_t * packetTail = 0, uint32_t * packetCount = 0, uint64_t * packetBytes = 0 ); OSMetaClassDeclareReservedUsed(IONetworkInterface, 9); /*! @function dequeueOutputPacketsWithMaxSize @abstract Dequeue packets with a byte size constraint. @discussion See <code>dequeueOutputPackets</code>. @param maxSize The maximum byte size of the dequeued packet chain. This value must be greater than zero. @param packetHead Pointer to the first packet that was dequeued. @param packetTail Optional pointer to the last packet that was dequeued. @param packetCount Optional pointer to store the number of packets that was dequeued. @param packetBytes Optional pointer to store the total length of packets that was dequeued. The length of each packet is given by <code>mbuf_pkthdr_len()</code>. */ IOReturn dequeueOutputPacketsWithMaxSize( uint32_t maxSize, mbuf_t * packetHead, mbuf_t * packetTail = 0, uint32_t * packetCount = 0, uint64_t * packetBytes = 0 ); /* @function installOutputPreEnqueueHandler @abstract Install a handler to intercept all output packets before they are added to the output queue. @discussion A single handler can be installed before the interface is attached to the networking stack. The handler will not be invoked unless the driver configures the interface to utilize the new output pull-model. @param handler A C-function handler. @target A reference passed to the handler. @refCon A reference constant passed to the handler. @result <code>kIOReturnSuccess</code> if the handler was successfully installed, <code>kIOReturnBadArgument</code> if the handler provided was NULL, or <code>kIOReturnError</code> if the call was made after the interface has already attached to the networking stack. */ IOReturn installOutputPreEnqueueHandler( OutputPreEnqueueHandler handler, void * target, void * refCon ); /* @function enqueueOutputPacket @abstract Enqueue a packet to the output queue. @discussion Wrapper for the private <code>ifnet_enqueue()</code>. @param packet The packet being enqueued; only one packet is allowed to be enqueued at a time. @param options No options are currently defined, always pass zero. @result The value returned by <code>ifnet_enqueue()</code>. */ errno_t enqueueOutputPacket( mbuf_t packet, IOOptionBits options = 0 ); /*! @function enqueueInputPacket @abstract Queue a packet received by the driver before forwarding it to the networking stack. @discussion When input polling is not enabled, drivers should call this method to queue each received packet on the interface input queue, then flush the input queue at the end of the driver receive loop. When this method is called as a result of input polling, driver must specify the polling queue by passing the queue provided by the poller. Access to the interface input queue is unsynchronized, since input packet handling is expected to be single-threaded. The input packet must point to a header mbuf with <code>MBUF_PKTHDR</code> flag set, with any additional mbufs linked by the next chain. The length in the packet header, including the data length for every mbuf in the chain must be set. If FCS is included in the packet data, then the <code>MBUF_HASFCS</code> mbuf flag must be set. This is the preferred interface to queue and submit an input packet, and is functionally equivalent to calling <code>inputPacket</code> with the <code>kInputOptionQueuePacket</code> option. Submitting a chain of packets is not supported. @param packet The input packet. Caller ceases ownership of the packet regardless of the return value. @param queue Defaults to zero which specifies the interface input queue. To handoff a packet during input polling, pass the queue provided by the poller. @param options No options are currently defined, always pass zero. @result <code>kIOReturnSuccess</code> if packet was added to the queue, or an error code otherwise. */ virtual IOReturn enqueueInputPacket( mbuf_t packet, IOMbufQueue * queue = 0, IOOptionBits options = 0 ); OSMetaClassDeclareReservedUsed(IONetworkInterface, 10); /*! @function reportTransmitCompletionStatus @abstract Report the transmit completion status for an outgoing packet. @discussion Invoked by drivers that are capable of reporting when a packet has been transmitted across the link layer. Besides reporting the packet transmit status using this method, driver must also publish the <code>kIONetworkFeatureTransmitCompletionStatus</code> feature. @param packet The packet that was transmitted. @param status The transmit status. @param param1 Always pass zero. @param param2 Always pass zero. @param No options are currently defined, always pass zero. @result <code>kIOReturnSuccess</code> if the transmit status was valid and accepted, otherwise <code>kIOReturnBadArgument</code> for bad status, or <code>kIOReturnError</code> if an error occurred when passing the status to the networking stack. */ IOReturn reportTransmitCompletionStatus( mbuf_t packet, IOReturn status, uint32_t param1 = 0, uint32_t param2 = 0, IOOptionBits options = 0 ); /*! @function reportDatapathIssue @abstract Used by kernel network driver or family to inform userspace of a datapath issue. @discussion An issue report will be sent to any userspace applications or daemons that have registered for datapath issues notifications from this network interface. @param issue Subsystem specific error code. @param data Reserved for future use. @param length Reserved for future use. @result Returns <code>kIOReturnSuccess</code> if successful, otherwise an appropriate error code. */ IOReturn reportDatapathIssue( IOReturn issue, void * data = 0, IOByteCount length = 0 ); /*! @function setPacketPollingParameters @abstract Modify the input polling parameters. @discussion Invokes <code>ifnet_set_poll_params()</code> using the parameters provided. @param params Polling parameters. @param options No options are currently defined, always pass zero. @result Returns <code>kIOReturnSuccess</code> if successful, otherwise an appropriate error code. */ IOReturn setPacketPollingParameters( const IONetworkPacketPollingParameters * params, IOOptionBits options = 0 ); /*! @function configureClientBehavior @abstract Configure client behavior. @discussion Invoked by drivers that wish to alter IONetworkInterface's behavior. @param options set <code>kIONetworkClientBehaviorLinkStateActiveRegister</code> to have IONetworkInterface trigger matching when link state goes to active. set <code>kIONetworkClientBehaviorLinkStateChangeMessage</code> to have IONetworkInterface deliver an IOKit message when link state changes. @result Returns <code>kIOReturnSuccess</code> if successful, otherwise an appropriate error code. */ IOReturn configureClientBehavior( IOOptionBits options = 0 ); #else /* !__PRIVATE_SPI__ */ OSMetaClassDeclareReservedUnused( IONetworkInterface, 5); OSMetaClassDeclareReservedUnused( IONetworkInterface, 6); OSMetaClassDeclareReservedUnused( IONetworkInterface, 7); OSMetaClassDeclareReservedUnused( IONetworkInterface, 8); OSMetaClassDeclareReservedUnused( IONetworkInterface, 9); OSMetaClassDeclareReservedUnused( IONetworkInterface, 10); #endif /* !__PRIVATE_SPI__ */ OSMetaClassDeclareReservedUnused( IONetworkInterface, 11); OSMetaClassDeclareReservedUnused( IONetworkInterface, 12); OSMetaClassDeclareReservedUnused( IONetworkInterface, 13); OSMetaClassDeclareReservedUnused( IONetworkInterface, 14); OSMetaClassDeclareReservedUnused( IONetworkInterface, 15); }; #endif /* __cplusplus */ #endif /* KERNEL */ #endif /* !_IONETWORKINTERFACE_H */