![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IOBasicSCSI.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 / scsi|
Return to IOBasicSCSI.h CVS log | Up to [Apple XNU] / XNU / iokit / IOKit / storage / scsi |
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: * IOBasicSCSI.h
26: *
27: * This class implements generic SCSI functionality.
28: */
29:
30: #ifndef _IOBASICSCSI_H
31: #define _IOBASICSCSI_H
32:
33: #include <IOKit/IOTypes.h>
34: #include <IOKit/IOService.h>
35: #include <IOKit/IOSyncer.h>
36: #include <IOKit/scsi/IOSCSIDeviceInterface.h>
37: #include <IOKit/storage/IOHDTypes.h>
38:
39: const int kMinInqSize = 5; /* minimal, supported by all devs */
40: const int kReadCapSize = 8;
41: const int kModeSenseSize = 64;
42: const int kMaxInqSize = 256;
43:
44: const int kCheckCondition = 0x02;
45: const int kUnitAttention = 0x06;
46:
47: /* SCSI operation codes: */
48:
49: const UInt8 SOP_TUR = 0x00; /* test unit ready */
50: const UInt8 SOP_INQUIRY = 0x12; /* inquiry */
51: const UInt8 SOP_MODESELECT = 0x15; /* mode select */
52: const UInt8 SOP_MODESENSE = 0x1a; /* mode sense */
53: const UInt8 SOP_READCAP = 0x25; /* read capacity */
54: const UInt8 SOP_READ10 = 0x28; /* read (10-byte) */
55: const UInt8 SOP_WRITE10 = 0x2a; /* write (10-byte) */
56:
57: struct IOTURcdb {
58: UInt8 opcode;
59: UInt8 lunbits;
60: UInt8 reserved1;
61: UInt8 reserved2;
62: UInt8 reserved3;
63: UInt8 ctlbyte;
64: };
65:
66: struct IORWcdb { /* CDB for read and write */
67: UInt8 opcode; /* read=0x28, write=0x2a */
68: UInt8 lunbits; /* lun and control bits */
69: UInt8 lba_3; /* logical block address: msb */
70: UInt8 lba_2;
71: UInt8 lba_1;
72: UInt8 lba_0; /* logical block address: lsb */
73: UInt8 reserved;
74: UInt8 count_msb; /* block count: msb */
75: UInt8 count_lsb; /* block count: lsb */
76: UInt8 ctlbyte;
77: };
78:
79: struct IOInquirycdb { /* inquiry */
80: UInt8 opcode; /* 0x12 */
81: UInt8 lunbits; /* lun and control bits */
82: UInt8 pagecode; /* page code/op code */
83: UInt8 reserved;
84: UInt8 len; /* allocation length */
85: UInt8 ctlbyte;
86: };
87:
88: struct IOReadCapcdb {
89: UInt8 opcode;
90: UInt8 lunbits;
91: UInt8 lba_3;
92: UInt8 lba_2;
93: UInt8 lba_1;
94: UInt8 lba_0;
95: UInt8 reserved1;
96: UInt8 reserved2;
97: UInt8 reserved3;
98: UInt8 ctlbyte;
99: };
100:
101: struct IOModeSensecdb {
102: UInt8 opcode;
103: UInt8 lunbits; /* lun and control bits */
104: UInt8 pagecode;
105: UInt8 reserved;
106: UInt8 len; /* allocation length */
107: UInt8 ctlbyte;
108: };
109:
110: struct IOModeSelectcdb {
111: UInt8 opcode;
112: UInt8 lunbits;
113: UInt8 reserved1;
114: UInt8 reserved2;
115: UInt8 paramlen;
116: UInt8 ctlbyte;
117: };
118:
119: /*!
120: * @enum stateValues
121: * @discussion
122: * These state values are used to determin the state of an IO operation.
123: * Some are simply for debugging use.
124: * @constant kNone
125: * Nothing happening.
126: * @constant kAsyncReadWrite
127: * Doing an asynchronous IO operation.
128: * @constant kSimpleSynchIO
129: * Doing a simple synchronous IO operation.
130: * @constant kHandlingUnitAttention
131: * Currently handling a Unit-Attention condition.
132: * @constant kDoneHandlingUnitAttention
133: * Done handling Unit Attention; command should be reissued.
134: * @constant kAwaitingPower
135: * Awaiting power.
136: * @constant kMaxValidState
137: * The maximum valid state value.
138: * @constant kMaxStateValue
139: * The maximum state value possible.
140: */
141: enum stateValues {
142: kNone = 0,
143: kAsyncReadWrite = 1,
144: kSimpleSynchIO = 2,
145: kHandlingUnitAttention = 3,
146: kDoneHandlingUnitAttention = 4,
147: kAwaitingPower = 5,
148:
149: kMaxValidState = kAwaitingPower,
150:
151: kMaxStateValue = 255
152: };
153: /*!
154: * @typedef statevalue
155: * @discussion
156: * Shorthand for enum StateValues.
157: */
158: typedef enum stateValues stateValue;
159:
160: const bool kSync = true; /* type info for requests awaiting power */
161: const bool kAsync = false;
162:
163: /*!
164: * @class
165: * IOBasicSCSI : public IOService
166: * @abstract
167: * Basic SCSI support functions.
168: * @discussion
169: * IOBasicSCSI provides a set of basic SCSI functions and support
170: * utilities. It is intended to be the base class for a SCSI Transport
171: * Driver.
172: */
173:
174: class IOBasicSCSI : public IOService {
175:
176: OSDeclareAbstractStructors(IOBasicSCSI)
177:
178: public:
179:
180: /*!
181: * @struct completion
182: * @field action
183: * The C function called upon completion of the operation.
184: * @field target
185: * The C++ class pointer, passed to tha action function.
186: * @field param
187: * A value passed to the action function. This value is not touched.
188: */
189: /*!
190: * @struct context
191: * @discussion
192: * The context structure contains all persistent information needed for a
193: * synchronous or asynchronous IO operation.
194: * @field completion
195: * The completion information for an asynchronous read or write operation.
196: * @field state
197: * The current state of the operation.
198: * @field step
199: * The current step value, if we are handling a Unit Attention.
200: * @field originalContext
201: * A pointer to the context for the command that caused the Unit Attention
202: * condition.
203: * @field scsireq
204: * A pointer to the IOSCSIRequest object.
205: * @field memory
206: * The data buffer for the operation. A pointer to an IOMemoryDescriptor.
207: * @field scsiresult
208: * A pointer to the IOSCSIResult object.
209: * @field desiredPower
210: * The desired power level for the operation to execute.
211: * @field isSync
212: * True if synchronous; False if asynchronous.
213: * @field next
214: * A pointer to a context structure, used as a queue forward-link.
215: * @field sync
216: * A syncer used to block a thread awaiting a power level, or for completion
217: * of a synchronous operation.
218: */
219: struct context {
220:
221: /* Completion information for our client, used only for async operations.
222: * Typically this information will only be used by subclasses.
223: */
224:
225: struct {
226: gdCompletionFunction action; /* function to call */
227: IOService *target; /* client object ("this") */
228: void *param; /* client's parameter */
229: } completion;
230:
231: /* Parameters used during an IO retry: */
232:
233: stateValue state; /* what state we're in */
234: UInt32 step;
235: struct context *originalIOContext; /* original SCSI IO if doing a retry */
236:
237: IOMemoryDescriptor *memory;
238:
239: UInt32 desiredPower; /* desired power level state */
240: bool isSync; /* true if sync, false if async */
241: struct context *next; /* for queue of requests pending power */
242: /* Parameters to hand off to the SCSI provider: */
243:
244: IOSCSICommand *scsireq;
245: SCSISenseData *senseData;
246: IOMemoryDescriptor *senseDataDesc;
247:
248: IOSyncer *sync; /* to wait for completion */
249: };
250:
251: /* Overrides from IOService: */
252:
253: virtual void free(void);
254:
255: virtual bool init(OSDictionary * properties);
256:
257: /*!
258: * @function probe
259: * @abstract
260: * Determine if device matches expected type.
261: * @discussion
262: * This method is responsible for matching the device type. It calls
263: * doInquiry to issue a SCSI Inquiry command to the device, then calls
264: * deviceTypeMatches to ensure that the device type matches the expected
265: * type. If the device type matches, then the Vendor, Product, and
266: * Revision strings are copied from the inquiry data, and "this" is
267: * returned. If the device type does not match, NULL is returned.
268: *
269: * The default implementation ignores the score parameter, though that
270: * parameter is passed to the superclass probe method.
271: */
272: virtual IOService * probe(IOService * provider,SInt32 * score);
273:
274: /* --- end of IOService overrides --- */
275:
276: /*!
277: * @function deviceTypeMatches
278: * @abstract
279: * Determine if device type matches expected type.
280: * @discussion
281: * This method must be implemented by a device-specific subclass.
282: * @param inqBuf
283: * A pointer to the SCSI inquiry data for the device.
284: * @param inqLen
285: * The size of the data in the inquiry buffer.
286: * @result
287: * True indicates a match; False indicates a failure.
288: */
289: virtual bool deviceTypeMatches(UInt8 inqBuf[],UInt32 inqLen) = 0;
290:
291: /*!
292: * @function executeCdb
293: * Issue the client's cdb as a pass-through.
294: * @discussion This method is provided to allow developers to issue arbitrary commands
295: * to the device (via the Transport Driver). Expected uses might include vendor-specific
296: * commands to support device-based password-protection, or for other vendor features.
297: *
298: * This method may not be supported by all Transport Drivers. For example, ATA devices
299: * do not have a CDB concept; those Transport Drivers will return kIOReturnUnsupported.
300: * @param params
301: * See IOHDTypes.h for the layout of this data structure.
302: */
303: virtual IOReturn executeCdb(struct cdbParams *params);
304:
305: /*!
306: * @function getAdditionalDeviceInfoString
307: * @abstract
308: * Return additional informational string for the device.
309: * @result
310: * A pointer to a static character string. The default implementation
311: * returns "[SCSI]" .
312: */
313: virtual char * getAdditionalDeviceInfoString(void);
314:
315: /*!
316: * @function getVendorString
317: * @abstract
318: * Return Vendor Name string
319: * @result
320: * A pointer to a static character string, copied from the inquiry data.
321: */
322: virtual char * getVendorString(void);
323:
324: /*!
325: * @function getProductString
326: * @abstract
327: * Return Product Name string for the device.
328: * @result
329: A pointer to a static character string, copied from the inquiry data.
330: */
331: virtual char * getProductString(void);
332:
333: /*!
334: * @function getRevisionString
335: * @abstract
336: * Return Product Revision string for the device.
337: * @result
338: * A pointer to a static character string, copied from the inquiry data.
339: */
340: virtual char * getRevisionString(void);
341:
342: /*!
343: * @function reportBlockSize
344: * @abstract
345: * Report the block size for the device, in bytes.
346: * @discussion
347: * This method returns the block size for the media. The default
348: * implementation obtains the block size from the SCSI Read Capacity
349: * command. Since the result of the Read Capacity is used by this
350: * method and reportMaxValidBlock, this method either returns a cached
351: * value or calls doReadCapacity to issue the command and cache both
352: * values.
353: * @param blockSize
354: * Pointer to returned block size value.
355: */
356: virtual IOReturn reportBlockSize(UInt64 *blockSize);
357:
358: /*!
359: * @function reportEjectability
360: * @abstract
361: * Report if the media is ejectable under software control.
362: * @discussion
363: * This method reports whether the media is ejectable under software
364: * control. The default implementation always reports that removable
365: * media is ejectable.
366: *
367: * This method should only be called if the media is known to be removable.
368: * @param isEjectable
369: * Pointer to returned result. True indicates the media is ejectable, False indicates
370: * the media cannot be ejected under software control.
371: */
372: virtual IOReturn reportEjectability(bool *isEjectable);
373:
374: /*!
375: * @function reportLockability
376: * @abstract
377: * Report if the media is lockable under software control.
378: * @discussion
379: * This method reports whether the media can be locked under software
380: * control, to prevent the user from removing the media manually, e.g.
381: * by pressing a button on the drive. This method is only called by
382: * the generic driver when the media is known to be removable. The
383: * default implementation always returns true.
384: *
385: * This method should only be called if the media is known to be removable.
386: * @param isLockable
387: * Pointer to returned result. True indicates the media can be locked in place; False
388: * indicates the media cannot be locked by software.
389: */
390: virtual IOReturn reportLockability(bool *isLockable);
391:
392: /*!
393: * @function reportMaxReadTransfer
394: * @abstract
395: * Report the maximum allowed byte transfer for read operations.
396: * @discussion
397: * Some devices impose a maximum data transfer size. Because this limit
398: * may be determined by the size of a block-count field in a command, the limit may
399: * depend on the block size of the transfer.
400: * The default implementation reports blocksize * 65536, which is the maximum
401: * number of bytes that can be transferred
402: * in a SCSI command with a standard 16-bit block count field.
403: * @param blockSize
404: * The block size desired for the transfer.
405: * @param max
406: * Pointer to returned result.
407: */
408: virtual IOReturn reportMaxReadTransfer (UInt64 blocksize,UInt64 *max);
409:
410: /*!
411: * @function reportMaxValidBlock
412: * @abstract
413: * Report the highest valid block for the device.
414: * @discussion
415: * This method reports the maximum allowable block number. The default
416: * implementation obtains the block number from the SCSI Read Capacity
417: * command. Since the result of the Read Capacity is used by this
418: * method and reportBlockSize, this method either returns a cached
419: * value or calls doReadCapacity to issue the command and cache both
420: * values.
421: * @param maxBlock
422: * Pointer to returned result
423: */
424: virtual IOReturn reportMaxValidBlock(UInt64 *maxBlock);
425:
426: /*!
427: * @function reportMaxWriteTransfer
428: * @abstract
429: * Report the maximum allowed byte transfer for write operations.
430: * @discussion
431: * Some devices impose a maximum data transfer size. Because this limit
432: * may be determined by the size of a block-count field in a command, the limit may
433: * depend on the block size of the transfer.
434: * The default implementation reports blocksize * 65536, which is the maximum
435: * number of bytes that can be transferred
436: * in a SCSI command with a standard 16-bit block count field.
437: * @param blockSize
438: * The block size desired for the transfer.
439: * @param max
440: * Pointer to returned result.
441: */
442: virtual IOReturn reportMaxWriteTransfer(UInt64 blocksize,UInt64 *max);
443:
444: /*!
445: * @function reportPollRequirements
446: * @abstract
447: * Report if it's necessary to poll for media insertion, and if polling is expensive.
448: * @discussion
449: * This method reports whether the device must be polled to detect media
450: * insertion, and whether a poll is expensive to perform.
451: *
452: * The term "expensive" typically implies a device that must be spun-up to detect media,
453: * as on a PC floppy. Most devices can detect media inexpensively.
454: *
455: * The default implementation of this method always reports an
456: * inexpensive poll (pollIsExpensive = false), and that all removable
457: * media must be polled.
458: * @param pollRequired
459: * Pointer to returned result. True indicates that polling is required; False indicates
460: * that polling is not required to detect media.
461: * @param pollIsExpensive
462: * Pointer to returned result. True indicates that the polling operation is expensive;
463: * False indicates that the polling operation is cheap.
464: */
465: virtual IOReturn reportPollRequirements(bool *pollRequired,bool *pollIsExpensive);
466:
467: /*!
468: * @function reportRemovability
469: * @abstract
470: * Report whether the media is removable or not.
471: * @discussion
472: * This method reports whether the media is removable, but it does not
473: * provide detailed information regarding software eject or lock/unlock capability.
474: *
475: * The default implementation of this method examines the cached
476: * Inquiry data to determine if media is removable. If the RMB bit
477: * (0x80 of Inquiry data byte 1) is set, the media is removable. If
478: * there is no Inquiry data, the media is reported to be nonremovable.
479: *
480: * This method also sets the instance variable _removable.
481: * @param isRemovable
482: * Pointer to returned result. True indicates that the media is removable; False
483: * indicates the media is not removable.
484: */
485: virtual IOReturn reportRemovability(bool *isRemovable);
486:
487: /*!
488: * @function reportWriteProtection
489: * @abstract
490: * Report whether the media is write-protected or not.
491: * @discussion
492: * The default implementation of this method issues a SCSI Mode Sense
493: * command to test the WP bit( 0x80 of byte 2 of the Mode Sense Header
494: * data). A request is made for Mode Sense Page 1, though any valid
495: * page will return a header. If the bit is set, the media is considered
496: * write-protected.
497: * @param isWriteProtected
498: * Pointer to returned result. True indicates that the media is write-protected (it
499: * cannot be written); False indicates that the media is not write-protected (it
500: * is permissible to write).
501: */
502: virtual IOReturn reportWriteProtection(bool *isWriteProtected);
503:
504: protected:
505:
506: /*!
507: * @function createReadCdb
508: * @abstract
509: * Create a SCSI CDB for a read operation.
510: * @discussion
511: * Override this to control the cdb created for a read operation.
512: * The default implementation creates a 10-byte read command with
513: * disconnect allowed, 8-byte autosense, and a 2-second timeout.
514: * @param cdb
515: * A pointer to the CDB bytes.
516: * @param cdbLength
517: * The length of the CDB in bytes.
518: * @param block
519: * The device block to be read.
520: * @param nblks
521: * The number of blocks to be transferred.
522: * @param maxAutoSenseLength
523: * The maximum size of the autosense data, in bytes. A value of zero
524: * will disable autosense.
525: * @param timeoutSeconds
526: * The command timeout in seconds.
527: * @result
528: * The IOSCSICommandOptions returned will be used to issue the command.
529: */
530: virtual UInt32 createReadCdb(
531: UInt8 *cdb, /* in */
532: UInt32 *cdbLength, /* out */
533: UInt32 block, /* in */
534: UInt32 nblks, /* in */
535: UInt32 *maxAutoSenseLength, /* out */
536: UInt32 *timeoutSeconds); /* out */
537:
538: /*!
539: * @function createWriteCdb
540: * @abstract
541: * Create a SCSI CDB for a write operation.
542: * @discussion
543: * Override this to control the cdb created for a write operation.
544: * The default implementation creates a 10-byte write command with
545: * disconnect allowed, 8-byte autosense, and a 2-second timeout.
546: * @param cdb
547: * A pointer to the CDB bytes.
548: * @param cdbLength
549: * The length of the CDB in bytes.
550: * @param block
551: * The device block to be written.
552: * @param nblks
553: * The number of blocks to be transferred.
554: * @param maxAutoSenseLength
555: * The maximum size of the autosense data, in bytes. A value of zero
556: * will disable autosense.
557: * @param timeoutSeconds
558: * The command timeout in seconds.
559: * @result
560: * The IOSCSICommandOptions returned will be used to issue the command.
561: */
562: virtual UInt32 createWriteCdb(
563: UInt8 *cdb, /* in */
564: UInt32 *cdbLength, /* out */
565: UInt32 block, /* in */
566: UInt32 nblks, /* in */
567: UInt32 *maxAutoSenseLength, /* out */
568: UInt32 *timeoutSeconds); /* out */
569:
570:
571: /*!
572: * @function doInquiry
573: * @abstract
574: * Obtain SCSI Inquiry data from the device.
575: * @discussion
576: * This method issues a SCSI Inquiry command to the device, to obtain
577: * the result in the supplied buffer. The method first issues an
578: * inquiry with a 5-byte length, to obtain the full length of the
579: * devices inquiry data. The second Inquiry command is issued to get
580: * the full inquiry data (limited to maxLen, of course).
581: * @param inqBuf
582: * A pointer to the buffer.
583: * @param maxLen
584: * The maximum number of bytes the buffer can contain.
585: * @param actualLen
586: * A pointer to the returned byte count actually transferred.
587: */
588: virtual IOReturn doInquiry(UInt8 *inqBuf,UInt32 maxLen,UInt32 *actualLen);
589:
590: /*!
591: * @function handleUnitAttention
592: * @abstract
593: * @discussion
594: * Override this to perform any special processing required when
595: * a Unit-Attention condition is detected. The cx->step value starts at 1 and
596: * is incremented as each subsequent command is executed. HandleUnitAttention
597: * is then called again duirng the command completion, until cx->state is
598: * changed to kDoneHandlingUnitAttention. This repeated calling behavior allows
599: * handleUnitAttention to issue several commands to the device to recover from
600: * the Unit-Attention condition. Note that since handleUnitAttention is called
601: * on the SCSI completion thread, it must not issue blocking operations, but
602: * should instead call simpleAsyncIO.
603: *
604: * The default implementation merely sets the state to
605: * kDoneHandlingUnitAttention, to allow the original command to be
606: * reissued.
607: * @param cx
608: * Pointer to context for the current command.
609: */
610: virtual void handleUnitAttention(struct context *cx);
611:
612: /* Internally used methods. */
613:
614: /*
615: * @group
616: * Internally Used Methods
617: * @discussion
618: * These methods are used internally, and will not generally be modified.
619: */
620:
621: /*!
622: * @function allocateContext
623: * @abstract
624: * Allocate a context structure for use with the current IO operation.
625: */
626: virtual struct context * allocateContext(void);
627:
628: /*!
629: * @function allocateInquiryBuffer
630: * @abstract
631: * Allocate an inquiry buffer.
632: * @param buf
633: * A pointer for the returned buffer pointer.
634: * @param size
635: * The requested size of the buffer, in bytes.
636: */
637: virtual IOReturn allocateInquiryBuffer(UInt8 **buf,UInt32 size);
638:
639: /*!
640: * @function allocateTempBuffer
641: * @abstract
642: * Allocate a buffer for temporary use.
643: * @param buf
644: * A pointer for the returned buffer pointer.
645: * @param size
646: * The requested size of the buffer, in bytes.
647: */
648: virtual IOReturn allocateTempBuffer(UInt8 **buf,UInt32 size);
649:
650: /*!
651: * @function allocateReadCapacityBuffer
652: * @abstract
653: * Allocate a buffer for Read-Capacity data.
654: * @param buf
655: * A pointer for the returned buffer pointer.
656: * @param size
657: * The requested size of the buffer, in bytes.
658: */
659: virtual IOReturn allocateReadCapacityBuffer(UInt8 **buf,UInt8 size);
660:
661: /*!
662: * @function deleteContext
663: * @abstract
664: * Delete a context structure.
665: * @discussion
666: * This method also issues a "release" for the IO buffer and/or lock, if any.
667: * @param cx
668: * A pointer to the context structure to be deleted.
669: */
670: virtual void deleteContext(struct context *cx);
671:
672: /*!
673: * @function deleteInquiryBuffer
674: * @abstract
675: * Delete an inquiry data buffer.
676: * @param buf
677: * A pointer to the buffer.
678: * @param size
679: * The requested size of the buffer, in bytes.
680: */
681: virtual void deleteInquiryBuffer(UInt8 *buf,UInt32 size);
682:
683: /*!
684: * @function deleteTempBuffer
685: * @abstract
686: * Delete a temporary data buffer.
687: * @param buf
688: * A pointer to the buffer.
689: * @param len
690: * The requested size of the buffer, in bytes.
691: */
692: virtual void deleteTempBuffer(UInt8 *buf,UInt32 len);
693:
694: /*!
695: * @function deleteReadCapacityBuffer
696: * @abstract
697: * Delete a Read-Capacity data buffer.
698: * @param buf
699: * A pointer to the buffer.
700: * @param len
701: * The requested size of the buffer, in bytes.
702: */
703: virtual void deleteReadCapacityBuffer(UInt8 *buf,UInt32 len);
704:
705: /*!
706: * @function doReadCapacity
707: * @abstract
708: * @discussion
709: * The default implementation of this method issues a standard SCSI
710: * Read Capacity command. The block size and maximum valid block are
711: * extracted from the returned data in an endian-neutral way.
712: * @param blockSize
713: * A pointer to the returned block size value.
714: * @param maxBlock
715: * A pointer to the returned maximum block number.
716: */
717: virtual IOReturn doReadCapacity(UInt64 *blockSize,UInt64 *maxBlock);
718:
719: /*!
720: * @function getBlockSize
721: * @abstract
722: * Return the device block size.
723: * @discussion
724: * This method obtains the block size from the Read-Capacity data. If RC data is
725: * not yet cached, a call is made to doReadCapacity to obtain the data.
726: */
727: virtual UInt64 getBlockSize(void);
728:
729:
730: /*!
731: * @function dequeueCommands
732: * @abstract
733: * Dequeue commands previously enqueued awaiting the proper device power level.
734: * @discussion
735: * This method is called when a command is queued (from queueCommand), when a call
736: * completes (from RWCompletion), and when the device power level changes. All commands
737: * for which the device power level is proper are immediately dequeued.
738: *
739: * Queued synchronous commands are simply "awakened" by unlocking a lock. The originating
740: * thread then continues and issues the command. Asynchronous commands are immediately
741: * dispatched via a call to standardAsyncReadWriteExecute.
742: */
743: virtual void dequeueCommands(void);
744:
745: /*!
746: * @function queueCommand
747: * @abstract
748: * Queue commands awaiting the proper device power level.
749: * @discussion
750: * This method is called prior to issuing any IO command, so that each command can
751: * be enqueued awaiting its desired device power level. After queuing the command, a
752: * call is made to dequeueCommands to attempt to dequeue any available command that can
753: * be executed (including the one just queued). Putting commands into the queue ensures
754: * that the proper sequence is maintained.
755: * @param cx
756: * The context for the command being queued.
757: * @param isSync
758: * True if the command is synchronous; False if the command is asynchronous.
759: * @param desiredPower
760: * The device power level needed before the command can execute.
761: */
762: virtual void queueCommand(struct context *cx,bool isSync,UInt32 desiredPower);
763:
764: /*!
765: * @function RWCompletion
766: * @abstract
767: * Asynchronous read/write completion routine.
768: * @discussion
769: * A subclass must implement the read-write completion, called upon completion
770: * of an IO started by doAsyncReadWrite.
771: * @param cx
772: * A pointer to the context structure for the completing command.
773: */
774: virtual void RWCompletion(struct context *cx) = 0;
775:
776: /*!
777: * @function simpleSynchIO
778: * @abstract
779: * Issue a simple synchronous SCSI command.
780: * @discussion
781: * This method issues a single SCSI command and waits for the command
782: * to complete. The SCSI command must already be set up in the context
783: * structure.
784: * @param cx
785: * A pointer to the context structure for the command.
786: */
787: virtual IOReturn simpleSynchIO(struct context *cx);
788:
789: /*!
790: * @function standardAsyncReadWrite
791: * @abstract
792: * Start an asynchronous read or write operation.
793: * @discussion
794: * This method starts an asynchronous read or write operation. No
795: * incoming parameters are validated. The default implementation
796: * calls createReadCdb or createWriteCdb,
797: * then issues a SCSI command to IOSCSIDevice. If the command is
798: * accepted, then the completion will be called at some future time.
799: * @result
800: * The only possible returns from this method are:
801: *
802: * kIOReturnSuccess, meaning that the IO was accepted by the transport
803: * drivers provider (e.g. IOSCSIDevice), and that the completion
804: * function will be called when the IO completes, i.e. target->action(param).
805: *
806: * kIOReturnNoMemory, meaning that memory allocation failed.
807: *
808: * Other kIOReturn codes from the provider which occurred
809: * because the IO was not accepted in that provider's queue. This
810: * might indicate a full queue or bad parameter.
811: * @param buffer
812: * An IOMemoryDescriptor describing the data-transfer buffer. The data direction
813: * is contained in the IOMemoryDescriptor. Responsiblity for releasing the descriptor
814: * rests with the caller.
815: * @param block
816: * The starting block number of the data transfer.
817: * @param nblks
818: * The integral number of blocks to be transferred.
819: * @param action
820: * The C function called upon completion of the data transfer.
821: * @param target
822: * The C++ class "this" pointer, passed as an argument to "action."
823: * @param param
824: * This value is passed as an argument to "action." It is not validated or modified.
825: */
826: virtual IOReturn standardAsyncReadWrite(IOMemoryDescriptor *buffer,
827: UInt32 block,UInt32 nblks,
828: gdCompletionFunction action,
829: IOService *target,void *param);
830:
831: /*!
832: * @function standardAsyncReadWriteExecute
833: * @abstract
834: * Issue an asynchronous read/write operation after dequeuing.
835: * @param cx
836: * A pointer to the context structure for the command.
837: */
838: virtual IOReturn standardAsyncReadWriteExecute(struct context *cx);
839:
840: /*!
841: * @function standardSyncReadWrite
842: * Perform a synchronous read or write operation.
843: * @param buffer
844: * An IOMemoryDescriptor describing the data-transfer buffer. The data direction
845: * is contained in the IOMemoryDescriptor. Responsiblity for releasing the descriptor
846: * rests with the caller.
847: * @param block
848: * The starting block number of the data transfer.
849: * @param nblks
850: * The integral number of blocks to be transferred.
851: */
852: virtual IOReturn standardSyncReadWrite(IOMemoryDescriptor *buffer,UInt32 block,UInt32 nblks);
853:
854: /*!
855: * @function stringFromState
856: * @abstract
857: * Return a string description of a state value.
858: * @discussion
859: * Used for debugging.
860: * @param state
861: * The state to be converted to a string description.
862: */
863: virtual char * stringFromState(stateValue state);
864:
865: public:
866:
867: /*!
868: * @function genericCompletion
869: * @abstract
870: * Generic IO completion function.
871: * @discussion
872: * This method handles completion of a SCSI command. It implements a
873: * simple state machine to handle a Unit Attention condition on a
874: * command.
875: *
876: * This method must be public so we can reach it from
877: * the C-language callback "glue" routine. It should not be called
878: * from outside this class.
879: *
880: *
881: *
882: * If a Unit Attention condition occurs, we set the state to
883: * kHandlingUnitAttention and call handleUnitAttention to do whatever
884: * is necessary to clear the condition. Eventually, handleUnitAttention
885: * resets the state to kDoneHandlingUnitAttention, which will allow
886: * the state machine to reissue the original command.
887: *
888: * If we are already processing a Unit Attention, then genericCompletion
889: * increments a step counter and calls handleUnitAttention. The step
890: * counter allows handleUnitAttention to issue multiple SCSI commands
891: * to clear the condition. The handleUnitAttention method is called
892: * repeatedly, until the state is set to kDoneHandlingUnitAttention.
893: *
894: * If this operation is a normal asynchronous read or write (usually
895: * started by standardAsyncReadWrite, though this is not required),
896: * then a call is made to RWCompletion, followed by deletion of the
897: * context structure for the command. RWCompletion is implemented by
898: * the subclass of IOBasicSCSI, for example in IOSCSIHDDrive.
899: * @param cx
900: * A pointer to the context structure for the command.
901: */
902: virtual void genericCompletion(struct context *cx);
903:
904: /*
905: * @endgroup
906: */
907:
908: protected:
909:
910: /*
911: * @group
912: * Power Management Methods
913: * @discussion
914: * A subclass must implement these to report the power level required to do various commands.
915: */
916:
917: /*!
918: * @function getExecuteCDBPowerState
919: * @abstract
920: * Return the required device power level to execute a client CDB.
921: */
922: virtual UInt32 getExecuteCDBPowerState(void) = 0;
923:
924: /*!
925: * @function getInquiryPowerState
926: * @abstract
927: * Return the required device power level to issue an Inquiry command.
928: */
929: virtual UInt32 getInquiryPowerState(void) = 0;
930:
931: /*!
932: * @function getReadCapacityPowerState
933: * @abstract
934: * Return the required device power level to issue a Read Capacity command.
935: */
936: virtual UInt32 getReadCapacityPowerState(void) = 0;
937:
938: /*!
939: * @function getReadWritePowerState
940: * @abstract
941: * Return the required device power level to issue a data read or write.
942: */
943: virtual UInt32 getReadWritePowerState(void) = 0;
944:
945: /*!
946: * @function getReportWriteProtectionPowerState
947: * @abstract
948: * Return the required device power level to determine media write protection.
949: */
950: virtual UInt32 getReportWriteProtectionPowerState(void) = 0;
951:
952: /*!
953: * @function powerTickle
954: * @abstract
955: * Check for the device power state currently being in the desired state.
956: * @discussion
957: * A subclass must implement powerTickle, which is called when we desire power to
958: * execute a command. PowerTickle may handle generic or a subclass-expanded set of
959: * power states. The implementation will usually relay the call to the Power Management
960: * subsystem function activityTickle. For a device without power management capability,
961: * the implementation should always return True.
962: * @param desiredState
963: * The desired device power level.
964: * @result
965: * True if power is in the desired state (or better); False if the caller must wait
966: * until power is available.
967: */
968: virtual bool powerTickle(UInt32 desiredState) = 0;
969:
970: /*
971: * @endgroup
972: */
973:
974: /*!
975: * @var _provider
976: * A pointer to our provider.
977: */
978: IOSCSIDevice * _provider;
979:
980: /* Device information : */
981:
982: /*!
983: * @var _inqBuf
984: * A pointer to the allocate Inquiry Data buffer.
985: */
986: UInt8 * _inqBuf; /* the Inquiry data buffer */
987:
988: /*!
989: * @var _inqBufSize
990: * The size of the inquiry data buffer, in bytes.
991: */
992: UInt32 _inqBufSize; /* size of the buffer */
993:
994: /*!
995: * @var _inqLen
996: * The number of valid bytes of inquiry data.
997: */
998: UInt32 _inqLen; /* valid bytes in buffer */
999:
1000: /*!
1001: * @var _vendor
1002: * The Vendor Name string from the inquiry data, null-terminated.
1003: */
1004: char _vendor[9]; /* info from Inquiry data */
1005:
1006: /*!
1007: * @var _product
1008: * The Product Name string from the inquiry data, null-terminated.
1009: */
1010: char _product[17];
1011:
1012: /*!
1013: * @var _rev
1014: * The Product Revision string from the inquiry data, null-terminated.
1015: */
1016: char _rev[5];
1017:
1018: /* Since we get both of these items from the same command, we
1019: * just cache both values if we get either call, so we only
1020: * have to issue the command once.
1021: */
1022:
1023: /*!
1024: * @var _readCapDone
1025: * True if we have issued a Read-Capacity command to obtain the
1026: * values for _maxBlock and _blockSize.
1027: */
1028: bool _readCapDone;
1029:
1030: /*!
1031: * @var _removable
1032: * True if the media is removable; False if the media is fixed.
1033: */
1034: bool _removable;
1035:
1036: /*!
1037: * @var _maxBlock
1038: * The highest valid block on the media, relative to zero.
1039: */
1040: UInt64 _maxBlock;
1041:
1042: /*!
1043: * @var _blockSize
1044: * The block size of the media in bytes.
1045: */
1046: UInt64 _blockSize;
1047:
1048: /* The queue of pending requests awaiting power: */
1049:
1050: /*!
1051: * @struct queue
1052: * @discussion
1053: * A data structure for a queue.
1054: * @field head
1055: * A pointer to the head item.
1056: * @field tail
1057: * A pointer to the tail item.
1058: * @field lock
1059: * A lock used to protect the queue during changes.
1060: */
1061: /*!
1062: * @var _powerQueue
1063: * A queue structure containing operations queued awaiting power level.
1064: */
1065: struct queue {
1066: struct context * head;
1067: struct context * tail;
1068: IOLock * lock;
1069: } _powerQueue;
1070:
1071: };
1072: #endif
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.