Chameleon Applications

Chameleon Applications Svn Source Tree

Root/branches/iFabio/Chameleon/i386/include/IOKit/storage/IOBlockStorageDevice.h

Source at commit 296 created 12 years 10 months ago.
By ifabio, add i386 folder
1/*
2 * Copyright (c) 1998-2009 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 IOBlockStorageDevice
26 * @abstract
27 * This header contains the IOBlockStorageDevice class definition.
28 */
29
30#ifndef _IOBLOCKSTORAGEDEVICE_H
31#define _IOBLOCKSTORAGEDEVICE_H
32
33#include <IOKit/IOTypes.h>
34#include <IOKit/storage/IOStorageDeviceCharacteristics.h>
35
36/*!
37 * @defined kIOBlockStorageDeviceClass
38 * @abstract
39 * The name of the IOBlockStorageDevice class.
40 */
41
42#define kIOBlockStorageDeviceClass "IOBlockStorageDevice"
43
44/*!
45 * @defined kIOBlockStorageDeviceWriteCacheStateKey
46 * @abstract
47 * The name of the property used to get or set the write cache state of the
48 * block storage device.
49 */
50#define kIOBlockStorageDeviceWriteCacheStateKey"WriteCacheState"
51
52#ifdef KERNEL
53#ifdef __cplusplus
54
55/*
56 * Kernel
57 */
58
59#include <IOKit/IOMemoryDescriptor.h>
60#include <IOKit/IOMessage.h>
61#include <IOKit/IOService.h>
62#include <IOKit/storage/IOMedia.h>
63
64/*!
65 * @defined kIOMessageMediaParametersHaveChanged
66 * @abstract
67 * The message ID which indicates that the media parameters, such as the highest valid block
68 * for the device, have changed.
69 * @discussion
70 * The message is passed to all clients of the IOBlockStorageDevice via the message() method.
71 */
72#define kIOMessageMediaParametersHaveChanged iokit_family_msg(sub_iokit_block_storage, 2)
73
74/*!
75 * @defined kIOMessageMediaStateHasChanged
76 * @abstract
77 * The message ID which indicates that the media state has changed.
78 * @discussion
79 * The message is passed to all clients of the IOBlockStorageDevice via the message() method.
80 * The argument that is passed along with this message is an IOMediaState value.
81 *
82 * Devices that aren't capable of detecting media state changes indicate this in
83 * the reportPollRequirements() method.
84 */
85#define kIOMessageMediaStateHasChanged iokit_family_msg(sub_iokit_block_storage, 1)
86
87/* Property used for matching, so the generic driver gets the nub it wants. */
88/*!
89 * @defined kIOBlockStorageDeviceTypeKey
90 * @abstract The name of the property tested for nub type matching by the generic block
91 * storage driver.
92 */
93#definekIOBlockStorageDeviceTypeKey"device-type"
94/*!
95 * @defined kIOBlockStorageDeviceTypeGeneric
96 * @abstract A character string used for nub matching.
97 */
98#definekIOBlockStorageDeviceTypeGeneric"Generic"
99
100/*!
101 * @class
102 * IOBlockStorageDevice
103 * @abstract
104 * A generic block storage device abstraction.
105 * @discussion
106 * The IOBlockStorageDevice class exports the generic block storage protocol,
107 * independent of the physical connection protocol (e.g. SCSI, ATA, USB),
108 * forwarding all requests to its provider (the Transport Driver).
109 * Though the nub does no actual processing of requests, it is necessary
110 * in a C++ environment. The Transport Driver can be of any type, as
111 * long as it inherits from IOService. Because Transport Drivers needn't
112 * derive from a type known to IOBlockStorageDriver, it isn't possible for
113 * IOBlockStorageDriver to include the appropriate header file to allow direct
114 * communication with the Transport Driver. Thus we achieve polymorphism by
115 * having the Transport Driver instantiate a subclass of IOBlockStorageDevice.
116 * A typical implementation for a concrete subclass of IOBlockStorageDevice
117 * simply relays all methods to its provider (the Transport Driver), which
118 * implements the protocol- and device-specific behavior.
119 *
120 * All pure-virtual functions must be implemented by the Transport Driver, which
121 * is responsible for instantiating the Nub.
122 */
123
124class IOBlockStorageDevice : public IOService {
125
126 OSDeclareAbstractStructors(IOBlockStorageDevice)
127
128protected:
129
130 struct ExpansionData { /* */ };
131 ExpansionData * _expansionData;
132
133public:
134
135 /* Overrides from IORegistryEntry */
136
137 using IORegistryEntry::getProperty;
138
139 /*!
140 * @function init
141 * @discussion
142 * This function is overridden so that IOBlockStorageDevice can set a
143 * property, used by IOBlockStorageDriver for matching. Since the concrete
144 * subclass of IOBlockStorageDevice can be of any class type, the property
145 * is used for matching.
146 *
147 * This function is usually not overridden by developers.
148 */
149 virtual boolinit(OSDictionary * properties);
150
151 virtual OSObject *getProperty(const OSSymbol * key) const;
152
153 virtual IOReturnsetProperties(OSObject * properties);
154
155 /* --- A subclass must implement the the following methods: --- */
156
157#ifndef __LP64__
158 virtual IOReturndoAsyncReadWrite(IOMemoryDescriptor *buffer,
159 UInt32 block, UInt32 nblks,
160 IOStorageCompletion completion) __attribute__ ((deprecated));
161
162 virtual IOReturndoSyncReadWrite(IOMemoryDescriptor *buffer,
163 UInt32 block,UInt32 nblks) __attribute__ ((deprecated));
164#endif /* !__LP64__ */
165
166 /*!
167 * @function doEjectMedia
168 * @abstract
169 * Eject the media.
170 */
171 virtual IOReturndoEjectMedia(void)= 0;
172
173 /*!
174 * @function doFormatMedia
175 * @abstract
176 * Format the media to the specified byte capacity.
177 * @discussion
178 * The specified byte capacity must be one supported by the device.
179 * Supported capacities can be obtained by calling doGetFormatCapacities.
180 * @param byteCapacity
181 * The byte capacity to which the device is to be formatted, if possible.
182 */
183 virtual IOReturndoFormatMedia(UInt64 byteCapacity)= 0;
184
185 /*!
186 * @function doGetFormatCapacities
187 * @abstract
188 * Return the allowable formatting byte capacities.
189 * @discussion
190 * This function returns the supported byte capacities for the device.
191 * @param capacities
192 * Pointer for returning the list of capacities.
193 * @param capacitiesMaxCount
194 * The number of capacity values returned in "capacities," or if no buffer
195 * is given, the total number of capacity values available.
196 */
197 virtual UInt32doGetFormatCapacities(UInt64 * capacities,
198 UInt32 capacitiesMaxCount) const= 0;
199
200 /*!
201 * @function doLockUnlockMedia
202 * @abstract
203 * Lock or unlock the (removable) media in the drive.
204 * @discussion
205 * This method should only be called if the media is known to be removable.
206 * @param doLock
207 * True to lock the media, False to unlock.
208 */
209 virtual IOReturndoLockUnlockMedia(bool doLock)= 0;
210
211 /*!
212 * @function doSynchronizeCache
213 * @abstract
214 * Force data blocks in the hardware's buffer to be flushed to the media.
215 * @discussion
216 * This method should only be called if the media is writable.
217 */
218 virtual IOReturndoSynchronizeCache(void)= 0;
219
220 /*!
221 * @function getVendorString
222 * @abstract
223 * Return Vendor Name string for the device.
224 * @result
225 * A pointer to a static character string.
226 */
227 virtual char *getVendorString(void)= 0;
228
229 /*!
230 * @function getProductString
231 * @abstract
232 * Return Product Name string for the device.
233 * @result
234 * A pointer to a static character string.
235 */
236 virtual char *getProductString(void)= 0;
237
238 /*!
239 * @function getRevisionString
240 * @abstract
241 * Return Product Revision string for the device.
242 * @result
243 * A pointer to a static character string.
244 */
245 virtual char *getRevisionString(void)= 0;
246
247 /*!
248 * @function getAdditionalDeviceInfoString
249 * @abstract
250 * Return additional informational string for the device.
251 * @result
252 * A pointer to a static character string.
253 */
254 virtual char *getAdditionalDeviceInfoString(void)= 0;
255
256 /*!
257 * @function reportBlockSize
258 * @abstract
259 * Report the block size for the device, in bytes.
260 * @param blockSize
261 * Pointer to returned block size value.
262 */
263 virtual IOReturnreportBlockSize(UInt64 *blockSize)= 0;
264
265 /*!
266 * @function reportEjectability
267 * @abstract
268 * Report if the media is ejectable under software control.
269 * @discussion
270 * This method should only be called if the media is known to be removable.
271 * @param isEjectable
272 * Pointer to returned result. True indicates the media is ejectable, False indicates
273 * the media cannot be ejected under software control.
274 */
275 virtual IOReturnreportEjectability(bool *isEjectable)= 0;
276
277 /*!
278 * @function reportLockability
279 * @abstract
280 * Report if the media is lockable under software control.
281 * @discussion
282 * This method should only be called if the media is known to be removable.
283 * @param isLockable
284 * Pointer to returned result. True indicates the media can be locked in place; False
285 * indicates the media cannot be locked by software.
286 */
287 virtual IOReturnreportLockability(bool *isLockable)= 0;
288
289#ifndef __LP64__
290 virtual IOReturnreportMaxReadTransfer(UInt64 blockSize,UInt64 *max) __attribute__ ((deprecated));
291
292 virtual IOReturnreportMaxWriteTransfer(UInt64 blockSize,UInt64 *max) __attribute__ ((deprecated));
293#endif /* !__LP64__ */
294
295 /*!
296 * @function reportMaxValidBlock
297 * @abstract
298 * Report the highest valid block for the device.
299 * @param maxBlock
300 * Pointer to returned result
301 */
302 virtual IOReturnreportMaxValidBlock(UInt64 *maxBlock)= 0;
303
304 /*!
305 * @function reportMediaState
306 * @abstract
307 * Report the device's media state.
308 * @discussion
309 * This method reports whether we have media in the drive or not, and
310 * whether the state has changed from the previously reported state.
311 *
312 * A result of kIOReturnSuccess is always returned if the test for media is successful,
313 * regardless of media presence. The mediaPresent result should be used to determine
314 * whether media is present or not. A return other than kIOReturnSuccess indicates that
315 * the Transport Driver was unable to interrogate the device. In this error case, the
316 * outputs mediaState and changedState will *not* be stored.
317 * @param mediaPresent Pointer to returned media state. True indicates media is present
318 * in the device; False indicates no media is present.
319 * @param changedState Pointer to returned result. True indicates a change of state since
320 * prior calls, False indicates that the state has not changed.
321 */
322 virtual IOReturnreportMediaState(bool *mediaPresent,bool *changedState)= 0;
323
324 /*!
325 * @function reportPollRequirements
326 * @abstract
327 * Report if it's necessary to poll for media insertion, and if polling is expensive.
328 * @discussion
329 * This method reports whether the device must be polled to detect media
330 * insertion, and whether a poll is expensive to perform.
331 *
332 * The term "expensive" typically implies a device that must be spun-up to detect media,
333 * as on a PC floppy. Most devices can detect media inexpensively.
334 * @param pollRequired
335 * Pointer to returned result. True indicates that polling is required; False indicates
336 * that polling is not required to detect media.
337 * @param pollIsExpensive
338 * Pointer to returned result. True indicates that the polling operation is expensive;
339 * False indicates that the polling operation is cheap.
340 */
341 virtual IOReturnreportPollRequirements(bool *pollRequired,
342 bool *pollIsExpensive)= 0;
343
344 /*!
345 * @function reportRemovability
346 * @abstract
347 * Report whether the media is removable or not.
348 * @discussion
349 * This method reports whether the media is removable, but it does not
350 * provide detailed information regarding software eject or lock/unlock capability.
351 * @param isRemovable
352 * Pointer to returned result. True indicates that the media is removable; False
353 * indicates the media is not removable.
354 */
355 virtual IOReturnreportRemovability(bool *isRemovable) = 0;
356
357 /*!
358 * @function reportWriteProtection
359 * @abstract
360 * Report whether the media is write-protected or not.
361 * @param isWriteProtected
362 * Pointer to returned result. True indicates that the media is write-protected (it
363 * cannot be written); False indicates that the media is not write-protected (it
364 * is permissible to write).
365 */
366 virtual IOReturnreportWriteProtection(bool *isWriteProtected)= 0;
367
368#ifndef __LP64__
369 virtual IOReturndoAsyncReadWrite(IOMemoryDescriptor *buffer,
370 UInt64 block, UInt64 nblks,
371 IOStorageCompletion completion) __attribute__ ((deprecated));
372#endif /* !__LP64__ */
373
374 /*!
375 * @function getWriteCacheState
376 * @abstract
377 * Reports the current write cache state of the device.
378 * @discussion
379 * Reports the current write cache state of the device. The write cache
380 * state is not guaranteed to persist across reboots and detaches.
381 * @param enabled
382 * Pointer to returned result. True indicates the write cache is enabled;
383 * False indicates the write cache is disabled.
384 */
385#ifdef __LP64__
386 virtual IOReturngetWriteCacheState(bool *enabled)= 0;
387#else /* !__LP64__ */
388 virtual IOReturngetWriteCacheState(bool *enabled); /* 10.3.0 */
389#endif /* !__LP64__ */
390
391 /*!
392 * @function setWriteCacheState
393 * @abstract
394 * Sets the write cache state of the device.
395 * @discussion
396 * Sets the write cache state of the device. The write cache state
397 * is not guaranteed to persist across reboots and detaches.
398 * @param enabled
399 * True to enable the write cache; False to disable the write cache.
400 */
401#ifdef __LP64__
402 virtual IOReturnsetWriteCacheState(bool enabled)= 0;
403#else /* !__LP64__ */
404 virtual IOReturnsetWriteCacheState(bool enabled); /* 10.3.0 */
405#endif /* !__LP64__ */
406
407 /*!
408 * @function doAsyncReadWrite
409 * @abstract
410 * Start an asynchronous read or write operation.
411 * @param buffer
412 * An IOMemoryDescriptor describing the data-transfer buffer. The data direction
413 * is contained in the IOMemoryDescriptor. Responsibility for releasing the descriptor
414 * rests with the caller.
415 * @param block
416 * The starting block number of the data transfer.
417 * @param nblks
418 * The integral number of blocks to be transferred.
419 * @param attributes
420 * Attributes of the data transfer. See IOStorageAttributes.
421 * @param completion
422 * The completion routine to call once the data transfer is complete.
423 */
424#ifdef __LP64__
425 virtual IOReturndoAsyncReadWrite(IOMemoryDescriptor *buffer,
426 UInt64 block, UInt64 nblks,
427 IOStorageAttributes *attributes,
428 IOStorageCompletion *completion)= 0;
429#else /* !__LP64__ */
430 virtual IOReturndoAsyncReadWrite(IOMemoryDescriptor *buffer,
431 UInt64 block, UInt64 nblks,
432 IOStorageAttributes *attributes,
433 IOStorageCompletion *completion); /* 10.5.0 */
434#endif /* !__LP64__ */
435
436 /*!
437 * @function requestIdle
438 * @abstract
439 * Request that the device enter an idle state.
440 * @discussion
441 * Request that the device enter an idle state. The device will exit this state on the
442 * next read or write request, or as it sees necessary. One example is for a DVD drive
443 * to spin down when it enters such an idle state, and spin up on the next read request
444 * from the system.
445 */
446 virtual IOReturnrequestIdle(void); /* 10.6.0 */
447
448 /*!
449 * @function doDiscard
450 * @abstract
451 * Delete unused data blocks from the media.
452 * @param block
453 * The starting block number of the operation.
454 * @param nblks
455 * The integral number of blocks to be deleted.
456 */
457 virtual IOReturn doDiscard(UInt64 block, UInt64 nblks); /* 10.6.0 */
458
459#ifdef __LP64__
460 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 0);
461 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 1);
462 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 2);
463 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 3);
464 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 4);
465 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 5);
466#else /* !__LP64__ */
467 OSMetaClassDeclareReservedUsed(IOBlockStorageDevice, 0);
468 OSMetaClassDeclareReservedUsed(IOBlockStorageDevice, 1);
469 OSMetaClassDeclareReservedUsed(IOBlockStorageDevice, 2);
470 OSMetaClassDeclareReservedUsed(IOBlockStorageDevice, 3);
471 OSMetaClassDeclareReservedUsed(IOBlockStorageDevice, 4);
472 OSMetaClassDeclareReservedUsed(IOBlockStorageDevice, 5);
473#endif /* !__LP64__ */
474 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 6);
475 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 7);
476 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 8);
477 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 9);
478 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 10);
479 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 11);
480 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 12);
481 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 13);
482 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 14);
483 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 15);
484 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 16);
485 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 17);
486 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 18);
487 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 19);
488 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 20);
489 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 21);
490 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 22);
491 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 23);
492 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 24);
493 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 25);
494 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 26);
495 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 27);
496 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 28);
497 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 29);
498 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 30);
499 OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 31);
500};
501
502#endif /* __cplusplus */
503#endif /* KERNEL */
504#endif /* !_IOBLOCKSTORAGEDEVICE_H */
505

Archive Download this file

Revision: 296