Linux Kernel  3.7.1
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
cmm.h
Go to the documentation of this file.
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,
65  void **pp_buf_va);
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.
75  * mgr_attrts: Comm mem manager attributes.
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  * ph_cmm_mgr != NULL.
83  * mgr_attrts->min_block_size >= 4 bytes.
84  * Ensures:
85  *
86  */
87 extern int cmm_create(struct cmm_object **ph_cmm_mgr,
88  struct dev_object *hdev_obj,
89  const struct cmm_mgrattrs *mgr_attrts);
90 
91 /*
92  * ======== cmm_destroy ========
93  * Purpose:
94  * Destroy the communication memory manager object.
95  * Parameters:
96  * hcmm_mgr: Cmm Mgr handle.
97  * force: Force deallocation of all cmm memory immediately if set TRUE.
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  */
110 extern int cmm_destroy(struct cmm_object *hcmm_mgr, bool force);
111 
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,
151  struct cmm_object **ph_cmm_mgr);
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,
170  struct cmm_info *cmm_info_obj);
171 
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.
180  * dsp_addr_offset GPP PA to DSP PA Offset.
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.
184  * sgmt_id: Address to store segment Id.
185  *
186  * Returns:
187  * 0: Success.
188  * -EFAULT: Invalid hcmm_mgr handle.
189  * -EINVAL: Invalid input argument.
190  * -EPERM: Unable to register.
191  * - On success *sgmt_id is a valid SM segment ID.
192  * Requires:
193  * ul_size > 0
194  * sgmt_id != NULL
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,
203  u32 dsp_addr_offset,
204  s8 c_factor,
205  unsigned int dw_dsp_base,
206  u32 ul_dsp_size,
207  u32 *sgmt_id, u32 gpp_base_va);
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.
236  * va_buf: Virtual address ptr(client context)
237  * pa_size: Size of SM memory to allocate.
238  * Returns:
239  * Ptr to valid physical address(Pa) of pa_size bytes, NULL if failed.
240  * Requires:
241  * va_buf != 0.
242  * pa_size != 0.
243  * Ensures:
244  *
245  */
246 extern void *cmm_xlator_alloc_buf(struct cmm_xlatorobject *xlator,
247  void *va_buf, u32 pa_size);
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:
256  * xlator: Address to place handle to a new Xlator handle.
257  * hcmm_mgr: Handle to Cmm Mgr associated with this translator.
258  * xlator_attrs: Translator attributes used for the client NODE or STREAM.
259  * Returns:
260  * 0: Success.
261  * -EINVAL: Bad input Attrs.
262  * -ENOMEM: Insufficient memory(local) for requested resources.
263  * Requires:
264  * xlator != NULL
265  * hcmm_mgr != NULL
266  * xlator_attrs != NULL
267  * Ensures:
268  *
269  */
270 extern int cmm_xlator_create(struct cmm_xlatorobject **xlator,
271  struct cmm_object *hcmm_mgr,
272  struct cmm_xlatorattrs *xlator_attrs);
273 
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.
281  * buf_va Virtual address of PA to free.
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,
290  void *buf_va);
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.
302  * segm_id: Segment identifier of SM segment(s)
303  * set_info Set xlator fields if TRUE, else return base addr
304  * Returns:
305  * 0: Success.
306  * -EFAULT: Bad translator handle.
307  * Requires:
308  * (paddr != NULL)
309  * (ul_size > 0)
310  * Ensures:
311  *
312  */
313 extern int cmm_xlator_info(struct cmm_xlatorobject *xlator,
314  u8 **paddr,
315  u32 ul_size, u32 segm_id, bool set_info);
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.
325  * xtype Type of address xlation. CMM_PA2VA or CMM_VA2PA.
326  * Returns:
327  * Valid address on success, else NULL.
328  * Requires:
329  * paddr != NULL
330  * xtype >= CMM_VA2PA) && (xtype <= CMM_DSPPA2PA)
331  * Ensures:
332  *
333  */
334 extern void *cmm_xlator_translate(struct cmm_xlatorobject *xlator,
335  void *paddr, enum cmm_xlatetype xtype);
336 
337 #endif /* CMM_ */