1/* 2 * Copyright (c) 1998-2012 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 IOCDMedia 26 * @abstract 27 * This header contains the IOCDMedia class definition. 28 */ 29 30#ifndef _IOCDMEDIA_H 31#define _IOCDMEDIA_H 32 33/*! 34 * @defined kIOCDMediaClass 35 * @abstract 36 * kIOCDMediaClass is the name of the IOCDMedia class. 37 * @discussion 38 * kIOCDMediaClass is the name of the IOCDMedia class. 39 */ 40 41#define kIOCDMediaClass "IOCDMedia" 42 43/*! 44 * @defined kIOCDMediaTOCKey 45 * @abstract 46 * kIOCDMediaTOCKey is a property of IOCDMedia objects. It has an OSData value 47 * and a CDTOC structure. 48 * @discussion 49 * The kIOCDMediaTOCKey property contains the CD's full table of contents, 50 * formatted as a CDTOC structure. The CDTOC structure is same as what is 51 * returned by a READ TOC command, format 0x02. All fields in the TOC are 52 * guaranteed to be binary-encoded (no BCD-encoded numbers are ever passed). 53 */ 54 55#define kIOCDMediaTOCKey "TOC" 56 57/*! 58 * @defined kIOCDMediaTypeKey 59 * @abstract 60 * kIOCDMediaTypeKey is a property of IOCDMedia objects. It has an OSString 61 * value. 62 * @discussion 63 * The kIOCDMediaTypeKey property identifies the CD media type (CD-ROM, CD-R, 64 * CD-RW, etc). See the kIOCDMediaType contants for possible values. 65 */ 66 67#define kIOCDMediaTypeKey "Type" 68 69/*! 70 * @defined kIOCDMediaTypeROM 71 * The kIOCDMediaTypeKey constant for CD-ROM media (inclusive of the CD-I, 72 * CD-ROM XA, and CD Audio standards, and mixed mode combinations thereof). 73 */ 74 75#define kIOCDMediaTypeROM "CD-ROM" 76 77/*! 78 * @defined kIOCDMediaTypeR 79 * The kIOCDMediaTypeKey constant for CD Recordable (CD-R) media. 80 */ 81 82#define kIOCDMediaTypeR "CD-R" 83 84/*! 85 * @defined kIOCDMediaTypeRW 86 * The kIOCDMediaTypeKey constant for CD ReWritable (CD-RW) media. 87 */ 88 89#define kIOCDMediaTypeRW "CD-RW" 90 91#ifdef KERNEL 92#ifdef __cplusplus 93 94/* 95 * Kernel 96 */ 97 98#include <IOKit/storage/IOCDBlockStorageDriver.h> 99#include <IOKit/storage/IOMedia.h> 100 101/*! 102 * @class IOCDMedia 103 * @abstract 104 * The IOCDMedia class is a random-access disk device abstraction for CDs. 105 * @discussion 106 * The IOCDMedia class is a random-access disk device abstraction for CDs. It 107 * extends the IOMedia class by implementing special CD APIs, such as readCD, 108 * and publishing the TOC as a property of the IOCDMedia object. 109 */ 110 111class IOCDMedia : public IOMedia 112{ 113 OSDeclareDefaultStructors(IOCDMedia) 114 115protected: 116 117 struct ExpansionData { /* */ }; 118 ExpansionData * _expansionData; 119 120public: 121 122 using IOStorage::read; 123 using IOStorage::write; 124 125 /* 126 * Obtain this object's provider. We override the superclass's method to 127 * return a more specific subclass of IOService -- IOCDBlockStorageDriver. 128 * This method serves simply as a convenience to subclass developers. 129 */ 130 131 virtual IOCDBlockStorageDriver * getProvider() const; 132 133 /* 134 * Compare the properties in the supplied table to this object's properties. 135 */ 136 137 virtual bool matchPropertyTable(OSDictionary * table, SInt32 * score); 138 139 /*! 140 * @function read 141 * @discussion 142 * Read data from the storage object at the specified byte offset into the 143 * specified buffer, asynchronously. When the read completes, the caller 144 * will be notified via the specified completion action. 145 * 146 * The buffer will be retained for the duration of the read. 147 * @param client 148 * Client requesting the read. 149 * @param byteStart 150 * Starting byte offset for the data transfer. 151 * @param buffer 152 * Buffer for the data transfer. The size of the buffer implies the size of 153 * the data transfer. 154 * @param attributes 155 * Attributes of the data transfer. See IOStorageAttributes. It is the 156 * responsibility of the callee to maintain the information for the duration 157 * of the data transfer, as necessary. 158 * @param completion 159 * Completion routine to call once the data transfer is complete. It is the 160 * responsibility of the callee to maintain the information for the duration 161 * of the data transfer, as necessary. 162 */ 163 164 virtual void read(IOService * client, 165 UInt64 byteStart, 166 IOMemoryDescriptor * buffer, 167 IOStorageAttributes * attributes, 168 IOStorageCompletion * completion); 169 170 /* 171 * @function write 172 * @discussion 173 * Write data into the storage object at the specified byte offset from the 174 * specified buffer, asynchronously. When the write completes, the caller 175 * will be notified via the specified completion action. 176 * 177 * The buffer will be retained for the duration of the write. 178 * @param client 179 * Client requesting the write. 180 * @param byteStart 181 * Starting byte offset for the data transfer. 182 * @param buffer 183 * Buffer for the data transfer. The size of the buffer implies the size of 184 * the data transfer. 185 * @param attributes 186 * Attributes of the data transfer. See IOStorageAttributes. It is the 187 * responsibility of the callee to maintain the information for the duration 188 * of the data transfer, as necessary. 189 * @param completion 190 * Completion routine to call once the data transfer is complete. It is the 191 * responsibility of the callee to maintain the information for the duration 192 * of the data transfer, as necessary. 193 */ 194 195 virtual void write(IOService * client, 196 UInt64 byteStart, 197 IOMemoryDescriptor * buffer, 198 IOStorageAttributes * attributes, 199 IOStorageCompletion * completion); 200 201 /*! 202 * @function readCD 203 * @discussion 204 * Read data from the CD media object at the specified byte offset into the 205 * specified buffer, asynchronously. Special areas of the CD sector can be 206 * read via this method, such as the header and subchannel data. When the 207 * read completes, the caller will be notified via the specified completion 208 * action. 209 * 210 * The buffer will be retained for the duration of the read. 211 * @param client 212 * Client requesting the read. 213 * @param byteStart 214 * Starting byte offset for the data transfer (see sectorArea parameter). 215 * @param buffer 216 * Buffer for the data transfer. The size of the buffer implies the size of 217 * the data transfer. 218 * @param sectorArea 219 * Sector area(s) to read. The sum of each area's size defines the natural 220 * block size of the media for the call. This should be taken into account 221 * when computing the address of byteStart. See IOCDTypes.h. 222 * @param sectorType 223 * Sector type that is expected. The data transfer is terminated as soon as 224 * data is encountered that does not match the expected type. 225 * @param attributes 226 * Attributes of the data transfer. See IOStorageAttributes. It is the 227 * responsibility of the callee to maintain the information for the duration 228 * of the data transfer, as necessary. 229 * @param completion 230 * Completion routine to call once the data transfer is complete. It is the 231 * responsibility of the callee to maintain the information for the duration 232 * of the data transfer, as necessary. 233 */ 234 235#ifdef __LP64__ 236 virtual void readCD(IOService * client, 237 UInt64 byteStart, 238 IOMemoryDescriptor * buffer, 239 CDSectorArea sectorArea, 240 CDSectorType sectorType, 241 IOStorageAttributes * attributes, 242 IOStorageCompletion * completion); 243#else /* !__LP64__ */ 244 virtual void readCD(IOService * client, 245 UInt64 byteStart, 246 IOMemoryDescriptor * buffer, 247 CDSectorArea sectorArea, 248 CDSectorType sectorType, 249 IOStorageCompletion completion); 250#endif /* !__LP64__ */ 251 252 /*! 253 * @function readCD 254 * @discussion 255 * Read data from the CD media object at the specified byte offset into the 256 * specified buffer, synchronously. Special areas of the CD sector can be 257 * read via this method, such as the header and subchannel data. When the 258 * read completes, this method will return to the caller. The actual byte 259 * count field is optional. 260 * @param client 261 * Client requesting the read. 262 * @param byteStart 263 * Starting byte offset for the data transfer (see sectorArea parameter). 264 * @param buffer 265 * Buffer for the data transfer. The size of the buffer implies the size of 266 * the data transfer. 267 * @param sectorArea 268 * Sector area(s) to read. The sum of each area's size defines the natural 269 * block size of the media for the call. This should be taken into account 270 * when computing the address of byteStart. See IOCDTypes.h. 271 * @param sectorType 272 * Sector type that is expected. The data transfer is terminated as soon as 273 * data is encountered that does not match the expected type. 274 * @param attributes 275 * Attributes of the data transfer. See IOStorageAttributes. 276 * @param actualByteCount 277 * Returns the actual number of bytes transferred in the data transfer. 278 * @result 279 * Returns the status of the data transfer. 280 */ 281 282#ifdef __LP64__ 283 virtual IOReturn readCD(IOService * client, 284 UInt64 byteStart, 285 IOMemoryDescriptor * buffer, 286 CDSectorArea sectorArea, 287 CDSectorType sectorType, 288 IOStorageAttributes * attributes = 0, 289 UInt64 * actualByteCount = 0); 290#else /* !__LP64__ */ 291 virtual IOReturn readCD(IOService * client, 292 UInt64 byteStart, 293 IOMemoryDescriptor * buffer, 294 CDSectorArea sectorArea, 295 CDSectorType sectorType, 296 UInt64 * actualByteCount = 0); 297#endif /* !__LP64__ */ 298 299 /*! 300 * @function readISRC 301 * @discussion 302 * Read the International Standard Recording Code for the specified track. 303 * @param track 304 * Track number from which to read the ISRC. 305 * @param isrc 306 * Buffer for the ISRC data. Buffer contents will be zero-terminated. 307 * @result 308 * Returns the status of the operation. 309 */ 310 311 virtual IOReturn readISRC(UInt8 track, CDISRC isrc); 312 313 /*! 314 * @function readMCN 315 * @discussion 316 * Read the Media Catalog Number (also known as the Universal Product Code). 317 * @param mcn 318 * Buffer for the MCN data. Buffer contents will be zero-terminated. 319 * @result 320 * Returns the status of the operation. 321 */ 322 323 virtual IOReturn readMCN(CDMCN mcn); 324 325 /*! 326 * @function getTOC 327 * @discussion 328 * Get the full Table Of Contents. 329 * 330 * All CDTOC fields passed across I/O Kit APIs are guaranteed to be 331 * binary-encoded (no BCD-encoded numbers are ever passed). 332 * @result 333 * Returns a pointer to the TOC buffer (do not deallocate). 334 */ 335 336 virtual CDTOC * getTOC(); 337 338 /*! 339 * @function getSpeed 340 * @discussion 341 * Get the current speed used for data transfers. 342 * @param kilobytesPerSecond 343 * Returns the current speed used for data transfers, in kB/s. 344 * 345 * kCDSpeedMin specifies the minimum speed for all CD media (1X). 346 * kCDSpeedMax specifies the maximum speed supported in hardware. 347 * @result 348 * Returns the status of the operation. 349 */ 350 351 virtual IOReturn getSpeed(UInt16 * kilobytesPerSecond); /* 10.1.0 */ 352 353 /*! 354 * @function setSpeed 355 * @discussion 356 * Set the speed to be used for data transfers. 357 * @param kilobytesPerSecond 358 * Speed to be used for data transfers, in kB/s. 359 * 360 * kCDSpeedMin specifies the minimum speed for all CD media (1X). 361 * kCDSpeedMax specifies the maximum speed supported in hardware. 362 * @result 363 * Returns the status of the operation. 364 */ 365 366 virtual IOReturn setSpeed(UInt16 kilobytesPerSecond); /* 10.1.0 */ 367 368 /*! 369 * @function readTOC 370 * @discussion 371 * Issue an MMC READ TOC/PMA/ATIP command. 372 * @param buffer 373 * Buffer for the data transfer. The size of the buffer implies the size of 374 * the data transfer. 375 * @param format 376 * As documented by MMC. 377 * @param formatAsTime 378 * As documented by MMC. 379 * @param trackOrSessionNumber 380 * As documented by MMC. 381 * @param actualByteCount 382 * Returns the actual number of bytes transferred in the data transfer. 383 * @result 384 * Returns the status of the data transfer. 385 */ 386 387 virtual IOReturn readTOC(IOMemoryDescriptor * buffer, 388 CDTOCFormat format, 389 UInt8 formatAsTime, 390 UInt8 trackOrSessionNumber, 391 UInt16 * actualByteCount); /* 10.1.3 */ 392 393 /*! 394 * @function readDiscInfo 395 * @discussion 396 * Issue an MMC READ DISC INFORMATION command. 397 * @param buffer 398 * Buffer for the data transfer. The size of the buffer implies the size of 399 * the data transfer. 400 * @param actualByteCount 401 * Returns the actual number of bytes transferred in the data transfer. 402 * @result 403 * Returns the status of the data transfer. 404 */ 405 406 virtual IOReturn readDiscInfo(IOMemoryDescriptor * buffer, 407 UInt16 * actualByteCount); /* 10.1.3 */ 408 409 /*! 410 * @function readTrackInfo 411 * @discussion 412 * Issue an MMC READ TRACK INFORMATION command. 413 * @param buffer 414 * Buffer for the data transfer. The size of the buffer implies the size of 415 * the data transfer. 416 * @param address 417 * As documented by MMC. 418 * @param addressType 419 * As documented by MMC. 420 * @param actualByteCount 421 * Returns the actual number of bytes transferred in the data transfer. 422 * @result 423 * Returns the status of the data transfer. 424 */ 425 426 virtual IOReturn readTrackInfo(IOMemoryDescriptor * buffer, 427 UInt32 address, 428 CDTrackInfoAddressType addressType, 429 UInt16 * actualByteCount); /* 10.1.3 */ 430 431 /* 432 * @function writeCD 433 * @discussion 434 * Write data into the CD media object at the specified byte offset from the 435 * specified buffer, asynchronously. When the write completes, the caller 436 * will be notified via the specified completion action. 437 * 438 * The buffer will be retained for the duration of the write. 439 * @param client 440 * Client requesting the write. 441 * @param byteStart 442 * Starting byte offset for the data transfer (see sectorArea parameter). 443 * @param buffer 444 * Buffer for the data transfer. The size of the buffer implies the size of 445 * the data transfer. 446 * @param sectorArea 447 * Sector area(s) to write. The sum of each area's size defines the natural 448 * block size of the media for the call. This should be taken into account 449 * when computing the address of byteStart. See IOCDTypes.h. 450 * @param sectorType 451 * Sector type that is expected. 452 * @param attributes 453 * Attributes of the data transfer. See IOStorageAttributes. It is the 454 * responsibility of the callee to maintain the information for the duration 455 * of the data transfer, as necessary. 456 * @param completion 457 * Completion routine to call once the data transfer is complete. It is the 458 * responsibility of the callee to maintain the information for the duration 459 * of the data transfer, as necessary. 460 */ 461 462#ifdef __LP64__ 463 virtual void writeCD(IOService * client, 464 UInt64 byteStart, 465 IOMemoryDescriptor * buffer, 466 CDSectorArea sectorArea, 467 CDSectorType sectorType, 468 IOStorageAttributes * attributes, 469 IOStorageCompletion * completion); 470#else /* !__LP64__ */ 471 virtual void writeCD(IOService * client, 472 UInt64 byteStart, 473 IOMemoryDescriptor * buffer, 474 CDSectorArea sectorArea, 475 CDSectorType sectorType, 476 IOStorageCompletion completion); /* 10.2.0 */ 477#endif /* !__LP64__ */ 478 479 /* 480 * @function writeCD 481 * @discussion 482 * Write data into the CD media object at the specified byte offset from the 483 * specified buffer, synchronously. When the write completes, this method 484 * will return to the caller. The actual byte count field is optional. 485 * @param client 486 * Client requesting the write. 487 * @param byteStart 488 * Starting byte offset for the data transfer (see sectorArea parameter). 489 * @param buffer 490 * Buffer for the data transfer. The size of the buffer implies the size of 491 * the data transfer. 492 * @param sectorArea 493 * Sector area(s) to write. The sum of each area's size defines the natural 494 * block size of the media for the call. This should be taken into account 495 * when computing the address of byteStart. See IOCDTypes.h. 496 * @param sectorType 497 * Sector type that is expected. 498 * @param attributes 499 * Attributes of the data transfer. See IOStorageAttributes. 500 * @param actualByteCount 501 * Returns the actual number of bytes transferred in the data transfer. 502 * @result 503 * Returns the status of the data transfer. 504 */ 505 506#ifdef __LP64__ 507 virtual IOReturn writeCD(IOService * client, 508 UInt64 byteStart, 509 IOMemoryDescriptor * buffer, 510 CDSectorArea sectorArea, 511 CDSectorType sectorType, 512 IOStorageAttributes * attributes = 0, 513 UInt64 * actualByteCount = 0); 514#else /* !__LP64__ */ 515 virtual IOReturn writeCD(IOService * client, 516 UInt64 byteStart, 517 IOMemoryDescriptor * buffer, 518 CDSectorArea sectorArea, 519 CDSectorType sectorType, 520 UInt64 * actualByteCount = 0); /* 10.2.0 */ 521#endif /* !__LP64__ */ 522 523#ifdef __LP64__ 524 OSMetaClassDeclareReservedUnused(IOCDMedia, 0); 525 OSMetaClassDeclareReservedUnused(IOCDMedia, 1); 526 OSMetaClassDeclareReservedUnused(IOCDMedia, 2); 527 OSMetaClassDeclareReservedUnused(IOCDMedia, 3); 528 OSMetaClassDeclareReservedUnused(IOCDMedia, 4); 529 OSMetaClassDeclareReservedUnused(IOCDMedia, 5); 530 OSMetaClassDeclareReservedUnused(IOCDMedia, 6); 531#else /* !__LP64__ */ 532 OSMetaClassDeclareReservedUsed(IOCDMedia, 0); 533 OSMetaClassDeclareReservedUsed(IOCDMedia, 1); 534 OSMetaClassDeclareReservedUsed(IOCDMedia, 2); 535 OSMetaClassDeclareReservedUsed(IOCDMedia, 3); 536 OSMetaClassDeclareReservedUsed(IOCDMedia, 4); 537 OSMetaClassDeclareReservedUsed(IOCDMedia, 5); 538 OSMetaClassDeclareReservedUsed(IOCDMedia, 6); 539#endif /* !__LP64__ */ 540 OSMetaClassDeclareReservedUnused(IOCDMedia, 7); 541 OSMetaClassDeclareReservedUnused(IOCDMedia, 8); 542 OSMetaClassDeclareReservedUnused(IOCDMedia, 9); 543 OSMetaClassDeclareReservedUnused(IOCDMedia, 10); 544 OSMetaClassDeclareReservedUnused(IOCDMedia, 11); 545 OSMetaClassDeclareReservedUnused(IOCDMedia, 12); 546 OSMetaClassDeclareReservedUnused(IOCDMedia, 13); 547 OSMetaClassDeclareReservedUnused(IOCDMedia, 14); 548 OSMetaClassDeclareReservedUnused(IOCDMedia, 15); 549}; 550 551#endif /* __cplusplus */ 552#endif /* KERNEL */ 553#endif /* !_IOCDMEDIA_H */ 554