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

dsp/inc/mpcs.h

Go to the documentation of this file.
00001 /** ============================================================================
00002  *  @file   mpcs.h
00003  *
00004  *  @path   $(DSPLINK)/dsp/inc/
00005  *
00006  *  @brief  Defines the interfaces and data structures for the MPCS-Multi
00007  *          Processor Critical Section, sub-component.
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 
00053 #if defined (__cplusplus)
00054 extern "C" {
00055 #endif /* defined (__cplusplus) */
00056 
00057 
00058 /** ============================================================================
00059  *  @func   MPCS_create
00060  *
00061  *  @brief  This function creates and initializes an instance of the MPCS
00062  *          object.
00063  *          The memory for the object may or may not be provided by the user.
00064  *          If provided by the user, the memory for the object must be shared
00065  *          across the processors using the MPCS. It must also already be mapped
00066  *          into user space for OSes supporting user/kernel separation.
00067  *
00068  *  @param procId
00069  *              ID of the processor with which the MPCS object is to be shared.
00070  *  @param name
00071  *              System-wide unique name for the MPCS object.
00072  *  @param mpcsObj
00073  *              Pointer to the shared MPCS object.
00074  *              If memory for the MPCS object is provided by the user, the MPCS
00075  *              object handle is not NULL.
00076  *              Otherwise, if the memory is to be allocated by the MPCS
00077  *              component, the MPCS object handle can be specified as NULL.
00078  *  @param attrs
00079  *              Attributes for creation of the MPCS object.
00080  *
00081  *  @return SYS_OK
00082  *              Operation successfully completed.
00083  *          SYS_EINVAL
00084  *              Invalid argument.
00085  *          SYS_EALLOC
00086  *              Operation failed due to a memory error.
00087  *          SYS_EBUSY
00088  *              The specified MPCS name already exists.
00089  *          SYS_ENOTFOUND
00090  *              All MPCS entries are currently in use.
00091  *          SYS_EDEAD
00092  *              The MPCS component has not been initialized.
00093  *
00094  *  @pre    name must be valid.
00095  *          attrs must be valid.
00096  *
00097  *  @post   None
00098  *
00099  *  @see    MPCS_delete ()
00100  *  ============================================================================
00101  */
00102 Int
00103 MPCS_create (IN     Uint16         procId,
00104              IN     Char *         name,
00105              IN     MPCS_ShObj *   mpcsObj,
00106              IN     MPCS_Attrs *   attrs) ;
00107 
00108 
00109 /** ============================================================================
00110  *  @func   MPCS_delete
00111  *
00112  *  @brief  This function deletes the instance of the MPCS object.
00113  *
00114  *  @param procId
00115  *              ID of the processor with which the MPCS is shared.
00116  *  @param name
00117  *              System-wide unique name for the MPCS object.
00118  *
00119  *  @return SYS_OK
00120  *              Operation successfully completed.
00121  *          SYS_EINVAL
00122  *              Invalid argument.
00123  *          SYS_EFREE
00124  *              Operation failed due to a memory error.
00125  *          SYS_ENOTFOUND
00126  *              Specified MPCS object name does not exist.
00127  *          SYS_EDEAD
00128  *              The MPCS component has not been initialized.
00129  *
00130  *  @pre    name must be valid.
00131  *
00132  *  @post   None
00133  *
00134  *  @see    MPCS_create ()
00135  *  ============================================================================
00136  */
00137 Int
00138 MPCS_delete (IN     Uint16      procId,
00139              IN     Char *      name) ;
00140 
00141 
00142 /** ============================================================================
00143  *  @func   MPCS_open
00144  *
00145  *  @brief  This function opens an MPCS object specified by its name and gets a
00146  *          handle to the object.
00147  *          Every process that needs to use the MPCS object must get a handle to
00148  *          the object by calling this API.
00149  *
00150  *  @param procId
00151  *              ID of the processor with which the MPCS object is to be shared.
00152  *  @param name
00153  *              System-wide unique name for the MPCS object.
00154  *  @param mpcsHandle
00155  *              Location to receive the MPCS object handle, which is valid in
00156  *              the process space of the calling process.
00157  *
00158  *  @return SYS_OK
00159  *              Operation successfully completed.
00160  *          SYS_EINVAL
00161  *              Invalid argument.
00162  *          SYS_EALLOC
00163  *              Operation failed due to a memory error.
00164  *          SYS_ENOTFOUND
00165  *              Specified MPCS object name does not exist.
00166  *          SYS_EDEAD
00167  *              The MPCS component has not been initialized.
00168  *
00169  *  @pre    name must be valid.
00170  *          mpcsHandle must be a valid pointer.
00171  *
00172  *  @post   None
00173  *
00174  *  @see    MPCS_close ()
00175  *  ============================================================================
00176  */
00177 Int
00178 MPCS_open (IN     Uint16         procId,
00179            IN     Char *         name,
00180            OUT    MPCS_Handle *  mpcsHandle) ;
00181 
00182 
00183 /** ============================================================================
00184  *  @func   MPCS_close
00185  *
00186  *  @brief  This function closes an MPCS object specified by its handle.
00187  *
00188  *  @param procId
00189  *              ID of the processor with which the MPCS is shared.
00190  *  @param mpcsHandle
00191  *              Handle to the MPCS object to be closed.
00192  *
00193  *  @return SYS_OK
00194  *              Operation successfully completed.
00195  *          SYS_EINVAL
00196  *              Invalid argument.
00197  *          SYS_EFREE
00198  *              Operation failed due to a memory error.
00199  *          SYS_ENOTFOUND
00200  *              Specified MPCS object name does not exist.
00201  *          SYS_EDEAD
00202  *              The MPCS component has not been initialized.
00203  *
00204  *  @pre    mpcsHandle must be valid.
00205  *
00206  *  @post   None
00207  *
00208  *  @see    MPCS_open ()
00209  *  ============================================================================
00210  */
00211 Int
00212 MPCS_close (IN     Uint16         procId,
00213             IN     MPCS_Handle    mpcsHandle) ;
00214 
00215 
00216 /** ============================================================================
00217  *  @func   MPCS_enter
00218  *
00219  *  @brief  This function enters the critical section specified by the MPCS
00220  *          object.
00221  *
00222  *  @param mpcsHandle
00223  *              Handle to the MPCS object.
00224  *
00225  *  @return SYS_OK
00226  *              Operation successfully completed.
00227  *          SYS_EINVAL
00228  *              Invalid argument.
00229  *
00230  *  @pre    mpcsHandle must be valid.
00231  *
00232  *  @post   None
00233  *
00234  *  @see    MPCS_leave ()
00235  *  ============================================================================
00236  */
00237 Int
00238 MPCS_enter (IN     MPCS_Handle mpcsHandle) ;
00239 
00240 
00241 /** ============================================================================
00242  *  @func   MPCS_leave
00243  *
00244  *  @brief  This function leaves the critical section specified by the MPCS
00245  *          object.
00246  *
00247  *  @param mpcsHandle
00248  *              Handle to the MPCS object.
00249  *
00250  *  @return SYS_OK
00251  *              Operation successfully completed.
00252  *          SYS_EINVAL
00253  *              Invalid argument.
00254  *
00255  *  @pre    mpcsHandle must be valid.
00256  *
00257  *  @post   None
00258  *
00259  *  @see    MPCS_enter ()
00260  *  ============================================================================
00261  */
00262 Int
00263 MPCS_leave (IN     MPCS_Handle mpcsHandle) ;
00264 
00265 
00266 #if defined (__cplusplus)
00267 }
00268 #endif /* defined (__cplusplus) */
00269 
00270 
00271 #endif /* !defined (MPCS_H) */

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