1/* 2 * Copyright (c) 2020 Apple Inc. All rights reserved. 3 * 4 * @APPLE_OSREFERENCE_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. The rights granted to you under the License 10 * may not be used to create, or enable the creation or redistribution of, 11 * unlawful or unlicensed copies of an Apple operating system, or to 12 * circumvent, violate, or enable the circumvention or violation of, any 13 * terms of an Apple operating system software license agreement. 14 * 15 * Please obtain a copy of the License at 16 * http://www.opensource.apple.com/apsl/ and read it before using this file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27 */ 28 29#if !__IIG 30#if KERNEL 31#include <IOKit/IODMACommand.h> 32#endif 33#endif 34 35#ifndef _IOKIT_UIODMACOMMMAND_H 36#define _IOKIT_UIODMACOMMMAND_H 37 38#include <DriverKit/IOMemoryDescriptor.iig> 39#include <DriverKit/IOService.iig> 40 41// IODMACommand Create options 42enum { 43 kIODMACommandCreateNoOptions = 0, 44}; 45 46// IODMACommand PrepareForDMA options 47enum { 48 kIODMACommandPrepareForDMANoOptions = 0, 49}; 50 51// IODMACommand CompleteDMA options 52enum { 53 kIODMACommandCompleteDMANoOptions = 0, 54}; 55 56// IODMACommand PerformOperation options 57enum { 58 kIODMACommandPerformOperationOptionRead = 0x00000001, 59 kIODMACommandPerformOperationOptionWrite = 0x00000002, 60 kIODMACommandPerformOperationOptionZero = 0x00000004, 61}; 62 63// IODMACommandSpecification options 64enum { 65 kIODMACommandSpecificationNoOptions = 0, 66}; 67 68struct IODMACommandSpecification { 69 uint64_t options; 70 uint64_t maxAddressBits; 71 uint64_t _resv[16]; 72}; 73 74/*! 75 * @class IODMACommand 76 * 77 * @abstract 78 * IODMACommand allows a mapping for DMA to be created from an IOMemoryDescriptor. 79 * 80 * @discussion 81 * IODMACommand allows a mapping for DMA to be created from an IOMemoryDescriptor. 82 * The IODMACommand instance represents the mapping and should be kept prepared for the 83 * duration of the I/O, and completed when the I/O is finished. 84 * IODMACommand does not perform bounce buffering but allows access to the mapping with 85 * the PerformOperation method so that data can moved into and out of the mapping, eg. 86 * to/from a driver allocated bounce buffer. 87 * 88*/ 89 90class KERNEL IODMACommand : public OSObject 91{ 92public: 93 94 virtual bool 95 init() override; 96 97 virtual void 98 free() override; 99 100 /*! 101 * @brief Create an IODMACommand instance. 102 * @param device The device (typically an IOPCIDevice instance that will be 103 * generating the I/O. 104 * @param options 105 * kIODMACommandCreateNoOptions No options needed 106 * @param specification A caller initialized structure describing 107 * the hardware's DMA capaibilities 108 * @param command Returned IODMACommand object with +1 retain count. 109 * It should be retained until the map is no longer required. 110 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 111 */ 112 static kern_return_t 113 Create( 114 IOService * device, 115 uint64_t options, 116 const IODMACommandSpecification * specification, 117 IODMACommand ** command); 118 119 /*! 120 * @brief Create a DMA mapping for memory. 121 * @param options 122 * kIODMACommandPrepareForDMANoOptions No options needed. 123 * @param memory IOMemoryDescriptor for memory. 124 * @param offset Start offset of the DMA operation in the descriptor. 125 * @param length Pass zero to map the entire memory, or a value <= the length of the descriptor. 126 * @param flags Returned bit mask of flags 127 kIOMemoryDirectionOut the memory is readable 128 kIOMemoryDirectionIn the memory is writable 129 * @param segmentsCount In/out parameter - size of segments array on input, 130 and number of valid segments returned 131 * @param segments Returned DMA physical address and length segments covering the DMA 132 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 133 */ 134 virtual kern_return_t 135 PrepareForDMA( 136 uint64_t options, 137 IOMemoryDescriptor * memory, 138 uint64_t offset, 139 uint64_t length, 140 uint64_t * flags, 141 uint32_t * segmentsCount, 142 IOAddressSegment segments[32]); 143 144 /*! 145 * @brief Release a DMA mapping for memory. 146 * @param options 147 * kIODMACommandCompleteDMANoOptions No options needed. 148 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 149 */ 150 virtual kern_return_t 151 CompleteDMA( 152 uint64_t options); 153 154 /*! 155 * @brief Obtain the parameters of a DMA preparation. 156 * @param offset Returned starting offset of the preparation. 157 * @param length Returned length of the preparation. 158 * @param memory Returned IOMemoryDescriptor of the preparation. This should be 159 * released by the caller. 160 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 161 */ 162 virtual kern_return_t 163 GetPreparation( 164 uint64_t * offset, 165 uint64_t * length, 166 IOMemoryDescriptor ** memory); 167 168 /*! 169 * @brief Perform CPU access to the DMA mapping. 170 * @param options Flags for the operation to be performed 171 kIODMACommandPerformOperationOptionRead read from the DMA mapping to 172 the memory specified with the data param 173 kIODMACommandPerformOperationOptionWrite write to the DMA mapping from 174 the memory specified with the data param 175 kIODMACommandPerformOperationOptionZero zero the DMA mapping 176 * @param dmaOffset Offset into the DMA mapping for the operation to begin. 177 * @param length Length of the operation. 178 * @param dataffset Offset into the memory specified with the data param 179 * @param data Callers buffer to read into or write from. Pass NULL when 180 * using kIODMACommandPerformOperationOptionZero. 181 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 182 */ 183 virtual kern_return_t 184 PerformOperation( 185 uint64_t options, 186 uint64_t dmaOffset, 187 uint64_t length, 188 uint64_t dataOffset, 189 IOMemoryDescriptor * data); 190}; 191 192#endif /* ! _IOKIT_UIODMACOMMMAND_H */ 193