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: | |
6280238c | 82 | * ph_cmm_mgr != NULL. |
6c66e948 | 83 | * mgr_attrts->min_block_size >= 4 bytes. |
6280238c ORL |
84 | * Ensures: |
85 | * | |
86 | */ | |
e6bf74f0 | 87 | extern int cmm_create(struct cmm_object **ph_cmm_mgr, |
6280238c | 88 | struct dev_object *hdev_obj, |
9d7d0a52 | 89 | const struct cmm_mgrattrs *mgr_attrts); |
6280238c ORL |
90 | |
91 | /* | |
92 | * ======== cmm_destroy ======== | |
93 | * Purpose: | |
94 | * Destroy the communication memory manager object. | |
95 | * Parameters: | |
96 | * hcmm_mgr: Cmm Mgr handle. | |
a6bff488 | 97 | * force: Force deallocation of all cmm memory immediately if set TRUE. |
6280238c ORL |
98 | * If FALSE, and outstanding allocations will return -EPERM |
99 | * status. | |
100 | * Returns: | |
101 | * 0: CMM object & resources deleted. | |
102 | * -EPERM: Unable to free CMM object due to outstanding allocation. | |
103 | * -EFAULT: Unable to free CMM due to bad handle. | |
104 | * Requires: | |
105 | * CMM is initialized. | |
106 | * hcmm_mgr != NULL. | |
107 | * Ensures: | |
108 | * Memory resources used by Cmm Mgr are freed. | |
109 | */ | |
a6bff488 | 110 | extern int cmm_destroy(struct cmm_object *hcmm_mgr, bool force); |
6280238c | 111 | |
6280238c ORL |
112 | /* |
113 | * ======== cmm_free_buf ======== | |
114 | * Purpose: | |
115 | * Free the given buffer. | |
116 | * Parameters: | |
117 | * hcmm_mgr: Cmm Mgr handle. | |
118 | * pbuf: Pointer to memory allocated by cmm_calloc_buf(). | |
119 | * ul_seg_id: SM segment Id used in CMM_Calloc() attrs. | |
120 | * Set to 0 to use default segment. | |
121 | * Returns: | |
122 | * 0 | |
123 | * -EPERM | |
124 | * Requires: | |
125 | * CMM initialized. | |
126 | * buf_pa != NULL | |
127 | * Ensures: | |
128 | * | |
129 | */ | |
130 | extern int cmm_free_buf(struct cmm_object *hcmm_mgr, | |
131 | void *buf_pa, u32 ul_seg_id); | |
132 | ||
133 | /* | |
134 | * ======== cmm_get_handle ======== | |
135 | * Purpose: | |
136 | * Return the handle to the cmm mgr for the given device obj. | |
137 | * Parameters: | |
138 | * hprocessor: Handle to a Processor. | |
139 | * ph_cmm_mgr: Location to store the shared memory mgr handle on | |
140 | * output. | |
141 | * | |
142 | * Returns: | |
143 | * 0: Cmm Mgr opaque handle returned. | |
144 | * -EFAULT: Invalid handle. | |
145 | * Requires: | |
146 | * ph_cmm_mgr != NULL | |
147 | * hdev_obj != NULL | |
148 | * Ensures: | |
149 | */ | |
150 | extern int cmm_get_handle(void *hprocessor, | |
e6bf74f0 | 151 | struct cmm_object **ph_cmm_mgr); |
6280238c ORL |
152 | |
153 | /* | |
154 | * ======== cmm_get_info ======== | |
155 | * Purpose: | |
156 | * Return the current SM and VM utilization information. | |
157 | * Parameters: | |
158 | * hcmm_mgr: Handle to a Cmm Mgr. | |
159 | * cmm_info_obj: Location to store the Cmm information on output. | |
160 | * | |
161 | * Returns: | |
162 | * 0: Success. | |
163 | * -EFAULT: Invalid handle. | |
164 | * -EINVAL Invalid input argument. | |
165 | * Requires: | |
166 | * Ensures: | |
167 | * | |
168 | */ | |
169 | extern int cmm_get_info(struct cmm_object *hcmm_mgr, | |
e6bf74f0 | 170 | struct cmm_info *cmm_info_obj); |
6280238c | 171 | |
6280238c ORL |
172 | /* |
173 | * ======== cmm_register_gppsm_seg ======== | |
174 | * Purpose: | |
175 | * Register a block of SM with the CMM. | |
176 | * Parameters: | |
177 | * hcmm_mgr: Handle to a Cmm Mgr. | |
178 | * lpGPPBasePA: GPP Base Physical address. | |
179 | * ul_size: Size in GPP bytes. | |
b301c858 | 180 | * dsp_addr_offset GPP PA to DSP PA Offset. |
6280238c ORL |
181 | * c_factor: Add offset if CMM_ADDTODSPPA, sub if CMM_SUBFROMDSPPA. |
182 | * dw_dsp_base: DSP virtual base byte address. | |
183 | * ul_dsp_size: Size of DSP segment in bytes. | |
318b5df9 | 184 | * sgmt_id: Address to store segment Id. |
6280238c ORL |
185 | * |
186 | * Returns: | |
187 | * 0: Success. | |
188 | * -EFAULT: Invalid hcmm_mgr handle. | |
189 | * -EINVAL: Invalid input argument. | |
190 | * -EPERM: Unable to register. | |
318b5df9 | 191 | * - On success *sgmt_id is a valid SM segment ID. |
6280238c ORL |
192 | * Requires: |
193 | * ul_size > 0 | |
318b5df9 | 194 | * sgmt_id != NULL |
6280238c ORL |
195 | * dw_gpp_base_pa != 0 |
196 | * c_factor = CMM_ADDTODSPPA || c_factor = CMM_SUBFROMDSPPA | |
197 | * Ensures: | |
198 | * | |
199 | */ | |
200 | extern int cmm_register_gppsm_seg(struct cmm_object *hcmm_mgr, | |
201 | unsigned int dw_gpp_base_pa, | |
202 | u32 ul_size, | |
b301c858 | 203 | u32 dsp_addr_offset, |
6280238c ORL |
204 | s8 c_factor, |
205 | unsigned int dw_dsp_base, | |
206 | u32 ul_dsp_size, | |
c8c1ad8c | 207 | u32 *sgmt_id, u32 gpp_base_va); |
6280238c ORL |
208 | |
209 | /* | |
210 | * ======== cmm_un_register_gppsm_seg ======== | |
211 | * Purpose: | |
212 | * Unregister the given memory segment that was previously registered | |
213 | * by cmm_register_gppsm_seg. | |
214 | * Parameters: | |
215 | * hcmm_mgr: Handle to a Cmm Mgr. | |
216 | * ul_seg_id Segment identifier returned by cmm_register_gppsm_seg. | |
217 | * Returns: | |
218 | * 0: Success. | |
219 | * -EFAULT: Invalid handle. | |
220 | * -EINVAL: Invalid ul_seg_id. | |
221 | * -EPERM: Unable to unregister for unknown reason. | |
222 | * Requires: | |
223 | * Ensures: | |
224 | * | |
225 | */ | |
226 | extern int cmm_un_register_gppsm_seg(struct cmm_object *hcmm_mgr, | |
227 | u32 ul_seg_id); | |
228 | ||
229 | /* | |
230 | * ======== cmm_xlator_alloc_buf ======== | |
231 | * Purpose: | |
232 | * Allocate the specified SM buffer and create a local memory descriptor. | |
233 | * Place on the descriptor on the translator's HaQ (Host Alloc'd Queue). | |
234 | * Parameters: | |
235 | * xlator: Handle to a Xlator object. | |
318b5df9 | 236 | * va_buf: Virtual address ptr(client context) |
5e2eae57 | 237 | * pa_size: Size of SM memory to allocate. |
6280238c | 238 | * Returns: |
5e2eae57 | 239 | * Ptr to valid physical address(Pa) of pa_size bytes, NULL if failed. |
6280238c | 240 | * Requires: |
318b5df9 | 241 | * va_buf != 0. |
5e2eae57 | 242 | * pa_size != 0. |
6280238c ORL |
243 | * Ensures: |
244 | * | |
245 | */ | |
246 | extern void *cmm_xlator_alloc_buf(struct cmm_xlatorobject *xlator, | |
5e2eae57 | 247 | void *va_buf, u32 pa_size); |
6280238c ORL |
248 | |
249 | /* | |
250 | * ======== cmm_xlator_create ======== | |
251 | * Purpose: | |
252 | * Create a translator(xlator) object used for process specific Va<->Pa | |
253 | * address translation. Node messaging and streams use this to perform | |
254 | * inter-processor(GPP<->DSP) zero-copy data transfer. | |
255 | * Parameters: | |
daa89e6c | 256 | * xlator: Address to place handle to a new Xlator handle. |
6280238c | 257 | * hcmm_mgr: Handle to Cmm Mgr associated with this translator. |
318b5df9 | 258 | * xlator_attrs: Translator attributes used for the client NODE or STREAM. |
6280238c ORL |
259 | * Returns: |
260 | * 0: Success. | |
261 | * -EINVAL: Bad input Attrs. | |
262 | * -ENOMEM: Insufficient memory(local) for requested resources. | |
263 | * Requires: | |
daa89e6c | 264 | * xlator != NULL |
6280238c | 265 | * hcmm_mgr != NULL |
318b5df9 | 266 | * xlator_attrs != NULL |
6280238c ORL |
267 | * Ensures: |
268 | * | |
269 | */ | |
e6bf74f0 | 270 | extern int cmm_xlator_create(struct cmm_xlatorobject **xlator, |
6280238c | 271 | struct cmm_object *hcmm_mgr, |
318b5df9 | 272 | struct cmm_xlatorattrs *xlator_attrs); |
6280238c | 273 | |
6280238c ORL |
274 | /* |
275 | * ======== cmm_xlator_free_buf ======== | |
276 | * Purpose: | |
277 | * Free SM buffer and descriptor. | |
278 | * Does not free client process VM. | |
279 | * Parameters: | |
280 | * xlator: handle to translator. | |
aa09b091 | 281 | * buf_va Virtual address of PA to free. |
6280238c ORL |
282 | * Returns: |
283 | * 0: Success. | |
284 | * -EFAULT: Bad translator handle. | |
285 | * Requires: | |
286 | * Ensures: | |
287 | * | |
288 | */ | |
289 | extern int cmm_xlator_free_buf(struct cmm_xlatorobject *xlator, | |
aa09b091 | 290 | void *buf_va); |
6280238c ORL |
291 | |
292 | /* | |
293 | * ======== cmm_xlator_info ======== | |
294 | * Purpose: | |
295 | * Set/Get process specific "translator" address info. | |
296 | * This is used to perform fast virtaul address translation | |
297 | * for shared memory buffers between the GPP and DSP. | |
298 | * Parameters: | |
299 | * xlator: handle to translator. | |
300 | * paddr: Virtual base address of segment. | |
301 | * ul_size: Size in bytes. | |
5e2eae57 | 302 | * segm_id: Segment identifier of SM segment(s) |
6280238c ORL |
303 | * set_info Set xlator fields if TRUE, else return base addr |
304 | * Returns: | |
305 | * 0: Success. | |
306 | * -EFAULT: Bad translator handle. | |
307 | * Requires: | |
6280238c ORL |
308 | * (paddr != NULL) |
309 | * (ul_size > 0) | |
310 | * Ensures: | |
311 | * | |
312 | */ | |
313 | extern int cmm_xlator_info(struct cmm_xlatorobject *xlator, | |
e6bf74f0 | 314 | u8 **paddr, |
5e2eae57 | 315 | u32 ul_size, u32 segm_id, bool set_info); |
6280238c ORL |
316 | |
317 | /* | |
318 | * ======== cmm_xlator_translate ======== | |
319 | * Purpose: | |
320 | * Perform address translation VA<->PA for the specified stream or | |
321 | * message shared memory buffer. | |
322 | * Parameters: | |
323 | * xlator: handle to translator. | |
324 | * paddr address of buffer to translate. | |
5a09ddea | 325 | * xtype Type of address xlation. CMM_PA2VA or CMM_VA2PA. |
6280238c ORL |
326 | * Returns: |
327 | * Valid address on success, else NULL. | |
328 | * Requires: | |
6280238c | 329 | * paddr != NULL |
5a09ddea | 330 | * xtype >= CMM_VA2PA) && (xtype <= CMM_DSPPA2PA) |
6280238c ORL |
331 | * Ensures: |
332 | * | |
333 | */ | |
334 | extern void *cmm_xlator_translate(struct cmm_xlatorobject *xlator, | |
5a09ddea | 335 | void *paddr, enum cmm_xlatetype xtype); |
6280238c ORL |
336 | |
337 | #endif /* CMM_ */ |