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