/drivers/staging/tidspbridge/include/dspbridge/cmm.h

  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 */
 63extern 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 *      cmm_init(void) called.
 83 *      ph_cmm_mgr != NULL.
 84 *      mgr_attrts->min_block_size >= 4 bytes.
 85 *  Ensures:
 86 *
 87 */
 88extern int cmm_create(struct cmm_object **ph_cmm_mgr,
 89			     struct dev_object *hdev_obj,
 90			     const struct cmm_mgrattrs *mgr_attrts);
 91
 92/*
 93 *  ======== cmm_destroy ========
 94 *  Purpose:
 95 *      Destroy the communication memory manager object.
 96 *  Parameters:
 97 *      hcmm_mgr:   Cmm Mgr handle.
 98 *      force:     Force deallocation of all cmm memory immediately if set TRUE.
 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 */
111extern int cmm_destroy(struct cmm_object *hcmm_mgr, bool force);
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 */
125extern 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 */
145extern 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 */
165extern int cmm_get_handle(void *hprocessor,
166				 struct cmm_object **ph_cmm_mgr);
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 */
184extern int cmm_get_info(struct cmm_object *hcmm_mgr,
185			       struct cmm_info *cmm_info_obj);
186
187/*
188 *  ======== cmm_init ========
189 *  Purpose:
190 *      Initializes private state of CMM module.
191 *  Parameters:
192 *  Returns:
193 *      TRUE if initialized; FALSE if error occurred.
194 *  Requires:
195 *  Ensures:
196 *      CMM initialized.
197 */
198extern 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.
208 *      dsp_addr_offset  GPP PA to DSP PA Offset.
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.
212 *      sgmt_id:         Address to store segment Id.
213 *
214 *  Returns:
215 *      0:         Success.
216 *      -EFAULT:     Invalid hcmm_mgr handle.
217 *      -EINVAL: Invalid input argument.
218 *      -EPERM:       Unable to register.
219 *      - On success *sgmt_id is a valid SM segment ID.
220 *  Requires:
221 *      ul_size > 0
222 *      sgmt_id != NULL
223 *      dw_gpp_base_pa != 0
224 *      c_factor = CMM_ADDTODSPPA || c_factor = CMM_SUBFROMDSPPA
225 *  Ensures:
226 *
227 */
228extern int cmm_register_gppsm_seg(struct cmm_object *hcmm_mgr,
229					 unsigned int dw_gpp_base_pa,
230					 u32 ul_size,
231					 u32 dsp_addr_offset,
232					 s8 c_factor,
233					 unsigned int dw_dsp_base,
234					 u32 ul_dsp_size,
235					 u32 *sgmt_id, u32 gpp_base_va);
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 */
254extern 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.
264 *      va_buf:     Virtual address ptr(client context)
265 *      pa_size:    Size of SM memory to allocate.
266 *  Returns:
267 *      Ptr to valid physical address(Pa) of pa_size bytes, NULL if failed.
268 *  Requires:
269 *      va_buf != 0.
270 *      pa_size != 0.
271 *  Ensures:
272 *
273 */
274extern void *cmm_xlator_alloc_buf(struct cmm_xlatorobject *xlator,
275				  void *va_buf, u32 pa_size);
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:
284 *     xlator:         Address to place handle to a new Xlator handle.
285 *     hcmm_mgr:        Handle to Cmm Mgr associated with this translator.
286 *     xlator_attrs:   Translator attributes used for the client NODE or STREAM.
287 *  Returns:
288 *     0:            Success.
289 *     -EINVAL:    Bad input Attrs.
290 *     -ENOMEM:   Insufficient memory(local) for requested resources.
291 *  Requires:
292 *     xlator != NULL
293 *     hcmm_mgr != NULL
294 *     xlator_attrs != NULL
295 *  Ensures:
296 *
297 */
298extern int cmm_xlator_create(struct cmm_xlatorobject **xlator,
299				    struct cmm_object *hcmm_mgr,
300				    struct cmm_xlatorattrs *xlator_attrs);
301
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.
309 *      buf_va      Virtual address of PA to free.
310 *  Returns:
311 *      0:        Success.
312 *      -EFAULT:    Bad translator handle.
313 *  Requires:
314 *  Ensures:
315 *
316 */
317extern int cmm_xlator_free_buf(struct cmm_xlatorobject *xlator,
318				      void *buf_va);
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.
330 *     segm_id:     Segment identifier of SM segment(s)
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 */
342extern int cmm_xlator_info(struct cmm_xlatorobject *xlator,
343				  u8 **paddr,
344				  u32 ul_size, u32 segm_id, bool set_info);
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.
354 *     xtype    Type of address xlation. CMM_PA2VA or CMM_VA2PA.
355 *  Returns:
356 *     Valid address on success, else NULL.
357 *  Requires:
358 *      refs > 0
359 *      paddr != NULL
360 *      xtype >= CMM_VA2PA) && (xtype <= CMM_DSPPA2PA)
361 *  Ensures:
362 *
363 */
364extern void *cmm_xlator_translate(struct cmm_xlatorobject *xlator,
365				  void *paddr, enum cmm_xlatetype xtype);
366
367#endif /* CMM_ */