Commit | Line | Data |
---|---|---|
6280238c ORL |
1 | /* |
2 | * cmm.h | |
3 | * | |
4 | * DSP-BIOS Bridge driver support functions for TI OMAP processors. | |
5 | * | |
6 | * The Communication Memory Management(CMM) module provides shared memory | |
7 | * management services for DSP/BIOS Bridge data streaming and messaging. | |
8 | * Multiple shared memory segments can be registered with CMM. Memory is | |
9 | * coelesced back to the appropriate pool when a buffer is freed. | |
10 | * | |
11 | * The CMM_Xlator[xxx] functions are used for node messaging and data | |
12 | * streaming address translation to perform zero-copy inter-processor | |
13 | * data transfer(GPP<->DSP). A "translator" object is created for a node or | |
14 | * stream object that contains per thread virtual address information. This | |
15 | * translator info is used at runtime to perform SM address translation | |
16 | * to/from the DSP address space. | |
17 | * | |
18 | * Notes: | |
19 | * cmm_xlator_alloc_buf - Used by Node and Stream modules for SM address | |
20 | * translation. | |
21 | * | |
22 | * Copyright (C) 2008 Texas Instruments, Inc. | |
23 | * | |
24 | * This package is free software; you can redistribute it and/or modify | |
25 | * it under the terms of the GNU General Public License version 2 as | |
26 | * published by the Free Software Foundation. | |
27 | * | |
28 | * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR | |
29 | * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED | |
30 | * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. | |
31 | */ | |
32 | ||
33 | #ifndef CMM_ | |
34 | #define CMM_ | |
35 | ||
36 | #include <dspbridge/devdefs.h> | |
37 | ||
38 | #include <dspbridge/cmmdefs.h> | |
39 | #include <dspbridge/host_os.h> | |
40 | ||
41 | /* | |
42 | * ======== cmm_calloc_buf ======== | |
43 | * Purpose: | |
44 | * Allocate memory buffers that can be used for data streaming or | |
45 | * messaging. | |
46 | * Parameters: | |
47 | * hcmm_mgr: Cmm Mgr handle. | |
48 | * usize: Number of bytes to allocate. | |
49 | * pattr: Attributes of memory to allocate. | |
50 | * pp_buf_va: Address of where to place VA. | |
51 | * Returns: | |
52 | * Pointer to a zero'd block of SM memory; | |
53 | * NULL if memory couldn't be allocated, | |
54 | * or if byte_size == 0, | |
55 | * Requires: | |
56 | * Valid hcmm_mgr. | |
57 | * CMM initialized. | |
58 | * Ensures: | |
59 | * The returned pointer, if not NULL, points to a valid memory block of | |
60 | * the size requested. | |
61 | * | |
62 | */ | |
63 | extern void *cmm_calloc_buf(struct cmm_object *hcmm_mgr, | |
64 | u32 usize, struct cmm_attrs *pattrs, | |
e6bf74f0 | 65 | void **pp_buf_va); |
6280238c ORL |
66 | |
67 | /* | |
68 | * ======== cmm_create ======== | |
69 | * Purpose: | |
70 | * Create a communication memory manager object. | |
71 | * Parameters: | |
72 | * ph_cmm_mgr: Location to store a communication manager handle on | |
73 | * output. | |
74 | * hdev_obj: Handle to a device object. | |
fb6aabb7 | 75 | * mgr_attrts: Comm mem manager attributes. |
6280238c ORL |
76 | * Returns: |
77 | * 0: Success; | |
78 | * -ENOMEM: Insufficient memory for requested resources. | |
79 | * -EPERM: Failed to initialize critical sect sync object. | |
80 | * | |
81 | * Requires: | |
82 | * cmm_init(void) called. | |
83 | * ph_cmm_mgr != NULL. | |
6c66e948 | 84 | * mgr_attrts->min_block_size >= 4 bytes. |
6280238c ORL |
85 | * Ensures: |
86 | * | |
87 | */ | |
e6bf74f0 | 88 | extern int cmm_create(struct cmm_object **ph_cmm_mgr, |
6280238c | 89 | struct dev_object *hdev_obj, |
9d7d0a52 | 90 | const struct cmm_mgrattrs *mgr_attrts); |
6280238c ORL |
91 | |
92 | /* | |
93 | * ======== cmm_destroy ======== | |
94 | * Purpose: | |
95 | * Destroy the communication memory manager object. | |
96 | * Parameters: | |
97 | * hcmm_mgr: Cmm Mgr handle. | |
a6bff488 | 98 | * force: Force deallocation of all cmm memory immediately if set TRUE. |
6280238c ORL |
99 | * If FALSE, and outstanding allocations will return -EPERM |
100 | * status. | |
101 | * Returns: | |
102 | * 0: CMM object & resources deleted. | |
103 | * -EPERM: Unable to free CMM object due to outstanding allocation. | |
104 | * -EFAULT: Unable to free CMM due to bad handle. | |
105 | * Requires: | |
106 | * CMM is initialized. | |
107 | * hcmm_mgr != NULL. | |
108 | * Ensures: | |
109 | * Memory resources used by Cmm Mgr are freed. | |
110 | */ | |
a6bff488 | 111 | extern int cmm_destroy(struct cmm_object *hcmm_mgr, bool force); |
6280238c ORL |
112 | |
113 | /* | |
114 | * ======== cmm_exit ======== | |
115 | * Purpose: | |
116 | * Discontinue usage of module. Cleanup CMM module if CMM cRef reaches zero. | |
117 | * Parameters: | |
118 | * n/a | |
119 | * Returns: | |
120 | * n/a | |
121 | * Requires: | |
122 | * CMM is initialized. | |
123 | * Ensures: | |
124 | */ | |
125 | extern void cmm_exit(void); | |
126 | ||
127 | /* | |
128 | * ======== cmm_free_buf ======== | |
129 | * Purpose: | |
130 | * Free the given buffer. | |
131 | * Parameters: | |
132 | * hcmm_mgr: Cmm Mgr handle. | |
133 | * pbuf: Pointer to memory allocated by cmm_calloc_buf(). | |
134 | * ul_seg_id: SM segment Id used in CMM_Calloc() attrs. | |
135 | * Set to 0 to use default segment. | |
136 | * Returns: | |
137 | * 0 | |
138 | * -EPERM | |
139 | * Requires: | |
140 | * CMM initialized. | |
141 | * buf_pa != NULL | |
142 | * Ensures: | |
143 | * | |
144 | */ | |
145 | extern int cmm_free_buf(struct cmm_object *hcmm_mgr, | |
146 | void *buf_pa, u32 ul_seg_id); | |
147 | ||
148 | /* | |
149 | * ======== cmm_get_handle ======== | |
150 | * Purpose: | |
151 | * Return the handle to the cmm mgr for the given device obj. | |
152 | * Parameters: | |
153 | * hprocessor: Handle to a Processor. | |
154 | * ph_cmm_mgr: Location to store the shared memory mgr handle on | |
155 | * output. | |
156 | * | |
157 | * Returns: | |
158 | * 0: Cmm Mgr opaque handle returned. | |
159 | * -EFAULT: Invalid handle. | |
160 | * Requires: | |
161 | * ph_cmm_mgr != NULL | |
162 | * hdev_obj != NULL | |
163 | * Ensures: | |
164 | */ | |
165 | extern int cmm_get_handle(void *hprocessor, | |
e6bf74f0 | 166 | struct cmm_object **ph_cmm_mgr); |
6280238c ORL |
167 | |
168 | /* | |
169 | * ======== cmm_get_info ======== | |
170 | * Purpose: | |
171 | * Return the current SM and VM utilization information. | |
172 | * Parameters: | |
173 | * hcmm_mgr: Handle to a Cmm Mgr. | |
174 | * cmm_info_obj: Location to store the Cmm information on output. | |
175 | * | |
176 | * Returns: | |
177 | * 0: Success. | |
178 | * -EFAULT: Invalid handle. | |
179 | * -EINVAL Invalid input argument. | |
180 | * Requires: | |
181 | * Ensures: | |
182 | * | |
183 | */ | |
184 | extern int cmm_get_info(struct cmm_object *hcmm_mgr, | |
e6bf74f0 | 185 | struct cmm_info *cmm_info_obj); |
6280238c ORL |
186 | |
187 | /* | |
188 | * ======== cmm_init ======== | |
189 | * Purpose: | |
190 | * Initializes private state of CMM module. | |
191 | * Parameters: | |
192 | * Returns: | |
25985edc | 193 | * TRUE if initialized; FALSE if error occurred. |
6280238c ORL |
194 | * Requires: |
195 | * Ensures: | |
196 | * CMM initialized. | |
197 | */ | |
198 | extern bool cmm_init(void); | |
199 | ||
200 | /* | |
201 | * ======== cmm_register_gppsm_seg ======== | |
202 | * Purpose: | |
203 | * Register a block of SM with the CMM. | |
204 | * Parameters: | |
205 | * hcmm_mgr: Handle to a Cmm Mgr. | |
206 | * lpGPPBasePA: GPP Base Physical address. | |
207 | * ul_size: Size in GPP bytes. | |
b301c858 | 208 | * dsp_addr_offset GPP PA to DSP PA Offset. |
6280238c ORL |
209 | * c_factor: Add offset if CMM_ADDTODSPPA, sub if CMM_SUBFROMDSPPA. |
210 | * dw_dsp_base: DSP virtual base byte address. | |
211 | * ul_dsp_size: Size of DSP segment in bytes. | |
318b5df9 | 212 | * sgmt_id: Address to store segment Id. |
6280238c ORL |
213 | * |
214 | * Returns: | |
215 | * 0: Success. | |
216 | * -EFAULT: Invalid hcmm_mgr handle. | |
217 | * -EINVAL: Invalid input argument. | |
218 | * -EPERM: Unable to register. | |
318b5df9 | 219 | * - On success *sgmt_id is a valid SM segment ID. |
6280238c ORL |
220 | * Requires: |
221 | * ul_size > 0 | |
318b5df9 | 222 | * sgmt_id != NULL |
6280238c ORL |
223 | * dw_gpp_base_pa != 0 |
224 | * c_factor = CMM_ADDTODSPPA || c_factor = CMM_SUBFROMDSPPA | |
225 | * Ensures: | |
226 | * | |
227 | */ | |
228 | extern int cmm_register_gppsm_seg(struct cmm_object *hcmm_mgr, | |
229 | unsigned int dw_gpp_base_pa, | |
230 | u32 ul_size, | |
b301c858 | 231 | u32 dsp_addr_offset, |
6280238c ORL |
232 | s8 c_factor, |
233 | unsigned int dw_dsp_base, | |
234 | u32 ul_dsp_size, | |
c8c1ad8c | 235 | u32 *sgmt_id, u32 gpp_base_va); |
6280238c ORL |
236 | |
237 | /* | |
238 | * ======== cmm_un_register_gppsm_seg ======== | |
239 | * Purpose: | |
240 | * Unregister the given memory segment that was previously registered | |
241 | * by cmm_register_gppsm_seg. | |
242 | * Parameters: | |
243 | * hcmm_mgr: Handle to a Cmm Mgr. | |
244 | * ul_seg_id Segment identifier returned by cmm_register_gppsm_seg. | |
245 | * Returns: | |
246 | * 0: Success. | |
247 | * -EFAULT: Invalid handle. | |
248 | * -EINVAL: Invalid ul_seg_id. | |
249 | * -EPERM: Unable to unregister for unknown reason. | |
250 | * Requires: | |
251 | * Ensures: | |
252 | * | |
253 | */ | |
254 | extern int cmm_un_register_gppsm_seg(struct cmm_object *hcmm_mgr, | |
255 | u32 ul_seg_id); | |
256 | ||
257 | /* | |
258 | * ======== cmm_xlator_alloc_buf ======== | |
259 | * Purpose: | |
260 | * Allocate the specified SM buffer and create a local memory descriptor. | |
261 | * Place on the descriptor on the translator's HaQ (Host Alloc'd Queue). | |
262 | * Parameters: | |
263 | * xlator: Handle to a Xlator object. | |
318b5df9 | 264 | * va_buf: Virtual address ptr(client context) |
5e2eae57 | 265 | * pa_size: Size of SM memory to allocate. |
6280238c | 266 | * Returns: |
5e2eae57 | 267 | * Ptr to valid physical address(Pa) of pa_size bytes, NULL if failed. |
6280238c | 268 | * Requires: |
318b5df9 | 269 | * va_buf != 0. |
5e2eae57 | 270 | * pa_size != 0. |
6280238c ORL |
271 | * Ensures: |
272 | * | |
273 | */ | |
274 | extern void *cmm_xlator_alloc_buf(struct cmm_xlatorobject *xlator, | |
5e2eae57 | 275 | void *va_buf, u32 pa_size); |
6280238c ORL |
276 | |
277 | /* | |
278 | * ======== cmm_xlator_create ======== | |
279 | * Purpose: | |
280 | * Create a translator(xlator) object used for process specific Va<->Pa | |
281 | * address translation. Node messaging and streams use this to perform | |
282 | * inter-processor(GPP<->DSP) zero-copy data transfer. | |
283 | * Parameters: | |
daa89e6c | 284 | * xlator: Address to place handle to a new Xlator handle. |
6280238c | 285 | * hcmm_mgr: Handle to Cmm Mgr associated with this translator. |
318b5df9 | 286 | * xlator_attrs: Translator attributes used for the client NODE or STREAM. |
6280238c ORL |
287 | * Returns: |
288 | * 0: Success. | |
289 | * -EINVAL: Bad input Attrs. | |
290 | * -ENOMEM: Insufficient memory(local) for requested resources. | |
291 | * Requires: | |
daa89e6c | 292 | * xlator != NULL |
6280238c | 293 | * hcmm_mgr != NULL |
318b5df9 | 294 | * xlator_attrs != NULL |
6280238c ORL |
295 | * Ensures: |
296 | * | |
297 | */ | |
e6bf74f0 | 298 | extern int cmm_xlator_create(struct cmm_xlatorobject **xlator, |
6280238c | 299 | struct cmm_object *hcmm_mgr, |
318b5df9 | 300 | struct cmm_xlatorattrs *xlator_attrs); |
6280238c | 301 | |
6280238c ORL |
302 | /* |
303 | * ======== cmm_xlator_free_buf ======== | |
304 | * Purpose: | |
305 | * Free SM buffer and descriptor. | |
306 | * Does not free client process VM. | |
307 | * Parameters: | |
308 | * xlator: handle to translator. | |
aa09b091 | 309 | * buf_va Virtual address of PA to free. |
6280238c ORL |
310 | * Returns: |
311 | * 0: Success. | |
312 | * -EFAULT: Bad translator handle. | |
313 | * Requires: | |
314 | * Ensures: | |
315 | * | |
316 | */ | |
317 | extern int cmm_xlator_free_buf(struct cmm_xlatorobject *xlator, | |
aa09b091 | 318 | void *buf_va); |
6280238c ORL |
319 | |
320 | /* | |
321 | * ======== cmm_xlator_info ======== | |
322 | * Purpose: | |
323 | * Set/Get process specific "translator" address info. | |
324 | * This is used to perform fast virtaul address translation | |
325 | * for shared memory buffers between the GPP and DSP. | |
326 | * Parameters: | |
327 | * xlator: handle to translator. | |
328 | * paddr: Virtual base address of segment. | |
329 | * ul_size: Size in bytes. | |
5e2eae57 | 330 | * segm_id: Segment identifier of SM segment(s) |
6280238c ORL |
331 | * set_info Set xlator fields if TRUE, else return base addr |
332 | * Returns: | |
333 | * 0: Success. | |
334 | * -EFAULT: Bad translator handle. | |
335 | * Requires: | |
336 | * (refs > 0) | |
337 | * (paddr != NULL) | |
338 | * (ul_size > 0) | |
339 | * Ensures: | |
340 | * | |
341 | */ | |
342 | extern int cmm_xlator_info(struct cmm_xlatorobject *xlator, | |
e6bf74f0 | 343 | u8 **paddr, |
5e2eae57 | 344 | u32 ul_size, u32 segm_id, bool set_info); |
6280238c ORL |
345 | |
346 | /* | |
347 | * ======== cmm_xlator_translate ======== | |
348 | * Purpose: | |
349 | * Perform address translation VA<->PA for the specified stream or | |
350 | * message shared memory buffer. | |
351 | * Parameters: | |
352 | * xlator: handle to translator. | |
353 | * paddr address of buffer to translate. | |
5a09ddea | 354 | * xtype Type of address xlation. CMM_PA2VA or CMM_VA2PA. |
6280238c ORL |
355 | * Returns: |
356 | * Valid address on success, else NULL. | |
357 | * Requires: | |
358 | * refs > 0 | |
359 | * paddr != NULL | |
5a09ddea | 360 | * xtype >= CMM_VA2PA) && (xtype <= CMM_DSPPA2PA) |
6280238c ORL |
361 | * Ensures: |
362 | * | |
363 | */ | |
364 | extern void *cmm_xlator_translate(struct cmm_xlatorobject *xlator, | |
5a09ddea | 365 | void *paddr, enum cmm_xlatetype xtype); |
6280238c ORL |
366 | |
367 | #endif /* CMM_ */ |