![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IOMedia.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 IOMedia.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: /*!
24: * @header IOMedia
25: * @abstract
26: * This header contains the IOMedia class definition.
27: */
28:
29: #ifndef _IOMEDIA_H
30: #define _IOMEDIA_H
31:
32: /*!
33: * @defined kIOMediaContent
34: * @abstract
35: * kIOMediaContent is a property of IOMedia objects. It is an OSString.
36: * @discussion
37: * The kIOMediaContent property contains a description of the media's contents.
38: * The description is the same as the hint at the time of the object's creation,
39: * but it is possible that the description be overrided by a client (which has
40: * probed the media and identified the content correctly) of the media object.
41: * It is more accurate than the hint for this reason. The string is formed in
42: * the likeness of Apple's "Apple_HFS" strings.
43: */
44:
45: #define kIOMediaContent "Content"
46:
47: /*!
48: * @defined kIOMediaContentHint
49: * @abstract
50: * kIOMediaContentHint is a property of IOMedia objects. It is an OSString.
51: * @discussion
52: * The kIOMediaContentHint property contains a hint of the media's contents.
53: * The hint is set at the time of the object's creation, should the creator have
54: * a clue as to what it may contain. The hint string does not change for the
55: * lifetime of the object and is formed in the likeness of Apple's "Apple_HFS"
56: * strings.
57: */
58:
59: #define kIOMediaContentHint "Content Hint"
60:
61: /*!
62: * @defined kIOMediaEjectable
63: * @abstract
64: * kIOMediaEjectable is a property of IOMedia objects. It is an OSBoolean.
65: * @discussion
66: * The kIOMediaEjectable property describes whether the media is ejectable.
67: */
68:
69: #define kIOMediaEjectable "Ejectable"
70:
71: /*!
72: * @defined kIOMediaLeaf
73: * @abstract
74: * kIOMediaLeaf is a property of IOMedia objects. It is an OSBoolean.
75: * @discussion
76: * The kIOMediaLeaf property describes whether the media is a leaf, that is, it
77: * is the deepest media object in this branch of the I/O Kit registry.
78: */
79:
80: #define kIOMediaLeaf "Leaf"
81:
82: /*!
83: * @defined kIOMediaSize
84: * @abstract
85: * kIOMediaSize is a property of IOMedia objects. It is an OSNumber.
86: * @discussion
87: * The kIOMediaSize property describes the total length of the media in bytes.
88: */
89:
90: #define kIOMediaSize "Size"
91:
92: /*!
93: * @defined kIOMediaWhole
94: * @abstract
95: * kIOMediaWhole is a property of IOMedia objects. Is it an OSBoolean.
96: * @discussion
97: * The kIOMediaWhole property describes whether the media is whole, that is, it
98: * represents the whole disk (the physical disk, or a virtual replica thereof).
99: */
100:
101: #define kIOMediaWhole "Whole"
102:
103: /*!
104: * @defined kIOMediaWritable
105: * @abstract
106: * kIOMediaWritable is a property of IOMedia objects. It is an OSBoolean.
107: * @discussion
108: * The kIOMediaWritable property describes whether the media is writable.
109: */
110:
111: #define kIOMediaWritable "Writable"
112:
113: /*!
114: * @defined kIOMediaContentMask
115: * @abstract
116: * kIOMediaContentMask is a property of IOMedia clients. It is an OSString.
117: * @discussion
118: * The kIOMediaContentMask property must exist in all IOMedia clients that drive
119: * new content (that is, produce new media objects). When the client matches on
120: * the provider media, the value of the client's kIOMediaContentMask property is
121: * used to replace the provider's kIOMediaContent property.
122: */
123:
124: #define kIOMediaContentMask "Content Mask"
125:
126: /*
127: * Kernel
128: */
129:
130: #if defined(KERNEL) && defined(__cplusplus)
131:
132: #include <IOKit/storage/IOStorage.h>
133:
134: /*!
135: * @class IOMedia
136: * @abstract
137: * The IOMedia class is a random-access disk device abstraction.
138: * @discussion
139: * The IOMedia class is a random-access disk device abstraction. It provides a
140: * consistent interface for both real and virtual disk devices, for subdivisions
141: * of disks such as partitions, for supersets of disks such as RAID volumes, and
142: * so on. It extends the IOStorage class by implementing the appropriate open,
143: * close, read, write, and matching semantics for media objects. The properties
144: * it has reflect the properties of real disk devices, such as ejectability and
145: * writability.
146: *
147: * The read and write interfaces support byte-level access to the storage space,
148: * with the appropriate deblocking handled by IODrive, however, a typical client
149: * will want to obtain the natural block size in order to optimize access to the
150: * real disk device. A read or write is accepted so long as the client's access
151: * is valid, the media is formatted and the transfer is within the bounds of the
152: * media. An optional non-zero base (offset) is then applied before the read or
153: * write is passed to provider object.
154: *
155: * An open is accepted so long as no more than one writer is active at any time.
156: */
157:
158: class IOMedia : public IOStorage
159: {
160: OSDeclareDefaultStructors(IOMedia)
161:
162: protected:
163: bool _isEjectable;
164: bool _isWhole;
165: bool _isWritable;
166:
167: UInt64 _mediaBase; /* (relative to the storage object below us) */
168: UInt64 _mediaSize;
169:
170: IOStorageAccess _openLevel;
171: OSSet * _openReaders;
172: IOService * _openReaderWriter;
173:
174: UInt64 _preferredBlockSize;
175:
176: /*
177: * Free all of this object's outstanding resources.
178: */
179:
180: virtual void free();
181:
182: /*!
183: * @function handleOpen
184: * @discussion
185: * The handleOpen method grants or denies permission to access this object
186: * to an interested client. The argument is an IOStorageAccess value that
187: * specifies the level of access desired -- reader or reader-writer.
188: *
189: * This method can be invoked to upgrade or downgrade the access level for
190: * an existing client as well. The previous access level will prevail for
191: * upgrades that fail, of course. A downgrade should never fail. If the
192: * new access level should be the same as the old for a given client, this
193: * method will do nothing and return success. In all cases, one, singular
194: * close-per-client is expected for all opens-per-client received.
195: *
196: * This implementation replaces the IOService definition of handleOpen().
197: * @param client
198: * Client requesting the open.
199: * @param options
200: * Options for the open. Set to zero.
201: * @param access
202: * Access level for the open. Set to kAccessReader or kAccessReaderWriter.
203: * @result
204: * Returns true if the open was successful, false otherwise.
205: */
206:
207: virtual bool handleOpen(IOService * client,
208: IOOptionBits options,
209: void * access);
210:
211: /*!
212: * @function handleIsOpen
213: * @discussion
214: * The handleIsOpen method determines whether the specified client, or any
215: * client if none is specificed, presently has an open on this object.
216: *
217: * This implementation replaces the IOService definition of handleIsOpen().
218: * @param client
219: * Client to check the open state of. Set to zero to check the open state
220: * of all clients.
221: * @result
222: * Returns true if the client was (or clients were) open, false otherwise.
223: */
224:
225: virtual bool handleIsOpen(const IOService * client) const;
226:
227: /*!
228: * @function handleClose
229: * @discussion
230: * The handleClose method closes the client's access to this object.
231: *
232: * This implementation replaces the IOService definition of handleClose().
233: * @param client
234: * Client requesting the close.
235: * @param options
236: * Options for the close. Set to zero.
237: */
238:
239: virtual void handleClose(IOService * client, IOOptionBits options);
240:
241: public:
242:
243: ///m:2333367:workaround:commented:start
244: // IOStorage::open;
245: // IOStorage::close;
246: // IOStorage::read;
247: // IOStorage::write;
248: ///m:2333367:workaround:commented:stop
249:
250: ///m:2333367:workaround:added:start
251: inline bool open(IOService * client,
252: IOOptionBits options,
253: IOStorageAccess access)
254: { return IOStorage::open(client, options, access); }
255:
256: virtual IOReturn read(IOService * client,
257: UInt64 byteStart,
258: IOMemoryDescriptor * buffer,
259: UInt64 * actualByteCount = 0)
260: { return IOStorage::read(client, byteStart, buffer, actualByteCount); }
261:
262: virtual IOReturn write(IOService * client,
263: UInt64 byteStart,
264: IOMemoryDescriptor * buffer,
265: UInt64 * actualByteCount = 0)
266: { return IOStorage::write(client, byteStart, buffer, actualByteCount); }
267: ///m:2333367:workaround:added:stop
268:
269: /*!
270: * @function init
271: * @discussion
272: * Initialize this object's minimal state.
273: * @param base
274: * Media offset, in bytes.
275: * @param size
276: * Media size, in bytes.
277: * @param preferredBlockSize
278: * Natural block size, in bytes.
279: * @param isEjectable
280: * Indicates whether the media is ejectable.
281: * @param isWhole
282: * Indicated whether the media represents the whole disk.
283: * @param isWritable
284: * Indicates whether the media is writable.
285: * @param contentHint
286: * Hint of media's contents (optional). See getContentHint().
287: * @param properties
288: * Substitute property table for this object (optional).
289: * @result
290: * Returns true on success, false otherwise.
291: */
292:
293: virtual bool init(UInt64 base,
294: UInt64 size,
295: UInt64 preferredBlockSize,
296: bool isEjectable,
297: bool isWhole,
298: bool isWritable,
299: const char * contentHint = 0,
300: OSDictionary * properties = 0);
301:
302: /*
303: * This method is called for each client interested in the services we
304: * provide. The superclass links us as a parent to this client in the
305: * I/O Kit registry on success.
306: */
307:
308: bool attachToChild(IORegistryEntry * client, const IORegistryPlane *);
309:
310: /*
311: * This method is called for each client that loses interest in the
312: * services we provide. The superclass unlinks us from this client
313: * in the I/O Kit registry on success.
314: */
315:
316: void detachFromChild(IORegistryEntry * client, const IORegistryPlane *);
317:
318: /*
319: * I/O Kit is in the process of searching for a candidate object that wishes
320: * to match against an IOLocation={x} dictionary of properties. This is the
321: * method called to determine whether this object wants to be the candidate.
322: *
323: * The matchLocation method should return "this" if it decides to match with
324: * the IOLocation={x} dictionary, otherwise it should call the superclass to
325: * continue with the search and skip this object as a candidate.
326: *
327: * If this object chooses to match, the dictionary {x} will be passed to the
328: * standard (passive) matching method matchPropertyTable for comparison.
329: */
330:
331: virtual IOService * matchLocation(IOService * client);
332:
333: /*
334: * Compare the properties in the supplied table to this object's properties.
335: */
336:
337: virtual bool matchPropertyTable(OSDictionary * table);
338:
339: /*
340: * Obtain a path to this service object.
341: */
342:
343: virtual bool getPath(char * path, int * len, const IORegistryPlane *) const;
344:
345: /*!
346: * @function read
347: * @discussion
348: * Read data from the storage object at the specified byte offset into the
349: * specified buffer, asynchronously. When the read completes, the caller
350: * will be notified via the specified completion action.
351: *
352: * The buffer will be retained for the duration of the read.
353: * @param client
354: * Client requesting the read.
355: * @param byteStart
356: * Starting byte offset for the data transfer.
357: * @param buffer
358: * Buffer for the data transfer. The size of the buffer implies the size of
359: * the data transfer.
360: * @param completion
361: * Completion routine to call once the data transfer is complete.
362: */
363:
364: virtual void read(IOService * client,
365: UInt64 byteStart,
366: IOMemoryDescriptor * buffer,
367: IOStorageCompletion completion);
368:
369: /*!
370: * @function write
371: * @discussion
372: * Write data into the storage object at the specified byte offset from the
373: * specified buffer, asynchronously. When the write completes, the caller
374: * will be notified via the specified completion action.
375: *
376: * The buffer will be retained for the duration of the write.
377: * @param client
378: * Client requesting the write.
379: * @param byteStart
380: * Starting byte offset for the data transfer.
381: * @param buffer
382: * Buffer for the data transfer. The size of the buffer implies the size of
383: * the data transfer.
384: * @param completion
385: * Completion routine to call once the data transfer is complete.
386: */
387:
388: virtual void write(IOService * client,
389: UInt64 byteStart,
390: IOMemoryDescriptor * buffer,
391: IOStorageCompletion completion);
392:
393: /*!
394: * @function getPreferredBlockSize
395: * @discussion
396: * Ask the media object for its natural block size. This information
397: * is useful to clients that want to optimize access to the media.
398: * @result
399: * Natural block size, in bytes.
400: */
401:
402: virtual UInt64 getPreferredBlockSize() const;
403:
404: /*!
405: * @function getSize
406: * @discussion
407: * Ask the media object for its total length in bytes.
408: * @result
409: * Media size, in bytes.
410: */
411:
412: virtual UInt64 getSize() const;
413:
414: /*!
415: * @function getBase
416: * @discussion
417: * Ask the media object for its byte offset relative to its provider media
418: * object below it in the storage hierarchy.
419: * Media offset, in bytes.
420: */
421:
422: virtual UInt64 getBase() const;
423:
424: /*!
425: * @function isEjectable
426: * @discussion
427: * Ask the media object whether it is ejectable.
428: * @result
429: * Returns true if the media is ejectable, false otherwise.
430: */
431:
432: virtual bool isEjectable() const;
433:
434: /*!
435: * @function isFormatted
436: * @discussion
437: * Ask the media object whether it is formatted.
438: * @result
439: * Returns true if the media is formatted, false otherwise.
440: */
441:
442: virtual bool isFormatted() const;
443:
444: /*!
445: * @function isWhole
446: * @discussion
447: * Ask the media object whether it represents the whole disk.
448: * @result
449: * Returns true if the media represents the whole disk, false otherwise.
450: */
451:
452: virtual bool isWhole() const;
453:
454: /*!
455: * @function isWritable
456: * @discussion
457: * Ask the media object whether it is writable.
458: * @result
459: * Returns true if the media is writable, false otherwise.
460: */
461:
462: virtual bool isWritable() const;
463:
464: /*!
465: * @function getContent
466: * @discussion
467: * Ask the media object for a description of its contents. The description
468: * is the same as the hint at the time of the object's creation, but it is
469: * possible that the description be overrided by a client (which has probed
470: * the media and identified the content correctly) of the media object. It
471: * is more accurate than the hint for this reason. The string is formed in
472: * the likeness of Apple's "Apple_HFS" strings.
473: *
474: * The content description can be overrided by any client that matches onto
475: * this media object with a match category of kIOStorageCategory. The media
476: * object checks for a kIOMediaContentMask property in the client, and if it
477: * finds one, it copies it into kIOMediaContent property.
478: * @result
479: * Description of media's contents.
480: */
481:
482: virtual const char * getContent() const;
483:
484: /*!
485: * @function getContentHint
486: * @discussion
487: * Ask the media object for a hint of its contents. The hint is set at the
488: * time of the object's creation, should the creator have a clue as to what
489: * it may contain. The hint string does not change for the lifetime of the
490: * object and is also formed in the likeness of Apple's "Apple_HFS" strings.
491: * @result
492: * Hint of media's contents.
493: */
494:
495: virtual const char * getContentHint() const;
496:
497: /*
498: * Obtain this object's provider. We override the superclass's method to
499: * return a more specific subclass of OSObject -- IOStorage. This method
500: * serves simply as a convenience to subclass developers.
501: */
502:
503: virtual IOStorage * getProvider() const
504: {
505: return (IOStorage *) IOStorage::getProvider();
506: }
507: };
508:
509: #endif /* defined(KERNEL) && defined(__cplusplus) */
510:
511: #endif /* !_IOMEDIA_H */
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.