1 files changed, 50 insertions, 17 deletions

diff --git a/libhw_generic/include/libhw/generic/io.h b/libhw_generic/include/libhw/generic/io.h
index ebbd6cb..19edbe6 100644
--- a/libhw_generic/include/libhw/generic/io.h
+++ b/libhw_generic/include/libhw/generic/io.h
@@ -15,6 +15,8 @@
 
 /* structs ********************************************************************/
 
+/* iovec ===========================================================*/
+
 #if __unix__
 #include <sys/uio.h>
 #else
@@ -23,6 +25,11 @@ struct iovec {
 	size_t   iov_len;
 };
 #endif
+typedef struct iovec iovec;
+DECLARE_ERROR_OR(iovec);
+DECLARE_ERROR_AND(iovec);
+
+/* duplex_iovec ====================================================*/
 
 #define IOVEC_DISCARD ((void*)(~((uintptr_t)0)))
 
@@ -36,8 +43,11 @@ struct duplex_iovec {
 	void    *iov_write_from;
 	size_t   iov_len;
 };
+typedef struct duplex_iovec duplex_iovec;
+DECLARE_ERROR_OR(duplex_iovec);
+DECLARE_ERROR_AND(duplex_iovec);
 
-/* utilities ******************************************************************/
+/* iovec utilities ************************************************************/
 
 /* If byte_max_cnt == 0, then there is no maximum.  */
 
@@ -57,9 +67,25 @@ void io_slice_wr_to_duplex(struct duplex_iovec *dst, const struct iovec *src, in
 
 /* basic interfaces ***********************************************************/
 
+/*
+ * Conventions:
+ *
+ *  - Naming:
+ *     + The "v"[ec] suffix means a sequence of iovecs, instead of a
+ *       simple buf+len.
+ *
+ *  - Errors:
+ *     + Short *reads* are *not* errors (and so return size_t *or*
+ *       error).
+ *     + Short *writes* *are* errors (and so return size_t *and*
+ *       (possibly-null) error).
+ */
+
+/* read ============================================================*/
+
 /**
  * Return bytes-read on success.  A short read is *not* an error
- * (unlike writev).
+ * (unlike `write` methods).
  *
  * It is invalid to call readv when the sum length of iovecs is 0.
  */
@@ -69,8 +95,11 @@ 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)
 
+/* write ===========================================================*/
+
 /**
- * Return bytes-written.  A short write *is* an error (unlike readv)
+ * Return bytes-written.  A short write *is* an error (unlike `read`
+ * methods).
  *
  * Writes are *not* guaranteed to be atomic, so if you have concurrent
  * writers then you should arrange for a mutex to protect the writer.
@@ -83,21 +112,11 @@ 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)
 
-#define io_closer_LO_IFACE \
-	LO_FUNC(error, close)
-LO_INTERFACE(io_closer);
-#define io_close(c) LO_CALL(c, close)
-
-#define io_bidi_closer_LO_IFACE \
-	LO_NEST(io_closer) \
-	LO_FUNC(error, close_read) \
-	LO_FUNC(error, 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)
+/* readwrite =======================================================*/
 
 /**
- * A short read/write *is* an error (like writev and unlike readv).
+ * A short read/write *is* an error (like `write` methods and unlike
+ * `read` methods).
  *
  * Reads/writes are *not* guaranteed to be atomic, so if you have
  * concurrent readers/writers then you should arrange for a mutex to
@@ -108,10 +127,24 @@ LO_INTERFACE(io_bidi_closer);
 #define io_duplex_readwriter_LO_IFACE \
 	LO_FUNC(size_t_and_error, 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)
 
+/* close ===========================================================*/
+
+#define io_closer_LO_IFACE \
+	LO_FUNC(error, close)
+LO_INTERFACE(io_closer);
+#define io_close(c) LO_CALL(c, close)
+
+#define io_bidi_closer_LO_IFACE \
+	LO_NEST(io_closer) \
+	LO_FUNC(error, close_read) \
+	LO_FUNC(error, 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)
+
 /* aggregate interfaces *******************************************************/
 
 #define io_readwriter_LO_IFACE \