release/src-rt-6.x.4708/linux/linux-2.6.36/drivers/staging/tidspbridge/include/dspbridge/cmm.h

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