1 /**
2 * @file ProcMgr.h
3 *
4 * @brief The Processor Manager on a master processor provides control
5 * functionality for a slave device.<br>
6 *
7 * The ProcMgr module provides the following services for the
8 * slave processor:<br>
9 *
10 * -Slave processor boot-loading<br>
11 * -Read from or write to slave processor memory<br>
12 * -Slave processor power management<br>
13 * -Slave processor error handling<br>
14 * -Dynamic Memory Mapping<br>
15 *
16 * The Device Manager (Processor module) shall have interfaces for:<br>
17 *
18 * -Loader: There may be multiple implementations of the Loader
19 * interface within a single Processor instance.
20 * For example, COFF, ELF, dynamic loader, custom types
21 * of loaders may be written and plugged in.<br>
22 *
23 * -Power Manager: The Power Manager implementation can be a
24 * separate module that is plugged into the Processor
25 * module. This allows the Processor code to remain
26 * generic, and the Power Manager may be written and
27 * maintained either by a separate team, or by customer.<br>
28 *
29 * -Processor: The implementation of this interface provides all
30 * other functionality for the slave processor, including
31 * setup and initialization of the Processor module,
32 * management of slave processor MMU (if available),
33 * functions to write to and read from slave memory etc.<br>
34 *
35 * All processors in the system shall be identified by unique
36 * processor ID. The management of this processor ID is done by the
37 * MultiProc module.<br>
38 *
39 *
40 * @ver 02.00.00.46_alpha1
41 *
42 * ============================================================================
43 *
44 * Copyright (c) 2008-2009, Texas Instruments Incorporated
45 *
46 * Redistribution and use in source and binary forms, with or without
47 * modification, are permitted provided that the following conditions
48 * are met:
49 *
50 * * Redistributions of source code must retain the above copyright
51 * notice, this list of conditions and the following disclaimer.
52 *
53 * * Redistributions in binary form must reproduce the above copyright
54 * notice, this list of conditions and the following disclaimer in the
55 * documentation and/or other materials provided with the distribution.
56 *
57 * * Neither the name of Texas Instruments Incorporated nor the names of
58 * its contributors may be used to endorse or promote products derived
59 * from this software without specific prior written permission.
60 *
61 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
62 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
63 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
64 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
65 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
66 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
67 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
68 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
69 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
70 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
71 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
72 * Contact information for paper mail:
73 * Texas Instruments
74 * Post Office Box 655303
75 * Dallas, Texas 75265
76 * Contact information:
77 * http://www-k.ext.ti.com/sc/technical-support/product-information-centers.htm?
78 * DCMP=TIHomeTracking&HQS=Other+OT+home_d_contact
79 * ============================================================================
80 *
81 */
84 #ifndef ProcMgr_H_0xf2ba
85 #define ProcMgr_H_0xf2ba
87 #if defined (__cplusplus)
88 extern "C" {
89 #endif
92 /* =============================================================================
93 * All success and failure codes for the module
94 * =============================================================================
95 */
96 /*!
97 * @def ProcMgr_S_CANCELED
98 * @brief The function was successfully canceled.
99 */
100 #define ProcMgr_S_CANCELED 7
102 /*!
103 * @def ProcMgr_S_REPLYLATER
104 * @brief The function will send the reply later.
105 */
106 #define ProcMgr_S_REPLYLATER 6
108 /*!
109 * @def ProcMgr_S_OPENHANDLE
110 * @brief Other ProcMgr clients have still setup the ProcMgr module.
111 */
112 #define ProcMgr_S_SETUP 5
114 /*!
115 * @def ProcMgr_S_OPENHANDLE
116 * @brief Other ProcMgr handles are still open in this process.
117 */
118 #define ProcMgr_S_OPENHANDLE 4
120 /*!
121 * @def ProcMgr_S_ALREADYEXISTS
122 * @brief The ProcMgr instance has already been created/opened in this process
123 */
124 #define ProcMgr_S_ALREADYEXISTS 3
125 /*!
126 * @def ProcMgr_S_BUSY
127 * @brief The resource is still in use
128 */
129 #define ProcMgr_S_BUSY 2
131 /*!
132 * @def ProcMgr_S_ALREADYSETUP
133 * @brief The module has been already setup
134 */
135 #define ProcMgr_S_ALREADYSETUP 1
137 /*!
138 * @def ProcMgr_S_SUCCESS
139 * @brief Operation is successful.
140 */
141 #define ProcMgr_S_SUCCESS 0
143 /*!
144 * @def ProcMgr_E_FAIL
145 * @brief Generic failure.
146 */
147 #define ProcMgr_E_FAIL -1
149 /*!
150 * @def ProcMgr_E_INVALIDARG
151 * @brief Argument passed to function is invalid.
152 */
153 #define ProcMgr_E_INVALIDARG -2
155 /*!
156 * @def ProcMgr_E_MEMORY
157 * @brief Operation resulted in memory failure.
158 */
159 #define ProcMgr_E_MEMORY -3
161 /*!
162 * @def ProcMgr_E_ALREADYEXISTS
163 * @brief The specified entity already exists.
164 */
165 #define ProcMgr_E_ALREADYEXISTS -4
167 /*!
168 * @def ProcMgr_E_NOTFOUND
169 * @brief Unable to find the specified entity.
170 */
171 #define ProcMgr_E_NOTFOUND -5
173 /*!
174 * @def ProcMgr_E_TIMEOUT
175 * @brief Operation timed out.
176 */
177 #define ProcMgr_E_TIMEOUT -6
179 /*!
180 * @def ProcMgr_E_INVALIDSTATE
181 * @brief Module is not initialized.
182 */
183 #define ProcMgr_E_INVALIDSTATE -7
185 /*!
186 * @def ProcMgr_E_OSFAILURE
187 * @brief A failure occurred in an OS-specific call
188 */
189 #define ProcMgr_E_OSFAILURE -8
191 /*!
192 * @def ProcMgr_E_RESOURCE
193 * @brief Specified resource is not available
194 */
195 #define ProcMgr_E_RESOURCE -9
197 /*!
198 * @def ProcMgr_E_RESTART
199 * @brief Operation was interrupted. Please restart the operation
200 */
201 #define ProcMgr_E_RESTART -10
203 /*!
204 * @def ProcMgr_E_HANDLE
205 * @brief Invalid object handle specified
206 */
207 #define ProcMgr_E_HANDLE -11
209 /*!
210 * @def ProcMgr_E_ACCESSDENIED
211 * @brief The operation is not permitted in this process.
212 */
213 #define ProcMgr_E_ACCESSDENIED -12
215 /*!
216 * @def ProcMgr_E_TRANSLATE
217 * @brief An address translation error occurred.
218 */
219 #define ProcMgr_E_TRANSLATE -13
221 /*!
222 * @def ProcMgr_E_SYMBOLNOTFOUND
223 * @brief Could not find the specified symbol in the loaded file
224 */
225 #define ProcMgr_E_SYMBOLNOTFOUND -14
227 /*!
228 * @def ProcMgr_E_MAP
229 * @brief Failed to map/unmap an address range
230 */
231 #define ProcMgr_E_MAP -15
234 /* =============================================================================
235 * Macros and types
236 * =============================================================================
237 */
238 /*!
239 * @brief Maximum number of memory regions supported by ProcMgr module.
240 */
241 #define ProcMgr_MAX_MEMORY_REGIONS 32u
243 /*!
244 * @def IS_VALID_PROCID
245 * @brief Checks if the Processor ID is valid
246 */
247 #define IS_VALID_PROCID(id) (id < MultiProc_MAXPROCESSORS)
249 /*!
250 * @brief Defines ProcMgr object handle
251 */
252 typedef struct ProcMgr_Object * ProcMgr_Handle;
255 /*!
256 * @brief Enumerations to indicate Processor states.
257 */
258 typedef enum {
259 ProcMgr_State_Unknown = 0u,
260 /*!< Unknown Processor state (e.g. at startup or error). */
261 ProcMgr_State_Powered = 1u,
262 /*!< Indicates the Processor is powered up. */
263 ProcMgr_State_Reset = 2u,
264 /*!< Indicates the Processor is reset. */
265 ProcMgr_State_Loaded = 3u,
266 /*!< Indicates the Processor is loaded. */
267 ProcMgr_State_Running = 4u,
268 /*!< Indicates the Processor is running. */
269 ProcMgr_State_Suspended = 5u,
270 /*!< Indicates the Processor is suspended. */
271 ProcMgr_State_Unavailable = 6u,
272 /*!< Indicates the Processor is unavailable to the physical transport. */
273 ProcMgr_State_Error = 7u,
274 /*!< Indicates the Processor is in an error state (general error). */
275 ProcMgr_State_Watchdog = 8u,
276 /*!< Indicates the Processor is in an error state (Watchdog error). */
277 ProcMgr_State_Mmu_Fault = 9u,
278 /*!< Indicates the Processor is in an error state (MMU fault error). */
279 ProcMgr_State_EndValue = 10u
280 /*!< End delimiter indicating start of invalid values for this enum */
281 } ProcMgr_State ;
282 /*!
283 * @brief Enumerations to identify the Processor
284 */
285 typedef enum {
286 PROC_DSP = 0,
287 PROC_CORE1 = 1,
288 PROC_CORE0 = 2,
289 PROC_MPU = 3,
290 PROC_END = 4
291 } ProcMgr_ProcId;
293 /*!
294 * @brief Enumerations to indicate different types of slave boot modes.
295 */
296 typedef enum {
297 ProcMgr_BootMode_Boot = 0u,
298 /*!< ProcMgr is responsible for loading the slave and its reset control. */
299 ProcMgr_BootMode_NoLoad_Pwr = 1u,
300 /*!< ProcMgr is not responsible for loading the slave. It is responsible
301 for reset control of the slave. */
302 ProcMgr_BootMode_NoLoad_NoPwr = 2u,
303 /*!< ProcMgr is not responsible for loading the slave. It is partial responsible
304 for reset control of the slave. It doesn't put in reset while procMgr_attach
305 but release reset while procMgr_start operation. */
306 ProcMgr_BootMode_NoBoot = 3u,
307 /*!< ProcMgr is not responsible for loading or reset control of the slave.
308 The slave either self-boots, or this is done by some entity outside of
309 the ProcMgr module. */
310 ProcMgr_BootMode_EndValue = 4u
311 /*!< End delimiter indicating start of invalid values for this enum */
312 } ProcMgr_BootMode ;
314 /*!
315 * @brief Enumerations to indicate address types used for translation
316 */
317 typedef enum {
318 ProcMgr_AddrType_MasterKnlVirt = 0u,
319 /*!< Kernel Virtual address on master processor */
320 ProcMgr_AddrType_MasterUsrVirt = 1u,
321 /*!< User Virtual address on master processor */
322 ProcMgr_AddrType_MasterPhys = 2u,
323 /*!< Physical address on master processor */
324 ProcMgr_AddrType_SlaveVirt = 3u,
325 /*!< Virtual address on slave processor */
326 ProcMgr_AddrType_SlavePhys = 4u,
327 /*!< Physical address on slave processor */
328 ProcMgr_AddrType_EndValue = 5u
329 /*!< End delimiter indicating start of invalid values for this enum */
330 } ProcMgr_AddrType;
332 /**
333 * @brief Address Map Mask type
334 */
335 typedef UInt32 ProcMgr_MapMask;
337 /**
338 * @brief Kernel virtual address on master processor
339 */
340 #define ProcMgr_MASTERKNLVIRT (ProcMgr_MapMask)(1 << 0)
342 /**
343 * @brief User virtual address on master processor
344 */
345 #define ProcMgr_MASTERUSRVIRT (ProcMgr_MapMask)(1 << 1)
347 /**
348 * @brief Virtual address on slave processor
349 */
350 #define ProcMgr_SLAVEVIRT (ProcMgr_MapMask)(1 << 2)
352 /**
353 * @brief Tiler address on slave processor
354 */
355 #define ProcMgr_TILER (ProcMgr_MapMask)(1 << 3)
356 /*!
357 * @brief Event types
358 */
359 typedef enum {
360 PROC_MMU_FAULT = 0u,
361 /*!< MMU fault event */
362 PROC_ERROR = 1u,
363 /*!< Proc Error event */
364 PROC_STOP = 2u,
365 /*!< Proc Stop event */
366 PROC_START = 3u,
367 /*!< Proc start event */
368 PROC_WATCHDOG = 4u,
369 /*!< Proc WatchDog Timer event */
370 } ProcMgr_EventType;
372 /*!
373 * @brief Enumerations to indicate the available device address memory pools
374 */
375 typedef enum {
376 ProcMgr_DMM_MemPool = 0u,
377 /*!< Map/unmap to virtual address space (user) */
378 ProcMgr_TILER_MemPool = 1u,
379 /*!< Map/unmap to Tiler address space */
380 ProcMgr_NONE_MemPool = -1,
381 /*!< Provide valid Device address as input*/
382 } ProcMgr_MemPoolType;
384 /*!
385 * @brief Configuration parameters specific to the slave ProcMgr instance.
386 */
387 typedef struct ProcMgr_AttachParams_tag {
388 ProcMgr_BootMode bootMode;
389 /*!< Boot mode for the slave processor. */
390 Ptr bootParams;
391 /*!< Params for dependent processors like IVHD for netra. */
392 } ProcMgr_AttachParams ;
394 /*!
395 * @brief Configuration parameters to be provided while starting the slave
396 * processor.
397 */
398 typedef struct ProcMgr_StartParams_tag {
399 UInt32 reserved;
400 /*!< Reserved for future params. */
401 } ProcMgr_StartParams ;
404 /*!
405 * @brief This structure defines information about memory regions mapped by
406 * the ProcMgr module.
407 */
408 typedef struct ProcMgr_AddrInfo_tag {
409 UInt32 addr [ProcMgr_AddrType_EndValue];
410 /*!< Addresses for each type of address space */
411 UInt32 size;
412 /*!< Size of the memory region in bytes */
413 Bool isCached;
414 /*!< Region cached? */
415 Bool isMapped;
416 /*!< tells whether the entry is mapped */
417 ProcMgr_MapMask mapMask;
418 /*!< map type needed for default entries in translation table */
419 UInt16 refCount;
420 /*!< To ensure entry is added/removed only in appropriate map/unmap
421 */
422 } ProcMgr_AddrInfo;
424 /*!
425 * @brief Structure containing information of mapped memory regions
426 */
427 typedef struct ProcMgr_MappedMemEntry {
428 ProcMgr_AddrInfo info;
429 /*!< Address information */
430 ProcMgr_AddrType srcAddrType;
431 /*!< Source address type used for mapping */
432 ProcMgr_MapMask mapMask;
433 /*!< Mapping type */
434 Bool inUse;
435 /*!< Entry index is in use? */
436 } ProcMgr_MappedMemEntry;
438 /*!
439 * @brief Characteristics of the slave processor
440 */
441 typedef struct ProcMgr_ProcInfo_tag {
442 ProcMgr_BootMode bootMode;
443 /*!< Boot mode of the processor. */
444 UInt16 maxMemoryRegions;
445 /*!< Value of ProcMgr_Object.maxMemoryRegions */
446 UInt16 numMemEntries;
447 /*!< Number of valid memory entries */
448 ProcMgr_MappedMemEntry memEntries [ProcMgr_MAX_MEMORY_REGIONS];
449 /*!< Configuration of memory regions */
450 } ProcMgr_ProcInfo;
453 /*!
454 * @brief Characteristics of sections in executable
455 */
456 typedef struct ProcMgr_SectionInfo_tag {
457 UInt32 physicalAddress;
458 /*!< Requested/returned section's physicalAddress */
459 UInt32 virtualAddress;
460 /*!< Requested/returned section's vitualAddress */
461 UInt16 sectId;
462 /*!< Requested/returned section id */
463 UInt32 size;
464 /*!< Section size */
465 } ProcMgr_SectionInfo;
467 /*!
468 * @brief Enumerations to indicate Callback Event Status.
469 */
470 typedef enum {
471 ProcMgr_EventStatus_Event = 0u,
472 /*!< Indicates the requested event has occurred. */
473 ProcMgr_EventStatus_Canceled = 1u,
474 /*!< Indicates the request was canceled. */
475 ProcMgr_EventStatus_Timeout = 2u,
476 /*!< Indicates the request has timed out. */
477 } ProcMgr_EventStatus ;
479 /*!
480 * @brief Function pointer type that is passed to the
481 * ProcMgr_registerNotify function
482 *
483 * @param procId Processor ID for the processor that is undergoing the
484 * state change.
485 * @param handle Handle to the processor instance.
486 * @param fromState Previous processor state
487 * @param toState New processor state
488 * @param status Indicates the status of the event.
489 *
490 * @sa ProcMgr_registerNotify
491 */
492 typedef Int (*ProcMgr_CallbackFxn) (UInt16 procId,
493 ProcMgr_Handle handle,
494 ProcMgr_State fromState,
495 ProcMgr_State toState,
496 ProcMgr_EventStatus status,
497 Ptr args);
499 /* =============================================================================
500 * APIs
501 * =============================================================================
502 */
503 /*!
504 * @brief Function to open a handle to an existing ProcMgr object handling
505 * the procId.
506 *
507 * This function returns a handle to an existing ProcMgr instance
508 * created for this procId. It enables other entities to access
509 * and use this ProcMgr instance.
510 *
511 * @param handlePtr Return Parameter: Handle to the ProcMgr instance
512 * @param procId Processor ID represented by this ProcMgr instance
513 *
514 * @retval ProcMgr_S_SUCCESS Operation successful
515 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
516 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
517 * @retval ProcMgr_S_ALREADYEXISTS Object is already created/opened in this
518 * process
519 * @retval ProcMgr_E_MAP Failed to map address range to host OS
520 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
521 * @retval ProcMgr_E_MEMORY Memory allocation failed
522 *
523 * @sa ProcMgr_close, Memory_calloc
524 */
525 Int ProcMgr_open (ProcMgr_Handle * handlePtr, UInt16 procId);
527 /*!
528 * @brief Function to close this handle to the ProcMgr instance.
529 *
530 * This function closes the handle to the ProcMgr instance
531 * obtained through ProcMgr_open call made earlier. The handle in
532 * the passed pointer is reset on success.
533 *
534 * @param handlePtr Pointer to the ProcMgr handle
535 *
536 * @retval ProcMgr_S_SUCCESS Operation successful
537 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
538 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
539 * @retval ProcMgr_E_ACCESSDENIED All open handles to this ProcMgr object
540 * are already closed
541 * @retval ProcMgr_S_OPENHANDLE Other threads in this process have
542 * already opened handles to this ProcMgr
543 * instance.
544 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
545 *
546 * @sa ProcMgr_open, Memory_free
547 */
548 Int ProcMgr_close (ProcMgr_Handle * handlePtr);
550 /*!
551 * @brief Function to initialize the parameters for the ProcMgr attach
552 * function.
553 *
554 * This function can be called by the application to get their
555 * configuration parameter to #ProcMgr_attach filled in by the
556 * ProcMgr module with the default parameters. If the user does
557 * not wish to make any change in the default parameters, this API
558 * is not required to be called.
559 *
560 * @param handle Handle to the ProcMgr object. If specified as NULL,
561 * the default global configuration values are returned.
562 * @param params Pointer to the ProcMgr attach params structure in
563 * which the default params is to be returned.
564 *
565 * @sa ProcMgr_attach
566 */
567 Void ProcMgr_getAttachParams (ProcMgr_Handle handle,
568 ProcMgr_AttachParams * params);
570 /*!
571 * @brief Function to attach the client to the specified slave and also
572 * initialize the slave (if required).
573 *
574 * This function attaches to an instance of the ProcMgr module and
575 * performs any hardware initialization required to power up the
576 * slave device. This function also performs the required state
577 * transitions for this ProcMgr instance to ensure that the local
578 * object representing the slave device correctly indicates the
579 * state of the slave device. Depending on the slave boot mode
580 * being used, the slave may be powered up, in reset, or even
581 * running state.
582 * In typical scenarios, after calling ProcMgr_attach, the
583 * application should call ProcMgr_detach during shutdown to
584 * detach the client from the slave and perform any hardware
585 * finalization needed. However, there may be cases
586 * (e.g. in a slave loader application) when it is desirable to
587 * leave the hardware initialized and ready upon exiting the
588 * application. In such cases it is fine to defer the
589 * ProcMgr_detach call to a later point in time.
590 *
591 * Configuration parameters need to be provided to this
592 * function. If the user wishes to change some specific config
593 * parameters, then #ProcMgr_getAttachParams can be called to get
594 * the configuration filled with the default values. After this,
595 * only the required configuration values can be changed. If the
596 * user does not wish to make any change in the default parameters,
597 * the application can simply call ProcMgr_attach with NULL
598 * parameters.
599 * The default parameters would get automatically used.
600 *
601 * @param handle Handle to the ProcMgr object.
602 * @param params Optional ProcMgr attach parameters. If provided as
603 * NULL, default configuration is used.
604 *
605 * @retval ProcMgr_S_SUCCESS Operation successful
606 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
607 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
608 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
609 * @retval ProcMgr_E_MAP Failed to map address range to host OS
610 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
611 *
612 * @sa ProcMgr_detach()
613 * @sa ProcMgr_getAttachParams()
614 */
615 Int ProcMgr_attach (ProcMgr_Handle handle, ProcMgr_AttachParams * params);
617 /*!
618 * @brief Function to detach the client from the specified slave and also
619 * finalze the slave (if required).
620 *
621 * This function detaches from an instance of the ProcMgr module
622 * and performs any hardware finalization required to power down
623 * the slave device. This function also performs the required state
624 * transitions for this ProcMgr instance to ensure that the local
625 * object representing the slave device correctly indicates the
626 * state of the slave device. Depending on the slave boot mode
627 * being used, the slave may be powered down, in reset, or left in
628 * its original state.
629 *
630 * @param handle Handle to the ProcMgr object
631 *
632 * @retval ProcMgr_S_SUCCESS Operation successful
633 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
634 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
635 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
636 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
637 *
638 * @sa ProcMgr_attach
639 */
640 Int ProcMgr_detach (ProcMgr_Handle handle);
642 /*!
643 * @brief Function to load the specified slave executable on the slave
644 * Processor.
645 *
646 * This function allows usage of different types of loaders. The
647 * loader specified when creating this instance of the ProcMgr
648 * is used for loading the slave executable. Depending on the type
649 * of loader, the imagePath parameter may point to the path of the
650 * file in the host file system, or it may be NULL. Some loaders
651 * may require specific parameters to be passed. This function
652 *
653 * @remarks This function returns a fileId, which can be used for further
654 * function calls that reference a specific file that has been
655 * loaded on the slave processor.
656 *
657 * @remarks Some loaders may not support all features. For example, the
658 * ELF loader may not support passing argc/argv to the slave.
659 *
660 * @param handle Handle to the ProcMgr object
661 * @param imagePath Full file path
662 * @param argc Number of arguments
663 * @param argv String array of arguments
664 * @param params Loader specific parameters
665 * @param fileId Return parameter: ID of the loaded file
666 *
667 * @retval ProcMgr_S_SUCCESS Operation successful
668 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
669 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
670 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
671 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
672 *
673 * @sa ProcMgr_unload
674 */
675 Int ProcMgr_load (ProcMgr_Handle handle,
676 String imagePath,
677 UInt32 argc,
678 String * argv,
679 Ptr params,
680 UInt32 * fileId);
682 /*!
683 * @brief Function to unload the previously loaded file on the slave
684 * processor.
685 *
686 * This function unloads the file that was previously loaded on the
687 * slave processor through the #ProcMgr_load API. It frees up any
688 * resources that were allocated during ProcMgr_load for this file.
689 *
690 * The fileId received from the load function must be passed to
691 * this function.
692 *
693 * @param handle Handle to the ProcMgr object
694 * @param fileId ID of the loaded file to be unloaded
695 *
696 * @retval ProcMgr_S_SUCCESS Operation successful
697 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
698 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
699 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
700 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
701 *
702 * @sa ProcMgr_load
703 */
704 Int ProcMgr_unload (ProcMgr_Handle handle, UInt32 fileId);
706 /*!
707 * @brief Function to initialize the parameters for the ProcMgr start
708 * function.
709 *
710 * This function can be called by the application to get their
711 * configuration parameter to #ProcMgr_start filled in by the
712 * ProcMgr module with the default parameters. If the user does
713 *
714 * not wish to make any change in the default parameters, this API
715 * is not required to be called.
716 *
717 * @param handle Handle to the ProcMgr object. If specified as NULL,
718 * the default global configuration values are returned.
719 * @param params Pointer to the ProcMgr start params structure in
720 * which the default params is to be returned.
721 *
722 * @sa ProcMgr_start
723 */
724 Void ProcMgr_getStartParams (ProcMgr_Handle handle,
725 ProcMgr_StartParams * params);
727 /*!
728 * @brief Function to start the slave processor running.
729 *
730 * Function to start execution of the loaded code on the slave
731 * from the entry point specified in the slave executable loaded
732 * earlier by call to #ProcMgr_load ().
733 *
734 * After successful completion of this function, the ProcMgr
735 * instance is expected to be in the #ProcMgr_State_Running state.
736 *
737 * @param handle Handle to the ProcMgr object
738 * @param params Optional ProcMgr start parameters. If provided as NULL,
739 * default parameters are used.
740 *
741 * @retval ProcMgr_S_SUCCESS Operation successful
742 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
743 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
744 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
745 * @retval ProcMgr_E_SYMBOLNOTFOUND Entry ponit symbol not found in loaded
746 * file
747 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
748 *
749 * @sa ProcMgr_stop
750 */
751 Int ProcMgr_start (ProcMgr_Handle handle, ProcMgr_StartParams * params);
753 /*!
754 * @brief Function to stop the slave processor.
755 *
756 * Depending on the boot mode, after successful completion of this
757 * function, the ProcMgr instance may be in the
758 * #ProcMgr_State_Reset state.
759 *
760 * @param handle Handle to the ProcMgr object
761 *
762 * @retval ProcMgr_S_SUCCESS Operation successful
763 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
764 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
765 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
766 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
767 *
768 * @sa ProcMgr_start
769 */
770 Int ProcMgr_stop (ProcMgr_Handle handle);
772 /*!
773 * @brief Function to get the current state of the slave Processor.
774 *
775 * This function gets the state of the slave processor as
776 * maintained on the master Processor state machine. It does not
777 * go to the slave processor to get its actual state at the time
778 * when this API is called.
779 *
780 * @param handle Handle to the ProcMgr object
781 *
782 * @retval Processor-state Operation successful
783 */
784 ProcMgr_State ProcMgr_getState (ProcMgr_Handle handle);
786 /*!
787 * @brief Function to set the current state of the slave Processor.
788 *
789 * This function sets the state of the slave processor as
790 * maintained on the master Processor state machine. It does not
791 * go to the slave processor to set its actual state at the time
792 * when this API is called.
793 *
794 * @param handle Handle to the ProcMgr object
795 * @param state State to set
796 *
797 * @retval None
798 *
799 * @sa
800 */
801 Void ProcMgr_setState (ProcMgr_Handle handle, ProcMgr_State state);
803 /*!
804 * @brief Function to read from the slave processor's memory.
805 *
806 * This function reads from the specified address in the
807 * processor's address space and copies the required number of
808 * bytes into the specified buffer.
809 *
810 * It returns the number of bytes actually read in the numBytes
811 * parameter.
812 *
813 * @param handle Handle to the ProcMgr object
814 * @param procAddr Address in space processor's address space of the
815 * memory region to read from.
816 * @param numBytes IN/OUT parameter. As an IN-parameter, it takes in the
817 * number of bytes to be read. When the function
818 * returns, this parameter contains the number of bytes
819 * actually read.
820 * @param[in,out] buffer User-provided buffer in which the slave processor's
821 * memory contents are to be copied.
822 *
823 * @pre @c handle is a valid (non-NULL) ProcMgr handle.
824 *
825 * @retval ProcMgr_S_SUCCESS Operation successful
826 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
827 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
828 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
829 * @retval ProcMgr_E_TRANSLATE Address is not mapped
830 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
831 *
832 * @sa ProcMgr_write
833 */
834 Int ProcMgr_read (ProcMgr_Handle handle,
835 UInt32 procAddr,
836 UInt32 * numBytes,
837 Ptr buffer);
839 /*!
840 * @brief Function to write into the slave processor's memory.
841 *
842 * This function writes into the specified address in the
843 * processor's address space and copies the required number of
844 * bytes from the specified buffer.
845 * It returns the number of bytes actually written in the numBytes
846 * parameter.
847 *
848 * @param handle Handle to the ProcMgr object
849 * @param procAddr Address in space processor's address space of the
850 * memory region to write into.
851 * @param numBytes IN/OUT parameter. As an IN-parameter, it takes in the
852 * number of bytes to be written. When the function
853 * returns, this parameter contains the number of bytes
854 * actually written.
855 * @param buffer User-provided buffer from which the data is to be
856 * written into the slave processor's memory.
857 *
858 * @retval ProcMgr_S_SUCCESS Operation successful
859 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
860 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
861 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
862 * @retval ProcMgr_E_TRANSLATE Address is not mapped
863 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
864 *
865 * @sa ProcMgr_read
866 */
867 Int ProcMgr_write (ProcMgr_Handle handle,
868 UInt32 procAddr,
869 UInt32 * numBytes,
870 Ptr buffer);
872 /*!
873 * @brief Function to perform device-dependent operations.
874 *
875 * This function performs control operations supported by the
876 * as exposed directly by the specific implementation of the
877 * Processor interface. These commands and their specific argument
878 * types are used with this function.
879 *
880 * @param handle Handle to the ProcMgr object
881 * @param cmd Device specific processor command
882 * @param arg Arguments specific to the type of command.
883 *
884 * @retval ProcMgr_S_SUCCESS Operation successful
885 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
886 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
887 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
888 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
889 *
890 * @sa
891 */
892 Int ProcMgr_control (ProcMgr_Handle handle, Int32 cmd, Ptr arg);
894 /*!
895 * @brief Function to translate between two types of address spaces.
896 *
897 * This function translates addresses between two types of address
898 * spaces. The destination and source address types are indicated
899 * through parameters specified in this function.
900 *
901 * @param handle Handle to the ProcMgr object
902 * @param dstAddr Return parameter: Pointer to receive the translated
903 * address.
904 * @param dstAddrType Destination address type requested
905 * @param srcAddr Source address in the source address space
906 * @param srcAddrType Source address type
907 *
908 * @retval ProcMgr_S_SUCCESS Operation successful
909 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
910 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
911 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
912 * @retval ProcMgr_E_TRANSLATE Failed to translate address.
913 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
914 *
915 * @sa ProcMgr_AddrType
916 */
917 Int ProcMgr_translateAddr (ProcMgr_Handle handle,
918 Ptr * dstAddr,
919 ProcMgr_AddrType dstAddrType,
920 Ptr srcAddr,
921 ProcMgr_AddrType srcAddrType);
923 /*!
924 * @brief Function to retrieve the target address of a symbol from the
925 * specified file.
926 *
927 * @param handle Handle to the ProcMgr object
928 * @param fileId ID of the file received from the load function
929 * @param symbolName Name of the symbol
930 * @param symValue Return parameter: Symbol address
931 *
932 * @retval ProcMgr_S_SUCCESS Operation successful
933 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
934 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
935 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
936 * @retval ProcMgr_E_SYMBOLNOTFOUND Symbol not found in loaded file
937 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
938 *
939 * @sa
940 */
941 Int ProcMgr_getSymbolAddress (ProcMgr_Handle handle,
942 UInt32 fileId,
943 String symbolName,
944 UInt32 * symValue);
946 /*!
947 * @brief Function to map address to specified destination type(s).
948 *
949 * This function maps the provided address of specified srcAddrType
950 * to one or more destination address types, and returns the mapped
951 * addresses and size in the same addrInfo structure.
952 *
953 * @param handle Handle to the Processor object
954 * @param mapType Mask of destination types of mapping to be
955 * performed. One or more types may be ORed together.
956 * @param addrInfo Structure containing map info. When this API is
957 * called, user must provide a valid address for the
958 * address of srcAddrType. On successful completion of
959 * this function, this same structure shall contain
960 * valid addresses for destination address types given
961 * in mapType.
962 * @param srcAddrType Source address type.
963 *
964 * @retval ProcMgr_S_SUCCESS Operation successful
965 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
966 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
967 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
968 * @retval ProcMgr_E_MAP Failed to map address range to host OS
969 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
970 *
971 * @sa ProcMgr_unmap, ProcMgr_MapMask, ProcMgr_AddrInfo
972 */
973 Int ProcMgr_map (ProcMgr_Handle handle,
974 ProcMgr_MapMask mapMask,
975 ProcMgr_AddrInfo * addrInfo,
976 ProcMgr_AddrType srcAddrType);
978 /*!
979 * @brief Function to map address to slave address space.
980 *
981 * This function unmaps the provided address(es) of specified
982 * one or more destination address types. The srcAddrType indicates
983 * the source address with which the entry for the mapping is to be
984 * identified. It must be the same address that was specified as
985 * the src address when the corresponding mapping was performed.
986 *
987 * @param handle Handle to the Processor object
988 * @param mapType Mask of destination types of unmapping to be
989 * performed. One or more types may be ORed together.
990 * @param addrInfo Structure containing map info. When this API is
991 * called, user must provide a valid address for the
992 * address of srcAddrType, as well as each of the
993 * destination types given in the mapType mask. On
994 * successful completion of this function, the
995 * specified destination mappings are unmapped.
996 * @param srcAddrType Source address type.
997 *
998 * @retval ProcMgr_S_SUCCESS Operation successful
999 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
1000 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
1001 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
1002 * @retval ProcMgr_E_NOTFOUND Info provided does not match with any
1003 * mapped entry
1004 * @retval ProcMgr_E_MAP Failed to unmap address range from host
1005 * OS
1006 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
1007 *
1008 * @sa ProcMgr_map, ProcMgr_MapMask, ProcMgr_AddrInfo
1009 */
1010 Int ProcMgr_unmap (ProcMgr_Handle handle,
1011 ProcMgr_MapMask mapMask,
1012 ProcMgr_AddrInfo * addrInfo,
1013 ProcMgr_AddrType srcAddrType);
1016 /*!
1017 * @brief Function that registers for notification when the slave
1018 * processor transitions to any of the states specified.
1019 *
1020 * This function allows the user application to register for
1021 * changes in processor state and take actions accordingly.
1022 *
1023 * @param handle Handle to the ProcMgr object
1024 * @param fxn Handling function to be registered.
1025 * @param args Optional arguments associated with the handler fxn.
1026 * @param state Array of target states for which registration is
1027 * required.
1028 *
1029 * @retval ProcMgr_S_SUCCESS Operation successful
1030 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
1031 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
1032 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
1033 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
1034 *
1035 * @sa ProcMgr_State, ProcMgr_CallbackFxn, ProcMgr_unregisterNotify
1036 */
1037 Int ProcMgr_registerNotify (ProcMgr_Handle handle,
1038 ProcMgr_CallbackFxn fxn,
1039 Ptr args,
1040 Int32 timeout,
1041 ProcMgr_State state []);
1044 /*!
1045 * @brief Get the maximum number of memory entries
1046 *
1047 * @param[in] handle Handle to the ProcMgr object
1048 *
1049 * @remarks The kernel objects contain tables of size
1050 * ProcMgr_MAX_MEMORY_REGIONS, this function retrieves that value
1051 * for dynamically-sized arrays.
1052 *
1053 * @retval Number of max memory entries
1054 */
1055 UInt32 ProcMgr_getMaxMemoryRegions(ProcMgr_Handle handle);
1058 /*!
1059 * @brief Retrieve information about the slave processor
1060 *
1061 * @param[in] handle Handle to the ProcMgr object
1062 * @param[out] procInfo Pointer to the ProcInfo object to be populated.
1063 *
1064 * @retval ProcMgr_S_SUCCESS Operation successful
1065 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
1066 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
1067 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
1068 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
1069 */
1070 Int ProcMgr_getProcInfo (ProcMgr_Handle handle,
1071 ProcMgr_ProcInfo * procInfo);
1074 /*!
1075 * @brief Function that returns section information given the name of
1076 * section and number of bytes to read
1077 *
1078 * @param handle Handle to the ProcMgr object
1079 * @param fileId ID of the file received from the load function
1080 * @param sectionName Name of section to be retrieved
1081 * @param sectionInfo Return parameter: Section information
1082 *
1083 * @retval ProcMgr_S_SUCCESS Operation successful
1084 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
1085 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
1086 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
1087 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
1088 *
1089 * @sa ProcMgr_SectionInfo
1090 */
1091 Int ProcMgr_getSectionInfo (ProcMgr_Handle handle,
1092 UInt32 fileId,
1093 String sectionName,
1094 ProcMgr_SectionInfo * sectionInfo);
1096 /*!
1097 * @brief Function that returns section data in a buffer given section id
1098 * and size to be read
1099 *
1100 * @param handle Handle to the ProcMgr object
1101 * @param fileId ID of the file received from the load function
1102 * @param sectionInfo Structure filled by ProcMgr_getSectionInfo.
1103 * @param buffer Return parameter
1104 *
1105 * @retval ProcMgr_S_SUCCESS Operation successful
1106 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
1107 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
1108 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
1109 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
1110 *
1111 * @sa ProcMgr_SectionInfo, ProcMgr_getSectionInfo
1112 */
1113 Int ProcMgr_getSectionData (ProcMgr_Handle handle,
1114 UInt32 fileId,
1115 ProcMgr_SectionInfo * sectionInfo,
1116 Ptr buffer);
1119 /*!
1120 * @brief Function that returns section data in a buffer given section id
1121 * and size to be read
1122 *
1123 * @param handle Handle to the ProcMgr object
1124 *
1125 * @retval fileId Operation successful
1126 *
1127 * @sa ProcMgr_load
1128 */
1129 UInt32 ProcMgr_getLoadedFileId (ProcMgr_Handle handle);
1131 /*!
1132 * @brief Function that allows the caller to wait on the specified event
1133 *
1134 * @param procId Id of the processor on which to wait
1135 * @param eventType Event type on which to wait
1136 * @param timeout Amount of time to wait for the event
1137 *
1138 * @retval ProcMgr_S_REPLYLATER Operation successful, reply will be sent when
1139 * the event happens.
1140 *
1141 * @sa ProcMgr_WaitForEventCancel
1142 */
1143 Int32 ProcMgr_waitForEvent (ProcMgr_ProcId procId,
1144 ProcMgr_EventType eventType,
1145 Int timeout);
1147 /*!
1148 * @brief Function that allows the caller to wait on the specified event
1149 *
1150 * @param procId Id of the processor on which to wait
1151 * @param eventType Array of event type on which to wait
1152 * @param size Number of events in eventType array
1153 * @param timeout Amount of time to wait for the event
1154 * @param index Index of the event which occurred. Output param.
1155 *
1156 * @retval ProcMgr_S_REPLYLATER Operation successful, reply will be sent when
1157 * the event happens.
1158 *
1159 * @sa ProcMgr_WaitForEventCancel
1160 */
1161 Int
1162 ProcMgr_waitForMultipleEvents (ProcMgr_ProcId procId,
1163 ProcMgr_EventType * eventType,
1164 UInt32 size,
1165 Int timeout,
1166 UInt * index);
1168 /*!
1169 * @brief Function that allows the caller to cancel a wait on the specified event
1170 *
1171 * @param procId procId on which to cancel wait
1172 * @param eventType Event type on which to cancel the wait
1173 *
1174 * @retval ProcMgr_S_SUCCESS Operation successful.
1175 *
1176 * @sa ProcMgr_WaitForEvent
1177 */
1178 Int32 ProcMgr_waitForEventCancel (ProcMgr_ProcId procId,
1179 ProcMgr_EventType eventType);
1181 /*!
1182 * @brief Function that un-registers for notification when the slave
1183 * processor transitions to any of the states specified.
1184 *
1185 * This function allows the user application to un-register for
1186 * changes in processor state and take actions accordingly.
1187 *
1188 * @param handle Handle to the ProcMgr object
1189 * @param fxn Handling function to be un-registered.
1190 * @param args Optional arguments associated with the handler fxn.
1191 * @param state Array of target states for which un-registration is
1192 * required.
1193 *
1194 * @retval ProcMgr_S_SUCCESS Operation successful
1195 * @retval ProcMgr_E_INVALIDARG Invalid parameter specified
1196 * @retval ProcMgr_E_INVALIDSTATE Module was not initialized
1197 * @retval ProcMgr_E_HANDLE Invalid NULL handle specified
1198 * @retval ProcMgr_E_OSFAILURE Failed in an OS-specific call
1199 *
1200 * @sa ProcMgr_State, ProcMgr_CallbackFxn, ProcMgr_registerNotify
1201 */
1202 Int ProcMgr_unregisterNotify (ProcMgr_Handle handle,
1203 ProcMgr_CallbackFxn fxn,
1204 Ptr args,
1205 ProcMgr_State state []);
1207 /* Function to flush cache */
1209 Int ProcMgr_flushMemory (Ptr bufAddr,
1210 UInt32 bufSize,
1211 ProcMgr_ProcId procID);
1214 /* Function to invalidate cache */
1216 Int ProcMgr_invalidateMemory (Ptr bufAddr,
1217 UInt32 bufSize,
1218 ProcMgr_ProcId procID);
1220 /* Function to get the Id of the ProcMgr handle */
1222 UInt32 ProcMgr_getId (ProcMgr_Handle handle);
1224 /* Function to get the handle based on the id. */
1226 ProcMgr_Handle ProcMgr_getHandle (UInt32 id);
1228 #if defined (__cplusplus)
1229 }
1230 #endif /* defined (__cplusplus) */
1232 #endif /* ProcMgr_H_0xf2ba */