![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IOHDDriveNub.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 IOHDDriveNub.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: * Copyright (c) 1999 Apple Computer, Inc. All rights reserved. ! 24: * ! 25: * IOHDDriveNub.h ! 26: * ! 27: * This class is the protocol for generic hard disk functionality, independent of ! 28: * the physical connection protocol (e.g. SCSI, ATA, USB). ! 29: * ! 30: * A subclass implements relay methods that translate our requests into ! 31: * calls to a protocol- and device-specific provider. ! 32: */ ! 33: ! 34: /*! @language embedded-c++ */ ! 35: ! 36: #ifndef _IOHDDRIVENUB_H ! 37: #define _IOHDDRIVENUB_H ! 38: ! 39: #include <IOKit/IOTypes.h> ! 40: #include <IOKit/IOService.h> ! 41: #include "IOHDTypes.h" ! 42: ! 43: /*! ! 44: * @defined kDeviceTypeProperty ! 45: * The name of the property tested for nub type matching by the generic hard ! 46: * disk driver. This define is used by both IOHDDrive and IOHDDriveNub. ! 47: * @defined kDeviceTypeHardDisk ! 48: * A character string used for nub matching. ! 49: */ ! 50: /* Property used for matching, so the generic driver gets the nub it wants. */ ! 51: #define kDeviceTypeProperty "device-type" ! 52: #define kDeviceTypeHardDisk "Hard Disk" ! 53: ! 54: class IOMemoryDescriptor; ! 55: ! 56: /*! ! 57: * @class ! 58: * IOHDDriveNub : public IOService ! 59: * @abstract ! 60: * "Impedance-matcher" class to connect Generic device driver to Transport Driver. ! 61: * @discussion ! 62: * The IOHDDriveNub class exports the generic hard disk protocol, ! 63: * forwarding all requests to its provider (the Transport Driver). ! 64: * Though the nub does no actual processing of requests, it is necessary ! 65: * in a C++ environment. The Transport Driver can be of any type, as ! 66: * long as it inherits from IOService. Because Transport Drivers needn't ! 67: * derive from a type known to IOHDDrive, it isn't possible for IOHDDrive ! 68: * to include the appropriate header file to allow direct communication ! 69: * with the Transport Driver. Thus we achieve polymorphism by having ! 70: * the Transport Driver instantiate a subclass of IOHDDriveNub. ! 71: * A typical implementation for a concrete subclass of IOHDDriveNub ! 72: * (e.g. IOSCSIHDDriveNub) simply relays all methods to its provider ! 73: * (the Transport Driver). ! 74: * ! 75: * All pure-virtual functions must be implemented by the Transport Driver, which ! 76: * is responsible for instantiating the Nub. ! 77: */ ! 78: ! 79: class IOHDDriveNub : public IOService { ! 80: ! 81: OSDeclareAbstractStructors(IOHDDriveNub) ! 82: ! 83: public: ! 84: ! 85: /* Overrides from IORegistryEntry */ ! 86: ! 87: /*! ! 88: * @function init ! 89: * @discussion ! 90: * This function is overridden so that IOHDDriveNub can set a ! 91: * property, used by IOHDDrive for matching. Since the concrete subclass of ! 92: * IOHDDriveNub can be of any class type, the property is used for matching. ! 93: * ! 94: * This function is usually not overridden by developers. ! 95: */ ! 96: virtual bool init(OSDictionary * properties); ! 97: ! 98: /* --- A subclass must implement the the following methods: --- */ ! 99: ! 100: /*! ! 101: * @function doAsyncReadWrite ! 102: * @abstract ! 103: * Start an asynchronous read or write operation. ! 104: * @param buffer ! 105: * An IOMemoryDescriptor describing the data-transfer buffer. The data direction ! 106: * is contained in the IOMemoryDescriptor. Responsiblity for releasing the descriptor ! 107: * rests with the caller. ! 108: * @param block ! 109: * The starting block number of the data transfer. ! 110: * @param nblks ! 111: * The integral number of blocks to be transferred. ! 112: * @param action ! 113: * The C function called upon completion of the data transfer. ! 114: * @param target ! 115: * The C++ class "this" pointer, passed as an argument to "action." ! 116: * @param param ! 117: * This value is passed as an argument to "action." It is not validated or modified. ! 118: */ ! 119: ! 120: virtual IOReturn doAsyncReadWrite(IOMemoryDescriptor *buffer, ! 121: UInt32 block,UInt32 nblks, ! 122: gdCompletionFunction action, ! 123: IOService *target,void *param) = 0; ! 124: ! 125: /*! ! 126: * @function doSyncReadWrite ! 127: * @abstract ! 128: * Perform a synchronous read or write operation. ! 129: * @param buffer ! 130: * An IOMemoryDescriptor describing the data-transfer buffer. The data direction ! 131: * is contained in the IOMemoryDescriptor. Responsiblity for releasing the descriptor ! 132: * rests with the caller. ! 133: * @param block ! 134: * The starting block number of the data transfer. ! 135: * @param nblks ! 136: * The integral number of blocks to be transferred. ! 137: */ ! 138: virtual IOReturn doSyncReadWrite(IOMemoryDescriptor *buffer, ! 139: UInt32 block,UInt32 nblks) = 0; ! 140: ! 141: /*! ! 142: * @function doEjectMedia ! 143: * @abstract ! 144: * Eject the media. ! 145: */ ! 146: virtual IOReturn doEjectMedia(void) = 0; ! 147: ! 148: /*! ! 149: * @function doFormatMedia ! 150: * @abstract ! 151: * Format the media to the specified byte capacity. ! 152: * @discussion ! 153: * The specified byte capacity must be one supported by the device. ! 154: * Supported capacities can be obtained by calling doGetFormatCapacities. ! 155: * @param byteCapacity ! 156: * The byte capacity to which the device is to be formatted, if possible. ! 157: */ ! 158: virtual IOReturn doFormatMedia(UInt64 byteCapacity) = 0; ! 159: ! 160: /*! ! 161: * @function doGetFormatCapacities ! 162: * @abstract ! 163: * Return the allowable formatting byte capacities. ! 164: * @discussion ! 165: * This function returns the supported byte capacities for the device. ! 166: * @param capacities ! 167: * Pointer for returning the list of capacities. ! 168: * @param capacitiesMaxCount ! 169: * The number of capacity values returned in "capacities." ! 170: */ ! 171: virtual UInt32 doGetFormatCapacities(UInt64 * capacities, ! 172: UInt32 capacitiesMaxCount) const = 0; ! 173: ! 174: /*! ! 175: * @function doLockUnlockMedia ! 176: * @abstract ! 177: * Lock or unlock the (removable) media in the drive. ! 178: * @discussion ! 179: * This method should only be called if the media is known to be removable. ! 180: * @param doLock ! 181: * True to lock the media, False to unlock. ! 182: */ ! 183: virtual IOReturn doLockUnlockMedia(bool doLock) = 0; ! 184: ! 185: /*! ! 186: * @function doSynchronizeCache ! 187: * @abstract ! 188: * Force data blocks in the drive's buffer to be flushed to the media. ! 189: * @discussion ! 190: * This method should only be called if the media is writable. ! 191: */ ! 192: virtual IOReturn doSynchronizeCache(void) = 0; ! 193: ! 194: /*! ! 195: * @function executeCdb ! 196: * @abstract ! 197: * Issue the client's cdb as a pass-through. ! 198: * @discussion ! 199: * This method is provided to allow developers to issue arbitrary commands ! 200: * to the device (via the Transport Driver). Expected uses would include vendor-specific ! 201: * commands to effect password-protection, or for other vendor features. ! 202: * ! 203: * This method may not be supported by all Transport Drivers. For example, ATA devices ! 204: * do not have a CDB concept; those Transport Drivers will return kIOReturnUnsupported. ! 205: * @param params ! 206: * See IOHDTypes.h for the layout of this data structure. ! 207: */ ! 208: virtual IOReturn executeCdb(struct cdbParams *params) = 0; ! 209: ! 210: /*! ! 211: * @function getVendorString ! 212: * @abstract ! 213: * Return Vendor Name string for the device. ! 214: * @result ! 215: * A pointer to a static character string. ! 216: */ ! 217: virtual char * getVendorString(void) = 0; ! 218: ! 219: /*! ! 220: * @function getProductString ! 221: * @abstract ! 222: * Return Product Name string for the device. ! 223: * @result ! 224: * A pointer to a static character string. ! 225: */ ! 226: virtual char * getProductString(void) = 0; ! 227: ! 228: /*! ! 229: * @function getRevisionString ! 230: * @abstract ! 231: * Return Product Revision string for the device. ! 232: * @result ! 233: * A pointer to a static character string. ! 234: */ ! 235: virtual char * getRevisionString(void) = 0; ! 236: ! 237: /*! ! 238: * @function getAdditionalDeviceInfoString ! 239: * @abstract ! 240: * Return additional informational string for the device. ! 241: * @result ! 242: * A pointer to a static character string. ! 243: */ ! 244: virtual char * getAdditionalDeviceInfoString(void) = 0; ! 245: ! 246: /*! ! 247: * @function reportBlockSize ! 248: * @abstract ! 249: * Report the block size for the device, in bytes. ! 250: * @param blockSize ! 251: * Pointer to returned block size value. ! 252: */ ! 253: virtual IOReturn reportBlockSize(UInt64 *blockSize) = 0; ! 254: ! 255: /*! ! 256: * @function reportEjectability ! 257: * @abstract ! 258: * Report if the media is ejectable under software control. ! 259: * @discussion ! 260: * This method should only be called if the media is known to be removable. ! 261: * @param isEjectable ! 262: * Pointer to returned result. True indicates the media is ejectable, False indicates ! 263: * the media cannot be ejected under software control. ! 264: */ ! 265: virtual IOReturn reportEjectability(bool *isEjectable) = 0; ! 266: ! 267: /*! ! 268: * @function reportLockability ! 269: * @abstract ! 270: * Report if the media is lockable under software control. ! 271: * @discussion ! 272: * This method should only be called if the media is known to be removable. ! 273: * @param isLockable ! 274: * Pointer to returned result. True indicates the media can be locked in place; False ! 275: * indicates the media cannot be locked by software. ! 276: */ ! 277: virtual IOReturn reportLockability(bool *isLockable) = 0; ! 278: ! 279: /*! ! 280: * @function reportMaxReadTransfer ! 281: * @abstract ! 282: * Report the maximum allowed byte transfer for read operations. ! 283: * @discussion ! 284: * Some devices impose a maximum data transfer size. Because this limit ! 285: * may be determined by the size of a block-count field in a command, the limit may ! 286: * depend on the block size of the transfer. ! 287: * @param blockSize ! 288: * The block size desired for the transfer. ! 289: * @param max ! 290: * Pointer to returned result. ! 291: */ ! 292: virtual IOReturn reportMaxReadTransfer (UInt64 blockSize,UInt64 *max) = 0; ! 293: ! 294: /*! ! 295: * @function reportMaxWriteTransfer ! 296: * @abstract ! 297: * Report the maximum allowed byte transfer for write operations. ! 298: * @discussion ! 299: * Some devices impose a maximum data transfer size. Because this limit ! 300: * may be determined by the size of a block-count field in a command, the limit may ! 301: * depend on the block size of the transfer. ! 302: * @param blockSize ! 303: * The block size desired for the transfer. ! 304: * @param max ! 305: * Pointer to returned result. ! 306: */ ! 307: virtual IOReturn reportMaxWriteTransfer(UInt64 blockSize,UInt64 *max) = 0; ! 308: ! 309: /*! ! 310: * @function reportMaxValidBlock ! 311: * @abstract ! 312: * Report the highest valid block for the device. ! 313: * @param maxBlock ! 314: * Pointer to returned result ! 315: */ ! 316: virtual IOReturn reportMaxValidBlock(UInt64 *maxBlock) = 0; ! 317: ! 318: /*! ! 319: * @function reportMediaState ! 320: * @abstract ! 321: * Report the device's media state. ! 322: * @discussion ! 323: * This method reports whether we have media in the drive or not, and ! 324: * whether the state has changed from the previously reported state. ! 325: * ! 326: * A result of kIOReturnSuccess is always returned if the test for media is successful, ! 327: * regardless of media presence. The mediaPresent result should be used to determine ! 328: * whether media is present or not. A return other than kIOReturnSuccess indicates that ! 329: * the Transport Driver was unable to interrogate the device. In this error case, the ! 330: * outputs mediaState and changedState will *not* be stored. ! 331: * @param mediaPresent Pointer to returned media state. True indicates media is present ! 332: * in the device; False indicates no media is present. ! 333: * @param changedState Pointer to returned result. True indicates a change of state since ! 334: * prior calls, False indicates that the state has not changed. ! 335: */ ! 336: virtual IOReturn reportMediaState(bool *mediaPresent,bool *changedState) = 0; ! 337: ! 338: /*! ! 339: * @function reportPollRequirements ! 340: * @abstract ! 341: * Report if it's necessary to poll for media insertion, and if polling is expensive. ! 342: * @discussion ! 343: * This method reports whether the device must be polled to detect media ! 344: * insertion, and whether a poll is expensive to perform. ! 345: * ! 346: * The term "expensive" typically implies a device that must be spun-up to detect media, ! 347: * as on a PC floppy. Most devices can detect media inexpensively. ! 348: * @param pollRequired ! 349: * Pointer to returned result. True indicates that polling is required; False indicates ! 350: * that polling is not required to detect media. ! 351: * @param pollIsExpensive ! 352: * Pointer to returned result. True indicates that the polling operation is expensive; ! 353: * False indicates that the polling operation is cheap. ! 354: */ ! 355: virtual IOReturn reportPollRequirements(bool *pollRequired, ! 356: bool *pollIsExpensive) = 0; ! 357: ! 358: /*! ! 359: * @function reportRemovability ! 360: * @abstract ! 361: * Report whether the media is removable or not. ! 362: * @discussion ! 363: * This method reports whether the media is removable, but it does not ! 364: * provide detailed information regarding software eject or lock/unlock capability. ! 365: * @param isRemovable ! 366: * Pointer to returned result. True indicates that the media is removable; False ! 367: * indicates the media is not removable. ! 368: */ ! 369: virtual IOReturn reportRemovability(bool *isRemovable) = 0; ! 370: ! 371: /*! ! 372: * @function reportWriteProtection ! 373: * @abstract ! 374: * Report whether the media is write-protected or not. ! 375: * @param isWriteProtected ! 376: * Pointer to returned result. True indicates that the media is write-protected (it ! 377: * cannot be written); False indicates that the media is not write-protected (it ! 378: * is permissible to write). ! 379: */ ! 380: virtual IOReturn reportWriteProtection(bool *isWriteProtected) = 0; ! 381: }; ! 382: #endif
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.