uspace/lib/usb/include/usb/dma_buffer.h

   1 /*
   2  * Copyright (c) 2018 Ondrej Hlavaty
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * - Redistributions of source code must retain the above copyright
  10  *   notice, this list of conditions and the following disclaimer.
  11  * - Redistributions in binary form must reproduce the above copyright
  12  *   notice, this list of conditions and the following disclaimer in the
  13  *   documentation and/or other materials provided with the distribution.
  14  * - The name of the author may not be used to endorse or promote products
  15  *   derived from this software without specific prior written permission.
  16  *
  17  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  18  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  19  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  21  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  22  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27  */
  28 /** @addtogroup libusb
  29  * @{
  30  */
  31 /** @file
  32  * @brief USB host controller library: DMA buffer helpers
  33  *
  34  * Simplifies handling of buffers accessible to hardware. Defines properties of
  35  * such buffer, which can be communicated through IPC to allow higher layers to
  36  * allocate a buffer that is ready to be passed to HW right away (after being
  37  * shared through IPC).
  38  *
  39  * Currently, it is possible to allocate either completely contiguous buffers
  40  * (with dma_map_anonymous) or arbitrary memory (with as_area_create). Shall the
  41  * kernel be updated, this is a subject of major optimization of memory usage.
  42  * The other way to do it without the kernel is building an userspace IO vector
  43  * in a similar way how QEMU does it.
  44  *
  45  * The structures themselves are defined in usbhc_iface, because they need to be
  46  * passed through IPC.
  47  */
  48 #ifndef LIB_USB_DMA_BUFFER
  49 #define LIB_USB_DMA_BUFFER
  50
  51 #include <as.h>
  52 #include <bitops.h>
  53 #include <errno.h>
  54 #include <stdint.h>
  55 #include <stdlib.h>
  56 #include <usbhc_iface.h>
  57
  58 /**
  59  * The DMA policy describes properties of the buffer. It is used in two
  60  * different contexts. Either it represents requirements, which shall be
  61  * satisfied to avoid copying the buffer to a more strict one. Or, it is the
  62  * actual property of the buffer, which can be more strict than requested. It
  63  * always holds that more bits set means more restrictive policy, and that by
  64  * computing a bitwise OR one gets the restriction that holds for both.
  65  *
  66  * The high bits of a DMA policy represent a physical contiguity. If bit i is
  67  * set, it means that chunks of a size 2^(i+1) are contiguous in memory. It
  68  * shall never happen that bit i > j is set when j is not.
  69  *
  70  * The previous applies for i >= PAGE_WIDTH. Lower bits are used as bit flags.
  71  */
  72 #define DMA_POLICY_FLAGS_MASK           (PAGE_SIZE - 1)
  73 #define DMA_POLICY_CHUNK_SIZE_MASK      (~DMA_POLICY_FLAGS_MASK)
  74
  75 #define DMA_POLICY_4GiB (1<<0)          /**< Must use only 32-bit addresses */
  76
  77 #define DMA_POLICY_STRICT               (-1UL)
  78 #define DMA_POLICY_DEFAULT              DMA_POLICY_STRICT
  79
  80 extern dma_policy_t dma_policy_create(unsigned, size_t);
  81
  82 /**
  83  * Get mask which defines bits of offset in chunk.
  84  */
  85 static inline size_t dma_policy_chunk_mask(const dma_policy_t policy)
  86 {
  87         return policy | DMA_POLICY_FLAGS_MASK;
  88 }
  89
  90 extern errno_t dma_buffer_alloc(dma_buffer_t *db, size_t size);
  91 extern errno_t dma_buffer_alloc_policy(dma_buffer_t *, size_t, dma_policy_t);
  92 extern void dma_buffer_free(dma_buffer_t *);
  93
  94 extern uintptr_t dma_buffer_phys(const dma_buffer_t *, const void *);
  95
  96 static inline uintptr_t dma_buffer_phys_base(const dma_buffer_t *db)
  97 {
  98         return dma_buffer_phys(db, db->virt);
  99 }
 100
 101 extern errno_t dma_buffer_lock(dma_buffer_t *, void *, size_t);
 102 extern void dma_buffer_unlock(dma_buffer_t *, size_t);
 103
 104 extern void dma_buffer_acquire(dma_buffer_t *);
 105 extern void dma_buffer_release(dma_buffer_t *);
 106
 107 static inline bool dma_buffer_is_set(const dma_buffer_t *db)
 108 {
 109         return !!db->virt;
 110 }
 111
 112 #endif
 113 /**
 114  * @}
 115  */