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  *      cmm_init(void) called.
  83  *      ph_cmm_mgr != NULL.
  84  *      mgr_attrts->min_block_size >= 4 bytes.
  85  *  Ensures:
  86  *
  87  */
  88 extern 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  */
 111 extern 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  */
 125 extern 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  */
 145 extern 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  */
 165 extern 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  */
 184 extern 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  */
 198 extern 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  */
 228 extern 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  */
 254 extern 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  */
 274 extern 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  */
 298 extern 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  */
 317 extern 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  */
 342 extern 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  */
 364 extern void *cmm_xlator_translate(struct cmm_xlatorobject *xlator,
 365                                   void *paddr, enum cmm_xlatetype xtype);
 366
 367 #endif /* CMM_ */