/*
 * loader.h
 *
 *  Created on: 14 Sep 2023
 */

#ifndef INCLUDE_EFC_USB_LOADER_H_
#define INCLUDE_EFC_USB_LOADER_H_

#include <efc_usb/status.h>

/** @brief Пакет командного интерфейса */
struct /** @cond */ __attribute__((__packed__)) /** @endcond */
efc_usb_ld_cmd_packet {
    union {
        struct {
            /** Размер данных в поле @c data */
            uint16_t size       : 16;
        } bits;
        uint32_t all;
    } header; /**< Заголовок пакета */

    /** Поле данных пакета (аргументы для Rx пакета или результаты для Tx пакета) */
    uint8_t* data;
};

/**
 * @brief Метод чтения FIFO последнего входящего командного пакета
 *
 * Метод производит прямое чтение принятых данных из аппаратного FIFO буфера USB модуля.
 *
 * @param buffer Буфер, в который будут записаны данные входящего пакета
 * @param buffer_max_size Размер буфера
 * @param received_data_size Вернет количество полученных байт
 * @param data_size_avail Количество байт, которое остались непрочитанным в пакете
 *
 * @return @c true при успешном чтении; @c false при следующих случаях: @n
 *   - @c NULL аргумент;
 *   - Данные в буфере невалидны (принят или принимается новый пакет);
 *   - Драйвер не инциализирован или находится не в рабочем состоянии.
 *
 * @warning Операция чтения очищает FIFO буфер, повторное чтение тех же данных не возможно.
 */
efc_usb_status_t efc_usb_ld_data_recv(uint8_t* buffer, size_t buffer_max_size, size_t* received_data_size, size_t* data_size_avail);

/**
 * @brief Метод записи командного пакета в FIFO буфер передатчика
 *
 * Метод позволяет поставить запрос на отправку командного пакета.
 * При очередном IN запросе от хоста данные будут отправлены и будет возможно
 * оставить новый запрос на отправку.
 *
 * @param tx_packet Буфер, в котором находятся данные исходящего пакета
 *
 * @return @c true при успешном выполнении; @c false при следующих случаях: @n
 *   - @c NULL аргумент;
 *   - Буфер драйвера еще занят;
 *   - Драйвер не инциализирован или находится не в рабочем состоянии.
 */
efc_usb_status_t efc_usb_ld_data_send(const uint8_t* header, size_t header_size, const uint8_t* data, size_t data_size);

/**
 * @brief Обработчик сброса, инициированного хостом
 *
 * Вызывается после выполнения процедуры сброса состояния конфигурации дарайвера. @n
 *  - Буферы приёмника/передатчика считаются невалидными
 *  - Драйвер переводится в рабочее состояние
 *  - Обработка командного интерфейса включёна
 *
 *  @param param Пользовательский параметр, передаваемый при вызове со стороны драйвера
 *
 *  @return void
 *
  * @note Вызов производится из контекста обработчика прерывания
 */
typedef void (*efc_usb_ld_reset_handle_t) (void* param);

/**
 * @brief Обработчик входящих командных пакетов
 *
 * Вызывается @b после получения и буферизации в FIFO @n
 *
 * В рамках обратного вызова пользователю необходимо считать буфер, используя функцию @ref efc_usb_sv_cmd_read,
 * иначе данные могут быть перезаписаны асинхронно следующим входящим пакетом.
 *
 * @param param Пользовательский параметр, передаваемый при вызове со стороны драйвера
 *
 * @return void
 *
 * @note Вызов производится из контекста обработчика прерывания
 */
typedef void (*efc_usb_ld_cmd_rx_handle_t) (void* param);

/**
 * @brief Обработчик исходящих командных пакетов
 *
 * Вызывается @b до буферизации в FIFO и отправки пакета @n
 *
 * По готовности данные могут быть записаны в буфер передатчика @ref efc_usb_sv_cmd_write.
 *
 * @param param Пользовательский параметр, передаваемый при вызове со стороны драйвера
 *
 * @return void
 *
 * @note Вызов производится из контекста обработчика прерывания
 */
typedef void (*efc_usb_ld_cmd_tx_handle_t) (void* param);

/** @brief Параметры командного интерфейса */
struct efc_usb_ld_cmd_config {
    /** Обратный вызов приёмника командных пакетов */
    efc_usb_ld_cmd_rx_handle_t rx_handle;
    /** Параметр приёмника командных пакетов */
    void* rx_handle_param;
    /** Обратный вызов передатчика командных пакетов */
    efc_usb_ld_cmd_tx_handle_t tx_handle;
    /** Параметр передатчика командных пакетов */
    void* tx_handle_param;
};

/** @brief Параметры конфигурации usb загрузчика */
struct efc_usb_ld_config {
    /** Параметры командного интерфейса */
    struct efc_usb_ld_cmd_config cmd;

    /** Обратный вызов события сброса */
    efc_usb_ld_reset_handle_t reset_handle;
    /** Параметр обратного вызова события сброса */
    void* reset_handle_param;
};

#endif /* INCLUDE_EFC_USB_LOADER_H_ */