[apple/xnu.git] / iokit / IOKit / storage / IOPartitionScheme.h

/*
 * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * The contents of this file constitute Original Code as defined in and
 * are subject to the Apple Public Source License Version 1.1 (the
 * "License").  You may not use this file except in compliance with the
 * License.  Please obtain a copy of the License at
 * http://www.apple.com/publicsource and read it before using this file.
 * 
 * This Original Code and all software distributed under the License are
 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
 * License for the specific language governing rights and limitations
 * under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */

/*!
 * @header IOPartitionScheme
 * @abstract
 * This header contains the IOPartitionScheme class definition.
 */

#ifndef _IOPARTITIONSCHEME_H
#define _IOPARTITIONSCHEME_H

/*!
 * @defined kIOPartitionSchemeClass
 * @abstract
 * kIOPartitionSchemeClass is the name of the IOPartitionScheme class.
 * @discussion
 * kIOPartitionSchemeClass is the name of the IOPartitionScheme class.
 */

#define kIOPartitionSchemeClass "IOPartitionScheme"

/*!
 * @defined kIOMediaPartitionIDKey
 * @abstract
 * kIOMediaPartitionIDKey is property of IOMedia objects.  It has an OSNumber
 * value.
 * @discussion
 * The kIOMediaPartitionIDKey property is placed into each IOMedia instance
 * created via the partition scheme.  It is an ID that differentiates one 
 * partition from the other (within a given scheme).  It is typically an index
 * into the on-disk partition table.
 */

#define kIOMediaPartitionIDKey "Partition ID"
#define kIOMediaPartitionID "Partition ID" ///d:deprecated

/*
 * Kernel
 */

#if defined(KERNEL) && defined(__cplusplus)

#include <IOKit/storage/IOMedia.h>
#include <IOKit/storage/IOStorage.h>

/*!
 * @class IOPartitionScheme
 * @abstract
 * The IOPartitionScheme class is the common base class for all partition scheme
 * objects.
 * @discussion
 * The IOPartitionScheme class is the common base class for all partition scheme
 * objects.  It extends the IOStorage class by implementing the appropriate open
 * and close semantics for partition objects (standard semantics are to act as a
 * multiplexor for incoming opens,  producing one outgoing open with the correct
 * access).  It also implements the default read and write semantics, which pass
 * all reads and writes through to the provider media unprocessed.    For simple
 * schemes, the default behavior is sufficient.   More complex partition schemes
 * such as RAID will want to do extra processing for reads and writes.
 */

class IOPartitionScheme : public IOStorage
{
    OSDeclareDefaultStructors(IOPartitionScheme);

protected:

    struct ExpansionData { /* */ };
    ExpansionData * _expansionData;

    IOStorageAccess _openLevel;
    OSSet *         _openReaders;
    OSSet *         _openReaderWriters;

    /*
     * Free all of this object's outstanding resources.
     */

    virtual void free();

    /*!
     * @function handleOpen
     * @discussion
     * The handleOpen method grants or denies permission to access this object
     * to an interested client.  The argument is an IOStorageAccess value that
     * specifies the level of access desired -- reader or reader-writer.
     *
     * This method can be invoked to upgrade or downgrade the access level for
     * an existing client as well.  The previous access level will prevail for
     * upgrades that fail, of course.   A downgrade should never fail.  If the
     * new access level should be the same as the old for a given client, this
     * method will do nothing and return success.  In all cases, one, singular
     * close-per-client is expected for all opens-per-client received.
     *
     * This implementation replaces the IOService definition of handleOpen().
     * @param client
     * Client requesting the open.
     * @param options
     * Options for the open.  Set to zero.
     * @param access
     * Access level for the open.  Set to kIOStorageAccessReader or
     * kIOStorageAccessReaderWriter.
     * @result
     * Returns true if the open was successful, false otherwise.
     */

    virtual bool handleOpen(IOService *  client,
                            IOOptionBits options,
                            void *       access);

    /*!
     * @function handleIsOpen
     * @discussion
     * The handleIsOpen method determines whether the specified client, or any
     * client if none is specificed, presently has an open on this object.
     *
     * This implementation replaces the IOService definition of handleIsOpen().
     * @param client
     * Client to check the open state of.  Set to zero to check the open state
     * of all clients.
     * @result
     * Returns true if the client was (or clients were) open, false otherwise.
     */

    virtual bool handleIsOpen(const IOService * client) const;

    /*!
     * @function handleClose
     * @discussion
     * The handleClose method closes the client's access to this object.
     *
     * This implementation replaces the IOService definition of handleClose().
     * @param client
     * Client requesting the close.
     * @param options
     * Options for the close.  Set to zero.
     */

    virtual void handleClose(IOService * client, IOOptionBits options);

public:

///m:2333367:workaround:commented:start
//  using read;
//  using write;
///m:2333367:workaround:commented:stop

    /*
     * Initialize this object's minimal state.
     */

    virtual bool init(OSDictionary * properties = 0);

    /*!
     * @function read
     * @discussion
     * Read data from the storage object at the specified byte offset into the
     * specified buffer, asynchronously.   When the read completes, the caller
     * will be notified via the specified completion action.
     *
     * The buffer will be retained for the duration of the read.
     *
     * For simple partition schemes, the default behavior is to simply pass the
     * read through to the provider media.  More complex partition schemes such
     * as RAID will need to do extra processing here.
     * @param client
     * Client requesting the read.
     * @param byteStart
     * Starting byte offset for the data transfer.
     * @param buffer
     * Buffer for the data transfer.  The size of the buffer implies the size of
     * the data transfer.
     * @param completion
     * Completion routine to call once the data transfer is complete.
     */

    virtual void read(IOService *          client,
                      UInt64               byteStart,
                      IOMemoryDescriptor * buffer,
                      IOStorageCompletion  completion);

    /*!
     * @function write
     * @discussion
     * Write data into the storage object at the specified byte offset from the
     * specified buffer, asynchronously.   When the write completes, the caller
     * will be notified via the specified completion action.
     *
     * The buffer will be retained for the duration of the write.
     *
     * For simple partition schemes, the default behavior is to simply pass the
     * write through to the provider media. More complex partition schemes such
     * as RAID will need to do extra processing here.
     * @param client
     * Client requesting the write.
     * @param byteStart
     * Starting byte offset for the data transfer.
     * @param buffer
     * Buffer for the data transfer.  The size of the buffer implies the size of
     * the data transfer.
     * @param completion
     * Completion routine to call once the data transfer is complete.
     */

    virtual void write(IOService *          client,
                       UInt64               byteStart,
                       IOMemoryDescriptor * buffer,
                       IOStorageCompletion  completion);

    virtual IOReturn synchronizeCache(IOService * client);

    /*
     * Obtain this object's provider.  We override the superclass's method
     * to return a more specific subclass of OSObject -- an IOMedia.  This
     * method serves simply as a convenience to subclass developers.
     */

    virtual IOMedia * getProvider() const;

    OSMetaClassDeclareReservedUnused(IOPartitionScheme,  0);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme,  1);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme,  2);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme,  3);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme,  4);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme,  5);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme,  6);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme,  7);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme,  8);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme,  9);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 10);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 11);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 12);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 13);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 14);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 15);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 16);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 17);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 18);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 19);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 20);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 21);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 22);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 23);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 24);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 25);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 26);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 27);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 28);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 29);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 30);
    OSMetaClassDeclareReservedUnused(IOPartitionScheme, 31);
};

#endif /* defined(KERNEL) && defined(__cplusplus) */

#endif /* !_IOPARTITIONSCHEME_H */
Commit	Line	Data
1c79356b A	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 IOPartitionScheme
	25	* @abstract
	26	* This header contains the IOPartitionScheme class definition.
	27	*/
	28
	29	#ifndef _IOPARTITIONSCHEME_H
	30	#define _IOPARTITIONSCHEME_H
	31
	32	/*!
	33	* @defined kIOPartitionSchemeClass
	34	* @abstract
	35	* kIOPartitionSchemeClass is the name of the IOPartitionScheme class.
	36	* @discussion
	37	* kIOPartitionSchemeClass is the name of the IOPartitionScheme class.
	38	*/
	39
	40	#define kIOPartitionSchemeClass "IOPartitionScheme"
	41
	42	/*!
	43	* @defined kIOMediaPartitionIDKey
	44	* @abstract
	45	* kIOMediaPartitionIDKey is property of IOMedia objects. It has an OSNumber
	46	* value.
	47	* @discussion
	48	* The kIOMediaPartitionIDKey property is placed into each IOMedia instance
	49	* created via the partition scheme. It is an ID that differentiates one
	50	* partition from the other (within a given scheme). It is typically an index
	51	* into the on-disk partition table.
	52	*/
	53
	54	#define kIOMediaPartitionIDKey "Partition ID"
	55	#define kIOMediaPartitionID "Partition ID" ///d:deprecated
	56
	57	/*
	58	* Kernel
	59	*/
	60
	61	#if defined(KERNEL) && defined(__cplusplus)
	62
	63	#include <IOKit/storage/IOMedia.h>
	64	#include <IOKit/storage/IOStorage.h>
65
66	/*!
67	* @class IOPartitionScheme
68	* @abstract
69	* The IOPartitionScheme class is the common base class for all partition scheme
70	* objects.
71	* @discussion
72	* The IOPartitionScheme class is the common base class for all partition scheme
73	* objects. It extends the IOStorage class by implementing the appropriate open
74	* and close semantics for partition objects (standard semantics are to act as a
75	* multiplexor for incoming opens, producing one outgoing open with the correct
76	* access). It also implements the default read and write semantics, which pass
77	* all reads and writes through to the provider media unprocessed. For simple
78	* schemes, the default behavior is sufficient. More complex partition schemes
79	* such as RAID will want to do extra processing for reads and writes.
80	*/
81
82	class IOPartitionScheme : public IOStorage
83	{
84	OSDeclareDefaultStructors(IOPartitionScheme);
85
86	protected:
87
88	struct ExpansionData { /* */ };
89	ExpansionData * _expansionData;
90
91	IOStorageAccess _openLevel;
92	OSSet * _openReaders;
93	OSSet * _openReaderWriters;
94
95	/*
96	* Free all of this object's outstanding resources.
97	*/
98
99	virtual void free();
100
101	/*!
102	* @function handleOpen
103	* @discussion
104	* The handleOpen method grants or denies permission to access this object
105	* to an interested client. The argument is an IOStorageAccess value that
106	* specifies the level of access desired -- reader or reader-writer.
107	*
108	* This method can be invoked to upgrade or downgrade the access level for
109	* an existing client as well. The previous access level will prevail for
110	* upgrades that fail, of course. A downgrade should never fail. If the
111	* new access level should be the same as the old for a given client, this
112	* method will do nothing and return success. In all cases, one, singular
113	* close-per-client is expected for all opens-per-client received.
114	*
115	* This implementation replaces the IOService definition of handleOpen().
116	* @param client
117	* Client requesting the open.
118	* @param options
119	* Options for the open. Set to zero.
120	* @param access
121	* Access level for the open. Set to kIOStorageAccessReader or
122	* kIOStorageAccessReaderWriter.
123	* @result
124	* Returns true if the open was successful, false otherwise.
125	*/
126
127	virtual bool handleOpen(IOService * client,
128	IOOptionBits options,
129	void * access);
130
131	/*!
132	* @function handleIsOpen
133	* @discussion
134	* The handleIsOpen method determines whether the specified client, or any
135	* client if none is specificed, presently has an open on this object.
136	*
137	* This implementation replaces the IOService definition of handleIsOpen().
138	* @param client
139	* Client to check the open state of. Set to zero to check the open state
140	* of all clients.
141	* @result
142	* Returns true if the client was (or clients were) open, false otherwise.
143	*/
144
145	virtual bool handleIsOpen(const IOService * client) const;
146
147	/*!
148	* @function handleClose
149	* @discussion
150	* The handleClose method closes the client's access to this object.
151	*
152	* This implementation replaces the IOService definition of handleClose().
153	* @param client
154	* Client requesting the close.
155	* @param options
156	* Options for the close. Set to zero.
157	*/
158
159	virtual void handleClose(IOService * client, IOOptionBits options);
160
161	public:
162
163	///m:2333367:workaround:commented:start
164	// using read;
165	// using write;
166	///m:2333367:workaround:commented:stop
167
168	/*
169	* Initialize this object's minimal state.
170	*/
171
172	virtual bool init(OSDictionary * properties = 0);
173
174	/*!
175	* @function read
176	* @discussion
177	* Read data from the storage object at the specified byte offset into the
178	* specified buffer, asynchronously. When the read completes, the caller
179	* will be notified via the specified completion action.
180	*
181	* The buffer will be retained for the duration of the read.
182	*
183	* For simple partition schemes, the default behavior is to simply pass the
184	* read through to the provider media. More complex partition schemes such
185	* as RAID will need to do extra processing here.
186	* @param client
187	* Client requesting the read.
188	* @param byteStart
189	* Starting byte offset for the data transfer.
190	* @param buffer
191	* Buffer for the data transfer. The size of the buffer implies the size of
192	* the data transfer.
193	* @param completion
194	* Completion routine to call once the data transfer is complete.
195	*/
196
197	virtual void read(IOService * client,
198	UInt64 byteStart,
199	IOMemoryDescriptor * buffer,
200	IOStorageCompletion completion);
201
202	/*!
203	* @function write
204	* @discussion
205	* Write data into the storage object at the specified byte offset from the
206	* specified buffer, asynchronously. When the write completes, the caller
207	* will be notified via the specified completion action.
208	*
209	* The buffer will be retained for the duration of the write.
210	*
211	* For simple partition schemes, the default behavior is to simply pass the
212	* write through to the provider media. More complex partition schemes such
213	* as RAID will need to do extra processing here.
214	* @param client
215	* Client requesting the write.
216	* @param byteStart
217	* Starting byte offset for the data transfer.
218	* @param buffer
219	* Buffer for the data transfer. The size of the buffer implies the size of
220	* the data transfer.
221	* @param completion
222	* Completion routine to call once the data transfer is complete.
223	*/
224
225	virtual void write(IOService * client,
226	UInt64 byteStart,
227	IOMemoryDescriptor * buffer,
228	IOStorageCompletion completion);
229
230	virtual IOReturn synchronizeCache(IOService * client);
231
232	/*
233	* Obtain this object's provider. We override the superclass's method
234	* to return a more specific subclass of OSObject -- an IOMedia. This
235	* method serves simply as a convenience to subclass developers.
236	*/
237
238	virtual IOMedia * getProvider() const;
239
240	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 0);
241	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 1);
242	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 2);
243	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 3);
244	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 4);
245	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 5);
246	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 6);
247	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 7);
248	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 8);
249	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 9);
250	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 10);
251	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 11);
252	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 12);
253	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 13);
254	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 14);
255	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 15);
256	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 16);
257	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 17);
258	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 18);
259	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 19);
260	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 20);
261	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 21);
262	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 22);
263	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 23);
264	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 24);
265	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 25);
266	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 26);
267	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 27);
268	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 28);
269	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 29);
270	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 30);
271	OSMetaClassDeclareReservedUnused(IOPartitionScheme, 31);
272	};
273
274	#endif /* defined(KERNEL) && defined(__cplusplus) */
275
276	#endif /* !_IOPARTITIONSCHEME_H */