LXR linux/include/linux/dma-contiguous.h

   1/* SPDX-License-Identifier: GPL-2.0-or-later */
   2#ifndef __LINUX_CMA_H
   3#define __LINUX_CMA_H
   4
   5/*
   6 * Contiguous Memory Allocator for DMA mapping framework
   7 * Copyright (c) 2010-2011 by Samsung Electronics.
   8 * Written by:
   9 *      Marek Szyprowski <m.szyprowski@samsung.com>
  10 *      Michal Nazarewicz <mina86@mina86.com>
  11 */
  12
  13/*
  14 * Contiguous Memory Allocator
  15 *
  16 *   The Contiguous Memory Allocator (CMA) makes it possible to
  17 *   allocate big contiguous chunks of memory after the system has
  18 *   booted.
  19 *
  20 * Why is it needed?
  21 *
  22 *   Various devices on embedded systems have no scatter-getter and/or
  23 *   IO map support and require contiguous blocks of memory to
  24 *   operate.  They include devices such as cameras, hardware video
  25 *   coders, etc.
  26 *
  27 *   Such devices often require big memory buffers (a full HD frame
  28 *   is, for instance, more then 2 mega pixels large, i.e. more than 6
  29 *   MB of memory), which makes mechanisms such as kmalloc() or
  30 *   alloc_page() ineffective.
  31 *
  32 *   At the same time, a solution where a big memory region is
  33 *   reserved for a device is suboptimal since often more memory is
  34 *   reserved then strictly required and, moreover, the memory is
  35 *   inaccessible to page system even if device drivers don't use it.
  36 *
  37 *   CMA tries to solve this issue by operating on memory regions
  38 *   where only movable pages can be allocated from.  This way, kernel
  39 *   can use the memory for pagecache and when device driver requests
  40 *   it, allocated pages can be migrated.
  41 *
  42 * Driver usage
  43 *
  44 *   CMA should not be used by the device drivers directly. It is
  45 *   only a helper framework for dma-mapping subsystem.
  46 *
  47 *   For more information, see kernel-docs in kernel/dma/contiguous.c
  48 */
  49
  50#ifdef __KERNEL__
  51
  52#include <linux/device.h>
  53#include <linux/mm.h>
  54
  55struct cma;
  56struct page;
  57
  58#ifdef CONFIG_DMA_CMA
  59
  60extern struct cma *dma_contiguous_default_area;
  61
  62static inline struct cma *dev_get_cma_area(struct device *dev)
  63{
  64        if (dev && dev->cma_area)
  65                return dev->cma_area;
  66        return dma_contiguous_default_area;
  67}
  68
  69static inline void dev_set_cma_area(struct device *dev, struct cma *cma)
  70{
  71        if (dev)
  72                dev->cma_area = cma;
  73}
  74
  75static inline void dma_contiguous_set_default(struct cma *cma)
  76{
  77        dma_contiguous_default_area = cma;
  78}
  79
  80void dma_contiguous_reserve(phys_addr_t addr_limit);
  81
  82int __init dma_contiguous_reserve_area(phys_addr_t size, phys_addr_t base,
  83                                       phys_addr_t limit, struct cma **res_cma,
  84                                       bool fixed);
  85
  86/**
  87 * dma_declare_contiguous() - reserve area for contiguous memory handling
  88 *                            for particular device
  89 * @dev:   Pointer to device structure.
  90 * @size:  Size of the reserved memory.
  91 * @base:  Start address of the reserved memory (optional, 0 for any).
  92 * @limit: End address of the reserved memory (optional, 0 for any).
  93 *
  94 * This function reserves memory for specified device. It should be
  95 * called by board specific code when early allocator (memblock or bootmem)
  96 * is still activate.
  97 */
  98
  99static inline int dma_declare_contiguous(struct device *dev, phys_addr_t size,
 100                                         phys_addr_t base, phys_addr_t limit)
 101{
 102        struct cma *cma;
 103        int ret;
 104        ret = dma_contiguous_reserve_area(size, base, limit, &cma, true);
 105        if (ret == 0)
 106                dev_set_cma_area(dev, cma);
 107
 108        return ret;
 109}
 110
 111struct page *dma_alloc_from_contiguous(struct device *dev, size_t count,
 112                                       unsigned int order, bool no_warn);
 113bool dma_release_from_contiguous(struct device *dev, struct page *pages,
 114                                 int count);
 115struct page *dma_alloc_contiguous(struct device *dev, size_t size, gfp_t gfp);
 116void dma_free_contiguous(struct device *dev, struct page *page, size_t size);
 117
 118#else
 119
 120static inline struct cma *dev_get_cma_area(struct device *dev)
 121{
 122        return NULL;
 123}
 124
 125static inline void dev_set_cma_area(struct device *dev, struct cma *cma) { }
 126
 127static inline void dma_contiguous_set_default(struct cma *cma) { }
 128
 129static inline void dma_contiguous_reserve(phys_addr_t limit) { }
 130
 131static inline int dma_contiguous_reserve_area(phys_addr_t size, phys_addr_t base,
 132                                       phys_addr_t limit, struct cma **res_cma,
 133                                       bool fixed)
 134{
 135        return -ENOSYS;
 136}
 137
 138static inline
 139int dma_declare_contiguous(struct device *dev, phys_addr_t size,
 140                           phys_addr_t base, phys_addr_t limit)
 141{
 142        return -ENOSYS;
 143}
 144
 145static inline
 146struct page *dma_alloc_from_contiguous(struct device *dev, size_t count,
 147                                       unsigned int order, bool no_warn)
 148{
 149        return NULL;
 150}
 151
 152static inline
 153bool dma_release_from_contiguous(struct device *dev, struct page *pages,
 154                                 int count)
 155{
 156        return false;
 157}
 158
 159/* Use fallback alloc() and free() when CONFIG_DMA_CMA=n */
 160static inline struct page *dma_alloc_contiguous(struct device *dev, size_t size,
 161                gfp_t gfp)
 162{
 163        return NULL;
 164}
 165
 166static inline void dma_free_contiguous(struct device *dev, struct page *page,
 167                size_t size)
 168{
 169        __free_pages(page, get_order(size));
 170}
 171
 172#endif
 173
 174#endif
 175
 176#endif
 177