Home | History | Annotate | Download | only in inc
      1 /*
      2  * dspbridge/mpu_api/inc/DSPProcessor.h
      3  *
      4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
      5  *
      6  * Copyright (C) 2007 Texas Instruments, Inc.
      7  *
      8  * This program is free software; you can redistribute it and/or modify it
      9  * under the terms of the GNU Lesser General Public License as published
     10  * by the Free Software Foundation version 2.1 of the License.
     11  *
     12  * This program is distributed .as is. WITHOUT ANY WARRANTY of any kind,
     13  * whether express or implied; without even the implied warranty of
     14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     15  * Lesser General Public License for more details.
     16  */
     17 
     18 
     19 /*
     20  *  ======== DSPProcessor.h ========
     21  *  Description:
     22  *      This is the header for the DSP/BIOS Bridge processor module.
     23  *
     24  *  Public Functions:
     25  *      DSPProcessor_Attach
     26  *      DSPProcessor_Detach
     27  *      DSPProcessor_EnumNodes
     28  *      DSPProcessor_FlushMemory
     29  *      DSPProcessor_GetResourceInfo
     30  *      DSPProcessor_GetState
     31  *      DSPProcessor_Map
     32  *      DSPProcessor_RegisterNotify
     33  *      DSPProcessor_ReserveMemory
     34  *      DSPProcessor_UnMap
     35  *      DSPProcessor_UnReserveMemory
     36  *      DSPProcessor_InvalidateMemory
     37 
     38  *  Notes:
     39  *
     40  *! Revision History:
     41  *! ================
     42  *! 04-04-2007  sh  Added DSPProcessor_InvalidateMemory
     43  *! 19-Apr-2004 sb  Aligned DMM definitions with Symbian
     44  *! 08-Mar-2004 sb  Added the Dynamic Memory Mapping APIs
     45  *! 23-Nov-2002 gp: Comment cleanup.
     46  *! 13-Feb-2001 kc: DSP/BIOS Bridge name updates.
     47  *! 29-Nov-2000 rr: OEM Fxns moved to DSPProcessor_OEM.h
     48  *!                 Incorporated code review changes.
     49  *! 27-Oct-2000 jeh Changed uNotifyMask to uNotifyType.
     50  *! 28-Sep-2000 rr: Updated to Version 0.9.
     51  *! 07-Sep-2000 jeh Changed type HANDLE in DSPProcessor_RegisterNotify to
     52  *!                 DSP_HNOTIFICATION.
     53  *! 14-Aug-2000 rr: Cleaned up.
     54  *! 20-Jul-2000 rr: Updated to Version 0.8
     55  *! 27-Jun-2000 rr: Created from DBAPI.h
     56  */
     57 
     58 #ifndef DSPPROCESSOR_
     59 #define DSPPROCESSOR_
     60 
     61 #ifdef __cplusplus
     62 extern "C" {
     63 #endif
     64 
     65 /*
     66  *  ======== DSPProcessor_Attach ========
     67  *  Purpose:
     68  *      Prepare for communication with a particular DSP processor, and return
     69  *      a processor handle for subsequent operations.
     70  *  Parameters:
     71  *      uProcessor:             The processor index.
     72  *      pAttrIn:                Ptr to the DSP_PROCESSORATTRIN structure.
     73  *                              A NULL value means use default values.
     74  *      phProcessor:            Ptr to location to store processor handle.
     75  *  Returns:
     76  *      DSP_SOK:                Success.
     77  *      DSP_EPOINTER:           Parameter phProcessor is not valid.
     78  *      DSP_EINVALIDARG:        Parameter uProcessor is invalid
     79  *      DSP_EFAIL:              Unable to attach the processor
     80  *      DSP_SALREADYATTACHED:   Success; Processor already attached.
     81  *  Details:
     82  *      Returns DSP_EINVALIDARG if uProcessor index >= number of processors.
     83  *      When pAttrIn is NULL, the default timeout value is 10 seconds.
     84  *      This call does not affect the actual execution state of the DSP.
     85  */
     86 	extern DBAPI DSPProcessor_Attach(UINT uProcessor,
     87 					 OPTIONAL CONST struct DSP_PROCESSORATTRIN *
     88 					 pAttrIn,
     89 					 OUT DSP_HPROCESSOR * phProcessor);
     90 
     91 /*
     92  *  ======== DSPProcessor_Detach ========
     93  *  Purpose:
     94  *      Detach from a DSP processor and de-allocate all (GPP) resources reserved
     95  *      for it.
     96  *  Parameters:
     97  *      hProcessor:     The processor handle.
     98  *  Returns:
     99  *      DSP_SOK:        Success.
    100  *      DSP_EHANDLE:    Invalid processor handle.
    101  *      DSP_EFAIL:      Unable to detach from the processor.
    102  *  Details:
    103  *      This call does not affect the actual execution state of the DSP.
    104  */
    105 	extern DBAPI DSPProcessor_Detach(DSP_HPROCESSOR hProcessor);
    106 
    107 /*
    108  *  ======== DSPProcessor_EnumNodes ========
    109  *  Purpose:
    110  *      Enumerate the nodes currently allocated on a processor.
    111  *  Parameters:
    112  *      hProcessor:     The processor handle.
    113  *      aNodeTab:       An array allocated to receive the node handles.
    114  *      uNodeTabSize:   The number of (DSP_HNODE) handles that can be held
    115  *                      in aNodeTab.
    116  *      puNumNodes:     Location where DSPProcessor_EnumNodes will return
    117  *                      the number of valid handles written to aNodeTab
    118  *      puAllocated:    Location where DSPProcessor_EnumNodes will return
    119  *                      the number of nodes that are allocated on the DSP.
    120  *  Returns:
    121  *      DSP_SOK:        Success.
    122  *      DSP_EHANDLE:    Invalid processor handle.
    123  *      DSP_EPOINTER:   Parameters puNumNodes or puAllocated is not valid
    124  *      DSP_ESIZE:      The amount of memory allocated for aNodeTab is
    125  *                      insufficent.   The number of nodes actually
    126  *                      allocated on the DSP is greater than the value
    127  *                      specified for uNodeTabSize.
    128  *      DSP_EFAIL:      A failure occurred during enumeration.
    129  *  Details:
    130  */
    131 	extern DBAPI DSPProcessor_EnumNodes(DSP_HPROCESSOR hProcessor,
    132 					    IN DSP_HNODE * aNodeTab,
    133 					    IN UINT uNodeTabSize,
    134 					    OUT UINT * puNumNodes,
    135 					    OUT UINT * puAllocated);
    136 
    137 /*
    138  *  ======== DSPProcessor_FlushMemory ========
    139  *  Purpose:
    140  *      Flushes a buffer from the MPU data cache.
    141  *  Parameters:
    142  *      hProcessor      :   The processor handle.
    143  *      pMpuAddr        :   Buffer start address
    144  *      ulSize          :   Buffer size
    145  *      ulFlags         :   Reserved.
    146  *  Returns:
    147  *      DSP_SOK         :   Success.
    148  *      DSP_EHANDLE     :   Invalid processor handle.
    149  *      DSP_EFAIL       :   General failure.
    150  *  Requires:
    151  *      PROC Initialized.
    152  *  Ensures:
    153  *  Details:
    154  *      All the arguments are currently ignored.
    155  */
    156 	extern DBAPI DSPProcessor_FlushMemory(DSP_HPROCESSOR hProcessor,
    157 					      PVOID pMpuAddr,
    158 					      ULONG ulSize, ULONG ulFlags);
    159 
    160 /*
    161  *  ======== DSPProcessor_InvalidateMemory ========
    162  *  Purpose:
    163  *      Invalidates  a buffer from the MPU data cache.
    164  *  Parameters:
    165  *      hProcessor      :   The processor handle.
    166  *      pMpuAddr        :   Buffer start address
    167  *      ulSize          :   Buffer size
    168  *  Returns:
    169  *      DSP_SOK         :   Success.
    170  *      DSP_EHANDLE     :   Invalid processor handle.
    171  *      DSP_EFAIL       :   General failure.
    172  *  Requires:
    173  *      PROC Initialized.
    174  *  Ensures:
    175  *  Details:
    176  */
    177         extern DBAPI DSPProcessor_InvalidateMemory(DSP_HPROCESSOR hProcessor,
    178                                               PVOID pMpuAddr,
    179 	                                             ULONG ulSize);
    180 
    181 /*
    182  *  ======== DSPProcessor_GetResourceInfo ========
    183  *  Purpose:
    184  *      Get information about a DSP Resources.
    185  *  Parameters:
    186  *      hProcessor:         The processor handle.
    187  *      uResourceType:      Type of resource to be reported.
    188  *      pResourceInfo:      Ptr to the DSP_RESOURCEINFO structure in which
    189  *                          the processor resource information will be returned.
    190  *      uResourceInfoSize:  Size of the DSP_RESOURCEINFO structure.
    191  *  Returns:
    192  *      DSP_SOK:            Success.
    193  *      DSP_EHANDLE:        Invalid processor handle.
    194  *      DSP_EPOINTER:       Parameter pResourceInfo is not valid
    195  *      DSP_EVALUE:         Parameter uResourceType is invalid.
    196  *      DSP_EWRONGSTATE:    The processor is not in the PROC_RUNNING state.
    197  *      DSP_ETIMEOUT:       A timeout occured before the DSP responded to the
    198  *                          querry.
    199  *      DSP_ERESTART:       A Critical error has occured and the DSP is being
    200  *                          restarted.
    201  *      DSP_ESIZE:          The size of the specified DSP_RESOURCEINFO struct
    202  *                          is too small to hold all the information.
    203  *      DSP_EFAIL:          Unable to get Resource Information
    204  *  Details:
    205  */
    206 	extern DBAPI DSPProcessor_GetResourceInfo(DSP_HPROCESSOR hProcessor,
    207 						  UINT uResourceType,
    208 						  OUT struct DSP_RESOURCEINFO *
    209 						  pResourceInfo,
    210 						  UINT uResourceInfoSize);
    211 
    212 /*
    213  *  ======== DSPProcessor_GetState ========
    214  *  Purpose:
    215  *      Report the state of the specified DSP processor.
    216  *  Parameters:
    217  *      hProcessor:         The processor handle.
    218  *      pProcStatus:        Ptr to location to store the DSP_PROCESSORSTATE
    219  *                          structure.
    220  *      uStateInfoSize:     Size of DSP_PROCESSORSTATE.
    221  *  Returns:
    222  *      DSP_SOK:            Success.
    223  *      DSP_EHANDLE:        Invalid processor handle.
    224  *      DSP_EPOINTER:       Parameter pProcStatus is not valid.
    225  *      DSP_EFAIL:          General failure while querying processor state.
    226  *      DSP_ESIZE:          uStateInfoSize is smaller than sizeof
    227  *                          DSP_PROCESSORSTATE.
    228  *  Details:
    229  */
    230 	extern DBAPI DSPProcessor_GetState(DSP_HPROCESSOR hProcessor,
    231 					   OUT struct DSP_PROCESSORSTATE * pProcStatus,
    232 					   UINT uStateInfoSize);
    233 
    234 /*
    235  *  ======== DSPProcessor_Map ========
    236  *  Purpose:
    237  *      Maps a MPU buffer to DSP address space.
    238  *  Parameters:
    239  *      hProcessor      :   The processor handle.
    240  *      pMpuAddr        :   Starting address of the memory region to map.
    241  *      ulSize          :   Size of the memory region to map.
    242  *      pReqAddr        :   Requested DSP start address. Offset-adjusted actual
    243  *                          mapped address is in the last argument.
    244  *      ppMapAddr       :   Ptr to DSP side mapped BYTE address.
    245  *      ulMapAttr       :   Optional endianness attributes, virt to phys flag.
    246  *  Returns:
    247  *      DSP_SOK         :   Success.
    248  *      DSP_EHANDLE     :   Invalid processor handle.
    249  *      DSP_EFAIL       :   General failure.
    250  *      DSP_EMEMORY     :   MPU side memory allocation error.
    251  *      DSP_ENOTFOUND   :   Cannot find a reserved region starting with this
    252  *                      :   address.
    253  *  Requires:
    254  *      pMpuAddr is not NULL
    255  *      ulSize is not zero
    256  *      ppMapAddr is not NULL
    257  *      PROC Initialized.
    258  *  Ensures:
    259  *  Details:
    260  */
    261 	extern DBAPI DSPProcessor_Map(DSP_HPROCESSOR hProcessor,
    262 				      PVOID pMpuAddr,
    263 				      ULONG ulSize,
    264 				      PVOID pReqAddr,
    265 				      PVOID * ppMapAddr, ULONG ulMapAttr);
    266 
    267 /*
    268  *  ======== DSPProcessor_RegisterNotify ========
    269  *  Purpose:
    270  *      Register to be notified of specific processor events
    271  *  Parameters:
    272  *      hProcessor:         The processor handle.
    273  *      uEventMask:         Type of event to be notified about.
    274  *      uNotifyType:        Type of notification to be sent.
    275  *      hNotification:      Handle or event name to be used for notification.
    276  *                          about, or to de-register this notification.
    277  *  Returns:
    278  *      DSP_SOK:            Success.
    279  *      DSP_EHANDLE:        Invalid processor handle or hNotification.
    280  *      DSP_EVALUE:         Parameter uEventMask is Invalid
    281  *      DSP_ENOTIMP:        The notification type specified in uNotifyType
    282  *                          is not supported.
    283  *      DSP_EFAIL:          Unable to register for notification.
    284  *  Details:
    285  */
    286 	extern DBAPI DSPProcessor_RegisterNotify(DSP_HPROCESSOR hProcessor,
    287 						 UINT uEventMask,
    288 						 UINT uNotifyType,
    289 						 struct DSP_NOTIFICATION*
    290 						 hNotification);
    291 
    292 /*
    293  *  ======== DSPProcessor_ReserveMemory ========
    294  *  Purpose:
    295  *      Reserve a virtually contiguous region of DSP address space.
    296  *  Parameters:
    297  *      hProcessor      :   The processor handle.
    298  *      ulSize          :   Size of the address space to reserve.
    299  *      ppRsvAddr       :   Ptr to DSP side reserved BYTE address.
    300  *  Returns:
    301  *      DSP_SOK         :   Success.
    302  *      DSP_EHANDLE     :   Invalid processor handle.
    303  *      DSP_EFAIL       :   General failure.
    304  *      DSP_EMEMORY     :   Cannot reserve chunk of this size.
    305  *  Requires:
    306  *      ppRsvAddr is not NULL
    307  *      PROC Initialized.
    308  *  Ensures:
    309  *  Details:
    310  */
    311 	extern DBAPI DSPProcessor_ReserveMemory(DSP_HPROCESSOR hProcessor,
    312 						ULONG ulSize,
    313 						PVOID * ppRsvAddr);
    314 
    315 /*
    316  *  ======== DSPProcessor_UnMap ========
    317  *  Purpose:
    318  *      Removes a MPU buffer mapping from the DSP address space.
    319  *  Parameters:
    320  *      hProcessor      :   The processor handle.
    321  *      pMapAddr        :   Starting address of the mapped memory region.
    322  *  Returns:
    323  *      DSP_SOK         :   Success.
    324  *      DSP_EHANDLE     :   Invalid processor handle.
    325  *      DSP_EFAIL       :   General failure.
    326  *      DSP_ENOTFOUND   :   Cannot find a mapped region starting with this
    327  *                      :   address.
    328  *  Requires:
    329  *      pMapAddr is not NULL
    330  *      PROC Initialized.
    331  *  Ensures:
    332  *  Details:
    333  */
    334 	extern DBAPI DSPProcessor_UnMap(DSP_HPROCESSOR hProcessor,
    335 					PVOID pMapAddr);
    336 
    337 /*
    338  *  ======== DSPProcessor_UnReserveMemory ========
    339  *  Purpose:
    340  *      Frees a previously reserved region of DSP address space.
    341  *  Parameters:
    342  *      hProcessor      :   The processor handle.
    343  *      pRsvAddr        :   Ptr to DSP side reservedBYTE address.
    344  *  Returns:
    345  *      DSP_SOK         :   Success.
    346  *      DSP_EHANDLE     :   Invalid processor handle.
    347  *      DSP_EFAIL       :   General failure.
    348  *      DSP_ENOTFOUND   :   Cannot find a reserved region starting with this
    349  *                      :   address.
    350  *  Requires:
    351  *      pRsvAddr is not NULL
    352  *      PROC Initialized.
    353  *  Ensures:
    354  *  Details:
    355  */
    356 	extern DBAPI DSPProcessor_UnReserveMemory(DSP_HPROCESSOR hProcessor,
    357 						  PVOID pRsvAddr);
    358 
    359 #ifdef __cplusplus
    360 }
    361 #endif
    362 #endif				/* DSPPROCESSOR_ */
    363