BackEnd

UPC2 Communications Back End

Communications Back Ends are represented to the rest of the system through the the up_bio_t structure found in include/up_bio.h:

typedef struct up_bio_struct {
    void *handle;
    int (*poll_fd)(struct up_bio_struct *bio);
    int (*read)(struct up_bio_struct *bio, uint8_t *bytes, int nr);
    int (*write)(struct up_bio_struct *bio, const uint8_t *bytes, int nr);
    int (*safe_write)(struct up_bio_struct *bio, const uint8_t *bytes, int nr);
    int (*set_baud)(struct up_bio_struct *bio, int baud);
    void (*dispose)(struct up_bio_struct *bio);
} up_bio_t;

The handle field is provided for the private use of the back-end; to the rest of the system it is an opaque handle.

Conventionally the back-end supplies a function to allocate and fill in the structure: see up_bio_serial_create() for an example.

A back-end for general serial communications is supplied in src/up_bio_serial.c. Alternative implementations for less straightforward devices (wireless dongles, smoke signals, the flight paths of migrating starlings...) can be added as needed. These may need additional parameters from the front-end command-line parser, and potentially extra functions in the up_bio_t structure. If extra functions are required, dummy functions for existing back-ends will need to be written.

(RMJ: consider generalising set_baud() into a config() entry point passing a void * parameter.)

poll_fd(bio)

The purpose of this function is to return a file descriptor that can be polled. If no real file descriptor is available, a negative number should be returned so that poll() will ignore it.

read(bio, bytes, nr)

A non-blocking read with the same semantics as the standard POSIX read() function. Up to nr bytes are read into bytes. The return value is the number of bytes read, or a negative number on error. Returning zero bytes is permitted, and indeed normal for many protocols.

write(bio, bytes, nr)

A non-blocking write with the same semantics as the standard POSIX write() function. Up to nr bytes are written from bytes. The return value is the number of bytes written, or a negative number on error. Returning zero bytes is possible.

safe_write(bio, bytes, nr)

A blocking write that guarantees to send all nr bytes in the buffer bytes, or die trying. A utility function utils_bio_safe_write() can be used to provide this functionality trivially by (potentially) repeated calls to the back-end's write() routine. Returns the number of bytes written (always nr), or a negative number on error. (RMJ: in fact the utility function exits on error, so checking the return value is a little futile.)

set_baud(bio, baud)

Sets the baud rate of the connection, where that is meaningful. Returns 0 for success, or a negative number on error.

(RMJ: The serial implementation of this doesn't check it has been given a valid baud rate, and doesn't check that the setting worked either. At least one of these things should be fixed...)

dispose(bio)

Frees all resources associated with this instance of the back-end, including the up_bio_t structure if that was dynamically allocated.