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