//
// File:   overlay.h
//
//  This file implements interface to dsp overlays handling: initialization,
//  loading and running. Each dsp overlay must be  implemented and linked
//  in its own dsp unit. The core for overlay loading is set by function
//  set_curr_dsp before init. All dsp overlay program must be linked into
//  external memory before loading into dsp memory.
//  Functionality of this module is incapsulted into risc_dsp_caller module.
//
// (c) multicore.ru
//

#ifndef _OVERLAY_H_
#define _OVERLAY_H_

#ifdef	__cplusplus
extern "C" {
#endif

// Constant: DSP_TASK_SINGLE
// Constant DSP_TASK_SINGLE set maximum number of supported overlays
#define MAX_OVERLAY_CTX 16
// Constant: MAX_DSP
// Constant MAX_DSP set maximum number of supported dsp cores
#define MAX_DSP 2

//
// struct represent description of dsp core
//
struct dsp_ctx_info
{
    // dsp core id [0..3]
	unsigned  num;
    //
	unsigned  qstr_stop;
    // page mdoe(0,2,3) - sets ratio between pram:xram memory size
	unsigned  page_mode;
    // base address of pram memory
	unsigned  pram_base;
    // size of pram memory
	unsigned  pram_size;
    // base address of xram memory
	unsigned  xyram_base;
    // size of xram memory
	unsigned  xyram_size;
	unsigned  __present;		//
};

//
// struct represent description of overlay loaded into dsp
//
struct ovl_ctx
{
	// text section addresses
	unsigned *__text_src;
	unsigned *__text_dst;
	unsigned  __text_offset;
	unsigned  __text_size;
	unsigned *__exit_address;

	// data section addresses
	unsigned *__data_src;
	unsigned *__data_dst;
	unsigned  __data_size;
	// bss section addresses
	unsigned *__bss_src;
	unsigned *__bss_dst;
	unsigned  __bss_size;
	// overlay_info
	unsigned  __present;
	unsigned  __exit_dsp;
	unsigned  __num;
	// dsp core where ovelay is loaded
	struct dsp_ctx_info * dsp_info;
};

//
// struct represent description of all overlays in program
//
struct ovl_dsp_ctx
{
	struct ovl_ctx ctx[MAX_OVERLAY_CTX];
	struct dsp_ctx_info info;

	unsigned curr_ctx_num;
};

/**
 * Adds description of dsp.
 *
 * @param num Id of dsp core to add
 * @param page_mode Page mode defines memory size of pram and xram
 * @param qstr_stop Mask of qstr register shows processor is stopped
 * @param pram_base Base address of pram
 * @param xyram_base Base address of xram
 */
void add_dsp_entry(
        unsigned  num,
        unsigned  page_mode,
        unsigned  qstr_stop,
        unsigned  pram_base,
        unsigned  xyram_base);

// Section: Functions
//
// Function: set_curr_dsp
//
// Switch working dsp. Use this function before initialization of overlay section.
//
// Parameters:
//      num      - dsp core id
//
void set_curr_dsp(unsigned num);

// Function: config_overlay
//
// Init dsp description entries, set page mode, setup overlay config
//
// Parameters:
//      num   - dsp num (0..3)
//      page_mode - (0,2,3) - sets ratio between pram:xram memory size
//
void config_overlay(unsigned num, unsigned page_mode);

// Function: init_overlay
//
// Select active overlay and load it into memory
//
// Parameters:
//      num      - number of overlay id in implemented overlays
//		array
//
void init_overlay(unsigned num);

// Function: find_overlay_ctx
//
// Finds overlay section in all implememted overlay sections
// by given function address.
//
// Parameters:
//      address      - name of funciton overlay section contains
//
struct ovl_ctx* find_overlay_ctx(unsigned address);

// Function: load_overlay
//
// Loads overlay section into dsp memory. The overlay section previously
// loaded into dsp memory is overwritten after this call.
//
// Parameters:
//      ctx      - pointer to overlay to report
//
int load_overlay(struct ovl_ctx* ctx);

// Function: print_overlay
//
// Report overlay content: addresses of sections where they are linked
//	and where they would be loaded.
//
// Parameters:
//      ctx      - pointer to overlay to report
//
void print_overlay(struct ovl_ctx* ctx);

// Function: print_dsp_memory_info
//
// Report dsp memory settings
//
void print_dsp_memory_info();

//
// converts address from dsp byte address space into risc address space
//
unsigned xyram_byte_address_to_risc(unsigned address, unsigned page_size);

//
// converts address from dsp byte address space into risc address space
//
unsigned xyram_word_address_to_risc(unsigned address, unsigned page_size);

//
// converts address from risc address space into dsp byte address space
//
unsigned risc_to_xyram_byte_address(unsigned address, unsigned page_size);

//
// gets size of memory page accordingly to page_mode
//
unsigned get_page_size(unsigned page_mode);

#ifdef	__cplusplus
}
#endif

#endif // _OVERLAY_H_