API Convention

This is just a first draft. More information will be added.....

Naming convention

The format of a function name:
[device]_[operation]([parameters])

Set of operations

init
uint8_t [device]_init([pointer to typedef struct])
This operation initializes a device. Example of a function prototype for initializing the UART:
uint8_t uart_init(uart_settings_t *);
Where uart_settings_t is a type-defined struct, which is suitable for multiple parameters (example):
typedef struct uart_settings {
uint32_t baud_rate;
uint32_t parity;
} uart_settings_t;
As initialization can go wrong, it's important return a value. One method could be to return 1 for success and 0 for failure. Another method could be to return an error code. But in most cases the first method will be sufficient.
init is not suitable for all devices, such as digital I/O. See set for more information.

close
void [device]_close(void)
This operation shall only be implemented when it's absolutely needed.

read
uint32_t [device]_read([appropriate data type])
Return value could indicate a successful or complete reading. Parameter type is probably depending on what kind of data you're working with.

write
int [device]_write([appropriate type])
Return value could indicate a successful or complete writing. Parameter type is probably depending on what kind of data you're working with.

set
void [device]_set_[part of device]([parameters])
set is appropriate for simple devices. Example (digital I/O):
void digital_io_set_pin([parameters])

Modularity and preparation for further development

When designing an API it's good to make the device driver as modular as possible. Never call/use another device's API directly from the API you're developing.

API Dictionary (put functions in the following order)

1. init
   
2. set, select
   
3. enable, enabled, disable, disabled
   
4. read, write