sta-core/include/sta/bus/interface.hpp

#ifndef STA_CORE_BUS_SERIAL_INTERFACE_HPP
#define STA_CORE_BUS_SERIAL_INTERFACE_HPP

#include <sta/mutex.hpp>

#include <cstdint>
#include <cstddef>

/**
 * @brief The maximum timeout for bus communication in sta-core.
 */
#define STA_MAX_TIMEOUT         0xFFFFFFFFU

namespace sta
{
    /**
     * @brief Abstract interface for serial communication.
    */
    class Interface
    {
    public:
        /**
         * @param mutex     Mutex object for managing shared access. Pass nullptr for no access control.
         */
        Interface(Mutex * mutex);

        /**
         * @brief Send single byte of data.
         *
         * @param value     8-bit value
         */
        virtual bool transfer(uint8_t value, uint32_t timeout = STA_MAX_TIMEOUT) = 0;
        /**
         * @brief Send two bytes of data.
         *
         * @param value     16-bit value
         */
        virtual bool transfer16(uint16_t value, uint32_t timeout = STA_MAX_TIMEOUT) = 0;
        /**
         * @brief Send data from buffer.
         *
         * @param buffer    Source buffer
         * @param size      Number of bytes to transfer
         */
        virtual bool transfer(const uint8_t * buffer, size_t size, uint32_t timeout = STA_MAX_TIMEOUT) = 0;

        /**
         * @brief Write data to a specific memory address of the peripheral.
         * 
         * @param regAddr The memory address.
         * @param buffer The buffer of data to write to the address
         * @param size The number of bytes to write to the peripheral.
         */
        virtual bool writeMemory(uint8_t regAddr, const uint8_t * buffer, size_t size, uint32_t timeout = STA_MAX_TIMEOUT);

        /**
         * @brief Read incoming data to buffer.
         *
         * @param buffer    Destination buffer
         * @param size      Number of bytes to read
         */
        virtual bool receive(uint8_t * buffer, size_t size, uint32_t timeout = STA_MAX_TIMEOUT) = 0;

        /**
         * @brief Read data from a specific memory address of the peripheral.
         * 
         * @param regAddr The memory address.
         * @param buffer The buffer of data to write the received data to.
         * @param size The number of bytes to receive from the peripheral.
         */
        virtual bool readMemory(uint8_t regAddr, uint8_t * buffer, size_t size, uint32_t timeout = STA_MAX_TIMEOUT);

        /**
         * @brief Send byte value repeatedly.
         *
         * @param value     8-bit value to repeat
         * @param count     Number of repetitions
         */
        virtual bool fill(uint8_t value, size_t count, uint32_t timeout = STA_MAX_TIMEOUT) = 0;

        /**
         * @brief Acquire usage rights to use the interface.
         *
         * Must be called before any I/O operations are executed.
         */
        virtual void acquire(uint32_t timeout = STA_MAX_TIMEOUT);
        /**
         * @brief Release usage rights for interface.
         *
         * Must be called after last I/O operation.
         */
        virtual void release(uint32_t timeout = STA_MAX_TIMEOUT);

        /**
         * @returns true if the interface has been aquired.
        */
        bool isAcquired();
        
    private:
        Mutex * mutex_;
        bool    acquired_ = false;
    };
} // namespace sta


#endif // STA_CORE_BUS_SERIAL_INTERFACE_HPP