Return to IOMedia.h CVS log

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

Annotation of XNU/iokit/IOKit/storage/IOMedia.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: /*!
        !            24:  * @header IOMedia
        !            25:  * @abstract
        !            26:  * This header contains the IOMedia class definition.
        !            27:  */
        !            28: 
        !            29: #ifndef _IOMEDIA_H
        !            30: #define _IOMEDIA_H
        !            31: 
        !            32: /*!
        !            33:  * @defined kIOMediaContent
        !            34:  * @abstract
        !            35:  * kIOMediaContent is a property of IOMedia objects.  It is an OSString.
        !            36:  * @discussion
        !            37:  * The kIOMediaContent property contains a description of the media's contents.
        !            38:  * The description is the same as the hint at the time of the object's creation,
        !            39:  * but it is possible that the description be overrided by a client (which has
        !            40:  * probed the media and identified the content correctly) of the media object.
        !            41:  * It is more accurate than the hint for this reason.  The string is formed in
        !            42:  * the likeness of Apple's "Apple_HFS" strings.
        !            43:  */
        !            44: 
        !            45: #define kIOMediaContent "Content"
        !            46: 
        !            47: /*!
        !            48:  * @defined kIOMediaContentHint
        !            49:  * @abstract
        !            50:  * kIOMediaContentHint is a property of IOMedia objects.  It is an OSString.
        !            51:  * @discussion
        !            52:  * The kIOMediaContentHint property contains a hint of the media's contents.
        !            53:  * The hint is set at the time of the object's creation, should the creator have
        !            54:  * a clue as to what it may contain.  The hint string does not change for the
        !            55:  * lifetime of the object and is formed in the likeness of Apple's "Apple_HFS"
        !            56:  * strings.
        !            57:  */
        !            58: 
        !            59: #define kIOMediaContentHint "Content Hint"
        !            60: 
        !            61: /*!
        !            62:  * @defined kIOMediaEjectable
        !            63:  * @abstract
        !            64:  * kIOMediaEjectable is a property of IOMedia objects.  It is an OSBoolean.
        !            65:  * @discussion
        !            66:  * The kIOMediaEjectable property describes whether the media is ejectable.
        !            67:  */
        !            68: 
        !            69: #define kIOMediaEjectable "Ejectable"
        !            70: 
        !            71: /*!
        !            72:  * @defined kIOMediaLeaf
        !            73:  * @abstract
        !            74:  * kIOMediaLeaf is a property of IOMedia objects.  It is an OSBoolean.
        !            75:  * @discussion
        !            76:  * The kIOMediaLeaf property describes whether the media is a leaf, that is, it
        !            77:  * is the deepest media object in this branch of the I/O Kit registry.
        !            78:  */
        !            79: 
        !            80: #define kIOMediaLeaf "Leaf"
        !            81: 
        !            82: /*!
        !            83:  * @defined kIOMediaSize
        !            84:  * @abstract
        !            85:  * kIOMediaSize is a property of IOMedia objects.  It is an OSNumber.
        !            86:  * @discussion
        !            87:  * The kIOMediaSize property describes the total length of the media in bytes.
        !            88:  */
        !            89: 
        !            90: #define kIOMediaSize "Size"
        !            91: 
        !            92: /*!
        !            93:  * @defined kIOMediaWhole
        !            94:  * @abstract
        !            95:  * kIOMediaWhole is a property of IOMedia objects.  Is it an OSBoolean.
        !            96:  * @discussion
        !            97:  * The kIOMediaWhole property describes whether the media is whole, that is, it
        !            98:  * represents the whole disk (the physical disk, or a virtual replica thereof).
        !            99:  */
        !           100: 
        !           101: #define kIOMediaWhole "Whole"
        !           102: 
        !           103: /*!
        !           104:  * @defined kIOMediaWritable
        !           105:  * @abstract
        !           106:  * kIOMediaWritable is a property of IOMedia objects.  It is an OSBoolean.
        !           107:  * @discussion
        !           108:  * The kIOMediaWritable property describes whether the media is writable.
        !           109:  */
        !           110: 
        !           111: #define kIOMediaWritable "Writable"
        !           112: 
        !           113: /*!
        !           114:  * @defined kIOMediaContentMask
        !           115:  * @abstract
        !           116:  * kIOMediaContentMask is a property of IOMedia clients.  It is an OSString.
        !           117:  * @discussion
        !           118:  * The kIOMediaContentMask property must exist in all IOMedia clients that drive
        !           119:  * new content (that is, produce new media objects).  When the client matches on
        !           120:  * the provider media, the value of the client's kIOMediaContentMask property is
        !           121:  * used to replace the provider's kIOMediaContent property.
        !           122:  */
        !           123: 
        !           124: #define kIOMediaContentMask "Content Mask"
        !           125: 
        !           126: /*
        !           127:  * Kernel
        !           128:  */
        !           129: 
        !           130: #if defined(KERNEL) && defined(__cplusplus)
        !           131: 
        !           132: #include <IOKit/storage/IOStorage.h>
        !           133: 
        !           134: /*!
        !           135:  * @class IOMedia
        !           136:  * @abstract
        !           137:  * The IOMedia class is a random-access disk device abstraction.
        !           138:  * @discussion
        !           139:  * The IOMedia class is a random-access disk device abstraction.   It provides a
        !           140:  * consistent interface for both real and virtual disk devices, for subdivisions
        !           141:  * of disks such as partitions, for supersets of disks such as RAID volumes, and
        !           142:  * so on.   It extends the IOStorage class by implementing the appropriate open,
        !           143:  * close, read, write, and matching semantics for media objects.  The properties
        !           144:  * it has reflect the properties of real disk devices,  such as ejectability and
        !           145:  * writability.
        !           146:  *
        !           147:  * The read and write interfaces support byte-level access to the storage space,
        !           148:  * with the appropriate deblocking handled by IODrive, however, a typical client
        !           149:  * will want to obtain the natural block size in order to optimize access to the
        !           150:  * real disk device.  A read or write is accepted so long as the client's access
        !           151:  * is valid, the media is formatted and the transfer is within the bounds of the
        !           152:  * media.  An optional non-zero base (offset) is then applied before the read or
        !           153:  * write is passed to provider object.
        !           154:  *
        !           155:  * An open is accepted so long as no more than one writer is active at any time.
        !           156:  */
        !           157: 
        !           158: class IOMedia : public IOStorage
        !           159: {
        !           160:     OSDeclareDefaultStructors(IOMedia)
        !           161: 
        !           162: protected:
        !           163:     bool            _isEjectable;
        !           164:     bool            _isWhole;
        !           165:     bool            _isWritable;
        !           166: 
        !           167:     UInt64          _mediaBase;  /* (relative to the storage object below us) */
        !           168:     UInt64          _mediaSize;
        !           169: 
        !           170:     IOStorageAccess _openLevel;
        !           171:     OSSet *         _openReaders;
        !           172:     IOService *     _openReaderWriter;
        !           173: 
        !           174:     UInt64          _preferredBlockSize;
        !           175: 
        !           176:     /*
        !           177:      * Free all of this object's outstanding resources.
        !           178:      */
        !           179: 
        !           180:     virtual void free();
        !           181: 
        !           182:     /*!
        !           183:      * @function handleOpen
        !           184:      * @discussion
        !           185:      * The handleOpen method grants or denies permission to access this object
        !           186:      * to an interested client.  The argument is an IOStorageAccess value that
        !           187:      * specifies the level of access desired -- reader or reader-writer.
        !           188:      *
        !           189:      * This method can be invoked to upgrade or downgrade the access level for
        !           190:      * an existing client as well.  The previous access level will prevail for
        !           191:      * upgrades that fail, of course.   A downgrade should never fail.  If the
        !           192:      * new access level should be the same as the old for a given client, this
        !           193:      * method will do nothing and return success.  In all cases, one, singular
        !           194:      * close-per-client is expected for all opens-per-client received.
        !           195:      *
        !           196:      * This implementation replaces the IOService definition of handleOpen().
        !           197:      * @param client
        !           198:      * Client requesting the open.
        !           199:      * @param options
        !           200:      * Options for the open.  Set to zero.
        !           201:      * @param access
        !           202:      * Access level for the open.  Set to kAccessReader or kAccessReaderWriter.
        !           203:      * @result
        !           204:      * Returns true if the open was successful, false otherwise.
        !           205:      */
        !           206: 
        !           207:     virtual bool handleOpen(IOService *  client,
        !           208:                             IOOptionBits options,
        !           209:                             void *       access);
        !           210: 
        !           211:     /*!
        !           212:      * @function handleIsOpen
        !           213:      * @discussion
        !           214:      * The handleIsOpen method determines whether the specified client, or any
        !           215:      * client if none is specificed, presently has an open on this object.
        !           216:      *
        !           217:      * This implementation replaces the IOService definition of handleIsOpen().
        !           218:      * @param client
        !           219:      * Client to check the open state of.  Set to zero to check the open state
        !           220:      * of all clients.
        !           221:      * @result
        !           222:      * Returns true if the client was (or clients were) open, false otherwise.
        !           223:      */
        !           224: 
        !           225:     virtual bool handleIsOpen(const IOService * client) const;
        !           226: 
        !           227:     /*!
        !           228:      * @function handleClose
        !           229:      * @discussion
        !           230:      * The handleClose method closes the client's access to this object.
        !           231:      *
        !           232:      * This implementation replaces the IOService definition of handleClose().
        !           233:      * @param client
        !           234:      * Client requesting the close.
        !           235:      * @param options
        !           236:      * Options for the close.  Set to zero.
        !           237:      */
        !           238: 
        !           239:     virtual void handleClose(IOService * client, IOOptionBits options);
        !           240: 
        !           241: public:
        !           242: 
        !           243: ///m:2333367:workaround:commented:start
        !           244: //  IOStorage::open;
        !           245: //  IOStorage::close;
        !           246: //  IOStorage::read;
        !           247: //  IOStorage::write;
        !           248: ///m:2333367:workaround:commented:stop
        !           249: 
        !           250: ///m:2333367:workaround:added:start
        !           251:     inline bool open(IOService *     client,
        !           252:                      IOOptionBits    options,
        !           253:                      IOStorageAccess access)
        !           254:     { return IOStorage::open(client, options, access); }
        !           255: 
        !           256:     virtual IOReturn read(IOService *          client,
        !           257:                           UInt64               byteStart,
        !           258:                           IOMemoryDescriptor * buffer,
        !           259:                           UInt64 *             actualByteCount = 0)
        !           260:     { return IOStorage::read(client, byteStart, buffer, actualByteCount); }
        !           261: 
        !           262:     virtual IOReturn write(IOService *          client,
        !           263:                            UInt64               byteStart,
        !           264:                            IOMemoryDescriptor * buffer,
        !           265:                            UInt64 *             actualByteCount = 0)
        !           266:     { return IOStorage::write(client, byteStart, buffer, actualByteCount); }
        !           267: ///m:2333367:workaround:added:stop
        !           268: 
        !           269:     /*!
        !           270:      * @function init
        !           271:      * @discussion
        !           272:      * Initialize this object's minimal state.
        !           273:      * @param base
        !           274:      * Media offset, in bytes.
        !           275:      * @param size
        !           276:      * Media size, in bytes.
        !           277:      * @param preferredBlockSize
        !           278:      * Natural block size, in bytes.
        !           279:      * @param isEjectable
        !           280:      * Indicates whether the media is ejectable.
        !           281:      * @param isWhole
        !           282:      * Indicated whether the media represents the whole disk.
        !           283:      * @param isWritable
        !           284:      * Indicates whether the media is writable.
        !           285:      * @param contentHint
        !           286:      * Hint of media's contents (optional).  See getContentHint().
        !           287:      * @param properties
        !           288:      * Substitute property table for this object (optional).
        !           289:      * @result
        !           290:      * Returns true on success, false otherwise.
        !           291:      */
        !           292: 
        !           293:     virtual bool init(UInt64         base,
        !           294:                       UInt64         size,
        !           295:                       UInt64         preferredBlockSize,
        !           296:                       bool           isEjectable,
        !           297:                       bool           isWhole,
        !           298:                       bool           isWritable,
        !           299:                       const char *   contentHint = 0,
        !           300:                       OSDictionary * properties  = 0);
        !           301: 
        !           302:     /*
        !           303:      * This method is called for each client interested in the services we
        !           304:      * provide.  The superclass links us as a parent to this client in the
        !           305:      * I/O Kit registry on success.
        !           306:      */
        !           307: 
        !           308:     bool attachToChild(IORegistryEntry * client, const IORegistryPlane *);
        !           309: 
        !           310:     /*
        !           311:      * This method is called for each client that loses interest in the
        !           312:      * services we provide.  The superclass unlinks us from this client
        !           313:      * in the I/O Kit registry on success.
        !           314:      */
        !           315: 
        !           316:     void detachFromChild(IORegistryEntry * client, const IORegistryPlane *);
        !           317: 
        !           318:     /*
        !           319:      * I/O Kit is in the process of searching for a candidate object that wishes
        !           320:      * to match against an IOLocation={x} dictionary of properties.  This is the
        !           321:      * method called to determine whether this object wants to be the candidate.
        !           322:      *
        !           323:      * The matchLocation method should return "this" if it decides to match with
        !           324:      * the IOLocation={x} dictionary, otherwise it should call the superclass to
        !           325:      * continue with the search and skip this object as a candidate.
        !           326:      *
        !           327:      * If this object chooses to match, the dictionary {x} will be passed to the
        !           328:      * standard (passive) matching method matchPropertyTable for comparison.
        !           329:      */
        !           330: 
        !           331:     virtual IOService * matchLocation(IOService * client);
        !           332: 
        !           333:     /*
        !           334:      * Compare the properties in the supplied table to this object's properties.
        !           335:      */
        !           336: 
        !           337:     virtual bool matchPropertyTable(OSDictionary * table);
        !           338: 
        !           339:     /*
        !           340:      * Obtain a path to this service object.
        !           341:      */
        !           342: 
        !           343:     virtual bool getPath(char * path, int * len, const IORegistryPlane *) const;
        !           344: 
        !           345:     /*!
        !           346:      * @function read
        !           347:      * @discussion
        !           348:      * Read data from the storage object at the specified byte offset into the
        !           349:      * specified buffer, asynchronously.   When the read completes, the caller
        !           350:      * will be notified via the specified completion action.
        !           351:      *
        !           352:      * The buffer will be retained for the duration of the read.
        !           353:      * @param client
        !           354:      * Client requesting the read.
        !           355:      * @param byteStart
        !           356:      * Starting byte offset for the data transfer.
        !           357:      * @param buffer
        !           358:      * Buffer for the data transfer.  The size of the buffer implies the size of
        !           359:      * the data transfer.
        !           360:      * @param completion
        !           361:      * Completion routine to call once the data transfer is complete.
        !           362:      */
        !           363: 
        !           364:     virtual void read(IOService *          client,
        !           365:                       UInt64               byteStart,
        !           366:                       IOMemoryDescriptor * buffer,
        !           367:                       IOStorageCompletion  completion);
        !           368: 
        !           369:     /*!
        !           370:      * @function write
        !           371:      * @discussion
        !           372:      * Write data into the storage object at the specified byte offset from the
        !           373:      * specified buffer, asynchronously.   When the write completes, the caller
        !           374:      * will be notified via the specified completion action.
        !           375:      *
        !           376:      * The buffer will be retained for the duration of the write.
        !           377:      * @param client
        !           378:      * Client requesting the write.
        !           379:      * @param byteStart
        !           380:      * Starting byte offset for the data transfer.
        !           381:      * @param buffer
        !           382:      * Buffer for the data transfer.  The size of the buffer implies the size of
        !           383:      * the data transfer.
        !           384:      * @param completion
        !           385:      * Completion routine to call once the data transfer is complete.
        !           386:      */
        !           387: 
        !           388:     virtual void write(IOService *          client,
        !           389:                        UInt64               byteStart,
        !           390:                        IOMemoryDescriptor * buffer,
        !           391:                        IOStorageCompletion  completion);
        !           392: 
        !           393:     /*!
        !           394:      * @function getPreferredBlockSize
        !           395:      * @discussion
        !           396:      * Ask the media object for its natural block size.  This information
        !           397:      * is useful to clients that want to optimize access to the media.
        !           398:      * @result
        !           399:      * Natural block size, in bytes.
        !           400:      */
        !           401: 
        !           402:     virtual UInt64 getPreferredBlockSize() const;
        !           403: 
        !           404:     /*!
        !           405:      * @function getSize
        !           406:      * @discussion
        !           407:      * Ask the media object for its total length in bytes.
        !           408:      * @result
        !           409:      * Media size, in bytes.
        !           410:      */
        !           411: 
        !           412:     virtual UInt64 getSize() const;
        !           413: 
        !           414:     /*!
        !           415:      * @function getBase
        !           416:      * @discussion
        !           417:      * Ask the media object for its byte offset relative to its provider media
        !           418:      * object below it in the storage hierarchy.
        !           419:      * Media offset, in bytes.
        !           420:      */
        !           421: 
        !           422:     virtual UInt64 getBase() const;
        !           423: 
        !           424:     /*!
        !           425:      * @function isEjectable
        !           426:      * @discussion
        !           427:      * Ask the media object whether it is ejectable.
        !           428:      * @result
        !           429:      * Returns true if the media is ejectable, false otherwise.
        !           430:      */
        !           431: 
        !           432:     virtual bool isEjectable() const;
        !           433: 
        !           434:     /*!
        !           435:      * @function isFormatted
        !           436:      * @discussion
        !           437:      * Ask the media object whether it is formatted.
        !           438:      * @result
        !           439:      * Returns true if the media is formatted, false otherwise.
        !           440:      */
        !           441: 
        !           442:     virtual bool isFormatted() const;
        !           443: 
        !           444:     /*!
        !           445:      * @function isWhole
        !           446:      * @discussion
        !           447:      * Ask the media object whether it represents the whole disk.
        !           448:      * @result
        !           449:      * Returns true if the media represents the whole disk, false otherwise.
        !           450:      */
        !           451: 
        !           452:     virtual bool isWhole() const;
        !           453: 
        !           454:     /*!
        !           455:      * @function isWritable
        !           456:      * @discussion
        !           457:      * Ask the media object whether it is writable.
        !           458:      * @result
        !           459:      * Returns true if the media is writable, false otherwise.
        !           460:      */
        !           461: 
        !           462:     virtual bool isWritable() const;
        !           463: 
        !           464:     /*!
        !           465:      * @function getContent
        !           466:      * @discussion
        !           467:      * Ask the media object for a description of its contents.  The description
        !           468:      * is the same as the hint at the time of the object's creation,  but it is
        !           469:      * possible that the description be overrided by a client (which has probed
        !           470:      * the media and identified the content correctly) of the media object.  It
        !           471:      * is more accurate than the hint for this reason.  The string is formed in
        !           472:      * the likeness of Apple's "Apple_HFS" strings.
        !           473:      *
        !           474:      * The content description can be overrided by any client that matches onto
        !           475:      * this media object with a match category of kIOStorageCategory.  The media
        !           476:      * object checks for a kIOMediaContentMask property in the client, and if it
        !           477:      * finds one, it copies it into kIOMediaContent property.
        !           478:      * @result
        !           479:      * Description of media's contents.
        !           480:      */
        !           481: 
        !           482:     virtual const char * getContent() const;
        !           483: 
        !           484:     /*!
        !           485:      * @function getContentHint
        !           486:      * @discussion
        !           487:      * Ask the media object for a hint of its contents.  The hint is set at the
        !           488:      * time of the object's creation, should the creator have a clue as to what
        !           489:      * it may contain.  The hint string does not change for the lifetime of the
        !           490:      * object and is also formed in the likeness of Apple's "Apple_HFS" strings.
        !           491:      * @result
        !           492:      * Hint of media's contents.
        !           493:      */
        !           494: 
        !           495:     virtual const char * getContentHint() const;
        !           496: 
        !           497:     /*
        !           498:      * Obtain this object's provider.  We override the superclass's method to
        !           499:      * return a more specific subclass of OSObject -- IOStorage.  This method
        !           500:      * serves simply as a convenience to subclass developers.
        !           501:      */
        !           502: 
        !           503:     virtual IOStorage * getProvider() const
        !           504:     {
        !           505:         return (IOStorage *) IOStorage::getProvider();
        !           506:     }
        !           507: };
        !           508: 
        !           509: #endif /* defined(KERNEL) && defined(__cplusplus) */
        !           510: 
        !           511: #endif /* !_IOMEDIA_H */

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