onidriver.h#

Definitions and function prototypes for implementing Driver Translators.

Constants and Types#

enum oni_read_stream_t#

Represent the available data streams from the device to the host.

ONI_READ_STREAM_DATA#

(0) High-speed data stream to host

ONI_READ_STREAM_SIGNAL#

(1) Low-speed signaling stream

enum oni_write_stream_t#

Represent the available data streams from the host to the device.

ONI_WRITE_STREAM_DATA#

(0) High-speed data stream from host

typedef void *oni_driver_ctx#

A handle to a driver translator context. Each driver creates its own context storing all state variables required for its functionality. This common type is used to interchange this context between the common API, which does not needed to know its contents, and the driver translator implementation.

Functions#

All driver translators must implement these functions. They are called internally by the public interface described in oni.h and perform direct hardware access as needed.

oni_driver_ctx oni_driver_create_ctx()
int oni_driver_destroy_ctx(oni_driver_ctx driver_ctx)
int oni_driver_init(oni_driver_ctx driver_ctx, int host_idx)
int oni_driver_read_stream(oni_driver_ctx driver_ctx, oni_read_stream_t stream, void *data, size_t size)
int oni_driver_write_stream(oni_driver_ctx driver_ctx, oni_write_stream_t stream, const char *data, size_t size)
int oni_driver_read_config(oni_driver_ctx driver_ctx, oni_config_t config, oni_reg_val_t *value)
int oni_driver_write_config(oni_driver_ctx driver_ctx, oni_config_t config, oni_reg_val_t value)
int oni_driver_set_opt_callback(oni_driver_ctx driver_ctx, int oni_option, const void *value, size_t option_len)
int oni_driver_set_opt(oni_driver_ctx driver_ctx, int driver_option, const void *value, size_t option_len)
int oni_driver_get_opt(oni_driver_ctx driver_ctx, int driver_option, void *value, size_t *option_len)
const oni_driver_info_t *oni_driver_info()
oni_driver_ctx oni_driver_create_ctx()#

Creates the driver translator context.

Returns:

A handle to the newly created internal context, if successful, NULL otherwise.

int oni_driver_destroy_ctx(oni_driver_ctx driver_ctx)#

Destroys the driver translator context and frees its resources.

Parameters:

  • driver_ctx – Handle to the open context to destroy.

Returns:

0 on success otherwise see Error Codes.

int oni_driver_init(oni_driver_ctx driver_ctx, int host_idx)#

Initializes a driver translator context opening a specific hardware instance.

Parameters:

  • driver_ctx – Handle to the context to be initialized.

  • host_idx – Index of the hardware device to open. The enumeration depends on the specific hardware. -1 always means open the first available device.

Returns:

0 on success otherwise see Error Codes.

int oni_driver_read_stream(oni_driver_ctx driver_ctx, oni_read_stream_t stream, void *data, size_t size)#

Performs a read operation over the specified input stream.

Parameters:

  • driver_ctx – Context handling the device driver translator state.

  • stream – The input stream to perform the read operation on.

  • data – Pointer to the data buffer. It must be big enough to fit the requested amount of data.

  • size – Size, in bytes, of the data to read. Must read this amount from the device.

Returns:

Bytes retrieved in case of a successful read, see Error Codes otherwise. If the amount of retrieved bytes were different from size, it would also be treated as an error by the API.

int oni_driver_write_stream(oni_driver_ctx driver_ctx, oni_write_stream_t stream, const char *data, size_t size)#

Performs a write operation over the specified output stream.

Parameters:

  • driver_ctx – Context handling the device driver translator state.

  • stream – The output stream to perform the write operation on.

  • data – Pointer to the data buffer. It must contain the amount of data requested to write.

  • size – Size, in bytes, of the data to write.

Returns:

Bytes sent in case of a successful write, see Error Codes otherwise.

int oni_driver_read_config(oni_driver_ctx driver_ctx, oni_config_t config, oni_reg_val_t *value)#

Performs a read operation from one of the hardware configuration registers described in the ONI specification.

Parameters:

  • driver_ctx – Context handling the device driver translator state.

  • config – Register to read from.

  • value – Variable to store the register value after it is read.

Returns:

0 on success otherwise see Error Codes.

int oni_driver_write_config(oni_driver_ctx driver_ctx, oni_config_t config, oni_reg_val_t value)#

Performs a write operation to one of the hardware configuration registers described in the ONI specification.

Parameters:

  • driver_ctx – Context handling the device driver translator state.

  • config – Register to write to.

  • value – Value to be written.

Returns:

0 on success otherwise see Error Codes.

int oni_driver_set_opt_callback(oni_driver_ctx driver_ctx, int oni_option, const void *value, size_t option_len)#

This function gets called as the last step after a successful oni_set_opt(). The driver can optionally use this for any internal adjustment required. See Writing Driver Translators for examples. If this function is not used, it is safe to do nothing and return ONI_ESUCCESS.

Parameters:

  • driver_ctx – Context handling the device driver translator state.

  • oni_option – Option set, as specified in the originating oni_set_opt() call.

  • value – Option value, as specified in the originating oni_set_opt() call.

  • option_len – Value length, as specified in the originating oni_set_opt() call.

Returns:

0 on success otherwise see Error Codes.

int oni_driver_set_opt(oni_driver_ctx driver_ctx, int driver_option, const void *value, size_t option_len)#

Sets an internal option specific to the driver translator. Called directly by oni_set_driver_opt(). If no such options exist in a specific driver this can be an empty function returning ONI_EINVALOPT.

Parameters:

  • driver_ctx – Context handling the device driver translator state.

  • driver_option – Option index to set, specific to the device driver translator.

  • value – buffer containing data to be written to driver_option.

  • option_len – Size of value buffer (including terminating null character, if applicable) in bytes.

Returns:

0 on success otherwise see Error Codes.

int oni_driver_get_opt(oni_driver_ctx driver_ctx, int driver_option, void *value, size_t *option_len)#

Reads an internal option specific to the driver translator. Called directly by oni_get_driver_opt(). If no such options exist in a specific driver this can be an empty function returning ONI_EINVALOPT.

Parameters:

  • driver_ctx – Context handling the device driver translator state.

  • driver_option – Option index to read, specific to the device driver translator.

  • value – buffer to store value of driver_option after it is read.

  • option_len – Pointer to the size of value buffer (including terminating null character, if applicable) in bytes.

Returns:

0 on success otherwise see Error Codes.

const oni_driver_info_t *oni_driver_info()#

Provides static information about the driver translator.

Returns:

A Driver Information structure containing information about the driver translator.