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