bus.h

Go to the documentation of this file.

/************************************************************************//**
 * \file    heivs/bus.h
 * \brief   bus abstraction
 * \author  marc dot pignat at hevs dot ch
 *
 * \defgroup bus Bus
 * \ingroup libheivs_stm32
 *
 * @{
 * \brief Bus abstraction layer.
 *
 * This abstraction will be used to hide bus (i2c, spi, ...) behind a easy to
 * use interface
 ***************************************************************************/
#ifndef HEIVS_BUS_H
#define HEIVS_BUS_H

#ifdef __cplusplus
    extern "C" {
#endif

#include <stdint.h>
#include <string.h>
#include "heivs/error.h"

#include "heivs/config.h"
#if USE_FREERTOS
#include "freertos/FreeRTOS.h"
#endif

#define BUS_PARANOIA 1 /**< 0 = less check, 1 = more checks */

/**
 * \brief State of the bus
 */
enum heivs_bus_state_t
{
    /**
     * Bus never initialized
     *
     * Choosen value is zero because C uninitialized variables are zeros
     *
     * \see bus_init
     */
    BUS_NOINIT      = 0,

    /**
     * Initialized, but free to use
     *
     * \see bus_get
     * \see bus_release
     */
    BUS_INACTIVE,

    /**
     * In use
     *
     * \see bus_release
     * \see bus_get
     */
    BUS_ACTIVE,

    /**
     * Low power mode, use bus_init to re-enable
     *
     * \see bus_suspend
     * \see bus_init
     */
    BUS_SUSPENDED,
};

/**
 * \brief Variable part of the bus description
 *
 * This part has been taken out of heivs_bus_t to save some RAM.
 *
 * \see heivs_bus_t
 */
struct heivs_bus_var_t
{
    enum heivs_bus_state_t state;

    #if USE_FREERTOS
    SemaphoreHandle_t   mutex;
    uint32_t            mutex_ignore;
    #endif
};

/**
 * \brief Bus handler
 */
struct heivs_bus_t
{
    /**
     * Current state of the bus
     */
    struct heivs_bus_var_t *var;

    /**
     * Bus name
     */
    const char *name;

    /**
     * private data for the underlying driver
     */
    const void *priv;

    /**
     * Init
     */
    status_e (*_init)(const struct heivs_bus_t *);

    /**
     * Suspend (disable the bus controller, put all used IOs to zero)
     */
    status_e (*_suspend)(const struct heivs_bus_t *);

    /**
     * Resume
     */
    status_e (*_resume)(const struct heivs_bus_t *);

    /**
     * Read/write/readwrite
     *
     * BUS must be get before and released after
     *
     * \see bus_get
     * \see bus_release
     */
    status_e (*_read)(const struct heivs_bus_t *, uint32_t address, uint8_t *data, size_t len, size_t *rlen);
    status_e (*_write)(const struct heivs_bus_t *, uint32_t address, const uint8_t *data, size_t len);
    status_e (*_writeread)(const struct heivs_bus_t *, uint32_t address, const uint8_t *src, size_t src_len, uint8_t *dst, size_t dst_len, size_t *rlen);
};

/**
 * \brief initialize the bus
 *
 * \param bus
 * \return #NO_ERROR for no problem
 */
status_e bus_init(const struct heivs_bus_t *bus);

/**
 * \brief Get exclusive access to the bus
 *
 * \param bus
 * \return #NO_ERROR for no problem
 * \see bus_release
 */
status_e bus_get(const struct heivs_bus_t *bus);

/**
 * \brief Release exclusive access to the bus
 *
 * \param bus
 * \return #NO_ERROR for no problem
 * \see bus_get
 */
status_e bus_release(const struct heivs_bus_t *bus);

/**
 * \brief Suspend the bus (low power mode)
 *
 * \param bus
 * \return #NO_ERROR for no problem
 *
 * This function will disable the bus controller, put all pins used to logical
 * level zero to prevent power leakage.
 *
 * The bus must be owned (bus_get) before suspend and can be resumed using
 * bus_resume
 *
 * \warning The bus is automatically released when an error occurs
 *
 * \see bus_get
 * \see bus_resume
 */
status_e bus_suspend(const struct heivs_bus_t *bus);

/**
 * \brief Resume the bus (from low power mode)
 *
 * \param bus
 * \return #NO_ERROR for no problem
 *
 * \warning The bus is automatically released when an error occurs
 *
 * \see bus_release
 * \see bus_suspend
 */
status_e bus_resume(const struct heivs_bus_t *bus);

/**
 * \brief Resume the bus (from low power mode)
 *
 * \param bus
 * \return #NO_ERROR for no problem
 *
 * \see bus_release
 * \see bus_suspend
 */

/**
 * \brief Read data from the bus
 *
 * \param bus
 * \param address for i2c, the chip address, unused for spi and uart
 * \param data buffer where the data will be stored
 * \param len buffer len
 * \param rlen effective count of read bytes, can be NULL if not interested
 *
 * \return #NO_ERROR for no problem
 *
 * \warning The bus is automatically released when an error occurs
 *
 * \see bus_release
 * \see bus_suspend
 */
status_e bus_read(const struct heivs_bus_t *bus, uint32_t address, void *data, size_t len, size_t *rlen);

/**
 * \brief Write data to the bus
 *
 * \param bus
 * \param address for i2c, the chip address, unused for spi and uart
 * \param data to be sent
 * \param len of data
 *
 * \return #NO_ERROR for no problem
 *
 * \warning The bus is automatically released when an error occurs
 *
 * \see bus_release
 * \see bus_suspend
 */
status_e bus_write(const struct heivs_bus_t *bus, uint32_t address, const void *data, size_t len);

/**
 * \brief Combined write and read data
 *
 * \param bus
 * \param address for i2c, the chip address, unused for spi and uart
 * \param src data to be sent
 * \param src_len len of src
 * \param dst data to be read
 * \param dst_len len of dst
 * \param rlen effective count of read bytes, can be NULL if not interested
 *
 * \return #NO_ERROR for no problem
 *
 * \warning The bus is automatically released when an error occurs
 *
 * \see bus_release
 * \see bus_suspend
 */
status_e bus_writeread(const struct heivs_bus_t *bus, uint32_t address, const void *src, size_t src_len, void *dst, size_t dst_len, size_t *rlen);

#ifdef __cplusplus
    }
#endif

/**
 * @}
 */
#endif /* HEIVS_BUS_H */