/**
 * @file app_uart_protocol.h
 * @brief Table-driven incremental UART packet parser and checksum helpers.
 *
 * Architectural note:
 * The parser is intentionally transport-agnostic. It receives one byte at a
 * time from the IRQ adapter, reconstructs packets according to a descriptor
 * table, validates checksums when applicable, and emits fully decoded packet
 * objects for the application core.
 */

#ifndef APP_UART_PROTOCOL_H
#define APP_UART_PROTOCOL_H

#include <stdbool.h>
#include <stdint.h>

#include "app_types.h"

/**
 * @brief Descriptor describing one supported UART packet shape.
 */
typedef struct app_packet_descriptor_t {
    uint16_t header;
    uint8_t total_bytes;
    uint8_t payload_words;
    int8_t checksum_word_index;
    app_packet_kind_t kind;
} app_packet_descriptor_t;

/**
 * @brief Parsed UART packet emitted by the protocol layer.
 */
typedef struct app_packet_t {
    app_packet_kind_t kind;
    uint16_t header;
    uint8_t payload_words;
    bool checksum_valid;
    uint16_t words[APP_PROTOCOL_MAX_PAYLOAD_WORDS];
} app_packet_t;

/**
 * @brief Mutable state of the incremental UART parser.
 */
typedef struct app_uart_protocol_parser_t {
    const app_packet_descriptor_t *descriptor;
    uint16_t partial_header;
    uint8_t bytes_received;
    uint8_t buffer[APP_PROTOCOL_MAX_PACKET_BYTES];
} app_uart_protocol_parser_t;

/**
 * @brief Result returned after feeding one byte into the parser.
 */
typedef enum app_protocol_feed_result_t {
    APP_PROTOCOL_FEED_IN_PROGRESS = 0,
    APP_PROTOCOL_FEED_PACKET_READY,
    APP_PROTOCOL_FEED_INVALID_HEADER
} app_protocol_feed_result_t;

void app_uart_protocol_init(app_uart_protocol_parser_t *parser);
void app_uart_protocol_reset(app_uart_protocol_parser_t *parser);
app_protocol_feed_result_t app_uart_protocol_feed_byte(app_uart_protocol_parser_t *parser,
                                                       uint8_t byte,
                                                       app_packet_t *out_packet);
uint16_t app_protocol_calculate_checksum(const uint16_t *words, uint16_t word_count);

#endif /* APP_UART_PROTOCOL_H */