serial.h

Go to the documentation of this file.

/*
 * This file is part of the Ultibo project, https://ultibo.org/
 *
 * The MIT License (MIT)
 *
 * Copyright (c) 2026 Garry Wood <garry@softoz.com.au>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
#ifndef _ULTIBO_SERIAL_H
#define _ULTIBO_SERIAL_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "ultibo/globaltypes.h"
#include "ultibo/globalconst.h"
#include "ultibo/devices.h"

#define SERIAL_NAME_PREFIX  "Serial" 
 
#define SERIAL_LOGGING_DESCRIPTION  "Serial Logging"
 
#define SERIAL_RECEIVE_DEPTH_DEFAULT    SIZE_2K 
#define SERIAL_TRANSMIT_DEPTH_DEFAULT   SIZE_2K 
 
#define SERIAL_PUSH_TIMEOUT 50 

#define SERIAL_TYPE_NONE    0
#define SERIAL_TYPE_UART    1
#define SERIAL_TYPE_USB 2
 
#define SERIAL_TYPE_MAX 2

#define SERIAL_STATE_CLOSED 0
#define SERIAL_STATE_CLOSING    1
#define SERIAL_STATE_OPENING    2
#define SERIAL_STATE_OPEN   3
 
#define SERIAL_STATE_MAX    3

#define SERIAL_FLAG_NONE    0x00000000
#define SERIAL_FLAG_DATA_8BIT   0x00000001 
#define SERIAL_FLAG_DATA_7BIT   0x00000002 
#define SERIAL_FLAG_DATA_6BIT   0x00000004 
#define SERIAL_FLAG_DATA_5BIT   0x00000008 
#define SERIAL_FLAG_STOP_1BIT   0x00000010 
#define SERIAL_FLAG_STOP_2BIT   0x00000020 
#define SERIAL_FLAG_STOP_1BIT5  0x00000040 
#define SERIAL_FLAG_PARITY_ODD  0x00000080 
#define SERIAL_FLAG_PARITY_EVEN 0x00000100 
#define SERIAL_FLAG_PARITY_MARK 0x00000200 
#define SERIAL_FLAG_PARITY_SPACE    0x00000400 
#define SERIAL_FLAG_FLOW_RTS_CTS    0x00000800 
#define SERIAL_FLAG_FLOW_DSR_DTR    0x00001000 
#define SERIAL_FLAG_PUSH_RX 0x00002000 
#define SERIAL_FLAG_PUSH_TX 0x00004000 

#define SERIAL_READ_NONE    0x00000000
#define SERIAL_READ_NON_BLOCK   0x00000001 
#define SERIAL_READ_PEEK_BUFFER 0x00000002 

#define SERIAL_WRITE_NONE   0x00000000
#define SERIAL_WRITE_NON_BLOCK  0x00000001 
#define SERIAL_WRITE_PEEK_BUFFER    0x00000002 

#define SERIAL_WAIT_NONE    0
#define SERIAL_WAIT_RECEIVE 1 
#define SERIAL_WAIT_TRANSMIT    2 

#define SERIAL_FLUSH_NONE   0x00000000
#define SERIAL_FLUSH_RECEIVE    0x00000001 
#define SERIAL_FLUSH_TRANSMIT   0x00000002 

#define SERIAL_STATUS_NONE  0x00000000
#define SERIAL_STATUS_RTS   0x00000001 
#define SERIAL_STATUS_CTS   0x00000002 
#define SERIAL_STATUS_DSR   0x00000004 
#define SERIAL_STATUS_DTR   0x00000008 
#define SERIAL_STATUS_RX_FULL   0x00000010 
#define SERIAL_STATUS_RX_EMPTY  0x00000020 
#define SERIAL_STATUS_TX_FULL   0x00000040 
#define SERIAL_STATUS_TX_EMPTY  0x00000080 
#define SERIAL_STATUS_BUSY  0x00000100 
#define SERIAL_STATUS_BREAK_ERROR   0x00000200 
#define SERIAL_STATUS_PARITY_ERROR  0x00000400 
#define SERIAL_STATUS_FRAMING_ERROR 0x00000800 
#define SERIAL_STATUS_OVERRUN_ERROR 0x00001000 
#define SERIAL_STATUS_DCD   0x00002000 
#define SERIAL_STATUS_RI    0x00004000 


typedef struct _SERIAL_PROPERTIES SERIAL_PROPERTIES;
struct _SERIAL_PROPERTIES
{
    uint32_t flags; 
    uint32_t minrate; 
    uint32_t maxrate; 
    uint32_t baudrate; 
    uint32_t databits; 
    uint32_t stopbits; 
    uint32_t parity; 
    uint32_t flowcontrol; 
    uint32_t receivedepth; 
    uint32_t transmitdepth; 
};

typedef struct _SERIAL_BUFFER SERIAL_BUFFER;
struct _SERIAL_BUFFER
{
    EVENT_HANDLE wait; 
    uint32_t start; 
    uint32_t count; 
    uint32_t size; 
    void *data; 
};

typedef struct _SERIAL_DEVICE SERIAL_DEVICE;

typedef uint32_t STDCALL (*serial_enumerate_cb)(SERIAL_DEVICE *serial, void *data);
typedef uint32_t STDCALL (*serial_notification_cb)(DEVICE *device, void *data, uint32_t notification);

typedef uint32_t STDCALL (*serial_device_open_proc)(SERIAL_DEVICE *serial, uint32_t baudrate, uint32_t databits, uint32_t stopbits, uint32_t parity, uint32_t flowcontrol, uint32_t receivedepth, uint32_t transmitdepth);
typedef uint32_t STDCALL (*serial_device_close_proc)(SERIAL_DEVICE *serial);
 
typedef uint32_t STDCALL (*serial_device_read_proc)(SERIAL_DEVICE *serial, void *buffer, uint32_t size, uint32_t flags, uint32_t *count);
typedef uint32_t STDCALL (*serial_device_write_proc)(SERIAL_DEVICE *serial, void *buffer, uint32_t size, uint32_t flags, uint32_t *count);
 
typedef uint32_t STDCALL (*serial_device_wait_proc)(SERIAL_DEVICE *serial, uint32_t direction, uint32_t timeout, uint32_t *count);
typedef uint32_t STDCALL (*serial_device_flush_proc)(SERIAL_DEVICE *serial, uint32_t flags);
 
typedef uint32_t STDCALL (*serial_device_get_status_proc)(SERIAL_DEVICE *serial);
typedef uint32_t STDCALL (*serial_device_set_status_proc)(SERIAL_DEVICE *serial, uint32_t status);
 
typedef uint32_t STDCALL (*serial_device_get_properties_proc)(SERIAL_DEVICE *serial, SERIAL_PROPERTIES *properties);
typedef uint32_t STDCALL (*serial_device_set_properties_proc)(SERIAL_DEVICE *serial, SERIAL_PROPERTIES *properties);
 
struct _SERIAL_DEVICE
{
    // Device Properties
    DEVICE device; 
    // Serial Properties
    uint32_t serialid; 
    uint32_t serialstate; 
    uint32_t serialstatus; 
    serial_device_open_proc deviceopen; 
    serial_device_close_proc deviceclose; 
    serial_device_read_proc deviceread; 
    serial_device_write_proc devicewrite; 
    serial_device_wait_proc devicewait; 
    serial_device_flush_proc deviceflush; 
    serial_device_get_status_proc devicegetstatus; 
    serial_device_set_status_proc devicesetstatus; 
    serial_device_get_properties_proc devicegetproperties; 
    serial_device_set_properties_proc devicesetproperties; 
    // Driver Properties
    MUTEX_HANDLE lock; 
    SERIAL_BUFFER receive; 
    SERIAL_BUFFER transmit; 
    SERIAL_PROPERTIES properties; 
    // Statistics Properties
    uint32_t receivecount;
    uint32_t receiveerrors;
    uint32_t receiveoverruns;
    uint32_t transmitcount;
    uint32_t transmiterrors;
    uint32_t transmitoverruns;
    // Internal Properties
    SERIAL_DEVICE *prev; 
    SERIAL_DEVICE *next; 
};


uint32_t STDCALL serial_device_open(SERIAL_DEVICE *serial, uint32_t baudrate, uint32_t databits, uint32_t stopbits, uint32_t parity, uint32_t flowcontrol, uint32_t receivedepth, uint32_t transmitdepth);

uint32_t STDCALL serial_device_close(SERIAL_DEVICE *serial);

uint32_t STDCALL serial_device_read(SERIAL_DEVICE *serial, void *buffer, uint32_t size, uint32_t flags, uint32_t *count);

uint32_t STDCALL serial_device_write(SERIAL_DEVICE *serial, void *buffer, uint32_t size, uint32_t flags, uint32_t *count);

uint32_t STDCALL serial_device_wait(SERIAL_DEVICE *serial, uint32_t direction, uint32_t timeout, uint32_t *count);

uint32_t STDCALL serial_device_flush(SERIAL_DEVICE *serial, uint32_t flags);

uint32_t STDCALL serial_device_status(SERIAL_DEVICE *serial);

uint32_t STDCALL serial_device_get_status(SERIAL_DEVICE *serial);

uint32_t STDCALL serial_device_set_status(SERIAL_DEVICE *serial, uint32_t status);

uint32_t STDCALL serial_device_properties(SERIAL_DEVICE *serial, SERIAL_PROPERTIES *properties);

uint32_t STDCALL serial_device_get_properties(SERIAL_DEVICE *serial, SERIAL_PROPERTIES *properties);

uint32_t STDCALL serial_device_set_properties(SERIAL_DEVICE *serial, SERIAL_PROPERTIES *properties);

SERIAL_DEVICE * STDCALL serial_device_create(void);

SERIAL_DEVICE * STDCALL serial_device_create_ex(uint32_t size);

uint32_t STDCALL serial_device_destroy(SERIAL_DEVICE *serial);

uint32_t STDCALL serial_device_register(SERIAL_DEVICE *serial);

uint32_t STDCALL serial_device_deregister(SERIAL_DEVICE *serial);

SERIAL_DEVICE * STDCALL serial_device_find(uint32_t serialid);

SERIAL_DEVICE * STDCALL serial_device_find_by_name(const char *name);

SERIAL_DEVICE * STDCALL serial_device_find_by_description(const char *description);

uint32_t STDCALL serial_device_enumerate(serial_enumerate_cb callback, void *data);

uint32_t STDCALL serial_device_notification(SERIAL_DEVICE *serial, serial_notification_cb callback, void *data, uint32_t notification, uint32_t flags);

int STDCALL serial_device_printf(SERIAL_DEVICE *serial, const char *format, ...) _ATTRIBUTE ((__format__ (__printf__, 2, 3)));


uint32_t STDCALL serial_get_count(void);

SERIAL_DEVICE * STDCALL serial_device_get_default(void);

uint32_t STDCALL serial_device_set_default(SERIAL_DEVICE *serial);

SERIAL_DEVICE * STDCALL serial_device_check(SERIAL_DEVICE *serial);

uint32_t STDCALL serial_type_to_string(uint32_t serialtype, char *string, uint32_t len);

uint32_t STDCALL serial_state_to_string(uint32_t serialstate, char *string, uint32_t len);

BOOL STDCALL serial_device_redirect_input(SERIAL_DEVICE *serial);

BOOL STDCALL serial_device_redirect_output(SERIAL_DEVICE *serial);

void * STDCALL serial_buffer_read_start(SERIAL_BUFFER *buffer, uint32_t *available);

BOOL STDCALL serial_buffer_read_complete(SERIAL_BUFFER *buffer, uint32_t removed);

void * STDCALL serial_buffer_write_start(SERIAL_BUFFER *buffer, uint32_t *available);

BOOL STDCALL serial_buffer_write_complete(SERIAL_BUFFER *buffer, uint32_t added);
 
uint32_t STDCALL serial_data_bits_to_string(uint32_t bits, char *string, uint32_t len);
uint32_t STDCALL serial_stop_bits_to_string(uint32_t bits, char *string, uint32_t len);
uint32_t STDCALL serial_parity_to_string(uint32_t parity, char *string, uint32_t len);
uint32_t STDCALL serial_flow_control_to_string(uint32_t flow, char *string, uint32_t len);


uint32_t STDCALL serial_logging_device_add(SERIAL_DEVICE *serial);

uint32_t STDCALL serial_logging_device_remove(SERIAL_DEVICE *serial);

uint32_t STDCALL serial_logging_device_parameters(SERIAL_DEVICE *serial, const char *parameters, uint32_t *baudrate, uint32_t *parity, uint32_t *databits, uint32_t *stopbits);
 
#ifdef __cplusplus
}
#endif
 
#endif // _ULTIBO_SERIAL_H