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