1/* iig(DriverKit-286) generated from IODMACommand.iig */
2
3/* IODMACommand.iig:1-73 */
4/*
5 * Copyright (c) 2020 Apple Inc. All rights reserved.
6 *
7 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
8 *
9 * This file contains Original Code and/or Modifications of Original Code
10 * as defined in and that are subject to the Apple Public Source License
11 * Version 2.0 (the 'License'). You may not use this file except in
12 * compliance with the License. The rights granted to you under the License
13 * may not be used to create, or enable the creation or redistribution of,
14 * unlawful or unlicensed copies of an Apple operating system, or to
15 * circumvent, violate, or enable the circumvention or violation of, any
16 * terms of an Apple operating system software license agreement.
17 *
18 * Please obtain a copy of the License at
19 * http://www.opensource.apple.com/apsl/ and read it before using this file.
20 *
21 * The Original Code and all software distributed under the License are
22 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
23 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
24 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
25 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
26 * Please see the License for the specific language governing rights and
27 * limitations under the License.
28 *
29 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
30 */
31
32#if !__IIG
33#if KERNEL
34#include <IOKit/IODMACommand.h>
35#endif
36#endif
37
38#ifndef _IOKIT_UIODMACOMMMAND_H
39#define _IOKIT_UIODMACOMMMAND_H
40
41#include <DriverKit/IOMemoryDescriptor.h> /* .iig include */
42#include <DriverKit/IOService.h> /* .iig include */
43
44// IODMACommand Create options
45enum {
46 kIODMACommandCreateNoOptions = 0,
47};
48
49// IODMACommand PrepareForDMA options
50enum {
51 kIODMACommandPrepareForDMANoOptions = 0,
52};
53
54// IODMACommand CompleteDMA options
55enum {
56 kIODMACommandCompleteDMANoOptions = 0,
57};
58
59// IODMACommand PerformOperation options
60enum {
61 kIODMACommandPerformOperationOptionRead = 0x00000001,
62 kIODMACommandPerformOperationOptionWrite = 0x00000002,
63 kIODMACommandPerformOperationOptionZero = 0x00000004,
64};
65
66// IODMACommandSpecification options
67enum {
68 kIODMACommandSpecificationNoOptions = 0,
69};
70
71struct IODMACommandSpecification {
72 uint64_t options;
73 uint64_t maxAddressBits;
74 uint64_t _resv[16];
75};
76
77/* source class IODMACommand IODMACommand.iig:74-189 */
78
79#if __DOCUMENTATION__
80#define KERNEL IIG_KERNEL
81
82/*!
83 * @class IODMACommand
84 *
85 * @abstract
86 * IODMACommand allows a mapping for DMA to be created from an IOMemoryDescriptor.
87 *
88 * @discussion
89 * IODMACommand allows a mapping for DMA to be created from an IOMemoryDescriptor.
90 * The IODMACommand instance represents the mapping and should be kept prepared for the
91 * duration of the I/O, and completed when the I/O is finished.
92 * IODMACommand does not perform bounce buffering but allows access to the mapping with
93 * the PerformOperation method so that data can moved into and out of the mapping, eg.
94 * to/from a driver allocated bounce buffer.
95 *
96*/
97
98class KERNEL IODMACommand : public OSObject
99{
100public:
101
102 virtual bool
103 init() override;
104
105 virtual void
106 free() override;
107
108 /*!
109 * @brief Create an IODMACommand instance.
110 * @param device The device (typically an IOPCIDevice instance that will be
111 * generating the I/O.
112 * @param options
113 * kIODMACommandCreateNoOptions No options needed
114 * @param specification A caller initialized structure describing
115 * the hardware's DMA capaibilities
116 * @param command Returned IODMACommand object with +1 retain count.
117 * It should be retained until the map is no longer required.
118 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
119 */
120 static kern_return_t
121 Create(
122 IOService * device,
123 uint64_t options,
124 const IODMACommandSpecification * specification,
125 IODMACommand ** command);
126
127 /*!
128 * @brief Create a DMA mapping for memory.
129 * @param options
130 * kIODMACommandPrepareForDMANoOptions No options needed.
131 * @param memory IOMemoryDescriptor for memory.
132 * @param offset Start offset of the DMA operation in the descriptor.
133 * @param length Pass zero to map the entire memory, or a value <= the length of the descriptor.
134 * @param flags Returned bit mask of flags
135 kIOMemoryDirectionOut the memory is readable
136 kIOMemoryDirectionIn the memory is writable
137 * @param segmentsCount In/out parameter - size of segments array on input,
138 and number of valid segments returned
139 * @param segments Returned DMA physical address and length segments covering the DMA
140 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
141 */
142 virtual kern_return_t
143 PrepareForDMA(
144 uint64_t options,
145 IOMemoryDescriptor * memory,
146 uint64_t offset,
147 uint64_t length,
148 uint64_t * flags,
149 uint32_t * segmentsCount,
150 IOAddressSegment segments[32]);
151
152 /*!
153 * @brief Release a DMA mapping for memory.
154 * @param options
155 * kIODMACommandCompleteDMANoOptions No options needed.
156 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
157 */
158 virtual kern_return_t
159 CompleteDMA(
160 uint64_t options);
161
162 /*!
163 * @brief Obtain the parameters of a DMA preparation.
164 * @param offset Returned starting offset of the preparation.
165 * @param length Returned length of the preparation.
166 * @param memory Returned IOMemoryDescriptor of the preparation. This should be
167 * released by the caller.
168 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
169 */
170 virtual kern_return_t
171 GetPreparation(
172 uint64_t * offset,
173 uint64_t * length,
174 IOMemoryDescriptor ** memory);
175
176 /*!
177 * @brief Perform CPU access to the DMA mapping.
178 * @param options Flags for the operation to be performed
179 kIODMACommandPerformOperationOptionRead read from the DMA mapping to
180 the memory specified with the data param
181 kIODMACommandPerformOperationOptionWrite write to the DMA mapping from
182 the memory specified with the data param
183 kIODMACommandPerformOperationOptionZero zero the DMA mapping
184 * @param dmaOffset Offset into the DMA mapping for the operation to begin.
185 * @param length Length of the operation.
186 * @param dataffset Offset into the memory specified with the data param
187 * @param data Callers buffer to read into or write from. Pass NULL when
188 * using kIODMACommandPerformOperationOptionZero.
189 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
190 */
191 virtual kern_return_t
192 PerformOperation(
193 uint64_t options,
194 uint64_t dmaOffset,
195 uint64_t length,
196 uint64_t dataOffset,
197 IOMemoryDescriptor * data);
198};
199
200#undef KERNEL
201#else /* __DOCUMENTATION__ */
202
203/* generated class IODMACommand IODMACommand.iig:74-189 */
204
205#define IODMACommand_Create_ID 0xf296a92bb435af2eULL
206#define IODMACommand_PrepareForDMA_ID 0xf88a8c08b75b1110ULL
207#define IODMACommand_CompleteDMA_ID 0xae15e446c7041259ULL
208#define IODMACommand_GetPreparation_ID 0xcb1908ddf3b73cdeULL
209#define IODMACommand_PerformOperation_ID 0xc41cd97d9b3042eeULL
210
211#define IODMACommand_Create_Args \
212 IOService * device, \
213 uint64_t options, \
214 const IODMACommandSpecification * specification, \
215 IODMACommand ** command
216
217#define IODMACommand_PrepareForDMA_Args \
218 uint64_t options, \
219 IOMemoryDescriptor * memory, \
220 uint64_t offset, \
221 uint64_t length, \
222 uint64_t * flags, \
223 uint32_t * segmentsCount, \
224 IOAddressSegment * segments
225
226#define IODMACommand_CompleteDMA_Args \
227 uint64_t options
228
229#define IODMACommand_GetPreparation_Args \
230 uint64_t * offset, \
231 uint64_t * length, \
232 IOMemoryDescriptor ** memory
233
234#define IODMACommand_PerformOperation_Args \
235 uint64_t options, \
236 uint64_t dmaOffset, \
237 uint64_t length, \
238 uint64_t dataOffset, \
239 IOMemoryDescriptor * data
240
241#define IODMACommand_Methods \
242\
243public:\
244\
245 virtual kern_return_t\
246 Dispatch(const IORPC rpc) APPLE_KEXT_OVERRIDE;\
247\
248 static kern_return_t\
249 _Dispatch(IODMACommand * self, const IORPC rpc);\
250\
251 static kern_return_t\
252 Create(\
253 IOService * device,\
254 uint64_t options,\
255 const IODMACommandSpecification * specification,\
256 IODMACommand ** command);\
257\
258 kern_return_t\
259 PrepareForDMA(\
260 uint64_t options,\
261 IOMemoryDescriptor * memory,\
262 uint64_t offset,\
263 uint64_t length,\
264 uint64_t * flags,\
265 uint32_t * segmentsCount,\
266 IOAddressSegment * segments,\
267 OSDispatchMethod supermethod = NULL);\
268\
269 kern_return_t\
270 CompleteDMA(\
271 uint64_t options,\
272 OSDispatchMethod supermethod = NULL);\
273\
274 kern_return_t\
275 GetPreparation(\
276 uint64_t * offset,\
277 uint64_t * length,\
278 __attribute__((os_returns_retained)) IOMemoryDescriptor ** memory,\
279 OSDispatchMethod supermethod = NULL);\
280\
281 kern_return_t\
282 PerformOperation(\
283 uint64_t options,\
284 uint64_t dmaOffset,\
285 uint64_t length,\
286 uint64_t dataOffset,\
287 IOMemoryDescriptor * data,\
288 OSDispatchMethod supermethod = NULL);\
289\
290\
291protected:\
292 /* _Impl methods */\
293\
294\
295public:\
296 /* _Invoke methods */\
297\
298 typedef kern_return_t (*Create_Handler)(IODMACommand_Create_Args);\
299 static kern_return_t\
300 Create_Invoke(const IORPC rpc,\
301 Create_Handler func);\
302\
303 typedef kern_return_t (*PrepareForDMA_Handler)(OSMetaClassBase * target, IODMACommand_PrepareForDMA_Args);\
304 static kern_return_t\
305 PrepareForDMA_Invoke(const IORPC rpc,\
306 OSMetaClassBase * target,\
307 PrepareForDMA_Handler func);\
308\
309 typedef kern_return_t (*CompleteDMA_Handler)(OSMetaClassBase * target, IODMACommand_CompleteDMA_Args);\
310 static kern_return_t\
311 CompleteDMA_Invoke(const IORPC rpc,\
312 OSMetaClassBase * target,\
313 CompleteDMA_Handler func);\
314\
315 typedef kern_return_t (*GetPreparation_Handler)(OSMetaClassBase * target, IODMACommand_GetPreparation_Args);\
316 static kern_return_t\
317 GetPreparation_Invoke(const IORPC rpc,\
318 OSMetaClassBase * target,\
319 GetPreparation_Handler func);\
320\
321 typedef kern_return_t (*PerformOperation_Handler)(OSMetaClassBase * target, IODMACommand_PerformOperation_Args);\
322 static kern_return_t\
323 PerformOperation_Invoke(const IORPC rpc,\
324 OSMetaClassBase * target,\
325 PerformOperation_Handler func);\
326\
327
328
329#define IODMACommand_KernelMethods \
330\
331protected:\
332 /* _Impl methods */\
333\
334 static kern_return_t\
335 Create_Impl(IODMACommand_Create_Args);\
336\
337 kern_return_t\
338 PrepareForDMA_Impl(IODMACommand_PrepareForDMA_Args);\
339\
340 kern_return_t\
341 CompleteDMA_Impl(IODMACommand_CompleteDMA_Args);\
342\
343 kern_return_t\
344 GetPreparation_Impl(IODMACommand_GetPreparation_Args);\
345\
346 kern_return_t\
347 PerformOperation_Impl(IODMACommand_PerformOperation_Args);\
348\
349
350
351#define IODMACommand_VirtualMethods \
352\
353public:\
354\
355 virtual bool\
356 init(\
357) APPLE_KEXT_OVERRIDE;\
358\
359 virtual void\
360 free(\
361) APPLE_KEXT_OVERRIDE;\
362\
363
364
365#if !KERNEL
366
367extern OSMetaClass * gIODMACommandMetaClass;
368extern const OSClassLoadInformation IODMACommand_Class;
369
370class IODMACommandMetaClass : public OSMetaClass
371{
372public:
373 virtual kern_return_t
374 New(OSObject * instance) override;
375 virtual kern_return_t
376 Dispatch(const IORPC rpc) override;
377};
378
379#endif /* !KERNEL */
380
381#if !KERNEL
382
383class IODMACommandInterface : public OSInterface
384{
385public:
386};
387
388struct IODMACommand_IVars;
389struct IODMACommand_LocalIVars;
390
391class IODMACommand : public OSObject, public IODMACommandInterface
392{
393#if !KERNEL
394 friend class IODMACommandMetaClass;
395#endif /* !KERNEL */
396
397#if !KERNEL
398public:
399#ifdef IODMACommand_DECLARE_IVARS
400IODMACommand_DECLARE_IVARS
401#else /* IODMACommand_DECLARE_IVARS */
402 union
403 {
404 IODMACommand_IVars * ivars;
405 IODMACommand_LocalIVars * lvars;
406 };
407#endif /* IODMACommand_DECLARE_IVARS */
408#endif /* !KERNEL */
409
410#if !KERNEL
411 static OSMetaClass *
412 sGetMetaClass() { return gIODMACommandMetaClass; };
413#endif /* KERNEL */
414
415 using super = OSObject;
416
417#if !KERNEL
418 IODMACommand_Methods
419 IODMACommand_VirtualMethods
420#endif /* !KERNEL */
421
422};
423#endif /* !KERNEL */
424
425
426#endif /* !__DOCUMENTATION__ */
427
428/* IODMACommand.iig:191- */
429
430#endif /* ! _IOKIT_UIODMACOMMMAND_H */
431