iio-backend.h

/* SPDX-License-Identifier: MIT */
/*
 * libiio - Library for interfacing industrial I/O (IIO) devices
 *
 * Copyright (C) 2020 Analog Devices, Inc.
 */
 
#ifndef __IIO_BACKEND_H__
#define __IIO_BACKEND_H__
 
#include <iio/iio.h>
#include <stdbool.h>
 
#define __api __iio_api
 
#define __api_export_if(x) ___api_export_if(x)
#define ___api_export_if(x) ___api_export_if_##x
#define ___api_export_if_0
#define ___api_export_if_1 __iio_api_export
 
/* https://pubs.opengroup.org/onlinepubs/009695399/basedefs/limits.h.html
 * {NAME_MAX} : Maximum number of bytes in a filename
 * {PATH_MAX} : Maximum number of bytes in a pathname
 * {PAGESIZE} : Size in bytes of a page
 * Too bad we work on non-POSIX systems
 */
#ifndef NAME_MAX
#define NAME_MAX 256
#endif
#ifndef PATH_MAX
#define PATH_MAX 4096
#endif
#ifndef PAGESIZE
#define PAGESIZE 4096
#endif
 
#ifdef _MSC_BUILD
#define inline __inline
#define iio_sscanf sscanf_s
#else
#define iio_sscanf sscanf
#endif
 
#define IIO_ARRAY_SIZE(x) (sizeof(x) ? sizeof(x) / sizeof((x)[0]) : 0)
 
/*
 * Prototype of a user-supplied function that retrieves the number of ticks
 * (as microseconds) from a clock source. The value is used as a 64-bit
 * microsecond count; a 32-bit one would wrap after about 72 minutes.
 */
typedef uint64_t (*iio_get_ticks_us)(void);
 
struct iio_buffer;
struct iio_device;
struct iio_context;
struct iio_channel;
struct iio_block_pdata;
struct iio_buffer_pdata;
struct iio_context_pdata;
struct iio_device_pdata;
struct iio_scan_element;
struct iio_channel_pdata;
struct iio_event_stream_pdata;
 
enum iio_backend_api_ver {
    IIO_BACKEND_API_V1 = 1,
};
 
enum iio_attr_type {
    IIO_ATTR_TYPE_DEVICE = 0,
    IIO_ATTR_TYPE_DEBUG,
    IIO_ATTR_TYPE_DEVICE_EVENT,
    IIO_ATTR_TYPE_BUFFER,
    IIO_ATTR_TYPE_CHANNEL,
    IIO_ATTR_TYPE_CHANNEL_EVENT,
    IIO_ATTR_TYPE_CONTEXT,
};
 
#define CHN_ATTRLIST_IDX(type) (type - IIO_ATTR_TYPE_CHANNEL)
 
union iio_pointer {
    const struct iio_context *ctx;
    const struct iio_device *dev;
    const struct iio_channel *chn;
    const struct iio_buffer *buf;
};
 
struct iio_attr {
    union iio_pointer iio;
    enum iio_attr_type type;
    const char *name;
    const char *filename;
};
 
struct iio_backend_ops {
    int (*scan)(const struct iio_context_params *params, struct iio_scan *ctx,
            const char *args);
    struct iio_context *(*create)(const struct iio_context_params *params, const char *uri);
 
    ssize_t (*read_attr)(const struct iio_attr *attr, char *dst, size_t len);
    ssize_t (*write_attr)(const struct iio_attr *attr, const char *src, size_t len);
 
    const struct iio_device *(*get_trigger)(const struct iio_device *dev);
    int (*set_trigger)(const struct iio_device *dev, const struct iio_device *trigger);
 
    void (*shutdown)(struct iio_context *ctx);
 
    int (*get_version)(const struct iio_context *ctx, unsigned int *major, unsigned int *minor,
            unsigned int *patch, char git_tag[8]);
 
    int (*set_timeout)(struct iio_context *ctx, int timeout);
 
    struct iio_buffer_pdata *(*open_buffer)(const struct iio_device *dev, unsigned int idx,
            struct iio_channels_mask *mask);
    void (*close_buffer)(struct iio_buffer_pdata *pdata);
    int (*enable_buffer)(struct iio_buffer_pdata *pdata, size_t nb_samples, bool enable,
            bool cyclic);
    void (*cancel_buffer)(struct iio_buffer_pdata *pdata);
 
    ssize_t (*readbuf)(struct iio_buffer_pdata *pdata, void *dst, size_t len);
    ssize_t (*writebuf)(struct iio_buffer_pdata *pdata, const void *src, size_t len);
 
    struct iio_block_pdata *(*create_block)(
            struct iio_buffer_pdata *pdata, size_t size, void **data);
    void (*free_block)(struct iio_block_pdata *pdata);
 
    int (*enqueue_block)(struct iio_block_pdata *pdata, size_t bytes_used, bool cyclic);
    int (*dequeue_block)(struct iio_block_pdata *pdata, bool nonblock);
 
    int (*get_dmabuf_fd)(struct iio_block_pdata *pdata);
    int (*disable_cpu_access)(struct iio_block_pdata *pdata, bool disable);
 
    struct iio_event_stream_pdata *(*open_ev)(const struct iio_device *dev);
    void (*close_ev)(struct iio_event_stream_pdata *pdata);
    int (*read_ev)(struct iio_event_stream_pdata *pdata, struct iio_event *out_event,
            bool nonblock);
 
    /* Atomic register operations */
    int (*reg_read)(const struct iio_device *dev, uint32_t address, uint32_t *value);
    int (*reg_write)(const struct iio_device *dev, uint32_t address, uint32_t value);
 
    /* Channel format refresh */
    int (*refresh_format)(const struct iio_channel *chn);
 
    /* Connection liveness test */
    int (*ping)(struct iio_context *ctx);
};

struct iio_backend {
    unsigned int api_version;
    const char *name;
    const char *uri_prefix;
    const struct iio_backend_ops *ops;
    unsigned int default_timeout_ms;
};
 
/*
 * If Libiio was compiled with external backend support (WITH_EXTERNAL_BACKEND),
 * applications should implement their own backend and provide the
 * iio_external_backend symbol.
 */
extern const struct iio_backend iio_external_backend;
 
__api struct iio_context *iio_context_create_from_backend(const struct iio_context_params *params,
        const struct iio_backend *backend, const char *description, unsigned int major,
        unsigned int minor, unsigned int patch, const char *git_tag);
 
__api struct iio_device *iio_context_add_device(
        struct iio_context *ctx, const char *id, const char *name, const char *label);
 
__api struct iio_channel *iio_device_add_channel(struct iio_device *dev, long index, const char *id,
        const char *name, const char *label, bool output, bool scan_element,
        const struct iio_data_format *fmt);
 
__api struct iio_buffer *iio_device_add_buffer(struct iio_device *dev, unsigned int idx);
 
__api int iio_context_add_attr(struct iio_context *ctx, const char *key, const char *value);
__api int iio_device_add_attr(struct iio_device *dev, const char *name, enum iio_attr_type type);
 
__api int iio_buffer_add_attr(struct iio_buffer *buf, const char *name);
 
__api void iio_buffer_set_direction(struct iio_buffer *buf, const char *direction);
 
__api int iio_buffer_add_scan_element(
        struct iio_buffer *buf, const struct iio_channel *chn, const char *en_path);
 
__api int iio_parse_format_string(const char *fmt_str, struct iio_data_format *fmt);
 
__api int iio_channel_add_attr(struct iio_channel *chn, const char *name, enum iio_attr_type type,
        const char *filename);
 
__api struct iio_context_pdata *iio_context_get_pdata(const struct iio_context *ctx);
 
__api void iio_context_set_pdata(struct iio_context *ctx, struct iio_context_pdata *data);
 
__api struct iio_device_pdata *iio_device_get_pdata(const struct iio_device *dev);
 
__api void iio_device_set_pdata(struct iio_device *dev, struct iio_device_pdata *data);
 
__api struct iio_channel_pdata *iio_channel_get_pdata(const struct iio_channel *chn);
 
__api void iio_channel_set_pdata(struct iio_channel *chn, struct iio_channel_pdata *data);
 
__api int iio_scan_add_result(struct iio_scan *ctx, const char *desc, const char *uri);
 
#if defined(__MINGW32__)
#define __iio_printf __attribute__((__format__(gnu_printf, 3, 4)))
#elif defined(__GNUC__)
#define __iio_printf __attribute__((__format__(printf, 3, 4)))
#else
#define __iio_printf
#endif
 
__api __iio_printf ssize_t iio_snprintf(char *buf, size_t len, const char *fmt, ...);
__api char *iio_strdup(const char *str);
__api size_t iio_strlcpy(char *__restrict dst, const char *__restrict src, size_t dsize);
__api FILE *iio_fopen(const char *path, const char *mode);
 
__api struct iio_context *iio_create_context_from_xml(const struct iio_context_params *params,
        const char *uri, const struct iio_backend *backend, const char *description,
        const char **ctx_attr, const char **ctx_values, unsigned int nb_ctx_attrs);

__api void iio_register_get_ticks_us_cb(iio_get_ticks_us cb);
 
/* Allocate zeroed out memory */
static inline void *zalloc(size_t size)
{
    return calloc(1, size);
}
 
static inline const struct iio_device *iio_attr_get_device(const struct iio_attr *attr)
{
    switch (attr->type) {
    case IIO_ATTR_TYPE_CONTEXT:
        return NULL;
    case IIO_ATTR_TYPE_CHANNEL:
    case IIO_ATTR_TYPE_CHANNEL_EVENT:
        return iio_channel_get_device(attr->iio.chn);
    case IIO_ATTR_TYPE_BUFFER:
        return iio_buffer_get_device(attr->iio.buf);
    default:
        return attr->iio.dev;
    }
}
 
#undef __api
 
#endif /* __IIO_BACKEND_H__ */