path: root/docs/en/api/api_host.rst

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.