1/* 2 * Copyright (c) 1998-2014 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 70class IOFilterScheme : public IOStorage 71{ 72 OSDeclareDefaultStructors(IOFilterScheme); 73 74protected: 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 139public: 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 unmap 228 * @discussion 229 * Delete unused data from the storage object at the specified byte offsets, 230 * synchronously. 231 * @param client 232 * Client requesting the operation. 233 * @param extents 234 * List of extents. See IOStorageExtent. It is legal for the callee to 235 * overwrite the contents of this buffer in order to satisfy the request. 236 * @param extentsCount 237 * Number of extents. 238 * @result 239 * Returns the status of the operation. 240 */ 241 242 virtual IOReturn unmap(IOService * client, 243 IOStorageExtent * extents, 244 UInt32 extentsCount, 245 UInt32 options = 0); 246 247 /*! 248 * @function lockPhysicalExtents 249 * @discussion 250 * Lock the contents of the storage object against relocation temporarily, 251 * for the purpose of getting physical extents. 252 * @param client 253 * Client requesting the operation. 254 * @result 255 * Returns true if the lock was successful, false otherwise. 256 */ 257 258 virtual bool lockPhysicalExtents(IOService * client); 259 260 /*! 261 * @function copyPhysicalExtent 262 * @discussion 263 * Convert the specified byte offset into a physical byte offset, relative 264 * to a physical storage object. This call should only be made within the 265 * context of lockPhysicalExtents(). 266 * @param client 267 * Client requesting the operation. 268 * @param byteStart 269 * Starting byte offset for the operation. Returns a physical byte offset, 270 * relative to the physical storage object, on success. 271 * @param byteCount 272 * Size of the operation. Returns the actual number of bytes which can be 273 * transferred, relative to the physical storage object, on success. 274 * @result 275 * A reference to the physical storage object, which should be released by 276 * the caller, or a null on error. 277 */ 278 279 virtual IOStorage * copyPhysicalExtent(IOService * client, 280 UInt64 * byteStart, 281 UInt64 * byteCount); 282 283 /*! 284 * @function unlockPhysicalExtents 285 * @discussion 286 * Unlock the contents of the storage object for relocation again. This 287 * call must balance a successful call to lockPhysicalExtents(). 288 * @param client 289 * Client requesting the operation. 290 */ 291 292 virtual void unlockPhysicalExtents(IOService * client); 293 294 /*! 295 * @function setPriority 296 * @discussion 297 * Reprioritize read or write requests at the specified byte offsets. 298 * @param client 299 * Client requesting the operation. 300 * @param extents 301 * List of extents. See IOStorageExtent. It is legal for the callee to 302 * overwrite the contents of this buffer in order to satisfy the request. 303 * @param extentsCount 304 * Number of extents. 305 * @param priority 306 * New priority. See IOStoragePriority. 307 * @result 308 * Returns the status of the operation. 309 */ 310 311 virtual IOReturn setPriority(IOService * client, 312 IOStorageExtent * extents, 313 UInt32 extentsCount, 314 IOStoragePriority priority); 315 316 /* 317 * Obtain this object's provider. We override the superclass's method 318 * to return a more specific subclass of OSObject -- an IOMedia. This 319 * method serves simply as a convenience to subclass developers. 320 */ 321 322 virtual IOMedia * getProvider() const; 323 324 OSMetaClassDeclareReservedUnused(IOFilterScheme, 0); 325 OSMetaClassDeclareReservedUnused(IOFilterScheme, 1); 326 OSMetaClassDeclareReservedUnused(IOFilterScheme, 2); 327 OSMetaClassDeclareReservedUnused(IOFilterScheme, 3); 328 OSMetaClassDeclareReservedUnused(IOFilterScheme, 4); 329 OSMetaClassDeclareReservedUnused(IOFilterScheme, 5); 330 OSMetaClassDeclareReservedUnused(IOFilterScheme, 6); 331 OSMetaClassDeclareReservedUnused(IOFilterScheme, 7); 332 OSMetaClassDeclareReservedUnused(IOFilterScheme, 8); 333 OSMetaClassDeclareReservedUnused(IOFilterScheme, 9); 334 OSMetaClassDeclareReservedUnused(IOFilterScheme, 10); 335 OSMetaClassDeclareReservedUnused(IOFilterScheme, 11); 336 OSMetaClassDeclareReservedUnused(IOFilterScheme, 12); 337 OSMetaClassDeclareReservedUnused(IOFilterScheme, 13); 338 OSMetaClassDeclareReservedUnused(IOFilterScheme, 14); 339 OSMetaClassDeclareReservedUnused(IOFilterScheme, 15); 340 OSMetaClassDeclareReservedUnused(IOFilterScheme, 16); 341 OSMetaClassDeclareReservedUnused(IOFilterScheme, 17); 342 OSMetaClassDeclareReservedUnused(IOFilterScheme, 18); 343 OSMetaClassDeclareReservedUnused(IOFilterScheme, 19); 344 OSMetaClassDeclareReservedUnused(IOFilterScheme, 20); 345 OSMetaClassDeclareReservedUnused(IOFilterScheme, 21); 346 OSMetaClassDeclareReservedUnused(IOFilterScheme, 22); 347 OSMetaClassDeclareReservedUnused(IOFilterScheme, 23); 348 OSMetaClassDeclareReservedUnused(IOFilterScheme, 24); 349 OSMetaClassDeclareReservedUnused(IOFilterScheme, 25); 350 OSMetaClassDeclareReservedUnused(IOFilterScheme, 26); 351 OSMetaClassDeclareReservedUnused(IOFilterScheme, 27); 352 OSMetaClassDeclareReservedUnused(IOFilterScheme, 28); 353 OSMetaClassDeclareReservedUnused(IOFilterScheme, 29); 354 OSMetaClassDeclareReservedUnused(IOFilterScheme, 30); 355 OSMetaClassDeclareReservedUnused(IOFilterScheme, 31); 356}; 357 358#endif /* __cplusplus */ 359#endif /* KERNEL */ 360#endif /* !_IOFILTERSCHEME_H */ 361