Main Page | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

gpp/inc/mpcs.h

Go to the documentation of this file.
00001 /** ============================================================================
00002  *  @file   mpcs.h
00003  *
00004  *  @path   $(DSPLINK)/gpp/inc/usr/
00005  *
00006  *  @brief  Defines the interfaces and data structures for the API sub-component
00007  *          MPCS for Multi-Processor Critical Section.
00008  *
00009  *  @ver    1.65.00.03
00010  *  ============================================================================
00011  *  @copyright Copyright (C) 2002-2009, Texas Instruments Incorporated -
00012  *  http://www.ti.com/
00013  *
00014  *  Redistribution and use in source and binary forms, with or without
00015  *  modification, are permitted provided that the following conditions
00016  *  are met:
00017  *  
00018  *  *  Redistributions of source code must retain the above copyright
00019  *     notice, this list of conditions and the following disclaimer.
00020  *  
00021  *  *  Redistributions in binary form must reproduce the above copyright
00022  *     notice, this list of conditions and the following disclaimer in the
00023  *     documentation and/or other materials provided with the distribution.
00024  *  
00025  *  *  Neither the name of Texas Instruments Incorporated nor the names of
00026  *     its contributors may be used to endorse or promote products derived
00027  *     from this software without specific prior written permission.
00028  *  
00029  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00030  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
00031  *  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00032  *  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
00033  *  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00034  *  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00035  *  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
00036  *  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
00037  *  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
00038  *  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
00039  *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00040  *  ============================================================================
00041  */
00042 
00043 
00044 #if !defined (MPCS_H)
00045 #define MPCS_H
00046 
00047 
00048 /*  ----------------------------------- DSP/BIOS LINK Headers       */
00049 #include <dsplink.h>
00050 #include <mpcsdefs.h>
00051 
00052 #if defined (__cplusplus)
00053 extern "C" {
00054 #endif /* defined (__cplusplus) */
00055 
00056 
00057 /** ============================================================================
00058  *  @func   MPCS_create
00059  *
00060  *  @brief  This function creates and initializes an instance of the MPCS
00061  *          object.
00062  *          The memory for the object may or may not be provided by the user.
00063  *          If provided by the user, the memory for the object must be shared
00064  *          across the processors using the MPCS. It must also already be mapped
00065  *          into user space for OSes supporting user/kernel separation.
00066  *
00067  *  @param procId
00068  *              ID of the processor with which the MPCS object is to be shared.
00069  *  @param name
00070  *              System-wide unique name for the MPCS object.
00071  *  @param mpcsShObj
00072  *              Pointer to the shared MPCS object.
00073  *              If memory for the MPCS object is provided by the user, the MPCS
00074  *              object handle is not NULL.
00075  *              Otherwise, if the memory is to be allocated by the MPCS
00076  *              component, the MPCS object handle can be specified as NULL.
00077  *  @param attrs
00078  *              Attributes for creation of the MPCS object.
00079  *
00080  *  @return DSP_SOK
00081  *              Operation successfully completed.
00082  *          DSP_EINVALIDARG
00083  *              Invalid argument.
00084  *          DSP_EMEMORY
00085  *              Operation failed due to a memory error.
00086  *          DSP_EALREADYEXISTS
00087  *              The specified MPCS name already exists.
00088  *          DSP_ERESOURCE
00089  *              All MPCS entries are currently in use.
00090  *          DSP_EACCESSDENIED
00091  *              The MPCS component has not been initialized.
00092  *          DSP_EFAIL
00093  *              General failure.
00094  *
00095  *  @pre    procId must be valid.
00096  *          name must be valid.
00097  *          attrs must be valid.
00098  *
00099  *  @post   None
00100  *
00101  *  @see    MPCS_delete ()
00102  *  ============================================================================
00103  */
00104 EXPORT_API
00105 DSP_STATUS
00106 MPCS_create (IN     ProcessorId    procId,
00107              IN     Pstr           name,
00108              IN     MPCS_ShObj *   mpcsShObj,
00109              IN     MPCS_Attrs *   attrs) ;
00110 
00111 
00112 /** ============================================================================
00113  *  @func   MPCS_delete
00114  *
00115  *  @brief  This function deletes the instance of the MPCS object.
00116  *
00117  *  @param procId
00118  *              ID of the processor with which the MPCS is shared.
00119  *  @param name
00120  *              System-wide unique name for the MPCS object.
00121  *
00122  *  @return DSP_SOK
00123  *              Operation successfully completed.
00124  *          DSP_EINVALIDARG
00125  *              Invalid argument.
00126  *          DSP_EMEMORY
00127  *              Operation failed due to a memory error.
00128  *          DSP_ENOTFOUND
00129  *              Specified MPCS object name does not exist.
00130  *          DSP_EACCESSDENIED
00131  *              The MPCS component has not been initialized.
00132  *          DSP_EFAIL
00133  *              General failure.
00134  *
00135  *  @pre    procId must be valid.
00136  *          name must be valid.
00137  *
00138  *  @post   None
00139  *
00140  *  @see    MPCS_create ()
00141  *  ============================================================================
00142  */
00143 EXPORT_API
00144 DSP_STATUS
00145 MPCS_delete (IN     ProcessorId procId,
00146              IN     Pstr        name) ;
00147 
00148 
00149 /** ============================================================================
00150  *  @func   MPCS_open
00151  *
00152  *  @brief  This function opens an MPCS object specified by its name and gets a
00153  *          handle to the object.
00154  *          Every process that needs to use the MPCS object must get a handle to
00155  *          the object by calling this API.
00156  *
00157  *  @param procId
00158  *              ID of the processor with which the MPCS object is to be shared.
00159  *  @param name
00160  *              System-wide unique name for the MPCS object.
00161  *  @param mpcsHandle
00162  *              Location to receive the MPCS object handle, which is valid in
00163  *              the process space of the calling process.
00164  *
00165  *  @return DSP_SOK
00166  *              Operation successfully completed.
00167  *          DSP_SEXISTS
00168  *              The MPCS connection already exists.
00169  *          DSP_EINVALIDARG
00170  *              Invalid argument.
00171  *          DSP_EMEMORY
00172  *              Operation failed due to a memory error.
00173  *          DSP_ENOTFOUND
00174  *              Specified MPCS object name does not exist.
00175  *          DSP_EACCESSDENIED
00176  *              The MPCS component has not been initialized.
00177  *          DSP_EFAIL
00178  *              General failure.
00179  *
00180  *  @pre    procId must be valid.
00181  *          name must be valid.
00182  *          mpcsHandle must be a valid pointer.
00183  *
00184  *  @post   None
00185  *
00186  *  @see    MPCS_close ()
00187  *  ============================================================================
00188  */
00189 EXPORT_API
00190 DSP_STATUS
00191 MPCS_open (IN     ProcessorId    procId,
00192            IN     Pstr           name,
00193            OUT    MPCS_Handle *  mpcsHandle) ;
00194 
00195 
00196 /** ============================================================================
00197  *  @func   MPCS_close
00198  *
00199  *  @brief  This function closes an MPCS object specified by its handle.
00200  *
00201  *  @param procId
00202  *              ID of the processor with which the MPCS is shared.
00203  *  @param mpcsHandle
00204  *              Handle to the MPCS object to be closed.
00205  *
00206  *  @return DSP_SOK
00207  *              Operation successfully completed.
00208  *          DSP_SFREE
00209  *              The last close for specified MPCS resulted in it getting closed.
00210  *          DSP_EINVALIDARG
00211  *              Invalid argument.
00212  *          DSP_EMEMORY
00213  *              Operation failed due to a memory error.
00214  *          DSP_ENOTFOUND
00215  *              Specified MPCS object name does not exist.
00216  *          DSP_EACCESSDENIED
00217  *              The MPCS component has not been initialized.
00218  *          DSP_EFAIL
00219  *              General failure.
00220  *
00221  *  @pre    procId must be valid.
00222  *          mpcsHandle must be valid.
00223  *
00224  *  @post   None
00225  *
00226  *  @see    MPCS_open ()
00227  *  ============================================================================
00228  */
00229 EXPORT_API
00230 DSP_STATUS
00231 MPCS_close (IN     ProcessorId    procId,
00232             IN     MPCS_Handle    mpcsHandle) ;
00233 
00234 
00235 /** ============================================================================
00236  *  @func   MPCS_enter
00237  *
00238  *  @brief  This function enters the critical section specified by the MPCS
00239  *          object.
00240  *
00241  *  @param mpcsHandle
00242  *              Handle to the MPCS object.
00243  *
00244  *  @return DSP_SOK
00245  *              Operation successfully completed.
00246  *          DSP_EFAIL
00247  *              General failure.
00248  *
00249  *  @pre    mpcsHandle must be valid.
00250  *
00251  *  @post   None
00252  *
00253  *  @see    MPCS_leave ()
00254  *  ============================================================================
00255  */
00256 EXPORT_API
00257 DSP_STATUS
00258 MPCS_enter (IN     MPCS_Handle mpcsHandle) ;
00259 
00260 
00261 /** ============================================================================
00262  *  @func   MPCS_leave
00263  *
00264  *  @brief  This function leaves the critical section specified by the MPCS
00265  *          object.
00266  *
00267  *  @param mpcsHandle
00268  *              Handle to the MPCS object.
00269  *
00270  *  @return DSP_SOK
00271  *              Operation successfully completed.
00272  *          DSP_EFAIL
00273  *              General failure.
00274  *
00275  *  @pre    mpcsHandle must be valid.
00276  *
00277  *  @post   None
00278  *
00279  *  @see    MPCS_enter ()
00280  *  ============================================================================
00281  */
00282 EXPORT_API
00283 DSP_STATUS
00284 MPCS_leave (IN     MPCS_Handle mpcsHandle) ;
00285 
00286 
00287 #if defined (__cplusplus)
00288 }
00289 #endif /* defined (__cplusplus) */
00290 
00291 
00292 #endif /* !defined (MPCS_H) */

Generated on Fri Jul 16 14:34:02 2010 for DSP/BIOSLink by  doxygen 1.4.4