drivers: add Contiguous Memory Allocator
[linux-2.6.git] / include / linux / dma-contiguous.h
1 #ifndef __LINUX_CMA_H
2 #define __LINUX_CMA_H
3
4 /*
5  * Contiguous Memory Allocator for DMA mapping framework
6  * Copyright (c) 2010-2011 by Samsung Electronics.
7  * Written by:
8  *      Marek Szyprowski <m.szyprowski@samsung.com>
9  *      Michal Nazarewicz <mina86@mina86.com>
10  *
11  * This program is free software; you can redistribute it and/or
12  * modify it under the terms of the GNU General Public License as
13  * published by the Free Software Foundation; either version 2 of the
14  * License or (at your optional) any later version of the license.
15  */
16
17 /*
18  * Contiguous Memory Allocator
19  *
20  *   The Contiguous Memory Allocator (CMA) makes it possible to
21  *   allocate big contiguous chunks of memory after the system has
22  *   booted.
23  *
24  * Why is it needed?
25  *
26  *   Various devices on embedded systems have no scatter-getter and/or
27  *   IO map support and require contiguous blocks of memory to
28  *   operate.  They include devices such as cameras, hardware video
29  *   coders, etc.
30  *
31  *   Such devices often require big memory buffers (a full HD frame
32  *   is, for instance, more then 2 mega pixels large, i.e. more than 6
33  *   MB of memory), which makes mechanisms such as kmalloc() or
34  *   alloc_page() ineffective.
35  *
36  *   At the same time, a solution where a big memory region is
37  *   reserved for a device is suboptimal since often more memory is
38  *   reserved then strictly required and, moreover, the memory is
39  *   inaccessible to page system even if device drivers don't use it.
40  *
41  *   CMA tries to solve this issue by operating on memory regions
42  *   where only movable pages can be allocated from.  This way, kernel
43  *   can use the memory for pagecache and when device driver requests
44  *   it, allocated pages can be migrated.
45  *
46  * Driver usage
47  *
48  *   CMA should not be used by the device drivers directly. It is
49  *   only a helper framework for dma-mapping subsystem.
50  *
51  *   For more information, see kernel-docs in drivers/base/dma-contiguous.c
52  */
53
54 #ifdef __KERNEL__
55
56 struct cma;
57 struct page;
58 struct device;
59
60 #ifdef CONFIG_CMA
61
62 /*
63  * There is always at least global CMA area and a few optional device
64  * private areas configured in kernel .config.
65  */
66 #define MAX_CMA_AREAS   (1 + CONFIG_CMA_AREAS)
67
68 extern struct cma *dma_contiguous_default_area;
69
70 void dma_contiguous_reserve(phys_addr_t addr_limit);
71 int dma_declare_contiguous(struct device *dev, unsigned long size,
72                            phys_addr_t base, phys_addr_t limit);
73
74 struct page *dma_alloc_from_contiguous(struct device *dev, int count,
75                                        unsigned int order);
76 bool dma_release_from_contiguous(struct device *dev, struct page *pages,
77                                  int count);
78
79 #else
80
81 #define MAX_CMA_AREAS   (0)
82
83 static inline void dma_contiguous_reserve(phys_addr_t limit) { }
84
85 static inline
86 int dma_declare_contiguous(struct device *dev, unsigned long size,
87                            phys_addr_t base, phys_addr_t limit)
88 {
89         return -ENOSYS;
90 }
91
92 static inline
93 struct page *dma_alloc_from_contiguous(struct device *dev, int count,
94                                        unsigned int order)
95 {
96         return NULL;
97 }
98
99 static inline
100 bool dma_release_from_contiguous(struct device *dev, struct page *pages,
101                                  int count)
102 {
103         return false;
104 }
105
106 #endif
107
108 #endif
109
110 #endif