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

https://bitbucket.org/wisechild/galaxy-nexus · C++ Header · 367 lines · 43 code · 19 blank · 305 comment · 0 complexity · d9364c56c9bc54183f750d8847bf1cc2 MD5 · raw 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. #ifndef CMM_
  33. #define CMM_
  34. #include <dspbridge/devdefs.h>
  35. #include <dspbridge/cmmdefs.h>
  36. #include <dspbridge/host_os.h>
  37. /*
  38. * ======== cmm_calloc_buf ========
  39. * Purpose:
  40. * Allocate memory buffers that can be used for data streaming or
  41. * messaging.
  42. * Parameters:
  43. * hcmm_mgr: Cmm Mgr handle.
  44. * usize: Number of bytes to allocate.
  45. * pattr: Attributes of memory to allocate.
  46. * pp_buf_va: Address of where to place VA.
  47. * Returns:
  48. * Pointer to a zero'd block of SM memory;
  49. * NULL if memory couldn't be allocated,
  50. * or if byte_size == 0,
  51. * Requires:
  52. * Valid hcmm_mgr.
  53. * CMM initialized.
  54. * Ensures:
  55. * The returned pointer, if not NULL, points to a valid memory block of
  56. * the size requested.
  57. *
  58. */
  59. extern void *cmm_calloc_buf(struct cmm_object *hcmm_mgr,
  60. u32 usize, struct cmm_attrs *pattrs,
  61. void **pp_buf_va);
  62. /*
  63. * ======== cmm_create ========
  64. * Purpose:
  65. * Create a communication memory manager object.
  66. * Parameters:
  67. * ph_cmm_mgr: Location to store a communication manager handle on
  68. * output.
  69. * hdev_obj: Handle to a device object.
  70. * mgr_attrts: Comm mem manager attributes.
  71. * Returns:
  72. * 0: Success;
  73. * -ENOMEM: Insufficient memory for requested resources.
  74. * -EPERM: Failed to initialize critical sect sync object.
  75. *
  76. * Requires:
  77. * cmm_init(void) called.
  78. * ph_cmm_mgr != NULL.
  79. * mgr_attrts->min_block_size >= 4 bytes.
  80. * Ensures:
  81. *
  82. */
  83. extern int cmm_create(struct cmm_object **ph_cmm_mgr,
  84. struct dev_object *hdev_obj,
  85. const struct cmm_mgrattrs *mgr_attrts);
  86. /*
  87. * ======== cmm_destroy ========
  88. * Purpose:
  89. * Destroy the communication memory manager object.
  90. * Parameters:
  91. * hcmm_mgr: Cmm Mgr handle.
  92. * force: Force deallocation of all cmm memory immediately if set TRUE.
  93. * If FALSE, and outstanding allocations will return -EPERM
  94. * status.
  95. * Returns:
  96. * 0: CMM object & resources deleted.
  97. * -EPERM: Unable to free CMM object due to outstanding allocation.
  98. * -EFAULT: Unable to free CMM due to bad handle.
  99. * Requires:
  100. * CMM is initialized.
  101. * hcmm_mgr != NULL.
  102. * Ensures:
  103. * Memory resources used by Cmm Mgr are freed.
  104. */
  105. extern int cmm_destroy(struct cmm_object *hcmm_mgr, bool force);
  106. /*
  107. * ======== cmm_exit ========
  108. * Purpose:
  109. * Discontinue usage of module. Cleanup CMM module if CMM cRef reaches zero.
  110. * Parameters:
  111. * n/a
  112. * Returns:
  113. * n/a
  114. * Requires:
  115. * CMM is initialized.
  116. * Ensures:
  117. */
  118. extern void cmm_exit(void);
  119. /*
  120. * ======== cmm_free_buf ========
  121. * Purpose:
  122. * Free the given buffer.
  123. * Parameters:
  124. * hcmm_mgr: Cmm Mgr handle.
  125. * pbuf: Pointer to memory allocated by cmm_calloc_buf().
  126. * ul_seg_id: SM segment Id used in CMM_Calloc() attrs.
  127. * Set to 0 to use default segment.
  128. * Returns:
  129. * 0
  130. * -EPERM
  131. * Requires:
  132. * CMM initialized.
  133. * buf_pa != NULL
  134. * Ensures:
  135. *
  136. */
  137. extern int cmm_free_buf(struct cmm_object *hcmm_mgr,
  138. void *buf_pa, u32 ul_seg_id);
  139. /*
  140. * ======== cmm_get_handle ========
  141. * Purpose:
  142. * Return the handle to the cmm mgr for the given device obj.
  143. * Parameters:
  144. * hprocessor: Handle to a Processor.
  145. * ph_cmm_mgr: Location to store the shared memory mgr handle on
  146. * output.
  147. *
  148. * Returns:
  149. * 0: Cmm Mgr opaque handle returned.
  150. * -EFAULT: Invalid handle.
  151. * Requires:
  152. * ph_cmm_mgr != NULL
  153. * hdev_obj != NULL
  154. * Ensures:
  155. */
  156. extern int cmm_get_handle(void *hprocessor,
  157. struct cmm_object **ph_cmm_mgr);
  158. /*
  159. * ======== cmm_get_info ========
  160. * Purpose:
  161. * Return the current SM and VM utilization information.
  162. * Parameters:
  163. * hcmm_mgr: Handle to a Cmm Mgr.
  164. * cmm_info_obj: Location to store the Cmm information on output.
  165. *
  166. * Returns:
  167. * 0: Success.
  168. * -EFAULT: Invalid handle.
  169. * -EINVAL Invalid input argument.
  170. * Requires:
  171. * Ensures:
  172. *
  173. */
  174. extern int cmm_get_info(struct cmm_object *hcmm_mgr,
  175. struct cmm_info *cmm_info_obj);
  176. /*
  177. * ======== cmm_init ========
  178. * Purpose:
  179. * Initializes private state of CMM module.
  180. * Parameters:
  181. * Returns:
  182. * TRUE if initialized; FALSE if error occurred.
  183. * Requires:
  184. * Ensures:
  185. * CMM initialized.
  186. */
  187. extern bool cmm_init(void);
  188. /*
  189. * ======== cmm_register_gppsm_seg ========
  190. * Purpose:
  191. * Register a block of SM with the CMM.
  192. * Parameters:
  193. * hcmm_mgr: Handle to a Cmm Mgr.
  194. * lpGPPBasePA: GPP Base Physical address.
  195. * ul_size: Size in GPP bytes.
  196. * dsp_addr_offset GPP PA to DSP PA Offset.
  197. * c_factor: Add offset if CMM_ADDTODSPPA, sub if CMM_SUBFROMDSPPA.
  198. * dw_dsp_base: DSP virtual base byte address.
  199. * ul_dsp_size: Size of DSP segment in bytes.
  200. * sgmt_id: Address to store segment Id.
  201. *
  202. * Returns:
  203. * 0: Success.
  204. * -EFAULT: Invalid hcmm_mgr handle.
  205. * -EINVAL: Invalid input argument.
  206. * -EPERM: Unable to register.
  207. * - On success *sgmt_id is a valid SM segment ID.
  208. * Requires:
  209. * ul_size > 0
  210. * sgmt_id != NULL
  211. * dw_gpp_base_pa != 0
  212. * c_factor = CMM_ADDTODSPPA || c_factor = CMM_SUBFROMDSPPA
  213. * Ensures:
  214. *
  215. */
  216. extern int cmm_register_gppsm_seg(struct cmm_object *hcmm_mgr,
  217. unsigned int dw_gpp_base_pa,
  218. u32 ul_size,
  219. u32 dsp_addr_offset,
  220. s8 c_factor,
  221. unsigned int dw_dsp_base,
  222. u32 ul_dsp_size,
  223. u32 *sgmt_id, u32 gpp_base_va);
  224. /*
  225. * ======== cmm_un_register_gppsm_seg ========
  226. * Purpose:
  227. * Unregister the given memory segment that was previously registered
  228. * by cmm_register_gppsm_seg.
  229. * Parameters:
  230. * hcmm_mgr: Handle to a Cmm Mgr.
  231. * ul_seg_id Segment identifier returned by cmm_register_gppsm_seg.
  232. * Returns:
  233. * 0: Success.
  234. * -EFAULT: Invalid handle.
  235. * -EINVAL: Invalid ul_seg_id.
  236. * -EPERM: Unable to unregister for unknown reason.
  237. * Requires:
  238. * Ensures:
  239. *
  240. */
  241. extern int cmm_un_register_gppsm_seg(struct cmm_object *hcmm_mgr,
  242. u32 ul_seg_id);
  243. /*
  244. * ======== cmm_xlator_alloc_buf ========
  245. * Purpose:
  246. * Allocate the specified SM buffer and create a local memory descriptor.
  247. * Place on the descriptor on the translator's HaQ (Host Alloc'd Queue).
  248. * Parameters:
  249. * xlator: Handle to a Xlator object.
  250. * va_buf: Virtual address ptr(client context)
  251. * pa_size: Size of SM memory to allocate.
  252. * Returns:
  253. * Ptr to valid physical address(Pa) of pa_size bytes, NULL if failed.
  254. * Requires:
  255. * va_buf != 0.
  256. * pa_size != 0.
  257. * Ensures:
  258. *
  259. */
  260. extern void *cmm_xlator_alloc_buf(struct cmm_xlatorobject *xlator,
  261. void *va_buf, u32 pa_size);
  262. /*
  263. * ======== cmm_xlator_create ========
  264. * Purpose:
  265. * Create a translator(xlator) object used for process specific Va<->Pa
  266. * address translation. Node messaging and streams use this to perform
  267. * inter-processor(GPP<->DSP) zero-copy data transfer.
  268. * Parameters:
  269. * xlator: Address to place handle to a new Xlator handle.
  270. * hcmm_mgr: Handle to Cmm Mgr associated with this translator.
  271. * xlator_attrs: Translator attributes used for the client NODE or STREAM.
  272. * Returns:
  273. * 0: Success.
  274. * -EINVAL: Bad input Attrs.
  275. * -ENOMEM: Insufficient memory(local) for requested resources.
  276. * Requires:
  277. * xlator != NULL
  278. * hcmm_mgr != NULL
  279. * xlator_attrs != NULL
  280. * Ensures:
  281. *
  282. */
  283. extern int cmm_xlator_create(struct cmm_xlatorobject **xlator,
  284. struct cmm_object *hcmm_mgr,
  285. struct cmm_xlatorattrs *xlator_attrs);
  286. /*
  287. * ======== cmm_xlator_free_buf ========
  288. * Purpose:
  289. * Free SM buffer and descriptor.
  290. * Does not free client process VM.
  291. * Parameters:
  292. * xlator: handle to translator.
  293. * buf_va Virtual address of PA to free.
  294. * Returns:
  295. * 0: Success.
  296. * -EFAULT: Bad translator handle.
  297. * Requires:
  298. * Ensures:
  299. *
  300. */
  301. extern int cmm_xlator_free_buf(struct cmm_xlatorobject *xlator,
  302. void *buf_va);
  303. /*
  304. * ======== cmm_xlator_info ========
  305. * Purpose:
  306. * Set/Get process specific "translator" address info.
  307. * This is used to perform fast virtaul address translation
  308. * for shared memory buffers between the GPP and DSP.
  309. * Parameters:
  310. * xlator: handle to translator.
  311. * paddr: Virtual base address of segment.
  312. * ul_size: Size in bytes.
  313. * segm_id: Segment identifier of SM segment(s)
  314. * set_info Set xlator fields if TRUE, else return base addr
  315. * Returns:
  316. * 0: Success.
  317. * -EFAULT: Bad translator handle.
  318. * Requires:
  319. * (refs > 0)
  320. * (paddr != NULL)
  321. * (ul_size > 0)
  322. * Ensures:
  323. *
  324. */
  325. extern int cmm_xlator_info(struct cmm_xlatorobject *xlator,
  326. u8 **paddr,
  327. u32 ul_size, u32 segm_id, bool set_info);
  328. /*
  329. * ======== cmm_xlator_translate ========
  330. * Purpose:
  331. * Perform address translation VA<->PA for the specified stream or
  332. * message shared memory buffer.
  333. * Parameters:
  334. * xlator: handle to translator.
  335. * paddr address of buffer to translate.
  336. * xtype Type of address xlation. CMM_PA2VA or CMM_VA2PA.
  337. * Returns:
  338. * Valid address on success, else NULL.
  339. * Requires:
  340. * refs > 0
  341. * paddr != NULL
  342. * xtype >= CMM_VA2PA) && (xtype <= CMM_DSPPA2PA)
  343. * Ensures:
  344. *
  345. */
  346. extern void *cmm_xlator_translate(struct cmm_xlatorobject *xlator,
  347. void *paddr, enum cmm_xlatetype xtype);
  348. #endif /* CMM_ */