iokit/DriverKit/IOMemoryDescriptor.iig

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