diff options
Diffstat (limited to 'libhw_generic/include/libhw')
| -rw-r--r-- | libhw_generic/include/libhw/generic/alarmclock.h | 92 | ||||
| -rw-r--r-- | libhw_generic/include/libhw/generic/io.h | 118 | ||||
| -rw-r--r-- | libhw_generic/include/libhw/generic/net.h | 144 | ||||
| -rw-r--r-- | libhw_generic/include/libhw/generic/spi.h | 37 |
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_ */ |