• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /**************************************************************************
2  *
3  * Copyright 2007 VMware, Inc.
4  * All Rights Reserved.
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a
7  * copy of this software and associated documentation files (the
8  * "Software"), to deal in the Software without restriction, including
9  * without limitation the rights to use, copy, modify, merge, publish,
10  * distribute, sub license, and/or sell copies of the Software, and to
11  * permit persons to whom the Software is furnished to do so, subject to
12  * the following conditions:
13  *
14  * The above copyright notice and this permission notice (including the
15  * next paragraph) shall be included in all copies or substantial portions
16  * of the Software.
17  *
18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
19  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
21  * IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR
22  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
23  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
24  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
25  *
26  **************************************************************************/
27 
28 /**
29  * \file
30  * Buffer management.
31  *
32  * A buffer manager does only one basic thing: it creates buffers. Actually,
33  * "buffer factory" would probably a more accurate description.
34  *
35  * You can chain buffer managers so that you can have a finer grained memory
36  * management and pooling.
37  *
38  * For example, for a simple batch buffer manager you would chain:
39  * - the native buffer manager, which provides DMA memory from the graphics
40  * memory space;
41  * - the pool buffer manager, which keep around a pool of equally sized buffers
42  * to avoid latency associated with the native buffer manager;
43  * - the fenced buffer manager, which will delay buffer destruction until the
44  * the moment the card finishing processing it.
45  *
46  * \author Jose Fonseca <jfonseca@vmware.com>
47  */
48 
49 #ifndef PB_BUFMGR_H_
50 #define PB_BUFMGR_H_
51 
52 
53 #include "pb_buffer.h"
54 
55 
56 #ifdef __cplusplus
57 extern "C" {
58 #endif
59 
60 
61 struct pb_desc;
62 
63 
64 /**
65  * Abstract base class for all buffer managers.
66  */
67 struct pb_manager
68 {
69    void
70    (*destroy)( struct pb_manager *mgr );
71 
72    struct pb_buffer *
73    (*create_buffer)( struct pb_manager *mgr,
74 	             pb_size size,
75 	             const struct pb_desc *desc);
76 
77    /**
78     * Flush all temporary-held buffers.
79     *
80     * Used mostly to aid debugging memory issues or to clean up resources when
81     * the drivers are long lived.
82     */
83    void
84    (*flush)( struct pb_manager *mgr );
85 
86    boolean
87    (*is_buffer_busy)( struct pb_manager *mgr,
88                       struct pb_buffer *buf );
89 };
90 
91 
92 /**
93  * Malloc buffer provider.
94  *
95  * Simple wrapper around pb_malloc_buffer_create for convenience.
96  */
97 struct pb_manager *
98 pb_malloc_bufmgr_create(void);
99 
100 
101 /**
102  * Static buffer pool sub-allocator.
103  *
104  * Manages the allocation of equally sized buffers. It does so by allocating
105  * a single big buffer and divide it equally sized buffers.
106  *
107  * It is meant to manage the allocation of batch buffer pools.
108  */
109 struct pb_manager *
110 pool_bufmgr_create(struct pb_manager *provider,
111                    pb_size n, pb_size size,
112                    const struct pb_desc *desc);
113 
114 
115 /**
116  * Static sub-allocator based the old memory manager.
117  *
118  * It managers buffers of different sizes. It does so by allocating a buffer
119  * with the size of the heap, and then using the old mm memory manager to manage
120  * that heap.
121  */
122 struct pb_manager *
123 mm_bufmgr_create(struct pb_manager *provider,
124                  pb_size size, pb_size align2);
125 
126 /**
127  * Same as mm_bufmgr_create.
128  *
129  * Buffer will be release when the manager is destroyed.
130  */
131 struct pb_manager *
132 mm_bufmgr_create_from_buffer(struct pb_buffer *buffer,
133                              pb_size size, pb_size align2);
134 
135 
136 /**
137  * Slab sub-allocator.
138  */
139 struct pb_manager *
140 pb_slab_manager_create(struct pb_manager *provider,
141                        pb_size bufSize,
142                        pb_size slabSize,
143                        const struct pb_desc *desc);
144 
145 /**
146  * Allow a range of buffer size, by aggregating multiple slabs sub-allocators
147  * with different bucket sizes.
148  */
149 struct pb_manager *
150 pb_slab_range_manager_create(struct pb_manager *provider,
151                              pb_size minBufSize,
152                              pb_size maxBufSize,
153                              pb_size slabSize,
154                              const struct pb_desc *desc);
155 
156 
157 /**
158  * Time-based buffer cache.
159  *
160  * This manager keeps a cache of destroyed buffers during a time interval.
161  */
162 struct pb_manager *
163 pb_cache_manager_create(struct pb_manager *provider,
164                         unsigned usecs,
165                         float size_factor,
166                         unsigned bypass_usage,
167                         uint64_t maximum_cache_size);
168 
169 /**
170  * Remove a buffer from the cache, but keep it alive.
171  */
172 void
173 pb_cache_manager_remove_buffer(struct pb_buffer *buf);
174 
175 struct pb_fence_ops;
176 
177 /**
178  * Fenced buffer manager.
179  *
180  * This manager is just meant for convenience. It wraps the buffers returned
181  * by another manager in fenced buffers, so that
182  *
183  * NOTE: the buffer manager that provides the buffers will be destroyed
184  * at the same time.
185  */
186 struct pb_manager *
187 fenced_bufmgr_create(struct pb_manager *provider,
188                      struct pb_fence_ops *ops,
189                      pb_size max_buffer_size,
190                      pb_size max_cpu_total_size);
191 
192 
193 struct pb_manager *
194 pb_alt_manager_create(struct pb_manager *provider1,
195                       struct pb_manager *provider2);
196 
197 
198 /**
199  * Ondemand buffer manager.
200  *
201  * Buffers are created in malloc'ed memory (fast and cached), and the constents
202  * is transfered to a buffer from the provider (typically in slow uncached
203  * memory) when there is an attempt to validate the buffer.
204  *
205  * Ideal for situations where one does not know before hand whether a given
206  * buffer will effectively be used by the hardware or not.
207  */
208 struct pb_manager *
209 pb_ondemand_manager_create(struct pb_manager *provider);
210 
211 
212 /**
213  * Debug buffer manager to detect buffer under- and overflows.
214  *
215  * Under/overflow sizes should be a multiple of the largest alignment
216  */
217 struct pb_manager *
218 pb_debug_manager_create(struct pb_manager *provider,
219                         pb_size underflow_size, pb_size overflow_size);
220 
221 
222 #ifdef __cplusplus
223 }
224 #endif
225 
226 #endif /*PB_BUFMGR_H_*/
227