![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IODrive.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / XNU / iokit / IOKit / storage|
Return to IODrive.h CVS log | Up to [Apple XNU] / XNU / iokit / IOKit / storage |
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 IODrive ! 25: * @abstract ! 26: * This header contains the IODrive class definition. ! 27: */ ! 28: ! 29: #ifndef _IODRIVE_H ! 30: #define _IODRIVE_H ! 31: ! 32: /*! ! 33: * @defined kIODriveStatistics ! 34: * @abstract ! 35: * kIODriveStatistics is a property of IODrive objects. It is an OSDictionary. ! 36: * @discussion ! 37: * The kIODirectionStatistics property contains a table of statistics describing ! 38: * drive operations. All the different statistics are grouped under this table. ! 39: */ ! 40: ! 41: #define kIODriveStatistics "Statistics" ! 42: ! 43: /*! ! 44: * @defined kIODriveStatisticsBytesRead ! 45: * @abstract ! 46: * kIODriveStatisticsBytesRead is one of the statistic entries listed ! 47: * under the kIODriveStatistics property of IODrive objects. It is an OSNumber. ! 48: * @discussion ! 49: * The kIODriveStatisticsBytesRead property describes the number of ! 50: * bytes read since the drive object was instantiated. ! 51: */ ! 52: ! 53: #define kIODriveStatisticsBytesRead "Bytes (Read)" ! 54: ! 55: /*! ! 56: * @defined kIODriveStatisticsBytesWritten ! 57: * @abstract ! 58: * kIODriveStatisticsBytesWritten is one of the statistic entries listed ! 59: * under the kIODriveStatistics property of IODrive objects. It is an OSNumber. ! 60: * @discussion ! 61: * The kIODriveStatisticsBytesWritten property describes the number of ! 62: * bytes written since the drive object was instantiated. ! 63: */ ! 64: ! 65: #define kIODriveStatisticsBytesWritten "Bytes (Write)" ! 66: ! 67: /*! ! 68: * @defined kIODriveStatisticsReadErrors ! 69: * @abstract ! 70: * kIODriveStatisticsReadErrors is one of the statistic entries listed ! 71: * under the kIODriveStatistics property of IODrive objects. It is an OSNumber. ! 72: * @discussion ! 73: * The kIODriveStatisticsReadErrors property describes the number of ! 74: * read errors encountered since the drive object was instantiated. ! 75: */ ! 76: ! 77: #define kIODriveStatisticsReadErrors "Errors (Read)" ! 78: ! 79: /*! ! 80: * @defined kIODriveStatisticsWriteErrors ! 81: * @abstract ! 82: * kIODriveStatisticsWriteErrors is one of the statistic entries listed ! 83: * under the kIODriveStatistics property of IODrive objects. It is an OSNumber. ! 84: * @discussion ! 85: * The kIODriveStatisticsWriteErrors property describes the number of ! 86: * write errors encountered since the drive object was instantiated. ! 87: */ ! 88: ! 89: #define kIODriveStatisticsWriteErrors "Errors (Write)" ! 90: ! 91: /*! ! 92: * @defined kIODriveStatisticsLatentReadTime ! 93: * @abstract ! 94: * kIODriveStatisticsLatentReadTime is one of the statistic entries listed ! 95: * under the kIODriveStatistics property of IODrive objects. It is an OSNumber. ! 96: * @discussion ! 97: * The kIODriveStatisticsLatentReadTime property describes the number of ! 98: * nanoseconds of latency during reads since the drive object was instantiated. ! 99: */ ! 100: ! 101: #define kIODriveStatisticsLatentReadTime "Latency Time (Read)" ! 102: ! 103: /*! ! 104: * @defined kIODriveStatisticsLatentWriteTime ! 105: * @abstract ! 106: * kIODriveStatisticsLatentWriteTime is one of the statistic entries listed ! 107: * under the kIODriveStatistics property of IODrive objects. It is an OSNumber. ! 108: * @discussion ! 109: * The kIODriveStatisticsLatentWriteTime property describes the number of ! 110: * nanoseconds of latency during writes since the drive object was instantiated. ! 111: */ ! 112: ! 113: #define kIODriveStatisticsLatentWriteTime "Latency Time (Write)" ! 114: ! 115: /*! ! 116: * @defined kIODriveStatisticsReads ! 117: * @abstract ! 118: * kIODriveStatisticsReads is one of the statistic entries listed ! 119: * under the kIODriveStatistics property of IODrive objects. It is an OSNumber. ! 120: * @discussion ! 121: * The kIODriveStatisticsReads property describes the number of ! 122: * read operations processed since the drive object was instantiated. ! 123: */ ! 124: ! 125: #define kIODriveStatisticsReads "Operations (Read)" ! 126: ! 127: /*! ! 128: * @defined kIODriveStatisticsWrites ! 129: * @abstract ! 130: * kIODriveStatisticsWrites is one of the statistic entries listed ! 131: * under the kIODriveStatistics property of IODrive objects. It is an OSNumber. ! 132: * @discussion ! 133: * The kIODriveStatisticsWrites property describes the number of ! 134: * write operations processed since the drive object was instantiated. ! 135: */ ! 136: ! 137: #define kIODriveStatisticsWrites "Operations (Write)" ! 138: ! 139: /*! ! 140: * @defined kIODriveStatisticsReadRetries ! 141: * @abstract ! 142: * kIODriveStatisticsReadRetries is one of the statistic entries listed ! 143: * under the kIODriveStatistics property of IODrive objects. It is an OSNumber. ! 144: * @discussion ! 145: * The kIODriveStatisticsReadRetries property describes the number of ! 146: * read retries required since the drive object was instantiated. ! 147: */ ! 148: ! 149: #define kIODriveStatisticsReadRetries "Retries (Read)" ! 150: ! 151: /*! ! 152: * @defined kIODriveStatisticsWriteRetries ! 153: * @abstract ! 154: * kIODriveStatisticsWriteRetries is one of the statistic entries listed ! 155: * under the kIODriveStatistics property of IODrive objects. It is an OSNumber. ! 156: * @discussion ! 157: * The kIODriveStatisticsWriteRetries property describes the number of ! 158: * write retries required since the drive object was instantiated. ! 159: */ ! 160: ! 161: #define kIODriveStatisticsWriteRetries "Retries (Write)" ! 162: ! 163: /*! ! 164: * @defined kIODriveStatisticsTotalReadTime ! 165: * @abstract ! 166: * kIODriveStatisticsTotalReadTime is one of the statistic entries listed ! 167: * under the kIODriveStatistics property of IODrive objects. It is an OSNumber. ! 168: * @discussion ! 169: * The kIODriveStatisticsTotalReadTime property describes the number of ! 170: * nanoseconds spent performing reads since the drive object was instantiated. ! 171: */ ! 172: ! 173: #define kIODriveStatisticsTotalReadTime "Total Time (Read)" ! 174: ! 175: /*! ! 176: * @defined kIODriveStatisticsTotalWriteTime ! 177: * @abstract ! 178: * kIODriveStatisticsTotalWriteTime is one of the statistic entries listed ! 179: * under the kIODriveStatistics property of IODrive objects. It is an OSNumber. ! 180: * @discussion ! 181: * The kIODriveStatisticsTotalWriteTime property describes the number of ! 182: * nanoseconds spent performing writes since the drive object was instantiated. ! 183: */ ! 184: ! 185: #define kIODriveStatisticsTotalWriteTime "Total Time (Write)" ! 186: ! 187: /* ! 188: * Kernel ! 189: */ ! 190: ! 191: #if defined(KERNEL) && defined(__cplusplus) ! 192: ! 193: #include <IOKit/storage/IOStorage.h> ! 194: ! 195: /*! ! 196: * @class IODrive ! 197: * @abstract ! 198: * The IODrive class is the common base class for all disk drive objects. ! 199: * @discussion ! 200: * The IODrive class is the common base class for all disk drive objects. It ! 201: * extends the IOStorage class by implementing the appropriate open and close ! 202: * semantics for drive objects, deblocking for unaligned transfers, automatic ! 203: * polling for removable media, statistics gathering and reporting functions, ! 204: * and declaring the abstract APIs for media formatting, ejection and locking ! 205: * (removal prevention). ! 206: * ! 207: * There are more specific subclasses of IODrive which further implement the ! 208: * general semantics of hard disk drives (IOHDDrive), CD drives (IOCDDrive), ! 209: * and so on. ! 210: */ ! 211: ! 212: class IODrive : public IOStorage ! 213: { ! 214: OSDeclareAbstractStructors(IODrive); ! 215: ! 216: public: ! 217: ! 218: /*! ! 219: * @enum Statistics ! 220: * @discussion ! 221: * Indices for the different statistics that getStatistics() can report. ! 222: * @constant kStatisticsReads ! 223: * Number of read operations thus far. ! 224: * @constant kStatisticsSingleBlockReads ! 225: * Number of read operations for a single block thus far. ! 226: * @constant kStatisticsBytesRead ! 227: * Number of bytes read thus far. ! 228: * @constant kStatisticsTotalReadTime ! 229: * Nanoseconds spent performing reads thus far. ! 230: * @constant kStatisticsLatentReadTime ! 231: * Nanoseconds of latency during reads thus far. ! 232: * @constant kStatisticsReadRetries ! 233: * Number of read retries thus far. ! 234: * @constant kStatisticsReadErrors ! 235: * Number of read errors thus far. ! 236: * @constant kStatisticsWrites ! 237: * Number of write operations thus far. ! 238: * @constant kStatisticsSingleBlockWrites ! 239: * Number of write operations for a single block thus far. ! 240: * @constant kStatisticsBytesWritten ! 241: * Number of bytes written thus far. ! 242: * @constant kStatisticsTotalWriteTime ! 243: * Nanoseconds spent performing writes thus far. ! 244: * @constant kStatisticsLatentWriteTime ! 245: * Nanoseconds of latency during writes thus far. ! 246: * @constant kStatisticsWriteRetries ! 247: * Number of write retries thus far. ! 248: * @constant kStatisticsWriteErrors ! 249: * Number of write errors thus far. ! 250: */ ! 251: ! 252: enum Statistics ! 253: { ! 254: kStatisticsReads, ! 255: kStatisticsSingleBlockReads, ! 256: kStatisticsBytesRead, ! 257: kStatisticsTotalReadTime, ! 258: kStatisticsLatentReadTime, ! 259: kStatisticsReadRetries, ! 260: kStatisticsReadErrors, ! 261: ! 262: kStatisticsWrites, ! 263: kStatisticsSingleBlockWrites, ! 264: kStatisticsBytesWritten, ! 265: kStatisticsTotalWriteTime, ! 266: kStatisticsLatentWriteTime, ! 267: kStatisticsWriteRetries, ! 268: kStatisticsWriteErrors ! 269: }; ! 270: ! 271: static const UInt32 kStatisticsCount = kStatisticsWriteErrors + 1; ! 272: ! 273: /*! ! 274: * @enum IOMediaState ! 275: * @discussion ! 276: * The different states that getMediaState() can report. ! 277: * @constant kMediaOffline ! 278: * Media is not available. ! 279: * @constant kMediaOnline ! 280: * Media is available and ready for operations. ! 281: * @constant kMediaBusy ! 282: * Media is available, but not ready for operations. ! 283: */ ! 284: ! 285: enum IOMediaState ! 286: { ! 287: kMediaOffline, ! 288: kMediaOnline, ! 289: kMediaBusy ! 290: }; ! 291: ! 292: protected: ! 293: ! 294: OSSet * _openClients; ! 295: OSNumber * _statistics[kStatisticsCount]; ! 296: ! 297: /* ! 298: * Free all of this object's outstanding resources. ! 299: * ! 300: * This method's implementation is not typically overidden. ! 301: */ ! 302: ! 303: void free(); ! 304: ! 305: /*! ! 306: * @function handleOpen ! 307: * @discussion ! 308: * The handleOpen method grants or denies permission to access this object ! 309: * to an interested client. The argument is an IOStorageAccess value that ! 310: * specifies the level of access desired -- reader or reader-writer. ! 311: * ! 312: * This method can be invoked to upgrade or downgrade the access level for ! 313: * an existing client as well. The previous access level will prevail for ! 314: * upgrades that fail, of course. A downgrade should never fail. If the ! 315: * new access level should be the same as the old for a given client, this ! 316: * method will do nothing and return success. In all cases, one, singular ! 317: * close-per-client is expected for all opens-per-client received. ! 318: * ! 319: * This implementation replaces the IOService definition of handleIsOpen(). ! 320: * @param client ! 321: * Client requesting the open. ! 322: * @param options ! 323: * Options for the open. Set to zero. ! 324: * @param access ! 325: * Access level for the open. Set to kAccessReader or kAccessReaderWriter. ! 326: * @result ! 327: * Returns true if the open was successful, false otherwise. ! 328: */ ! 329: ! 330: virtual bool handleOpen(IOService * client, ! 331: IOOptionBits options, ! 332: void * access); ! 333: ! 334: /*! ! 335: * @function handleIsOpen ! 336: * @discussion ! 337: * The handleIsOpen method determines whether the specified client, or any ! 338: * client if none is specificed, presently has an open on this object. ! 339: * ! 340: * This implementation replaces the IOService definition of handleIsOpen(). ! 341: * @param client ! 342: * Client to check the open state of. Set to zero to check the open state ! 343: * of all clients. ! 344: * @result ! 345: * Returns true if the client was (or clients were) open, false otherwise. ! 346: */ ! 347: ! 348: virtual bool handleIsOpen(const IOService * client) const; ! 349: ! 350: /*! ! 351: * @function handleClose ! 352: * @discussion ! 353: * The handleClose method closes the client's access to this object. ! 354: * ! 355: * This implementation replaces the IOService definition of handleIsOpen(). ! 356: * @param client ! 357: * Client requesting the close. ! 358: * @param options ! 359: * Options for the close. Set to zero. ! 360: */ ! 361: ! 362: virtual void handleClose(IOService * client, IOOptionBits options); ! 363: ! 364: /*! ! 365: * @function addToBytesTransferred ! 366: * @discussion ! 367: * Update the total number of bytes transferred, the total transfer time, ! 368: * and the total latency time for this drive -- used for statistics. ! 369: * ! 370: * This method's implementation is not typically overidden. ! 371: * @param bytesTransferred ! 372: * Number of bytes transferred in this operation. ! 373: * @param totalTime ! 374: * Nanoseconds spent performing this operation. ! 375: * @param latentTime ! 376: * Nanoseconds of latency during this operation. ! 377: * @param isWrite ! 378: * Indicates whether this operation was a write, otherwise is was a read. ! 379: */ ! 380: ! 381: virtual void addToBytesTransferred(UInt64 bytesTransferred, ! 382: UInt64 totalTime, ! 383: UInt64 latentTime, ! 384: bool isWrite); ! 385: ! 386: /*! ! 387: * @function incrementErrors ! 388: * @discussion ! 389: * Update the total error count -- used for statistics. ! 390: * ! 391: * This method's implementation is not typically overidden. ! 392: * @param isWrite ! 393: * Indicates whether this operation was a write, otherwise is was a read. ! 394: */ ! 395: ! 396: virtual void incrementErrors(bool isWrite); ! 397: ! 398: /*! ! 399: * @function incrementRetries ! 400: * @discussion ! 401: * Update the total retry count -- used for statistics. ! 402: * ! 403: * This method's implementation is not typically overidden. ! 404: * @param isWrite ! 405: * Indicates whether this operation was a write, otherwise is was a read. ! 406: */ ! 407: ! 408: virtual void incrementRetries(bool isWrite); ! 409: ! 410: /*! ! 411: * @function deblockRequest ! 412: * @discussion ! 413: * The deblockRequest method checks to see if the incoming request rests ! 414: * on the media's block boundaries, and if not, deblocks it. Deblocking ! 415: * involves breaking up the request into sub-requests that rest on block ! 416: * boundaries, and performing the appropriate unaligned byte copies from ! 417: * the scratch buffer into into the client's request buffer. ! 418: * ! 419: * This method is part of a sequence of methods that are called for each ! 420: * read or write request. The first is deblockRequest, which aligns the ! 421: * request at the media's block boundaries; the second is prepareRequest, ! 422: * which prepares the memory involved in the transfer; and the third is ! 423: * executeRequest, which implements the actual transfer from the drive. ! 424: * ! 425: * This method's implementation is not typically overidden. ! 426: * @param byteStart ! 427: * Starting byte offset for the data transfer. ! 428: * @param buffer ! 429: * Buffer for the data transfer. The size of the buffer implies the size of ! 430: * the data transfer. ! 431: * @param completion ! 432: * Completion routine to call once the data transfer is complete. ! 433: */ ! 434: ! 435: virtual void deblockRequest(UInt64 byteStart, ! 436: IOMemoryDescriptor * buffer, ! 437: IOStorageCompletion completion); ! 438: ! 439: /*! ! 440: * @function prepareRequest ! 441: * @discussion ! 442: * The prepareRequest method prepares the memory involved in the transfer. ! 443: * The memory will be wired down, physically mapped, and broken up based ! 444: * on the controller's and drive's constraints. ! 445: * ! 446: * This method is part of a sequence of methods that are called for each ! 447: * read or write request. The first is deblockRequest, which aligns the ! 448: * request at the media's block boundaries; the second is prepareRequest, ! 449: * which prepares the buffer involved in the transfer; and the third is ! 450: * executeRequest, which implements the actual transfer from the drive. ! 451: * ! 452: * This method's implementation is not typically overidden. ! 453: * @param byteStart ! 454: * Starting byte offset for the data transfer. ! 455: * @param buffer ! 456: * Buffer for the data transfer. The size of the buffer implies the size of ! 457: * the data transfer. ! 458: * @param completion ! 459: * Completion routine to call once the data transfer is complete. ! 460: */ ! 461: ! 462: virtual void prepareRequest(UInt64 byteStart, ! 463: IOMemoryDescriptor * buffer, ! 464: IOStorageCompletion completion); ! 465: ! 466: /*! ! 467: * @function executeRequest ! 468: * @discussion ! 469: * Execute the specified storage request. The request is guaranteed to ! 470: * be block-aligned, and to have a memory buffer that is wired, mapped, ! 471: * and is constrained according to the controller's and drive's limits. ! 472: * ! 473: * This method is part of a sequence of methods that are called for each ! 474: * read or write request. The first is deblockRequest, which aligns the ! 475: * request at the media's block boundaries; the second is prepareRequest, ! 476: * which prepares the buffer involved in the transfer; and the third is ! 477: * executeRequest, which implements the actual transfer from the drive. ! 478: * ! 479: * When implementing this abstract method, it is important to remember ! 480: * that the buffer must be retained while the asynchronous operation is ! 481: * being processed, as per regular I/O Kit object-passing semantics. ! 482: * @param byteStart ! 483: * Starting byte offset for the data transfer. ! 484: * @param buffer ! 485: * Buffer for the data transfer. The size of the buffer implies the size of ! 486: * the data transfer. ! 487: * @param completion ! 488: * Completion routine to call once the data transfer is complete. ! 489: */ ! 490: ! 491: virtual void executeRequest(UInt64 byteStart, ! 492: IOMemoryDescriptor * buffer, ! 493: IOStorageCompletion completion) = 0; ! 494: ! 495: /*! ! 496: * @function handleStart ! 497: * @discussion ! 498: * Prepare the drive for operation. ! 499: * ! 500: * This is where a media object needs to be created for fixed media, and ! 501: * optionally for removable media. For removable media, the poller will ! 502: * issue handlePoll() once a second, so the creation of the media object ! 503: * could be delayed until then if you wish. ! 504: * ! 505: * Note that this method is called from the superclass' start() routine; ! 506: * if this method returns successfully, it should be prepared to accept ! 507: * any of IODrive's abstract methods. ! 508: * @param provider ! 509: * This object's provider. ! 510: * @result ! 511: * Returns true on success, false otherwise. ! 512: */ ! 513: ! 514: virtual bool handleStart(IOService * provider) = 0; ! 515: ! 516: /*! ! 517: * @function handleStop ! 518: * @discussion ! 519: * Stop the drive. ! 520: * ! 521: * This is where the driver should clean up its state in preparation for ! 522: * removal from the system. ! 523: * ! 524: * Note that this method is called from the superclass' stop() routine. ! 525: * @param provider ! 526: * This object's provider. ! 527: */ ! 528: ! 529: virtual void handleStop(IOService * provider) = 0; ! 530: ! 531: /*! ! 532: * @function getMediaBlockSize ! 533: * @discussion ! 534: * Ask the drive about the media's actual block size. ! 535: * @result ! 536: * Natural block size, in bytes. ! 537: */ ! 538: ! 539: virtual inline UInt64 getMediaBlockSize() const = 0; ! 540: ! 541: public: ! 542: ! 543: ///m:2333367:workaround:commented:start ! 544: // IOStorage::open; ! 545: // IOStorage::close; ! 546: // IOStorage::read; ! 547: // IOStorage::write; ! 548: ///m:2333367:workaround:commented:stop ! 549: ! 550: /* ! 551: * Initialize this object's minimal state. ! 552: * ! 553: * This method's implementation is not typically overidden. ! 554: */ ! 555: ! 556: virtual bool init(OSDictionary * properties = 0); ! 557: ! 558: /* ! 559: * This method is called once we have been attached to the provider object. ! 560: * ! 561: * This method's implementation is not typically overidden. ! 562: */ ! 563: ! 564: virtual bool start(IOService * provider); ! 565: ! 566: /* ! 567: * This method is called before we are detached from the provider object. ! 568: * ! 569: * This method's implementation is not typically overidden. ! 570: */ ! 571: ! 572: virtual void stop(IOService * provider); ! 573: ! 574: /*! ! 575: * @function read ! 576: * @discussion ! 577: * The read method is the receiving end for all read requests from the ! 578: * storage framework, that is, the child storage objects of this drive. ! 579: * ! 580: * This method kicks off a sequence of methods which are called for each ! 581: * read or write request. The first is deblockRequest, which aligns the ! 582: * request at the media's block boundaries; the second is prepareRequest, ! 583: * which prepares the buffer involved in the transfer; and the third is ! 584: * executeRequest, which implements the actual transfer from the drive. ! 585: * ! 586: * This method's implementation is not typically overidden. ! 587: * @param client ! 588: * Client requesting the read. ! 589: * @param byteStart ! 590: * Starting byte offset for the data transfer. ! 591: * @param buffer ! 592: * Buffer for the data transfer. The size of the buffer implies the size of ! 593: * the data transfer. ! 594: * @param completion ! 595: * Completion routine to call once the data transfer is complete. ! 596: */ ! 597: ! 598: virtual void read(IOService * client, ! 599: UInt64 byteStart, ! 600: IOMemoryDescriptor * buffer, ! 601: IOStorageCompletion completion); ! 602: ! 603: /*! ! 604: * @function write ! 605: * @discussion ! 606: * The write method is the receiving end for all write requests from the ! 607: * storage framework, that is, the child storage objects of this drive. ! 608: * ! 609: * This method kicks off a sequence of methods which are called for each ! 610: * read or write request. The first is deblockRequest, which aligns the ! 611: * request at the media's block boundaries; the second is prepareRequest, ! 612: * which prepares the buffer involved in the transfer; and the third is ! 613: * executeRequest, which implements the actual transfer from the drive. ! 614: * ! 615: * This method's implementation is not typically overidden. ! 616: * @param client ! 617: * Client requesting the write. ! 618: * @param byteStart ! 619: * Starting byte offset for the data transfer. ! 620: * @param buffer ! 621: * Buffer for the data transfer. The size of the buffer implies the size of ! 622: * the data transfer. ! 623: * @param completion ! 624: * Completion routine to call once the data transfer is complete. ! 625: */ ! 626: ! 627: virtual void write(IOService * client, ! 628: UInt64 byteStart, ! 629: IOMemoryDescriptor * buffer, ! 630: IOStorageCompletion completion); ! 631: ! 632: /*! ! 633: * @function ejectMedia ! 634: * @discussion ! 635: * Eject the media from the drive. The drive object is responsible for ! 636: * tearing down the child storage objects it created before proceeding ! 637: * with the eject. If the teardown fails, an error should be returned. ! 638: * @result ! 639: * An IOReturn code. ! 640: */ ! 641: ! 642: virtual IOReturn ejectMedia() = 0; ! 643: ! 644: /*! ! 645: * @function formatMedia ! 646: * @discussion ! 647: * Format the media in the drive with the specified byte capacity. The ! 648: * drive object is responsible for tearing down the child storage objects ! 649: * and recreating them, if applicable. ! 650: * @param byteCapacity ! 651: * Number of bytes to format media to. ! 652: * @result ! 653: * An IOReturn code. ! 654: */ ! 655: ! 656: virtual IOReturn formatMedia(UInt64 byteCapacity) = 0; ! 657: ! 658: /*! ! 659: * @function lockMedia ! 660: * @discussion ! 661: * Lock or unlock the ejectable media in the drive, that is, prevent ! 662: * it from manual ejection or allow its manual ejection. ! 663: * @param lock ! 664: * Pass true to lock the media, otherwise pass false to unlock the media. ! 665: * @result ! 666: * An IOReturn code. ! 667: */ ! 668: ! 669: virtual IOReturn lockMedia(bool lock) = 0; ! 670: ! 671: /*! ! 672: * @function pollMedia ! 673: * @discussion ! 674: * Poll for the presence of media in the drive. The drive object is ! 675: * responsible for tearing down the child storage objects it created ! 676: * should the media have been removed since the last poll, and vice- ! 677: * versa, creating the child storage objects should new media have ! 678: * arrived since the last poll. ! 679: * @result ! 680: * An IOReturn code. ! 681: */ ! 682: ! 683: virtual IOReturn pollMedia() = 0; ! 684: ! 685: /*! ! 686: * @function isMediaEjectable ! 687: * @discussion ! 688: * Ask the drive whether it contains ejectable media. ! 689: * @result ! 690: * Returns true if the media is ejectable, false otherwise. ! 691: */ ! 692: ! 693: virtual bool isMediaEjectable() const = 0; ! 694: ! 695: /*! ! 696: * @function isMediaPollExpensive ! 697: * @discussion ! 698: * Ask the drive whether it a pollMedia would be an expensive operation, ! 699: * that is, one that requires the drive to spin up or delay for a while. ! 700: * @result ! 701: * Returns true if polling the media is expensive, false otherwise. ! 702: */ ! 703: ! 704: virtual bool isMediaPollExpensive() const = 0; ! 705: ! 706: /*! ! 707: * @function isMediaPollRequired ! 708: * @discussion ! 709: * Ask the drive whether it requires polling, which is typically required ! 710: * for drives with ejectable media without the ability to asynchronously ! 711: * detect the arrival or departure of the media. ! 712: * @result ! 713: * Returns true if polling the media is required, false otherwise. ! 714: */ ! 715: ! 716: virtual bool isMediaPollRequired() const = 0; ! 717: ! 718: /*! ! 719: * @function getMediaState ! 720: * @discussion ! 721: * Ask the drive about the media's current state. ! 722: * @result ! 723: * An IOMediaState value. ! 724: */ ! 725: ! 726: virtual IOMediaState getMediaState() const = 0; ! 727: ! 728: /*! ! 729: * @function getFormatCapacities ! 730: * @discussion ! 731: * Ask the drive to report the feasible formatting capacities for the ! 732: * inserted media (in bytes). This routine fills the caller's buffer, ! 733: * up to the maximum count specified if the real number of capacities ! 734: * would overflow the buffer. The return value indicates the actual ! 735: * number of capacities copied to the buffer. ! 736: * ! 737: * If the capacities buffer is not supplied or if the maximum count is ! 738: * zero, the routine returns the proposed count of capacities instead. ! 739: * @param capacities ! 740: * Buffer that will receive the UInt64 capacity values. ! 741: * @param capacitiesMaxCount ! 742: * Maximum number of capacity values that can be held in the buffer. ! 743: * @result ! 744: * Actual number of capacity values copied to the buffer, or if no buffer ! 745: * is given, the total number of capacity values available. ! 746: */ ! 747: ! 748: virtual UInt32 getFormatCapacities(UInt64 * capacities, ! 749: UInt32 capacitiesMaxCount) const = 0; ! 750: ! 751: /*! ! 752: * @function getStatistics ! 753: * @discussion ! 754: * Ask the drive to report its operating statistics. The statistics are ! 755: * described by the IODrive::Statistics indices. This routine fills the ! 756: * caller's buffer, up to the maximum count specified if the real number ! 757: * of statistics would overflow the buffer. The return value indicates ! 758: * the actual number of statistics copied to the buffer. ! 759: * ! 760: * If the statistics buffer is not supplied or if the maximum count is ! 761: * zero, the routine returns the proposed count of statistics instead. ! 762: * @param statistics ! 763: * Buffer that will receive the UInt64 statistic values. ! 764: * @param statisticsMaxCount ! 765: * Maximum number of statistic values that can be held in the buffer. ! 766: * @result ! 767: * Actual number of statistic values copied to the buffer, or if no buffer ! 768: * is given, the total number of statistic values available. ! 769: */ ! 770: ! 771: virtual UInt32 getStatistics(UInt64 * statistics, ! 772: UInt32 statisticsMaxCount) const; ! 773: ! 774: /*! ! 775: * @function getStatistic ! 776: * @discussion ! 777: * Ask the drive to report one of its operating statistics. ! 778: * @param statistic ! 779: * Statistic index (an IODrive::Statistics index). ! 780: * @result ! 781: * Statistic value. ! 782: */ ! 783: ! 784: virtual UInt64 getStatistic(Statistics statistic) const; ! 785: ! 786: protected: ! 787: ! 788: /* ! 789: * Definitions for the default deblocker implementation. ! 790: */ ! 791: ! 792: enum DeblockerPhase ! 793: { ! 794: kPhaseBegin, ! 795: kPhaseStart, ! 796: kPhaseMiddle, ! 797: kPhaseFinal, ! 798: kPhaseDone, ! 799: ! 800: kPhaseBeginRMW, ! 801: kPhaseStartRM, ! 802: kPhaseStartW, ! 803: kPhaseMiddleW, ! 804: kPhaseFinalRM, ! 805: kPhaseFinalW ! 806: }; ! 807: ! 808: struct DeblockerContext ! 809: { ! 810: struct ! 811: { ! 812: UInt64 byteStart; ! 813: IOMemoryDescriptor * buffer; ! 814: IOStorageCompletion completion; ! 815: } subrequest; ! 816: ! 817: UInt64 offsetStart; ! 818: UInt64 bytesStart; ! 819: UInt64 bytesMiddle; ! 820: UInt64 bytesFinal; ! 821: ! 822: IOMemoryDescriptor * blockBuffer; ! 823: UInt8 * blockBufferPtr; ! 824: ! 825: IOMemoryDescriptor * middleBuffer; ! 826: ! 827: UInt64 bytesTransferred; ! 828: ! 829: struct ! 830: { ! 831: UInt64 byteStart; ! 832: IOMemoryDescriptor * buffer; ! 833: IOStorageCompletion completion; ! 834: } originalRequest; ! 835: ! 836: DeblockerPhase phase; ! 837: }; ! 838: ! 839: IOLock * _deblockerLockForRMWs; ! 840: ! 841: /* ! 842: * Allocate a deblocker context structure. It comes preinitialized with ! 843: * a block-sized scratch buffer and an associated memory descriptor, but ! 844: * is otherwise uninitialized. ! 845: */ ! 846: ! 847: DeblockerContext * deblockerContextAllocate(); ! 848: ! 849: /* ! 850: * Deallocate a deblocker context structure. The block-sized scratch ! 851: * buffer and memory descriptor is automatically deallocated as well. ! 852: */ ! 853: ! 854: void deblockerContextFree(DeblockerContext * deblockContext); ! 855: ! 856: /* ! 857: * This is the completion routine for the aligned deblocker subrequests. ! 858: * It performs work on the just-completed phase, if any, transitions to ! 859: * the next phase, then builds and issues a transfer for the next phase. ! 860: */ ! 861: ! 862: static void deblockerCompletion(void * target, ! 863: void * parameter, ! 864: IOReturn status, ! 865: UInt64 actualByteCount); ! 866: ! 867: /* ! 868: * Schedule the poller mechanism. ! 869: */ ! 870: ! 871: void schedulePoller(); ! 872: ! 873: /* ! 874: * Unschedule the poller mechanism. ! 875: */ ! 876: ! 877: void unschedulePoller(); ! 878: ! 879: /* ! 880: * This method is the timeout handler for the poller mechanism. It polls ! 881: * for media and reschedules another timeout if the drive is still closed. ! 882: */ ! 883: ! 884: static void poller(void *, void *); ! 885: }; ! 886: ! 887: #endif /* defined(KERNEL) && defined(__cplusplus) */ ! 888: ! 889: #endif /* !_IODRIVE_H */
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.