svm_api.h

Sigma SMP8634 Mrua v. 2.8.2.0

/****************************************************************************
 *    Copyright (c) Sigma Designs, Inc. 2005. All rights reserved.
 **/
/**
 *      @file       svm_api.h
 *
 *      @brief      Implementation of an API for launching/interacting with
 *                  BD+ Virtual Machine.
 * 
 *
 *      @author     Alan Liddeke
 *      
 ****************************************************************************/
#ifndef __SVM_API_H__
#define __SVM_API_H__

/*---------------------------------------------------------------------------
                                  INCLUDES
 ---------------------------------------------------------------------------*/

#include "rmdef/rmdef.h"
#include "svm_def.h"
#include "svm_callbacks.h"
#include "svmintrp.h"

/*---------------------------------------------------------------------------
                             CONSTANT LITERALS
 ---------------------------------------------------------------------------*/
/** RUA memory must be allocated, locked and mapped!
 */
#define SVM_MEMORY_SIZE VM_RAM_SIZE + CACHED_CC_BLOCKSIZE + XTASK_BUFFER_SIZE + \
                        MEDIACHECK_BUFFER_SIZE //+ RUNNATIVE_BUFFER_SIZE


/* The preferred flash page for BD+ xtask */
#define BDPLUS_FLASH_PAGE  4
/* Invalid slot ID is currently used as the last parameter to 'Init_Preloaded' 
 * to specify that the xtask contained within the library should be used in 
 * leu of a preloaded image. */
#define BDPLUS_INVALID_SLOT 0xFFFFFFFF

/*---------------------------------------------------------------------------
                               CLASSES / TYPES
 ---------------------------------------------------------------------------*/

/* Forward Declarations */

/* SVM handle - opaque */
struct SVM;

/*---------------------------------------------------------------------------
                             FUNCTION PROTOTYPES
 ---------------------------------------------------------------------------*/


/**
 * SVM_Init - Initialize/Open the BD+ virtual machine.
 * 
 * @brief Initialize the SVM including launch of the BD+ core xtask.
 * This will NOT initiate the BD+ intterupt InitializeMedia, nor load
 * the file "00000.svm" into the VM. This will be done when you queue
 * an InitializeMedia interrupt.
 * Only one call to SVM_Init is necessary for multiple Media session.
 *
 * @param pSVMContext      - The base context to the Virtual machine. (created in this call)
 * @param pSVMCallbacks    - Callback table that must be filled in before initializing.
 * @param callback_ctx     - State information kept for all of the callbacks.
 * @param svm_ram_addr     - The base address to be used for the VM Ram space.
 * @param rua_addr         - The unmapped rua address for the start of svm_ram.
 * @param svm_ram_size     - The size allocated for VM Ram.
 * @param xtask_ram_addr   - Base address for bd+ core xtask communication.
 * @param xtasK_ram_size   - The size allocated for xtask communication.
 * @param xtask_flash_page - The XPU serial flash page used by the bd+ core xtask.
 * @param xtask_slot_id    - The slot id of the preloaded xtask (BDPLUS_INVALID_SLOT will
 *                           instead use the xtask contained within the shared library)
 *                           
 * @return RM_OK         - successful initialization.
 *         RM_NOT_FOUND  - BD+ not present on disc.
 *         RM_ERROR      - failed to initialize.
 *
 *         ( Extra return values when using BD+ with InitPreloaded only )
 *         RM_DRM_XSTART_FAILURE     - No xtask image found in slot specified.
 *         RM_DRM_XTASK_SYNC_FAILURE - xtask image found, however, sync failed.  Xtask Mismatch?
 *         RM_DRM_XTASK_MISMATCH     - xtask image found, sync completed, DRM type invalid. Xtask Mismatch!
 *         RM_DRM_VERSION_MISMATCH   - xtask image found, sync completed, DRM type valid, version Mismatch!
 *         
 **/
RMstatus SVM_Init(struct SVM** pSVMContext, struct SVM_Callbacks *pSVMCallbacks, void *callback_ctx, 
		  RMuint8* svm_ram_addr, RMuint32 rua_addr, RMuint32 svm_ram_size, RMuint32 xtask_flash_page);

RMstatus SVM_Init_Preloaded(struct SVM** pSVMContext, struct SVM_Callbacks *pSVMCallbacks, void *callback_ctx, 
		  RMuint8* svm_ram_addr, RMuint32 rua_addr, RMuint32 svm_ram_size, RMuint32 xtask_flash_page, RMuint32 xtask_slot_id);


/**
 * SVM_Term - Terminate/Close the BD+ virtual machine.
 * 
 * @brief Terminate the SVM, including stoping the BD+ core xtask.
 * This will not cause any content code to run, during normal operation
 * a Shutdown INTRP will cause the final content code to run.
 *
 * @param pSVMContext - The base context to the Virtual machine. (invalid after this call)
 * @return RM_OK    - successful termination.
 * @return RM_ERROR - failed to terminate.
 **/
RMstatus SVM_Term(struct SVM *pSVMContext);

/**
 * SVM_QueueInterrupt
 * 
 * This function will handle passing of interrupts to the SVM.  If the
 * interrupt is not allready queued and it is valid then it will be 
 * queued.  Interrupt Pending count is incremented and handled by 
 * subsequent calls to SVM_Run_VM()
 *
 * @param pSVMContext - base context of the SVM.
 * @param pSVMINTRPContext - pointer to the interrupt parameter block of the 
 *                           given interrupt.
 * 
 * @return RM_OK    - Successful queue
 *         RM_ERROR - Unable to queue.
 **/
RMstatus SVM_QueueInterrupt(struct SVM* pSVMContext, union SVMINTRP* pSVMINTRPContext);


/**
 * SVM_VMRun 
 *
 * Runs the VM for a specified number of cycles, or until a change from either BG-mode
 * to IDLE-mode, or from Interrupt-mode to BG-mode.
 *
 * @param pSVMContext - pointer to base context for SVM.
 * @param numCycles - number of VM cycles to execute.
 * 
 * @return RM_OK          - Nothing more to do
 *         RM_TIMEOUT     - No more TUs left for interrupt(content code ERROR!)
 *         RM_PENDING     - Interrupt or BG mode still pending more cycles.
 *         RM_INVALIDMODE - VM is in IDLE mode, nothing to do.
 *         RM_ERROR       - Fatal error occured. VM should be shutdown.
 *         RM_ERROR_NOTHING_TO_DO - The vm is currently in background mode, and
 *                                  content code has issued syscall(0x10) to
 *                                  signify that there is no reason to give
 *                                  background mode anymore cycles.
 **/
RMstatus SVM_VMRun(struct SVM *pSVM, RMint32 *numCycles);

#endif // __SVM_API_H__