portable device access api based on unix file descriptors

common/include/hardware/interfaces.h

@@ -0,0 +1,37 @@
+#pragma once
+
+#include <stddef.h>
+#include <sys/types.h>
+
+/**
+ * Access to hardware interfaces local to the machine the code is running on.
+ * 
+ * The file descriptor returned by hw_decvice_open() is to be used by the standard
+ * read/write calls and to be closed by close().
+ * 
+ * For some specific hardware interfaces specific transactional calls are provided here
+ * to increase realtime performance.
+ * 
+ * So far the only example is an SPI interface, which performs synchronous transfers of
+ * n bytes in, n bytes out. If a write call is performed on such an interface, the number
+ * of bytes transfered equals the size of the hardware send buffer. For a read() call, the
+ * bytes contained in the hardware's receive buffer are returned.
+ */
+
+/**
+ * open a hardware device
+ * 
+ * if successful, returns a file descriptor to be used with read/write/transfer/close calls
+ * otherwise returns -1
+ */
+int hw_device_open(const char * path, size_t path_len);
+
+/**
+ * Perform a transfer of buffer_len bytes in and out.
+ * 
+ * sendbuffer and receivebuffer may be equal, where received bytes overwrite
+ * send bytes.
+ * 
+ * returns actual number of bytes transfered
+ */
+ssize_t hw_device_transfer(int fd, void* sendbuffer, void* receivebuffer, size_t buffer_len);