/* libhw/generic/io.h - Device-independent I/O definitions
 *
 * Copyright (C) 2024-2025  Luke T. Shumaker <lukeshu@lukeshu.com>
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

#ifndef _LIBHW_GENERIC_IO_H_
#define _LIBHW_GENERIC_IO_H_

#include <stddef.h>    /* for size_t */
#include <stdint.h>    /* for uintptr_t */
#include <sys/types.h> /* for ssize_t */

#include <libobj/obj.h>

/* structs ********************************************************************/

#if __unix__
#include <sys/uio.h>
#else
struct iovec {
	void    *iov_base;
	size_t   iov_len;
};
#endif

#define IOVEC_DISCARD ((void*)(~((uintptr_t)0)))

struct duplex_iovec {
	/**
	 * NULL is a valid pointer value in iov_read_to and
	 * iov_write_from.  To skip a read or write, use the special
	 * value IOVEC_DISCARD.
	 */
	void    *iov_read_to;
	void    *iov_write_from;
	size_t   iov_len;
};

/* utilities ******************************************************************/

/* slice iovec lists */
int  io_slice_cnt       (                          const struct        iovec *src, int src_cnt, size_t byte_start, size_t byte_max_cnt);
void io_slice           (struct        iovec *dst, const struct        iovec *src, int src_cnt, size_t byte_start, size_t byte_max_cnt);
int  io_duplex_slice_cnt(                          const struct duplex_iovec *src, int src_cnt, size_t byte_start, size_t byte_max_cnt);
void io_duplex_slice    (struct duplex_iovec *dst, const struct duplex_iovec *src, int src_cnt, size_t byte_start, size_t byte_max_cnt);

/* convert iovec lists */
void io_rd_to_duplex(struct duplex_iovec *dst, const struct iovec *src, int iovcnt);
void io_wr_to_duplex(struct duplex_iovec *dst, const struct iovec *src, int iovcnt);

/* slice and convert in one go */
void io_slice_rd_to_duplex(struct duplex_iovec *dst, const struct iovec *src, int src_cnt, size_t byte_start, size_t byte_max_cnt);
void io_slice_wr_to_duplex(struct duplex_iovec *dst, const struct iovec *src, int src_cnt, size_t byte_start, size_t byte_max_cnt);

/* basic interfaces ***********************************************************/

/**
 * Return bytes-read on success, 0 on EOF, -errno on error; a short
 * read is *not* an error.
 */
#define io_reader_LO_IFACE \
	LO_FUNC(ssize_t, readv, const struct iovec *iov, int iovcnt)
LO_INTERFACE(io_reader)
#define io_readv(r, iov, iovcnt) LO_CALL(r, readv, iov, iovcnt)
#define io_read(r, buf, count) LO_CALL(r, readv, &((struct iovec){.iov_base = buf, .iov_len = count}), 1)

/**
 * Return `count` on success, -errno on error; a short write *is* an
 * error.
 *
 * Writes are *not* guaranteed to be atomic, so if you have concurrent
 * writers then you should arrange for a mutex to protect the writer.
 */
#define io_writer_LO_IFACE \
	LO_FUNC(ssize_t, writev, const struct iovec *iov, int iovcnt)
LO_INTERFACE(io_writer)
#define io_writev(w, iov, iovcnt) LO_CALL(w, writev, iov, iovcnt)
#define io_write(w, buf, count) LO_CALL(w, writev, &((struct iovec){.iov_base = buf, .iov_len = count}), 1)

/**
 * Return 0 on success, -errno on error.
 */
#define io_closer_LO_IFACE \
	LO_FUNC(int, close)
LO_INTERFACE(io_closer)
#define io_close(c) LO_CALL(c, close)

/**
 * All methods return 0 on success, -errno on error.
 */
#define io_bidi_closer_LO_IFACE \
	LO_NEST(io_closer) \
	LO_FUNC(int, close_read) \
	LO_FUNC(int, close_write)
LO_INTERFACE(io_bidi_closer)
#define io_close_read(c) LO_CALL(c, close_read)
#define io_close_write(c) LO_CALL(c, close_write)

/**
 * Return bytes-read and bytes-written on success, -errno on error; a
 * short read/write *is* an error.
 */
#define io_duplex_readwriter_LO_IFACE \
	LO_FUNC(void, readwritev, const struct duplex_iovec *iov, int iovcnt)
LO_INTERFACE(io_duplex_readwriter)

#define io_readwritev(rw, iov, iovcnt) \
	LO_CALL(rw, readwritev, iov, iovcnt)

/* aggregate interfaces *******************************************************/

#define io_readwriter_LO_IFACE \
	LO_NEST(io_reader) \
	LO_NEST(io_writer)
LO_INTERFACE(io_readwriter)

#endif /* _LIBHW_GENERIC_IO_H_ */