summaryrefslogtreecommitdiff
path: root/libhw_generic/include
diff options
context:
space:
mode:
Diffstat (limited to 'libhw_generic/include')
-rw-r--r--libhw_generic/include/libhw/generic/alarmclock.h92
-rw-r--r--libhw_generic/include/libhw/generic/io.h118
-rw-r--r--libhw_generic/include/libhw/generic/net.h144
-rw-r--r--libhw_generic/include/libhw/generic/spi.h37
4 files changed, 391 insertions, 0 deletions
diff --git a/libhw_generic/include/libhw/generic/alarmclock.h b/libhw_generic/include/libhw/generic/alarmclock.h
new file mode 100644
index 0000000..02789f5
--- /dev/null
+++ b/libhw_generic/include/libhw/generic/alarmclock.h
@@ -0,0 +1,92 @@
+/* libhw/generic/alarmclock.h - Device-independent alarmclock definitions
+ *
+ * Copyright (C) 2024-2025 Luke T. Shumaker <lukeshu@lukeshu.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+#ifndef _LIBHW_GENERIC_ALARMCLOCK_H_
+#define _LIBHW_GENERIC_ALARMCLOCK_H_
+
+#include <stdbool.h> /* for bool */
+#include <stdint.h> /* for uint{n}_t and UINT{n}_C */
+
+#include <libmisc/private.h>
+#include <libobj/obj.h>
+
+/* Useful constants ***********************************************************/
+
+#define NS_PER_S UINT64_C(1000000000) /* needs at least log₂(10⁹) ≈ 29.9 bits */
+#define US_PER_S UINT64_C(1000000) /* needs at least log₂(10⁶) ≈ 19.9 bits */
+#define MS_PER_S UINT64_C(1000) /* needs at least log₂(10³) ≈ 9.9 bits */
+
+/* Structs ********************************************************************/
+
+struct alarmclock_trigger;
+struct alarmclock_trigger {
+ BEGIN_PRIVATE(LIBHW_GENERIC_ALARMCLOCK_H);
+ void *alarmclock;
+ struct alarmclock_trigger *prev, *next;
+
+ uint64_t fire_at_ns;
+ void (*cb)(void *);
+ void *cb_arg;
+ END_PRIVATE(LIBHW_GENERIC_ALARMCLOCK_H);
+};
+
+/* Interface ******************************************************************/
+
+#define alarmclock_LO_IFACE \
+ /** \
+ * (2⁶⁴-1 nanoseconds is more than 500 years; there is little \
+ * risk of this overflowing) \
+ */ \
+ LO_FUNC(uint64_t, get_time_ns) \
+ \
+ /** \
+ * Returns true on error. \
+ * \
+ * Implementations may return an error if fire_at_ns is more \
+ * than UINT32_MAX µs (72 minutes) in the future. \
+ * \
+ * If fire_at_ns is in the past, then it will fire \
+ * immediately. \
+ */ \
+ LO_FUNC(bool, add_trigger, struct alarmclock_trigger *trigger, \
+ uint64_t fire_at_ns, \
+ void (*cb)(void *), \
+ void *cb_arg) \
+ \
+ LO_FUNC(void, del_trigger, struct alarmclock_trigger *trigger)
+LO_INTERFACE(alarmclock);
+
+/* Utilities ******************************************************************/
+
+void alarmclock_sleep_until_ns(lo_interface alarmclock clock, uint64_t abstime_ns);
+
+static inline void alarmclock_sleep_for_ns(lo_interface alarmclock clock, uint64_t delta_ns) {
+ alarmclock_sleep_until_ns(clock, LO_CALL(clock, get_time_ns) + delta_ns);
+}
+
+static inline void alarmclock_sleep_for_us(lo_interface alarmclock clock, uint64_t delta_us) {
+ alarmclock_sleep_for_ns(clock, delta_us * (NS_PER_S/US_PER_S));
+}
+
+static inline void alarmclock_sleep_for_ms(lo_interface alarmclock clock, uint64_t delta_ms) {
+ alarmclock_sleep_for_ns(clock, delta_ms * (NS_PER_S/MS_PER_S));
+}
+
+static inline void alarmclock_sleep_for_s(lo_interface alarmclock clock, uint64_t delta_s) {
+ alarmclock_sleep_for_ns(clock, delta_s * NS_PER_S);
+}
+
+/* Globals ********************************************************************/
+
+extern lo_interface alarmclock bootclock;
+
+#define sleep_until_ns(t) alarmclock_sleep_until_ns(bootclock, t)
+#define sleep_for_ns(t) alarmclock_sleep_for_ns(bootclock, t)
+#define sleep_for_us(t) alarmclock_sleep_for_us(bootclock, t)
+#define sleep_for_ms(t) alarmclock_sleep_for_ms(bootclock, t)
+#define sleep_for_s(t) alarmclock_sleep_for_s(bootclock, t)
+
+#endif /* _LIBHW_GENERIC_ALARMCLOCK_H_ */
diff --git a/libhw_generic/include/libhw/generic/io.h b/libhw_generic/include/libhw/generic/io.h
new file mode 100644
index 0000000..62ddbb3
--- /dev/null
+++ b/libhw_generic/include/libhw/generic/io.h
@@ -0,0 +1,118 @@
+/* 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_ */
diff --git a/libhw_generic/include/libhw/generic/net.h b/libhw_generic/include/libhw/generic/net.h
new file mode 100644
index 0000000..4af574b
--- /dev/null
+++ b/libhw_generic/include/libhw/generic/net.h
@@ -0,0 +1,144 @@
+/* libhw/generic/net.h - Device-independent network definitions
+ *
+ * Copyright (C) 2024-2025 Luke T. Shumaker <lukeshu@lukeshu.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+#ifndef _LIBHW_GENERIC_NET_H_
+#define _LIBHW_GENERIC_NET_H_
+
+#include <inttypes.h> /* for PRI{u,x}{n} */
+#include <stdbool.h> /* for bool */
+#include <stddef.h> /* for size_t */
+#include <stdint.h> /* for uint{n}_t} */
+#include <sys/types.h> /* for ssize_t */
+
+#include <libhw/generic/io.h>
+
+/* Errnos *********************************************************************/
+
+#define NET_EOTHER 1
+#define NET_EARP_TIMEOUT 2
+#define NET_EACK_TIMEOUT 3
+#define NET_ERECV_TIMEOUT 4
+#define NET_ETHREAD 5
+#define NET_ECLOSED 6
+#define NET_EMSGSIZE 7
+
+const char *net_strerror(int net_errno);
+
+/* Address types **************************************************************/
+
+struct net_ip4_addr {
+ unsigned char octets[4];
+};
+
+static const struct net_ip4_addr net_ip4_addr_broadcast = {{255, 255, 255, 255}};
+static const struct net_ip4_addr net_ip4_addr_zero = {{0, 0, 0, 0}};
+
+#define PRI_net_ip4_addr "%"PRIu8".%"PRIu8".%"PRIu8".%"PRIu8
+#define ARG_net_ip4_addr(addr) (addr).octets[0], \
+ (addr).octets[1], \
+ (addr).octets[2], \
+ (addr).octets[3]
+
+struct net_eth_addr {
+ unsigned char octets[6];
+};
+
+#define PRI_net_eth_addr "%02"PRIx8":%02"PRIx8":%02"PRIx8":%02"PRIx8":%02"PRIx8":%02"PRIx8
+#define ARG_net_eth_addr(addr) (addr).octets[0], \
+ (addr).octets[1], \
+ (addr).octets[2], \
+ (addr).octets[3], \
+ (addr).octets[4], \
+ (addr).octets[5]
+
+/* Streams (e.g. TCP) *********************************************************/
+
+lo_interface net_stream_conn;
+
+#define net_stream_listener_LO_IFACE \
+ /** \
+ * It is invalid to accept() a new connection if an existing \
+ * connection is still open. \
+ */ \
+ LO_FUNC(lo_interface net_stream_conn, accept) \
+ \
+ /** \
+ * The net_stream_conn returned from accept() may still be \
+ * valid after the listener is closed. \
+ */ \
+ LO_NEST(io_closer)
+LO_INTERFACE(net_stream_listener);
+
+#define net_stream_conn_LO_IFACE \
+ LO_NEST(io_readwriter) \
+ LO_NEST(io_bidi_closer) \
+ \
+ /** \
+ * Set a timestamp after which calls to read() will return \
+ * NET_ETIMEDOUT. The timestamp is in nanoseconds on the \
+ * system monotonic clock, which is usually (on pico-sdk and \
+ * on the Linux kernel) nanoseconds-since-boot. \
+ * \
+ * A zero value disables the deadline. \
+ * \
+ * (2⁶⁴-1 nanoseconds is more than 500 years; there is little \
+ * risk of this overflowing) \
+ */ \
+ LO_FUNC(void, set_read_deadline, uint64_t ns_since_boot)
+LO_INTERFACE(net_stream_conn);
+
+/* Packets (e.g. UDP) *********************************************************/
+
+#define net_packet_conn_LO_IFACE \
+ LO_FUNC(ssize_t, sendto, \
+ void *buf, size_t len, \
+ struct net_ip4_addr node, uint16_t port) \
+ \
+ /** \
+ * @return The full length of the message, which may be more \
+ * than the given `len` (as if the Linux MSG_TRUNC flag were \
+ * given). \
+ */ \
+ LO_FUNC(ssize_t, recvfrom, \
+ void *buf, size_t len, \
+ struct net_ip4_addr *ret_node, uint16_t *ret_port) \
+ \
+ /** \
+ * Set a timestamp after which calls to recvfrom() will return \
+ * NET_ETIMEDOUT. The timestamp is in nanoseconds on the \
+ * system monotonic clock, which is usually (on pico-sdk and \
+ * on the Linux kernel) nanoseconds-since-boot. \
+ * \
+ * A zero value disables the deadline. \
+ * \
+ * (2⁶⁴-1 nanoseconds is more than 500 years; there is little \
+ * risk of this overflowing) \
+ */ \
+ LO_FUNC(void, set_recv_deadline, \
+ uint64_t ns_since_boot) \
+ \
+ LO_NEST(io_closer)
+LO_INTERFACE(net_packet_conn);
+
+/* Interfaces *****************************************************************/
+
+struct net_iface_config {
+ struct net_ip4_addr addr;
+ struct net_ip4_addr gateway_addr;
+ struct net_ip4_addr subnet_mask;
+};
+
+#define net_iface_LO_IFACE \
+ LO_FUNC(struct net_eth_addr , hwaddr ) \
+ LO_FUNC(void , ifup , struct net_iface_config) \
+ LO_FUNC(void , ifdown ) \
+ \
+ LO_FUNC(lo_interface net_stream_listener, tcp_listen, uint16_t local_port) \
+ LO_FUNC(lo_interface net_stream_conn , tcp_dial , struct net_ip4_addr remote_node, uint16_t remote_port) \
+ LO_FUNC(lo_interface net_packet_conn , udp_conn , uint16_t local_port)
+LO_INTERFACE(net_iface);
+
+#endif /* _LIBHW_GENERIC_NET_H_ */
diff --git a/libhw_generic/include/libhw/generic/spi.h b/libhw_generic/include/libhw/generic/spi.h
new file mode 100644
index 0000000..4bbf649
--- /dev/null
+++ b/libhw_generic/include/libhw/generic/spi.h
@@ -0,0 +1,37 @@
+/* libhw/generic/spi.h - Device-independent SPI definitions
+ *
+ * Copyright (C) 2024-2025 Luke T. Shumaker <lukeshu@lukeshu.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+#ifndef _LIBHW_GENERIC_SPI_H_
+#define _LIBHW_GENERIC_SPI_H_
+
+#include <stddef.h> /* for size_t */
+
+#include <libhw/generic/io.h>
+
+enum spi_mode {
+ SPI_MODE_0 = 0, /* clk_polarity=0 (idle low), clk_phase=0 (sample on rise) */
+ SPI_MODE_1 = 1, /* clk_polarity=0 (idle low), clk_phase=1 (sample on fall) */
+ SPI_MODE_2 = 2, /* clk_polarity=1 (idle high), clk_phase=0 (sample on rise) */
+ SPI_MODE_3 = 3, /* clk_polarity=1 (idle high), clk_phase=1 (sample on fall) */
+};
+
+/* This API assumes that an SPI frame is a multiple of 8-bits.
+ *
+ * It is my understanding that this is a common constraint of SPI
+ * hardware, and that the RP2040 is somewhat unusual in that it allows
+ * frames of any length 4-16 bits (we disconnect the CS pin from the
+ * PL022 SSP and manually GPIO it from the CPU in order to achieve
+ * longer frames).
+ *
+ * But, more relevantly: The W5500's protocol uses frames that are 4-N
+ * octets; so we have no need for an API that allows a
+ * non-multiple-of-8 number of bits.
+ */
+#define spi_LO_IFACE \
+ LO_NEST(io_duplex_readwriter)
+LO_INTERFACE(spi);
+
+#endif /* _LIBHW_GENERIC_SPI_H_ */
generated by cgit v1.2.3-2-g168b (git 2.25.1) at 2025-04-21 16:26:38 +0000