payton/nt9856x
Template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
57420f5c15
nt9856x/code/lib/include/FwSrvApi.h
payton 543d2da268 1.一次S530代码提交
2023-03-28 15:07:53 +08:00

399 lines
15 KiB
C
Raw Blame History

/**
Firmware Read/Write Service
@file FwSrvApi.h
@ingroup mFWSRV
Copyright Novatek Microelectronics Corp. 2012. All rights reserved.
*/
#ifndef _FWSRVAPI_H
#define _FWSRVAPI_H
#include <kwrap/task.h>
#include <kwrap/type.h>
#include <PartLoad.h>
/**
@addtogroup mFWSRV
*/
//@{
#define FWSRV_API_VERSION 0x19062017U ///< API version
#define FWSRV_PL_BURST_END_TAG 0xFFFFFFFFU ///< indicate end number for FWSRV_PL_LOAD_BURST_IN::puiIdxSequence
/**
Error Code.
Any error code occured will display on uart or return.
*/
typedef enum _FWSRV_ER {
FWSRV_ER_OK = 0, ///< no error
FWSRV_ER_NOT_INIT = -1, ///< FwSrv_Init() is not called or not success
FWSRV_ER_SYS = -2, ///< unknown system error
FWSRV_ER_LOCK = -3, ///< failed to lock API
FWSRV_ER_UNLOCK = -4, ///< failed to unlock API
FWSRV_ER_PARAM = -5, ///< wrong Parameters
FWSRV_ER_API_VERSION = -6, ///< wrong API version
FWSRV_ER_STA_TASK = -7, ///< failed to call sta_tsk
FWSRV_ER_WAIT_IDLE = -8, ///< failed to call wai_flg for idle
FWSRV_ER_SET_IDLE = -9, ///< failed to call set_flg to idle
FWSRV_ER_NOT_IN_IDLE = -10, ///< if Prop.bEnterOnlyIdle is true, but system is not idle
FWSRV_ER_STATE = -11, ///< service state machine is not correctly.
FWSRV_ER_INVALID_CALL = -12, ///< invald to call this API
FWSRV_ER_OUT_DATA_VOLATILE = -13, ///< the parameter FWSRV_CMD.out maybe volatile. (suggest to bExitCmdFinish=TRUE)
FWSRV_ER_CMD_MAXDATA = -14, ///< internal error. all cmd data structure have to declare in FWSRV_CMD_MAXDATA
FWSRV_ER_INVALID_CMD_IDX = -15, ///< invalid command index
FWSRV_ER_CMD_MAP_NULL = -16, ///< internal error. cmd function map to a null pointer
FWSRV_ER_CMD_NOT_MATCH = -17, ///< internal error. g_FwSrvCallTbl is not match to FWSRV_CMD_IDX
FWSRV_ER_CMD_IN_DATA = -18, ///< wrong FWSRV_CMD.In Data
FWSRV_ER_CMD_OUT_DATA = -19, ///< wrong FWSRV_CMD.Out Data
FWSRV_ER_PL_VERSION = -20, ///< partial load lib invalid
FWSRV_ER_PL_INIT = -21, ///< init partial load fail
FWSRV_ER_PL_LOAD = -22, ///< partial load fail
FWSRV_ER_SIZE_NOT_BLK_ALIGN = -23, ///< input size have to block alignment
FWSRV_ER_SIZE_NOT_ENOUGH = -24, ///< input buffer size is too small
FWSRV_ER_SIZE_OUT_OF_RANGE = -25, ///< input data size is out of range
FWSRV_ER_AREA_OUT_OF_RANGE = -26, ///< input data area is out of range
FWSRV_ER_ADDR_NOT_WORD_ALIGN = -27, ///< input address have to word alignment
FWSRV_ER_DEPACK_WRONG_CONTEXT = -28, ///< wrong context of input file at depack command
FWSRV_ER_DX = -29, ///< access Dx object is failed.
FWSRV_ER_ECOS_CONTEXT = -30, ///< invalid ecos context
FWSRV_ER_ECOS_BUF_TOO_SMALL = -31, ///< buffer is too small to read eCos firmware
FWSRV_ER_LINUX = -32, ///< read linux fail
FWSRV_ER_DSP = -33, ///< invalid dsp context
FWSRV_ER_CONTEXT = -34, ///< invalid buffer context
FWSRV_ER_INVALID_UPDATED_DATA = -35, ///< after fw updated, fwsrv reload and check fail
FWSRV_ER_WRITE_BLOCK = -36, ///< write block fail during fw updating
ENUM_DUMMY4WORD(FWSRV_ER)
} FWSRV_ER;
/**
Warning Code.
The warning codes is only displayed via uart.
*/
typedef enum _FWSRV_WR {
FWSRV_WR_OK = 0, ///< no warning
FWSRV_WR_INIT_TWICE = -1, ///< FwSrv_Init() is called twice
FWSRV_WR_ALREADY_CLOSED = -2, ///< service is already closed.
FWSRV_WR_SUSPEND_TWICE = -3, ///< FwSrv_Suspend maybe is called twice
FWSRV_WR_NOT_IN_SUSPEND = -4, ///< call FwSrv_Resume, but service isn't in suspend state before.
FWSRV_WR_CMD_SKIP = -5, ///< existing a command is skipped
ENUM_DUMMY4WORD(FWSRV_WR)
} FWSRV_WR;
/**
State Machine.
Indicate the task state.
*/
typedef enum _FWSRV_STATE {
FWSRV_STATE_UNKNOWN = 0, ///< unknown. only existing service is not opened.
FWSRV_STATE_OPEN_BEGIN, ///< start to open a task
FWSRV_STATE_OPEN_END, ///< finished to do open flow
FWSRV_STATE_CLOSE_BEGIN, ///< start to close
FWSRV_STATE_CLOSE_END, ///< task is terminated.
FWSRV_STATE_SUSPEND_BEGIN, ///< start to enter suspend state
FWSRV_STATE_SUSPEND_END, ///< task is in suspend state
FWSRV_STATE_RESUME_BEGIN, ///< start to resume service
FWSRV_STATE_RESUME_END, ///< finished to resume, task start to recevice command
FWSRV_STATE_CMD_BEGIN, ///< start to do a command
FWSRV_STATE_CMD_END, ///< command finished
FWSRV_STATE_CMD_CB_BEGIN, ///< start to call a callback when command finished
FWSRV_STATE_CMD_CB_END, ///< exit to callback when command finished
FWSRV_STATE_STATUS_CB_BEGIN, ///< start to call a callback when status change
FWSRV_STATE_STATUS_CB_END, ///< exit to callback when status change
FWSRV_STATE_ER_CB_BEGIN, ///< start to call a callback when error occured
FWSRV_STATE_ER_CB_END, ///< exit to callback when error occured
FWSRV_STATE_MAX_NUM, ///< total state numbers
ENUM_DUMMY4WORD(FWSRV_STATE)
} FWSRV_STATE;
/**
Command Index.
The command of FwSrv service support. Set this index to the FWSRV_CMD
and call the FwSrv_Cmd to do command when service is opened.
*/
typedef enum _FWSRV_CMD_IDX {
FWSRV_CMD_IDX_UNKNOWN = 0, ///< unknown command. maybe forget to set FWSRV_CMD.Idx1
FWSRV_CMD_IDX_PL_LOAD_BURST, ///< Input:FWSRV_PL_LOAD_BURST_IN
FWSRV_CMD_IDX_BIN_UPDATE_ALL_IN_ONE, ///< Input:FWSRV_BIN_UPDATE_ALL_IN_ONE, update all-in-one bin
FWSRV_CMD_IDX_FASTLOAD, ///< Input: FWSRV_FASTLOAD, Output: MEM_RANGE (real decoded data size)
FWSRV_CMD_IDX_MAX_NUM, ///< total command numbers
ENUM_DUMMY4WORD(FWSRV_CMD_IDX)
} FWSRV_CMD_IDX;
/**
DX_TYPE_EMBMEM? map to partition name
*/
typedef struct _FWSRV_STRG_MAP {
STORAGE_OBJ *pStrgFdt;
STORAGE_OBJ *pStrgApp;
STORAGE_OBJ *pStrgUboot;
STORAGE_OBJ *pStrgRtos;
STORAGE_OBJ *pStrgKernel;
STORAGE_OBJ *pStrgRootfs;
STORAGE_OBJ *pStrgRootfs1;
STORAGE_OBJ *pStrgAppfs;
} FWSRV_STRG_MAP, *PFWSRV_STRG_MAP;
typedef void (*FWSRV_FP_STATE_CB)(FWSRV_STATE State); ///< State callback. If there's any state changed, the service will callback out.
typedef void (*FWSRV_FP_ERROR_CB)(FWSRV_ER er); ///< Error callback. If there's any error occured, the service will callback out.
/**
Initial Data.
For system inital via FwSrv_Init().
*/
typedef struct _FWSRV_INIT {
UINT32 uiApiVer; ///< just assign to FWSRV_API_VERSION
VK_TASK_HANDLE TaskID; ///< given a task id form project layer creation (can set 0 to use system default)
ID SemID; ///< given a semaphore id form project layer creation (can set 0 to use system default)
ID FlagID; ///< given a flag id form project layer creation (can set 0 to use system default)
FWSRV_STRG_MAP StrgMap; ///< map to partitions
PARTLOAD_INIT PlInit; ///< partial load init data. if you don't use partial load, uiWorkingSize can set it to 0
FWSRV_FP_STATE_CB fpStateCb; ///< (Option) system will call the callback when state change
FWSRV_FP_ERROR_CB fpErrorCb; ///< (Option) if there is error occured, callback will be performed for debug
} FWSRV_INIT, *PFWSRV_INIT;
/**
Finish information.
When FWSRV_PROP.fpFinishCb assign a callback, the data will send to this
callback after command finish.
*/
typedef struct _FWSRV_FINISH {
FWSRV_CMD_IDX Idx; ///< Finished command index
FWSRV_ER er; ///< command finish result.
VOID *pUserData; ///< If FWSRV_PROP.pUserData is assigned a userdata pointer. service will take it to FWSRV_PROP.fpFinishCb
} FWSRV_FINISH, *PFWSRV_FINISH;
typedef void (*FWSRV_CB_FINISH)(const FWSRV_FINISH *pInfo); ///< Command finish callback. When any command is finished, the service will callback out.
/**
Command Property.
Indicate how to run the current command.
*/
typedef struct _FWSRV_PROP {
BOOL bEnterOnlyIdle; ///< do job only system idle. if system is busy, the FWSRV_ER_NOT_IN_IDLE returned.
BOOL bExitCmdFinish; ///< exit API when job finished.
FWSRV_CB_FINISH fpFinishCb; ///< (Option) system will call the callback when job is finished
VOID *pUserData; ///< (Option) when CbFinish is called, assigned userdata can get from CbFinish parameter.
} FWSRV_PROP, *PFWSRV_PROP;
/**
Command Input/Output Data.
Including data pointer and data size depend on FWSRV_CMD_IDX.
*/
typedef struct _FWSRV_DATA {
VOID *pData; ///< input/output data pointer
UINT32 uiNumByte; ///< input/output data size
} FWSRV_DATA, *PFWSRV_DATA;
/**
Command Description.
The necessary information for running a command via FwSrv_Cmd().
*/
typedef struct _FWSRV_CMD {
FWSRV_CMD_IDX Idx; ///< index
FWSRV_PROP Prop; ///< property
FWSRV_DATA In; ///< input data description (depend on Idx)
FWSRV_DATA Out; ///< output data description (depend on Idx)
} FWSRV_CMD, *PFWSRV_CMD;
/**
Partial load finish callback
For the command FWSRV_CMD_IDX_PL_LOAD_BURST , the module will callback when
any part load finish.
*/
typedef void (*FWSRV_CB_PL_LOAD_FINISH)(const UINT32 Idx);
/**
Burst Description
For the command FWSRV_CMD_IDX_PL_LOAD_BURST. Partial load will load activity.
*/
typedef struct _FWSRV_PL_LOAD_BURST_IN {
UINT32 *puiIdxSequence; ///< An UINT32 array to save load sequence (have to be the global array address) have to use FWSRV_PL_BURST_END_TAG at last
FWSRV_CB_PL_LOAD_FINISH fpLoadedCb; ///< load a part finish callback.
} FWSRV_PL_LOAD_BURST_IN, *PFWSRV_PL_LOAD_BURST_IN;
/**
FWSRV_CMD_IDX_BIN_UPDATE_ALL_IN_ONE Notify Check Sum is OK
For the command FWSRV_CMD_IDX_BIN_UPDATE_ALL_IN_ONE , if internal previous checksum is vaild, we notify it.
*/
typedef void (*FWSRV_CB_CHECK_SUM_OK)(void);
/**
Updating All-In-One Bin structure
For de-packing and updating the all-in-one bin file, for PStore partition data, it callbacks out to users updating themselves.
*/
typedef struct _FWSRV_BIN_UPDATE_ALL_IN_ONE {
UINT32 uiSrcBufAddr; ///< all-in-one bin context
UINT32 uiSrcBufSize; ///< all-in-one bin size
FWSRV_CB_CHECK_SUM_OK fpCheckSumCb; ///< (Optional) check sum result notification
} FWSRV_BIN_UPDATE_ALL_IN_ONE, *PFWSRV_BIN_UPDATE_ALL_IN_ONE;
typedef struct _FWSRV_FASTLOAD {
STORAGE_OBJ *pStrg;
MEM_RANGE MemComp; ///< temp buffer to store gz-compressed linux
MEM_RANGE MemUnComp; ///< target buffer to decompress linux-kernel
} FWSRV_FASTLOAD;
/**
Initialize FwSrv service.
For using the FwSrv service, the task id, flag id, semphore id have to
prepare by project layer. Assign these ids to the FWSRV_INIT strcuture
when system starup (just set once).
@param[in] pInit necessary inital data.
@return
- @b FWSRV_ER_OK: inital success.
- @b FWSRV_ER_API_VERSION: FwSrvApi.h and AppFwSrv.a not match.
*/
extern FWSRV_ER FwSrv_Init(const FWSRV_INIT *pInit);
/**
Start to open the FwSrv service.
After FwSrv service is initialized, call FwSrv_Open to start the
service.
@return
- @b FWSRV_ER_OK: open success.
- @b FWSRV_ER_STATE: may FwSrv_Init does not be called yet.
- @b FWSRV_ER_STA_TASK: failed to start task(sta_tsk failed).
*/
extern FWSRV_ER FwSrv_Open(VOID);
/**
Stop to open the FwSrv service.
When FwSrv service is running, call FwSrv_Close to terminate the task
service.
@note: Don't call FwSrv_Close in any FwSrv service callback. In
callback, the FwSrv_AsyncClose is allowed to call to stop recevice receive
data but task is not terminated. The FwSrv_Close need to be called outside.
@return
- @b FWSRV_ER_OK: close success.
- @b FWSRV_ER_INVALID_CALL: call FwSrv_Close in callback.
- @b FWSRV_ER_STA_TASK: failed to start task(sta_tsk failed).
*/
extern FWSRV_ER FwSrv_Close(VOID);
/**
Suspend the service task.
When FwSrv service is running, call FwSrv_Suspend to stop recevice
command. Any command will be skiped by service task. The function exit after
task finish his suspend.
@return
- @b FWSRV_ER_OK: suspend success.
- @b FWSRV_ER_STATE: may FwSrv_Open does not be opened yet.
*/
extern FWSRV_ER FwSrv_Suspend(VOID);
/**
Resume the service task.
When FwSrv service is suspended, call FwSrv_Resume to start to
recevice command. The function exit after task finish his resume.
@return
- @b FWSRV_ER_OK: suspend success.
- @b FWSRV_ER_STATE: may FwSrv_Open does not be opened yet.
*/
extern FWSRV_ER FwSrv_Resume(VOID);
/**
Set a command action to FwSrv service.
Configure FWSRV_CMD and send it to the service to do some action via
FwSrv_Cmd.
@param[in] pCmd command description.
@return
- @b FWSRV_ER_OK: send command success.
- @b FWSRV_ER_CMD_NOT_MATCH: internal error. Please contact to module
maintenance staff.
- @b FWSRV_ER_CMD_IN_DATA: the FWSRV_CMD.In maybe assing wrong object
/ structure
- @b FWSRV_ER_CMD_IN_DATA: the FWSRV_CMD.Out maybe assing wrong object
/ structure
- @b FWSRV_ER_STATE: may FwSrv_Open does not be opened yet.
- @b FWSRV_ER_NOT_IN_IDLE: If FWSRV_CMD.FWSRV_PROP.bEnterOnlyIdle set
to TRUE and service is not in idle. Notice you this command is
skipped.
- @b FWSRV_ER_OUT_DATA_VOLATILE: If the command include the output data
and set FWSRV_CMD.FWSRV_PROP.bExitCmdFinish to FALSE, the finish
callback have to plug-in a callback function to FWSRV_CMD
.FWSRV_PROP.fpFinishCb and FWSRV_CMD.Out have to point to a
global data structure.
- @b FWSRV_ER_CMD_MAXDATA: internal error. Please contact to module
maintenance staff.
*/
extern FWSRV_ER FwSrv_Cmd(const FWSRV_CMD *pCmd);
/**
Suspend task service, but exit this function without finish suspend.
This function is for advance. If you don't want to wait FwSrv_Suspend()
finish too long and you want to pipe some flow, you can do the flow that
FwSrv_AsyncSuspend() -> Do Something -> FwSrv_Suspend();
@note: FwSrv_Suspend() is also called necessary to confirm the suspend is
finished.
@return
- @b FWSRV_ER_OK: suspend success.
- @b FWSRV_ER_STATE: may FwSrv_Open does not be opened yet.
*/
extern FWSRV_ER FwSrv_AsyncSuspend(VOID);
/**
Stop task service, but exit this function without finish close.
This function is for advance. If you don't want to wait FwSrv_Close()
finish too long and you want to pipe some flow, you can do the flow that
FwSrv_AsyncClose() -> Do Something -> FwSrv_Close();
@note: FwSrv_AsyncClose() is also called necessary to confirm the suspend is
finished.
@return
- @b FWSRV_ER_OK: suspend success.
- @b FWSRV_ER_STATE: may FwSrv_Open does not be opened yet.
*/
extern FWSRV_ER FwSrv_AsyncClose(VOID);
/**
Dump FwSrv application library information.
The information includes version, build date, last error code, last warning
code, last command, last state and check internal data.
@return
- @b FWSRV_ER_OK: suspend success.
*/
extern FWSRV_ER FwSrv_DumpInfo(VOID);
//@}
#endif
Reference in New Issue View Git Blame Copy Permalink