iokit/DriverKit/IODMACommand.iig

   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
  42 enum {
  43         kIODMACommandCreateNoOptions = 0,
  44 };
  45
  46 // IODMACommand PrepareForDMA options
  47 enum {
  48         kIODMACommandPrepareForDMANoOptions = 0,
  49 };
  50
  51 // IODMACommand CompleteDMA options
  52 enum {
  53         kIODMACommandCompleteDMANoOptions = 0,
  54 };
  55
  56 // IODMACommand PerformOperation options
  57 enum {
  58         kIODMACommandPerformOperationOptionRead  = 0x00000001,
  59         kIODMACommandPerformOperationOptionWrite = 0x00000002,
  60         kIODMACommandPerformOperationOptionZero  = 0x00000004,
  61 };
  62
  63 // IODMACommandSpecification options
  64 enum {
  65         kIODMACommandSpecificationNoOptions = 0,
  66 };
  67
  68 struct 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
  90 class KERNEL IODMACommand : public OSObject
  91 {
  92 public:
  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 Returned count of segements returned in segments
 130          * @param       segments Returned DMA physical address and length segments covering the DMA
 131      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 132      */
 133         virtual kern_return_t
 134         PrepareForDMA(
 135                 uint64_t options,
 136                 IOMemoryDescriptor * memory,
 137                 uint64_t offset,
 138                 uint64_t length,
 139                 uint64_t * flags,
 140                 uint32_t * segmentsCount,
 141                 IOAddressSegment segments[32]);
 142
 143     /*!
 144      * @brief       Release a DMA mapping for memory.
 145      * @param       options
 146          *              kIODMACommandCompleteDMANoOptions No options needed.
 147      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 148      */
 149         virtual kern_return_t
 150         CompleteDMA(
 151                 uint64_t options);
 152
 153     /*!
 154      * @brief       Obtain the parameters of a DMA preparation.
 155      * @param       offset Returned starting offset of the preparation.
 156      * @param       length Returned length of the preparation.
 157      * @param       memory Returned IOMemoryDescriptor of the preparation. This should be
 158      *              released by the caller.
 159      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 160      */
 161         virtual kern_return_t
 162         GetPreparation(
 163                 uint64_t * offset,
 164                 uint64_t * length,
 165                 IOMemoryDescriptor ** memory);
 166
 167     /*!
 168      * @brief       Perform CPU access to the DMA mapping.
 169          * @param       options Flags for the operation to be performed
 170                                         kIODMACommandPerformOperationOptionRead read from the DMA mapping to
 171                                         the memory specified with the data param
 172                                         kIODMACommandPerformOperationOptionWrite write to the DMA mapping from
 173                                         the memory specified with the data param
 174                                         kIODMACommandPerformOperationOptionZero zero the DMA mapping
 175      * @param       dmaOffset Offset into the DMA mapping for the operation to begin.
 176      * @param       length Length of the operation.
 177      * @param       dataffset Offset into the memory specified with the data param
 178      * @param       data Callers buffer to read into or write from. Pass NULL when
 179      *              using kIODMACommandPerformOperationOptionZero.
 180      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 181      */
 182         virtual kern_return_t
 183         PerformOperation(
 184                 uint64_t options,
 185                 uint64_t dmaOffset,
 186                 uint64_t length,
 187                 uint64_t dataOffset,
 188                 IOMemoryDescriptor * data);
 189 };
 190
 191 #endif /* ! _IOKIT_UIODMACOMMMAND_H */