/*
 * File:   risc_dsp_caller.h
 *
 *  Risc_dsp_caller provides interface to dsp tasks handling by risc processor. Risc processor
 *  is used as cpu, it creates, initializes, runs dsp tasks. One dsp task must be implemented
 *  as one dsp unit.
 *  Requirement: To use this module you must generate overlay description tables by the elcore-xlgen
 *  tool and include generated overlay.inc if you include risc_dsp_caller.h in your application.
 *  Add, e.g. in main.c,
 * > #include "risc_dsp_caller.h"
 * > #include "overlay.h"
 * > #include "overlay.inc"
 *
 * (c) multicore.ru
 */

#include "erlcommon.h"
#include "libdsp.h"
#include "overlay.h"

#ifndef _RISC_DSP_CALLER_H_
#define _RISC_DSP_CALLER_H_

#ifdef	__cplusplus
extern "C" {
#endif

// Enumeration: DSP_TASK_STATUS
//
// Enum DSP_TASK_STATUS describes status of dsp task
//
enum DSP_TASK_STATUS
{
	// Constant: DSP_TASK_EMPTY
	// task is not created
    DSP_TASK_EMPTY,
	// Constant: DSP_TASK_READY
	// task is ready to run
    DSP_TASK_READY,
	// Constant: DSP_TASK_RUNNING
	// task is executed by dsp processor
    DSP_TASK_RUNNING,
	// Constant: DSP_TASK_TERMINATED
	// dsp has executed task and stoped
    DSP_TASK_TERMINATED,
	// Constant: DSP_TASK_BLOCKED
	// task is blocked by interrupt or by other reason
    DSP_TASK_BLOCKED
};

// Enumeration: DSP_TASK_MODE
//
// Enum DSP_TASK_MODE describes how dsp cores are working in api. Possible ways
// are the next - only one core is running, two cores are running and
// two cores are starting simultaneously (syncronized)
// DSP_TASK_SINGLE mode is set as default mode.
//
enum DSP_TASK_MODE
{
	// Constant: DSP_TASK_SINGLE
	// only one core is working
    DSP_TASK_SINGLE = 0x1,
	// Constant: DSP_TASK_PARALLEL
	//  more than one core are working
    DSP_TASK_PARALLEL = 0x2,
	// Constant: DSP_TASK_SYNC
	// cluster works in synchronous mode (simultaneously start)
    DSP_TASK_SYNC = 0x4
};

#define DSP_TASK_MAX_PARAMETERS 16

typedef struct _reg_pair
{
    // Variable: reg_offset
    // Offset of regiter in dsp_regs of another structure
    int reg_offset;      
    // Variable: reg_value
    // Value of register
    int reg_value;
} reg_pair;

//
// Class: dsp_task_info
//
// Dsp task descriptor
//
//
struct dsp_task_info
{
    // Variable: status
    // state of task
    enum DSP_TASK_STATUS status;
    // Variable: ctx
    // overlay descriptor with function
    struct ovl_ctx *ctx;
    // Variable: dsp_num
    // id of dsp where task is running
    int dsp_num;
    // Variable: dsp_regs
    // Pointer to dsp register structure
    struct _dsp_regs* dsp_regs;
    // Variable: dsp_comm_regs
    // Pointer to dsp common register structure
    common_regs*      dsp_comm_regs;
    // Variable: register_context[DSP_TASK_MAX_PARAMETERS = 16]
    // Context of register values to initialize DSP core registers
    reg_pair register_ctx[DSP_TASK_MAX_PARAMETERS];
    // Variable: qstr_stop
    // qstr_stop mask
    int qstr_stop;
    // Variable: dsp_pc
    // entry point (in terms of dsp pc value)
    int dsp_pc;
    // Variable: dsp_sp_value
    // stack pointer
    int dsp_sp_value;
    // Variable: dsp_fp_value
    // frame pointer
    int dsp_fp_value;
    // Variable: hasInterruptHandler
    // if task with interrupt
    int hasInterruptHandler;
};

// Section: Functions
//
// Function: risc_dsp_set_mode
//
// Setup dsp cores running mode (single, paralle or syncronized)
//
// Parameters:
//      mode      - dsp running mode
//
// > risc_dsp_set_mode(DSP_TASK_SINGLE);
// > risc_dsp_set_mode(DSP_TASK_PARALLEL);
// > risc_dsp_set_mode(DSP_TASK_SYNC);
// > risc_dsp_set_mode(DSP_TASK_PARALLEL|DSP_TASK_SYNC);
//
// See also:
//  <enum DSP_TASK_MODE>
//
void risc_dsp_set_mode(enum DSP_TASK_MODE mode);

// Function: risc_dsp_init_task
//
// Prepare task, calculates values of register for starting of dsp program
//
// Parameters:
//      pTask      - pointer to task descriptor
//      fnAddress  - function to be started as dsp task
//
enum ERL_ERROR risc_dsp_init_task(struct dsp_task_info* pTask, unsigned int fnAddress );

enum ERL_ERROR risc_dsp_init_asm_task(struct dsp_task_info* pTask, unsigned int fnAddress,
        reg_pair _register_context[], int n_regiter_context);

// Function: risc_dsp_load_task
//
// Loads task context into dsp memory, setups dsp specific register to start
// dsp application execution
//
// Parameters:
//      pTask      - pointer to task descriptor, it must be previously initialized
//                   with risc_dsp_init_task function
//
// Return: ERL_ERROR - state of load function
//
// See also:
//
//      <risc_dsp_init_task>
//      <risc_dsp_run_task>
//
enum ERL_ERROR risc_dsp_load_task(struct dsp_task_info* pTask);

// Function: risc_dsp_load_task
//
// Prepair task context in dsp memory, setups dsp specific register to start
// dsp application execution
//
// Parameters:
//      pTask      - pointer to task descriptor, it must be previously initialized
//                   with risc_dsp_init_task function
//
// Return: ERL_ERROR - state of load function
//
// See also:
//
//      <risc_dsp_init_task>
//      <risc_dsp_run_task>
//
enum ERL_ERROR risc_dsp_prepair_task(struct dsp_task_info* pTask);


// Function: risc_dsp_run_task
//
// Starts execution of task by writing start bit to dcsr register
//
// Parameters:
//      pTask      - pointer to task descriptor, it must be previously initialized
//                   with risc_dsp_init_task function
//
// Return: ERL_ERROR - state of init function
//
// See also:
//
//      <risc_dsp_init_task>
//      <risc_dsp_load_task>
//
enum ERL_ERROR risc_dsp_run_task(struct dsp_task_info* pTask);

// Function: risc_dsp_run_task
//
// Starts execution of tasks by writing start bit to dcsr register if the
// parallel mode is set or sync start of the dsp cluster if sync mode is set
//
// Parameters:
//      pTask0      - pointer to the first task descriptor, it must be
//                    previously initialized with risc_dsp_init_task function
//      pTask1      - pointer to the second task descriptor, it must be
//                    previously initialized with risc_dsp_init_task function
// Return: ERL_ERROR - state of init function
//
// See also:
//
//      <risc_dsp_init_task>
//      <risc_dsp_load_task>
//
enum ERL_ERROR risc_dsp_run_tasks(struct dsp_task_info* pTask0,
                                  struct dsp_task_info* pTask1);

// Function: risc_dsp_wait_task
//
// Waits the corresponding dsp core to task stops its execution. Function sets
// the state of task into DSP_TASK_TERMINATED is dsp core stops its execution
//
// Parameters:
//      pTask      - pointer to task descriptor, it must be previously initialized
//                   with risc_dsp_init_task function
//
// Return: ERL_UNITIALIZED_ARG - function gets zero-pointer to task info
//         ERL_NO_ERROR, pTask->status = DSP_TASK_TERMINATED - task is terminated
//
// See also:
//
//      <risc_dsp_init_task>
//      <risc_dsp_run_task>
//
enum ERL_ERROR risc_dsp_wait_task(struct dsp_task_info* pTask);

// Function: risc_dsp_wait_all_tasks
//
// Waits both tasks stopped its execution. 
//
// Parameters:
//      pTask0     - pointer to the 1st task descriptor, it must be previously 
//                  initialized with risc_dsp_init_task function
//      pTask1     - pointer to the 2nd task descriptor, it must be previously 
//                  initialized with risc_dsp_init_task function
//
// Return: ERL_UNITIALIZED_ARG - function gets zero-pointer to one of tasks info
//         ERL_NO_ERROR, pTask0->status = DSP_TASK_TERMINATED,
//         pTask1->status = DSP_TASK_TERMINATED,   - both tasks are terminated
//
// See also:
//
//      <risc_dsp_init_task>
//      <risc_dsp_run_task>
//
enum ERL_ERROR risc_dsp_wait_all_tasks(struct dsp_task_info* pTask0,
                                       struct dsp_task_info* pTask1);

// Function: risc_dsp_wait_any_task
//
// Waits one of given tasks stops its execution. If all tasks are terminated
// already the function do nothing. If one of tasks is terminated already the 
// function waits anonther task stops its execution.
//
// Parameters:
//      pTask0     - pointer to the 1st task descriptor, it must be previously 
//                  initialized with risc_dsp_init_task function
//      pTask1     - pointer to the 2nd task descriptor, it must be previously 
//                  initialized with risc_dsp_init_task function
//      pTaskStopped  - the function sets its value to the task is terminated
//
// Return: ERL_UNITIALIZED_ARG - function gets zero-pointer to one of tasks info
//         ERL_NO_ERROR  - one task is terminated or both tasks are terminated
//
// See also:
//
//      <risc_dsp_init_task>
//      <risc_dsp_run_task>
//
enum ERL_ERROR risc_dsp_wait_any_task(struct dsp_task_info* pTask0,
                                      struct dsp_task_info* pTask1, 
                                      struct dsp_task_info* pTaskStopped);

// Function: risc_dsp_free_task
//
// Clean source given to task
//
// Parameters:
//      pTask      - pointer to task descriptor, it must be previously initialized
//                   with risc_dsp_init_task function
//
// See also:
//
//      <risc_dsp_init_task>
//
void           risc_dsp_free_task(struct dsp_task_info* pTask);

// Function: remap_addr_risc2dsp_data
//
// Converting risc pointer data adress to dsp before loading
// of overlay section
//
// Parameters:
//      pTtask      - task descriptor, it must be previously initialized
//                   with risc_dsp_init_task function
//	addr - adress to be converting
//
// Return: unsigned - dsp adress
//
// See also:
//
//      <risc_dsp_init_task>
//
unsigned int remap_addr_risc2dsp_data(struct dsp_task_info task, void *addr);

// Function: remap_addr_risc2dsp_text
//
// Converting risc pointer text adress to dsp before loading
// of overlay section
//
// Parameters:
//      pTtask      - task descriptor, it must be previously initialized
//                   with risc_dsp_init_task function
//	addr - adress to be converting
//
// Return: unsigned - dsp adress
//
// See also:
//
//
unsigned int remap_addr_risc2dsp_text(struct dsp_task_info task, void *addr);


#ifdef	__cplusplus
}
#endif

#endif // _RISC_DSP_CALLER_H_