/*
 * Copyright (c) CompanyNameMagicTag 2018-2019. All rights reserved.
 * Description: Diagnosis (DIAG) Interaction APIs.
 * Author: CompanyName
 * Create: 2018-10-31
 */
/**
 * @defgroup hct_cpup CPU usage
 * @ingroup  mid
 */

#ifndef __SOC_MDM_DIAG_H__
#define __SOC_MDM_DIAG_H__

#include <soc_mdm_uart.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @ingroup  hct_diag
 * @brief Registers the callback function for DIAG channel status changes.
 *
 * @par Description:
 * Registers the callback function for DIAG channel status changes. That is, when the DIAG channel is
 * connected or disconnected, the function registered by this API is called back.
 *
 * @attention None
 * @param  port_num [IN] Type #td_u16 Port number.
 * @param  connect  [IN] Type #td_bool Connection status.
 *
 * @retval #0               Success.
 * @retval #Other values    Failure. For details, see soc_errno.h.
 * @par Dependency:
 * @li soc_mdm_diag.h: Describes DIAG APIs.
 * @see  None
 * @since DW21_V100R001C00
 */
typedef td_u32 (*ext_diag_connect_f)(td_u16 port_num, td_bool connect);

/**
 * @ingroup  hct_diag
 * @brief Registers the callback function for DIAG channel status changes.
 *
 * @par Description:
 * Registers the callback function for DIAG channel status changes. That is, when the DIAG channel is
 * connected or disconnected, the function registered by this API is called back.
 *
 * @attention None
 * @param  connect_notify [IN] Type #ext_diag_connect_f User function.
 *
 * @retval #0               Success.
 * @retval #Other values    Failure. For details, see soc_errno.h.
 * @par Dependency:
 * @li soc_mdm_diag.h: Describes DIAG APIs.
 * @see  None
 * @since DW21_V100R001C00
 */
td_u32 uapi_diag_register_connect_notify(ext_diag_connect_f connect_notify);

/**
 * @ingroup  hct_diag
 * @brief Checks the connection status of the DIAG channel.
 *
 * @par Description:
 * Checks the connection status of the DIAG channel.
 *
 * @attention None
 * @param  None
 *
 * @retval #TD_FALSE disconnected.
 * @retval #TD_TRUE  connected.
 * @par Dependency:
 * @li soc_mdm_diag.h: Describes DIAG APIs.
 * @see  None
 * @since DW21_V100R001C00
 */
td_bool uapi_diag_is_connect(td_void);

/**
 * @ingroup  hct_diag
 * @brief Callback function for handling diagnosis commands.
 *
 * @par Description:
 *           Callback function for handling diagnosis commands, that is, the function body for executing commands.
 *
 * @attention
 *           @li If the returned value is not EXT_ERR_CONSUMED, the DIAG framework automatically forwards
 *               the returned value to the host.
 *           @li If the return value is EXT_ERR_CONSUMED, it indicates that the user sends a response (local connection)
 *               to the host through the uapi_diag_send_ack_packet API. The DIAG framework does not automatically

 *               respond to the host.
 *           @li The return value of the API cannot be EXT_ERR_NOT_FOUND.
 * @param  cmd_id         [IN] Type #td_u16 Command ID
 * @param  cmd_param      [IN] Type #td_pvoid Pointer to the user input command.
 * @param  cmd_param_size [IN] Type #td_u16 Length of the command input by the user (unit: byte).
 * @param  option         [IN] Type #td_u8#EXT_DIAG_CMD_INSTANCE_LOCAL and #EXT_DIAG_CMD_INSTANCE_IREMOTE are supported.
 *
 * @retval #0               Success.
 * @retval #Other values    Failure. For details, see soc_errno.h.
 * @par Dependency:
 *           @li soc_mdm_diag.h: Describes DIAG APIs.
 * @see  None
 * @since DW21_V100R001C00
 */
typedef td_u32 (*ext_diag_cmd_f)(td_u16 cmd_id, td_pvoid cmd_param, td_u16 cmd_param_size, td_u8 option);

/**
 * @ingroup  hct_diag
 * Command registration structure. The same callback function can be used within the command ID range.
 *
 * If a single command is used, the maximum and minimum IDs are the same.
 */
typedef struct {
    td_u16 min_id;              /* Minimum DIAG ID */
    td_u16 max_id;              /* Maximum DIAG ID */
    ext_diag_cmd_f fn_input_cmd; /* This Handler is used to process the DBK command. */
} ext_diag_cmd_reg_obj;

/**
 * @ingroup  hct_diag
 * @brief  Registers the command handling function.
 *
 * @par Description:
 * The DIAG subsystem supports a maximum of 20 different command tables. You can run
 * uapi_diag_get_cmd_stat_reg_info to query the number of registered command tables.
 *
 * @attention The range of command IDs that can be used by the SDK user is [0xFD00, 0xFFFF).
 * @param  cmd_tbl  [IN] Type #ext_diag_cmd_reg_obj* Command table, which must be declared as a constant array
 * and transmitted to this parameter.
 * @param  cmd_num  [IN] Type #td_u16 Number of commands. The value cannot be 0.
 *
 * @retval #0               Success.
 * @retval #Other values    Failure. For details, see soc_errno.h.
 * @par Dependency:
 * @li soc_mdm_diag.h: Describes DIAG APIs.
 * @see  None
 * @since DW21_V100R001C00
 */
td_u32 uapi_diag_register_cmd(EXT_CONST ext_diag_cmd_reg_obj *cmd_tbl, td_u16 cmd_num);

/**
 * @ingroup hct_diag
 * Statistic description structure.
 */
typedef struct {
    td_u16 id;               /**< Statistics ID. */
    td_u16 array_cnt;        /**< Number of statistic structures. */
    td_u32 stat_packet_size; /**< Size of a single statistic structure (unit: byte). */
    td_pvoid stat_packet;    /**< Pointer to the statistic structure. */
} ext_diag_sys_stat_obj;

/**
 * @ingroup  hct_diag
 * @brief  Registers the system diagnosis statistic.
 *
 * @par Description:
 * The DIAG subsystem can register a maximum of 20 statistic tables. You can run
 * uapi_diag_get_cmd_stat_reg_info to query the number of registered statistic tables.
 *
 * @attention The range of statistic IDs that can be used by the SDK user is [0xEE00, 0xF000).
 * @param  stat_obj_tbl     [IN] Type #ext_diag_sys_stat_obj_s* Table of statistics objects.
 * @param  obj_num          [IN] Type #td_u16 Number of statistics objects. The value cannot be 0.
 *
 * @retval #0               Success.
 * @retval #Other values    Failure. For details, see soc_errno.h.
 * @par Dependency:
 * @li soc_mdm_diag.h: Describes DIAG APIs.
 * @see  None
 * @since DW21_V100R001C00
 */
td_u32 uapi_diag_register_stat_obj(EXT_CONST ext_diag_sys_stat_obj *stat_obj_tbl, td_u16 obj_num);

/**
 * @ingroup  hct_diag
 * Local instance  -->DBK  Interaction command between the host software and the local station.
 */
#define EXT_DIAG_CMD_INSTANCE_DEFAULT ((td_u8)0)

/**
 * @ingroup  hct_diag
 * Local instance  -->DBK  Interaction command between the host software and the local station.
 */
#define EXT_DIAG_CMD_INSTANCE_LOCAL EXT_DIAG_CMD_INSTANCE_DEFAULT

/**
 * @ingroup  hct_diag
 * Command received from a remote station or sent from the local station to a remote station.
 */
#define EXT_DIAG_CMD_INSTANCE_IREMOTE 1

/**
 * @ingroup  hct_diag
 * Command that the host software sends to a remote station or the command received from a remote station and
 * reported to the host. (invisible in the DW21 secondary development)
 */
#define EXT_DIAG_CMD_INSTANCE_DREMOTE 2
#define EXT_DIAG_CMD_INSTANCE_DREMOTE_NDM 3 /* Not supported */
#define EXT_DIAG_CMD_INSTANCE_UNKNOWN 0xFF  /* Invalid parameter, used for exception determination. */

/**
 * @ingroup  hct_diag
 * @brief  Reports DIAG packets.
 *
 * @par Description:
 * Reports DIAG channel packets to the DIAG client.
 *
 * @attention None
 * @param  cmd_id       [IN] Type #td_u16 DIAG data packet ID. For example, if the packet ID is the same as the command
 * request ID, use the cmd_id parameter in the command callback function ext_diag_cmd_f.
 * @param  instance_id  [IN] Type #td_u8 Command type. Valid values are as follows: EXT_DIAG_CMD_INSTANCE_LOCAL and
 * EXT_DIAG_CMD_INSTANCE_IREMOTE. Use the option parameter in the command callback function
 * ext_diag_cmd_f to notify the DIAG subsystem whether the packet is a local packet or a
 * remote packet.
 * @param  packet     [IN] Type #td_pbyte Buffer address of the data packet. This function does not release the pointer.
 * @param  pakcet_size  [IN] Type #td_u16 Data packet size (unit: byte)
 * @param  sync         [IN] Type #td_bool Synchronous or asynchronous DIAG packet pushing. TRUE indicates that the
 * packets are pushed synchronously and the operation is blocked. FALSE indicates the packets
 * are pushed asynchronously (with the memory allocated, the packet is cashed by the OS queue
 * before being pushed), and the operation is not blocked.
 *
 * @retval #0               Success.
 * @retval #Other values    Failure. For details, see soc_errno.h.
 * @par Dependency:
 * @li soc_mdm_diag.h: Describes DIAG APIs.
 * @see  None
 * @since DW21_V100R001C00
 */
td_u32 uapi_diag_report_packet(td_u16 cmd_id, td_u8 instance_id, const td_pbyte packet, td_u16 pakcet_size,
    td_bool sync);

/**
 * @ingroup  hct_diag
 * @brief  Sends ACK packets to the DIAG client.
 *
 * @par Description:
 * Sends ACK packets to the DIAG client.
 *
 * @attention This API can be used only for the response to local commands, not remote commands.
 * @param  cmd_id      [IN] Type #td_u16 DIAG ACK packet ID. For example, if the packet ID is the same as the command
 * request ID, use the cmd_id parameter in the command callback function ext_diag_cmd_f.
 * @param  instance_id [IN] Type #td_u8 Command type. The value is fixed to EXT_DIAG_CMD_INSTANCE_LOCAL.
 * @param  buffer     [IN] Type #td_pvoid Buffer address of the data packet. This function does not release the pointer.
 * @param  buffer_size [IN] Type #td_u16 Buffer size (unit: byte). The maximum value is 1024.
 *
 * @retval #0               Success.
 * @retval #Other values    Failure. For details, see soc_errno.h.
 * @par Dependency:
 * @li soc_mdm_diag.h: Describes DIAG APIs.
 * @see  None
 * @since DW21_V100R001C00
 */
td_u32 uapi_diag_send_ack_packet(td_u16 cmd_id, td_u8 instance_id, EXT_IN td_pvoid buffer, td_u16 buffer_size);

#define EXT_DIAG_LOG_OPT_LOCAL_REQ 1         /**< Local command request from the host to DIAG. */
#define EXT_DIAG_LOG_OPT_LOCAL_IND 2         /**< local response from DIAG to the host. */
#define EXT_DIAG_LOG_OPT_LOCAL_ACK 3         /**< Local ACK from DIAG to the host. */
/**< Remote command request from the local station to a remote station. */
#define EXT_DIAG_LOG_OPT_REMOTE_REQ_TO_PLC 4
/**< Received remote command request from a remote station to the local * station. */
#define EXT_DIAG_LOG_OPT_REMOTE_REQ_FROM_PLC 5
/**< Remote command response from the local station to a remote station */
#define EXT_DIAG_LOG_OPT_REMOTE_RSP_TO_PLC 6
/**< Received remote command response from a remote station to the local * station. */
#define EXT_DIAG_LOG_OPT_REMOTE_RSP_FROM_PLC 7

/**
 * @ingroup  hct_diag
 * Describes the command type transferred to the app layer.
 */
typedef struct {
    td_u32 opt; /**< Option configuration, which is used to set the command as a local command or a remote
                 * command. The value is a EXT_DIAG_LOG_OPT_XXX macro such as #EXT_DIAG_LOG_OPT_LOCAL_REQ.
                 */
    td_u8 plc_mac[EXT_PLC_MAC_ADDR_LEN]; /**< MAC address of the target board of
                                         * the remote command. This parameter is not
                                         * involved in a local command.
                                         */
    td_u8 pad[2];                       /**< Reserved, not supported currently.pad 2 */
} ext_diag_log_ctrl;

/**
 * @ingroup  hct_diag
 * @brief  Callback function for notifying DIAG operations
 *
 * @par Description:
 * Carbon copies data to the app layer by using a callback function in the case of data interaction between
 * the host and the board.
 *
 * @attention It is not allowed to call an API for sending data in the DIAG subsystem in this callback function.
 * @param  cmd_id       [IN] Type #td_u16 Command ID.
 * @param  buffer       [IN] Type #td_pvoid Data pointer transferred to the app layer.
 * @param  buffer_size  [IN] Type #td_u16 Length of the data transferred to the app layer (unit: byte)
 * @param  log_ctrl     [IN] Type #ext_diag_log_ctrl* Command type sent to the app layer
 *
 * @retval None
 * @par Dependency:
 * @li soc_mdm_diag.h: Describes DIAG APIs.
 * @see  None
 * @since DW21_V100R001C00
 */
typedef td_void (*ext_diag_cmd_notify_f)(td_u16 cmd_id,
    td_pvoid buffer, td_u16 buffer_size, ext_diag_log_ctrl *log_ctrl);

/**
 * @ingroup  hct_diag
 * @brief  Registers the callback function for notifying DIAG operations.
 *
 * @par Description:
 * Carbon copies data to the app layer by using a callback function in the case of data interaction between
 * the host and the board.
 *
 * @attention If func is null, the registration is canceled and the registered notification callback is invalid.
 * @param  func  [IN] Type #ext_diag_cmd_notify_f* When data interaction occurs between the DBK and the board, this API
 * is used to notify the app layer.
 *
 * @retval #0               Success.
 * @retval #Other values    Failure. For details, see soc_errno.h.
 * @par Dependency:
 * @li soc_mdm_diag.h: Describes DIAG APIs.
 * @see  None
 * @since DW21_V100R001C00
 */
td_u32 uapi_diag_register_cmd_notify(ext_diag_cmd_notify_f func);

/**
 * @ingroup  hct_diag
 * @brief  Sets the UART parameters of the DIAG channel.
 *
 * @par Description:
 * Sets the UART parameters of the used by the DIAG subsystem before the DIAG subsystem is initialized.
 *
 * @attention The parameters must be set before the initialization of the DIAG subsystem.
 * @param  uart_port [IN] Type #ext_uart_port UART port number used by the DIAG subsystem.
 * @param  uart_cfg  [IN] Type #ext_uart_init_type UART configuration used by the DIAG subsystem.
 *
 * @retval #0               Success.
 * @retval #Other values    Failure. For details, see soc_errno.h.
 * @par Dependency:
 * @li soc_mdm_diag.h: Describes DIAG APIs.
 * @see  None
 * @since DW21_V100R001C00
 */
td_u32 uapi_diag_set_uart_param(ext_uart_port uart_port, ext_uart_init_type uart_cfg);

/**
 * @ingroup  hct_diag
 * @brief  Initializes the DIAG subsystem.
 *
 * @par Description:
 * Initializes the DIAG subsystem.
 *
 * @attention The initialization of the DIAG subsystem needs to be performed only once. Repeated initialization
 * is invalid.
 * @param  None
 *
 * @retval #0               Success.
 * @retval #Other values    Failure. For details, see soc_errno.h.
 * @par Dependency:
 * @li soc_mdm_diag.h: Describes DIAG APIs.
 * @see  None
 * @since DW21_V100R001C00
 */
td_u32 uapi_diag_init(td_void);

/**
 * @ingroup  hct_diag
 * Structure for querying the number of command tables and statistic object tables.
 */
typedef struct {
    td_u8 cmd_list_total_cnt;  /**< Number of command registration tables can be registered. */
    td_u8 cmd_list_used_cnt;   /**< Number of registered command tables. */
    td_u8 stat_list_total_cnt; /**< Number of statistic object tables can be registered. */
    td_u8 stat_list_used_cnt;  /**< Number of registered statistic object tables. */
} ext_diag_cmd_stat_reg_info;

/**
 * @ingroup  hct_diag
 * @brief  Queries the registration status of the command tables and statistic tables of the DIAG subsystem.
 *
 * @par Description:
 * Queries the registration status of the command tables and statistic tables of the DIAG subsystem.
 * Number of registered command tables and number of command tables can be registered/ Number of registered
 * statistic object tables
 *
 * @attention None
 * @param     None
 *
 * @retval #ext_diag_cmd_stat_reg_info Structure of the number of registered command tables and statistic tables.
 * @par Dependency:
 * @li soc_mdm_diag.h: Describes DIAG APIs.
 * @see  None
 * @since DW21_V100R001C00
 */
ext_diag_cmd_stat_reg_info uapi_diag_get_cmd_stat_reg_info(td_void);

#ifdef __cplusplus
}
#endif
#endif /* __SOC_MDM_DIAG_H__ */