iokit/IOKit/storage/IOPartitionScheme.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 IOPartitionScheme
  25  * @abstract
  26  * This header contains the IOPartitionScheme class definition.
  27  */
  28
  29 #ifndef _IOPARTITIONSCHEME_H
  30 #define _IOPARTITIONSCHEME_H
  31
  32 /*!
  33  * @defined kIOPartitionSchemeClass
  34  * @abstract
  35  * kIOPartitionSchemeClass is the name of the IOPartitionScheme class.
  36  * @discussion
  37  * kIOPartitionSchemeClass is the name of the IOPartitionScheme class.
  38  */
  39
  40 #define kIOPartitionSchemeClass "IOPartitionScheme"
  41
  42 /*!
  43  * @defined kIOMediaPartitionIDKey
  44  * @abstract
  45  * kIOMediaPartitionIDKey is property of IOMedia objects.  It has an OSNumber
  46  * value.
  47  * @discussion
  48  * The kIOMediaPartitionIDKey property is placed into each IOMedia instance
  49  * created via the partition scheme.  It is an ID that differentiates one
  50  * partition from the other (within a given scheme).  It is typically an index
  51  * into the on-disk partition table.
  52  */
  53
  54 #define kIOMediaPartitionIDKey "Partition ID"
  55 #define kIOMediaPartitionID "Partition ID" ///d:deprecated
  56
  57 /*
  58  * Kernel
  59  */
  60
  61 #if defined(KERNEL) && defined(__cplusplus)
  62
  63 #include <IOKit/storage/IOMedia.h>
  64 #include <IOKit/storage/IOStorage.h>
  65
  66 /*!
  67  * @class IOPartitionScheme
  68  * @abstract
  69  * The IOPartitionScheme class is the common base class for all partition scheme
  70  * objects.
  71  * @discussion
  72  * The IOPartitionScheme class is the common base class for all partition scheme
  73  * objects.  It extends the IOStorage class by implementing the appropriate open
  74  * and close semantics for partition objects (standard semantics are to act as a
  75  * multiplexor for incoming opens,  producing one outgoing open with the correct
  76  * access).  It also implements the default read and write semantics, which pass
  77  * all reads and writes through to the provider media unprocessed.    For simple
  78  * schemes, the default behavior is sufficient.   More complex partition schemes
  79  * such as RAID will want to do extra processing for reads and writes.
  80  */
  81
  82 class IOPartitionScheme : public IOStorage
  83 {
  84     OSDeclareDefaultStructors(IOPartitionScheme);
  85
  86 protected:
  87
  88     struct ExpansionData { /* */ };
  89     ExpansionData * _expansionData;
  90
  91     IOStorageAccess _openLevel;
  92     OSSet *         _openReaders;
  93     OSSet *         _openReaderWriters;
  94
  95     /*
  96      * Free all of this object's outstanding resources.
  97      */
  98
  99     virtual void free();
 100
 101     /*!
 102      * @function handleOpen
 103      * @discussion
 104      * The handleOpen method grants or denies permission to access this object
 105      * to an interested client.  The argument is an IOStorageAccess value that
 106      * specifies the level of access desired -- reader or reader-writer.
 107      *
 108      * This method can be invoked to upgrade or downgrade the access level for
 109      * an existing client as well.  The previous access level will prevail for
 110      * upgrades that fail, of course.   A downgrade should never fail.  If the
 111      * new access level should be the same as the old for a given client, this
 112      * method will do nothing and return success.  In all cases, one, singular
 113      * close-per-client is expected for all opens-per-client received.
 114      *
 115      * This implementation replaces the IOService definition of handleOpen().
 116      * @param client
 117      * Client requesting the open.
 118      * @param options
 119      * Options for the open.  Set to zero.
 120      * @param access
 121      * Access level for the open.  Set to kIOStorageAccessReader or
 122      * kIOStorageAccessReaderWriter.
 123      * @result
 124      * Returns true if the open was successful, false otherwise.
 125      */
 126
 127     virtual bool handleOpen(IOService *  client,
 128                             IOOptionBits options,
 129                             void *       access);
 130
 131     /*!
 132      * @function handleIsOpen
 133      * @discussion
 134      * The handleIsOpen method determines whether the specified client, or any
 135      * client if none is specificed, presently has an open on this object.
 136      *
 137      * This implementation replaces the IOService definition of handleIsOpen().
 138      * @param client
 139      * Client to check the open state of.  Set to zero to check the open state
 140      * of all clients.
 141      * @result
 142      * Returns true if the client was (or clients were) open, false otherwise.
 143      */
 144
 145     virtual bool handleIsOpen(const IOService * client) const;
 146
 147     /*!
 148      * @function handleClose
 149      * @discussion
 150      * The handleClose method closes the client's access to this object.
 151      *
 152      * This implementation replaces the IOService definition of handleClose().
 153      * @param client
 154      * Client requesting the close.
 155      * @param options
 156      * Options for the close.  Set to zero.
 157      */
 158
 159     virtual void handleClose(IOService * client, IOOptionBits options);
 160
 161 public:
 162
 163 ///m:2333367:workaround:commented:start
 164 //  using read;
 165 //  using write;
 166 ///m:2333367:workaround:commented:stop
 167
 168     /*
 169      * Initialize this object's minimal state.
 170      */
 171
 172     virtual bool init(OSDictionary * properties = 0);
 173
 174     /*!
 175      * @function read
 176      * @discussion
 177      * Read data from the storage object at the specified byte offset into the
 178      * specified buffer, asynchronously.   When the read completes, the caller
 179      * will be notified via the specified completion action.
 180      *
 181      * The buffer will be retained for the duration of the read.
 182      *
 183      * For simple partition schemes, the default behavior is to simply pass the
 184      * read through to the provider media.  More complex partition schemes such
 185      * as RAID will need to do extra processing here.
 186      * @param client
 187      * Client requesting the read.
 188      * @param byteStart
 189      * Starting byte offset for the data transfer.
 190      * @param buffer
 191      * Buffer for the data transfer.  The size of the buffer implies the size of
 192      * the data transfer.
 193      * @param completion
 194      * Completion routine to call once the data transfer is complete.
 195      */
 196
 197     virtual void read(IOService *          client,
 198                       UInt64               byteStart,
 199                       IOMemoryDescriptor * buffer,
 200                       IOStorageCompletion  completion);
 201
 202     /*!
 203      * @function write
 204      * @discussion
 205      * Write data into the storage object at the specified byte offset from the
 206      * specified buffer, asynchronously.   When the write completes, the caller
 207      * will be notified via the specified completion action.
 208      *
 209      * The buffer will be retained for the duration of the write.
 210      *
 211      * For simple partition schemes, the default behavior is to simply pass the
 212      * write through to the provider media. More complex partition schemes such
 213      * as RAID will need to do extra processing here.
 214      * @param client
 215      * Client requesting the write.
 216      * @param byteStart
 217      * Starting byte offset for the data transfer.
 218      * @param buffer
 219      * Buffer for the data transfer.  The size of the buffer implies the size of
 220      * the data transfer.
 221      * @param completion
 222      * Completion routine to call once the data transfer is complete.
 223      */
 224
 225     virtual void write(IOService *          client,
 226                        UInt64               byteStart,
 227                        IOMemoryDescriptor * buffer,
 228                        IOStorageCompletion  completion);
 229
 230     virtual IOReturn synchronizeCache(IOService * client);
 231
 232     /*
 233      * Obtain this object's provider.  We override the superclass's method
 234      * to return a more specific subclass of OSObject -- an IOMedia.  This
 235      * method serves simply as a convenience to subclass developers.
 236      */
 237
 238     virtual IOMedia * getProvider() const;
 239
 240     OSMetaClassDeclareReservedUnused(IOPartitionScheme,  0);
 241     OSMetaClassDeclareReservedUnused(IOPartitionScheme,  1);
 242     OSMetaClassDeclareReservedUnused(IOPartitionScheme,  2);
 243     OSMetaClassDeclareReservedUnused(IOPartitionScheme,  3);
 244     OSMetaClassDeclareReservedUnused(IOPartitionScheme,  4);
 245     OSMetaClassDeclareReservedUnused(IOPartitionScheme,  5);
 246     OSMetaClassDeclareReservedUnused(IOPartitionScheme,  6);
 247     OSMetaClassDeclareReservedUnused(IOPartitionScheme,  7);
 248     OSMetaClassDeclareReservedUnused(IOPartitionScheme,  8);
 249     OSMetaClassDeclareReservedUnused(IOPartitionScheme,  9);
 250     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 10);
 251     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 11);
 252     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 12);
 253     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 13);
 254     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 14);
 255     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 15);
 256     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 16);
 257     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 17);
 258     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 18);
 259     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 19);
 260     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 20);
 261     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 21);
 262     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 22);
 263     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 23);
 264     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 24);
 265     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 25);
 266     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 26);
 267     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 27);
 268     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 28);
 269     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 29);
 270     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 30);
 271     OSMetaClassDeclareReservedUnused(IOPartitionScheme, 31);
 272 };
 273
 274 #endif /* defined(KERNEL) && defined(__cplusplus) */
 275
 276 #endif /* !_IOPARTITIONSCHEME_H */