#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);