1/* 2 * Copyright (c) 1998-2013 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 IOBlockStorageDriver 26 * @abstract 27 * This header contains the IOBlockStorageDriver class definition. 28 */ 29 30#ifndef _IOBLOCKSTORAGEDRIVER_H 31#define _IOBLOCKSTORAGEDRIVER_H 32 33#include <IOKit/IOTypes.h> 34 35/*! 36 * @defined kIOBlockStorageDriverClass 37 * @abstract 38 * The name of the IOBlockStorageDriver class. 39 */ 40 41#define kIOBlockStorageDriverClass "IOBlockStorageDriver" 42 43/*! 44 * @defined kIOBlockStorageDriverStatisticsKey 45 * @abstract 46 * Holds a table of numeric values describing the driver's 47 * operating statistics. 48 * @discussion 49 * This property holds a table of numeric values describing the driver's 50 * operating statistics. The table is an OSDictionary, where each entry 51 * describes one given statistic. 52 */ 53 54#define kIOBlockStorageDriverStatisticsKey "Statistics" 55 56/*! 57 * @defined kIOBlockStorageDriverStatisticsBytesReadKey 58 * @abstract 59 * Describes the number of bytes read since the block storage 60 * driver was instantiated. 61 * @discussion 62 * This property describes the number of bytes read since the block storage 63 * driver was instantiated. It is one of the statistic entries listed under 64 * the top-level kIOBlockStorageDriverStatisticsKey property table. It has 65 * an OSNumber value. 66 */ 67 68#define kIOBlockStorageDriverStatisticsBytesReadKey "Bytes (Read)" 69 70/*! 71 * @defined kIOBlockStorageDriverStatisticsBytesWrittenKey 72 * @abstract 73 * Describes the number of bytes written since the block storage 74 * driver was instantiated. 75 * @discussion 76 * This property describes the number of bytes written since the block storage 77 * driver was instantiated. It is one of the statistic entries listed under the 78 * top-level kIOBlockStorageDriverStatisticsKey property table. It has an 79 * OSNumber value. 80 */ 81 82#define kIOBlockStorageDriverStatisticsBytesWrittenKey "Bytes (Write)" 83 84/*! 85 * @defined kIOBlockStorageDriverStatisticsReadErrorsKey 86 * @abstract 87 * Describes the number of read errors encountered since the block 88 * storage driver was instantiated. 89 * @discussion 90 * This property describes the number of read errors encountered since the block 91 * storage driver was instantiated. It is one of the statistic entries listed 92 * under the top-level kIOBlockStorageDriverStatisticsKey property table. It 93 * has an OSNumber value. 94 */ 95 96#define kIOBlockStorageDriverStatisticsReadErrorsKey "Errors (Read)" 97 98/*! 99 * @defined kIOBlockStorageDriverStatisticsWriteErrorsKey 100 * @abstract 101 * Describes the number of write errors encountered since the 102 * block storage driver was instantiated. 103 * @discussion 104 * This property describes the number of write errors encountered since the 105 * block storage driver was instantiated. It is one of the statistic entries 106 * listed under the top-level kIOBlockStorageDriverStatisticsKey property table. 107 * It has an OSNumber value. 108 */ 109 110#define kIOBlockStorageDriverStatisticsWriteErrorsKey "Errors (Write)" 111 112/*! 113 * @defined kIOBlockStorageDriverStatisticsLatentReadTimeKey 114 * @abstract 115 * Describes the number of nanoseconds of latency during reads 116 * since the block storage driver was instantiated. 117 * @discussion 118 * This property describes the number of nanoseconds of latency during reads 119 * since the block storage driver was instantiated. It is one of the statistic 120 * entries listed under the top-level kIOBlockStorageDriverStatisticsKey 121 * property table. It has an OSNumber value. 122 */ 123 124#define kIOBlockStorageDriverStatisticsLatentReadTimeKey "Latency Time (Read)" 125 126/*! 127 * @defined kIOBlockStorageDriverStatisticsLatentWriteTimeKey 128 * @abstract 129 * Describes the number of nanoseconds of latency during writes 130 * since the block storage driver was instantiated. 131 * @discussion 132 * This property describes the number of nanoseconds of latency during writes 133 * since the block storage driver was instantiated. It is one of the statistic 134 * entries listed under the top-level kIOBlockStorageDriverStatisticsKey 135 * property table. It has an OSNumber value. 136 */ 137 138#define kIOBlockStorageDriverStatisticsLatentWriteTimeKey "Latency Time (Write)" 139 140/*! 141 * @defined kIOBlockStorageDriverStatisticsReadsKey 142 * @abstract 143 * Describes the number of read operations processed since the 144 * block storage driver was instantiated. 145 * @discussion 146 * This property describes the number of read operations processed since the 147 * block storage driver was instantiated. It is one of the statistic entries 148 * listed under the top-level kIOBlockStorageDriverStatisticsKey property table. 149 * It has an OSNumber value. 150 */ 151 152#define kIOBlockStorageDriverStatisticsReadsKey "Operations (Read)" 153 154/*! 155 * @defined kIOBlockStorageDriverStatisticsWritesKey 156 * @abstract 157 * Describes the number of write operations processed since the 158 * block storage driver was instantiated. 159 * @discussion 160 * This property describes the number of write operations processed since the 161 * block storage driver was instantiated. It is one of the statistic entries 162 * listed under the top-level kIOBlockStorageDriverStatisticsKey property table. 163 * It has an OSNumber value. 164 */ 165 166#define kIOBlockStorageDriverStatisticsWritesKey "Operations (Write)" 167 168/*! 169 * @defined kIOBlockStorageDriverStatisticsReadRetriesKey 170 * @abstract 171 * Describes the number of read retries required since the block 172 * storage driver was instantiated. 173 * @discussion 174 * This property describes the number of read retries required since the block 175 * storage driver was instantiated. It is one of the statistic entries listed 176 * under the top-level kIOBlockStorageDriverStatisticsKey property table. It 177 * has an OSNumber value. 178 */ 179 180#define kIOBlockStorageDriverStatisticsReadRetriesKey "Retries (Read)" 181 182/*! 183 * @defined kIOBlockStorageDriverStatisticsWriteRetriesKey 184 * @abstract 185 * Describes the number of write retries required since the block 186 * storage driver was instantiated. 187 * @discussion 188 * This property describes the number of write retries required since the block 189 * storage driver was instantiated. It is one of the statistic entries listed 190 * under the top-level kIOBlockStorageDriverStatisticsKey property table. It 191 * has an OSNumber value. 192 */ 193 194#define kIOBlockStorageDriverStatisticsWriteRetriesKey "Retries (Write)" 195 196/*! 197 * @defined kIOBlockStorageDriverStatisticsTotalReadTimeKey 198 * @abstract 199 * Describes the number of nanoseconds spent performing reads 200 * since the block storage driver was instantiated. 201 * @discussion 202 * This property describes the number of nanoseconds spent performing reads 203 * since the block storage driver was instantiated. It is one of the statistic 204 * entries listed under the top-level kIOBlockStorageDriverStatisticsKey 205 * property table. It has an OSNumber value. 206 */ 207 208#define kIOBlockStorageDriverStatisticsTotalReadTimeKey "Total Time (Read)" 209 210/*! 211 * @defined kIOBlockStorageDriverStatisticsTotalWriteTimeKey 212 * @abstract 213 * Describes the number of nanoseconds spent performing writes 214 * since the block storage driver was instantiated. 215 * @discussion 216 * This property describes the number of nanoseconds spent performing writes 217 * since the block storage driver was instantiated. It is one of the statistic 218 * entries listed under the top-level kIOBlockStorageDriverStatisticsKey 219 * property table. It has an OSNumber value. 220 */ 221 222#define kIOBlockStorageDriverStatisticsTotalWriteTimeKey "Total Time (Write)" 223 224/*! 225 * @enum IOMediaState 226 * @abstract 227 * The different states that getMediaState() can report. 228 * @constant kIOMediaStateOffline 229 * Media is not available. 230 * @constant kIOMediaStateOnline 231 * Media is available and ready for operations. 232 * @constant kIOMediaStateBusy 233 * Media is available, but not ready for operations. 234 */ 235 236enum 237{ 238 kIOMediaStateOffline = 0, 239 kIOMediaStateOnline = 1, 240 kIOMediaStateBusy = 2 241}; 242 243typedef UInt32 IOMediaState; 244 245#ifdef KERNEL 246#ifdef __cplusplus 247 248/* 249 * Kernel 250 */ 251 252#include <IOKit/storage/IOBlockStorageDevice.h> 253#include <IOKit/storage/IOMedia.h> 254#include <IOKit/storage/IOStorage.h> 255 256/*! 257 * @class IOBlockStorageDriver 258 * @abstract 259 * The common base class for generic block storage drivers. 260 * @discussion 261 * The IOBlockStorageDriver class is the common base class for generic block 262 * storage drivers. It matches and communicates via an IOBlockStorageDevice 263 * interface, and connects to the remainder of the storage framework via the 264 * IOStorage protocol. It extends the IOStorage protocol by implementing the 265 * appropriate open and close semantics, deblocking for unaligned transfers, 266 * polling for ejectable media, locking and ejection policies, media object 267 * creation and tear-down, and statistics gathering and reporting. 268 * 269 * Block storage drivers are split into two parts: the generic driver handles 270 * all generic device issues, independent of the lower-level transport 271 * mechanism (e.g. SCSI, ATA, USB, FireWire). All storage operations 272 * at the generic driver level are translated into a series of generic 273 * device operations. These operations are passed via the IOBlockStorageDevice 274 * nub to a transport driver, which implements the appropriate 275 * transport-dependent protocol to execute these operations. 276 * 277 * To determine the write-protect state of a device (or media), for 278 * example, the generic driver would issue a call to the 279 * Transport Driver's reportWriteProtection method. If this were a SCSI 280 * device, its transport driver would issue a Mode Sense command to 281 * extract the write-protection status bit. The transport driver then 282 * reports true or false to the generic driver. 283 * 284 * The generic driver therefore has no knowledge of, or involvement 285 * with, the actual commands and mechanisms used to communicate with 286 * the device. It is expected that the generic driver will rarely, if 287 * ever, need to be subclassed to handle device idiosyncrasies; rather, 288 * the transport driver should be changed via overrides. 289 * 290 * A generic driver could be subclassed to create a different type of 291 * generic device. The generic driver IOCDBlockStorageDriver class is 292 * a subclass of IOBlockStorageDriver, adding CD functions. 293 */ 294 295class IOBlockStorageDriver : public IOStorage 296{ 297 OSDeclareDefaultStructors(IOBlockStorageDriver); 298 299public: 300 301 /*! 302 * @enum Statistics 303 * @abstract 304 * Indices for the different statistics that getStatistics() can report. 305 * @constant kStatisticsReads Number of read operations thus far. 306 * @constant kStatisticsBytesRead Number of bytes read thus far. 307 * @constant kStatisticsTotalReadTime Nanoseconds spent performing reads thus far. 308 * @constant kStatisticsLatentReadTime Nanoseconds of latency during reads thus far. 309 * @constant kStatisticsReadRetries Number of read retries thus far. 310 * @constant kStatisticsReadErrors Number of read errors thus far. 311 * @constant kStatisticsWrites Number of write operations thus far. 312 * @constant kStatisticsSingleBlockWrites Number of write operations for a single block thus far. 313 * @constant kStatisticsBytesWritten Number of bytes written thus far. 314 * @constant kStatisticsTotalWriteTime Nanoseconds spent performing writes thus far. 315 * @constant kStatisticsLatentWriteTime Nanoseconds of latency during writes thus far. 316 * @constant kStatisticsWriteRetries Number of write retries thus far. 317 * @constant kStatisticsWriteErrors Number of write errors thus far. 318 */ 319 320 enum Statistics 321 { 322 kStatisticsReads, 323 kStatisticsBytesRead, 324 kStatisticsTotalReadTime, 325 kStatisticsLatentReadTime, 326 kStatisticsReadRetries, 327 kStatisticsReadErrors, 328 329 kStatisticsWrites, 330 kStatisticsSingleBlockWrites, 331 kStatisticsBytesWritten, 332 kStatisticsTotalWriteTime, 333 kStatisticsLatentWriteTime, 334 kStatisticsWriteRetries, 335 kStatisticsWriteErrors 336 }; 337 338 static const UInt32 kStatisticsCount = kStatisticsWriteErrors + 1; 339 340protected: 341 342 struct Context; 343 344 struct ExpansionData 345 { 346#ifdef __LP64__ 347 UInt64 reserved0000; 348#else /* !__LP64__ */ 349 UInt32 reserved0000; 350#endif /* !__LP64__ */ 351 UInt64 maxReadBlockTransfer; 352 UInt64 maxWriteBlockTransfer; 353 IONotifier * powerEventNotifier; 354 UInt32 deblockRequestWriteLockCount; 355 UInt64 maxReadSegmentTransfer; 356 UInt64 maxWriteSegmentTransfer; 357 UInt64 maxReadSegmentByteTransfer; 358 UInt64 maxWriteSegmentByteTransfer; 359 UInt64 minSegmentAlignmentByteTransfer; 360 UInt64 maxSegmentWidthByteTransfer; 361 Context * contexts; 362 IOSimpleLock * contextsLock; 363 UInt32 contextsCount; 364 UInt32 contextsMaxCount; 365 }; 366 ExpansionData * _expansionData; 367 368 #define _maxReadBlockTransfer \ 369 IOBlockStorageDriver::_expansionData->maxReadBlockTransfer 370 #define _maxWriteBlockTransfer \ 371 IOBlockStorageDriver::_expansionData->maxWriteBlockTransfer 372 #define _powerEventNotifier \ 373 IOBlockStorageDriver::_expansionData->powerEventNotifier 374 #define _deblockRequestWriteLockCount \ 375 IOBlockStorageDriver::_expansionData->deblockRequestWriteLockCount 376 #define _maxReadSegmentTransfer \ 377 IOBlockStorageDriver::_expansionData->maxReadSegmentTransfer 378 #define _maxWriteSegmentTransfer \ 379 IOBlockStorageDriver::_expansionData->maxWriteSegmentTransfer 380 #define _maxReadSegmentByteTransfer \ 381 IOBlockStorageDriver::_expansionData->maxReadSegmentByteTransfer 382 #define _maxWriteSegmentByteTransfer \ 383 IOBlockStorageDriver::_expansionData->maxWriteSegmentByteTransfer 384 #define _minSegmentAlignmentByteTransfer \ 385 IOBlockStorageDriver::_expansionData->minSegmentAlignmentByteTransfer 386 #define _maxSegmentWidthByteTransfer \ 387 IOBlockStorageDriver::_expansionData->maxSegmentWidthByteTransfer 388 #define _contexts \ 389 IOBlockStorageDriver::_expansionData->contexts 390 #define _contextsLock \ 391 IOBlockStorageDriver::_expansionData->contextsLock 392 #define _contextsCount \ 393 IOBlockStorageDriver::_expansionData->contextsCount 394 #define _contextsMaxCount \ 395 IOBlockStorageDriver::_expansionData->contextsMaxCount 396 397 OSSet * _openClients; 398 OSNumber * _statistics[kStatisticsCount]; 399 400 /* 401 * @struct Context 402 * @discussion 403 * Context structure for a read/write operation. It describes the block size, 404 * and where applicable, a block type and block sub-type, for a data transfer, 405 * as well as the completion information for the original request. Note that 406 * the block type field is unused in the IOBlockStorageDriver class. 407 * @field block.size 408 * Block size for the operation. 409 * @field block.type 410 * Block type for the operation. Unused in IOBlockStorageDriver. The default 411 * value for this field is IOBlockStorageDriver::kBlockTypeStandard. 412 * @field block.typeSub 413 * Block sub-type for the operation. It's definition depends on block.type. 414 * Unused in IOBlockStorageDriver. 415 * @field request.byteStart 416 * Starting byte offset for the data transfer. 417 * @param request.buffer 418 * Buffer for the data transfer. The size of the buffer implies the size of 419 * the data transfer. 420 * @param request.attributes 421 * Attributes of the data transfer. See IOStorageAttributes. 422 * @param request.completion 423 * Completion routine to call once the data transfer is complete. 424 */ 425 426 struct Context 427 { 428#ifdef __LP64__ 429 struct 430 { 431 UInt64 byteStart; 432 IOMemoryDescriptor * buffer; 433 IOStorageAttributes attributes; 434 IOStorageCompletion completion; 435 } request; 436 437 struct 438 { 439 UInt32 size; 440 UInt8 type; 441 UInt8 typeSub[3]; 442 } block; 443 444 AbsoluteTime timeStart; 445 446 UInt64 reserved0704; 447 UInt64 reserved0768; 448 UInt64 reserved0832; 449 UInt64 reserved0896; 450#else /* !__LP64__ */ 451 struct 452 { 453 UInt32 size; 454 UInt8 type; 455 UInt8 typeSub[3]; 456 } block; 457 458 struct 459 { 460 UInt64 byteStart; 461 IOMemoryDescriptor * buffer; 462 IOStorageCompletion completion; 463 } original; 464 465 AbsoluteTime timeStart; 466 467 struct 468 { 469 IOStorageAttributes attributes; 470 } request; 471 472 UInt32 reserved0448; 473#endif /* !__LP64__ */ 474 475 Context * next; 476 }; 477 478 static const UInt8 kBlockTypeStandard = 0x00; 479 480 using IOService::open; 481 482 /* 483 * Free all of this object's outstanding resources. 484 * 485 * This method's implementation is not typically overridden. 486 */ 487 488 void free(); 489 490 /*! 491 * @function handleOpen 492 * @discussion 493 * The handleOpen method grants or denies permission to access this object 494 * to an interested client. The argument is an IOStorageAccess value that 495 * specifies the level of access desired -- reader or reader-writer. 496 * 497 * This method can be invoked to upgrade or downgrade the access level for 498 * an existing client as well. The previous access level will prevail for 499 * upgrades that fail, of course. A downgrade should never fail. If the 500 * new access level should be the same as the old for a given client, this 501 * method will do nothing and return success. In all cases, one, singular 502 * close-per-client is expected for all opens-per-client received. 503 * 504 * This implementation replaces the IOService definition of handleIsOpen(). 505 * @param client 506 * Client requesting the open. 507 * @param options 508 * Options for the open. Set to zero. 509 * @param access 510 * Access level for the open. Set to kIOStorageAccessReader or 511 * kIOStorageAccessReaderWriter. 512 * @result 513 * Returns true if the open was successful, false otherwise. 514 */ 515 516 virtual bool handleOpen(IOService * client, 517 IOOptionBits options, 518 void * access); 519 520 /*! 521 * @function handleIsOpen 522 * @discussion 523 * The handleIsOpen method determines whether the specified client, or any 524 * client if none is specified, presently has an open on this object. 525 * 526 * This implementation replaces the IOService definition of handleIsOpen(). 527 * @param client 528 * Client to check the open state of. Set to zero to check the open state 529 * of all clients. 530 * @result 531 * Returns true if the client was (or clients were) open, false otherwise. 532 */ 533 534 virtual bool handleIsOpen(const IOService * client) const; 535 536 /*! 537 * @function handleClose 538 * @discussion 539 * The handleClose method closes the client's access to this object. 540 * 541 * This implementation replaces the IOService definition of handleIsOpen(). 542 * @param client 543 * Client requesting the close. 544 * @param options 545 * Options for the close. Set to zero. 546 */ 547 548 virtual void handleClose(IOService * client, IOOptionBits options); 549 550 /*! 551 * @function addToBytesTransferred 552 * @discussion 553 * Update the total number of bytes transferred, the total transfer time, 554 * and the total latency time -- used for statistics. 555 * 556 * This method's implementation is not typically overridden. 557 * @param bytesTransferred 558 * Number of bytes transferred in this operation. 559 * @param totalTime 560 * Nanoseconds spent performing this operation. 561 * @param latentTime 562 * Nanoseconds of latency during this operation. 563 * @param isWrite 564 * Indicates whether this operation was a write, otherwise is was a read. 565 */ 566 567 virtual void addToBytesTransferred(UInt64 bytesTransferred, 568 UInt64 totalTime, 569 UInt64 latentTime, 570 bool isWrite); 571 572 /*! 573 * @function incrementErrors 574 * @discussion 575 * Update the total error count -- used for statistics. 576 * 577 * This method's implementation is not typically overridden. 578 * @param isWrite 579 * Indicates whether this operation was a write, otherwise is was a read. 580 */ 581 582 virtual void incrementErrors(bool isWrite); 583 584 /*! 585 * @function incrementRetries 586 * @discussion 587 * Update the total retry count -- used for statistics. 588 * 589 * This method's implementation is not typically overridden. 590 * @param isWrite 591 * Indicates whether this operation was a write, otherwise is was a read. 592 */ 593 594 virtual void incrementRetries(bool isWrite); 595 596 /*! 597 * @function allocateContext 598 * @discussion 599 * Allocate a context structure for a read/write operation. 600 * @result 601 * Context structure. 602 */ 603 604 virtual Context * allocateContext(); 605 606 /*! 607 * @function deleteContext 608 * @discussion 609 * Delete a context structure from a read/write operation. 610 * @param context 611 * Context structure to be deleted. 612 */ 613 614 virtual void deleteContext(Context * context); 615 616#ifndef __LP64__ 617 virtual void prepareRequest(UInt64 byteStart, 618 IOMemoryDescriptor * buffer, 619 IOStorageCompletion completion) __attribute__ ((deprecated)); 620#endif /* !__LP64__ */ 621 622 /*! 623 * @function deblockRequest 624 * @discussion 625 * The deblockRequest method checks to see if the incoming request rests 626 * on the media's block boundaries, and if not, deblocks it. Deblocking 627 * involves rounding out the request to the nearest block boundaries and 628 * transferring the excess bytes into a scratch buffer. 629 * 630 * This method is part of a sequence of methods invoked for each read/write 631 * request. The first is prepareRequest, which allocates and prepares some 632 * context for the transfer; the second is deblockRequest, which aligns the 633 * transfer at the media's block boundaries; third is breakUpRequest, which 634 * breaks up the transfer into multiple sub-transfers when certain hardware 635 * constraints are exceeded; fourth is executeRequest, which implements the 636 * actual transfer from the block storage device. 637 * 638 * This method's implementation is not typically overridden. 639 * @param byteStart 640 * Starting byte offset for the data transfer. 641 * @param buffer 642 * Buffer for the data transfer. The size of the buffer implies the size of 643 * the data transfer. 644 * @param attributes 645 * Attributes of the data transfer. See IOStorageAttributes. It is the 646 * responsibility of the callee to maintain the information for the duration 647 * of the data transfer, as necessary. 648 * @param completion 649 * Completion routine to call once the data transfer is complete. It is the 650 * responsibility of the callee to maintain the information for the duration 651 * of the data transfer, as necessary. 652 * @param context 653 * Additional context information for the data transfer (e.g. block size). 654 */ 655 656#ifdef __LP64__ 657 virtual void deblockRequest(UInt64 byteStart, 658 IOMemoryDescriptor * buffer, 659 IOStorageAttributes * attributes, 660 IOStorageCompletion * completion, 661 Context * context); 662#else /* !__LP64__ */ 663 virtual void deblockRequest(UInt64 byteStart, 664 IOMemoryDescriptor * buffer, 665 IOStorageCompletion completion, 666 Context * context); 667#endif /* !__LP64__ */ 668 669 /*! 670 * @function executeRequest 671 * @discussion 672 * Execute an asynchronous storage request. The request is guaranteed to be 673 * block-aligned. 674 * 675 * This method is part of a sequence of methods invoked for each read/write 676 * request. The first is prepareRequest, which allocates and prepares some 677 * context for the transfer; the second is deblockRequest, which aligns the 678 * transfer at the media's block boundaries; third is breakUpRequest, which 679 * breaks up the transfer into multiple sub-transfers when certain hardware 680 * constraints are exceeded; fourth is executeRequest, which implements the 681 * actual transfer from the block storage device. 682 * @param byteStart 683 * Starting byte offset for the data transfer. 684 * @param buffer 685 * Buffer for the data transfer. The size of the buffer implies the size of 686 * the data transfer. 687 * @param attributes 688 * Attributes of the data transfer. See IOStorageAttributes. It is the 689 * responsibility of the callee to maintain the information for the duration 690 * of the data transfer, as necessary. 691 * @param completion 692 * Completion routine to call once the data transfer is complete. It is the 693 * responsibility of the callee to maintain the information for the duration 694 * of the data transfer, as necessary. 695 * @param context 696 * Additional context information for the data transfer (e.g. block size). 697 */ 698 699#ifdef __LP64__ 700 virtual void executeRequest(UInt64 byteStart, 701 IOMemoryDescriptor * buffer, 702 IOStorageAttributes * attributes, 703 IOStorageCompletion * completion, 704 Context * context); 705#else /* !__LP64__ */ 706 virtual void executeRequest(UInt64 byteStart, 707 IOMemoryDescriptor * buffer, 708 IOStorageCompletion completion, 709 Context * context); 710#endif /* !__LP64__ */ 711 712 /*! 713 * @function handleStart 714 * @discussion 715 * Prepare the block storage driver for operation. 716 * 717 * This is where a media object needs to be created for fixed media, and 718 * optionally for removable media. 719 * 720 * Note that this method is called from within the start() routine; 721 * if this method returns successfully, it should be prepared to accept 722 * any of IOBlockStorageDriver's APIs. 723 * @param provider 724 * This object's provider. 725 * @result 726 * Returns true on success, false otherwise. 727 */ 728 729 virtual bool handleStart(IOService * provider); 730 731 virtual bool handleYield(IOService * provider, 732 IOOptionBits options = 0, 733 void * argument = 0) __attribute__ ((deprecated)); 734 735 /*! 736 * @function getMediaBlockSize 737 * @discussion 738 * Ask the driver about the media's natural block size. 739 * @result 740 * Natural block size, in bytes. 741 */ 742 743 virtual UInt64 getMediaBlockSize() const; 744 745public: 746 747 using IOStorage::open; 748 using IOStorage::read; 749 using IOStorage::write; 750 751 /* 752 * Initialize this object's minimal state. 753 * 754 * This method's implementation is not typically overridden. 755 */ 756 757 virtual bool init(OSDictionary * properties = 0); 758 759 /* 760 * This method is called once we have been attached to the provider object. 761 * 762 * This method's implementation is not typically overridden. 763 */ 764 765 virtual bool start(IOService * provider); 766 767 /* 768 * This method is called before we are detached from the provider object. 769 * 770 * This method's implementation is not typically overridden. 771 */ 772 773 virtual void stop(IOService * provider); 774 775 virtual bool didTerminate(IOService * provider, 776 IOOptionBits options, 777 bool * defer); 778 779 virtual bool yield(IOService * provider, 780 IOOptionBits options = 0, 781 void * argument = 0) __attribute__ ((deprecated)); 782 783 /*! 784 * @function read 785 * @discussion 786 * The read method is the receiving end for all read requests from the 787 * storage framework (through the media object created by this driver). 788 * 789 * This method initiates a sequence of methods (stages) for each read/write 790 * request. The first is prepareRequest, which allocates and prepares some 791 * context for the transfer; the second is deblockRequest, which aligns the 792 * transfer at the media's block boundaries; third is breakUpRequest, which 793 * breaks up the transfer into multiple sub-transfers when certain hardware 794 * constraints are exceeded; fourth is executeRequest, which implements the 795 * actual transfer from the block storage device. 796 * 797 * This method's implementation is not typically overridden. 798 * @param client 799 * Client requesting the read. 800 * @param byteStart 801 * Starting byte offset for the data transfer. 802 * @param buffer 803 * Buffer for the data transfer. The size of the buffer implies the size of 804 * the data transfer. 805 * @param attributes 806 * Attributes of the data transfer. See IOStorageAttributes. It is the 807 * responsibility of the callee to maintain the information for the duration 808 * of the data transfer, as necessary. 809 * @param completion 810 * Completion routine to call once the data transfer is complete. It is the 811 * responsibility of the callee to maintain the information for the duration 812 * of the data transfer, as necessary. 813 */ 814 815 virtual void read(IOService * client, 816 UInt64 byteStart, 817 IOMemoryDescriptor * buffer, 818 IOStorageAttributes * attributes, 819 IOStorageCompletion * completion); 820 821 /*! 822 * @function write 823 * @discussion 824 * The write method is the receiving end for all write requests from the 825 * storage framework (through the media object created by this driver). 826 * 827 * This method initiates a sequence of methods (stages) for each read/write 828 * request. The first is prepareRequest, which allocates and prepares some 829 * context for the transfer; the second is deblockRequest, which aligns the 830 * transfer at the media's block boundaries; third is breakUpRequest, which 831 * breaks up the transfer into multiple sub-transfers when certain hardware 832 * constraints are exceeded; fourth is executeRequest, which implements the 833 * actual transfer from the block storage device. 834 * 835 * This method's implementation is not typically overridden. 836 * @param client 837 * Client requesting the write. 838 * @param byteStart 839 * Starting byte offset for the data transfer. 840 * @param buffer 841 * Buffer for the data transfer. The size of the buffer implies the size of 842 * the data transfer. 843 * @param attributes 844 * Attributes of the data transfer. See IOStorageAttributes. It is the 845 * responsibility of the callee to maintain the information for the duration 846 * of the data transfer, as necessary. 847 * @param completion 848 * Completion routine to call once the data transfer is complete. It is the 849 * responsibility of the callee to maintain the information for the duration 850 * of the data transfer, as necessary. 851 */ 852 853 virtual void write(IOService * client, 854 UInt64 byteStart, 855 IOMemoryDescriptor * buffer, 856 IOStorageAttributes * attributes, 857 IOStorageCompletion * completion); 858 859 /*! 860 * @function synchronizeCache 861 * @discussion 862 * Flush the cached data in the storage object, if any, synchronously. 863 * @param client 864 * Client requesting the cache synchronization. 865 * @result 866 * Returns the status of the cache synchronization. 867 */ 868 869 virtual IOReturn synchronizeCache(IOService * client); 870 871 /*! 872 * @function unmap 873 * @discussion 874 * Delete unused data from the storage object at the specified byte offsets, 875 * synchronously. 876 * @param client 877 * Client requesting the operation. 878 * @param extents 879 * List of extents. See IOStorageExtent. It is legal for the callee to 880 * overwrite the contents of this buffer in order to satisfy the request. 881 * @param extentsCount 882 * Number of extents. 883 * @result 884 * Returns the status of the operation. 885 */ 886 887 virtual IOReturn unmap(IOService * client, 888 IOStorageExtent * extents, 889 UInt32 extentsCount, 890 UInt32 options = 0); 891 892 /*! 893 * @function lockPhysicalExtents 894 * @discussion 895 * Lock the contents of the storage object against relocation temporarily, 896 * for the purpose of getting physical extents. 897 * @param client 898 * Client requesting the operation. 899 * @result 900 * Returns true if the lock was successful, false otherwise. 901 */ 902 903 virtual bool lockPhysicalExtents(IOService * client); 904 905 /*! 906 * @function copyPhysicalExtent 907 * @discussion 908 * Convert the specified byte offset into a physical byte offset, relative 909 * to a physical storage object. This call should only be made within the 910 * context of lockPhysicalExtents(). 911 * @param client 912 * Client requesting the operation. 913 * @param byteStart 914 * Starting byte offset for the operation. Returns a physical byte offset, 915 * relative to the physical storage object, on success. 916 * @param byteCount 917 * Size of the operation. Returns the actual number of bytes which can be 918 * transferred, relative to the physical storage object, on success. 919 * @result 920 * A reference to the physical storage object, which should be released by 921 * the caller, or a null on error. 922 */ 923 924 virtual IOStorage * copyPhysicalExtent(IOService * client, 925 UInt64 * byteStart, 926 UInt64 * byteCount); 927 928 /*! 929 * @function unlockPhysicalExtents 930 * @discussion 931 * Unlock the contents of the storage object for relocation again. This 932 * call must balance a successful call to lockPhysicalExtents(). 933 * @param client 934 * Client requesting the operation. 935 */ 936 937 virtual void unlockPhysicalExtents(IOService * client); 938 939 /*! 940 * @function ejectMedia 941 * @discussion 942 * Eject the media from the device. The driver is responsible for tearing 943 * down the media object it created before proceeding with the eject. If 944 * the tear-down fails, an error should be returned. 945 * @result 946 * An IOReturn code. 947 */ 948 949 virtual IOReturn ejectMedia(); 950 951 /*! 952 * @function formatMedia 953 * @discussion 954 * Format the media with the specified byte capacity. The driver is 955 * responsible for tearing down the media object and recreating it. 956 * @param byteCapacity 957 * Number of bytes to format media to. 958 * @result 959 * An IOReturn code. 960 */ 961 962 virtual IOReturn formatMedia(UInt64 byteCapacity); 963 964 virtual IOReturn lockMedia(bool lock) __attribute__ ((deprecated)); 965 966 virtual IOReturn pollMedia() __attribute__ ((deprecated)); 967 968 /*! 969 * @function isMediaEjectable 970 * @discussion 971 * Ask the driver whether the media is ejectable. 972 * @result 973 * Returns true if the media is ejectable, false otherwise. 974 */ 975 976 virtual bool isMediaEjectable() const; 977 978#ifdef __LP64__ 979 /*! 980 * @function isMediaRemovable 981 * @discussion 982 * Ask the driver whether the media is ejectable. 983 * @result 984 * Returns true if the media is ejectable, false otherwise. 985 */ 986 987 virtual bool isMediaRemovable() const; 988#endif /* __LP64__ */ 989 990 virtual bool isMediaPollExpensive() const __attribute__ ((deprecated)); 991 992 virtual bool isMediaPollRequired() const __attribute__ ((deprecated)); 993 994 /*! 995 * @function isMediaWritable 996 * @discussion 997 * Ask the driver whether the media is writable. 998 * @result 999 * Returns true if the media is writable, false otherwise. 1000 */ 1001 1002 virtual bool isMediaWritable() const; 1003 1004 /*! 1005 * @function getMediaState 1006 * @discussion 1007 * Ask the driver about the media's current state. 1008 * @result 1009 * An IOMediaState value. 1010 */ 1011 1012 virtual IOMediaState getMediaState() const; 1013 1014 /*! 1015 * @function getFormatCapacities 1016 * @discussion 1017 * Ask the driver to report the feasible formatting capacities for the 1018 * inserted media (in bytes). This routine fills the caller's buffer, 1019 * up to the maximum count specified if the real number of capacities 1020 * would overflow the buffer. The return value indicates the actual 1021 * number of capacities copied to the buffer. 1022 * 1023 * If the capacities buffer is not supplied or if the maximum count is 1024 * zero, the routine returns the proposed count of capacities instead. 1025 * @param capacities 1026 * Buffer that will receive the UInt64 capacity values. 1027 * @param capacitiesMaxCount 1028 * Maximum number of capacity values that can be held in the buffer. 1029 * @result 1030 * Actual number of capacity values copied to the buffer, or if no buffer 1031 * is given, the total number of capacity values available. 1032 */ 1033 1034 virtual UInt32 getFormatCapacities(UInt64 * capacities, 1035 UInt32 capacitiesMaxCount) const; 1036 1037 /*! 1038 * @function getStatistics 1039 * @discussion 1040 * Ask the driver to report its operating statistics. 1041 * 1042 * The statistics are each indexed by IOBlockStorageDriver::Statistics 1043 * indices. This routine fills the caller's buffer, up to the maximum 1044 * count specified if the real number of statistics would overflow the 1045 * buffer. The return value indicates the actual number of statistics 1046 * copied to the buffer. 1047 * 1048 * If the statistics buffer is not supplied or if the maximum count is 1049 * zero, the routine returns the proposed count of statistics instead. 1050 * @param statistics 1051 * Buffer that will receive the UInt64 statistic values. 1052 * @param statisticsMaxCount 1053 * Maximum number of statistic values that can be held in the buffer. 1054 * @result 1055 * Actual number of statistic values copied to the buffer, or if no buffer 1056 * is given, the total number of statistic values available. 1057 */ 1058 1059 virtual UInt32 getStatistics(UInt64 * statistics, 1060 UInt32 statisticsMaxCount) const; 1061 1062 /*! 1063 * @function getStatistic 1064 * @discussion 1065 * Ask the driver to report one of its operating statistics. 1066 * @param statistic 1067 * Statistic index (an IOBlockStorageDriver::Statistics index). 1068 * @result 1069 * Statistic value. 1070 */ 1071 1072 virtual UInt64 getStatistic(Statistics statistic) const; 1073 1074 /* 1075 * Generic entry point for calls from the provider. A return value of 1076 * kIOReturnSuccess indicates that the message was received, and where 1077 * applicable, that it was successful. 1078 */ 1079 1080 virtual IOReturn message(UInt32 type, IOService * provider, void * argument); 1081 1082 /* 1083 * Obtain this object's provider. We override the superclass's method to 1084 * return a more specific subclass of IOService -- IOBlockStorageDevice. 1085 * This method serves simply as a convenience to subclass developers. 1086 */ 1087 1088 virtual IOBlockStorageDevice * getProvider() const; 1089 1090protected: 1091 1092 IOLock * _deblockRequestWriteLock; 1093 1094#ifdef __LP64__ 1095 UInt64 _reserved1024; 1096#else /* !__LP64__ */ 1097 UInt32 _reserved1024; 1098#endif /* !__LP64__ */ 1099 1100 static void breakUpRequestExecute(void * parameter, void * target); 1101 1102 static void deblockRequestExecute(void * parameter, void * target); 1103 1104 /* 1105 * This is the completion routine for the broken up breaker sub-requests. 1106 * It verifies the success of the just-completed stage, transitions to 1107 * the next stage, then builds and issues a transfer for the next stage. 1108 */ 1109 1110 static void breakUpRequestCompletion(void * target, 1111 void * parameter, 1112 IOReturn status, 1113 UInt64 actualByteCount); 1114 1115 /* 1116 * This is the completion routine for the aligned deblocker sub-requests. 1117 * It verifies the success of the just-completed stage, transitions to 1118 * the next stage, then builds and issues a transfer for the next stage. 1119 */ 1120 1121 static void deblockRequestCompletion(void * target, 1122 void * parameter, 1123 IOReturn status, 1124 UInt64 actualByteCount); 1125 1126 /* 1127 * This is the completion routine for the prepared request. It updates 1128 * the driver's statistics, performs some clean up work, then calls the 1129 * original request's completion routine. 1130 */ 1131 1132 static void prepareRequestCompletion(void * target, 1133 void * parameter, 1134 IOReturn status, 1135 UInt64 actualByteCount); 1136 1137 virtual void schedulePoller() __attribute__ ((deprecated)); 1138 1139 virtual void unschedulePoller() __attribute__ ((deprecated)); 1140 1141 /* 1142 * This method is the power event handler for restarts and shutdowns. 1143 */ 1144 1145 static IOReturn handlePowerEvent(void * target, 1146 void * parameter, 1147 UInt32 messageType, 1148 IOService * provider, 1149 void * messageArgument, 1150 vm_size_t messageArgumentSize); 1151 1152protected: 1153 1154 /* Device info: */ 1155 1156 /*! 1157 * @var _removable 1158 * True if the media is removable; False if it is fixed (not removable). 1159 */ 1160 bool _removable; 1161 1162 /*! 1163 * @var _ejectable 1164 * True if the media is ejectable under software control. 1165 */ 1166 bool _ejectable; /* software-ejectable */ 1167 1168 UInt16 _reserved1104; 1169 1170 UInt32 _openAssertions; 1171 1172 /* Media info and states: */ 1173 1174 /*! 1175 * @var _mediaObject 1176 * A pointer to the media object we have instantiated (if any). 1177 */ 1178 IOMedia * _mediaObject; 1179 1180 /*! 1181 * @var _mediaType 1182 * Type of the media (can be used to differentiate between the 1183 * different types of CD media, DVD media, etc). 1184 */ 1185 UInt32 _mediaType; 1186 1187 UInt8 _reserved1248; 1188 1189 /*! 1190 * @var _writeProtected 1191 * True if the media is write-protected; False if not. 1192 */ 1193 bool _writeProtected; 1194 1195 UInt16 _reserved1264; 1196#ifdef __LP64__ 1197 UInt64 _reserved1280; 1198#else /* !__LP64__ */ 1199 UInt32 _reserved1280; 1200#endif /* !__LP64__ */ 1201 1202 /*! 1203 * @var _mediaBlockSize 1204 * The block size of the media, in bytes. 1205 */ 1206 UInt64 _mediaBlockSize; 1207 1208 /*! 1209 * @var _maxBlockNumber 1210 * The maximum allowable block number for the media, zero-based. 1211 */ 1212 UInt64 _maxBlockNumber; 1213 1214 /*! 1215 * @var _maxReadByteTransfer 1216 * The maximum byte transfer allowed for read operations. 1217 */ 1218 UInt64 _maxReadByteTransfer; 1219 1220 /*! 1221 * @var _maxWriteByteTransfer 1222 * The maximum byte transfer allowed for write operations. 1223 */ 1224 UInt64 _maxWriteByteTransfer; 1225 1226 /*! 1227 * @function acceptNewMedia 1228 * @abstract 1229 * React to new media insertion. 1230 * @discussion 1231 * This method logs the media block size and block count, then calls 1232 * instantiateMediaObject to get a media object instantiated. The 1233 * media object is then attached above us and registered. 1234 * 1235 * This method can be overridden to control what happens when new media 1236 * is inserted. The default implementation deals with one IOMedia object. 1237 */ 1238 virtual IOReturn acceptNewMedia(void); 1239 1240 /*! 1241 * @function constrainByteCount 1242 * @abstract 1243 * Constrain the byte count for this IO to device limits. 1244 * @discussion 1245 * This function should be called prior to each read or write operation, so that 1246 * the driver can constrain the requested byte count, as necessary, to meet 1247 * current device limits. Such limits could be imposed by the device depending 1248 * on operating modes, media types, or transport protocol (e.g. ATA, SCSI). 1249 * 1250 * At present, this method is not used. 1251 * @param requestedCount 1252 * The requested byte count for the next read or write operation. 1253 * @param isWrite 1254 * True if the operation will be a write; False if the operation will be a read. 1255 */ 1256 virtual UInt64 constrainByteCount(UInt64 requestedCount,bool isWrite); 1257 1258 /*! 1259 * @function decommissionMedia 1260 * @abstract 1261 * Decommission an existing piece of media that has gone away. 1262 * @discussion 1263 * This method wraps a call to terminate, to tear down the stack and 1264 * the IOMedia object for the media. If "forcible" is true, the media 1265 * object will be forgotten, and initMediaState will be called. A 1266 * forcible decommission would occur when an unrecoverable error 1267 * happens during tear-down (e.g. perhaps a client is still open), but 1268 * we must still forget about the media. 1269 * @param forcible 1270 * True to force forgetting of the media object even if terminate reports 1271 * that there was an active client. 1272 */ 1273 virtual IOReturn decommissionMedia(bool forcible); 1274 1275 /*! 1276 * @function instantiateDesiredMediaObject 1277 * @abstract 1278 * Create an IOMedia object for media. 1279 * @discussion 1280 * This method creates the exact type of IOMedia object desired. It is called by 1281 * instantiateMediaObject. A subclass may override this one-line method to change 1282 * the type of media object actually instantiated. 1283 */ 1284 virtual IOMedia * instantiateDesiredMediaObject(void); 1285 1286 /*! 1287 * @function instantiateMediaObject 1288 * @abstract 1289 * Create an IOMedia object for media. 1290 * @discussion 1291 * This method creates an IOMedia object from the supplied parameters. It is a 1292 * convenience method to wrap the handful of steps to do the job. 1293 * @param base 1294 * Byte number of beginning of active data area of the media. Usually zero. 1295 * @param byteSize 1296 * Size of the data area of the media, in bytes. 1297 * @param blockSize 1298 * Block size of the media, in bytes. 1299 * @param mediaName 1300 * Name of the IOMedia object. 1301 * @result 1302 * A pointer to the created IOMedia object, or a null on error. 1303 */ 1304 virtual IOMedia * instantiateMediaObject(UInt64 base,UInt64 byteSize, 1305 UInt32 blockSize,char *mediaName); 1306 1307 /*! 1308 * @function recordMediaParameters 1309 * @abstract 1310 * Obtain media-related parameters on media insertion. 1311 * @discussion 1312 * This method obtains media-related parameters via calls to the 1313 * Transport Driver's reportBlockSize, reportMaxValidBlock, 1314 * and reportWriteProtection methods. 1315 */ 1316 virtual IOReturn recordMediaParameters(void); 1317 1318 /*! 1319 * @function rejectMedia 1320 * @abstract 1321 * Reject new media. 1322 * @discussion 1323 * This method will be called if validateNewMedia returns False (thus rejecting 1324 * the new media. A vendor may choose to override this method to control behavior 1325 * when media is rejected. 1326 * 1327 * The default implementation simply calls ejectMedia. 1328 */ 1329 virtual void rejectMedia(void); /* default ejects */ 1330 1331 /*! 1332 * @function validateNewMedia 1333 * @abstract 1334 * Verify that new media is acceptable. 1335 * @discussion 1336 * This method will be called whenever new media is detected. Return true to accept 1337 * the media, or false to reject it (and call rejectMedia). Vendors might override 1338 * this method to handle password-protection for new media. 1339 * 1340 * The default implementation always returns True, indicating media is accepted. 1341 */ 1342 virtual bool validateNewMedia(void); 1343 1344 /* --- Internally used methods. --- */ 1345 1346 /* 1347 * @group 1348 * Internally Used Methods 1349 * @discussion 1350 * These methods are used internally, and will not generally be modified. 1351 */ 1352 1353 /*! 1354 * @function checkForMedia 1355 * @abstract 1356 * Check if media has newly arrived or disappeared. 1357 * @discussion 1358 * This method does most of the work in polling for media, first 1359 * calling the block storage device's reportMediaState method. If 1360 * reportMediaState reports no change in the media state, kIOReturnSuccess 1361 * is returned. If the media state has indeed changed, a call is made to 1362 * mediaStateHasChanged to act on the event. 1363 */ 1364 virtual IOReturn checkForMedia(void); 1365 1366 /*! 1367 * @function getDeviceTypeName 1368 * @abstract 1369 * Return the desired device name. 1370 * @discussion 1371 * This method returns a string, used to compare the 1372 * kIOBlockStorageDeviceTypeKey of our provider. This method is called from 1373 * probe. 1374 * 1375 * The default implementation of this method returns 1376 * kIOBlockStorageDeviceTypeGeneric. 1377 */ 1378 virtual const char * getDeviceTypeName(void); 1379 1380 /*! 1381 * @function initMediaState 1382 * @abstract 1383 * Initialize media-related instance variables. 1384 * @discussion 1385 * Called when media is not present, this method marks the device state 1386 * as not having media present, not spun up, and write-enabled. 1387 */ 1388 virtual void initMediaState(void); 1389 1390 /*! 1391 * @function mediaStateHasChanged 1392 * @abstract 1393 * React to a new media insertion or a media removal. 1394 * @discussion 1395 * This method is called on a media state change, that is, an arrival 1396 * or removal. If media has just become available, calls are made to 1397 * recordMediaParameters and acceptNewMedia. If media has just gone 1398 * away, a call is made to decommissionMedia, with the forcible 1399 * parameter set to true. The forcible tear-down is needed to enforce 1400 * the disappearance of media, regardless of interested clients. 1401 */ 1402 virtual IOReturn mediaStateHasChanged(IOMediaState state); 1403 1404 /* 1405 * @endgroup 1406 */ 1407 1408protected: 1409 1410 /*! 1411 * @function breakUpRequest 1412 * @discussion 1413 * The breakUpRequest method checks to see if the incoming request exceeds 1414 * our transfer constraints, and if so, breaks up the request into smaller 1415 * sub-requests. 1416 * 1417 * This method is part of a sequence of methods invoked for each read/write 1418 * request. The first is prepareRequest, which allocates and prepares some 1419 * context for the transfer; the second is deblockRequest, which aligns the 1420 * transfer at the media's block boundaries; third is breakUpRequest, which 1421 * breaks up the transfer into multiple sub-transfers when certain hardware 1422 * constraints are exceeded; fourth is executeRequest, which implements the 1423 * actual transfer from the block storage device. 1424 * 1425 * This method's implementation is not typically overridden. 1426 * @param byteStart 1427 * Starting byte offset for the data transfer. 1428 * @param buffer 1429 * Buffer for the data transfer. The size of the buffer implies the size of 1430 * the data transfer. 1431 * @param attributes 1432 * Attributes of the data transfer. See IOStorageAttributes. It is the 1433 * responsibility of the callee to maintain the information for the duration 1434 * of the data transfer, as necessary. 1435 * @param completion 1436 * Completion routine to call once the data transfer is complete. It is the 1437 * responsibility of the callee to maintain the information for the duration 1438 * of the data transfer, as necessary. 1439 * @param context 1440 * Additional context information for the data transfer (e.g. block size). 1441 */ 1442 1443#ifdef __LP64__ 1444 virtual void breakUpRequest(UInt64 byteStart, 1445 IOMemoryDescriptor * buffer, 1446 IOStorageAttributes * attributes, 1447 IOStorageCompletion * completion, 1448 Context * context); 1449#else /* !__LP64__ */ 1450 virtual void breakUpRequest(UInt64 byteStart, 1451 IOMemoryDescriptor * buffer, 1452 IOStorageCompletion completion, 1453 Context * context); /* 10.1.2 */ 1454#endif /* !__LP64__ */ 1455 1456 /*! 1457 * @function prepareRequest 1458 * @discussion 1459 * The prepareRequest method allocates and prepares state for the transfer. 1460 * 1461 * This method is part of a sequence of methods invoked for each read/write 1462 * request. The first is prepareRequest, which allocates and prepares some 1463 * context for the transfer; the second is deblockRequest, which aligns the 1464 * transfer at the media's block boundaries; third is breakUpRequest, which 1465 * breaks up the transfer into multiple sub-transfers when certain hardware 1466 * constraints are exceeded; fourth is executeRequest, which implements the 1467 * actual transfer from the block storage device. 1468 * 1469 * This method's implementation is not typically overridden. 1470 * @param byteStart 1471 * Starting byte offset for the data transfer. 1472 * @param buffer 1473 * Buffer for the data transfer. The size of the buffer implies the size of 1474 * the data transfer. 1475 * @param attributes 1476 * Attributes of the data transfer. See IOStorageAttributes. It is the 1477 * responsibility of the callee to maintain the information for the duration 1478 * of the data transfer, as necessary. 1479 * @param completion 1480 * Completion routine to call once the data transfer is complete. It is the 1481 * responsibility of the callee to maintain the information for the duration 1482 * of the data transfer, as necessary. 1483 */ 1484 1485 virtual void prepareRequest(UInt64 byteStart, 1486 IOMemoryDescriptor * buffer, 1487 IOStorageAttributes * attributes, 1488 IOStorageCompletion * completion); /* 10.5.0 */ 1489 1490public: 1491 1492 /*! 1493 * @function requestIdle 1494 * @abstract 1495 * Request that the device enter an idle state. 1496 * @discussion 1497 * Request that the device enter an idle state. The device will exit this state on the 1498 * next read or write request, or as it sees necessary. One example is for a DVD drive 1499 * to spin down when it enters such an idle state, and spin up on the next read request 1500 * from the system. 1501 */ 1502 virtual IOReturn requestIdle(void); /* 10.6.0 */ 1503 1504#ifdef __LP64__ 1505 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 0); 1506 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 1); 1507 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 2); 1508#else /* !__LP64__ */ 1509 OSMetaClassDeclareReservedUsed(IOBlockStorageDriver, 0); 1510 OSMetaClassDeclareReservedUsed(IOBlockStorageDriver, 1); 1511 OSMetaClassDeclareReservedUsed(IOBlockStorageDriver, 2); 1512#endif /* !__LP64__ */ 1513 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 3); 1514 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 4); 1515 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 5); 1516 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 6); 1517 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 7); 1518 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 8); 1519 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 9); 1520 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 10); 1521 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 11); 1522 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 12); 1523 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 13); 1524 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 14); 1525 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 15); 1526 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 16); 1527 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 17); 1528 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 18); 1529 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 19); 1530 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 20); 1531 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 21); 1532 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 22); 1533 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 23); 1534 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 24); 1535 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 25); 1536 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 26); 1537 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 27); 1538 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 28); 1539 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 29); 1540 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 30); 1541 OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 31); 1542}; 1543 1544#endif /* __cplusplus */ 1545#endif /* KERNEL */ 1546#endif /* !_IOBLOCKSTORAGEDRIVER_H */ 1547