1/*
2 * Copyright (c) 1998-2008 Apple 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#ifndef _IONETWORKMEDIUM_H
24#define _IONETWORKMEDIUM_H
25
26__BEGIN_DECLS
27
28#include <net/if_media.h>
29
30/*! @typedef IOMediumType
31    @discussion A 32-bit value divided into fields which describes
32    a single medium type. */
33
34typedef UInt32 IOMediumType;
35
36/*! @defined kIOMediumType
37    @abstract A property of IONetworkMedium objects.
38    @discussion The kIOMediumType property is an OSNumber object that describes the type of
39        medium that this object represents.
40*/
41
42#define kIOMediumType           "Type"
43
44/*! @defined kIOMediumFlags
45    @abstract A property of IONetworkMedium objects.
46    @discussion The kIOMediumFlags property is an OSNumber object that describes a set of
47        attributes assigned to the medium.
48*/
49
50#define kIOMediumFlags          "Flags"
51
52/*! @defined kIOMediumSpeed
53    @abstract A property of IONetworkMedium objects.
54    @discussion The kIOMediumSpeed property is an OSNumber object that describes the maximum link
55        speed supported by the medium in bits per second.
56*/
57
58#define kIOMediumSpeed          "Speed"
59
60/*! @defined kIOMediumIndex
61    @abstract A property of IONetworkMedium objects.
62    @discussion The kIOMediumIndex property is an OSNumber object that describes an index assigned
63        by the owner of the medium object. Its interpretation is driver
64        specific.
65*/
66
67#define kIOMediumIndex          "Index"
68
69//===========================================================================
70// Medium Type (IOMediumType).
71//
72// The medium type is encoded by a 32-bit value. The definitions of
73// the fields and the encoding for each field is adapted from FreeBSD.
74//
75// Bits     Definition
76// -------------------
77//  4-0     medium subtype
78//  7-5     network type
79// 15-8     network specific options
80// 19-16    reserved
81// 27-20    common options
82// 31-28    instance number
83
84// Ethernet.
85//
86enum {
87    kIOMediumEthernet             =  IFM_ETHER,
88    kIOMediumEthernetAuto         =  ( IFM_AUTO    | IFM_ETHER ),
89    kIOMediumEthernetManual       =  ( IFM_MANUAL  | IFM_ETHER ),
90    kIOMediumEthernetNone         =  ( IFM_NONE    | IFM_ETHER ),
91    kIOMediumEthernet10BaseT      =  ( IFM_10_T    | IFM_ETHER ),
92    kIOMediumEthernet10Base2      =  ( IFM_10_2    | IFM_ETHER ),
93    kIOMediumEthernet10Base5      =  ( IFM_10_5    | IFM_ETHER ),
94    kIOMediumEthernet100BaseTX    =  ( IFM_100_TX  | IFM_ETHER ),
95    kIOMediumEthernet100BaseFX    =  ( IFM_100_FX  | IFM_ETHER ),
96    kIOMediumEthernet100BaseT4    =  ( IFM_100_T4  | IFM_ETHER ),
97    kIOMediumEthernet100BaseVG    =  ( IFM_100_VG  | IFM_ETHER ),
98    kIOMediumEthernet100BaseT2    =  ( IFM_100_T2  | IFM_ETHER ),
99    kIOMediumEthernet1000BaseSX   =  ( IFM_1000_SX | IFM_ETHER ),
100    kIOMediumEthernet10BaseSTP    =  ( IFM_10_STP  | IFM_ETHER ),
101    kIOMediumEthernet10BaseFL     =  ( IFM_10_FL   | IFM_ETHER ),
102    kIOMediumEthernet1000BaseLX   =  ( IFM_1000_LX | IFM_ETHER ),
103    kIOMediumEthernet1000BaseCX   =  ( IFM_1000_CX | IFM_ETHER ),
104    kIOMediumEthernet1000BaseTX   =  ( IFM_1000_T  | IFM_ETHER ), //deprecated- use kIOMediumEthernet1000BaseT instead
105    kIOMediumEthernet1000BaseT    =  ( IFM_1000_T  | IFM_ETHER ),
106    kIOMediumEthernetHomePNA1     =  ( IFM_HPNA_1  | IFM_ETHER ),
107	kIOMediumEthernet10GBaseSR    =  ( IFM_10G_SR  | IFM_ETHER ),
108	kIOMediumEthernet10GBaseLR    =  ( IFM_10G_LR  | IFM_ETHER ),
109    kIOMediumEthernet10GBaseCX4   =  ( IFM_10G_CX4 | IFM_ETHER ),
110    kIOMediumEthernet10GBaseT     =  ( IFM_10G_T   | IFM_ETHER )
111};
112
113// IEEE 802.11 Wireless.
114//
115enum {
116    kIOMediumIEEE80211            =  IFM_IEEE80211,
117    kIOMediumIEEE80211Auto        =  ( IFM_AUTO           | IFM_IEEE80211 ),
118    kIOMediumIEEE80211Manual      =  ( IFM_MANUAL         | IFM_IEEE80211 ),
119    kIOMediumIEEE80211None        =  ( IFM_NONE           | IFM_IEEE80211 ),
120    kIOMediumIEEE80211FH1         =  ( IFM_IEEE80211_FH1  | IFM_IEEE80211 ),
121    kIOMediumIEEE80211FH2         =  ( IFM_IEEE80211_FH2  | IFM_IEEE80211 ),
122    kIOMediumIEEE80211DS2         =  ( IFM_IEEE80211_DS2  | IFM_IEEE80211 ),
123    kIOMediumIEEE80211DS5         =  ( IFM_IEEE80211_DS5  | IFM_IEEE80211 ),
124    kIOMediumIEEE80211DS11        =  ( IFM_IEEE80211_DS11 | IFM_IEEE80211 ),
125    kIOMediumIEEE80211DS1         =  ( IFM_IEEE80211_DS1  | IFM_IEEE80211 ),
126    kIOMediumIEEE80211OptionAdhoc =  IFM_IEEE80211_ADHOC
127};
128
129// Common options.
130//
131enum {
132    kIOMediumOptionFullDuplex     = IFM_FDX,
133    kIOMediumOptionHalfDuplex     = IFM_HDX,
134    kIOMediumOptionFlowControl    = IFM_FLOW,
135    kIOMediumOptionEEE            = IFM_EEE,
136    kIOMediumOptionFlag0          = IFM_FLAG0,
137    kIOMediumOptionFlag1          = IFM_FLAG1,
138    kIOMediumOptionFlag2          = IFM_FLAG2,
139    kIOMediumOptionLoopback       = IFM_LOOP
140};
141
142// Medium type masks.
143//
144#define kIOMediumSubTypeMask        IFM_TMASK
145#define kIOMediumNetworkTypeMask    IFM_NMASK
146#define kIOMediumOptionsMask        IFM_OMASK
147#define kIOMediumCommonOptionsMask  IFM_GMASK
148#define kIOMediumInstanceShift      IFM_ISHIFT
149#define kIOMediumInstanceMask       IFM_IMASK
150
151// Medium type field accessors.
152//
153#define IOMediumGetSubType(x)       ((x)  & kIOMediumSubTypeMask)
154#define IOMediumGetNetworkType(x)   ((x)  & kIOMediumNetworkTypeMask)
155#define IOMediumGetInstance(x)      (((x) & kIOMediumInstanceMask) >> \
156                                            kIOMediumInstanceShift)
157
158//===========================================================================
159// Medium flags.
160
161
162//===========================================================================
163// Link status bits.
164//
165enum {
166    kIONetworkLinkValid           = IFM_AVALID,     // link status is valid
167    kIONetworkLinkActive          = IFM_ACTIVE,     // link is up/active.
168    kIONetworkLinkNoNetworkChange = IFM_WAKESAMENET
169};
170
171__END_DECLS
172
173#ifdef KERNEL
174//===========================================================================
175// IONetworkMedium class.
176
177#include <libkern/c++/OSObject.h>
178#include <libkern/c++/OSSymbol.h>
179
180/*! @class IONetworkMedium
181    @abstract An object that encapsulates information about a network
182    medium (i.e. 10Base-T, or 100Base-T Full Duplex).
183    @discussion The main purpose of
184    this object is for a network driver to advertise its media capability,
185    through a collection of IONetworkMedium objects stored in a dictionary
186    in its property table. IONetworkMedium supports serialization, and will
187    encode its properties in the form of a dictionary to the serialization
188    stream when instructed. This will allow a user-space application to
189    browse the set of media types supported by the controller.
190*/
191
192class IONetworkMedium : public OSObject
193{
194    OSDeclareDefaultStructors( IONetworkMedium )
195
196protected:
197    IOMediumType      _type;
198    UInt32            _flags;
199    UInt64            _speed;
200    UInt32            _index;
201    const OSSymbol *  _name;
202
203    struct ExpansionData { };
204    /*! @var reserved
205        Reserved for future use.  (Internal use only)  */
206    ExpansionData *_reserved;
207
208
209/*! @function free
210    @abstract Frees the IONetworkMedium object.
211*/
212
213    virtual void free();
214
215public:
216
217/*! @function nameForType
218    @abstract Creates a name that describes a medium type.
219    @discussion Given a medium type, creates an OSymbol object that
220    describes the medium type. There is a 1-to-1 mapping between the
221    medium type, and the medium name created by this method. The caller
222    is responsible for releasing the OSSymbol object returned.
223    @param type A medium type. See IONetworkMedium.h for type encoding.
224    @result Returns an OSSymbol object is created based on the type provided.
225*/
226
227    static const OSSymbol * nameForType(IOMediumType type);
228
229/*! @function addMedium
230    @abstract Adds an IONetworkMedium object to a dictionary.
231    @discussion A helper function to add an IONetworkMedium object to a
232    given dictionary. The name of the medium is used as the key for the
233    new dictionary entry.
234    @param dict An OSDictionary object where the medium object should be
235    added as a new entry.
236    @param medium The IONetworkMedium object to add to the dictionary.
237    @result Returns true on success, false otherwise.
238*/
239
240    static bool addMedium(OSDictionary *          dict,
241                          const IONetworkMedium * medium);
242
243/*! @function removeMedium
244    @abstract Removes an IONetworkMedium object from a dictionary.
245    @discussion A helper function to remove an entry in a dictionary.
246    @param dict The OSDictionary object where the medium object should be
247    removed from.
248    @param medium The name of this medium object is used as the key.
249*/
250
251    static void removeMedium(OSDictionary *          dict,
252                             const IONetworkMedium * medium);
253
254/*! @function getMediumWithType
255    @abstract Finds a medium object from a dictionary with a given type.
256    @discussion This method iterates through a dictionary and returns an IONetworkMedium
257    entry with the given type. An optional mask supplies the don't care bits.
258    @param dict The dictionary to look for a matching entry.
259    @param type Search for an entry with this type.
260    @param mask The don't care bits in IOMediumType. Defaults to 0, which
261    implies that a perfect match is desired.
262    @result Returns the first matching IONetworkMedium entry found,
263    or 0 if no match was found.
264*/
265
266    static IONetworkMedium * getMediumWithType(const OSDictionary * dict,
267                                               IOMediumType         type,
268                                               IOMediumType         mask = 0);
269
270/*! @function getMediumWithIndex
271    @abstract Finds a medium object from a dictionary with a given index.
272    @discussion This method iterates through a dictionary and returns an IONetworkMedium
273    entry with the given index. An optional mask supplies the don't care bits.
274    @param dict The dictionary to look for a matching entry.
275    @param index Search for an entry with the given index.
276    @param mask The don't care bits in index. Defaults to 0, which
277    implies that a perfect match is desired.
278    @result Returns the first matching IONetworkMedium entry found,
279    or 0 if no match was found.
280*/
281
282    static IONetworkMedium * getMediumWithIndex(const OSDictionary * dict,
283                                                UInt32               index,
284                                                UInt32               mask = 0);
285
286/*! @function init
287    @abstract Initializes an IONetworkMedium object.
288    @param type The medium type, this value is encoded with bits defined in
289           IONetworkMedium.h.
290    @param speed The maximum (or the only) link speed supported over this
291           medium in units of bits per second.
292    @param flags An optional flag for the medium object.
293           See IONetworkMedium.h for defined flags.
294    @param index An optional index number assigned by the owner.
295           Drivers can use this to store an index to a media table in
296           the driver, or it may map to a driver-defined media type.
297    @param name An optional name assigned to this medium object. If 0,
298           then a name will be created based on the medium type by
299           calling IONetworkMedium::nameForType(). Since the name of
300           the medium is used as a key when inserted into a dictionary,
301           the name chosen must be unique within the scope of the owner.
302    @result Returns true on success, false otherwise.
303*/
304
305    virtual bool init(IOMediumType  type,
306                      UInt64        speed,
307                      UInt32        flags = 0,
308                      UInt32        index = 0,
309                      const char *  name  = 0);
310
311/*! @function medium
312    @abstract Factory method that allocates and initializes an IONetworkMedium object.
313    @param type The medium type, this value is encoded with bits defined in
314           IONetworkMedium.h.
315    @param speed The maximum (or the only) link speed supported over this
316           medium in units of bits per second.
317    @param flags An optional flag for the medium object.
318           See IONetworkMedium.h for defined flags.
319    @param index An optional index number assigned by the owner.
320           Drivers can use this to store an index to a media table in
321           the driver, or it may map to a driver-defined media type.
322    @param name An optional name assigned to this medium object. If 0,
323           then a name will be created based on the medium type by
324           calling IONetworkMedium::nameForType(). Since the name of
325           the medium is used as a key when inserted into a dictionary,
326           the name chosen must be unique within the scope of the owner.
327    @result Returns an IONetworkMedium instance on success, or 0 otherwise.
328*/
329
330    static IONetworkMedium * medium(IOMediumType  type,
331                                    UInt64        speed,
332                                    UInt32        flags = 0,
333                                    UInt32        index = 0,
334                                    const char *  name  = 0);
335
336/*! @function getType
337    @result Returns the medium type assigned to this medium object.
338*/
339
340    virtual IOMediumType  getType() const;
341
342/*! @function getSpeed
343    @result Returns the maximum link speed supported by this medium.
344*/
345
346    virtual UInt64        getSpeed() const;
347
348/*! @function getFlags
349    @result Returns the medium flags.
350*/
351
352    virtual UInt32        getFlags() const;
353
354/*! @function getIndex
355    @result Returns the assigned medium index.
356*/
357
358    virtual UInt32        getIndex() const;
359
360/*! @function getName
361    @result Returns the name assigned to this medium object.
362*/
363
364    virtual const OSSymbol * getName() const;
365
366/*! @function getKey
367    @result Returns the key to use for this medium object. This key should be
368    used when this object is added to a dictionary. Same as getName().
369*/
370
371    virtual const OSSymbol * getKey() const;
372
373/*! @function isEqualTo
374    @abstract Tests for equality between two IONetworkMedium objects.
375    @discussion Two IONetworkMedium objects are considered equal if
376    they have similar properties assigned to them during initialization.
377    @param medium An IONetworkMedium to test against the IONetworkMedium
378    object being called.
379    @result Returns true if equal, false otherwise.
380*/
381
382    virtual bool isEqualTo(const IONetworkMedium * medium) const;
383
384/*! @function isEqualTo
385    @abstract Tests for equality between a IONetworkMedium object and an
386    OSObject.
387    @discussion The OSObject is considered equal to the IONetworkMedium
388    object if the OSObject is an IONetworkMedium, and they have
389    similar properties assigned to them during initialization.
390    @param obj An OSObject to test against an IONetworkMedium object.
391    @result Returns true if equal, false otherwise.
392*/
393
394    virtual bool isEqualTo(const OSMetaClassBase * obj) const;
395
396/*! @function serialize
397    @abstract Serializes the IONetworkMedium object.
398    @discussion A dictionary is created containing the properties
399    assigned to this medium object, and this dictionary is then
400    serialized using the OSSerialize object provided.
401    @param s An OSSerialize object.
402    @result Returns true on success, false otherwise.
403*/
404
405    virtual bool serialize(OSSerialize * s) const;
406
407    // Virtual function padding
408    OSMetaClassDeclareReservedUnused( IONetworkMedium,  0);
409    OSMetaClassDeclareReservedUnused( IONetworkMedium,  1);
410    OSMetaClassDeclareReservedUnused( IONetworkMedium,  2);
411    OSMetaClassDeclareReservedUnused( IONetworkMedium,  3);
412};
413
414// Translate getKey() to getName().
415//
416inline const OSSymbol * IONetworkMedium::getKey() const
417{
418    return getName();
419}
420
421#endif /* KERNEL */
422
423#endif /* !_IONETWORKMEDIUM_H */
424