1/* 2 * Copyright (c) 2019-2019 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/IOMemoryDescriptor.h> 32#endif 33#endif 34 35#ifndef _IOKIT_UIOMEMORYDESCRIPTOR_H 36#define _IOKIT_UIOMEMORYDESCRIPTOR_H 37 38#include <DriverKit/OSObject.iig> 39 40class IOService; 41class IOMemoryMap; 42 43 44// IOMemoryDescriptor Create options 45enum { 46 kIOMemoryDirectionNone = 0x00000000, 47 kIOMemoryDirectionIn = 0x00000001, 48 kIOMemoryDirectionOut = 0x00000002, 49 kIOMemoryDirectionOutIn = kIOMemoryDirectionIn | kIOMemoryDirectionOut, 50 kIOMemoryDirectionInOut = kIOMemoryDirectionOutIn, 51 kIOMemoryDisableCopyOnWrite = 0x00000010 52}; 53 54// IOMemoryDescriptor CreateMapping options 55enum { 56 kIOMemoryMapFixedAddress = 0x00000001, 57 kIOMemoryMapReadOnly = 0x00000002, 58 kIOMemoryMapGuardedMask = 0x0000001C, 59 kIOMemoryMapGuardedDefault = 0x00000000, 60 kIOMemoryMapGuardedNone = 0x00000004, 61 kIOMemoryMapGuardedSmall = 0x00000008, 62 kIOMemoryMapGuardedLarge = 0x0000000C, 63 kIOMemoryMapCacheModeDefault = 0x00000000, 64 kIOMemoryMapCacheModeInhibit = 0x00000100, 65 kIOMemoryMapCacheModeCopyback = 0x00000200, 66 kIOMemoryMapCacheModeWriteThrough = 0x00000400, 67}; 68 69struct IOAddressSegment { 70 uint64_t address; 71 uint64_t length; 72}; 73 74struct _IOMDPrivateState { 75 uint64_t length; 76 uint64_t options; 77}; 78 79/*! 80 * @class IOMemoryDescriptor 81 * 82 * @abstract 83 * IOMemoryDescriptor describes a memory buffer. 84 * 85 * @discussion 86 * To allocate memory for I/O or sharing, use IOBufferMemoryDescriptor::Create() 87 * Methods in this class are used for memory that was supplied as a parameter. 88 * 89 90@iig implementation 91#include <DriverKit/IOService.h> 92@iig end 93*/ 94 95class KERNEL IOMemoryDescriptor : public OSObject 96{ 97public: 98 99 100 virtual bool 101 init() override; 102 103 virtual void 104 free() override; 105 106 /*! 107 * @brief Obtain the length of the memory described. 108 * @param returnLength Returned length. 109 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 110 */ 111 kern_return_t 112 GetLength( 113 uint64_t * returnLength) LOCALONLY; 114 115 /*! 116 * @brief Create a mapping of the memory in the callers address space. 117 * @param options 118 * kIOMemoryMapFixedAddress map at the address requested 119 * kIOMemoryMapReadOnly create a read only mapping 120 * kIOMemoryMapCacheModeDefault default cache mode 121 * kIOMemoryMapCacheModeInhibit inhibited cache mode 122 * kIOMemoryMapCacheModeCopyback copyback cache mode 123 * kIOMemoryMapCacheModeWriteThrough write through cache mode 124 * @param address Requested address if kIOMemoryMapFixedAddress was passed 125 * @param offset Start offset of the mapping in the descriptor. 126 * @param length Pass zero to map the entire memory, or a value <= the length of the descriptor. 127 * @param alignment of the memory virtual mapping. Only zero for no alignment is supported. 128 * @param map Returned IOMemoryMap object with +1 retain count. 129 * It should be retained until the map is no longer required. 130 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 131 */ 132 virtual kern_return_t 133 CreateMapping( 134 uint64_t options, 135 uint64_t address, 136 uint64_t offset, 137 uint64_t length, 138 uint64_t alignment, 139 IOMemoryMap ** map); 140 141 /*! 142 * @brief Create a memory descriptor that is a subrange of another memory 143 * descriptor 144 * @param memoryDescriptorCreateOptions 145 * kIOMemoryDirectionIn memory described will be writable 146 * kIOMemoryDirectionOut memory described will be readable 147 * @param offset Start offset of the memory relative to the descriptor ofDescriptor. 148 * @param length Length of the memory. 149 * @param ofDescriptor Memory descriptor describing source memory. 150 * @param memory Returned IOMemoryDescriptor object with +1 retain count. 151 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 152 */ 153 static kern_return_t 154 CreateSubMemoryDescriptor( 155 uint64_t memoryDescriptorCreateOptions, 156 uint64_t offset, 157 uint64_t length, 158 IOMemoryDescriptor * ofDescriptor, 159 IOMemoryDescriptor ** memory) __attribute__((availability(driverkit,introduced=20.0))); 160 161 /*! 162 * @brief Create a memory descriptor that is a concatenation of a set of memory 163 * descriptors 164 * @param memoryDescriptorCreateOptions 165 * kIOMemoryDirectionIn memory described will be writable. The source 166 * descriptors must include this direction. 167 * kIOMemoryDirectionOut memory described will be readable. The source 168 * descriptors must include this direction. 169 * @param withDescriptorsCount Number of valid memory descriptors being passed 170 * in the withDescriptors array. 171 * @param withDescriptors Source memory descriptor array. 172 * @param memory Returned IOMemoryDescriptor object with +1 retain count. 173 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 174 */ 175 static kern_return_t 176 CreateWithMemoryDescriptors( 177 uint64_t memoryDescriptorCreateOptions, 178 uint32_t withDescriptorsCount, 179 IOMemoryDescriptor * const withDescriptors[32], 180 IOMemoryDescriptor ** memory) __attribute__((availability(driverkit,introduced=20.0))); 181 182private: 183 kern_return_t 184 Map( 185 uint64_t options, 186 uint64_t address, 187 uint64_t length, 188 uint64_t alignment, 189 190 uint64_t * returnAddress, 191 uint64_t * returnLength) LOCALONLY; 192}; 193 194class EXTENDS (IOMemoryDescriptor) IOMemoryDescriptorPrivate 195{ 196 virtual kern_return_t 197 _CopyState( 198 _IOMDPrivateState * state); 199}; 200 201 202 203#endif /* ! _IOKIT_UIOMEMORYDESCRIPTOR_H */ 204