| 1 | /*␊ |
| 2 | * Copyright (c) 1998-2009 Apple Inc. All rights reserved.␊ |
| 3 | *␊ |
| 4 | * @APPLE_LICENSE_HEADER_START@␊ |
| 5 | * ␊ |
| 6 | * This file contains Original Code and/or Modifications of Original Code␊ |
| 7 | * as defined in and that are subject to the Apple Public Source License␊ |
| 8 | * Version 2.0 (the 'License'). You may not use this file except in␊ |
| 9 | * compliance with the License. Please obtain a copy of the License at␊ |
| 10 | * http://www.opensource.apple.com/apsl/ and read it before using this␊ |
| 11 | * file.␊ |
| 12 | * ␊ |
| 13 | * The Original Code and all software distributed under the License are␊ |
| 14 | * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER␊ |
| 15 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,␊ |
| 16 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,␊ |
| 17 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.␊ |
| 18 | * Please see the License for the specific language governing rights and␊ |
| 19 | * limitations under the License.␊ |
| 20 | * ␊ |
| 21 | * @APPLE_LICENSE_HEADER_END@␊ |
| 22 | */␊ |
| 23 | ␊ |
| 24 | /*!␊ |
| 25 | * @header IOFilterScheme␊ |
| 26 | * @abstract␊ |
| 27 | * This header contains the IOFilterScheme class definition.␊ |
| 28 | */␊ |
| 29 | ␊ |
| 30 | #ifndef _IOFILTERSCHEME_H␊ |
| 31 | #define _IOFILTERSCHEME_H␊ |
| 32 | ␊ |
| 33 | /*!␊ |
| 34 | * @defined kIOFilterSchemeClass␊ |
| 35 | * @abstract␊ |
| 36 | * The name of the IOFilterScheme class.␊ |
| 37 | * @discussion␊ |
| 38 | * kIOFilterSchemeClass is the name of the IOFilterScheme class.␊ |
| 39 | */␊ |
| 40 | ␊ |
| 41 | #define kIOFilterSchemeClass "IOFilterScheme"␊ |
| 42 | ␊ |
| 43 | #ifdef KERNEL␊ |
| 44 | #ifdef __cplusplus␊ |
| 45 | ␊ |
| 46 | /*␊ |
| 47 | * Kernel␊ |
| 48 | */␊ |
| 49 | ␊ |
| 50 | #include <IOKit/storage/IOMedia.h>␊ |
| 51 | #include <IOKit/storage/IOStorage.h>␊ |
| 52 | ␊ |
| 53 | /*!␊ |
| 54 | * @class IOFilterScheme␊ |
| 55 | * @abstract␊ |
| 56 | * The common base class for all filter scheme␊ |
| 57 | * objects.␊ |
| 58 | * @discussion␊ |
| 59 | * The IOFilterScheme class is the common base class for all filter scheme␊ |
| 60 | * objects. It extends the IOStorage class by implementing the appropriate␊ |
| 61 | * open and close semantics for filter objects (standard semantics are act␊ |
| 62 | * as a relay for incoming opens, producing one outgoing open for each␊ |
| 63 | * incoming open). It also implements the default read and write semantics,␊ |
| 64 | * which pass all reads and writes through to the provider media unprocessed.␊ |
| 65 | * For simple schemes, the default behavior is sufficient. More complex␊ |
| 66 | * filter schemes such as RAID will want to do extra processing for reads␊ |
| 67 | * and writes.␊ |
| 68 | */␊ |
| 69 | ␊ |
| 70 | class IOFilterScheme : public IOStorage␊ |
| 71 | {␊ |
| 72 | OSDeclareDefaultStructors(IOFilterScheme);␊ |
| 73 | ␊ |
| 74 | protected:␊ |
| 75 | ␊ |
| 76 | struct ExpansionData { /* */ };␊ |
| 77 | ExpansionData * _expansionData;␊ |
| 78 | ␊ |
| 79 | /*!␊ |
| 80 | * @function handleOpen␊ |
| 81 | * @discussion␊ |
| 82 | * The handleOpen method grants or denies permission to access this object␊ |
| 83 | * to an interested client. The argument is an IOStorageAccess value that␊ |
| 84 | * specifies the level of access desired -- reader or reader-writer.␊ |
| 85 | *␊ |
| 86 | * This method can be invoked to upgrade or downgrade the access level for␊ |
| 87 | * an existing client as well. The previous access level will prevail for␊ |
| 88 | * upgrades that fail, of course. A downgrade should never fail. If the␊ |
| 89 | * new access level should be the same as the old for a given client, this␊ |
| 90 | * method will do nothing and return success. In all cases, one, singular␊ |
| 91 | * close-per-client is expected for all opens-per-client received.␊ |
| 92 | *␊ |
| 93 | * This implementation replaces the IOService definition of handleOpen().␊ |
| 94 | * @param client␊ |
| 95 | * Client requesting the open.␊ |
| 96 | * @param options␊ |
| 97 | * Options for the open. Set to zero.␊ |
| 98 | * @param access␊ |
| 99 | * Access level for the open. Set to kIOStorageAccessReader or␊ |
| 100 | * kIOStorageAccessReaderWriter.␊ |
| 101 | * @result␊ |
| 102 | * Returns true if the open was successful, false otherwise.␊ |
| 103 | */␊ |
| 104 | ␊ |
| 105 | virtual bool handleOpen(IOService * client,␊ |
| 106 | IOOptionBits options,␊ |
| 107 | void * access);␊ |
| 108 | ␊ |
| 109 | /*!␊ |
| 110 | * @function handleIsOpen␊ |
| 111 | * @discussion␊ |
| 112 | * The handleIsOpen method determines whether the specified client, or any␊ |
| 113 | * client if none is specified, presently has an open on this object.␊ |
| 114 | *␊ |
| 115 | * This implementation replaces the IOService definition of handleIsOpen().␊ |
| 116 | * @param client␊ |
| 117 | * Client to check the open state of. Set to zero to check the open state␊ |
| 118 | * of all clients.␊ |
| 119 | * @result␊ |
| 120 | * Returns true if the client was (or clients were) open, false otherwise.␊ |
| 121 | */␊ |
| 122 | ␊ |
| 123 | virtual bool handleIsOpen(const IOService * client) const;␊ |
| 124 | ␊ |
| 125 | /*!␊ |
| 126 | * @function handleClose␊ |
| 127 | * @discussion␊ |
| 128 | * The handleClose method closes the client's access to this object.␊ |
| 129 | *␊ |
| 130 | * This implementation replaces the IOService definition of handleClose().␊ |
| 131 | * @param client␊ |
| 132 | * Client requesting the close.␊ |
| 133 | * @param options␊ |
| 134 | * Options for the close. Set to zero.␊ |
| 135 | */␊ |
| 136 | ␊ |
| 137 | virtual void handleClose(IOService * client, IOOptionBits options);␊ |
| 138 | ␊ |
| 139 | public:␊ |
| 140 | ␊ |
| 141 | using IOStorage::read;␊ |
| 142 | using IOStorage::write;␊ |
| 143 | ␊ |
| 144 | /*!␊ |
| 145 | * @function read␊ |
| 146 | * @discussion␊ |
| 147 | * Read data from the storage object at the specified byte offset into the␊ |
| 148 | * specified buffer, asynchronously. When the read completes, the caller␊ |
| 149 | * will be notified via the specified completion action.␊ |
| 150 | *␊ |
| 151 | * The buffer will be retained for the duration of the read.␊ |
| 152 | *␊ |
| 153 | * For simple filter schemes, the default behavior is to simply pass the␊ |
| 154 | * read through to the provider media. More complex filter schemes such␊ |
| 155 | * as RAID will need to do extra processing here.␊ |
| 156 | * @param client␊ |
| 157 | * Client requesting the read.␊ |
| 158 | * @param byteStart␊ |
| 159 | * Starting byte offset for the data transfer.␊ |
| 160 | * @param buffer␊ |
| 161 | * Buffer for the data transfer. The size of the buffer implies the size of␊ |
| 162 | * the data transfer.␊ |
| 163 | * @param attributes␊ |
| 164 | * Attributes of the data transfer. See IOStorageAttributes. It is the␊ |
| 165 | * responsibility of the callee to maintain the information for the duration␊ |
| 166 | * of the data transfer, as necessary.␊ |
| 167 | * @param completion␊ |
| 168 | * Completion routine to call once the data transfer is complete. It is the␊ |
| 169 | * responsibility of the callee to maintain the information for the duration␊ |
| 170 | * of the data transfer, as necessary.␊ |
| 171 | */␊ |
| 172 | ␊ |
| 173 | virtual void read(IOService * client,␊ |
| 174 | UInt64 byteStart,␊ |
| 175 | IOMemoryDescriptor * buffer,␊ |
| 176 | IOStorageAttributes * attributes,␊ |
| 177 | IOStorageCompletion * completion);␊ |
| 178 | ␊ |
| 179 | /*!␊ |
| 180 | * @function write␊ |
| 181 | * @discussion␊ |
| 182 | * Write data into the storage object at the specified byte offset from the␊ |
| 183 | * specified buffer, asynchronously. When the write completes, the caller␊ |
| 184 | * will be notified via the specified completion action.␊ |
| 185 | *␊ |
| 186 | * The buffer will be retained for the duration of the write.␊ |
| 187 | *␊ |
| 188 | * For simple filter schemes, the default behavior is to simply pass the␊ |
| 189 | * write through to the provider media. More complex filter schemes such␊ |
| 190 | * as RAID will need to do extra processing here.␊ |
| 191 | * @param client␊ |
| 192 | * Client requesting the write.␊ |
| 193 | * @param byteStart␊ |
| 194 | * Starting byte offset for the data transfer.␊ |
| 195 | * @param buffer␊ |
| 196 | * Buffer for the data transfer. The size of the buffer implies the size of␊ |
| 197 | * the data transfer.␊ |
| 198 | * @param attributes␊ |
| 199 | * Attributes of the data transfer. See IOStorageAttributes. It is the␊ |
| 200 | * responsibility of the callee to maintain the information for the duration␊ |
| 201 | * of the data transfer, as necessary.␊ |
| 202 | * @param completion␊ |
| 203 | * Completion routine to call once the data transfer is complete. It is the␊ |
| 204 | * responsibility of the callee to maintain the information for the duration␊ |
| 205 | * of the data transfer, as necessary.␊ |
| 206 | */␊ |
| 207 | ␊ |
| 208 | virtual void write(IOService * client,␊ |
| 209 | UInt64 byteStart,␊ |
| 210 | IOMemoryDescriptor * buffer,␊ |
| 211 | IOStorageAttributes * attributes,␊ |
| 212 | IOStorageCompletion * completion);␊ |
| 213 | ␊ |
| 214 | /*!␊ |
| 215 | * @function synchronizeCache␊ |
| 216 | * @discussion␊ |
| 217 | * Flush the cached data in the storage object, if any, synchronously.␊ |
| 218 | * @param client␊ |
| 219 | * Client requesting the cache synchronization.␊ |
| 220 | * @result␊ |
| 221 | * Returns the status of the cache synchronization.␊ |
| 222 | */␊ |
| 223 | ␊ |
| 224 | virtual IOReturn synchronizeCache(IOService * client);␊ |
| 225 | ␊ |
| 226 | /*!␊ |
| 227 | * @function discard␊ |
| 228 | * @discussion␊ |
| 229 | * Delete unused data from the storage object at the specified byte offset,␊ |
| 230 | * synchronously.␊ |
| 231 | * @param client␊ |
| 232 | * Client requesting the operation.␊ |
| 233 | * @param byteStart␊ |
| 234 | * Starting byte offset for the operation.␊ |
| 235 | * @param byteCount␊ |
| 236 | * Size of the operation.␊ |
| 237 | * @result␊ |
| 238 | * Returns the status of the operation.␊ |
| 239 | */␊ |
| 240 | ␊ |
| 241 | virtual IOReturn discard(IOService * client,␊ |
| 242 | UInt64 byteStart,␊ |
| 243 | UInt64 byteCount);␊ |
| 244 | ␊ |
| 245 | /*␊ |
| 246 | * Obtain this object's provider. We override the superclass's method␊ |
| 247 | * to return a more specific subclass of OSObject -- an IOMedia. This␊ |
| 248 | * method serves simply as a convenience to subclass developers.␊ |
| 249 | */␊ |
| 250 | ␊ |
| 251 | virtual IOMedia * getProvider() const;␊ |
| 252 | ␊ |
| 253 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 0);␊ |
| 254 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 1);␊ |
| 255 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 2);␊ |
| 256 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 3);␊ |
| 257 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 4);␊ |
| 258 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 5);␊ |
| 259 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 6);␊ |
| 260 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 7);␊ |
| 261 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 8);␊ |
| 262 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 9);␊ |
| 263 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 10);␊ |
| 264 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 11);␊ |
| 265 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 12);␊ |
| 266 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 13);␊ |
| 267 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 14);␊ |
| 268 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 15);␊ |
| 269 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 16);␊ |
| 270 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 17);␊ |
| 271 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 18);␊ |
| 272 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 19);␊ |
| 273 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 20);␊ |
| 274 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 21);␊ |
| 275 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 22);␊ |
| 276 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 23);␊ |
| 277 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 24);␊ |
| 278 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 25);␊ |
| 279 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 26);␊ |
| 280 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 27);␊ |
| 281 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 28);␊ |
| 282 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 29);␊ |
| 283 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 30);␊ |
| 284 | OSMetaClassDeclareReservedUnused(IOFilterScheme, 31);␊ |
| 285 | };␊ |
| 286 | ␊ |
| 287 | #endif /* __cplusplus */␊ |
| 288 | #endif /* KERNEL */␊ |
| 289 | #endif /* !_IOFILTERSCHEME_H */␊ |
| 290 | |
