/*
****************************************************************************
PROJECT : VOWE driver
FILE : $Id: r_vowe_api.h 15479 2018-01-11 14:04:31Z florian.zimmermann $
============================================================================
DESCRIPTION
Driver for the VOWE(Video Output Warping Engine) macro
============================================================================
C O P Y R I G H T
============================================================================
Copyright (c) 2013 - 2014
by
Renesas Electronics (Europe) GmbH.
Arcadiastrasse 10
D-40472 Duesseldorf
Germany
All rights reserved.
============================================================================
DISCLAIMER
LICENSEE has read, understood and accepted the terms and conditions defined in
the license agreement, especially the usage rights. In any case, it is
LICENSEE's responsibility to make sure that any user of the software complies
with the terms and conditions of the signed license agreement.
****************************************************************************
*/
/***************************************************************************
Title: VOWE Driver API
VOWE (Video Output Warping Engine) driver API
VOWE driver controls VOWE H/W macro and accesses following registers.
* VOWE H/W macro. (D1x UM section 39)
* VOWEMAC & VOWEMMC. (D1x UM section 37.11)
VOWE driver also controls VDCE driver via VOWE support functions.
An application using VOWE driver should include the following header files.
* r_typedefs.h
* r_vowe_api.h
*/
#ifndef R_VOWE_API_H_
#define R_VOWE_API_H_
#ifdef __cplusplus
extern "C" {
#endif
/***************************************************************************
Section: Global defines
*/
/***************************************************************************
Group: Constants
*/
/***************************************************************************
Constants: API Version
This constant is the value which shows the version information of the VOWE driver.
It refers at the <R_VOWE_VersionStringGet> function.
Values:
R_VOWE_VERSION_HI - This constant is the high byte of the version information.
It is major version information.
R_VOWE_VERSION_LO - This constant is the low byte of the version information.
It is miner version information.
High and Low number of the API version
*/
#define R_VOWE_VERSION_HI 1
#define R_VOWE_VERSION_LO 15
/***************************************************************************
Constants: Interrupt Factor
This definition describes the factor of callback.
Values:
R_VOWE_FACTOR_NON - This definition specifies no factor.
R_VOWE_FACTOR_TRA - This definition specifies the TRA occurred. It means that
the warping correction processing was complete.
R_VOWE_FACTOR_IER - This definition specifies the IER occurred. It means that
VOWE H/W macro processed tha invalid display list (DL).
R_VOWE_FACTOR_STOP - This definition specifies the the stop command finished and
the state is in the Idle state.
*/
#define R_VOWE_FACTOR_NON (0x00000000uL)
#define R_VOWE_FACTOR_TRA (0x00000001uL)
#define R_VOWE_FACTOR_IER (0x00000002uL)
#define R_VOWE_FACTOR_STOP (0x00000008uL)
/***************************************************************************
Constants: Pixel size
This definition describes the pixel size.
Values:
R_VOWE_SIZE_OF_ARGB8888 - This definition specifies the pixel size of ARGB8888 format.
R_VOWE_SIZE_OF_RGB565 - This definition specifies the pixel size of RGB565 format.
*/
#define R_VOWE_SIZE_OF_ARGB8888 (4)
#define R_VOWE_SIZE_OF_RGB565 (2)
/***************************************************************************
Section: Global Types
*/
/***************************************************************************
Group: Enumerations and Types
*/
/***************************************************************************
Enum: r_vowe_Error_t
Description:
This type describes the error code of the VOWE driver.
Values:
R_VOWE_ERR_OK - No error has occurred.
R_VOWE_ERR_NG - The error out of the assumption.
R_VOWE_ERR_PARAM_INCORRECT - A parameter provided to a function is incorrect.
( It excludes the outside of the range )
R_VOWE_ERR_RANGE_UNIT - The unit-number error.
R_VOWE_ERR_RANGE_PARAM - The parameter error in the range.
R_VOWE_ERR_NOT_ACCEPTABLE - A function was called in an incorrect state.
R_VOWE_ERR_FATAL_OS - Fatal error has occurred at OS interface.
R_VOWE_ERR_FATAL_HW - Fatal error has occurred at H/W.
R_VOWE_ERR_SYS_VDCE - The error has occurred at the driver support function
of VDCE driver.
R_VOWE_ERR_SYS_INTC - The error has occurred at the driver support function
of INTC (interrupt contoroller).
*/
typedef enum
{
R_VOWE_ERR_OK = 0,
R_VOWE_ERR_NG,
R_VOWE_ERR_PARAM_INCORRECT,
R_VOWE_ERR_RANGE_UNIT,
R_VOWE_ERR_RANGE_PARAM,
R_VOWE_ERR_NOT_ACCEPTABLE,
R_VOWE_ERR_FATAL_OS,
R_VOWE_ERR_FATAL_HW,
R_VOWE_ERR_SYS_VDCE,
R_VOWE_ERR_SYS_INTC
} r_vowe_Error_t;
/***************************************************************************
Typedef: r_vowe_SourceConfig_t
Description:
This type describes the structure of the source image information.
Struct members:
LineStartPos - This member specifies the start position of source image.
In the detail of LineStartPosition, refer to VOWE of H/W manual.
(1 <= LineStartPos <= 1,019)
SourceWidth - This member specifies the source image width (pixel).
(4 <= SourceWidth <= 1,280)
SourceHeight - This member specifies the source image height (pixel).
(5 <= SourceHeight <= 1,024)
*/
typedef struct
{
uint32_t LineStartPos;
uint32_t SourceWidth;
uint32_t SourceHeight;
} r_vowe_SourceConfig_t;
/***************************************************************************
Typedef: r_vowe_DisplayList_t
Description:
This type describes the structure of the display list information.
Struct members:
DspList - This is a pointer to the top address of the display list (DL).
The address must be a multiple of 8 bytes.
Size - This member specifies the size of display list.
*/
typedef struct
{
uint32_t * DspList;
uint32_t Size;
} r_vowe_DisplayList_t;
/***************************************************************************
Enum: r_vowe_BufferMode_t
Description:
This type describes the work buffer mode.
Values:
R_VOWE_FRAME_BUFFER_MODE - This member specifies the frame buffer mode.
If using the WorkBuffferAddr of <r_vowe_DestConfig_t>
as the frame buffer, specify this mode.
R_VOWE_RING_BUFFER_MODE - This member specifies the ring buffer mode.
If using the WorkBuffferAddr of <r_vowe_DestConfig_t>
as the ring buffer, specify this mode.
*/
typedef enum
{
R_VOWE_FRAME_BUFFER_MODE = 0,
R_VOWE_RING_BUFFER_MODE
} r_vowe_BufferMode_t;
/***************************************************************************
Enum: r_vowe_ColorFormat_t
Description:
This type describes the color format.
Values:
R_VOWE_FORMAT_ARGB8888 - This member specifies the ARGB8888 format.
R_VOWE_FORMAT_RGB565 - This member specifies the RGB565 format.
*/
typedef enum
{
R_VOWE_FORMAT_ARGB8888 = 0,
R_VOWE_FORMAT_RGB565
} r_vowe_ColorFormat_t;
/***************************************************************************
Enum: r_vowe_DestMode_t
Description:
This type describes the destination mode.
Values:
R_VOWE_DEST_MODE_NORMAL - This member specifies the NORMAL mode.
R_VOWE_DEST_MODE_SCREEN_SHOTS - This member specifies the SCREEN SHOTS mode.
A distortion image by VOWE is not output to
LCD panel. A distortion image data is only
extracted by the frame buffer.
*/
typedef enum
{
R_VOWE_DEST_MODE_NORMAL = 0,
R_VOWE_DEST_MODE_SCREEN_SHOTS
} r_vowe_DestMode_t;
/***************************************************************************
Typedef: r_vowe_DestConfig_t
Description:
This type describes the structure of the destination buffer settings information.
The application must allocate the work buffer to set to WorkBufferAddr of this structure.
The top address of work buffer must be a multiple of 1024 bytes. Allocate the work buffer
at the following size.
* In case of the frame buffer mode (<R_VOWE_FRAME_BUFFER_MODE>)
(code)
Work buffer size (byte) = stride * source height * pixel size * 2
stride = ((source width + (128 - 1)) / 128) * 128
pixle size:
- R_VOWE_FORMAT_ARGB8888: 4 bytes
- R_VOWE_FORMAT_RGB565: 2 bytes.
(end)
* In case of the ring buffer mode (<R_VOWE_RING_BUFFER_MODE>)
Work buffer size (byte) is 2 exponentiations.
ex) The example with the work buffer size which can be chosen
(code)
: :
256 kbyte : 0x40000
128 kbyte : 0x20000
64 kbyte : 0x10000
32 kbyte : 0x08000
: :
(end)
Struct members:
WorkBufferMode - This member specifeis the work buffer mode. See <r_vowe_BufferMode_t>.
WorkBufferAddr - This is a pointer to the top address of the work buffer.
WorkBufferSize - This member specifies the work buffer size.
ColorFormat - This member specifies the color format of output image.
See <r_vowe_ColorFormat_t>.
DitherMode - This member specifies the dither mode. If this member is setted true (R_TRUE),
dither is ON. If this member is setted false (R_FALSE), dither is OFF.
Note that if ColorFormat is <R_VOWE_FORMAT_ARGB8888>, this member is ignored.
RingBufferDelay - This member specifies the number of output delay lines of VDCE.
Note that if WorkBufferMode is <R_VOWE_FRAME_BUFFER_MODE>, this member
is ignored.
(1 <= RingBufferDelay <= 255)
> Recommended Delay:
> RingBufferDelay = 16 + VerticalScreenTiming->BackPorch + Vertical Distortion Distance
BackPorch is the time after the Sync Pulse.
> Vertical Blanking Pulse:
> ___________
> ____________| |___________
> Front Porch SyncWidth BACK PORCH
DestMode - This member specifies the destination mode.
See <r_vowe_DestMode_t>.
Note:
In addition to the memory area occupied by the work buffer, the next 512 bytes of memory must
be readable by the VDCE H/W. VDCE will neither use or modify the data in this area, so it may
be used by any other purpose.
Please be careful when you assign the work buffer at the end of VRAM, SDRAM or other memory
area.
For details consult the D1x H/W User-manual (section: 38.6.1.2 (6) Restriction).
*/
typedef struct
{
r_vowe_BufferMode_t WorkBufferMode;
uint8_t* WorkBufferAddr;
uint32_t WorkBufferSize;
r_vowe_ColorFormat_t ColorFormat;
uint32_t DitherMode;
uint32_t RingBufferDelay;
r_vowe_DestMode_t DestMode;
} r_vowe_DestConfig_t;
/***************************************************************************
Typedef: r_vowe_CallbackFunction_t
Description:
This type describes to callback function.
and error.
Struct members:
Unit - The parameter specifies the instance number.
Factor - This parameter is the interrupt factor.
CallbackParam - This parameter is the CallbackParam which is specified the <R_VOWE_Open>
function.
*/
typedef void (*r_vowe_CallbackFunction_t)(
const uint32_t Unit,
const uint32_t Factor,
const uint32_t CallbackParam);
/***************************************************************************
Section: Global API functions
*/
/***************************************************************************
Function: R_VOWE_Init
Description:
This function initializes the VOWE driver.
<R_VOWE_Init> function shall be the first call and should be executed only one time
without an intervening <R_VOWE_DeInit> function.
If the function successfully execute, the return code will be <R_VOWE_ERR_OK> and
the state will be in the Initialize state.
Note that this function can't call from interrupt handler.
Parameter:
Unit - The parameter specifies the instance number.
Return value:
R_VOWE_ERR_OK - No error has occurred.
R_VOWE_ERR_RANGE_UNIT - The unit-number error.
R_VOWE_ERR_NOT_ACCEPTABLE - A function was called in an incorrect state.
R_VOWE_ERR_FATAL_OS - Fatal error has occurred at OS interface.
See <r_vowe_Error_t>.
*/
r_vowe_Error_t R_VOWE_Init(const uint32_t Unit);
/***************************************************************************
Function: R_VOWE_DeInit
Description:
This function de-initializes theVOWE driver.
<R_VOWE_DeInit> function should be the last call after all VOWE driver related
resources have been released.
If the function successfully execute, the return code will be <R_VOWE_ERR_OK> and
the state will be in the Uninitialize state.
Note that this function can't call from interrupt handler.
Parameter:
Unit - The parameter specifies the instance number.
Return value:
R_VOWE_ERR_OK - No error has occurred.
R_VOWE_ERR_RANGE_UNIT - The unit-number error.
R_VOWE_ERR_NOT_ACCEPTABLE - A function was called in an incorrect state.
R_VOWE_ERR_FATAL_OS - Fatal error has occurred at OS interface.
See <r_vowe_Error_t>.
*/
r_vowe_Error_t R_VOWE_DeInit(const uint32_t Unit);
/***************************************************************************
Function: R_VOWE_Open
Description:
This function opens the VOWE driver.
This functions sets the source image information, the display list (DL) information,
the destination buffer information and the callback function information.
If the function successfully execute, the return code will be <R_VOWE_ERR_OK> and the
state will be in the Idle state.
Note that this function can't call from interrupt handler.
Parameter:
Unit - The parameter specifies the instance number.
SourceConfig - The parameter specifies the source image information.
See <r_vowe_SourceConfig_t>.
DisplayList - The parameter specifies the display list information.
See <r_vowe_DisplayList_t>.
DestConfig - The parameter specifies the the destination buffer informatiom.
See <r_vowe_DestConfig_t>.
CallbackFunc - This parameter specifies the callback function that will be called when
the warping correction processing is finished or the error occurred.
If the callback function unnecessary, sets NULL (R_NULL).
See <r_vowe_CallbackFunction_t>.
CallbackParam - This parameter specifies the value which is passed the callback function.
Use is freedom of an application layer. If that's unnecessary, set 0.
Return value:
R_VOWE_ERR_OK - No error has occurred.
R_VOWE_ERR_PARAM_INCORRECT - A parameter provided to a function is incorrect.
R_VOWE_ERR_RANGE_UNIT - The unit-number error.
R_VOWE_ERR_NOT_ACCEPTABLE - A function was called in an incorrect state.
R_VOWE_ERR_FATAL_OS - Fatal error has occurred at OS interface.
See <r_vowe_Error_t>.
*/
r_vowe_Error_t R_VOWE_Open(
const uint32_t Unit,
const r_vowe_SourceConfig_t * const SourceConfig,
const r_vowe_DisplayList_t * const DisplayList,
const r_vowe_DestConfig_t * const DestConfig,
const r_vowe_CallbackFunction_t CallbackFunc,
const uint32_t CallbackParam);
/***************************************************************************
Function: R_VOWE_Close
Description:
This function closes the VOWE driver.
If the function successfully execute, the return code will be <R_VOWE_ERR_OK> and the
state will be in the Initialize state.
Note that this function can't call from interrupt handler.
Parameter:
Unit - The parameter specifies the instance number.
Return value:
R_VOWE_ERR_OK - No error has occurred.
R_VOWE_ERR_RANGE_UNIT - The unit-number error.
R_VOWE_ERR_NOT_ACCEPTABLE - A function was called in an incorrect state.
R_VOWE_ERR_FATAL_OS - Fatal error has occurred at OS interface.
See <r_vowe_Error_t>.
*/
r_vowe_Error_t R_VOWE_Close(const uint32_t Unit);
/***************************************************************************
Function: R_VOWE_Start
Description:
This function starts the warping correction.
If the function successfully execute, the return code will be <R_VOWE_ERR_OK> and
the state will be in the Execution state.
Note that this function can't call from interrupt handler.
Parameter:
Unit - The parameter specifies the instance number.
ContinuousMode - The parameter specifies the continuouse mode or one-shot mode.
If ContinuousMode is R_TURE, this driver processes the warping correction
processing every time the VSYNC interrupt occurs. The warping correction
processing is done until the <R_VOWE_Stop> function can be called.
If ContinuousMode is false (R_FALSE), this driver processes the warping correction
processing only once when VSYNC interrupt occurrs and this driver transfers
automatically to the Idle state. It does not need to call the <R_VOWE_Stop>
function.
Return value:
R_VOWE_ERR_OK - No error has occurred.
R_VOWE_ERR_PARAM_INCORRECT - A parameter provided to a function is incorrect.
R_VOWE_ERR_RANGE_UNIT - The unit-number error.
R_VOWE_ERR_NOT_ACCEPTABLE - A function was called in an incorrect state.
R_VOWE_ERR_FATAL_OS - Fatal error has occurred at OS interface.
See <r_vowe_Error_t>.
*/
r_vowe_Error_t R_VOWE_Start(const uint32_t Unit, const uint32_t ContinuousMode);
/***************************************************************************
Function: R_VOWE_Stop
Description:
This function stops the warping correction.
If the function successfully execute, the return code will be <R_VOWE_ERR_OK>. Whrn the warping
correction processing stops, the callback function is called with <R_VOWE_FACTOR_STOP> and
the state is in the Idle state.
Note that this function can't call from interrupt handler.
Note that when a callback function is not called with <R_VOWE_FACTOR_STOP> during
2 VSYNC period after <R_VOWE_Stop> fuction execution, reset a system.
Parameter:
Unit - The parameter specifies the instance number.
Return value:
R_VOWE_ERR_OK - No error has occurred.
R_VOWE_ERR_RANGE_UNIT - The unit-number error.
R_VOWE_ERR_NOT_ACCEPTABLE - A function was called in an incorrect state.
R_VOWE_ERR_FATAL_OS - Fatal error has occurred at OS interface.
See <r_vowe_Error_t>.
*/
r_vowe_Error_t R_VOWE_Stop(const uint32_t Unit);
/***************************************************************************
Function: R_VOWE_DLChange
Description:
This function changes the display list (DL).
If the function successfully execute, the return code will be <R_VOWE_ERR_OK> and
the new display list (DL) is reflected when <R_VOWE_Start> function is called.
Note that this function can't call from interrupt handler.
Parameter:
Unit - The parameter specifies the instance number.
DisplayList - The parameter specifies the information of the display list.
See <r_vowe_DisplayList_t>.
Return value:
R_VOWE_ERR_OK - No error has occurred.
R_VOWE_ERR_PARAM_INCORRECT - A parameter provided to a function is incorrect.
R_VOWE_ERR_RANGE_UNIT - The unit-number error.
R_VOWE_ERR_NOT_ACCEPTABLE - A function was called in an incorrect state.
R_VOWE_ERR_FATAL_OS - Fatal error has occurred at OS interface.
See <r_vowe_Error_t>.
*/
r_vowe_Error_t R_VOWE_DLChange(const uint32_t Unit,
const r_vowe_DisplayList_t * const DisplayList );
/***************************************************************************
Function: R_VOWE_VersionStringGet
Description:
This fucntion returns the version string of this VOWE driver.
Return value:
the version string of this VOWE driver
*/
const uint8_t *R_VOWE_VersionStringGet(void);
/***************************************************************************
Function: R_VOWE_MacroVersionGet
Description:
This function returns the major and minor version of the H/W macro.
Parameter:
Major - This is a pointer to major version.
Minor - This is a pointer to minor version.
Return value:
R_VOWE_ERR_OK - No error has occurred.
R_VOWE_ERR_PARAM_INCORRECT - A parameter provided to a function is incorrect.
R_VOWE_ERR_RANGE_UNIT - The unit-number error.
See <r_vowe_Error_t>.
*/
r_vowe_Error_t R_VOWE_MacroVersionGet(uint32_t *const Major,
uint32_t *const Minor);
/****************************************************************************
Function: R_VOWE_Isr0
Description:
This function is called from ISR (Interrupt Service Routines) and processes
the interrupt factor.
It depends on the CPU which is loaded into the device for ISR.
Parameter:
Unit - The parameter specifies the instance number.
Return value:
None.
*/
void R_VOWE_Isr0(uint32_t Unit);
#ifdef __cplusplus
}
#endif
#endif /* R_VOWE_API_H_ */