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_ */ 338