qmk_firmware/internals/SERIAL_USB.md

group SERIAL_USB

Summary

Members	Descriptions
define _qmk_usb_driver_data	SerialDriver specific data.
define _qmk_usb_driver_methods	SerialUSBDriver specific methods.
enum qmkusbstate_t	Driver state machine possible states.
public static bool qmkusb_start_receive(QMKUSBDriver * qmkusbp)
public static size_t _write(void * ip,const uint8_t * bp,size_t n)
public static size_t _read(void * ip,uint8_t * bp,size_t n)
public static msg_t _put(void * ip,uint8_t b)
public static msg_t _get(void * ip)
public static msg_t _putt(void * ip,uint8_t b,sysinterval_t timeout)
public static msg_t _gett(void * ip,sysinterval_t timeout)
public static size_t _writet(void * ip,const uint8_t * bp,size_t n,sysinterval_t timeout)
public static size_t _readt(void * ip,uint8_t * bp,size_t n,sysinterval_t timeout)
public static void ibnotify(io_buffers_queue_t * bqp)	Notification of empty buffer released into the input buffers queue.
public static void obnotify(io_buffers_queue_t * bqp)	Notification of filled buffer inserted into the output buffers queue.
public void qmkusbInit(void)	Serial Driver initialization.
public void qmkusbObjectInit(QMKUSBDriver* qmkusbp,constQMKUSBConfig * config)	Initializes a generic full duplex driver object.
public void qmkusbStart(QMKUSBDriver* qmkusbp,constQMKUSBConfig * config)	Configures and starts the driver.
public void qmkusbStop(QMKUSBDriver * qmkusbp)	Stops the driver.
public void qmkusbSuspendHookI(QMKUSBDriver * qmkusbp)	USB device suspend handler.
public void qmkusbWakeupHookI(QMKUSBDriver * qmkusbp)	USB device wakeup handler.
public void qmkusbConfigureHookI(QMKUSBDriver * qmkusbp)	USB device configured handler.
public bool qmkusbRequestsHook(USBDriver * usbp)	Default requests hook.
public void qmkusbSOFHookI(QMKUSBDriver * qmkusbp)	SOF handler.
public void qmkusbDataTransmitted(USBDriver * usbp,usbep_t ep)	Default data transmitted callback.
public void qmkusbDataReceived(USBDriver * usbp,usbep_t ep)	Default data received callback.
public void qmkusbInterruptTransmitted(USBDriver * usbp,usbep_t ep)	Default data received callback.
struct QMKUSBConfig	Serial over USB Driver configuration structure.
struct QMKUSBDriverVMT	SerialDriver virtual methods table.
struct QMKUSBDriver	Full duplex serial driver class.

Members

define _qmk_usb_driver_data

SerialDriver specific data.

define _qmk_usb_driver_methods

SerialUSBDriver specific methods.

enum qmkusbstate_t

Values	Descriptions
QMKUSB_UNINIT	Not initialized.
QMKUSB_STOP	Stopped.
QMKUSB_READY	Ready.

Driver state machine possible states.

public static bool qmkusb_start_receive(QMKUSBDriver * qmkusbp)

public static size_t _write(void * ip,const uint8_t * bp,size_t n)

public static size_t _read(void * ip,uint8_t * bp,size_t n)

public static msg_t _put(void * ip,uint8_t b)

public static msg_t _get(void * ip)

public static msg_t _putt(void * ip,uint8_t b,sysinterval_t timeout)

public static msg_t _gett(void * ip,sysinterval_t timeout)

public static size_t _writet(void * ip,const uint8_t * bp,size_t n,sysinterval_t timeout)

public static size_t _readt(void * ip,uint8_t * bp,size_t n,sysinterval_t timeout)

public static void ibnotify(io_buffers_queue_t * bqp)

Notification of empty buffer released into the input buffers queue.

Parameters

• bqp the buffers queue pointer.

public static void obnotify(io_buffers_queue_t * bqp)

Notification of filled buffer inserted into the output buffers queue.

Parameters

• bqp the buffers queue pointer.

public void qmkusbInit(void)

Serial Driver initialization.

This function is implicitly invoked by halInit(), there is no need to explicitly initialize the driver.

@init

public void qmkusbObjectInit(QMKUSBDriver* qmkusbp,constQMKUSBConfig * config)

Initializes a generic full duplex driver object.

The HW dependent part of the initialization has to be performed outside, usually in the hardware initialization code.

Parameters

• qmkusbp pointer to a [QMKUSBDriver](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver) structure

@init

public void qmkusbStart(QMKUSBDriver* qmkusbp,constQMKUSBConfig * config)

Configures and starts the driver.

Parameters

• qmkusbp pointer to a [QMKUSBDriver](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver) object

• config the serial over USB driver configuration

@api

public void qmkusbStop(QMKUSBDriver * qmkusbp)

Stops the driver.

Any thread waiting on the driver's queues will be awakened with the message MSG_RESET.

Parameters

• qmkusbp pointer to a [QMKUSBDriver](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver) object

@api

public void qmkusbSuspendHookI(QMKUSBDriver * qmkusbp)

USB device suspend handler.

Generates a CHN_DISCONNECT event and puts queues in non-blocking mode, this way the application cannot get stuck in the middle of an I/O operations. If this function is not called from an ISR then an explicit call to osalOsRescheduleS() in necessary afterward.

Parameters

• qmkusbp pointer to a [QMKUSBDriver](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver) object

@iclass

public void qmkusbWakeupHookI(QMKUSBDriver * qmkusbp)

USB device wakeup handler.

Generates a CHN_CONNECT event and resumes normal queues operations.

If this function is not called from an ISR then an explicit call to osalOsRescheduleS() in necessary afterward.

Parameters

• qmkusbp pointer to a [QMKUSBDriver](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver) object

@iclass

public void qmkusbConfigureHookI(QMKUSBDriver * qmkusbp)

USB device configured handler.

Parameters

• qmkusbp pointer to a [QMKUSBDriver](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver) object

@iclass

public bool qmkusbRequestsHook(USBDriver * usbp)

Default requests hook.

Applications wanting to use the Serial over USB driver can use this function as requests hook in the USB configuration. The following requests are emulated:

• CDC_GET_LINE_CODING.

• CDC_SET_LINE_CODING.

• CDC_SET_CONTROL_LINE_STATE.

Parameters

• usbp pointer to the USBDriver object

Returns

The hook status.

Parameters

• true Message handled internally.

• false Message not handled.

public void qmkusbSOFHookI(QMKUSBDriver * qmkusbp)

SOF handler.

The SOF interrupt is used for automatic flushing of incomplete buffers pending in the output queue.

Parameters

• qmkusbp pointer to a [QMKUSBDriver](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver) object

@iclass

public void qmkusbDataTransmitted(USBDriver * usbp,usbep_t ep)

Default data transmitted callback.

The application must use this function as callback for the IN data endpoint.

Parameters

• usbp pointer to the USBDriver object

• ep IN endpoint number

public void qmkusbDataReceived(USBDriver * usbp,usbep_t ep)

Default data received callback.

The application must use this function as callback for the OUT data endpoint.

Parameters

• usbp pointer to the USBDriver object

• ep OUT endpoint number

public void qmkusbInterruptTransmitted(USBDriver * usbp,usbep_t ep)

Default data received callback.

The application must use this function as callback for the IN interrupt endpoint.

Parameters

• usbp pointer to the USBDriver object

• ep endpoint number

struct QMKUSBConfig

Serial over USB Driver configuration structure.

An instance of this structure must be passed to sduStart() in order to configure and start the driver operations.

Summary

Members	Descriptions
public USBDriver * usbp	USB driver to use.
public usbep_t bulk_in	Bulk IN endpoint used for outgoing data transfer.
public usbep_t bulk_out	Bulk OUT endpoint used for incoming data transfer.
public usbep_t int_in	Interrupt IN endpoint used for notifications.
public size_t in_buffers	The number of buffers in the queues.
public size_t out_buffers
public size_t in_size	The size of each buffer in the queue, typically the same as the endpoint size.
public size_t out_size
public bool fixed_size	Always send full buffers in_size (the rest is filled with zeroes)
public uint8_t * ib
public uint8_t * ob

Members

public USBDriver * usbp

USB driver to use.

public usbep_t bulk_in

Bulk IN endpoint used for outgoing data transfer.

public usbep_t bulk_out

Bulk OUT endpoint used for incoming data transfer.

public usbep_t int_in

Interrupt IN endpoint used for notifications.

If set to zero then the INT endpoint is assumed to be not present, USB descriptors must be changed accordingly.

public size_t in_buffers

The number of buffers in the queues.

public size_t out_buffers

public size_t in_size

The size of each buffer in the queue, typically the same as the endpoint size.

public size_t out_size

public bool fixed_size

Always send full buffers in_size (the rest is filled with zeroes)

public uint8_t * ib

public uint8_t * ob

struct QMKUSBDriverVMT

struct QMKUSBDriverVMT
  : public BaseAsynchronousChannelVMT

SerialDriver virtual methods table.

Summary

Members	Descriptions

Members

struct QMKUSBDriver

struct QMKUSBDriver
  : public BaseAsynchronousChannel

Full duplex serial driver class.

This class extends BaseAsynchronousChannel by adding physical I/O queues.

Summary

Members	Descriptions
public const struct QMKUSBDriverVMT*vmt	Virtual Methods Table.

Members

public const struct QMKUSBDriverVMT*vmt

Virtual Methods Table.