The ProcMgr module provides the following services for the slave processor:
-Slave processor boot-loading
-Read from or write to slave processor memory
-Slave processor power management
-Slave processor error handling
-Dynamic Memory Mapping
The Device Manager (Processor module) shall have interfaces for:
-Loader: There may be multiple implementations of the Loader interface within a single Processor instance. For example, COFF, ELF, dynamic loader, custom types of loaders may be written and plugged in.
-Power Manager: The Power Manager implementation can be a separate module that is plugged into the Processor module. This allows the Processor code to remain generic, and the Power Manager may be written and maintained either by a separate team, or by customer.
-Processor: The implementation of this interface provides all other functionality for the slave processor, including setup and initialization of the Processor module, management of slave processor MMU (if available), functions to write to and read from slave memory etc.
All processors in the system shall be identified by unique processor ID. The management of this processor ID is done by the MultiProc module.
02.00.00.68_beta1
============================================================================
Copyright (c) 2008-2009, Texas Instruments Incorporated
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* Neither the name of Texas Instruments Incorporated nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Contact information for paper mail: Texas Instruments Post Office Box 655303 Dallas, Texas 75265 Contact information: http://www-k.ext.ti.com/sc/technical-support/product-information-centers.htm? DCMP=TIHomeTracking&HQS=Other+OT+home_d_contact ============================================================================
Definition in file ProcMgr.h.
Go to the source code of this file.
Data Structures | |
| struct | ProcMgr_AttachParams_tag |
| Configuration parameters specific to the slave ProcMgr instance. More... | |
| struct | ProcMgr_StartParams_tag |
| Configuration parameters to be provided while starting the slave processor. More... | |
| struct | ProcMgr_AddrInfo_tag |
| This structure defines information about memory regions mapped by the ProcMgr module. More... | |
| struct | ProcMgr_MappedMemEntry |
| Structure containing information of mapped memory regions. More... | |
| struct | ProcMgr_ProcInfo_tag |
| Characteristics of the slave processor. More... | |
| struct | ProcMgr_SectionInfo_tag |
| Characteristics of sections in executable. More... | |
Defines | |
| #define | ProcMgr_S_SETUP 5 |
| #define | ProcMgr_S_OPENHANDLE 4 |
| Other ProcMgr clients have still setup the ProcMgr module. | |
| #define | ProcMgr_S_ALREADYEXISTS 3 |
| The ProcMgr instance has already been created/opened in this process. | |
| #define | ProcMgr_S_BUSY 2 |
| The resource is still in use. | |
| #define | ProcMgr_S_ALREADYSETUP 1 |
| The module has been already setup. | |
| #define | ProcMgr_S_SUCCESS 0 |
| Operation is successful. | |
| #define | ProcMgr_E_FAIL -1 |
| Generic failure. | |
| #define | ProcMgr_E_INVALIDARG -2 |
| Argument passed to function is invalid. | |
| #define | ProcMgr_E_MEMORY -3 |
| Operation resulted in memory failure. | |
| #define | ProcMgr_E_ALREADYEXISTS -4 |
| The specified entity already exists. | |
| #define | ProcMgr_E_NOTFOUND -5 |
| Unable to find the specified entity. | |
| #define | ProcMgr_E_TIMEOUT -6 |
| Operation timed out. | |
| #define | ProcMgr_E_INVALIDSTATE -7 |
| Module is not initialized. | |
| #define | ProcMgr_E_OSFAILURE -8 |
| A failure occurred in an OS-specific call. | |
| #define | ProcMgr_E_RESOURCE -9 |
| Specified resource is not available. | |
| #define | ProcMgr_E_RESTART -10 |
| Operation was interrupted. Please restart the operation. | |
| #define | ProcMgr_E_HANDLE -11 |
| Invalid object handle specified. | |
| #define | ProcMgr_E_ACCESSDENIED -12 |
| The operation is not permitted in this process. | |
| #define | ProcMgr_E_TRANSLATE -13 |
| An address translation error occurred. | |
| #define | ProcMgr_E_SYMBOLNOTFOUND -14 |
| Could not find the specified symbol in the loaded file. | |
| #define | ProcMgr_E_MAP -15 |
| Failed to map/unmap an address range. | |
| #define | ProcMgr_MAX_MEMORY_REGIONS 32u |
| Maximum number of memory regions supported by ProcMgr module. | |
| #define | IS_VALID_PROCID(id) (id < MultiProc_MAXPROCESSORS) |
| Checks if the Processor ID is valid. | |
Typedefs | |
| typedef ProcMgr_Object * | ProcMgr_Handle |
| Defines ProcMgr object handle. | |
| typedef ProcMgr_AttachParams_tag | ProcMgr_AttachParams |
| Configuration parameters specific to the slave ProcMgr instance. | |
| typedef ProcMgr_StartParams_tag | ProcMgr_StartParams |
| Configuration parameters to be provided while starting the slave processor. | |
| typedef ProcMgr_AddrInfo_tag | ProcMgr_AddrInfo |
| This structure defines information about memory regions mapped by the ProcMgr module. | |
| typedef ProcMgr_MappedMemEntry | ProcMgr_MappedMemEntry |
| Structure containing information of mapped memory regions. | |
| typedef ProcMgr_ProcInfo_tag | ProcMgr_ProcInfo |
| Characteristics of the slave processor. | |
| typedef ProcMgr_SectionInfo_tag | ProcMgr_SectionInfo |
| Characteristics of sections in executable. | |
| typedef Int(* | ProcMgr_CallbackFxn )(UInt16 procId, ProcMgr_Handle handle, ProcMgr_State fromState, ProcMgr_State toState) |
| Function pointer type that is passed to the ProcMgr_registerNotify function. | |
Enumerations | |
| enum | ProcMgr_State { ProcMgr_State_Unknown = 0u, ProcMgr_State_Powered = 1u, ProcMgr_State_Reset = 2u, ProcMgr_State_Loaded = 3u, ProcMgr_State_Running = 4u, ProcMgr_State_Unavailable = 5u, ProcMgr_State_EndValue = 6u } |
| Enumerations to indicate Processor states. More... | |
| enum | ProcMgr_BootMode { ProcMgr_BootMode_Boot = 0u, ProcMgr_BootMode_NoLoad_Pwr = 1u, ProcMgr_BootMode_NoLoad_NoPwr = 2u, ProcMgr_BootMode_NoBoot = 3u, ProcMgr_BootMode_EndValue = 4u } |
| Enumerations to indicate different types of slave boot modes. More... | |
| enum | ProcMgr_AddrType { ProcMgr_AddrType_MasterKnlVirt = 0u, ProcMgr_AddrType_MasterUsrVirt = 1u, ProcMgr_AddrType_MasterPhys = 2u, ProcMgr_AddrType_SlaveVirt = 3u, ProcMgr_AddrType_SlavePhys = 4u, ProcMgr_AddrType_EndValue = 5u } |
| Enumerations to indicate address types used for translation. More... | |
| enum | ProcMgr_MapType { ProcMgr_MapType_MasterKnlVirt = 0x0001u, ProcMgr_MapType_MasterUsrVirt = 0x0002u, ProcMgr_MapType_SlaveVirt = 0x0004u, ProcMgr_MapType_EndValue = 0x0008u } |
| Enumerations to indicate address mask types used for mapping. More... | |
Functions | |
| Int | ProcMgr_open (ProcMgr_Handle *handlePtr, UInt16 procId) |
| Function to open a handle to an existing ProcMgr object handling the procId. | |
| Int | ProcMgr_close (ProcMgr_Handle *handlePtr) |
| Function to close this handle to the ProcMgr instance. | |
| Void | ProcMgr_getAttachParams (ProcMgr_Handle handle, ProcMgr_AttachParams *params) |
| Function to initialize the parameters for the ProcMgr attach function. | |
| Int | ProcMgr_attach (ProcMgr_Handle handle, ProcMgr_AttachParams *params) |
| Function to attach the client to the specified slave and also initialize the slave (if required). | |
| Int | ProcMgr_detach (ProcMgr_Handle handle) |
| Function to detach the client from the specified slave and also finalze the slave (if required). | |
| Int | ProcMgr_load (ProcMgr_Handle handle, String imagePath, UInt32 argc, String *argv, Ptr params, UInt32 *fileId) |
| Function to load the specified slave executable on the slave Processor. | |
| Int | ProcMgr_unload (ProcMgr_Handle handle, UInt32 fileId) |
| Function to unload the previously loaded file on the slave processor. | |
| Void | ProcMgr_getStartParams (ProcMgr_Handle handle, ProcMgr_StartParams *params) |
| Function to initialize the parameters for the ProcMgr start function. | |
| Int | ProcMgr_start (ProcMgr_Handle handle, ProcMgr_StartParams *params) |
| Function to start the slave processor running. | |
| Int | ProcMgr_stop (ProcMgr_Handle handle) |
| Function to stop the slave processor. | |
| ProcMgr_State | ProcMgr_getState (ProcMgr_Handle handle) |
| Function to get the current state of the slave Processor. | |
| Int | ProcMgr_read (ProcMgr_Handle handle, UInt32 procAddr, UInt32 *numBytes, Ptr buffer) |
| Function to read from the slave processor's memory. | |
| Int | ProcMgr_write (ProcMgr_Handle handle, UInt32 procAddr, UInt32 *numBytes, Ptr buffer) |
| Function to write into the slave processor's memory. | |
| Int | ProcMgr_control (ProcMgr_Handle handle, Int32 cmd, Ptr arg) |
| Function to perform device-dependent operations. | |
| Int | ProcMgr_translateAddr (ProcMgr_Handle handle, Ptr *dstAddr, ProcMgr_AddrType dstAddrType, Ptr srcAddr, ProcMgr_AddrType srcAddrType) |
| Function to translate between two types of address spaces. | |
| Int | ProcMgr_getSymbolAddress (ProcMgr_Handle handle, UInt32 fileId, String symbolName, UInt32 *symValue) |
| Function to retrieve the target address of a symbol from the specified file. | |
| Int | ProcMgr_map (ProcMgr_Handle handle, ProcMgr_MapType mapType, ProcMgr_AddrInfo *addrInfo, ProcMgr_AddrType srcAddrType) |
| Function to map address to specified destination type(s). | |
| Int | ProcMgr_unmap (ProcMgr_Handle handle, ProcMgr_MapType mapType, ProcMgr_AddrInfo *addrInfo, ProcMgr_AddrType srcAddrType) |
| Function to map address to slave address space. | |
| Int | ProcMgr_registerNotify (ProcMgr_Handle handle, ProcMgr_CallbackFxn fxn, Ptr args, ProcMgr_State state[]) |
| Function that registers for notification when the slave processor transitions to any of the states specified. | |
| Int | ProcMgr_getProcInfo (ProcMgr_Handle handle, ProcMgr_ProcInfo *procInfo) |
| Function that returns information about the characteristics of the slave processor. | |
| Int | ProcMgr_getSectionInfo (ProcMgr_Handle handle, UInt32 fileId, String sectionName, ProcMgr_SectionInfo *sectionInfo) |
| Function that returns section information given the name of section and number of bytes to read. | |
| Int | ProcMgr_getSectionData (ProcMgr_Handle handle, UInt32 fileId, ProcMgr_SectionInfo *sectionInfo, Ptr buffer) |
| UInt32 | ProcMgr_getLoadedFileId (ProcMgr_Handle handle) |
|
|
Checks if the Processor ID is valid.
|
|
|
The operation is not permitted in this process.
|
|
|
The specified entity already exists.
|
|
|
Generic failure.
|
|
|
Invalid object handle specified.
|
|
|
Argument passed to function is invalid.
|
|
|
Module is not initialized.
|
|
|
Failed to map/unmap an address range.
|
|
|
Operation resulted in memory failure.
|
|
|
Unable to find the specified entity.
|
|
|
A failure occurred in an OS-specific call.
|
|
|
Specified resource is not available.
|
|
|
Operation was interrupted. Please restart the operation.
|
|
|
Could not find the specified symbol in the loaded file.
|
|
|
Operation timed out.
|
|
|
An address translation error occurred.
|
|
|
Maximum number of memory regions supported by ProcMgr module.
|
|
|
The ProcMgr instance has already been created/opened in this process.
|
|
|
The module has been already setup.
|
|
|
The resource is still in use.
|
|
|
Other ProcMgr clients have still setup the ProcMgr module.
|
|
|
|
|
|
Operation is successful.
|
|
|
This structure defines information about memory regions mapped by the ProcMgr module.
|
|
|
Configuration parameters specific to the slave ProcMgr instance.
|
|
|
Function pointer type that is passed to the ProcMgr_registerNotify function.
|
|
|
Defines ProcMgr object handle.
|
|
|
Structure containing information of mapped memory regions.
|
|
|
Characteristics of the slave processor.
|
|
|
Characteristics of sections in executable.
|
|
|
Configuration parameters to be provided while starting the slave processor.
|
|
|
Enumerations to indicate address types used for translation.
Definition at line 287 of file ProcMgr.h. 00287 { 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;
|
|
|
Enumerations to indicate different types of slave boot modes.
Definition at line 266 of file ProcMgr.h. 00266 { 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 ;
|
|
|
Enumerations to indicate address mask types used for mapping.
Definition at line 305 of file ProcMgr.h. 00305 { 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;
|
|
|
Enumerations to indicate Processor states.
Definition at line 246 of file ProcMgr.h. 00246 { 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 ;
|
|
||||||||||||
|
Function to attach the client to the specified slave and also initialize the slave (if required). This function attaches to an instance of the ProcMgr module and performs any hardware initialization required to power up the slave device. This function also performs the required state transitions for this ProcMgr instance to ensure that the local object representing the slave device correctly indicates the state of the slave device. Depending on the slave boot mode being used, the slave may be powered up, in reset, or even running state. Configuration parameters need to be provided to this function. If the user wishes to change some specific config parameters, then ProcMgr_getAttachParams can be called to get the configuration filled with the default values. After this, only the required configuration values can be changed. If the user does not wish to make any change in the default parameters, the application can simply call ProcMgr_attach with NULL parameters. The default parameters would get automatically used.
|
|
|
Function to close this handle to the ProcMgr instance. This function closes the handle to the ProcMgr instance obtained through ProcMgr_open call made earlier. The handle in the passed pointer is reset on success.
|
|
||||||||||||||||
|
Function to perform device-dependent operations. This function performs control operations supported by the as exposed directly by the specific implementation of the Processor interface. These commands and their specific argument types are used with this function.
|
|
|
Function to detach the client from the specified slave and also finalze the slave (if required). This function detaches from an instance of the ProcMgr module and performs any hardware finalization required to power down the slave device. This function also performs the required state transitions for this ProcMgr instance to ensure that the local object representing the slave device correctly indicates the state of the slave device. Depending on the slave boot mode being used, the slave may be powered down, in reset, or left in its original state.
|
|
||||||||||||
|
Function to initialize the parameters for the ProcMgr attach function. This function can be called by the application to get their configuration parameter to ProcMgr_attach filled in by the ProcMgr module with the default parameters. If the user does not wish to make any change in the default parameters, this API is not required to be called.
|
|
|
|
|
||||||||||||
|
Function that returns information about the characteristics of the slave processor.
|
|
||||||||||||||||||||
|
|
|
||||||||||||||||||||
|
Function that returns section information given the name of section and number of bytes to read.
|
|
||||||||||||
|
Function to initialize the parameters for the ProcMgr start function. This function can be called by the application to get their configuration parameter to ProcMgr_start filled in by the ProcMgr module with the default parameters. If the user does not wish to make any change in the default parameters, this API is not required to be called.
|
|
|
Function to get the current state of the slave Processor. This function gets the state of the slave processor as maintained on the master Processor state machine. It does not go to the slave processor to get its actual state at the time when this API is called.
|
|
||||||||||||||||||||
|
Function to retrieve the target address of a symbol from the specified file.
|
|
||||||||||||||||||||||||||||
|
Function to load the specified slave executable on the slave Processor. This function allows usage of different types of loaders. The loader specified when creating this instance of the ProcMgr is used for loading the slave executable. Depending on the type of loader, the imagePath parameter may point to the path of the file in the host file system, or it may be NULL. Some loaders may require specific parameters to be passed. This function returns a fileId, which can be used for further function calls that reference a specific file that has been loaded on the slave processor.
|
|
||||||||||||||||||||
|
Function to map address to specified destination type(s). This function maps the provided address of specified srcAddrType to one or more destination address types, and returns the mapped addresses and size in the same addrInfo structure.
|
|
||||||||||||
|
Function to open a handle to an existing ProcMgr object handling the procId. This function returns a handle to an existing ProcMgr instance created for this procId. It enables other entities to access and use this ProcMgr instance.
|
|
||||||||||||||||||||
|
Function to read from the slave processor's memory. This function reads from the specified address in the processor's address space and copies the required number of bytes into the specified buffer. It returns the number of bytes actually read in the numBytes parameter.
|
|
||||||||||||||||||||
|
Function that registers for notification when the slave processor transitions to any of the states specified. This function allows the user application to register for changes in processor state and take actions accordingly.
|
|
||||||||||||
|
Function to start the slave processor running. Function to start execution of the loaded code on the slave from the entry point specified in the slave executable loaded earlier by call to ProcMgr_load (). After successful completion of this function, the ProcMgr instance is expected to be in the ProcMgr_State_Running state.
|
|
|
Function to stop the slave processor. Function to stop execution of the slave processor. Depending on the boot mode, after successful completion of this function, the ProcMgr instance may be in the ProcMgr_State_Reset state.
|
|
||||||||||||||||||||||||
|
Function to translate between two types of address spaces. This function translates addresses between two types of address spaces. The destination and source address types are indicated through parameters specified in this function.
|
|
||||||||||||
|
Function to unload the previously loaded file on the slave processor. This function unloads the file that was previously loaded on the slave processor through the ProcMgr_load API. It frees up any resources that were allocated during ProcMgr_load for this file. The fileId received from the load function must be passed to this function.
|
|
||||||||||||||||||||
|
Function to map address to slave address space. This function unmaps the provided address(es) of specified one or more destination address types. The srcAddrType indicates the source address with which the entry for the mapping is to be identified. It must be the same address that was specified as the src address when the corresponding mapping was performed.
|
|
||||||||||||||||||||
|
Function to write into the slave processor's memory. This function writes into the specified address in the processor's address space and copies the required number of bytes from the specified buffer. It returns the number of bytes actually written in the numBytes parameter.
|
1.4.4