iokit/IOKit/network/IONetworkMedium.h

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