Return to IOStorage.h CVS log

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

Annotation of XNU/iokit/IOKit/storage/IOStorage.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 IOStorage
        !            25:  * @abstract
        !            26:  * This header contains the IOStorage class definition.
        !            27:  */
        !            28: 
        !            29: #ifndef _IOSTORAGE_H
        !            30: #define _IOSTORAGE_H
        !            31: 
        !            32: /*!
        !            33:  * @enum IOStorageAccess
        !            34:  * @discussion
        !            35:  * The IOStorageAccess enumeration describes the possible access levels for open
        !            36:  * requests.
        !            37:  * @constant kAccessNone
        !            38:  * No access is requested; should not be passed to open().
        !            39:  * @constant kAccessReader
        !            40:  * Read-only access is requested.
        !            41:  * @constant kAccessReaderWriter
        !            42:  * Read and write access is requested.
        !            43:  */
        !            44: 
        !            45: enum IOStorageAccess
        !            46: {
        !            47:     kAccessNone = 0, kAccessReader = 1, kAccessReaderWriter = 3
        !            48: };
        !            49: 
        !            50: /*!
        !            51:  * @defined kIOStorageCategory
        !            52:  * @abstract
        !            53:  * kIOStorageCategory is a value for IOService's kIOMatchCategoryKey property.
        !            54:  * @discussion
        !            55:  * The kIOStorageCategory value is the standard value for the IOService property
        !            56:  * kIOMatchCategoryKey ("IOMatchCategory") for all storage drivers.  All storage
        !            57:  * objects that expect to drive new content (that is, produce new media objects)
        !            58:  * are expected to compete within the kIOStorageCategory namespace.
        !            59:  *
        !            60:  * See the IOService documentation for more information on match categories.
        !            61:  */
        !            62: 
        !            63: #define kIOStorageCategory "IOStorage"                /* (as IOMatchCategory) */
        !            64: 
        !            65: /*
        !            66:  * Kernel
        !            67:  */
        !            68: 
        !            69: #if defined(KERNEL) && defined(__cplusplus)
        !            70: 
        !            71: #include <IOKit/assert.h>
        !            72: #include <IOKit/IOMemoryDescriptor.h>
        !            73: #include <IOKit/IOService.h>
        !            74: 
        !            75: /*!
        !            76:  * @typedef IOStorageCompletionAction
        !            77:  * @discussion
        !            78:  * The IOStorageCompletionAction declaration describes the C (or C++) completion
        !            79:  * routine that is called once an asynchronous storage operation completes.
        !            80:  * @param target
        !            81:  * Opaque client-supplied pointer (or an instance pointer for a C++ callback).
        !            82:  * @param parameter
        !            83:  * Opaque client-supplied pointer.
        !            84:  * @param status
        !            85:  * Status of the data transfer.
        !            86:  * @param actualByteCount
        !            87:  * Actual number of bytes transferred in the data transfer.
        !            88:  */
        !            89: 
        !            90: typedef void (*IOStorageCompletionAction)(void *   target,
        !            91:                                           void *   parameter,
        !            92:                                           IOReturn status,
        !            93:                                           UInt64   actualByteCount);
        !            94: 
        !            95: /*!
        !            96:  * @struct IOStorageCompletion
        !            97:  * @discussion
        !            98:  * The IOStorageCompletion structure describes the C (or C++) completion routine
        !            99:  * that is called once an asynchronous storage operation completes.   The values
        !           100:  * passed for the target and parameter fields will be passed to the routine when
        !           101:  * it is called.
        !           102:  * @field target
        !           103:  * Opaque client-supplied pointer (or an instance pointer for a C++ callback).
        !           104:  * @field action
        !           105:  * Completion routine to call on completion of the data transfer.
        !           106:  * @field parameter
        !           107:  * Opaque client-supplied pointer.
        !           108:  */
        !           109: 
        !           110: struct IOStorageCompletion
        !           111: {
        !           112:     void *                    target;
        !           113:     IOStorageCompletionAction action;
        !           114:     void *                    parameter;
        !           115: };
        !           116: 
        !           117: /*!
        !           118:  * @class IOStorage
        !           119:  * @abstract
        !           120:  * The IOStorage class is the common base class for mass storage objects.
        !           121:  * @discussion
        !           122:  * The IOStorage class is the common base class for mass storage objects.  It is
        !           123:  * an abstract class that defines the open/close/read/write APIs that need to be
        !           124:  * implemented in a given subclass.  Synchronous versions of the read/write APIs
        !           125:  * are provided here -- they are coded in such a way as to wrap the asynchronous
        !           126:  * versions implmeneted in the subclass.
        !           127:  */
        !           128: 
        !           129: class IOStorage : public IOService
        !           130: {
        !           131:     OSDeclareAbstractStructors(IOStorage);
        !           132: 
        !           133: protected:
        !           134: 
        !           135:     /*!
        !           136:      * @function complete
        !           137:      * @discussion
        !           138:      * Invokes the specified completion action of the read/write request.  If
        !           139:      * the completion action is unspecified, no action is taken.  This method
        !           140:      * serves simply as a convenience to storage subclass developers.
        !           141:      * @param completion
        !           142:      * Completion information for the data transfer.
        !           143:      * @param status
        !           144:      * Status of the data transfer.
        !           145:      * @param actualByteCount
        !           146:      * Actual number of bytes transferred in the data transfer.
        !           147:      */
        !           148: 
        !           149:     inline void complete(IOStorageCompletion completion,
        !           150:                          IOReturn            status,
        !           151:                          UInt64              actualByteCount = 0);
        !           152: 
        !           153:     /*!
        !           154:      * @function handleOpen
        !           155:      * @discussion
        !           156:      * The handleOpen method grants or denies permission to access this object
        !           157:      * to an interested client.  The argument is an IOStorageAccess value that
        !           158:      * specifies the level of access desired -- reader or reader-writer.
        !           159:      *
        !           160:      * This method can be invoked to upgrade or downgrade the access level for
        !           161:      * an existing client as well.  The previous access level will prevail for
        !           162:      * upgrades that fail, of course.   A downgrade should never fail.  If the
        !           163:      * new access level should be the same as the old for a given client, this
        !           164:      * method will do nothing and return success.  In all cases, one, singular
        !           165:      * close-per-client is expected for all opens-per-client received.
        !           166:      * @param client
        !           167:      * Client requesting the open.
        !           168:      * @param options
        !           169:      * Options for the open.  Set to zero.
        !           170:      * @param access
        !           171:      * Access level for the open.  Set to kAccessReader or kAccessReaderWriter.
        !           172:      * @result
        !           173:      * Returns true if the open was successful, false otherwise.
        !           174:      */
        !           175: 
        !           176:     virtual bool handleOpen(IOService *  client,
        !           177:                             IOOptionBits options,
        !           178:                             void *       access) = 0;
        !           179: 
        !           180:     /*!
        !           181:      * @function handleIsOpen
        !           182:      * @discussion
        !           183:      * The handleIsOpen method determines whether the specified client, or any
        !           184:      * client if none is specificed, presently has an open on this object.
        !           185:      * @param client
        !           186:      * Client to check the open state of.  Set to zero to check the open state
        !           187:      * of all clients.
        !           188:      * @result
        !           189:      * Returns true if the client was (or clients were) open, false otherwise.
        !           190:      */
        !           191: 
        !           192:     virtual bool handleIsOpen(const IOService * client) const = 0;
        !           193: 
        !           194:     /*!
        !           195:      * @function handleClose
        !           196:      * @discussion
        !           197:      * The handleClose method closes the client's access to this object.
        !           198:      * @param client
        !           199:      * Client requesting the close.
        !           200:      * @param options
        !           201:      * Options for the close.  Set to zero.
        !           202:      */
        !           203: 
        !           204:     virtual void handleClose(IOService * client, IOOptionBits options) = 0;
        !           205: 
        !           206: public:
        !           207: 
        !           208:     /*!
        !           209:      * @function open
        !           210:      * @discussion
        !           211:      * Ask the storage object for permission to access its contents; the method
        !           212:      * is equivalent to IOService::open(), but with the correct parameter types.
        !           213:      *
        !           214:      * This method may also be invoked to upgrade or downgrade the access of an
        !           215:      * existing open (if it fails, the existing open prevails).
        !           216:      * @param client
        !           217:      * Client requesting the open.
        !           218:      * @param options
        !           219:      * Options for the open.  Set to zero.
        !           220:      * @param access
        !           221:      * Access level for the open.  Set to kAccessReader or kAccessReaderWriter.
        !           222:      * @result
        !           223:      * Returns true if the open was successful, false otherwise.
        !           224:      */
        !           225: 
        !           226:     inline bool open(IOService *     client,
        !           227:                      IOOptionBits    options,
        !           228:                      IOStorageAccess access);
        !           229: 
        !           230:     /*!
        !           231:      * @function read
        !           232:      * @discussion
        !           233:      * Read data from the storage object at the specified byte offset into the
        !           234:      * specified buffer, asynchronously.   When the read completes, the caller
        !           235:      * will be notified via the specified completion action.
        !           236:      *
        !           237:      * The buffer will be retained for the duration of the read.
        !           238:      * @param client
        !           239:      * Client requesting the read.
        !           240:      * @param byteStart
        !           241:      * Starting byte offset for the data transfer.
        !           242:      * @param buffer
        !           243:      * Buffer for the data transfer.  The size of the buffer implies the size of
        !           244:      * the data transfer.
        !           245:      * @param completion
        !           246:      * Completion routine to call once the data transfer is complete.
        !           247:      */
        !           248: 
        !           249:     virtual void read(IOService *          client,
        !           250:                       UInt64               byteStart,
        !           251:                       IOMemoryDescriptor * buffer,
        !           252:                       IOStorageCompletion  completion) = 0;
        !           253: 
        !           254:     /*!
        !           255:      * @function write
        !           256:      * @discussion
        !           257:      * Write data into the storage object at the specified byte offset from the
        !           258:      * specified buffer, asynchronously.   When the write completes, the caller
        !           259:      * will be notified via the specified completion action.
        !           260:      *
        !           261:      * The buffer will be retained for the duration of the write.
        !           262:      * @param client
        !           263:      * Client requesting the write.
        !           264:      * @param byteStart
        !           265:      * Starting byte offset for the data transfer.
        !           266:      * @param buffer
        !           267:      * Buffer for the data transfer.  The size of the buffer implies the size of
        !           268:      * the data transfer.
        !           269:      * @param completion
        !           270:      * Completion routine to call once the data transfer is complete.
        !           271:      */
        !           272: 
        !           273:     virtual void write(IOService *          client,
        !           274:                        UInt64               byteStart,
        !           275:                        IOMemoryDescriptor * buffer,
        !           276:                        IOStorageCompletion  completion) = 0;
        !           277: 
        !           278:     /*!
        !           279:      * @function read
        !           280:      * @discussion
        !           281:      * Read data from the storage object at the specified byte offset into the
        !           282:      * specified buffer, synchronously.   When the read completes, this method
        !           283:      * will return to the caller.  The actual byte count field is optional.
        !           284:      * @param client
        !           285:      * Client requesting the read.
        !           286:      * @param byteStart
        !           287:      * Starting byte offset for the data transfer.
        !           288:      * @param buffer
        !           289:      * Buffer for the data transfer.  The size of the buffer implies the size of
        !           290:      * the data transfer.
        !           291:      * @param actualByteCount
        !           292:      * Returns the actual number of bytes transferred in the data transfer.
        !           293:      * @result
        !           294:      * Returns the status of the data transfer.
        !           295:      */
        !           296: 
        !           297:     virtual IOReturn read(IOService *          client,
        !           298:                           UInt64               byteStart,
        !           299:                           IOMemoryDescriptor * buffer,
        !           300:                           UInt64 *             actualByteCount = 0);
        !           301: 
        !           302:     /*!
        !           303:      * @function write
        !           304:      * @discussion
        !           305:      * Write data into the storage object at the specified byte offset from the
        !           306:      * specified buffer, synchronously.   When the write completes, this method
        !           307:      * will return to the caller.  The actual byte count field is optional.
        !           308:      * @param client
        !           309:      * Client requesting the write.
        !           310:      * @param byteStart
        !           311:      * Starting byte offset for the data transfer.
        !           312:      * @param buffer
        !           313:      * Buffer for the data transfer.  The size of the buffer implies the size of
        !           314:      * the data transfer.
        !           315:      * @param actualByteCount
        !           316:      * Returns the actual number of bytes transferred in the data transfer.
        !           317:      * @result
        !           318:      * Returns the status of the data transfer.
        !           319:      */
        !           320: 
        !           321:     virtual IOReturn write(IOService *          client,
        !           322:                            UInt64               byteStart,
        !           323:                            IOMemoryDescriptor * buffer,
        !           324:                            UInt64 *             actualByteCount = 0);
        !           325: };
        !           326: 
        !           327: /*
        !           328:  * Inline Functions
        !           329:  */
        !           330: 
        !           331: inline void IOStorage::complete(IOStorageCompletion completion,
        !           332:                                 IOReturn            status,
        !           333:                                 UInt64              actualByteCount)
        !           334: {
        !           335:     /*
        !           336:      * Invokes the specified completion action of the read/write request.  If
        !           337:      * the completion action is unspecified, no action is taken.  This method
        !           338:      * serves simply as a convenience to storage subclass developers.
        !           339:      */
        !           340: 
        !           341:     if (completion.action)  (*completion.action)(completion.target, 
        !           342:                                                  completion.parameter,
        !           343:                                                  status,
        !           344:                                                  actualByteCount);
        !           345: }
        !           346: 
        !           347: inline bool IOStorage::open(IOService *     client,
        !           348:                             IOOptionBits    options,
        !           349:                             IOStorageAccess access)
        !           350: {
        !           351:     /*
        !           352:      * Ask the storage object for permission to access its contents; the method
        !           353:      * is equivalent to IOService::open(), but with the correct parameter types.
        !           354:      */
        !           355: 
        !           356:     return IOService::open(client, options, (void *) access);
        !           357: }
        !           358: 
        !           359: #endif /* defined(KERNEL) && defined(__cplusplus) */
        !           360: 
        !           361: #endif /* !_IOSTORAGE_H */

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