1/*
2 * Copyright (c) 1998-2014 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 IOFilterScheme
26 * @abstract
27 * This header contains the IOFilterScheme class definition.
28 */
29
30#ifndef _IOFILTERSCHEME_H
31#define _IOFILTERSCHEME_H
32
33/*!
34 * @defined kIOFilterSchemeClass
35 * @abstract
36 * The name of the IOFilterScheme class.
37 * @discussion
38 * kIOFilterSchemeClass is the name of the IOFilterScheme class.
39 */
40
41#define kIOFilterSchemeClass "IOFilterScheme"
42
43#ifdef KERNEL
44#ifdef __cplusplus
45
46/*
47 * Kernel
48 */
49
50#include <IOKit/storage/IOMedia.h>
51#include <IOKit/storage/IOStorage.h>
52
53/*!
54 * @class IOFilterScheme
55 * @abstract
56 * The common base class for all filter scheme
57 * objects.
58 * @discussion
59 * The IOFilterScheme class is the common base class for all filter scheme
60 * objects.  It extends the IOStorage class by implementing the appropriate
61 * open and close semantics for filter objects (standard semantics are act
62 * as a relay for incoming opens, producing one outgoing open for each
63 * incoming open).  It also implements the default read and write semantics,
64 * which pass all reads and writes through to the provider media unprocessed.
65 * For simple schemes, the default behavior is sufficient.  More complex
66 * filter schemes such as RAID will want to do extra processing for reads
67 * and writes.
68 */
69
70class IOFilterScheme : public IOStorage
71{
72    OSDeclareDefaultStructors(IOFilterScheme);
73
74protected:
75
76    struct ExpansionData { /* */ };
77    ExpansionData * _expansionData;
78
79    /*!
80     * @function handleOpen
81     * @discussion
82     * The handleOpen method grants or denies permission to access this object
83     * to an interested client.  The argument is an IOStorageAccess value that
84     * specifies the level of access desired -- reader or reader-writer.
85     *
86     * This method can be invoked to upgrade or downgrade the access level for
87     * an existing client as well.  The previous access level will prevail for
88     * upgrades that fail, of course.   A downgrade should never fail.  If the
89     * new access level should be the same as the old for a given client, this
90     * method will do nothing and return success.  In all cases, one, singular
91     * close-per-client is expected for all opens-per-client received.
92     *
93     * This implementation replaces the IOService definition of handleOpen().
94     * @param client
95     * Client requesting the open.
96     * @param options
97     * Options for the open.  Set to zero.
98     * @param access
99     * Access level for the open.  Set to kIOStorageAccessReader or
100     * kIOStorageAccessReaderWriter.
101     * @result
102     * Returns true if the open was successful, false otherwise.
103     */
104
105    virtual bool handleOpen(IOService *  client,
106                            IOOptionBits options,
107                            void *       access);
108
109    /*!
110     * @function handleIsOpen
111     * @discussion
112     * The handleIsOpen method determines whether the specified client, or any
113     * client if none is specified, presently has an open on this object.
114     *
115     * This implementation replaces the IOService definition of handleIsOpen().
116     * @param client
117     * Client to check the open state of.  Set to zero to check the open state
118     * of all clients.
119     * @result
120     * Returns true if the client was (or clients were) open, false otherwise.
121     */
122
123    virtual bool handleIsOpen(const IOService * client) const;
124
125    /*!
126     * @function handleClose
127     * @discussion
128     * The handleClose method closes the client's access to this object.
129     *
130     * This implementation replaces the IOService definition of handleClose().
131     * @param client
132     * Client requesting the close.
133     * @param options
134     * Options for the close.  Set to zero.
135     */
136
137    virtual void handleClose(IOService * client, IOOptionBits options);
138
139public:
140
141    using IOStorage::read;
142    using IOStorage::write;
143
144    /*!
145     * @function read
146     * @discussion
147     * Read data from the storage object at the specified byte offset into the
148     * specified buffer, asynchronously.   When the read completes, the caller
149     * will be notified via the specified completion action.
150     *
151     * The buffer will be retained for the duration of the read.
152     *
153     * For simple filter schemes, the default behavior is to simply pass the
154     * read through to the provider media.  More complex filter schemes such
155     * as RAID will need to do extra processing here.
156     * @param client
157     * Client requesting the read.
158     * @param byteStart
159     * Starting byte offset for the data transfer.
160     * @param buffer
161     * Buffer for the data transfer.  The size of the buffer implies the size of
162     * the data transfer.
163     * @param attributes
164     * Attributes of the data transfer.  See IOStorageAttributes.  It is the
165     * responsibility of the callee to maintain the information for the duration
166     * of the data transfer, as necessary.
167     * @param completion
168     * Completion routine to call once the data transfer is complete.  It is the
169     * responsibility of the callee to maintain the information for the duration
170     * of the data transfer, as necessary.
171     */
172
173    virtual void read(IOService *           client,
174                      UInt64                byteStart,
175                      IOMemoryDescriptor *  buffer,
176                      IOStorageAttributes * attributes,
177                      IOStorageCompletion * completion);
178
179    /*!
180     * @function write
181     * @discussion
182     * Write data into the storage object at the specified byte offset from the
183     * specified buffer, asynchronously.   When the write completes, the caller
184     * will be notified via the specified completion action.
185     *
186     * The buffer will be retained for the duration of the write.
187     *
188     * For simple filter schemes, the default behavior is to simply pass the
189     * write through to the provider media. More complex filter schemes such
190     * as RAID will need to do extra processing here.
191     * @param client
192     * Client requesting the write.
193     * @param byteStart
194     * Starting byte offset for the data transfer.
195     * @param buffer
196     * Buffer for the data transfer.  The size of the buffer implies the size of
197     * the data transfer.
198     * @param attributes
199     * Attributes of the data transfer.  See IOStorageAttributes.  It is the
200     * responsibility of the callee to maintain the information for the duration
201     * of the data transfer, as necessary.
202     * @param completion
203     * Completion routine to call once the data transfer is complete.  It is the
204     * responsibility of the callee to maintain the information for the duration
205     * of the data transfer, as necessary.
206     */
207
208    virtual void write(IOService *           client,
209                       UInt64                byteStart,
210                       IOMemoryDescriptor *  buffer,
211                       IOStorageAttributes * attributes,
212                       IOStorageCompletion * completion);
213
214    /*!
215     * @function synchronizeCache
216     * @discussion
217     * Flush the cached data in the storage object, if any, synchronously.
218     * @param client
219     * Client requesting the cache synchronization.
220     * @result
221     * Returns the status of the cache synchronization.
222     */
223
224    virtual IOReturn synchronizeCache(IOService * client);
225
226    /*!
227     * @function unmap
228     * @discussion
229     * Delete unused data from the storage object at the specified byte offsets,
230     * synchronously.
231     * @param client
232     * Client requesting the operation.
233     * @param extents
234     * List of extents.  See IOStorageExtent.  It is legal for the callee to
235     * overwrite the contents of this buffer in order to satisfy the request.
236     * @param extentsCount
237     * Number of extents.
238     * @result
239     * Returns the status of the operation.
240     */
241
242    virtual IOReturn unmap(IOService *       client,
243                           IOStorageExtent * extents,
244                           UInt32            extentsCount,
245                           UInt32            options = 0);
246
247    /*!
248     * @function lockPhysicalExtents
249     * @discussion
250     * Lock the contents of the storage object against relocation temporarily,
251     * for the purpose of getting physical extents.
252     * @param client
253     * Client requesting the operation.
254     * @result
255     * Returns true if the lock was successful, false otherwise.
256     */
257
258    virtual bool lockPhysicalExtents(IOService * client);
259
260    /*!
261     * @function copyPhysicalExtent
262     * @discussion
263     * Convert the specified byte offset into a physical byte offset, relative
264     * to a physical storage object.  This call should only be made within the
265     * context of lockPhysicalExtents().
266     * @param client
267     * Client requesting the operation.
268     * @param byteStart
269     * Starting byte offset for the operation.  Returns a physical byte offset,
270     * relative to the physical storage object, on success.
271     * @param byteCount
272     * Size of the operation.  Returns the actual number of bytes which can be
273     * transferred, relative to the physical storage object, on success.
274     * @result
275     * A reference to the physical storage object, which should be released by
276     * the caller, or a null on error.
277     */
278
279    virtual IOStorage * copyPhysicalExtent(IOService * client,
280                                           UInt64 *    byteStart,
281                                           UInt64 *    byteCount);
282
283    /*!
284     * @function unlockPhysicalExtents
285     * @discussion
286     * Unlock the contents of the storage object for relocation again.  This
287     * call must balance a successful call to lockPhysicalExtents().
288     * @param client
289     * Client requesting the operation.
290     */
291
292    virtual void unlockPhysicalExtents(IOService * client);
293
294    /*!
295     * @function setPriority
296     * @discussion
297     * Reprioritize read or write requests at the specified byte offsets.
298     * @param client
299     * Client requesting the operation.
300     * @param extents
301     * List of extents.  See IOStorageExtent.  It is legal for the callee to
302     * overwrite the contents of this buffer in order to satisfy the request.
303     * @param extentsCount
304     * Number of extents.
305     * @param priority
306     * New priority.  See IOStoragePriority.
307     * @result
308     * Returns the status of the operation.
309     */
310
311    virtual IOReturn setPriority(IOService *       client,
312                                 IOStorageExtent * extents,
313                                 UInt32            extentsCount,
314                                 IOStoragePriority priority);
315
316    /*
317     * Obtain this object's provider.  We override the superclass's method
318     * to return a more specific subclass of OSObject -- an IOMedia.  This
319     * method serves simply as a convenience to subclass developers.
320     */
321
322    virtual IOMedia * getProvider() const;
323
324    OSMetaClassDeclareReservedUnused(IOFilterScheme,  0);
325    OSMetaClassDeclareReservedUnused(IOFilterScheme,  1);
326    OSMetaClassDeclareReservedUnused(IOFilterScheme,  2);
327    OSMetaClassDeclareReservedUnused(IOFilterScheme,  3);
328    OSMetaClassDeclareReservedUnused(IOFilterScheme,  4);
329    OSMetaClassDeclareReservedUnused(IOFilterScheme,  5);
330    OSMetaClassDeclareReservedUnused(IOFilterScheme,  6);
331    OSMetaClassDeclareReservedUnused(IOFilterScheme,  7);
332    OSMetaClassDeclareReservedUnused(IOFilterScheme,  8);
333    OSMetaClassDeclareReservedUnused(IOFilterScheme,  9);
334    OSMetaClassDeclareReservedUnused(IOFilterScheme, 10);
335    OSMetaClassDeclareReservedUnused(IOFilterScheme, 11);
336    OSMetaClassDeclareReservedUnused(IOFilterScheme, 12);
337    OSMetaClassDeclareReservedUnused(IOFilterScheme, 13);
338    OSMetaClassDeclareReservedUnused(IOFilterScheme, 14);
339    OSMetaClassDeclareReservedUnused(IOFilterScheme, 15);
340    OSMetaClassDeclareReservedUnused(IOFilterScheme, 16);
341    OSMetaClassDeclareReservedUnused(IOFilterScheme, 17);
342    OSMetaClassDeclareReservedUnused(IOFilterScheme, 18);
343    OSMetaClassDeclareReservedUnused(IOFilterScheme, 19);
344    OSMetaClassDeclareReservedUnused(IOFilterScheme, 20);
345    OSMetaClassDeclareReservedUnused(IOFilterScheme, 21);
346    OSMetaClassDeclareReservedUnused(IOFilterScheme, 22);
347    OSMetaClassDeclareReservedUnused(IOFilterScheme, 23);
348    OSMetaClassDeclareReservedUnused(IOFilterScheme, 24);
349    OSMetaClassDeclareReservedUnused(IOFilterScheme, 25);
350    OSMetaClassDeclareReservedUnused(IOFilterScheme, 26);
351    OSMetaClassDeclareReservedUnused(IOFilterScheme, 27);
352    OSMetaClassDeclareReservedUnused(IOFilterScheme, 28);
353    OSMetaClassDeclareReservedUnused(IOFilterScheme, 29);
354    OSMetaClassDeclareReservedUnused(IOFilterScheme, 30);
355    OSMetaClassDeclareReservedUnused(IOFilterScheme, 31);
356};
357
358#endif /* __cplusplus */
359#endif /* KERNEL */
360#endif /* !_IOFILTERSCHEME_H */
361