qmk_firmware/internals/SERIAL_USB.md

331 lines
18 KiB
Markdown

# group `SERIAL_USB`
## Summary
Members | Descriptions
--------------------------------|---------------------------------------------
`define `[`_qmk_usb_driver_data`](#group___s_e_r_i_a_l___u_s_b_1ga623f2c1e20bb296cf3cbdc88d153b6c9) | `SerialDriver` specific data.
`define `[`_qmk_usb_driver_methods`](#group___s_e_r_i_a_l___u_s_b_1ga798bce936d06cb5332a1c0e545b84dbb) | `SerialUSBDriver` specific methods.
`enum `[`qmkusbstate_t`](#group___s_e_r_i_a_l___u_s_b_1ga534e1c5933a7c4785f5882ad21674302) | Driver state machine possible states.
`public static bool `[`qmkusb_start_receive`](#group___s_e_r_i_a_l___u_s_b_1ga4a2db2450b14c2a07c681b5d9429d76e)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * qmkusbp)` |
`public static size_t `[`_write`](#group___s_e_r_i_a_l___u_s_b_1ga5e8117f4f91892c3d46076b0853b9116)`(void * ip,const uint8_t * bp,size_t n)` |
`public static size_t `[`_read`](#group___s_e_r_i_a_l___u_s_b_1gac07ed241c806363b6d298d7b4e2c3dad)`(void * ip,uint8_t * bp,size_t n)` |
`public static msg_t `[`_put`](#group___s_e_r_i_a_l___u_s_b_1ga240a53ff8cbb972b8e9ccdd4cdbcaedd)`(void * ip,uint8_t b)` |
`public static msg_t `[`_get`](#group___s_e_r_i_a_l___u_s_b_1ga0ef118239efc83deca980513e7330658)`(void * ip)` |
`public static msg_t `[`_putt`](#group___s_e_r_i_a_l___u_s_b_1ga63abfd1c739742e5ae219f15824e47ca)`(void * ip,uint8_t b,sysinterval_t timeout)` |
`public static msg_t `[`_gett`](#group___s_e_r_i_a_l___u_s_b_1ga122f8c98aa183cf27022ea53a7cac4d5)`(void * ip,sysinterval_t timeout)` |
`public static size_t `[`_writet`](#group___s_e_r_i_a_l___u_s_b_1ga015a4300ed5207dec4541348a9a04671)`(void * ip,const uint8_t * bp,size_t n,sysinterval_t timeout)` |
`public static size_t `[`_readt`](#group___s_e_r_i_a_l___u_s_b_1ga87af5dde7865331b7634b63a3b004914)`(void * ip,uint8_t * bp,size_t n,sysinterval_t timeout)` |
`public static void `[`ibnotify`](#group___s_e_r_i_a_l___u_s_b_1ga278a0b24aa52959889f37ab7e8041698)`(io_buffers_queue_t * bqp)` | Notification of empty buffer released into the input buffers queue.
`public static void `[`obnotify`](#group___s_e_r_i_a_l___u_s_b_1gaf0e8ad9d01f2cbe14aa5a4e49f099547)`(io_buffers_queue_t * bqp)` | Notification of filled buffer inserted into the output buffers queue.
`public void `[`qmkusbInit`](#group___s_e_r_i_a_l___u_s_b_1ga3853659326b42a6df413177ff65d7c15)`(void)` | Serial Driver initialization.
`public void `[`qmkusbObjectInit`](#group___s_e_r_i_a_l___u_s_b_1gaf8ba926d88993cb4fab100f1ef427e0b)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * qmkusbp,const `[`QMKUSBConfig`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_config)` * config)` | Initializes a generic full duplex driver object.
`public void `[`qmkusbStart`](#group___s_e_r_i_a_l___u_s_b_1ga82f3c032f7fb6832a60d6048f69c3e3d)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * qmkusbp,const `[`QMKUSBConfig`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_config)` * config)` | Configures and starts the driver.
`public void `[`qmkusbStop`](#group___s_e_r_i_a_l___u_s_b_1gaa032aca2a467800dc0dc0e205b4757d5)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * qmkusbp)` | Stops the driver.
`public void `[`qmkusbSuspendHookI`](#group___s_e_r_i_a_l___u_s_b_1gad59935eea3dab7a0584fd759c884e814)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * qmkusbp)` | USB device suspend handler.
`public void `[`qmkusbWakeupHookI`](#group___s_e_r_i_a_l___u_s_b_1ga9bc8dd88462d0e3b39f7fdfec2c3ee55)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * qmkusbp)` | USB device wakeup handler.
`public void `[`qmkusbConfigureHookI`](#group___s_e_r_i_a_l___u_s_b_1ga920acd9f8890b819614515b73923b72f)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * qmkusbp)` | USB device configured handler.
`public bool `[`qmkusbRequestsHook`](#group___s_e_r_i_a_l___u_s_b_1gabae5bdec8abeac31be61c976301c37ba)`(USBDriver * usbp)` | Default requests hook.
`public void `[`qmkusbSOFHookI`](#group___s_e_r_i_a_l___u_s_b_1ga6db1c065c87835f96ffa248b80dbf381)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * qmkusbp)` | SOF handler.
`public void `[`qmkusbDataTransmitted`](#group___s_e_r_i_a_l___u_s_b_1ga2baecc9d4f4ec49c7e26b5dd0740c7cd)`(USBDriver * usbp,usbep_t ep)` | Default data transmitted callback.
`public void `[`qmkusbDataReceived`](#group___s_e_r_i_a_l___u_s_b_1gafb6e37d8a2dd4fe37aabf86d18275546)`(USBDriver * usbp,usbep_t ep)` | Default data received callback.
`public void `[`qmkusbInterruptTransmitted`](#group___s_e_r_i_a_l___u_s_b_1ga67ee1fd2c4129831dc15194d5284cf52)`(USBDriver * usbp,usbep_t ep)` | Default data received callback.
`struct `[`QMKUSBConfig`](#struct_q_m_k_u_s_b_config) | Serial over USB Driver configuration structure.
`struct `[`QMKUSBDriverVMT`](#struct_q_m_k_u_s_b_driver_v_m_t) | `SerialDriver` virtual methods table.
`struct `[`QMKUSBDriver`](#struct_q_m_k_u_s_b_driver) | Full duplex serial driver class.
## Members
#### `define `[`_qmk_usb_driver_data`](#group___s_e_r_i_a_l___u_s_b_1ga623f2c1e20bb296cf3cbdc88d153b6c9)
`SerialDriver` specific data.
#### `define `[`_qmk_usb_driver_methods`](#group___s_e_r_i_a_l___u_s_b_1ga798bce936d06cb5332a1c0e545b84dbb)
`SerialUSBDriver` specific methods.
#### `enum `[`qmkusbstate_t`](#group___s_e_r_i_a_l___u_s_b_1ga534e1c5933a7c4785f5882ad21674302)
Values | Descriptions
--------------------------------|---------------------------------------------
QMKUSB_UNINIT | Not initialized.
QMKUSB_STOP | Stopped.
QMKUSB_READY | Ready.
Driver state machine possible states.
#### `public static bool `[`qmkusb_start_receive`](#group___s_e_r_i_a_l___u_s_b_1ga4a2db2450b14c2a07c681b5d9429d76e)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * qmkusbp)`
#### `public static size_t `[`_write`](#group___s_e_r_i_a_l___u_s_b_1ga5e8117f4f91892c3d46076b0853b9116)`(void * ip,const uint8_t * bp,size_t n)`
#### `public static size_t `[`_read`](#group___s_e_r_i_a_l___u_s_b_1gac07ed241c806363b6d298d7b4e2c3dad)`(void * ip,uint8_t * bp,size_t n)`
#### `public static msg_t `[`_put`](#group___s_e_r_i_a_l___u_s_b_1ga240a53ff8cbb972b8e9ccdd4cdbcaedd)`(void * ip,uint8_t b)`
#### `public static msg_t `[`_get`](#group___s_e_r_i_a_l___u_s_b_1ga0ef118239efc83deca980513e7330658)`(void * ip)`
#### `public static msg_t `[`_putt`](#group___s_e_r_i_a_l___u_s_b_1ga63abfd1c739742e5ae219f15824e47ca)`(void * ip,uint8_t b,sysinterval_t timeout)`
#### `public static msg_t `[`_gett`](#group___s_e_r_i_a_l___u_s_b_1ga122f8c98aa183cf27022ea53a7cac4d5)`(void * ip,sysinterval_t timeout)`
#### `public static size_t `[`_writet`](#group___s_e_r_i_a_l___u_s_b_1ga015a4300ed5207dec4541348a9a04671)`(void * ip,const uint8_t * bp,size_t n,sysinterval_t timeout)`
#### `public static size_t `[`_readt`](#group___s_e_r_i_a_l___u_s_b_1ga87af5dde7865331b7634b63a3b004914)`(void * ip,uint8_t * bp,size_t n,sysinterval_t timeout)`
#### `public static void `[`ibnotify`](#group___s_e_r_i_a_l___u_s_b_1ga278a0b24aa52959889f37ab7e8041698)`(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`](#group___s_e_r_i_a_l___u_s_b_1gaf0e8ad9d01f2cbe14aa5a4e49f099547)`(io_buffers_queue_t * bqp)`
Notification of filled buffer inserted into the output buffers queue.
#### Parameters
* `bqp` the buffers queue pointer.
#### `public void `[`qmkusbInit`](#group___s_e_r_i_a_l___u_s_b_1ga3853659326b42a6df413177ff65d7c15)`(void)`
Serial Driver initialization.
This function is implicitly invoked by `halInit()`, there is no need to explicitly initialize the driver.
@init
#### `public void `[`qmkusbObjectInit`](#group___s_e_r_i_a_l___u_s_b_1gaf8ba926d88993cb4fab100f1ef427e0b)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * qmkusbp,const `[`QMKUSBConfig`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_config)` * 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`](#group___s_e_r_i_a_l___u_s_b_1ga82f3c032f7fb6832a60d6048f69c3e3d)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * qmkusbp,const `[`QMKUSBConfig`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_config)` * 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`](#group___s_e_r_i_a_l___u_s_b_1gaa032aca2a467800dc0dc0e205b4757d5)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * 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`](#group___s_e_r_i_a_l___u_s_b_1gad59935eea3dab7a0584fd759c884e814)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * 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`](#group___s_e_r_i_a_l___u_s_b_1ga9bc8dd88462d0e3b39f7fdfec2c3ee55)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * 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`](#group___s_e_r_i_a_l___u_s_b_1ga920acd9f8890b819614515b73923b72f)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * 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`](#group___s_e_r_i_a_l___u_s_b_1gabae5bdec8abeac31be61c976301c37ba)`(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`](#group___s_e_r_i_a_l___u_s_b_1ga6db1c065c87835f96ffa248b80dbf381)`(`[`QMKUSBDriver`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver)` * 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`](#group___s_e_r_i_a_l___u_s_b_1ga2baecc9d4f4ec49c7e26b5dd0740c7cd)`(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`](#group___s_e_r_i_a_l___u_s_b_1gafb6e37d8a2dd4fe37aabf86d18275546)`(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`](#group___s_e_r_i_a_l___u_s_b_1ga67ee1fd2c4129831dc15194d5284cf52)`(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`](#struct_q_m_k_u_s_b_config_1ada1ea0b2aba306995949dbaa24fdf71d) | USB driver to use.
`public usbep_t `[`bulk_in`](#struct_q_m_k_u_s_b_config_1afa43b7b434054546af9f4ec651c5f97e) | Bulk IN endpoint used for outgoing data transfer.
`public usbep_t `[`bulk_out`](#struct_q_m_k_u_s_b_config_1a88cf95319b2e27fb5bcdb6d3bb116ba5) | Bulk OUT endpoint used for incoming data transfer.
`public usbep_t `[`int_in`](#struct_q_m_k_u_s_b_config_1a475ce337f1cac40f24657c2030a2f268) | Interrupt IN endpoint used for notifications.
`public size_t `[`in_buffers`](#struct_q_m_k_u_s_b_config_1a983983e0ca22143fd32e8dc3383c174e) | The number of buffers in the queues.
`public size_t `[`out_buffers`](#struct_q_m_k_u_s_b_config_1a481eeab48689523b99a95e1666b2cb96) |
`public size_t `[`in_size`](#struct_q_m_k_u_s_b_config_1a600c0d75ca3fa7bafc2e38ce9bb0bf6e) | The size of each buffer in the queue, typically the same as the endpoint size.
`public size_t `[`out_size`](#struct_q_m_k_u_s_b_config_1ac5e66af2f4fed2cf04fcbd77f1114bfb) |
`public bool `[`fixed_size`](#struct_q_m_k_u_s_b_config_1ad90e1bf1d310f5fbf5e8ce49b596f94b) | Always send full buffers in_size (the rest is filled with zeroes)
`public uint8_t * `[`ib`](#struct_q_m_k_u_s_b_config_1ae3be5d8a14227ab7003a9523994cae54) |
`public uint8_t * `[`ob`](#struct_q_m_k_u_s_b_config_1a66f479912494377c5a80dc78ac2702cc) |
## Members
#### `public USBDriver * `[`usbp`](#struct_q_m_k_u_s_b_config_1ada1ea0b2aba306995949dbaa24fdf71d)
USB driver to use.
#### `public usbep_t `[`bulk_in`](#struct_q_m_k_u_s_b_config_1afa43b7b434054546af9f4ec651c5f97e)
Bulk IN endpoint used for outgoing data transfer.
#### `public usbep_t `[`bulk_out`](#struct_q_m_k_u_s_b_config_1a88cf95319b2e27fb5bcdb6d3bb116ba5)
Bulk OUT endpoint used for incoming data transfer.
#### `public usbep_t `[`int_in`](#struct_q_m_k_u_s_b_config_1a475ce337f1cac40f24657c2030a2f268)
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`](#struct_q_m_k_u_s_b_config_1a983983e0ca22143fd32e8dc3383c174e)
The number of buffers in the queues.
#### `public size_t `[`out_buffers`](#struct_q_m_k_u_s_b_config_1a481eeab48689523b99a95e1666b2cb96)
#### `public size_t `[`in_size`](#struct_q_m_k_u_s_b_config_1a600c0d75ca3fa7bafc2e38ce9bb0bf6e)
The size of each buffer in the queue, typically the same as the endpoint size.
#### `public size_t `[`out_size`](#struct_q_m_k_u_s_b_config_1ac5e66af2f4fed2cf04fcbd77f1114bfb)
#### `public bool `[`fixed_size`](#struct_q_m_k_u_s_b_config_1ad90e1bf1d310f5fbf5e8ce49b596f94b)
Always send full buffers in_size (the rest is filled with zeroes)
#### `public uint8_t * `[`ib`](#struct_q_m_k_u_s_b_config_1ae3be5d8a14227ab7003a9523994cae54)
#### `public uint8_t * `[`ob`](#struct_q_m_k_u_s_b_config_1a66f479912494377c5a80dc78ac2702cc)
# 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`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver_v_m_t)` * `[`vmt`](#struct_q_m_k_u_s_b_driver_1aa84464b0edad252f9f93af83c669501e) | Virtual Methods Table.
## Members
#### `public const struct `[`QMKUSBDriverVMT`](.build/docs/internals/SERIAL_USB.md#struct_q_m_k_u_s_b_driver_v_m_t)` * `[`vmt`](#struct_q_m_k_u_s_b_driver_1aa84464b0edad252f9f93af83c669501e)
Virtual Methods Table.