1/*
2 * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * The contents of this file constitute Original Code as defined in and
7 * are subject to the Apple Public Source License Version 1.1 (the
8 * "License").  You may not use this file except in compliance with the
9 * License.  Please obtain a copy of the License at
10 * http://www.apple.com/publicsource and read it before using this file.
11 *
12 * This Original Code and all software distributed under the License are
13 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
14 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
15 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
17 * License for the specific language governing rights and limitations
18 * under the License.
19 *
20 * @APPLE_LICENSE_HEADER_END@
21 */
22/*
23 * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved.
24 *
25 * IOFWController.h
26 *
27 */
28
29#ifndef _IOFWCONTROLLER_H
30#define _IOFWCONTROLLER_H
31
32#include <IOKit/network/IONetworkController.h>
33
34/*! @defined kIOFWControllerClass
35    @abstract kIOFWControllerClass is the name of the
36        IOFWController class. */
37
38#define kIOFWControllerClass        "IOFWController"
39
40/*! @defined kIOFWAddressSize
41    @abstract The number of bytes in an FireWire hardware address. */
42
43#define kIOFWAddressSize            8
44
45/*! @defined kIOFWMaxPacketSize
46    @abstract The maximum size of an FireWire packet, including
47        the FCS bytes. */
48
49#define kIOFWMaxPacketSize          4096
50
51/*! @defined kIOFWMinPacketSize
52    @abstract The minimum size of an FireWire packet, including
53        the FCS bytes. */
54
55#define kIOFWMinPacketSize     64
56
57/*! @defined kIOFWCRCSize
58    @abstract The size in bytes of the 32-bit CRC value appended
59        to the end of each FireWire frame. */
60
61#define kIOFWCRCSize                0
62
63/*! @defined kIOFWWakeOnLANFilterGroup
64    @abstract kIOFWWakeOnLANFilterGroup describes the name assigned
65        to the FireWire wake-On-LAN filter group. */
66
67#define kIOFWWakeOnLANFilterGroup   "IOFWWakeOnLANFilterGroup"
68
69/*! @enum Enumeration of wake-On-LAN filters.
70    @discussion An enumeration of all filters in the wake-on-LAN filter
71        group. Each filter listed will respond to a network event that
72        will trigger a system wake-up.
73    @constant kIOFWWakeOnMagicPacket Reception of a Magic Packet.
74    @constant kIOFWWakeOnPacketAddressMatch Reception of a packet
75    which passes through any of the address filtering mechanisms based
76    on its destination FireWire address. This may include unicast,
77    broadcast, or multicast addresses depending on the current state
78    and setting of the corresponding packet filters. */
79
80enum {
81    kIOFWWakeOnMagicPacket         = 0x00000001,
82    kIOFWWakeOnPacketAddressMatch  = 0x00000002
83};
84
85/*
86 * Kernel
87 */
88#if defined(KERNEL) && defined(__cplusplus)
89
90struct IOFWAddress {
91	UInt8 bytes[kIOFWAddressSize];
92};
93
94/*!	@defined gIOEthernetWakeOnLANFilterGroup
95    @discussion gIOEthernetWakeOnLANFilterGroup is an OSSymbol object
96        that contains the name of the FireWire wake-on-LAN filter group
97        defined by kIOFWWakeOnLANFilterGroup. */
98
99extern const OSSymbol * gIOEthernetWakeOnLANFilterGroup;
100
101/*! @class IOFWController : public IONetworkController
102    @abstract An abstract superclass for FireWire controllers. FireWire
103    controller drivers should subclass IOFWController, and implement
104    or override the hardware specific methods to create an FireWire driver.
105    An interface object (an IOFWInterface instance) must be
106    instantiated by the driver, through attachInterface(), to connect
107    the controller driver to the data link layer. */
108
109class IOFWController : public IONetworkController
110{
111    OSDeclareDefaultStructors( IOFWController )
112
113protected:
114    struct ExpansionData { };
115    /*! @var reserved
116        Reserved for future use.  (Internal use only)  */
117    ExpansionData *  _reserved;
118
119
120public:
121
122/*! @function initialize
123    @abstract IOFWController class initializer.
124    @discussion Create global OSSymbol objects that are used as keys. */
125
126    static void initialize();
127
128/*! @function init
129    @abstract Initialize an IOFWController object.
130    @param properties A dictionary object containing a property table
131        associated with this instance.
132    @result true on success, false otherwise. */
133
134    virtual bool init(OSDictionary * properties);
135
136/*! @function getPacketFilters
137    @abstract Get the set of packet filters supported by the FireWire
138    controller in the given filter group.
139    @discussion The default implementation of the abstract method inherited
140    from IONetworkController. When the filter group specified is
141    gIONetworkFilterGroup, then this method will return a value formed by
142    a bitwise OR of kIOPacketFilterUnicast, kIOPacketFilterBroadcast,
143    kIOPacketFilterMulticast, kIOPacketFilterPromiscuous. Otherwise, the
144    return value will be set to zero (0). Subclasses must override this
145    method if their filtering capability differs from what is reported by
146    this default implementation. This method is called from the workloop
147    context, and the result is published to the I/O Kit registry.
148    @param group The name of the filter group.
149    @param filters Pointer to the mask of supported filters returned by
150    	this method.
151    @result kIOReturnSuccess. Drivers that override this
152    method must return kIOReturnSuccess to indicate success, or an error
153    return code otherwise. */
154
155    virtual IOReturn getPacketFilters(const OSSymbol * group,
156                                      UInt32 *         filters) const;
157
158/*! @function enablePacketFilter
159    @abstract Enable one of the supported packet filters from the
160    given filter group.
161    @discussion The default implementation of the abstract method inherited
162    from IONetworkController. This method will call setMulticastMode() or
163    setPromiscuousMode() when the multicast or the promiscuous filter is to be
164    enabled. Requests to disable the Unicast or Broadcast filters are handled
165    silently, without informing the subclass. Subclasses can override this
166    method to change this default behavior, or to extend it to handle
167    additional filter types or filter groups. This method call is synchronized
168    by the workloop's gate.
169    @param group The name of the filter group containing the filter to be
170    enabled.
171    @param aFilter The filter to enable.
172    @param enabledFilters All filters currently enabled by the client.
173    @param options Optional flags for the enable request.
174    @result The return from setMulticastMode() or setPromiscuousMode() if
175    either of those two methods are called. kIOReturnSuccess if the filter
176    specified is kIOPacketFilterUnicast or kIOPacketFilterBroadcast.
177    kIOReturnUnsupported if the filter group specified is not
178    gIONetworkFilterGroup. */
179
180    virtual IOReturn enablePacketFilter(const OSSymbol * group,
181                                        UInt32           aFilter,
182                                        UInt32           enabledFilters,
183                                        IOOptionBits     options = 0);
184
185/*! @function disablePacketFilter
186    @abstract Disable a packet filter that is currently enabled from the
187    given filter group.
188    @discussion The default implementation of the abstract method inherited
189    from IONetworkController. This method will call setMulticastMode() or
190    setPromiscuousMode() when the multicast or the promiscuous filter is to be
191    disabled. Requests to disable the Unicast or Broadcast filters are handled
192    silently, without informing the subclass. Subclasses can override this
193    method to change this default behavior, or to extend it to handle
194    additional filter types or filter groups. This method call is synchronized
195    by the workloop's gate.
196    @param group The name of the filter group containing the filter to be
197    disabled.
198    @param aFilter The filter to disable.
199    @param enabledFilters All filters currently enabled by the client.
200    @param options Optional flags for the disable request.
201    @result The return from setMulticastMode() or setPromiscuousMode() if
202    either of those two methods are called. kIOReturnSuccess if the filter
203    specified is kIOPacketFilterUnicast or kIOPacketFilterBroadcast.
204    kIOReturnUnsupported if the filter group specified is not
205    gIONetworkFilterGroup. */
206
207    virtual IOReturn disablePacketFilter(const OSSymbol * group,
208                                         UInt32           aFilter,
209                                         UInt32           enabledFilters,
210                                         IOOptionBits     options = 0);
211
212/*! @function getHardwareAddress
213    @abstract Get the FireWire controller's station address.
214    @discussion The default implementation of the abstract method inherited
215    from IONetworkController. This method will call the overloaded form
216    IOFWController::getHardwareAddress() that subclasses are expected
217    to override.
218    @param addr The buffer where the controller's hardware address should
219           be written.
220    @param inOutAddrBytes The size of the address buffer provided by the
221           client, and replaced by this method with the actual size of
222           the hardware address in bytes.
223    @result kIOReturnSuccess on success, or an error otherwise. */
224
225    virtual IOReturn getHardwareAddress(void *   addr,
226                                        UInt32 * inOutAddrBytes);
227
228/*! @function setHardwareAddress
229    @abstract Set or change the station address used by the FireWire
230    controller.
231    @discussion The default implementation of the abstract method inherited
232    from IONetworkController. This method will call the overloaded form
233    IOFWController::setHardwareAddress() that subclasses are expected
234    to override.
235    @param addr The buffer containing the hardware address provided by
236    the client.
237    @param addrBytes The size of the address buffer provided by the
238    client in bytes.
239    @result kIOReturnSuccess on success, or an error otherwise. */
240
241    virtual IOReturn setHardwareAddress(const void * addr,
242                                        UInt32       addrBytes);
243
244/*! @function getMaxPacketSize
245    @abstract Get the maximum packet size supported by the FireWire
246        controller, including the frame header and FCS.
247    @param maxSize Pointer to the return value.
248    @result kIOReturnSuccess on success, or an error code otherwise. */
249
250    virtual IOReturn getMaxPacketSize(UInt32 * maxSize) const;
251
252/*! @function getMinPacketSize
253    @abstract Get the minimum packet size supported by the FireWire
254        controller, including the frame header and FCS.
255    @param minSize Pointer to the return value.
256    @result kIOReturnSuccess on success, or an error code otherwise. */
257
258    virtual IOReturn getMinPacketSize(UInt32 * minSize) const;
259
260/*! @function getPacketFilters
261    @abstract Get the set of packet filters supported by the FireWire
262    controller in the network filter group.
263    @param filters Pointer to the return value containing a mask of
264    supported filters.
265    @result kIOReturnSuccess. Drivers that override this
266    method must return kIOReturnSuccess to indicate success, or an error
267    return code otherwise. */
268
269    virtual IOReturn getPacketFilters(UInt32 * filters) const;
270
271/*! @function getHardwareAddress
272    @abstract Get the FireWire controller's permanent station address.
273    @discussion. FireWire drivers must implement this method, by reading the
274    address from hardware and writing it to the buffer provided. This method
275    is called from the workloop context.
276    @param addrP Pointer to an IOFWAddress where the hardware address
277    should be returned.
278    @result kIOReturnSuccess on success, or an error return code otherwise. */
279
280    virtual IOReturn getHardwareAddress(IOFWAddress * addrP);
281
282/*! @function setHardwareAddress
283    @abstract Set or change the station address used by the FireWire
284        controller.
285    @discussion This method is called in response to a client command to
286    change the station address used by the FireWire controller. Implementation
287    of this method is optional. This method is called from the workloop context.
288    @param addrP Pointer to an IOFWAddress containing the new station
289    address.
290    @result The default implementation will always return kIOReturnUnsupported.
291    If overridden, drivers must return kIOReturnSuccess on success, or an error
292    return code otherwise. */
293
294    virtual IOReturn setHardwareAddress(const IOFWAddress * addrP);
295
296/*! @function setMulticastMode
297    @abstract Enable or disable multicast mode.
298    @discussion Called by enablePacketFilter() or disablePacketFilter()
299    when there is a change in the activation state of the multicast filter
300    identified by kIOPacketFilterMulticast. This method is called from the
301    workloop context.
302    @param active True to enable multicast mode, false to disable it.
303    @result kIOReturnUnsupported. If overridden, drivers must return
304    kIOReturnSuccess on success, or an error return code otherwise. */
305
306    virtual IOReturn setMulticastMode(bool active);
307
308/*! @function setMulticastList
309    @abstract Set the list of multicast addresses that the multicast filter
310    should use to match against the destination address of an incoming frame.
311    The frame should be accepted when a match occurs.
312    @discussion Called when the multicast group membership of an interface
313    object is changed. Drivers that support kIOPacketFilterMulticast should
314    override this method and update the hardware multicast filter using the
315    list of FireWire addresses provided. Perfect multicast filtering is
316    preferred if supported by the hardware, to order to reduce the number of
317    unwanted packets received. If the number of multicast addresses in the
318    list exceeds what the hardware is capable of supporting, or if perfect
319    filtering is not supported, then ideally the hardware should be programmed
320    to perform imperfect filtering, thorugh some form of hash filtering
321    mechanism. Only at the last resort should the driver enable reception of
322    all multicast packets to satisfy this request. This method is called
323    from the workloop context, and only if the driver reports
324    kIOPacketFilterMulticast support in getPacketFilters().
325    @param addrs An array of FireWire addresses. This argument must be
326        ignored if the count argument is 0.
327    @param count The number of FireWire addresses in the list. This value
328        will be zero when the list becomes empty.
329    @result kIOReturnUnsupported. Drivers must return kIOReturnSuccess to
330    indicate success, or an error return code otherwise. */
331
332    virtual IOReturn setMulticastList(IOFWAddress * addrs,
333                                      UInt32              count);
334
335/*! @function setPromiscuousMode
336    @abstract Enable or disable promiscuous mode.
337    @discussion Called by enablePacketFilter() or disablePacketFilter()
338    when there is a change in the activation state of the promiscuous
339    filter identified by kIOPacketFilterPromiscuous. This method is
340    called from the workloop context.
341    @param active True to enable promiscuous mode, false to disable it.
342    @result kIOReturnUnsupported. If overridden, drivers must return
343    kIOReturnSuccess on success, or an error return code otherwise. */
344
345    virtual IOReturn setPromiscuousMode(bool active);
346
347/*! @function setWakeOnMagicPacket
348    @abstract Enable or disable the wake on Magic Packet support.
349    @discussion Called by enablePacketFilter() or disablePacketFilter()
350    when there is a change in the activation state of the wake-on-LAN
351    filter identified by kIOFWWakeOnMagicPacket. This method is
352    called from the workloop context.
353    @param active True to enable support for system wake on reception
354    of a Magic Packet, false to disable it.
355    @result kIOReturnUnsupported. If overridden, drivers must return
356    kIOReturnSuccess on success, or an error return code otherwise. */
357
358    virtual IOReturn setWakeOnMagicPacket(bool active);
359
360protected:
361
362/*! @function createInterface
363    @abstract Create an IOFWInterface object.
364    @discussion Allocate and return a new IOFWInterface instance.
365    A subclass of IONetworkController must implement this method and return
366    a matching interface object. The implementation in IOFWController
367    will return an IOFWInterface object. Subclasses of
368    IOFWController, such as FireWire controller drivers, will have
369    little reason to override this implementation.
370    @result A newly allocated and initialized IOFWInterface object. */
371
372    virtual IONetworkInterface * createInterface();
373
374/*! @function free
375    @abstract Free the IOFWController instance. Release resources,
376    then followed by a call to super::free(). */
377
378    virtual void free();
379
380/*! @function publishProperties
381    @abstract Publish FireWire controller properties and capabilities.
382    @discussion Publish FireWire controller properties to the property
383    table. For instance, getHardwareAddress() is called to fetch the
384    hardware address, and the address is then published to the property
385    table. This method call is synchronized by the workloop's gate,
386    and must never be called directly by subclasses.
387    @result true if all properties and capabilities were discovered,
388    and published successfully, false otherwise. Returning false will
389    prevent client objects from attaching to the FireWire controller
390    since a property that a client relies upon may be missing. */
391
392    virtual bool publishProperties();
393
394    // Virtual function padding
395    OSMetaClassDeclareReservedUnused( IOFWController,  0);
396    OSMetaClassDeclareReservedUnused( IOFWController,  1);
397    OSMetaClassDeclareReservedUnused( IOFWController,  2);
398    OSMetaClassDeclareReservedUnused( IOFWController,  3);
399    OSMetaClassDeclareReservedUnused( IOFWController,  4);
400    OSMetaClassDeclareReservedUnused( IOFWController,  5);
401    OSMetaClassDeclareReservedUnused( IOFWController,  6);
402    OSMetaClassDeclareReservedUnused( IOFWController,  7);
403    OSMetaClassDeclareReservedUnused( IOFWController,  8);
404    OSMetaClassDeclareReservedUnused( IOFWController,  9);
405    OSMetaClassDeclareReservedUnused( IOFWController, 10);
406    OSMetaClassDeclareReservedUnused( IOFWController, 11);
407    OSMetaClassDeclareReservedUnused( IOFWController, 12);
408    OSMetaClassDeclareReservedUnused( IOFWController, 13);
409    OSMetaClassDeclareReservedUnused( IOFWController, 14);
410    OSMetaClassDeclareReservedUnused( IOFWController, 15);
411    OSMetaClassDeclareReservedUnused( IOFWController, 16);
412    OSMetaClassDeclareReservedUnused( IOFWController, 17);
413    OSMetaClassDeclareReservedUnused( IOFWController, 18);
414    OSMetaClassDeclareReservedUnused( IOFWController, 19);
415    OSMetaClassDeclareReservedUnused( IOFWController, 20);
416    OSMetaClassDeclareReservedUnused( IOFWController, 21);
417    OSMetaClassDeclareReservedUnused( IOFWController, 22);
418    OSMetaClassDeclareReservedUnused( IOFWController, 23);
419    OSMetaClassDeclareReservedUnused( IOFWController, 24);
420    OSMetaClassDeclareReservedUnused( IOFWController, 25);
421    OSMetaClassDeclareReservedUnused( IOFWController, 26);
422    OSMetaClassDeclareReservedUnused( IOFWController, 27);
423    OSMetaClassDeclareReservedUnused( IOFWController, 28);
424    OSMetaClassDeclareReservedUnused( IOFWController, 29);
425    OSMetaClassDeclareReservedUnused( IOFWController, 30);
426    OSMetaClassDeclareReservedUnused( IOFWController, 31);
427};
428
429/*
430 * FIXME: remove this.
431 */
432enum {
433    kIOEnetPromiscuousModeOff   = false,
434    kIOEnetPromiscuousModeOn    = true,
435    kIOEnetPromiscuousModeAll   = true,
436    kIOEnetMulticastModeOff     = false,
437    kIOEnetMulticastModeFilter  = true
438};
439typedef bool IOEnetPromiscuousMode;
440typedef bool IOEnetMulticastMode;
441
442#endif /* defined(KERNEL) && defined(__cplusplus) */
443
444#endif /* !_IOFWCONTROLLER_H */
445