PERFORCE change 136404 for review
Hans Petter Selasky
hselasky at FreeBSD.org
Fri Feb 29 19:47:40 UTC 2008
http://perforce.freebsd.org/chv.cgi?CH=136404
Change 136404 by hselasky at hselasky_laptop001 on 2008/02/28 07:52:34
Add more documentation to "usb_subr.h".
Affected files ...
.. //depot/projects/usb/src/sys/dev/usb/usb_subr.h#98 edit
Differences ...
==== //depot/projects/usb/src/sys/dev/usb/usb_subr.h#98 (text+ko) ====
@@ -38,10 +38,15 @@
#ifndef _USB_SUBR_H_
#define _USB_SUBR_H_
+/*
+ * The "USBD_STATUS" macro defines all the USB error codes.
+ * "USBD_ERR_NORMAL_COMPLETION" is not an error code. The reason all
+ * the error codes have been put inside a macro is so that the
+ * definition can be reused at various places in the code.
+ */
#define USBD_STATUS_DESC(enum,value) #enum
#define USBD_STATUS(m)\
-m(USBD_ERR_NORMAL_COMPLETION,=0 /* must be zero*/)\
-/* errors */\
+m(USBD_ERR_NORMAL_COMPLETION,)\
m(USBD_ERR_PENDING_REQUESTS,)\
m(USBD_ERR_NOT_STARTED,)\
m(USBD_ERR_INVAL,)\
@@ -71,14 +76,31 @@
m(USBD_ERR_NO_INTR_THREAD,)\
/**/
+/*
+ * The MAKE_ENUM macro will transform the USBD_STATUS macro into
+ * enums.
+ */
MAKE_ENUM(USBD_STATUS,
N_USBD_STATUS);
+/*
+ * The following macro will return the current state of an USB
+ * transfer like defined by the "USBD_ST_XXX" enums.
+ */
#define USBD_GET_STATE(xfer) ((xfer)->usb_state)
+
+/*
+ * The following macro will tell if an USB transfer is currently
+ * receiving or transferring data.
+ */
#define USBD_GET_DATA_ISREAD(xfer) (((xfer)->flags_int.usb_mode == \
USB_MODE_DEVICE) ? ((xfer->endpoint & UE_DIR_IN) ? 0 : 1) : \
((xfer->endpoint & UE_DIR_IN) ? 1 : 0))
+/*
+ * The following macro will return the previous element of a singly
+ * linked list.
+ */
#undef LIST_PREV
#define LIST_PREV(head,elm,field) \
(((elm) == LIST_FIRST(head)) ? ((__typeof(elm))0) : \
@@ -93,6 +115,8 @@
USBD_ST_ERROR,
};
+/* prototypes */
+
struct usbd_xfer;
struct usbd_pipe;
struct usbd_bus;
@@ -140,7 +164,7 @@
USBD_STD_ROOT_TR_PRE_CALLBACK,
};
-/* USB contexts */
+/* Definition of USB contexts */
enum {
USBD_CONTEXT_UNDEFINED,
@@ -149,6 +173,10 @@
USBD_CONTEXT_CALLBACK,
};
+/*
+ * The following structure is used when generating USB descriptors
+ * from USB templates.
+ */
struct usbd_temp_setup {
void *buf;
uint32_t size;
@@ -161,6 +189,10 @@
usbd_status_t err;
};
+/*
+ * The following structure is used to define all the USB BUS
+ * callbacks.
+ */
struct usbd_bus_methods {
/* USB Device and Host mode - Mandatory */
@@ -186,6 +218,10 @@
void (*vbus_interrupt) (struct usbd_bus *, uint8_t is_on);
};
+/*
+ * The following structure is used to define all the USB pipe
+ * callbacks.
+ */
struct usbd_pipe_methods {
/* USB Device and Host mode: */
@@ -196,6 +232,9 @@
void (*start) (struct usbd_xfer *xfer);
};
+/*
+ * The following structure defines an USB port.
+ */
struct usbd_port {
uint8_t restartcnt;
#define USBD_RESTART_MAX 5
@@ -204,12 +243,20 @@
uint8_t unused:7;
};
+/*
+ * The following structure defines how many bytes are
+ * left in an 1ms USB time slot.
+ */
struct usbd_fs_isoc_schedule {
uint16_t total_bytes;
uint8_t frame_bytes;
uint8_t frame_slot;
};
+/*
+ * The following structure is used to keep the state of a standard
+ * root transfer.
+ */
struct usbd_std_root_transfer {
usb_device_request_t req;
struct usbd_xfer *xfer;
@@ -219,6 +266,9 @@
usbd_status_t err;
};
+/*
+ * The following structure defines an USB HUB.
+ */
struct usbd_hub {
struct usbd_fs_isoc_schedule fs_isoc_schedule[USB_ISOC_TIME_MAX];
struct usbd_device *hubudev; /* the HUB device */
@@ -231,17 +281,30 @@
struct usbd_port ports[0];
};
+/*
+ * The following structure defines physical and non kernel virtual
+ * address of a memory page having size USB_PAGE_SIZE.
+ */
struct usbd_page {
bus_size_t physaddr;
void *buffer; /* non Kernel Virtual Address */
};
+/*
+ * The following structure is used when needing the kernel virtual
+ * pointer and the physical address belonging to an offset in an USB
+ * page cache.
+ */
struct usbd_page_search {
void *buffer;
bus_size_t physaddr;
uint32_t length;
};
+/*
+ * The following structure is used to keep information about a DMA
+ * memory allocation.
+ */
struct usbd_page_cache {
#ifdef __FreeBSD__
@@ -261,11 +324,16 @@
#endif
uint32_t page_offset_buf;
uint32_t page_offset_end;
- uint8_t isread:1;
+ uint8_t isread:1; /* set if we are currently reading
+ * from the memory. Else write. */
uint8_t ismultiseg:1; /* set if we can have multiple
* segments */
};
+/*
+ * The following structure is used when setting up an array of USB
+ * transfers.
+ */
struct usbd_setup_params {
struct usbd_dma_tag *dma_tag_p;
struct usbd_page *dma_page_ptr;
@@ -293,6 +361,10 @@
usbd_status_t err;
};
+/*
+ * The following structure keeps information about what a hardware USB
+ * endpoint supports.
+ */
struct usbd_hw_ep_profile {
uint16_t max_frame_size;
uint8_t is_simplex:1;
@@ -305,6 +377,10 @@
uint8_t support_out:1; /* OUT-token is supported */
};
+/*
+ * The following structure is used when trying to allocate hardware
+ * endpoints for an USB configuration in USB device side mode.
+ */
struct usbd_sw_ep_scratch {
const struct usbd_hw_ep_profile *pf;
uint16_t max_frame_size;
@@ -315,6 +391,10 @@
uint8_t needs_out:1;
};
+/*
+ * The following structure is used when trying to allocate hardware
+ * endpoints for an USB configuration in USB device side mode.
+ */
struct usbd_hw_ep_scratch {
struct usbd_sw_ep_scratch ep[USB_MAX_ENDPOINTS];
struct usbd_sw_ep_scratch *ep_max;
@@ -325,6 +405,9 @@
uint8_t bmInAlloc[(USB_MAX_ENDPOINTS + 15) / 16];
};
+/*
+ * The following structure keeps an USB DMA tag.
+ */
struct usbd_dma_tag {
#ifdef __NetBSD__
bus_dma_segment_t *p_seg;
@@ -344,8 +427,12 @@
#define USB_BUS_EXPLORE_STOP 2
#define USB_BUS_EXPLORE_SYNC 3
+/**/
+
#define USB_BUS_DMA_TAG_MAX 8
+/* The following structure defines the explore state of an USB BUS. */
+
struct usbd_bus_needs {
uint8_t sync:1; /* Set if explore thread sync is
* needed. */
@@ -358,9 +445,14 @@
uint8_t unused:3;
};
+/*
+ * The following structure defines an USB BUS. There is one USB BUS
+ * for every Host or Device controller.
+ */
struct usbd_bus {
struct usb_device_stats stats;
- struct mtx mtx;
+ struct mtx mtx; /* this mutex protects the USB
+ * hardware */
LIST_HEAD(, usbd_xfer) intr_list_head; /* driver interrupt list */
device_t bdev; /* filled by HC driver */
@@ -387,6 +479,8 @@
uint8_t usb_clone_count;
#define USB_BUS_MAX_CLONES 128
+/* Definition of USB revisions */
+
#define USBREV_UNKNOWN 0
#define USBREV_PRE_1_0 1
#define USBREV_1_0 2
@@ -397,12 +491,19 @@
uint8_t usb_name[32];
};
+/*
+ * The following structure defines an USB interface.
+ */
struct usbd_interface {
usb_interface_descriptor_t *idesc;
device_t subdev;
uint8_t alt_index;
};
+/*
+ * The following structure defines an USB pipe which is equal to an
+ * USB endpoint.
+ */
struct usbd_pipe {
LIST_HEAD(, usbd_xfer) list_head;
@@ -418,6 +519,9 @@
uint8_t iface_index; /* not used by "default pipe" */
};
+/*
+ * The following structure defines the USB device flags.
+ */
struct usbd_device_flags {
uint8_t usb_mode:1; /* USB mode (see USB_MODE_XXX) */
uint8_t self_powered:1; /* set if USB device is self powered */
@@ -429,6 +533,10 @@
uint8_t unused:2;
};
+/*
+ * The following structure defines an USB device. There exists one of
+ * these structures for every USB device.
+ */
struct usbd_device {
struct sx default_sx[1];
struct mtx default_mtx[1];
@@ -444,7 +552,7 @@
#error "USB_MAX_ENDPOINTS must be increased!"
#endif
- struct usbd_bus *bus; /* our controller */
+ struct usbd_bus *bus; /* our USB BUS */
device_t parent_dev; /* parent device */
struct usbd_device *parent_hub;
const struct usbd_quirks *quirks; /* device quirks, always set */
@@ -502,6 +610,9 @@
} scratch[1];
};
+/*
+ * The following structure defines a set of USB transfer flags.
+ */
struct usbd_xfer_flags {
uint8_t force_short_xfer:1; /* force a short transmit transfer
* last */
@@ -521,13 +632,18 @@
* before starting this transfer! */
};
+/*
+ * The following structure defines a set of internal USB transfer
+ * flags.
+ */
struct usbd_xfer_flags_int {
uint16_t control_rem; /* remainder in bytes */
- uint8_t open:1;
- uint8_t recursed_1:1;
- uint8_t recursed_2:1;
- uint8_t transferring:1;
+ uint8_t open:1; /* set if USB pipe has been opened */
+ uint8_t recursed_1:1; /* see "usbd_callback_wrapper()" */
+ uint8_t recursed_2:1; /* see "usbd_callback_wrapper()" */
+ uint8_t transferring:1; /* set if an USB transfer is in
+ * progress */
uint8_t did_dma_delay:1; /* set if we waited for HW DMA */
uint8_t draining:1; /* set if we are draining an USB
* transfer */
@@ -551,6 +667,10 @@
uint8_t curr_dma_set:1; /* used by USB HC/DC driver */
};
+/*
+ * The following structure defines the symmetric part of an USB config
+ * structure.
+ */
struct usbd_config_sub {
usbd_callback_t *callback; /* USB transfer callback */
uint32_t bufsize; /* total pipe buffer size in bytes */
@@ -561,6 +681,10 @@
struct usbd_xfer_flags flags; /* transfer flags */
};
+/*
+ * The following structure define an USB configuration, that basically
+ * is used when setting up an USB transfer.
+ */
struct usbd_config {
struct usbd_config_sub mh; /* parameters for USB_MODE_HOST */
struct usbd_config_sub md; /* parameters for USB_MODE_DEVICE */
@@ -571,6 +695,9 @@
uint8_t if_index; /* "ifaces" index to use */
};
+/*
+ * The following structure defines an USB transfer.
+ */
struct usbd_xfer {
struct usb_callout timeout_handle;
struct usbd_page_cache *buf_fixup; /* fixup buffer(s) */
@@ -580,7 +707,7 @@
LIST_ENTRY(usbd_xfer) dma_list;/* used by BUS-DMA */
struct usbd_page *dma_page_ptr;
- struct usbd_pipe *pipe;
+ struct usbd_pipe *pipe; /* our USB pipe */
struct usbd_device *udev;
struct mtx *priv_mtx; /* cannot be changed during operation */
struct mtx *usb_mtx; /* used by HC driver */
@@ -590,12 +717,15 @@
* The value of "usb_thread" is used to tell who has reserved
* the USB transfer for callback:
*
- * NULL: - "usbd_transfer_start"
+ * case "NULL":
+ * - "usbd_transfer_start"
* - "usbd_transfer_stop"
* - "{ehci,ohci,uhci}_interrupt"
* - "{ehci,ohci,uhci}_timeout"
- * xfer->usb_root:
+ *
+ * case "xfer->usb_root":
* - "usbd_callback_intr_td"
+ *
* Else:
* - the given thread in case of polling
*/
@@ -605,8 +735,8 @@
void *td_transfer_first; /* used by HC driver */
void *td_transfer_last; /* used by HC driver */
void *td_transfer_cache; /* used by HC driver */
- void *priv_sc;
- void *priv_fifo;
+ void *priv_sc; /* device driver data pointer 1 */
+ void *priv_fifo; /* device driver data pointer 2 */
void *local_buffer;
uint32_t *frlengths;
struct usbd_page_cache *frbuffers;
@@ -630,8 +760,8 @@
uint16_t isoc_time_complete; /* in ms */
uint16_t interval; /* milliseconds */
- uint8_t address;
- uint8_t endpoint;
+ uint8_t address; /* physical USB address */
+ uint8_t endpoint; /* physical USB endpoint */
uint8_t max_packet_count;
uint8_t usb_smask;
uint8_t usb_cmask;
@@ -644,6 +774,11 @@
struct usbd_xfer_flags_int flags_int;
};
+/*
+ * The following structure is used to keep information about memory
+ * that should be automatically freed at the moment all USB transfers
+ * have been freed.
+ */
struct usbd_memory_info {
LIST_HEAD(, usbd_xfer) dma_head;
LIST_HEAD(, usbd_xfer) done_head;
@@ -672,6 +807,10 @@
uint8_t done_sleep; /* set if done thread is sleeping */
};
+/*
+ * The following structure defines a minimum re-implementation of the
+ * mbuf system in the kernel.
+ */
struct usbd_mbuf {
uint8_t *cur_data_ptr;
uint8_t *min_data_ptr;
@@ -683,6 +822,10 @@
uint32_t last_packet:1;
};
+/*
+ * The following structure defines a minimum re-implementation of the
+ * ifqueue structure in the kernel.
+ */
struct usbd_ifqueue {
struct usbd_mbuf *ifq_head;
struct usbd_mbuf *ifq_tail;
@@ -732,7 +875,7 @@
} while (0)
/*------------------------------------------------------------------------*
- * structures used by the usbd config thread system
+ * structures used by the USB config thread system
*------------------------------------------------------------------------*/
struct usbd_config_td_softc;
struct usbd_config_td_cc;
@@ -740,6 +883,9 @@
typedef void (usbd_config_td_command_t)(struct usbd_config_td_softc *sc, struct usbd_config_td_cc *cc, uint16_t reference);
typedef void (usbd_config_td_end_of_commands_t)(struct usbd_config_td_softc *sc);
+/*
+ * The following structure defines an USB config thread.
+ */
struct usbd_config_td {
struct usbd_ifqueue cmd_free;
struct usbd_ifqueue cmd_used;
@@ -757,6 +903,10 @@
uint8_t flag_config_td_gone;
};
+/*
+ * The following structure defines a command that should be executed
+ * using the USB config thread system.
+ */
struct usbd_config_td_item {
usbd_config_td_command_t *command_func;
uint16_t command_ref;
@@ -768,11 +918,17 @@
struct usb_devno {
uint16_t ud_vendor;
uint16_t ud_product;
+
+ /*
+ * XXX this structure should be extended to also contain some
+ * flags --hps
+ */
} __packed;
-#define usb_lookup(tbl, vendor, product) usb_match_device \
- ((const struct usb_devno *)(tbl), (sizeof (tbl) / sizeof ((tbl)[0])), \
- sizeof ((tbl)[0]), (vendor), (product)) \
+#define usb_lookup(tbl, vendor, product) \
+ usb_match_device((const struct usb_devno *)(tbl), \
+ (sizeof(tbl) / sizeof((tbl)[0])), sizeof((tbl)[0]), \
+ (vendor), (product)) \
/**/
#define USB_PRODUCT_ANY 0xffff
@@ -813,11 +969,9 @@
#define UMATCH_NONE (ENXIO)
/*------------------------------------------------------------------------*
- * prototypes
+ * prototypes from "usb_subr.c"
*------------------------------------------------------------------------*/
-/* prototypes from usb_subr.c */
-
#ifdef __FreeBSD__
#if (__FreeBSD_version >= 700020)
#define device_get_dma_tag(dev) bus_get_dma_tag(dev)
@@ -828,7 +982,6 @@
typedef void (usbd_bus_mem_sub_cb_t)(struct usbd_bus *bus, struct usbd_page_cache *pc, struct usbd_page *pg, uint32_t size, uint32_t align);
typedef void (usbd_bus_mem_cb_t)(struct usbd_bus *bus, usbd_bus_mem_sub_cb_t *scb);
-
void usbd_devinfo(struct usbd_device *udev, char *dst_ptr, uint16_t dst_len);
const char *usbd_errstr(usbd_status_t err);
void usb_delay_ms(struct usbd_bus *bus, uint32_t ms);
@@ -895,7 +1048,9 @@
struct usbd_device *usbd_bus_port_get_device(struct usbd_bus *bus, struct usbd_port *up);
void usbd_bus_port_set_device(struct usbd_bus *bus, struct usbd_port *up, struct usbd_device *udev, uint8_t device_index);
-/* prototypes from usb.c */
+/*------------------------------------------------------------------------*
+ * prototypes from "usb.c"
+ *------------------------------------------------------------------------*/
#if 0
extern struct mtx usb_global_lock;
@@ -908,13 +1063,17 @@
void usb_needs_explore(struct usbd_bus *bus, uint8_t what);
void usb_needs_probe_and_attach(void);
-/* prototypes from usb_template.c */
+/*------------------------------------------------------------------------*
+ * prototypes from "usb_template.c"
+ *------------------------------------------------------------------------*/
void usbd_temp_get_desc(struct usbd_device *udev, usb_device_request_t *req, const void **pPtr, uint16_t *pLen);
usbd_status_t usbd_temp_setup(struct usbd_device *udev, const struct usb_temp_device_desc *tdd);
void usbd_temp_unsetup(struct usbd_device *udev);
-/* prototypes from usb_transfer.c */
+/*------------------------------------------------------------------------*
+ * prototypes from "usb_transfer.c"
+ *------------------------------------------------------------------------*/
#ifdef USB_DEBUG
void usbd_dump_iface(struct usbd_interface *iface);
@@ -959,7 +1118,9 @@
const struct usb_devno *usb_match_device(const struct usb_devno *tbl, uint32_t nentries, uint32_t size, uint16_t vendor, uint16_t product);
int32_t usbd_driver_load(struct module *mod, int32_t what, void *arg);
-/* prototypes from usb_requests.c */
+/*------------------------------------------------------------------------*
+ * prototypes from "usb_requests.c"
+ *------------------------------------------------------------------------*/
usbd_status_t usbreq_reset_port(struct usbd_device *udev, struct mtx *mtx, uint8_t port);
usbd_status_t usbreq_get_desc(struct usbd_device *udev, struct mtx *mtx, void *desc, uint16_t min_len, uint16_t max_len, uint16_t id, uint8_t type, uint8_t index, uint8_t retries);
@@ -1007,7 +1168,9 @@
#define USBD_MS_TO_TICKS(ms) \
(((uint32_t)((((uint32_t)(ms)) * ((uint32_t)(hz))) + 1023)) / 1024)
-/* prototypes from "usb_cdev.c" */
+/*------------------------------------------------------------------------*
+ * prototypes from "usb_cdev.c"
+ *------------------------------------------------------------------------*/
struct usb_cdev;
struct cdev;
More information about the p4-projects
mailing list