00001 /** 00002 * @file ProcMgr.h 00003 * 00004 * @brief The Processor Manager on a master processor provides control 00005 * functionality for a slave device.<br> 00006 * 00007 * The ProcMgr module provides the following services for the 00008 * slave processor:<br> 00009 * 00010 * -Slave processor boot-loading<br> 00011 * -Read from or write to slave processor memory<br> 00012 * -Slave processor power management<br> 00013 * -Slave processor error handling<br> 00014 * -Dynamic Memory Mapping<br> 00015 * 00016 * The Device Manager (Processor module) shall have interfaces for:<br> 00017 * 00018 * -Loader: There may be multiple implementations of the Loader 00019 * interface within a single Processor instance. 00020 * For example, COFF, ELF, dynamic loader, custom types 00021 * of loaders may be written and plugged in.<br> 00022 * 00023 * -Power Manager: The Power Manager implementation can be a 00024 * separate module that is plugged into the Processor 00025 * module. This allows the Processor code to remain 00026 * generic, and the Power Manager may be written and 00027 * maintained either by a separate team, or by customer.<br> 00028 * 00029 * -Processor: The implementation of this interface provides all 00030 * other functionality for the slave processor, including 00031 * setup and initialization of the Processor module, 00032 * management of slave processor MMU (if available), 00033 * functions to write to and read from slave memory etc.<br> 00034 * 00035 * All processors in the system shall be identified by unique 00036 * processor ID. The management of this processor ID is done by the 00037 * MultiProc module.<br> 00038 * 00039 * 00040 * @ver 02.00.00.68_beta1 00041 * 00042 * ============================================================================ 00043 * 00044 * Copyright (c) 2008-2009, Texas Instruments Incorporated 00045 * 00046 * Redistribution and use in source and binary forms, with or without 00047 * modification, are permitted provided that the following conditions 00048 * are met: 00049 * 00050 * * Redistributions of source code must retain the above copyright 00051 * notice, this list of conditions and the following disclaimer. 00052 * 00053 * * Redistributions in binary form must reproduce the above copyright 00054 * notice, this list of conditions and the following disclaimer in the 00055 * documentation and/or other materials provided with the distribution. 00056 * 00057 * * Neither the name of Texas Instruments Incorporated nor the names of 00058 * its contributors may be used to endorse or promote products derived 00059 * from this software without specific prior written permission. 00060 * 00061 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 00062 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 00063 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 00064 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 00065 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 00066 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 00067 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 00068 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 00069 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 00070 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 00071 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00072 * Contact information for paper mail: 00073 * Texas Instruments 00074 * Post Office Box 655303 00075 * Dallas, Texas 75265 00076 * Contact information: 00077 * http://www-k.ext.ti.com/sc/technical-support/product-information-centers.htm? 00078 * DCMP=TIHomeTracking&HQS=Other+OT+home_d_contact 00079 * ============================================================================ 00080 * 00081 */ 00082 00083 00084 #ifndef ProcMgr_H_0xf2ba 00085 #define ProcMgr_H_0xf2ba 00086 00087 #if defined (__cplusplus) 00088 extern "C" { 00089 #endif 00090 00091 00092 /* ============================================================================= 00093 * All success and failure codes for the module 00094 * ============================================================================= 00095 */ 00096 /*! 00097 * @def ProcMgr_S_OPENHANDLE 00098 * @brief Other ProcMgr clients have still setup the ProcMgr module. 00099 */ 00100 #define ProcMgr_S_SETUP 5 00101 00102 /*! 00103 * @def ProcMgr_S_OPENHANDLE 00104 * @brief Other ProcMgr handles are still open in this process. 00105 */ 00106 #define ProcMgr_S_OPENHANDLE 4 00107 00108 /*! 00109 * @def ProcMgr_S_ALREADYEXISTS 00110 * @brief The ProcMgr instance has already been created/opened in this process 00111 */ 00112 #define ProcMgr_S_ALREADYEXISTS 3 00113 /*! 00114 * @def ProcMgr_S_BUSY 00115 * @brief The resource is still in use 00116 */ 00117 #define ProcMgr_S_BUSY 2 00118 00119 /*! 00120 * @def ProcMgr_S_ALREADYSETUP 00121 * @brief The module has been already setup 00122 */ 00123 #define ProcMgr_S_ALREADYSETUP 1 00124 00125 /*! 00126 * @def ProcMgr_S_SUCCESS 00127 * @brief Operation is successful. 00128 */ 00129 #define ProcMgr_S_SUCCESS 0 00130 00131 /*! 00132 * @def ProcMgr_E_FAIL 00133 * @brief Generic failure. 00134 */ 00135 #define ProcMgr_E_FAIL -1 00136 00137 /*! 00138 * @def ProcMgr_E_INVALIDARG 00139 * @brief Argument passed to function is invalid. 00140 */ 00141 #define ProcMgr_E_INVALIDARG -2 00142 00143 /*! 00144 * @def ProcMgr_E_MEMORY 00145 * @brief Operation resulted in memory failure. 00146 */ 00147 #define ProcMgr_E_MEMORY -3 00148 00149 /*! 00150 * @def ProcMgr_E_ALREADYEXISTS 00151 * @brief The specified entity already exists. 00152 */ 00153 #define ProcMgr_E_ALREADYEXISTS -4 00154 00155 /*! 00156 * @def ProcMgr_E_NOTFOUND 00157 * @brief Unable to find the specified entity. 00158 */ 00159 #define ProcMgr_E_NOTFOUND -5 00160 00161 /*! 00162 * @def ProcMgr_E_TIMEOUT 00163 * @brief Operation timed out. 00164 */ 00165 #define ProcMgr_E_TIMEOUT -6 00166 00167 /*! 00168 * @def ProcMgr_E_INVALIDSTATE 00169 * @brief Module is not initialized. 00170 */ 00171 #define ProcMgr_E_INVALIDSTATE -7 00172 00173 /*! 00174 * @def ProcMgr_E_OSFAILURE 00175 * @brief A failure occurred in an OS-specific call 00176 */ 00177 #define ProcMgr_E_OSFAILURE -8 00178 00179 /*! 00180 * @def ProcMgr_E_RESOURCE 00181 * @brief Specified resource is not available 00182 */ 00183 #define ProcMgr_E_RESOURCE -9 00184 00185 /*! 00186 * @def ProcMgr_E_RESTART 00187 * @brief Operation was interrupted. Please restart the operation 00188 */ 00189 #define ProcMgr_E_RESTART -10 00190 00191 /*! 00192 * @def ProcMgr_E_HANDLE 00193 * @brief Invalid object handle specified 00194 */ 00195 #define ProcMgr_E_HANDLE -11 00196 00197 /*! 00198 * @def ProcMgr_E_ACCESSDENIED 00199 * @brief The operation is not permitted in this process. 00200 */ 00201 #define ProcMgr_E_ACCESSDENIED -12 00202 00203 /*! 00204 * @def ProcMgr_E_TRANSLATE 00205 * @brief An address translation error occurred. 00206 */ 00207 #define ProcMgr_E_TRANSLATE -13 00208 00209 /*! 00210 * @def ProcMgr_E_SYMBOLNOTFOUND 00211 * @brief Could not find the specified symbol in the loaded file 00212 */ 00213 #define ProcMgr_E_SYMBOLNOTFOUND -14 00214 00215 /*! 00216 * @def ProcMgr_E_MAP 00217 * @brief Failed to map/unmap an address range 00218 */ 00219 #define ProcMgr_E_MAP -15 00220 00221 00222 /* ============================================================================= 00223 * Macros and types 00224 * ============================================================================= 00225 */ 00226 /*! 00227 * @brief Maximum number of memory regions supported by ProcMgr module. 00228 */ 00229 #define ProcMgr_MAX_MEMORY_REGIONS 32u 00230 00231 /*! 00232 * @def IS_VALID_PROCID 00233 * @brief Checks if the Processor ID is valid 00234 */ 00235 #define IS_VALID_PROCID(id) (id < MultiProc_MAXPROCESSORS) 00236 00237 /*! 00238 * @brief Defines ProcMgr object handle 00239 */ 00240 typedef struct ProcMgr_Object * ProcMgr_Handle; 00241 00242 00243 /*! 00244 * @brief Enumerations to indicate Processor states. 00245 */ 00246 typedef enum { 00247 ProcMgr_State_Unknown = 0u, 00248 /*!< Unknown Processor state (e.g. at startup or error). */ 00249 ProcMgr_State_Powered = 1u, 00250 /*!< Indicates the Processor is powered up. */ 00251 ProcMgr_State_Reset = 2u, 00252 /*!< Indicates the Processor is reset. */ 00253 ProcMgr_State_Loaded = 3u, 00254 /*!< Indicates the Processor is loaded. */ 00255 ProcMgr_State_Running = 4u, 00256 /*!< Indicates the Processor is running. */ 00257 ProcMgr_State_Unavailable = 5u, 00258 /*!< Indicates the Processor is unavailable to the physical transport. */ 00259 ProcMgr_State_EndValue = 6u 00260 /*!< End delimiter indicating start of invalid values for this enum */ 00261 } ProcMgr_State ; 00262 00263 /*! 00264 * @brief Enumerations to indicate different types of slave boot modes. 00265 */ 00266 typedef enum { 00267 ProcMgr_BootMode_Boot = 0u, 00268 /*!< ProcMgr is responsible for loading the slave and its reset control. */ 00269 ProcMgr_BootMode_NoLoad_Pwr = 1u, 00270 /*!< ProcMgr is not responsible for loading the slave. It is responsible 00271 for reset control of the slave. */ 00272 ProcMgr_BootMode_NoLoad_NoPwr = 2u, 00273 /*!< ProcMgr is not responsible for loading the slave. It is partial responsible 00274 for reset control of the slave. It doesn't put in reset while procMgr_attach 00275 but release reset while procMgr_start operation. */ 00276 ProcMgr_BootMode_NoBoot = 3u, 00277 /*!< ProcMgr is not responsible for loading or reset control of the slave. 00278 The slave either self-boots, or this is done by some entity outside of 00279 the ProcMgr module. */ 00280 ProcMgr_BootMode_EndValue = 4u 00281 /*!< End delimiter indicating start of invalid values for this enum */ 00282 } ProcMgr_BootMode ; 00283 00284 /*! 00285 * @brief Enumerations to indicate address types used for translation 00286 */ 00287 typedef enum { 00288 ProcMgr_AddrType_MasterKnlVirt = 0u, 00289 /*!< Kernel Virtual address on master processor */ 00290 ProcMgr_AddrType_MasterUsrVirt = 1u, 00291 /*!< User Virtual address on master processor */ 00292 ProcMgr_AddrType_MasterPhys = 2u, 00293 /*!< Physical address on master processor */ 00294 ProcMgr_AddrType_SlaveVirt = 3u, 00295 /*!< Virtual address on slave processor */ 00296 ProcMgr_AddrType_SlavePhys = 4u, 00297 /*!< Physical address on slave processor */ 00298 ProcMgr_AddrType_EndValue = 5u 00299 /*!< End delimiter indicating start of invalid values for this enum */ 00300 } ProcMgr_AddrType; 00301 00302 /*! 00303 * @brief Enumerations to indicate address mask types used for mapping 00304 */ 00305 typedef enum { 00306 ProcMgr_MapType_MasterKnlVirt = 0x0001u, 00307 /*!< Kernel Virtual address on master processor */ 00308 ProcMgr_MapType_MasterUsrVirt = 0x0002u, 00309 /*!< User Virtual address on master processor */ 00310 ProcMgr_MapType_SlaveVirt = 0x0004u, 00311 /*!< Virtual address on slave processor */ 00312 ProcMgr_MapType_EndValue = 0x0008u 00313 /*!< End delimiter indicating start of invalid values for this enum */ 00314 } ProcMgr_MapType; 00315 00316 /*! 00317 * @brief Configuration parameters specific to the slave ProcMgr instance. 00318 */ 00319 typedef struct ProcMgr_AttachParams_tag { 00320 ProcMgr_BootMode bootMode; 00321 /*!< Boot mode for the slave processor. */ 00322 Ptr bootParams; 00323 /*!< Params for dependent processors like IVHD for netra. */ 00324 } ProcMgr_AttachParams ; 00325 00326 /*! 00327 * @brief Configuration parameters to be provided while starting the slave 00328 * processor. 00329 */ 00330 typedef struct ProcMgr_StartParams_tag { 00331 UInt32 reserved; 00332 /*!< Reserved for future params. */ 00333 } ProcMgr_StartParams ; 00334 00335 00336 /*! 00337 * @brief This structure defines information about memory regions mapped by 00338 * the ProcMgr module. 00339 */ 00340 typedef struct ProcMgr_AddrInfo_tag { 00341 UInt32 addr [ProcMgr_AddrType_EndValue]; 00342 /*!< Addresses for each type of address space */ 00343 UInt32 size; 00344 /*!< Size of the memory region in bytes */ 00345 Bool isCached; 00346 /*!< Region cached? */ 00347 } ProcMgr_AddrInfo; 00348 00349 /*! @brief Structure containing information of mapped memory regions */ 00350 typedef struct ProcMgr_MappedMemEntry { 00351 ProcMgr_AddrInfo info; 00352 /*!< Address information */ 00353 ProcMgr_AddrType srcAddrType; 00354 /*!< Source address type used for mapping */ 00355 ProcMgr_MapType mapType; 00356 /*!< Mapping type */ 00357 Bool inUse; 00358 /*!< Entry index is in use? */ 00359 } ProcMgr_MappedMemEntry; 00360 00361 /*! 00362 * @brief Characteristics of the slave processor 00363 */ 00364 typedef struct ProcMgr_ProcInfo_tag { 00365 ProcMgr_BootMode bootMode; 00366 /*!< Boot mode of the processor. */ 00367 UInt16 numMemEntries; 00368 /*!< Number of valid memory entries */ 00369 ProcMgr_MappedMemEntry memEntries [ProcMgr_MAX_MEMORY_REGIONS]; 00370 /*!< Configuration of memory regions */ 00371 } ProcMgr_ProcInfo; 00372 00373 00374 /*! 00375 * @brief Characteristics of sections in executable 00376 */ 00377 typedef struct ProcMgr_SectionInfo_tag { 00378 UInt32 physicalAddress; 00379 /*!< Requested/returned section's physicalAddress */ 00380 UInt32 virtualAddress; 00381 /*!< Requested/returned section's vitualAddress */ 00382 UInt16 sectId; 00383 /*!< Requested/returned section id */ 00384 UInt32 size; 00385 /*!< Section size */ 00386 } ProcMgr_SectionInfo; 00387 00388 /*! 00389 * @brief Function pointer type that is passed to the 00390 * ProcMgr_registerNotify function 00391 * 00392 * @param procId Processor ID for the processor that is undergoing the 00393 * state change. 00394 * @param handle Handle to the processor instance. 00395 * @param fromState Previous processor state 00396 * @param toState New processor state 00397 * 00398 * @sa ProcMgr_registerNotify 00399 */ 00400 typedef Int (*ProcMgr_CallbackFxn) (UInt16 procId, 00401 ProcMgr_Handle handle, 00402 ProcMgr_State fromState, 00403 ProcMgr_State toState); 00404 00405 /* ============================================================================= 00406 * APIs 00407 * ============================================================================= 00408 */ 00409 /*! 00410 * @brief Function to open a handle to an existing ProcMgr object handling 00411 * the procId. 00412 * 00413 * This function returns a handle to an existing ProcMgr instance 00414 * created for this procId. It enables other entities to access 00415 * and use this ProcMgr instance. 00416 * 00417 * @param handlePtr Return Parameter: Handle to the ProcMgr instance 00418 * @param procId Processor ID represented by this ProcMgr instance 00419 * 00420 * @retval ProcMgr_S_SUCCESS Operation successful 00421 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00422 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00423 * @retval ProcMgr_S_ALREADYEXISTS Object is already created/opened in this 00424 * process 00425 * @retval ProcMgr_E_MAP Failed to map address range to host OS 00426 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00427 * @retval ProcMgr_E_MEMORY Memory allocation failed 00428 * 00429 * @sa ProcMgr_close, Memory_calloc 00430 */ 00431 Int ProcMgr_open (ProcMgr_Handle * handlePtr, UInt16 procId); 00432 00433 /*! 00434 * @brief Function to close this handle to the ProcMgr instance. 00435 * 00436 * This function closes the handle to the ProcMgr instance 00437 * obtained through ProcMgr_open call made earlier. The handle in 00438 * the passed pointer is reset on success. 00439 * 00440 * @param handlePtr Pointer to the ProcMgr handle 00441 * 00442 * @retval ProcMgr_S_SUCCESS Operation successful 00443 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00444 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00445 * @retval ProcMgr_E_ACCESSDENIED All open handles to this ProcMgr object 00446 * are already closed 00447 * @retval ProcMgr_S_OPENHANDLE Other threads in this process have 00448 * already opened handles to this ProcMgr 00449 * instance. 00450 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00451 * 00452 * @sa ProcMgr_open, Memory_free 00453 */ 00454 Int ProcMgr_close (ProcMgr_Handle * handlePtr); 00455 00456 /*! 00457 * @brief Function to initialize the parameters for the ProcMgr attach 00458 * function. 00459 * 00460 * This function can be called by the application to get their 00461 * configuration parameter to #ProcMgr_attach filled in by the 00462 * ProcMgr module with the default parameters. If the user does 00463 * not wish to make any change in the default parameters, this API 00464 * is not required to be called. 00465 * 00466 * @param handle Handle to the ProcMgr object. If specified as NULL, 00467 * the default global configuration values are returned. 00468 * @param params Pointer to the ProcMgr attach params structure in 00469 * which the default params is to be returned. 00470 * 00471 * @sa ProcMgr_attach 00472 */ 00473 Void ProcMgr_getAttachParams (ProcMgr_Handle handle, 00474 ProcMgr_AttachParams * params); 00475 00476 /*! 00477 * @brief Function to attach the client to the specified slave and also 00478 * initialize the slave (if required). 00479 * 00480 * This function attaches to an instance of the ProcMgr module and 00481 * performs any hardware initialization required to power up the 00482 * slave device. This function also performs the required state 00483 * transitions for this ProcMgr instance to ensure that the local 00484 * object representing the slave device correctly indicates the 00485 * state of the slave device. Depending on the slave boot mode 00486 * being used, the slave may be powered up, in reset, or even 00487 * running state. 00488 * Configuration parameters need to be provided to this 00489 * function. If the user wishes to change some specific config 00490 * parameters, then #ProcMgr_getAttachParams can be called to get 00491 * the configuration filled with the default values. After this, 00492 * only the required configuration values can be changed. If the 00493 * user does not wish to make any change in the default parameters, 00494 * the application can simply call ProcMgr_attach with NULL 00495 * parameters. 00496 * The default parameters would get automatically used. 00497 * 00498 * @param handle Handle to the ProcMgr object. 00499 * @param params Optional ProcMgr attach parameters. If provided as 00500 * NULL, default configuration is used. 00501 * 00502 * @retval ProcMgr_S_SUCCESS Operation successful 00503 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00504 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00505 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00506 * @retval ProcMgr_E_MAP Failed to map address range to host OS 00507 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00508 * 00509 * @sa ProcMgr_detach, ProcMgr_getAttachParams 00510 */ 00511 Int ProcMgr_attach (ProcMgr_Handle handle, ProcMgr_AttachParams * params); 00512 00513 /*! 00514 * @brief Function to detach the client from the specified slave and also 00515 * finalze the slave (if required). 00516 * 00517 * This function detaches from an instance of the ProcMgr module 00518 * and performs any hardware finalization required to power down 00519 * the slave device. This function also performs the required state 00520 * transitions for this ProcMgr instance to ensure that the local 00521 * object representing the slave device correctly indicates the 00522 * state of the slave device. Depending on the slave boot mode 00523 * being used, the slave may be powered down, in reset, or left in 00524 * its original state. 00525 * 00526 * @param handle Handle to the ProcMgr object 00527 * 00528 * @retval ProcMgr_S_SUCCESS Operation successful 00529 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00530 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00531 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00532 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00533 * 00534 * @sa ProcMgr_attach 00535 */ 00536 Int ProcMgr_detach (ProcMgr_Handle handle); 00537 00538 /*! 00539 * @brief Function to load the specified slave executable on the slave 00540 * Processor. 00541 * 00542 * This function allows usage of different types of loaders. The 00543 * loader specified when creating this instance of the ProcMgr 00544 * is used for loading the slave executable. Depending on the type 00545 * of loader, the imagePath parameter may point to the path of the 00546 * file in the host file system, or it may be NULL. Some loaders 00547 * may require specific parameters to be passed. This function 00548 * returns a fileId, which can be used for further function calls 00549 * that reference a specific file that has been loaded on the 00550 * slave processor. 00551 * 00552 * @param handle Handle to the ProcMgr object 00553 * @param imagePath Full file path 00554 * @param argc Number of arguments 00555 * @param argv String array of arguments 00556 * @param params Loader specific parameters 00557 * @param fileId Return parameter: ID of the loaded file 00558 * 00559 * @retval ProcMgr_S_SUCCESS Operation successful 00560 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00561 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00562 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00563 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00564 * 00565 * @sa ProcMgr_unload 00566 */ 00567 Int ProcMgr_load (ProcMgr_Handle handle, 00568 String imagePath, 00569 UInt32 argc, 00570 String * argv, 00571 Ptr params, 00572 UInt32 * fileId); 00573 00574 /*! 00575 * @brief Function to unload the previously loaded file on the slave 00576 * processor. 00577 * 00578 * This function unloads the file that was previously loaded on the 00579 * slave processor through the #ProcMgr_load API. It frees up any 00580 * resources that were allocated during ProcMgr_load for this file. 00581 * The fileId received from the load function must be passed to 00582 * this function. 00583 * 00584 * @param handle Handle to the ProcMgr object 00585 * @param fileId ID of the loaded file to be unloaded 00586 * 00587 * @retval ProcMgr_S_SUCCESS Operation successful 00588 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00589 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00590 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00591 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00592 * 00593 * @sa ProcMgr_load 00594 */ 00595 Int ProcMgr_unload (ProcMgr_Handle handle, UInt32 fileId); 00596 00597 /*! 00598 * @brief Function to initialize the parameters for the ProcMgr start 00599 * function. 00600 * 00601 * This function can be called by the application to get their 00602 * configuration parameter to #ProcMgr_start filled in by the 00603 * ProcMgr module with the default parameters. If the user does 00604 * not wish to make any change in the default parameters, this API 00605 * is not required to be called. 00606 * 00607 * @param handle Handle to the ProcMgr object. If specified as NULL, 00608 * the default global configuration values are returned. 00609 * @param params Pointer to the ProcMgr start params structure in 00610 * which the default params is to be returned. 00611 * 00612 * @sa ProcMgr_start 00613 */ 00614 Void ProcMgr_getStartParams (ProcMgr_Handle handle, 00615 ProcMgr_StartParams * params); 00616 00617 /*! 00618 * @brief Function to start the slave processor running. 00619 * 00620 * Function to start execution of the loaded code on the slave 00621 * from the entry point specified in the slave executable loaded 00622 * earlier by call to #ProcMgr_load (). 00623 * After successful completion of this function, the ProcMgr 00624 * instance is expected to be in the #ProcMgr_State_Running state. 00625 * 00626 * @param handle Handle to the ProcMgr object 00627 * @param params Optional ProcMgr start parameters. If provided as NULL, 00628 * default parameters are used. 00629 * 00630 * @retval ProcMgr_S_SUCCESS Operation successful 00631 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00632 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00633 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00634 * @retval ProcMgr_E_SYMBOLNOTFOUND Entry ponit symbol not found in loaded 00635 * file 00636 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00637 * 00638 * @sa ProcMgr_stop 00639 */ 00640 Int ProcMgr_start (ProcMgr_Handle handle, ProcMgr_StartParams * params); 00641 00642 /*! 00643 * @brief Function to stop the slave processor. 00644 * 00645 * Function to stop execution of the slave processor. 00646 * Depending on the boot mode, after successful completion of this 00647 * function, the ProcMgr instance may be in the 00648 * #ProcMgr_State_Reset state. 00649 * 00650 * @param handle Handle to the ProcMgr object 00651 * 00652 * @retval ProcMgr_S_SUCCESS Operation successful 00653 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00654 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00655 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00656 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00657 * 00658 * @sa ProcMgr_start 00659 */ 00660 Int ProcMgr_stop (ProcMgr_Handle handle); 00661 00662 /*! 00663 * @brief Function to get the current state of the slave Processor. 00664 * 00665 * This function gets the state of the slave processor as 00666 * maintained on the master Processor state machine. It does not 00667 * go to the slave processor to get its actual state at the time 00668 * when this API is called. 00669 * 00670 * @param handle Handle to the ProcMgr object 00671 * 00672 * @retval Processor-state Operation successful 00673 * 00674 * @sa 00675 */ 00676 ProcMgr_State ProcMgr_getState (ProcMgr_Handle handle); 00677 00678 /*! 00679 * @brief Function to read from the slave processor's memory. 00680 * 00681 * This function reads from the specified address in the 00682 * processor's address space and copies the required number of 00683 * bytes into the specified buffer. 00684 * It returns the number of bytes actually read in the numBytes 00685 * parameter. 00686 * 00687 * @param handle Handle to the ProcMgr object 00688 * @param procAddr Address in space processor's address space of the 00689 * memory region to read from. 00690 * @param numBytes IN/OUT parameter. As an IN-parameter, it takes in the 00691 * number of bytes to be read. When the function 00692 * returns, this parameter contains the number of bytes 00693 * actually read. 00694 * @param buffer User-provided buffer in which the slave processor's 00695 * memory contents are to be copied. 00696 * 00697 * @retval ProcMgr_S_SUCCESS Operation successful 00698 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00699 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00700 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00701 * @retval ProcMgr_E_TRANSLATE Address is not mapped 00702 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00703 * 00704 * @sa ProcMgr_write 00705 */ 00706 Int ProcMgr_read (ProcMgr_Handle handle, 00707 UInt32 procAddr, 00708 UInt32 * numBytes, 00709 Ptr buffer); 00710 00711 /*! 00712 * @brief Function to write into the slave processor's memory. 00713 * 00714 * This function writes into the specified address in the 00715 * processor's address space and copies the required number of 00716 * bytes from the specified buffer. 00717 * It returns the number of bytes actually written in the numBytes 00718 * parameter. 00719 * 00720 * @param handle Handle to the ProcMgr object 00721 * @param procAddr Address in space processor's address space of the 00722 * memory region to write into. 00723 * @param numBytes IN/OUT parameter. As an IN-parameter, it takes in the 00724 * number of bytes to be written. When the function 00725 * returns, this parameter contains the number of bytes 00726 * actually written. 00727 * @param buffer User-provided buffer from which the data is to be 00728 * written into the slave processor's memory. 00729 * 00730 * @retval ProcMgr_S_SUCCESS Operation successful 00731 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00732 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00733 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00734 * @retval ProcMgr_E_TRANSLATE Address is not mapped 00735 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00736 * 00737 * @sa ProcMgr_read 00738 */ 00739 Int ProcMgr_write (ProcMgr_Handle handle, 00740 UInt32 procAddr, 00741 UInt32 * numBytes, 00742 Ptr buffer); 00743 00744 /*! 00745 * @brief Function to perform device-dependent operations. 00746 * 00747 * This function performs control operations supported by the 00748 * as exposed directly by the specific implementation of the 00749 * Processor interface. These commands and their specific argument 00750 * types are used with this function. 00751 * 00752 * @param handle Handle to the ProcMgr object 00753 * @param cmd Device specific processor command 00754 * @param arg Arguments specific to the type of command. 00755 * 00756 * @retval ProcMgr_S_SUCCESS Operation successful 00757 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00758 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00759 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00760 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00761 * 00762 * @sa 00763 */ 00764 Int ProcMgr_control (ProcMgr_Handle handle, Int32 cmd, Ptr arg); 00765 00766 /*! 00767 * @brief Function to translate between two types of address spaces. 00768 * 00769 * This function translates addresses between two types of address 00770 * spaces. The destination and source address types are indicated 00771 * through parameters specified in this function. 00772 * 00773 * @param handle Handle to the ProcMgr object 00774 * @param dstAddr Return parameter: Pointer to receive the translated 00775 * address. 00776 * @param dstAddrType Destination address type requested 00777 * @param srcAddr Source address in the source address space 00778 * @param srcAddrType Source address type 00779 * 00780 * @retval ProcMgr_S_SUCCESS Operation successful 00781 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00782 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00783 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00784 * @retval ProcMgr_E_TRANSLATE Failed to translate address. 00785 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00786 * 00787 * @sa ProcMgr_AddrType 00788 */ 00789 Int ProcMgr_translateAddr (ProcMgr_Handle handle, 00790 Ptr * dstAddr, 00791 ProcMgr_AddrType dstAddrType, 00792 Ptr srcAddr, 00793 ProcMgr_AddrType srcAddrType); 00794 00795 /*! 00796 * @brief Function to retrieve the target address of a symbol from the 00797 * specified file. 00798 * 00799 * @param handle Handle to the ProcMgr object 00800 * @param fileId ID of the file received from the load function 00801 * @param symbolName Name of the symbol 00802 * @param symValue Return parameter: Symbol address 00803 * 00804 * @retval ProcMgr_S_SUCCESS Operation successful 00805 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00806 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00807 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00808 * @retval ProcMgr_E_SYMBOLNOTFOUND Symbol not found in loaded file 00809 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00810 * 00811 * @sa 00812 */ 00813 Int ProcMgr_getSymbolAddress (ProcMgr_Handle handle, 00814 UInt32 fileId, 00815 String symbolName, 00816 UInt32 * symValue); 00817 00818 /*! 00819 * @brief Function to map address to specified destination type(s). 00820 * 00821 * This function maps the provided address of specified srcAddrType 00822 * to one or more destination address types, and returns the mapped 00823 * addresses and size in the same addrInfo structure. 00824 * 00825 * @param handle Handle to the Processor object 00826 * @param mapType Mask of destination types of mapping to be 00827 * performed. One or more types may be ORed together. 00828 * @param addrInfo Structure containing map info. When this API is 00829 * called, user must provide a valid address for the 00830 * address of srcAddrType. On successful completion of 00831 * this function, this same structure shall contain 00832 * valid addresses for destination address types given 00833 * in mapType. 00834 * @param srcAddrType Source address type. 00835 * 00836 * @retval ProcMgr_S_SUCCESS Operation successful 00837 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00838 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00839 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00840 * @retval ProcMgr_E_MAP Failed to map address range to host OS 00841 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00842 * 00843 * @sa ProcMgr_unmap, ProcMgr_MapType, ProcMgr_AddrInfo 00844 */ 00845 Int ProcMgr_map (ProcMgr_Handle handle, 00846 ProcMgr_MapType mapType, 00847 ProcMgr_AddrInfo * addrInfo, 00848 ProcMgr_AddrType srcAddrType); 00849 00850 /*! 00851 * @brief Function to map address to slave address space. 00852 * 00853 * This function unmaps the provided address(es) of specified 00854 * one or more destination address types. The srcAddrType indicates 00855 * the source address with which the entry for the mapping is to be 00856 * identified. It must be the same address that was specified as 00857 * the src address when the corresponding mapping was performed. 00858 * 00859 * @param handle Handle to the Processor object 00860 * @param mapType Mask of destination types of unmapping to be 00861 * performed. One or more types may be ORed together. 00862 * @param addrInfo Structure containing map info. When this API is 00863 * called, user must provide a valid address for the 00864 * address of srcAddrType, as well as each of the 00865 * destination types given in the mapType mask. On 00866 * successful completion of this function, the 00867 * specified destination mappings are unmapped. 00868 * @param srcAddrType Source address type. 00869 * 00870 * @retval ProcMgr_S_SUCCESS Operation successful 00871 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00872 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00873 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00874 * @retval ProcMgr_E_NOTFOUND Info provided does not match with any 00875 * mapped entry 00876 * @retval ProcMgr_E_MAP Failed to unmap address range from host 00877 * OS 00878 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00879 * 00880 * @sa ProcMgr_map, ProcMgr_MapType, ProcMgr_AddrInfo 00881 */ 00882 Int ProcMgr_unmap (ProcMgr_Handle handle, 00883 ProcMgr_MapType mapType, 00884 ProcMgr_AddrInfo * addrInfo, 00885 ProcMgr_AddrType srcAddrType); 00886 00887 00888 /*! 00889 * @brief Function that registers for notification when the slave 00890 * processor transitions to any of the states specified. 00891 * 00892 * This function allows the user application to register for 00893 * changes in processor state and take actions accordingly. 00894 * 00895 * @param handle Handle to the ProcMgr object 00896 * @param fxn Handling function to be registered. 00897 * @param args Optional arguments associated with the handler fxn. 00898 * @param state Array of target states for which registration is 00899 * required. 00900 * 00901 * @retval ProcMgr_S_SUCCESS Operation successful 00902 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00903 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00904 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00905 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00906 * 00907 * @sa ProcMgr_State, ProcMgr_CallbackFxn 00908 */ 00909 Int ProcMgr_registerNotify (ProcMgr_Handle handle, 00910 ProcMgr_CallbackFxn fxn, 00911 Ptr args, 00912 ProcMgr_State state []); 00913 00914 /*! 00915 * @brief Function that returns information about the characteristics of 00916 * the slave processor. 00917 * 00918 * @param handle Handle to the ProcMgr object 00919 * @param procInfo Pointer to the ProcInfo object to be populated. 00920 * 00921 * @retval ProcMgr_S_SUCCESS Operation successful 00922 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00923 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00924 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00925 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00926 * 00927 * @sa ProcMgr_ProcInfo 00928 */ 00929 Int ProcMgr_getProcInfo (ProcMgr_Handle handle, 00930 ProcMgr_ProcInfo * procInfo); 00931 00932 00933 /*! 00934 * @brief Function that returns section information given the name of 00935 * section and number of bytes to read 00936 * 00937 * @param handle Handle to the ProcMgr object 00938 * @param fileId ID of the file received from the load function 00939 * @param sectionName Name of section to be retrieved 00940 * @param sectionInfo Return parameter: Section information 00941 * 00942 * @retval ProcMgr_S_SUCCESS Operation successful 00943 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00944 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00945 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00946 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00947 * 00948 * @sa ProcMgr_SectionInfo 00949 */ 00950 Int ProcMgr_getSectionInfo (ProcMgr_Handle handle, 00951 UInt32 fileId, 00952 String sectionName, 00953 ProcMgr_SectionInfo * sectionInfo); 00954 00955 /* @brief Function that returns section data in a buffer given section id 00956 * and size to be read 00957 * 00958 * @param handle Handle to the ProcMgr object 00959 * @param fileId ID of the file received from the load function 00960 * @param sectionInfo Structure filled by ProcMgr_getSectionInfo. 00961 * @param buffer Return parameter 00962 * 00963 * @retval ProcMgr_S_SUCCESS Operation successful 00964 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified 00965 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized 00966 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified 00967 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call 00968 * 00969 * @sa ProcMgr_SectionInfo, ProcMgr_getSectionInfo 00970 */ 00971 Int ProcMgr_getSectionData (ProcMgr_Handle handle, 00972 UInt32 fileId, 00973 ProcMgr_SectionInfo * sectionInfo, 00974 Ptr buffer); 00975 00976 00977 /* @brief Function that returns section data in a buffer given section id 00978 * and size to be read 00979 * 00980 * @param handle Handle to the ProcMgr object 00981 * 00982 * @retval fileId Operation successful 00983 * 00984 * @sa ProcMgr_load 00985 */ 00986 UInt32 ProcMgr_getLoadedFileId (ProcMgr_Handle handle); 00987 00988 00989 #if defined (__cplusplus) 00990 } 00991 #endif /* defined (__cplusplus) */ 00992 00993 #endif /* ProcMgr_H_0xf2ba */
1.4.4