diff options
Diffstat (limited to 'docs/en/api/api_host.rst')
| -rwxr-xr-x | docs/en/api/api_host.rst | 317 |
1 files changed, 317 insertions, 0 deletions
diff --git a/docs/en/api/api_host.rst b/docs/en/api/api_host.rst new file mode 100755 index 00000000..7499d188 --- /dev/null +++ b/docs/en/api/api_host.rst @@ -0,0 +1,317 @@ +Host Protocol Stack +======================================= + +For the naming, classification, and member composition of structures in the host protocol stack, refer to the following two diagrams: + +.. figure:: img/api_host1.png +.. figure:: img/api_host2.png + +CORE +----------------- + +CLASS Driver Information Structure +"""""""""""""""""""""""""""""""""""" + +.. code-block:: C + + struct usbh_class_info { + uint8_t match_flags; /* Used for product specific matches; range is inclusive */ + uint8_t bInterfaceClass; /* Base device class code */ + uint8_t bInterfaceSubClass; /* Sub-class, depends on base class. Eg. */ + uint8_t bInterfaceProtocol; /* Protocol, depends on base class. Eg. */ + const uint16_t (*id_table)[2]; /* List of Vendor/Product ID pairs */ + const struct usbh_class_driver *class_driver; + }; + +Endpoint Structure +"""""""""""""""""""""""""""""""""""" + +.. code-block:: C + + struct usbh_endpoint { + struct usb_endpoint_descriptor ep_desc; + }; + +Interface Altsetting Structure +"""""""""""""""""""""""""""""""""""" + +.. code-block:: C + + struct usbh_interface_altsetting { + struct usb_interface_descriptor intf_desc; + struct usbh_endpoint ep[CONFIG_USBHOST_MAX_ENDPOINTS]; + }; + +Interface Structure +"""""""""""""""""""""""""""""""""""" + +.. code-block:: C + + struct usbh_interface { + char devname[CONFIG_USBHOST_DEV_NAMELEN]; + struct usbh_class_driver *class_driver; + void *priv; + struct usbh_interface_altsetting altsetting[CONFIG_USBHOST_MAX_INTF_ALTSETTINGS]; + uint8_t altsetting_num; + }; + +Configuration Structure +"""""""""""""""""""""""""""""""""""" + +.. code-block:: C + + struct usbh_configuration { + struct usb_configuration_descriptor config_desc; + struct usbh_interface intf[CONFIG_USBHOST_MAX_INTERFACES]; + }; + +hubport Structure +"""""""""""""""""""""""""""""""""""" + +.. code-block:: C + + struct usbh_hubport { + bool connected; /* True: device connected; false: disconnected */ + uint8_t port; /* Hub port index */ + uint8_t dev_addr; /* device address */ + uint8_t speed; /* device speed */ + uint8_t depth; /* distance from root hub */ + uint8_t route; /* route string */ + uint8_t slot_id; /* slot id */ + struct usb_device_descriptor device_desc; + struct usbh_configuration config; + const char *iManufacturer; + const char *iProduct; + const char *iSerialNumber; + uint8_t *raw_config_desc; + struct usb_setup_packet *setup; + struct usbh_hub *parent; + struct usbh_hub *self; /* if this hubport is a hub */ + struct usbh_bus *bus; + struct usb_endpoint_descriptor ep0; + struct usbh_urb ep0_urb; + usb_osal_mutex_t mutex; + }; + +hub Structure +"""""""""""""""""""""""""""""""""""" + +.. code-block:: C + + struct usbh_hub { + bool connected; + bool is_roothub; + uint8_t index; + uint8_t hub_addr; + uint8_t speed; + uint8_t nports; + uint8_t powerdelay; + uint8_t tt_think; + bool ismtt; + struct usb_hub_descriptor hub_desc; /* USB 2.0 only */ + struct usb_hub_ss_descriptor hub_ss_desc; /* USB 3.0 only */ + struct usbh_hubport child[CONFIG_USBHOST_MAX_EHPORTS]; + struct usbh_hubport *parent; + struct usbh_bus *bus; + struct usb_endpoint_descriptor *intin; + struct usbh_urb intin_urb; + uint8_t *int_buffer; + struct usb_osal_timer *int_timer; + }; + +usbh_initialize +"""""""""""""""""""""""""""""""""""" + +``usbh_initialize`` is used to initialize the USB host protocol stack, including: initializing the USB host controller, creating roothub device, creating hub detection thread. + +.. code-block:: C + + int usbh_initialize(uint8_t busid, uint32_t reg_base, usbh_event_handler_t event_handler); + +- **busid** bus id, starting from 0, cannot exceed `CONFIG_USBHOST_MAX_BUS` +- **reg_base** hcd register base address +- **event_handler** host event callback function, can be NULL +- **return** 0 indicates normal, other values indicate error + +usbh_find_class_instance +"""""""""""""""""""""""""""""""""""" + +``usbh_find_class_instance`` finds the corresponding class structure handle based on the registered class name. + +.. code-block:: C + + void *usbh_find_class_instance(const char *devname); + +- **devname** class name +- **return** class structure handle + +lsusb +"""""""""""""""""""""""""""""""""""" + +``lsusb`` is used to view and operate device information on the hub. Requires shell plugin to use. + +.. code-block:: C + + int lsusb(int argc, char **argv); + +SERIAL +----------------- + +usbh_serial_open +"""""""""""""""""""""""""""""""""""" + +``usbh_serial_open`` opens a serial device according to the path. + +.. code-block:: C + + struct usbh_serial *usbh_serial_open(const char *devname, uint32_t open_flags); + +- **devname** serial path +- **open_flags** open flags, refer to `USBH_SERIAL_OFLAG_*` definitions +- **return** serial structure handle + +usbh_serial_close +"""""""""""""""""""""""""""""""""""" + +``usbh_serial_close`` closes the serial device. + +.. code-block:: C + + void usbh_serial_close(struct usbh_serial *serial); + +- **serial** serial structure handle + +usbh_serial_control +"""""""""""""""""""""""""""""""""""" + +``usbh_serial_control`` configures the serial port. + +.. code-block:: C + + int usbh_serial_control(struct usbh_serial *serial, int cmd, void *arg); + +- **serial** serial structure handle +- **cmd** control command, refer to `USBH_SERIAL_CMD_*` definitions +- **arg** control parameter pointer +- **return** 0 indicates normal, other values indicate error + +usbh_serial_write +"""""""""""""""""""""""""""""""""""" + +``usbh_serial_write`` writes data to the serial port. + +.. code-block:: C + + int usbh_serial_write(struct usbh_serial *serial, const void *buffer, uint32_t buflen); + +- **serial** serial structure handle +- **buffer** data buffer pointer +- **buflen** length of data to write +- **return** actual length of data written or error code + +.. note:: If CONFIG_USB_DCACHE_ENABLE is not enabled, buffer needs to be in nocache area, otherwise it needs to be aligned to CONFIG_USB_ALIGN_SIZE area. + +usbh_serial_read +"""""""""""""""""""""""""""""""""""" + +``usbh_serial_read`` reads data from the serial port. **If baud rate is not set, this API is not allowed to be used. After setting baud rate, rx reception will be enabled internally and data will be written to ringbuf**. + +.. code-block:: C + + int usbh_serial_read(struct usbh_serial *serial, void *buffer, uint32_t buflen); + +- **serial** serial structure handle +- **buffer** data buffer pointer +- **buflen** maximum length of data to read +- **return** actual length of data read or error code + +.. note:: Since ringbuffer is used internally, there are no restrictions on user buffer attributes. + +usbh_serial_cdc_write_async +"""""""""""""""""""""""""""""""""""" + +``usbh_serial_cdc_write_async`` asynchronously writes data to the serial port. **If baud rate is set, this API is not allowed to be used**. + +.. code-block:: C + + int usbh_serial_cdc_write_async(struct usbh_serial *serial, uint8_t *buffer, uint32_t buflen, usbh_complete_callback_t complete, void *arg); + +- **serial** serial structure handle +- **buffer** data buffer pointer +- **buflen** length of data to send +- **complete** data write completion callback function +- **arg** callback function parameter +- **return** 0 indicates normal, other values indicate error + +.. note:: If CONFIG_USB_DCACHE_ENABLE is not enabled, buffer needs to be in nocache area, otherwise it needs to be aligned to CONFIG_USB_ALIGN_SIZE area. + +usbh_serial_cdc_read_async +"""""""""""""""""""""""""""""""""""" + +``usbh_serial_cdc_read_async`` asynchronously reads data from the serial port. **If baud rate is set, this API is not allowed to be used. After setting baud rate, rx reception will be enabled internally and data will be written to ringbuf**. + +.. code-block:: C + + int usbh_serial_cdc_read_async(struct usbh_serial *serial, uint8_t *buffer, uint32_t buflen, usbh_complete_callback_t complete, void *arg); + +- **serial** serial structure handle +- **buffer** data buffer pointer +- **buflen** maximum length of data to read, up to 16K at a time. Must be a multiple of wMaxPacketSize +- **complete** data read completion callback function +- **arg** callback function parameter +- **return** 0 indicates normal, other values indicate error + +.. note:: If CONFIG_USB_DCACHE_ENABLE is not enabled, buffer needs to be in nocache area, otherwise it needs to be aligned to CONFIG_USB_ALIGN_SIZE area. + +HID +----------------- + +MSC +----------------- + +usbh_msc_scsi_init +"""""""""""""""""""""""""""""""""""" + +``usbh_msc_scsi_init`` initializes msc scsi device. Gets MSC status and capacity information. + +.. code-block:: C + + int usbh_msc_scsi_init(struct usbh_msc *msc_class); + +- **msc_class** msc structure handle +- **return** 0 indicates normal, other values indicate error + +usbh_msc_scsi_write10 +"""""""""""""""""""""""""""""""""""" + +``usbh_msc_scsi_write10`` writes data to msc device. + +.. code-block:: C + + int usbh_msc_scsi_write10(struct usbh_msc *msc_class, uint32_t start_sector, const uint8_t *buffer, uint32_t nsectors); + +- **msc_class** msc structure handle +- **start_sector** starting sector +- **buffer** data buffer pointer +- **nsectors** number of sectors to write +- **return** returns 0 for normal, other values indicate error + +usbh_msc_scsi_read10 +"""""""""""""""""""""""""""""""""""" + +``usbh_msc_scsi_read10`` reads data from msc device. + +.. code-block:: C + + int usbh_msc_scsi_read10(struct usbh_msc *msc_class, uint32_t start_sector, uint8_t *buffer, uint32_t nsectors); + +- **msc_class** msc structure handle +- **start_sector** starting sector +- **buffer** data buffer pointer +- **nsectors** number of sectors to read +- **return** returns 0 for normal, other values indicate error + +NETWORK +----------------- + +Already integrated with lwIP protocol stack or other network protocol stacks, use socket API.
\ No newline at end of file |