iokit/IOKit/storage/scsi/IOSCSICDDrive.h

   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  * IOSCSICDDrive.h
  24  *
  25  * This class implements SCSI CDROM functionality.
  26  *
  27  * Subclasses may modify the operations to handle device-specific variations.
  28  */
  29
  30 #ifndef _IOSCSICDDRIVE_H
  31 #define _IOSCSICDDRIVE_H
  32
  33 #include <IOKit/IOTypes.h>
  34 #include <IOKit/scsi/IOSCSIDeviceInterface.h>
  35 #include <IOKit/storage/IOCDTypes.h>
  36 #include <IOKit/storage/scsi/IOSCSIHDDrive.h>
  37
  38 /* SCSI (inquiry) device type. */
  39
  40 enum {
  41     kIOSCSIDeviceTypeCDROM         = 0x05
  42 };
  43
  44 /* SCSI commands. */
  45
  46 enum {
  47     kIOSCSICommandReadSubChannel   = 0x42,
  48     kIOSCSICommandReadTOC          = 0x43,
  49     kIOSCSICommandPlayAudioMSF     = 0x47,
  50     kIOSCSICommandPauseResume      = 0x4b,
  51     kIOSCSICommandStopPlay         = 0x4e,
  52     kIOSCSICommandScan             = 0xba,
  53     kIOSCSICommandReadCD           = 0xbe
  54 };
  55
  56 struct IOAudioPlayMSFcdb {
  57     UInt8       opcode;
  58     UInt8       lunbits;
  59     UInt8       reserved1;
  60     UInt8       start_m;
  61     UInt8       start_s;
  62     UInt8       start_f;
  63     UInt8       end_m;
  64     UInt8       end_s;
  65     UInt8       end_f;
  66     UInt8       ctlbyte;
  67 };
  68
  69 struct IOReadToccdb {
  70     UInt8       opcode;
  71     UInt8       lunbits;
  72 static const UInt8      kMSF = 0x02;            /* set to get mm:ss:ff format, else logical addr */
  73     UInt8       reserved1;
  74     UInt8       reserved2;
  75     UInt8       reserved3;
  76     UInt8       reserved4;
  77     UInt8       start_trk_session;      /* starting track/session number */
  78     UInt8       len_hi;
  79     UInt8       len_lo;
  80     UInt8       ctlbyte;                /* and format code */
  81 static const UInt8      kTOC            = 0x00;
  82 static const UInt8      kSessionInfo    = 0x01;
  83 static const UInt8      kFullTOC        = 0x02;
  84 };
  85
  86 struct IORSCcdb {
  87     UInt8       opcode;
  88     UInt8       lunbits;
  89 static const UInt8      kMSF = 0x02;            /* set to get mm:ss:ff format, else logical addr */
  90     UInt8       subq;
  91 static const UInt8      kSubq = 0x40;           /* set to get subq data */
  92     UInt8       dataformat;
  93 static const UInt8      kCurrentPosition        = 1;
  94 static const UInt8      kMCN                    = 2;
  95 static const UInt8      kISRC                   = 3;
  96     UInt8       reserved1;
  97     UInt8       reserved2;
  98     UInt8       track;
  99     UInt8       len_hi;
 100     UInt8       len_lo;
 101     UInt8       ctlbyte;
 102 };
 103
 104 /*!
 105  * @class IOSCSICDDrive : public IOSCSIHDDrive
 106  * @abstract
 107  * Driver for SCSI CD-ROM drives.
 108  * @discussion
 109  * IOSCSICDDrive is a subclass of IOSCSIHDDrive. It adds appropriate CD-ROM
 110  * APIs (e.g. audio), and overrides some methods of IOSCSIHDDrive in order
 111  * to alter their behavior for CD-ROM devices.
 112  */
 113 /*------------------------------------------------*/
 114 class IOSCSICDDrive : public IOSCSIHDDrive {
 115
 116     OSDeclareDefaultStructors(IOSCSICDDrive)
 117
 118 public:
 119
 120     /* Overrides from IOService: */
 121
 122     virtual bool        init(OSDictionary * properties);
 123
 124     /* Overrides from IOBasicSCSI: */
 125
 126     /*!
 127      * @function deviceTypeMatches
 128      * @abstract
 129      * Determine if the device type matches that which we expect.
 130      * @discussion
 131      * This override allows us to check for the SCSI CD-ROM
 132      * device type instead of hard disk.
 133      * See IOBasicSCSI for details.
 134      */
 135     virtual bool        deviceTypeMatches(UInt8 inqBuf[],UInt32 inqLen,SInt32 *score);
 136
 137     /* End of IOBasicSCSI overrides */
 138
 139     /* IOSCSIHDDrive overrides: */
 140
 141     /*!
 142      * @function doAsyncReadWrite
 143      * @abstract
 144      * Start an asynchronous read or write operation.
 145      * @discussion
 146      * See IOBlockStorageDevice for details.
 147      */
 148     virtual IOReturn    doAsyncReadWrite(IOMemoryDescriptor *buffer,
 149                                             UInt32 block,UInt32 nblks,
 150                                             IOStorageCompletion completion);
 151
 152     /*!
 153      * @function doSyncReadWrite
 154      * @abstract
 155      * Perform a synchronous read or write operation.
 156      * @discussion
 157      * See IOBlockStorageDevice for details.
 158      */
 159     virtual IOReturn    doSyncReadWrite(IOMemoryDescriptor *buffer,UInt32 block,UInt32 nblks);
 160
 161     /*!
 162      * @function doFormatMedia
 163      * @abstract
 164      * Attempt to format the media.
 165      * @discussion
 166      * This override allows us to reject formatting attempts for CD-ROM.
 167      */
 168     virtual IOReturn    doFormatMedia(UInt64 byteCapacity);
 169
 170     /*!
 171      * @function doGetFormatCapacities
 172      * @abstract
 173      * Report available formatting capacities for the device/media.
 174      * @discussion
 175      * This override allows us to reject formatting attempts for CD-ROM.
 176      */
 177     virtual UInt32      doGetFormatCapacities(UInt64 * capacities,
 178                                             UInt32   capacitiesMaxCount) const;
 179
 180     /*!
 181      * @function doSynchronizeCache
 182      * @abstract
 183      * Issue a synchronize-cache command when finished with a drive.
 184      * @discussion
 185      * This override allows us to reject the operation, since we never write to CD-ROM.
 186      */
 187     virtual IOReturn    doSynchronizeCache(void);
 188
 189     /*!
 190      * @function getDeviceTypeName
 191      * @abstract
 192      * Return a character string for the device type.
 193      * @discussion
 194      * This override returns kIOBlockStorageDeviceTypeCDROM.
 195      */
 196     virtual const char * getDeviceTypeName(void);
 197     /*!
 198      * @function instantiateNub
 199      * @abstract
 200      * Create the device nub.
 201      * @discussion
 202      * This override instantiates an IOSCSICDDriveNub instead of an IOSCSIHDDriveNub.
 203      */
 204     virtual IOService * instantiateNub(void);
 205
 206     /* We want to track media changes to do cleanup.     */
 207     /*!
 208      * @function reportMediaState
 209      * @abstract
 210      * Report the device's media state.
 211      * @discussion
 212      * This override allows us to reset device settings when media changes.
 213      */
 214     virtual IOReturn    reportMediaState(bool *mediaPresent,bool *changed);
 215
 216     /* end of IOSCSIHDDrive overrides */
 217
 218     /*-----------------------------------------*/
 219     /* CD APIs                                 */
 220     /*-----------------------------------------*/
 221
 222     /*!
 223      * @abstract
 224      * Start an asynchronous read CD operation.
 225      * @param buffer
 226      * An IOMemoryDescriptor describing the data-transfer buffer.  Responsiblity for releasing the descriptor
 227      * rests with the caller.
 228      * @param timeStart
 229      * The starting M:S:F address of the data transfer.
 230      * @param timeStop
 231      * The ending M:S:F address of the data transfer.
 232      * @param sectorArea
 233      * Sector area(s) to read.
 234      * @param sectorType
 235      * Sector type that is expected.  The data transfer is terminated as soon as
 236      * data is encountered that does not match the expected type.
 237      * @param action
 238      * The C function called upon completion of the data transfer.
 239      * @param target
 240      * The C++ class "this" pointer, passed as an argument to "action."
 241      * @param param
 242      * This value is passed as an argument to "action." It is not validated or modified.
 243      */
 244
 245     virtual IOReturn    doAsyncReadCD(IOMemoryDescriptor *buffer,
 246                                       UInt32 block,UInt32 nblks,
 247                                       CDSectorArea sectorArea,
 248                                       CDSectorType sectorType,
 249                                       IOStorageCompletion completion);
 250
 251     /*!
 252      * @function readISRC
 253      * @abstract
 254      * Read the International Standard Recording Code for the specified track.
 255      * @param track
 256      * The track number from which to read the ISRC.
 257      * @param isrc
 258      * The buffer for the ISRC data.  Buffer contents will be zero-terminated.
 259      */
 260     virtual IOReturn    readISRC(UInt8 track,CDISRC isrc);
 261
 262     /*!
 263      * @function readMCN
 264      * @abstract
 265      * Read the Media Catalog Number (also known as the Universal Product Code).
 266      * @param mcn
 267      * The buffer for the MCN data.  Buffer contents will be zero-terminated.
 268      */
 269     virtual IOReturn    readMCN(CDMCN mcn);
 270
 271     /*!
 272      * @function readTOC
 273      * @abstract
 274      * Read the full Table Of Contents.
 275      * @param buffer
 276      * The buffer for the returned data.
 277      */
 278     virtual IOReturn    readTOC(IOMemoryDescriptor * buffer);
 279
 280     /*!
 281      * @function reportMaxWriteTransfer
 282      * @abstract
 283      * Report the maximum allowed byte transfer for write operations.
 284      * @discussion
 285      * This override lets us return zero for the max write transfer, since
 286      * we never write to CD-ROM media. See IOBasicSCSI for other details.
 287      */
 288     virtual IOReturn    reportMaxWriteTransfer(UInt64 blockSize,UInt64 *max);
 289
 290     /*!
 291      * @function reportWriteProtection
 292      * @abstract
 293      * Report whether the media is write-protected or not.
 294      * @discussion
 295      * This override lets us return TRUE in all cases. See IOBasicSCSI for details.
 296      */
 297     virtual IOReturn    reportWriteProtection(bool *isWriteProtected);
 298
 299     /*-----------------------------------------*/
 300     /*  APIs exported by IOCDAudioControl      */
 301     /*-----------------------------------------*/
 302
 303     /*!
 304      * @function audioPause
 305      * @abstract
 306      * Pause or resume the audio playback.
 307      * @param pause
 308      * True to pause playback; False to resume.
 309      */
 310     virtual IOReturn    audioPause(bool pause);
 311     /*!
 312      * @function audioPlay
 313      * @abstract
 314      * Play audio.
 315      * @param timeStart
 316      * The M:S:F address from which to begin.
 317      * @param timeStop
 318      * The M:S:F address at which to stop.
 319      */
 320     virtual IOReturn    audioPlay(CDMSF timeStart,CDMSF timeStop);
 321     /*!
 322      * @function audioScan
 323      * @abstract
 324      * Perform a fast-forward or fast-backward operation.
 325      * @param timeStart
 326      * The M:S:F address from which to begin.
 327      * @param reverse
 328      * True to go backward; False to go forward.
 329      */
 330     virtual IOReturn    audioScan(CDMSF timeStart,bool reverse);
 331     /*!
 332      * @function audioStop
 333      * @abstract
 334      * Stop the audio playback (or audio scan).
 335      */
 336     virtual IOReturn    audioStop();
 337     /*!
 338      * @function getAudioStatus
 339      * @abstract
 340      * Get the current audio play status information.
 341      * @param status
 342      * The buffer for the returned information.
 343      */
 344     virtual IOReturn    getAudioStatus(CDAudioStatus *status);
 345     /*!
 346      * @function getAudioVolume
 347      * @abstract
 348      * Get the current audio volume.
 349      * @param leftVolume
 350      * A pointer to the returned left-channel volume.
 351      * @param rightVolume
 352      * A pointer to the returned right-channel volume.
 353      */
 354     virtual IOReturn    getAudioVolume(UInt8 *leftVolume,UInt8 *rightVolume);
 355     /*!
 356      * @function setAudioVolume
 357      * @abstract
 358      * Set the current audio volume.
 359      * @param leftVolume
 360      * The desired left-channel volume.
 361      * @param rightVolume
 362      * The desired right-channel volume.
 363      */
 364     virtual IOReturn    setAudioVolume(UInt8 leftVolume,UInt8 rightVolume);
 365
 366 protected:
 367
 368     /* Internally used methods: */
 369
 370     /*!
 371      * @function doAudioPlayCommand
 372      * @abstract
 373      * Issue an audio play command to the device.
 374      * @param timeStart
 375      * The M:S:F address from which to begin.
 376      * @param timeStop
 377      * The M:S:F address at which to stop.
 378      */
 379     virtual IOReturn    doAudioPlayCommand(CDMSF timeStart,CDMSF timeStop);
 380
 381     /*!
 382      * @function mediaArrived
 383      * @abstract
 384      * React to new media arrival.
 385      */
 386     virtual void        mediaArrived(void);
 387
 388     /*!
 389      * @function mediaGone
 390      * @abstract
 391      * React to media going away.
 392      */
 393     virtual void        mediaGone(void);
 394
 395     /*!
 396      * @function readSubChannel
 397      * @abstract
 398      * Issue the command necessary to read subchannel data.
 399      * @param buffer
 400      * The buffer for the data.
 401      * @param length
 402      * The maximum data length desired.
 403      * @param dataFormat
 404      * The subchannel data desired.
 405      * @param track
 406      * The desired track from which to read the data
 407      */
 408     virtual IOReturn    readSubChannel(UInt8 *buffer,UInt32 length,UInt8 dataFormat,UInt8 trackNumber);
 409 };
 410 #endif