diff options
| -rw-r--r-- | include/driver/usbh_device_driver.h | 98 | ||||
| -rw-r--r-- | include/usbh_driver_ac_midi.h | 17 | ||||
| -rw-r--r-- | include/usbh_driver_gp_xbox.h | 5 | ||||
| -rw-r--r-- | include/usbh_driver_hid_mouse.h | 9 | ||||
| -rw-r--r-- | include/usbh_driver_hub.h | 3 | ||||
| -rw-r--r-- | include/usbh_hubbed.h | 53 | ||||
| -rw-r--r-- | src/usbh_hubbed.c | 6 |
7 files changed, 171 insertions, 20 deletions
diff --git a/include/driver/usbh_device_driver.h b/include/driver/usbh_device_driver.h index 3a4fbe3..2839a17 100644 --- a/include/driver/usbh_device_driver.h +++ b/include/driver/usbh_device_driver.h @@ -56,20 +56,49 @@ enum USBH_POLL_STATUS { USBH_POLL_STATUS_DEVICE_DISCONNECTED }; +/** + * @brief The _usbh_device struct + * + * This represents exactly one connected device. + */ struct _usbh_device { + /// max packet size for control endpoint(0) uint16_t packet_size_max0; + + /// Device's address int8_t address; - enum USBH_SPEED speed; // (USBH_SPEED_*) - uint8_t state; // for enumeration purposes + + /// @see USBH_SPEED + enum USBH_SPEED speed; + + /// state used for enumeration purposes + uint8_t state; + + /// toggle bit uint8_t toggle0; + + /** + * @brief drv - device driver used for this connected device + */ + const usbh_dev_driver_t *drv; + /** + * @brief drvdata - device driver's private data + */ void *drvdata; + + /** + * @brief lld - pointer to a low-level driver's instance + */ const void *lld; }; typedef struct _usbh_device usbh_device_t; struct _usbh_packet_callback_data { + /// status - it is used for reporting of the errors enum USBH_PACKET_CALLBACK_STATUS status; + + /// count of bytes that has been actually transferred uint32_t transferred_length; }; typedef struct _usbh_packet_callback_data usbh_packet_callback_data_t; @@ -77,27 +106,76 @@ typedef struct _usbh_packet_callback_data usbh_packet_callback_data_t; typedef void (*usbh_packet_callback_t)(usbh_device_t *dev, usbh_packet_callback_data_t status); struct _usbh_packet { - void *data; // Pointer to data - uint16_t datalen; // Data length 0..1023 - int8_t address; // Device address - uint8_t endpoint_type; // Endpoint type (see USBH_EPTYP_*) - uint8_t endpoint_address; // Endpoint number 0..15 - uint16_t endpoint_size_max; // Max packet size for an endpoint - enum USBH_SPEED speed; // (USBH_SPEED_*) + /// pointer to data + void *data; + + /// length of the data (up to 1023) + uint16_t datalen; + + /// Device's address + int8_t address; + + /// Endpoint type (see USBH_ENDPOINT_TYPE_*) + uint8_t endpoint_type; + + /// Endpoint number 0..15 + uint8_t endpoint_address; + + /// Max packet size for an endpoint + uint16_t endpoint_size_max; + + /// @see USBH_SPEED + enum USBH_SPEED speed; uint8_t *toggle; + + /** + * @brief callback this will be called when the packet is finished - either successfuly or not. + */ usbh_packet_callback_t callback; + + /** + * @brief callback_arg argument passed into callback + * + * Low level driver is not allowed to alter the data pointed by callback_arg + */ void *callback_arg; }; typedef struct _usbh_packet usbh_packet_t; struct _usbh_driver { + /** + * @brief init initialization routine of the low-level driver + * + * + * This function is called during the initialization of the library(@see usbh_init()) + */ void (*init)(void *drvdata); + + /** + * write - perform a write to a device (@see usbh_packet_t) + */ void (*write)(void *drvdata, const usbh_packet_t *packet); + + /** + * @brief read - perform a read from a device (@see usbh_packet_t) + */ void (*read)(void *drvdata, usbh_packet_t *packet); + + /** + * @brief this is called as a part of @ref usbh_poll() routine + */ enum USBH_POLL_STATUS (*poll)(void *drvdata, uint32_t time_curr_us); - // Pointer to Low-level driver data + /** + * @brief speed of the low-level bus + */ enum USBH_SPEED (*root_speed)(void *drvdata); + + /** + * @brief Pointer to Low-level driver data + * + * Data pointed by this pointer should not be altered by the logic other from low-level driver's logic + */ void *driver_data; }; typedef struct _usbh_driver usbh_driver_t; diff --git a/include/usbh_driver_ac_midi.h b/include/usbh_driver_ac_midi.h index 7b006a9..0993589 100644 --- a/include/usbh_driver_ac_midi.h +++ b/include/usbh_driver_ac_midi.h @@ -36,9 +36,24 @@ struct _midi_config { }; typedef struct _midi_config midi_config_t; -typedef void (*midi_write_callback_t)(uint8_t); +/** + * @param bytes_written count of bytes that were actually written + */ +typedef void (*midi_write_callback_t)(uint8_t bytes_written); +/** + * @brief midi_driver_init initialization routine - this will initialize internal structures of this device driver + * @param config + */ void midi_driver_init(const midi_config_t *config); + +/** + * @brief usbh_midi_write + * @param device_id + * @param data + * @param length + * @param callback this is called when the write call finishes + */ void usbh_midi_write(uint8_t device_id, const void *data, uint32_t length, midi_write_callback_t callback); extern const usbh_dev_driver_t usbh_midi_driver; diff --git a/include/usbh_driver_gp_xbox.h b/include/usbh_driver_gp_xbox.h index 8080f30..90d0ca1 100644 --- a/include/usbh_driver_gp_xbox.h +++ b/include/usbh_driver_gp_xbox.h @@ -64,6 +64,11 @@ struct _gp_xbox_config { }; typedef struct _gp_xbox_config gp_xbox_config_t; + +/** + * @brief gp_xbox_driver_init initialization routine - this will initialize internal structures of this device driver + * @param config + */ void gp_xbox_driver_init(const gp_xbox_config_t *config); extern const usbh_dev_driver_t usbh_gp_xbox_driver; diff --git a/include/usbh_driver_hid_mouse.h b/include/usbh_driver_hid_mouse.h index c12fed4..de7707c 100644 --- a/include/usbh_driver_hid_mouse.h +++ b/include/usbh_driver_hid_mouse.h @@ -30,10 +30,19 @@ BEGIN_DECLS struct _hid_mouse_config { + /** + * @brief this is called when some data is read when polling the device + * @param device_id + * @param data pointer to the data (only 4 bytes are valid!) + */ void (*mouse_in_message_handler)(uint8_t device_id, const uint8_t *data); }; typedef struct _hid_mouse_config hid_mouse_config_t; +/** + * @brief hid_mouse_driver_init initialization routine - this will initialize internal structures of this device driver + * @param config + */ void hid_mouse_driver_init(const hid_mouse_config_t *config); extern const usbh_dev_driver_t usbh_hid_mouse_driver; diff --git a/include/usbh_driver_hub.h b/include/usbh_driver_hub.h index cda1463..8555f79 100644 --- a/include/usbh_driver_hub.h +++ b/include/usbh_driver_hub.h @@ -27,6 +27,9 @@ BEGIN_DECLS
+/**
+ * @brief hub_driver_init initialization routine - this will initialize internal structures of this device driver
+ */
void hub_driver_init(void);
extern const usbh_dev_driver_t usbh_hub_driver;
diff --git a/include/usbh_hubbed.h b/include/usbh_hubbed.h index f99108d..ca4a489 100644 --- a/include/usbh_hubbed.h +++ b/include/usbh_hubbed.h @@ -40,7 +40,7 @@ BEGIN_DECLS
-// set to -1 to unused items
+/// set to -1 for unused items ("don't care" functionality) @see find_driver()
struct _usbh_dev_driver_info {
int32_t deviceClass;
int32_t deviceSubClass;
@@ -54,22 +54,63 @@ struct _usbh_dev_driver_info { typedef struct _usbh_dev_driver_info usbh_dev_driver_info_t;
struct _usbh_dev_driver {
+ /**
+ * @brief init is initialization routine of the device driver
+ *
+ * This function is called during the initialization of the device driver
+ */
void *(*init)(void *usbh_dev);
- bool (*analyze_descriptor)(void *drv, void *descriptor);
+
+ /**
+ * @brief analyze descriptor
+ * @param[in/out] drvdata is the device driver's private data
+ * @param[in] descriptor is the pointer to the descriptor that should
+ * be parsed in order to prepare driver to be loaded
+ *
+ * @retval true when the enumeration is complete and the driver is ready to be used
+ * @retval false when the device driver is not ready to be used
+ *
+ * This should be used for getting correct endpoint numbers, getting maximum sizes of endpoints.
+ * Should return true, when no more data is needed.
+ *
+ */
+ bool (*analyze_descriptor)(void *drvdata, void *descriptor);
+
+ /**
+ * @brief poll method is called periodically by the library core (@see usbh_poll())
+ * @param[in/out] drvdata is the device driver's private data
+ * @param[in] time_curr_us current timestamp in microseconds
+ */
void (*poll)(void *drvdata, uint32_t time_curr_us);
+
+ /**
+ * @brief unloads the device driver
+ * @param[in/out] drvdata is the device driver's private data
+ *
+ * This should free any data associated with this device
+ */
void (*remove)(void *drvdata);
+
+ /**
+ * @brief info - compatibility information about the driver. It is used by the core during device enumeration (@see find_driver())
+ */
const usbh_dev_driver_info_t * const info;
};
typedef struct _usbh_dev_driver usbh_dev_driver_t;
-void usbh_init(const void *drivers[], const usbh_dev_driver_t * const device_drivers[]);
+/**
+ * @brief usbh_init
+ * @param low_level_drivers list of the low level drivers to be used by this library
+ * @param device_drivers list of the device drivers that could be used with attached devices
+ */
+void usbh_init(const void *low_level_drivers[], const usbh_dev_driver_t * const device_drivers[]);
/**
- * \brief usbh_poll
- * \param time_curr_us - use monotically rising time
+ * @brief usbh_poll
+ * @param time_curr_us - use monotically rising time
*
* time_curr_us:
- * * can overflow, in time of this writing, after 1s)
+ * * can overflow, in time of this writing, after 1s
* * unit is microseconds
*/
void usbh_poll(uint32_t time_curr_us);
diff --git a/src/usbh_hubbed.c b/src/usbh_hubbed.c index b631263..7ffc83d 100644 --- a/src/usbh_hubbed.c +++ b/src/usbh_hubbed.c @@ -163,13 +163,13 @@ static void device_register(void *descriptors, uint16_t descriptors_len, usbh_de LOG_PRINTF("Device NOT Initialized\n"); } -void usbh_init(const void *drivers_lld[], const usbh_dev_driver_t * const device_drivers[]) +void usbh_init(const void *low_level_drivers[], const usbh_dev_driver_t * const device_drivers[]) { - if (!drivers_lld) { + if (!low_level_drivers) { return; } - usbh_data.lld_drivers = (const usbh_driver_t **)drivers_lld; + usbh_data.lld_drivers = (const usbh_driver_t **)low_level_drivers; usbh_data.dev_drivers = device_drivers; // TODO: init structures |