/**
 * @file tms2812.h
 * @brief Shared PM67/TMS320F2812 legacy terminal and memory protocol.
 */
#ifndef TMS2812_H
#define TMS2812_H

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#define TMS2812_CMD_UPLOAD 52U
#define TMS2812_CMD_PEEK 56U
#define TMS2812_CMD_POKE 57U
#define TMS2812_CMD_TEST_ALL 66U
#define TMS2812_PING_ADDRESS 0x00000100UL
#define TMS2812_UPLOAD_REQUEST_SIZE 12U
#define TMS2812_UPLOAD_RESPONSE_OVERHEAD 8U

typedef enum {
    TMS2812_OK = 0,
    TMS2812_ERROR_ARGUMENT = -1,
    TMS2812_ERROR_RANGE = -2,
    TMS2812_ERROR_LENGTH = -3,
    TMS2812_ERROR_CRC = -4,
    TMS2812_ERROR_HEADER = -5,
    TMS2812_ERROR_CAPACITY = -6
} tms2812_status_t;

uint16_t tms2812_crc16(const uint8_t *data, size_t size);

size_t tms2812_build_fixed_request(uint8_t controller, uint8_t command,
    const uint8_t *payload, size_t payload_size, uint8_t *output, size_t output_size);
/* command=0 is the host PING operation; on wire it is PEEK at 0x100. */
size_t tms2812_build_memory_request(uint8_t controller, uint8_t command,
    uint32_t word_address, uint16_t value, uint8_t *output, size_t output_size);
size_t tms2812_build_test_request(uint8_t controller, uint16_t duration,
    uint16_t pause, const uint8_t *digits, size_t digit_count,
    uint8_t *output, size_t output_size);
/* Ordinary BALZAM responses reserve two bytes after CRC. If allow_short_tail
 * is true only those bytes may be omitted; caller must observe the UART gap.
 * UPLOAD responses use tms2812_validate_upload_response instead. */
int tms2812_validate_response(const uint8_t *data, size_t size,
    uint8_t controller, uint8_t command, size_t full_size, int allow_short_tail);

size_t tms2812_build_upload_request(
    uint8_t controller, uint32_t word_address, uint32_t byte_count,
    uint8_t *output, size_t output_size);

size_t tms2812_expected_upload_response_size(uint32_t byte_count);

int tms2812_validate_upload_response(
    const uint8_t *data, size_t size, uint8_t controller,
    uint32_t byte_count);

int tms2812_decode_upload_response(
    const uint8_t *data, size_t size, uint8_t controller,
    uint32_t byte_count, uint8_t *output, size_t output_size);

#ifdef __cplusplus
}
#endif

#endif /* TMS2812_H */