Return to IONetworkMedium.h CVS log

Up to [Apple XNU] / XNU / iokit / IOKit / network

Annotation of XNU/iokit/IOKit/network/IONetworkMedium.h, revision 1.1

1.1     ! root        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: /*! @typedef IOMediumType
        !            35:     @discussion A 32-bit value divided into fields describing the medium
        !            36:     type. See IONetworkMedium.h. */
        !            37: 
        !            38: typedef UInt32 IOMediumType;
        !            39: 
        !            40: /*! @typedef IOMediumDescriptor
        !            41:     @discussion A structure which describes the properties of an
        !            42:     IONetworkMedium object. The fields in the structure consist of
        !            43:     properties assigned to the object during init(). */
        !            44: 
        !            45: typedef struct {
        !            46:     IOMediumType   type;
        !            47:     UInt32         flags;
        !            48:     UInt64         speed;
        !            49:     UInt32         data;
        !            50:     UInt32         rsvd[3];
        !            51: } IOMediumDescriptor;
        !            52: 
        !            53: //===========================================================================
        !            54: // Medium Type (IOMediumType).
        !            55: //
        !            56: // The medium type is encoded by a 32-bit value. The definitions of
        !            57: // the fields and the encoding for each field is adapted from FreeBSD.
        !            58: //
        !            59: // Bits     Definition
        !            60: // -------------------
        !            61: //  3-0     medium index
        !            62: //    4     reserved
        !            63: //  7-5     medium family
        !            64: // 15-8     type specific options
        !            65: // 19-16    reserved
        !            66: // 27-20    common options
        !            67: // 31-28    instance number
        !            68: 
        !            69: // Common medium definitions.
        !            70: //
        !            71: enum {
        !            72:     kIOMediumIndexAuto        = 0,   /* autoselect */
        !            73:     kIOMediumIndexManual      = 1,   /* use manual configuration */
        !            74:     kIOMediumIndexNone        = 2,   /* de-select all media */
        !            75: };
        !            76: 
        !            77: // Ethernet medium definitions.
        !            78: //
        !            79: enum {
        !            80:     kIOMediumFamilyEthernet = 0x00000020,
        !            81:     kIOMediumEtherAuto      = (kIOMediumIndexAuto   | kIOMediumFamilyEthernet),
        !            82:     kIOMediumEtherManual    = (kIOMediumIndexManual | kIOMediumFamilyEthernet),
        !            83:     kIOMediumEtherNone      = (kIOMediumIndexNone   | kIOMediumFamilyEthernet),
        !            84:     kIOMediumEther10BaseT     = (3  | kIOMediumFamilyEthernet),
        !            85:     kIOMediumEther10Base2     = (4  | kIOMediumFamilyEthernet),
        !            86:     kIOMediumEther10Base5     = (5  | kIOMediumFamilyEthernet),
        !            87:     kIOMediumEther100BaseTX   = (6  | kIOMediumFamilyEthernet),
        !            88:     kIOMediumEther100BaseFX   = (7  | kIOMediumFamilyEthernet),
        !            89:     kIOMediumEther100BaseT4   = (8  | kIOMediumFamilyEthernet),
        !            90:     kIOMediumEther100BaseVG   = (9  | kIOMediumFamilyEthernet),
        !            91:     kIOMediumEther100BaseT2   = (10 | kIOMediumFamilyEthernet),
        !            92:     kIOMediumEther1000BaseSX  = (11 | kIOMediumFamilyEthernet),
        !            93: };
        !            94: 
        !            95: // Common options.
        !            96: //
        !            97: enum {
        !            98:     kIOMediumFullDuplex       = 0x00100000,
        !            99:     kIOMediumHalfDuplex       = 0x00200000,
        !           100:     kIOMediumOptionFlag0      = 0x01000000,
        !           101:     kIOMediumOptionFlag1      = 0x02000000,
        !           102:     kIOMediumOptionFlag2      = 0x04000000,
        !           103: };
        !           104: 
        !           105: // Medium type masks.
        !           106: //
        !           107: #define kIOMediumIndexMask          0x0000000f
        !           108: #define kIOMediumFamilyMask         0x000000e0
        !           109: #define kIOMediumTypeMask           (kIOMediumFamilyMask | kIOMediumIndexMask)
        !           110: #define kIOMediumFamilyOptionsMask  0x0000ff00
        !           111: #define kIOMediumCommonOptionsMask  0x0ff00000
        !           112: #define kIOMediumInstanceShift      28
        !           113: #define kIOMediumInstanceMask       0xf0000000
        !           114: 
        !           115: // Medium type field accessors.
        !           116: //
        !           117: #define IOMediumGetIndex(x)         ((x)  & kIOMediumIndexMask)
        !           118: #define IOMediumGetFamily(x)        ((x)  & kIOMediumFamilyMask)
        !           119: #define IOMediumGetType(x)          ((x)  & kIOMediumTypeMask)
        !           120: #define IOMediumGetInstance(x)      (((x) & kIOMediumInstanceMask) >> \
        !           121:                                             kIOMediumInstanceShift)
        !           122: 
        !           123: //===========================================================================
        !           124: // Medium flags.
        !           125: 
        !           126: enum {
        !           127:     kIOMediumFlagDriverMask   = 0xffff0000,     // fields for driver use
        !           128: };
        !           129: 
        !           130: //===========================================================================
        !           131: // Medium descriptions.
        !           132: 
        !           133: struct IOMediumDescription {
        !           134:     SInt32       word;
        !           135:     const char * string;
        !           136: };
        !           137: 
        !           138: // Family descriptions.
        !           139: //
        !           140: #define kIOMediumFamilyDescriptions {              \
        !           141:     { kIOMediumFamilyEthernet,  "Ethernet" },      \
        !           142:     { 0, NULL },                                   \
        !           143: }
        !           144: 
        !           145: // Ethernet type descriptions.
        !           146: //
        !           147: #define kIOMediumEthernetDescriptions {            \
        !           148:     { kIOMediumEther10BaseT,    "10Base-T" },      \
        !           149:     { kIOMediumEther10Base2,    "10Base-2" },      \
        !           150:     { kIOMediumEther10Base5,    "10Base-5" },      \
        !           151:     { kIOMediumEther100BaseTX,  "100Base-TX" },    \
        !           152:     { kIOMediumEther100BaseFX,  "100Base-FX" },    \
        !           153:     { kIOMediumEther100BaseT4,  "100Base-T4" },    \
        !           154:     { kIOMediumEther100BaseVG,  "100Base-VG" },    \
        !           155:     { kIOMediumEther100BaseT2,  "100Base-T2" },    \
        !           156:     { kIOMediumEther1000BaseSX, "1000Base-SX" },   \
        !           157:     { 0, NULL },                                   \
        !           158: }
        !           159: 
        !           160: // Ethernet option descriptions.
        !           161: //
        !           162: #define kIOMediumEthernetOptionDescriptions {      \
        !           163:     { 0, NULL },                                   \
        !           164: }
        !           165: 
        !           166: // Common type descriptions.
        !           167: //
        !           168: #define kIOMediumCommonDescriptions {              \
        !           169:     { kIOMediumIndexAuto,       "Auto" },          \
        !           170:     { kIOMediumIndexManual,     "Manual" },        \
        !           171:     { kIOMediumIndexNone,       "None" },          \
        !           172:     { 0, NULL },                                   \
        !           173: }
        !           174: 
        !           175: // Common option descriptions.
        !           176: //
        !           177: #define kIOMediumCommonOptionDescriptions {        \
        !           178:     { kIOMediumFullDuplex,      "full-duplex" },   \
        !           179:     { kIOMediumHalfDuplex,      "half-duplex" },   \
        !           180:     { kIOMediumOptionFlag0,     "flag0" },         \
        !           181:     { kIOMediumOptionFlag1,     "flag1" },         \
        !           182:     { kIOMediumOptionFlag2,     "flag2" },         \
        !           183:     { 0, NULL },                                   \
        !           184: }
        !           185: 
        !           186: //===========================================================================
        !           187: // Link status bits.
        !           188: //
        !           189: enum {
        !           190:     kIONetworkLinkValid        = 0x00000001,    // link status is valid
        !           191:     kIONetworkLinkActive       = 0x00000002,    // link is up/active.
        !           192: };
        !           193: 
        !           194: //===========================================================================
        !           195: // IONetworkMedium class.
        !           196: 
        !           197: #ifdef KERNEL
        !           198: 
        !           199: #include <libkern/c++/OSObject.h>
        !           200: #include <libkern/c++/OSSymbol.h>
        !           201: 
        !           202: /*! @class IONetworkMedium
        !           203:     @abstract An object that encapsulates information about a network
        !           204:     medium (i.e. 10Base-T, 100Base-T Full Duplex). The primary use of
        !           205:     this object is for network drivers to advertise its media
        !           206:     capability, by adding a collection of IONetworkMedium objects stored
        !           207:     in a dictionary to its property table.
        !           208:     IONetworkMedium supports serialization, and will encode its
        !           209:     properties in the form of an IOMediumDescriptor structure,
        !           210:     wrapped by an OSData to the serialization stream when instructed. */
        !           211: 
        !           212: class IONetworkMedium : public OSObject
        !           213: {
        !           214:     OSDeclareDefaultStructors(IONetworkMedium)
        !           215: 
        !           216: protected:
        !           217:     IOMediumDescriptor * _desc;
        !           218:     const OSSymbol *     _name;
        !           219: 
        !           220: /*! @function free
        !           221:     @abstract Free the IONetworkMedium instance. */
        !           222: 
        !           223:     virtual void free();
        !           224: 
        !           225: public:
        !           226: 
        !           227: /*! @function nameForType
        !           228:     @abstract Create a name for a medium type.
        !           229:     @discussion Given a 32-bit medium type, create an unique OSymbol name
        !           230:     for the medium. The caller is responsible for releasing the OSSymbol 
        !           231:     object returned.
        !           232:     @param type A medium type. See IONetworkMedium.h for type encoding.
        !           233:     @result An OSSymbol created based on the type provided. */
        !           234: 
        !           235:     static const OSSymbol * nameForType(IOMediumType type);
        !           236: 
        !           237: /*! @function addMedium
        !           238:     @abstract Add an IONetworkMedium object to a dictionary.
        !           239:     @discussion A helper function to add an IONetworkMedium object to a
        !           240:     given dictionary. The name of the medium is used as the key for the
        !           241:     new dictionary entry.
        !           242:     @param dict An OSDictionary object where the medium object should be
        !           243:     added to.
        !           244:     @param medium The IONetworkMedium object to add to the dictionary.
        !           245:     @result true on success, false otherwise. */
        !           246: 
        !           247:     static bool addMedium(OSDictionary * dict, const IONetworkMedium * medium);
        !           248: 
        !           249: /*! @function removeMedium
        !           250:     @abstract Remove an IONetworkMedium object from a dictionary.
        !           251:     @discussion A helper function to remove an entry in a dictionary.
        !           252:     @param dict An OSDictionary object where the medium object should be
        !           253:     removed from.
        !           254:     @param medium The name of this medium object is used as the key. */
        !           255: 
        !           256:     static void removeMedium(OSDictionary *          dict,
        !           257:                              const IONetworkMedium * medium);
        !           258: 
        !           259: /*! @function getMedium
        !           260:     @abstract Find a medium object from a dictionary.
        !           261:     @discussion Iterate through a dictionary and return an IONetworkMedium
        !           262:     entry that satisfies the matching criteria. Returns 0 if there is
        !           263:     no match. Also see getMediumWithType() and getMediumWithIndex() that
        !           264:     are specialized forms derived from this method.
        !           265:     @param dict The dictionary to look for a match.
        !           266:     @param match An IOMediumDescriptor structure containing the matching
        !           267:     fields.
        !           268:     @param mask An IOMediumDescriptor structure containing the matching
        !           269:     mask. Bits set in the mask are used for matching, while bits cleared
        !           270:     are considered to be don't care bits.
        !           271:     @result The first matching IONetworkMedium entry found,
        !           272:     or 0 if no match was found. */
        !           273: 
        !           274:     static IONetworkMedium * getMedium(const OSDictionary * dict,
        !           275:                                        IOMediumDescriptor * match,
        !           276:                                        IOMediumDescriptor * mask);
        !           277: 
        !           278: /*! @function getMediumWithType
        !           279:     @abstract Find a medium object from a dictionary with a given type.
        !           280:     @discussion Iterate through a dictionary and return an IONetworkMedium
        !           281:     entry with the given type. An optional mask supplies the don't care bits.
        !           282:     See getMedium().
        !           283:     @param dict The dictionary to look for a match.
        !           284:     @param type Search for an entry with the given type.
        !           285:     @param mask The don't care bits in IOMediumType. Defaults to 0, which
        !           286:     implies a perfect match is desired.
        !           287:     @result The first matching IONetworkMedium entry found,
        !           288:     or 0 if no match was found. */
        !           289: 
        !           290:     static IONetworkMedium * getMediumWithType(const OSDictionary * dict,
        !           291:                                                IOMediumType         type,
        !           292:                                                IOMediumType         mask = 0);
        !           293: 
        !           294: /*! @function getMediumWithIndex
        !           295:     @abstract Find a medium object from a dictionary with a given index.
        !           296:     @discussion Iterate through a dictionary and return an IONetworkMedium
        !           297:     entry with the given index. A optional mask supplies the don't care bits.
        !           298:     See getMedium().
        !           299:     @param dict The dictionary to look for a match.
        !           300:     @param index Search for an entry with the given index.
        !           301:     @param mask The don't care bits in index. Defaults to 0, which
        !           302:     implies a perfect match is desired.
        !           303:     @result The first matching IONetworkMedium entry found,
        !           304:     or 0 if no match was found. */
        !           305: 
        !           306:     static IONetworkMedium * getMediumWithIndex(const OSDictionary * dict,
        !           307:                                                 UInt32               index,
        !           308:                                                 UInt32               mask = 0);
        !           309: 
        !           310: /*! @function init
        !           311:     @abstract Initialize an IONetworkMedium instance.
        !           312:     @param type The medium type, the fields are encoded with bits defined in
        !           313:            IONetworkMedium.h.
        !           314:     @param speed The maximum (or the only) link speed supported over this 
        !           315:            medium in units of bits per second.
        !           316:     @param flags An optional flag for the medium object.
        !           317:            See IONetworkMedium.h for defined flags.
        !           318:     @param index An optional 32-bit index assigned by the caller.
        !           319:            Drivers can use this to store an index or a pointer to a media table
        !           320:            inside the driver, or it may map to a driver defined media type.
        !           321:     @param name An optional name assigned to this medium object. If 0,
        !           322:            then a name will be created based on the medium type given
        !           323:            using nameForType().
        !           324:     @result true on success, false otherwise. */
        !           325: 
        !           326:     virtual bool init(IOMediumType  type,
        !           327:                       UInt64        speed,
        !           328:                       UInt32        flags = 0,
        !           329:                       UInt32        index = 0,
        !           330:                       const char *  name  = 0);
        !           331: 
        !           332: /*! @function medium
        !           333:     @abstract Factory method which performs allocation and initialization
        !           334:     of an IONetworkMedium instance.
        !           335:     @param type See init().
        !           336:     @param speed See init().
        !           337:     @param flags See init().
        !           338:     @param index See init().
        !           339:     @param name See init().
        !           340:     @result An IONetworkMedium instance on success, or 0 otherwise. */
        !           341: 
        !           342:     static IONetworkMedium * medium(IOMediumType  type,
        !           343:                                     UInt64        speed,
        !           344:                                     UInt32        flags = 0,
        !           345:                                     UInt32        index = 0,
        !           346:                                     const char *  name  = 0);
        !           347: 
        !           348: /*! @function getType
        !           349:     @result The assigned medium type. */
        !           350: 
        !           351:     virtual IOMediumType  getType() const;
        !           352: 
        !           353: /*! @function getSpeed
        !           354:     @result The maximum medium speed. */
        !           355: 
        !           356:     virtual UInt64        getSpeed() const;
        !           357: 
        !           358: /*! @function getFlags
        !           359:     @result The medium flags. */
        !           360: 
        !           361:     virtual UInt32        getFlags() const;
        !           362: 
        !           363: /*! @function getIndex
        !           364:     @result The assigned index. */
        !           365: 
        !           366:     virtual UInt32        getIndex() const;
        !           367: 
        !           368: /*! @function getDescriptor
        !           369:     @param descP The IOMediumDescriptor structure associated with the
        !           370:     instance is copied to the address provided. */
        !           371: 
        !           372:     virtual void          getDescriptor(IOMediumDescriptor * descP) const;
        !           373: 
        !           374: /*! @function getName
        !           375:     @result The name for this instance. */
        !           376: 
        !           377:     virtual const OSSymbol * getName() const;
        !           378: 
        !           379: /*! @function getKey
        !           380:     @result The key for this instance. Same as getName(). */
        !           381: 
        !           382:     virtual const OSSymbol * getKey() const;
        !           383: 
        !           384: /*! @function isEqualTo
        !           385:     @abstract Test for equality between two IONetworkMedium objects.
        !           386:     @discussion Two IONetworkMedium objects are considered equal if
        !           387:     they have similar properties assigned to them during initialization.
        !           388:     @param medium An IONetworkMedium to test against the IONetworkMedium
        !           389:     object being called.
        !           390:     @result true if equal, false otherwise. */
        !           391: 
        !           392:     virtual bool isEqualTo(const IONetworkMedium * medium) const;
        !           393: 
        !           394: /*! @function isEqualTo
        !           395:     @abstract Test for equality between a IONetworkMedium object and an
        !           396:     OSObject.
        !           397:     @discussion The OSObject is considered equal to the IONetworkMedium
        !           398:     object if the OSObject is an IONetworkMedium, and they have
        !           399:     similar properties assigned to them during initialization.
        !           400:     @param obj An OSObject to test against the IONetworkMedium object
        !           401:     being called.
        !           402:     @result true if equal, false otherwise. */
        !           403: 
        !           404:     virtual bool isEqualTo(const OSObject * obj) const;
        !           405: 
        !           406: /*! @function serialize
        !           407:     @abstract Serialize the IONetworkMedium object.
        !           408:     @discussion An OSData is created containing an IOMediumDescriptor
        !           409:     structure (not copied), and this OSData is serialized.
        !           410:     @param s An OSSerialize object.
        !           411:     @result true on success, false otherwise. */
        !           412: 
        !           413:     virtual bool serialize(OSSerialize * s) const;
        !           414: };
        !           415: 
        !           416: // Translate getKey() to getName().
        !           417: //
        !           418: inline const OSSymbol * IONetworkMedium::getKey() const
        !           419: {
        !           420:     return getName();
        !           421: }
        !           422: 
        !           423: #endif /* KERNEL */
        !           424: 
        !           425: #endif /* !_IONETWORKMEDIUM_H */

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.