![[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.