summaryrefslogtreecommitdiff
path: root/include
diff options
context:
space:
mode:
authorAmir Hammad <amir.hammad@hotmail.com>2016-07-08 23:21:37 +0200
committerAmir Hammad <amir.hammad@hotmail.com>2016-07-08 23:45:57 +0200
commit2c0f82a4f07fe35bc043f68b9f58b954a16ea689 (patch)
tree857bf067cf88fe1e4b8182020791a286173bfddd /include
parente61ed66174df0bf889586c757aa6a9d23d9401c0 (diff)
downloadsecure-hid-2c0f82a4f07fe35bc043f68b9f58b954a16ea689.tar.gz
secure-hid-2c0f82a4f07fe35bc043f68b9f58b954a16ea689.tar.bz2
secure-hid-2c0f82a4f07fe35bc043f68b9f58b954a16ea689.zip
documentation: add some basic documentation accross the headers
Signed-off-by: Amir Hammad <amir.hammad@hotmail.com>
Diffstat (limited to 'include')
-rw-r--r--include/driver/usbh_device_driver.h98
-rw-r--r--include/usbh_driver_ac_midi.h17
-rw-r--r--include/usbh_driver_gp_xbox.h5
-rw-r--r--include/usbh_driver_hid_mouse.h9
-rw-r--r--include/usbh_driver_hub.h3
-rw-r--r--include/usbh_hubbed.h53
6 files changed, 168 insertions, 17 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);