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) */