device/class/usbdev.h header reference
[Devices support library module]
The source code of this header can be browsed online.
Description [link]
See DRIVER_CLASS_USBDEV.
Members [link]
Types [link]
- typedef void *(dev_usbdev_alloc_t)(struct dev_usbdev_context_s *ctx, size_t size)
- enum dev_usbdev_cfg_e
- typedef [...] dev_usbdev_cfgrev_t
- struct dev_usbdev_config_s
- typedef error_t (dev_usbdev_config_t)(struct dev_usbdev_context_s *ctx, struct dev_usbdev_config_s *cfg)
- struct dev_usbdev_context_s
- struct dev_usbdev_driver_ops_s
- typedef struct usbdev_endpoint_s *(dev_usbdev_endpoint_t)(struct dev_usbdev_context_s *ctx, enum usb_endpoint_dir_e dir, uint8_t address)
- typedef [...] dev_usbdev_ep_addr_t
- typedef [...] dev_usbdev_ep_map_t
- enum dev_usbdev_event_e
- typedef void (dev_usbdev_free_t)(struct dev_usbdev_context_s *ctx, void *ptr)
- struct dev_usbdev_interface_cfg_s
- enum dev_usbdev_interface_e
- typedef error_t (dev_usbdev_request_t)(struct dev_usbdev_context_s *ctx, struct dev_usbdev_rq_s *tr)
- struct dev_usbdev_rq_s
- enum dev_usbdev_rq_type_e
- struct device_usbdev_s
- struct driver_usbdev_s
- struct usbdev_device_info_s
- struct usbdev_endpoint_s
- typedef const char *(usbdev_get_string_t)(const struct usbdev_service_s *service, uint8_t idx)
- struct usbdev_interface_default_s
- struct usbdev_interface_s
- typedef void (usbdev_replace_t)(const struct dev_usbdev_desc_iterator_s *it, const struct usb_descriptor_header_s *src, struct usb_descriptor_header_s *dst, size_t begin, size_t end)
- enum usbdev_service_cmd_type_e
- struct usbdev_service_descriptor_s
- struct usbdev_service_index_s
- typedef [...] * usbdev_service_item_t
- enum usbdev_service_req_type_e
- struct usbdev_service_rq_s
- struct usbdev_service_s
- enum dev_usbdev_ctrl_ep_state_e
- struct dev_usbdev_desc_iterator_s
Functions [link]
- error_t dev_res_get_usbdev_epmap(struct device_s *dev, struct usbdev_service_s *service)
- struct dev_usbdev_context_s * dev_usbdev_context_s_from_kr(void *x)
- enum usb_transfert_direction_e dev_usbdev_get_transfer_dir(struct dev_usbdev_rq_s *tr)
- void dev_usbdev_rq_done(struct dev_usbdev_rq_s *rq)
- struct dev_usbdev_rq_s * dev_usbdev_rq_from_kr(struct kroutine_s *kr)
- struct dev_usbdev_rq_s * dev_usbdev_rq_head(dev_request_queue_root_t *q)
- void dev_usbdev_rq_init(struct dev_usbdev_rq_s *rq, kroutine_exec_t *exec)
- void dev_usbdev_rq_init_immediate(struct dev_usbdev_rq_s *rq, kroutine_exec_t *exec)
- void dev_usbdev_rq_init_queue(struct dev_usbdev_rq_s *rq, kroutine_exec_t *exec, struct kroutine_queue_s *queue)
- void dev_usbdev_rq_init_seq(struct dev_usbdev_rq_s *rq, kroutine_exec_t *exec, struct kroutine_sequence_s *seq)
- struct dev_usbdev_rq_s * dev_usbdev_rq_pop(dev_request_queue_root_t *q)
- void dev_usbdev_rq_pushback(dev_request_queue_root_t *q, struct dev_usbdev_rq_s *rq)
- void dev_usbdev_rq_remove(dev_request_queue_root_t *q, struct dev_usbdev_rq_s *rq)
- struct dev_request_s * dev_usbdev_rq_s_base(struct dev_usbdev_rq_s *x)
- struct dev_usbdev_rq_s * dev_usbdev_rq_s_cast(struct dev_request_s *x)
- struct dev_usbdev_context_s * device_usbdev_context(const struct device_usbdev_s *x)
- struct device_accessor_s * device_usbdev_s_base(struct device_usbdev_s *x)
- struct device_usbdev_s * device_usbdev_s_cast(struct device_accessor_s *x)
- void usbdev_cdc_descriptor_replace(const struct dev_usbdev_desc_iterator_s *it, const struct usb_descriptor_header_s *src, struct usb_descriptor_header_s *dst, size_t begin, size_t end)
- void usbdev_descriptor_replace(const struct dev_usbdev_desc_iterator_s *it, const struct usb_descriptor_header_s *src, struct usb_descriptor_header_s *dst, size_t begin, size_t end)
- void * usbdev_stack_allocate(const struct device_usbdev_s *dev, size_t size)
- error_t usbdev_stack_cleanup(struct dev_usbdev_context_s *ctx)
- void usbdev_stack_config_done(struct dev_usbdev_context_s *ctx)
- void usbdev_stack_free(const struct device_usbdev_s *dev, void *ptr)
- uint8_t usbdev_stack_get_ep0_mps(struct dev_usbdev_context_s *ctx)
- uint8_t usbdev_stack_get_ep_addr(const struct usb_endpoint_descriptor_s *desc, dev_usbdev_ep_map_t mapi, dev_usbdev_ep_map_t mapo)
- error_t usbdev_stack_init(struct device_s *dev, struct dev_usbdev_context_s *ctx, uint16_t epi_msk, uint16_t epo_msk, const struct dev_usbdev_driver_ops_s *ops)
- error_t usbdev_stack_request(const struct device_usbdev_s *dev, struct usbdev_service_s *service, struct usbdev_service_rq_s *rq)
- void usbdev_stack_request_done(struct dev_usbdev_context_s *ctx, struct dev_usbdev_rq_s *tr)
- error_t usbdev_stack_service_register(const struct device_usbdev_s *dev, struct usbdev_service_s *service)
- error_t usbdev_stack_service_unregister(const struct device_usbdev_s *dev, struct usbdev_service_s *service)
- void usbdev_stack_set_device_info(const struct device_usbdev_s *dev, const struct usbdev_device_info_s *info)
- error_t usbdev_stack_transfer(const struct device_usbdev_s *dev, struct usbdev_service_s *service, struct dev_usbdev_rq_s *tr, const struct usb_endpoint_descriptor_s *desc)
Constants [link]
- const char dev_usbdev_ctrl_ep_state_e[]
- const char dev_usbdev_event_e[]
- const char dev_usbdev_rq_type_e[]
Macros [link]
Members detail [link]
#define DEV_STATIC_RES_USBDEV_EP_MAP(config_, mapin_, mapout_) [link]
This macro is declared in device/class/usbdev.h source file, line 911.
This macro specifies a USBDEV resource entry in a static device resources table declaration. The mapin and mapout parameters map local input and output endpoints of a service to endpoints of USB controller.
A service might owns one or several interfaces with alternate settings. Endpoint mapping can be different for each of this setting. The config specifies the altenate setting number associated to the mapin and mapout parameters. When no alternate setting is used in a service, the config parameter is set to 0.
Alternate declarations with same identifier: [1], [2].
Preprocessor condition: defined( CONFIG_DEVICE_USBDEV )
#define DEV_STATIC_RES_USBDEV_EP_MAP(config_, mapin_, mapout_) [link]
This macro is declared in device/class/usbdev.h source file, line 921.
Documentation from alternate declaration:
This macro specifies a USBDEV resource entry in a static device resources table declaration. The mapin and mapout parameters map local input and output endpoints of a service to endpoints of USB controller.
A service might owns one or several interfaces with alternate settings. Endpoint mapping can be different for each of this setting. The config specifies the altenate setting number associated to the mapin and mapout parameters. When no alternate setting is used in a service, the config parameter is set to 0.
Alternate declarations with same identifier: [1], [2].
Preprocessor condition: not defined( CONFIG_DEVICE_USBDEV )
#define DEV_USBDEV_ALLOC(n) [link]
This macro is declared in device/class/usbdev.h source file, line 379.
#define DEV_USBDEV_CONFIG(n) [link]
This macro is declared in device/class/usbdev.h source file, line 352.
#define DEV_USBDEV_ENDPOINT(n) [link]
This macro is declared in device/class/usbdev.h source file, line 409.
#define DEV_USBDEV_FREE(n) [link]
This macro is declared in device/class/usbdev.h source file, line 392.
#define DEV_USBDEV_REQUEST(n) [link]
This macro is declared in device/class/usbdev.h source file, line 171.
#define DRIVER_USBDEV_METHODS(prefix) [link]
This macro is declared in device/class/usbdev.h source file, line 425.
#define GCT_CONTAINER_ALGO_usbdev_service [link]
This macro is declared in device/class/usbdev.h source file, line 572.
#define USBDEV_ENDPOINT(...) [link]
This macro is declared in device/class/usbdev.h source file, line 724.
#define USBDEV_FOREACH_ENDPOINT(intf, mapin, mapout, ... /* loop body */) [link]
This macro is declared in device/class/usbdev.h source file, line 446.
#define USBDEV_FOREACH_INTERFACE(intf, ... /* loop body */ ) [link]
This macro is declared in device/class/usbdev.h source file, line 431.
#define USBDEV_GET_STRING(n) [link]
This macro is declared in device/class/usbdev.h source file, line 542.
This macro is provided by service to dynamically get strings.
#define USBDEV_INTERFACE(...) [link]
This macro is declared in device/class/usbdev.h source file, line 716.
#define USBDEV_INTERFACE_ALTERNATE(...) [link]
This macro is declared in device/class/usbdev.h source file, line 720.
#define USBDEV_REPLACE(n) [link]
This macro is declared in device/class/usbdev.h source file, line 532.
This macro is provided by service with some class specific descriptors. This function is used by stack when building global configuration descriptor to dynamically replace some fields of descriptor.
Buffer passed in dst contains a copy of src, and this macro should patch bytes between begin (included) and end (excluded) only. Others may be invalid.
src is the original constant descriptor, its address is the one from the descriptor array in service descriptor.
#define USBDEV_SERVICE_DESCRIPTOR(...) [link]
This macro is declared in device/class/usbdev.h source file, line 712.
#define __USBDEV_H__ [link]
This macro is declared in device/class/usbdev.h source file, line 30.
error_t dev_res_get_usbdev_epmap(struct device_s *dev, struct usbdev_service_s *service) [link]
This function is declared in device/class/usbdev.h source file, line 898.
This is available when CONFIG_DEVICE_USBDEV is defined.
typedef void *(dev_usbdev_alloc_t)(struct dev_usbdev_context_s *ctx, size_t size) [link]
This typedef is declared in device/class/usbdev.h source file, line 391.
USB device class allocate() function type. Allocate a buffer compliant with USB device controller. Most of USB device controller need special alignement or minimum size for receive or send buffer. Returns 0 when the required allocation failed otherwise returns a pointer on the buffer. Allocated size must always be multiple of the Maximum Packet Size of the endpoint for which the buffer is allocated.
enum dev_usbdev_cfg_e [link]
This enum is declared in device/class/usbdev.h source file, line 263.
| Identifier | Description |
|---|---|
| DEV_USBDEV_CONFIGURE | This is used either to configure endpoint 0 or when a SET CONFIGURATION command from host is received. Because some USB controllers have an internal RAM that must be allocated and partionned by driver for each endpoint, changing dynamically the size of an endpoint due to a DEV_USBDEV_CHANGE_INTERFACE command could lead to a complete reallocation of the whole memory and thus prevent other interfaces from working. If one or more alternate setting are used for an interface, it migth be attractive to known in advance these different settings to prevent a whole reallocation of the memory. That is why, the driver have access to all aternate settings of each interface during this operation. Parsing all settings of an interface and all the corresponding endpoints can be facilitated by USBDEV_FOREACH_INTERFACE and USBDEV_FOREACH_ENDPOINT macros |
| DEV_USBDEV_UNCONFIGURE | Unconfigure all endpoint except endpoint 0. Unconfigure operation is used when a set configuration or an event happen on the USB device. All controller endpoints except endpoint zero must be unconfigured in this case. When unconfiguring controller, all on-going transfer must be terminated with dev_usbdev_config_s::error field set to -EPIPE. dev_usbdev_rq_s::size field of on-going transfer might not be updated in this case. |
| DEV_USBDEV_SET_ADDRESS | Set controller address. This is used when a SET ADDRESS command from host is received. The usb device must not change its device address until after the status stage of this control transfer is completed successfully. However some controller need to configure the new address before sending the status stage. For this reason, this is called before sending status stage and it is the responsability of the driver to delay or not to the end of status stage the address configuration. |
| DEV_USBDEV_CHANGE_INTERFACE | Change configuration of an interface. This is used when SET INTERFACE command from host is received. This occurs when device has shown alternate settings for an interface during enumeration. The driver must unconfigure each endpoint that are not used anymore. This must be done neatly since no data of on-going transfer must be lost except on isochronous endpoints. The dev_usbdev_rq_s::size field of any on-going request must be updated an the request must be terminated with -EAGAIN error code. At this point, the new interface configuration can be set by the driver. During these two operations other interfaces must go on working normally. |
This typedef is declared in device/class/usbdev.h source file, line 71.
Endpoint configuration revision number
struct dev_usbdev_config_s [link]
This struct is declared in device/class/usbdev.h source file, line 332.
| Field | Description |
|---|---|
| error_t error; | |
| enum dev_usbdev_cfg_e type; | |
| union <anonymous> { | |
| struct dev_usbdev_interface_cfg_s * intf; | This is a list of interface. When used in conjunction with the DEV_USBDEV_CHANGE_INTERFACE, this list contains two entries. One with information about interface to disable and the other one with information about interface to enable. When used in conjunction with the DEV_USBDEV_CONFIGURE, this list of interface is NULL terminated and contains all interfaces of the configuration that must be enable. When NULL, endpoint 0 must be configured. |
| uint16_t addr; | |
| }; |
typedef error_t (dev_usbdev_config_t)(struct dev_usbdev_context_s *ctx, struct dev_usbdev_config_s *cfg) [link]
This typedef is declared in device/class/usbdev.h source file, line 375.
USB device class configure() function type. Perform several configuration on USB device controller.
When a configuration is posted on driver, if its processing is done immediately without differed interrupt, this function must return 0. If the configuration is processed later or if an interrupt must be waited to terminate the operation, this function must return -EAGAIN. In this case, when the configuration is terminated, the driver will have to call the usbdev_stack_config_done function. If an error is detected when posting a configuration, this function must return the associated error code.
If an event occurs during a configuration operation, it should not be stopped or cancelled and should be terminated normaly if possible. In any case, usbdev_stack_config_done must be called without error. Event will be reported later on the next request on endpoint 0.
If an configuration is not supported by a controller -ENOTSUP error must be returned.
struct dev_usbdev_context_s [link]
This struct is declared in device/class/usbdev.h source file, line 791.
This struct stucture hold the usb device stack context associated to an usb device controller. USB device controller driver usually allocate this structure in the device private context and perform its initialization by calling the dev_usbdev_context_init function.
| Field | Description |
|---|---|
| const struct dev_usbdev_driver_ops_s * ops; | |
| struct device_s * dev; | Accessor on usb device controller |
| const struct usbdev_device_info_s * devinfo; | |
| struct dev_usbdev_desc_iterator_s it; | |
| enum dev_usbdev_state_e state; | Device state |
| uint8_t service_cnt; | Number of services registerd on USB device |
| uint32_t service_state; | |
| usbdev_service_root_t service; | List of usb services |
| struct kroutine_s kr; | |
| uint32_t setup[2]; | Endpoint 0 setup packet |
| enum dev_usbdev_ctrl_ep_state_e ep0_state:8; | Endpoint 0 state |
| union <anonymous> { | |
| struct dev_usbdev_config_s cfg; | Configuration request for USB driver |
| struct dev_usbdev_rq_s tr; | Endpoint 0 transfer |
| }; | |
| uint8_t * data; | Endpoint buffer |
| bool_t halted; | |
| uint16_t epi_msk; | Controller endpoint mask |
| uint16_t epo_msk; | |
| uint8_t event; | Pending Bus event |
| uint8_t intf_cfg[CONFIG_USBDEV_MAX_INTERFACE_COUNT]; | |
| struct dev_usbdev_interface_cfg_s intf[CONFIG_USBDEV_MAX_INTERFACE_COUNT]; |
struct dev_usbdev_context_s * dev_usbdev_context_s_from_kr(void *x) [link]
This function is declared in device/class/usbdev.h source file, line 842.
const char dev_usbdev_ctrl_ep_state_e[] [link]
This constant is declared in ENUM_DESCRIPTOR function like macro expansion, line 1 in device/class/usbdev.h source file, line 749.
Alternate declarations with same identifier: [1], [2].
struct dev_usbdev_driver_ops_s [link]
This struct is declared in device/class/usbdev.h source file, line 480.
| Field | Description |
|---|---|
| dev_usbdev_request_t * f_transfer; | |
| dev_usbdev_config_t * f_config; | |
| dev_usbdev_alloc_t * f_alloc; | |
| dev_usbdev_free_t * f_free; | |
| dev_usbdev_endpoint_t * f_endpoint; |
typedef struct usbdev_endpoint_s *(dev_usbdev_endpoint_t)(struct dev_usbdev_context_s *ctx, enum usb_endpoint_dir_e dir, uint8_t address) [link]
This typedef is declared in device/class/usbdev.h source file, line 422.
USB device class endpoint() function type. Return endpoint structure of a specified endpoint allocated in the USB controller device private data. Each USB device controller specifies a number of endpoint that it is able to support in addition to endpoint 0. For each of these additional endpoints, it must allocate a struct usbdev_endpoint_s structure. Endpoint 0 must not be allocated by driver. Return NULL if the requested endpoint does not exist.
This typedef is declared in device/class/usbdev.h source file, line 69.
Endpoint address
This typedef is declared in device/class/usbdev.h source file, line 67.
Endpoint maps
const char dev_usbdev_event_e[] [link]
This constant is declared in ENUM_DESCRIPTOR function like macro expansion, line 1 in device/class/usbdev.h source file, line 48.
Alternate declarations with same identifier: [1], [2].
enum dev_usbdev_event_e [link]
This enum is declared in device/class/usbdev.h source file, line 51.
Alternate declarations with same identifier: [1], [2].
| Identifier | Description |
|---|---|
| USBDEV_EVENT_CONNECT | Device Attached |
| USBDEV_EVENT_DISCONNECT | |
| USBDEV_EVENT_RESET | Reset on bus |
| USBDEV_EVENT_IDLE | No bus traffic for more than 3 ms |
| USBDEV_EVENT_WAKEUP | Wake up when suspended |
| USBDEV_EVENT_STOP | Device stopped |
typedef void (dev_usbdev_free_t)(struct dev_usbdev_context_s *ctx, void *ptr) [link]
This typedef is declared in device/class/usbdev.h source file, line 398.
This typedef frees an allocated buffer.
enum usb_transfert_direction_e dev_usbdev_get_transfer_dir(struct dev_usbdev_rq_s *tr) [link]
This function is declared in device/class/usbdev.h source file, line 894.
This is available when CONFIG_DEVICE_USBDEV is defined.
struct dev_usbdev_interface_cfg_s [link]
This struct is declared in device/class/usbdev.h source file, line 319.
| Field | Description |
|---|---|
| const struct usbdev_interface_s * i; | |
| dev_usbdev_ep_map_t * epi; | |
| dev_usbdev_ep_map_t * epo; |
enum dev_usbdev_interface_e [link]
This enum is declared in device/class/usbdev.h source file, line 313.
| Identifier | Description |
|---|---|
| DEV_USBDEV_INTF_ENABLE | |
| DEV_USBDEV_INTF_DISABLE |
typedef error_t (dev_usbdev_request_t)(struct dev_usbdev_context_s *ctx, struct dev_usbdev_rq_s *tr) [link]
This typedef is declared in device/class/usbdev.h source file, line 257.
USB device class request() function type. Post a request on an USB device driver. There can be only one single request active at the same time on an endpoint.
When a request is posted on driver, this function must return 0 if request processing is done immediately. If the request is processed later or if an interrupt must be waited to terminate the request, this function must return -EAGAIN. In this case, when the request will be terminated, the driver will have to call the usbdev_stack_request_done function.
A USB CONTROL transfer involves multiple stages and multipe transactions. Up to 3 stages are necessary. The first stage will retrieve setup packet. If there is a data stage, the next stage will retrieve or send data packet(s) depending on direction of control transfer. The last stage is the status stage.
No data stage:
SETUP | STATUS IN
SETUP | STATUS IN STALLWith DATA IN stage
SETUP | DATA IN | DATA IN | ... | STATUS OUT
SETUP | DATA IN | DATA IN | ... | STATUS OUT STALL
SETUP | DATA IN | ... | DATA IN STALLWith DATA OUT stage
SETUP | DATA OUT | DATA OUT | ... | STATUS IN
SETUP | DATA OUT | DATA OUT | ... | STATUS IN STALL
SETUP | DATA OUT | ... | DATA OUT STALLAll other transfer types involve only one DATA stage consisting of one or more USB transactions. For ISOCHRONOUS transfers the DEV_USBDEV_DATA_OUT_STALL and DEV_USBDEV_DATA_IN_STALL can not be used.
For endpoint 0 and only for this endpoint, each on-going transfer can be terminated prematurely if an event is detected on bus or if the device is stopped. In this case, request is terminated with -EIO error. It is the responsability of the driver to end properly the on-going transfer on endpoint 0 when a event occurs so that any new transfer on this endpoint can be processed normally.
If a transfer is running on an endpoint and this endpoint is unconfigured due to a switch to an interface alternate configuration, the usbdev_stack_request_done is called and dev_usbdev_rq_s::error field is set to -EAGAIN.
Each control endpoint must always have a active request for incoming setup packet. If no SETUP request is active when a SETUP packet arrives, it is the responsability of the driver to keep the packet until the next SETUP request. At device start-up, a request is pushed on control endpoint 0 to retrieve initial setup packet from host.
For CONTROL DATA stage, BULK and INTERRUPT transactions, if there is no active request on the corresponding endpoint, the driver is in charge of sending the NAK token in response to the DATA stage transaction from host.
For isochronous endpoints, if a packet has been dropped because no request has been posted in time, dev_usbdev_rq_s::error field will be set to -ETIMEDOUT on the next request posted on this endpoint.
-EAGAIN: If returned when posting request, this means that request will terminate later. If returned with usbdev_stack_request_done for endpoints other than 0, this means that endpoint has been deconfigured and transfer aborted.
-EIO: Only for endpoint 0. A event has occured on device.
-ETIMEDOUT: Returned with usbdev_stack_request_done only. A packet has been dropped on an isochronous endpoint.
-EPIPE: Returned with usbdev_stack_request_done only. USB connection has been lost and transfer is aborted.
void dev_usbdev_rq_done(struct dev_usbdev_rq_s *rq) [link]
This function is declared in device/class/usbdev.h source file, line 168.
This function invokes or schedules execution of the usbdev request callback associated to the request. For use in device drivers.
struct dev_usbdev_rq_s * dev_usbdev_rq_from_kr(struct kroutine_s *kr) [link]
This function is declared in device/class/usbdev.h source file, line 168.
This function retrieves a pointer to the request when in the request completion callback routine.
struct dev_usbdev_rq_s * dev_usbdev_rq_head(dev_request_queue_root_t *q) [link]
This function is declared in device/class/usbdev.h source file, line 168.
This function returns the oldest usbdev request in the given queue. A NULL pointer is returned if the queue is empty. For use in device drivers.
void dev_usbdev_rq_init(struct dev_usbdev_rq_s *rq, kroutine_exec_t *exec) [link]
This function is declared in device/class/usbdev.h source file, line 168.
This function initializes the given usbdev request callback. This must be used before submitting the request to a driver.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
void dev_usbdev_rq_init_immediate(struct dev_usbdev_rq_s *rq, kroutine_exec_t *exec) [link]
This function is declared in device/class/usbdev.h source file, line 168.
This function initializes the given usbdev request callback. This must be used before submitting the request to a driver.
void dev_usbdev_rq_init_queue(struct dev_usbdev_rq_s *rq, kroutine_exec_t *exec, struct kroutine_queue_s *queue) [link]
This function is declared in device/class/usbdev.h source file, line 168.
This function initializes the given usbdev request callback. This must be used before submitting the request to a driver.
This is available when CONFIG_MUTEK_KROUTINE_QUEUE is defined.
void dev_usbdev_rq_init_seq(struct dev_usbdev_rq_s *rq, kroutine_exec_t *exec, struct kroutine_sequence_s *seq) [link]
This function is declared in device/class/usbdev.h source file, line 168.
This function initializes the given usbdev request callback. This must be used before submitting the request to a driver.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
struct dev_usbdev_rq_s * dev_usbdev_rq_pop(dev_request_queue_root_t *q) [link]
This function is declared in device/class/usbdev.h source file, line 168.
This function removes and return the oldest usbdev request in the queue. A NULL pointer is returned if the queue is empty. For use in device drivers.
void dev_usbdev_rq_pushback(dev_request_queue_root_t *q, struct dev_usbdev_rq_s *rq) [link]
This function is declared in device/class/usbdev.h source file, line 168.
This function insert a new usbdev request at the end of the given queue. For use in device drivers.
void dev_usbdev_rq_remove(dev_request_queue_root_t *q, struct dev_usbdev_rq_s *rq) [link]
This function is declared in device/class/usbdev.h source file, line 168.
This function removes the specified usbdev request from the queue. For use in device drivers.
struct dev_usbdev_rq_s [link]
This struct is declared in device/class/usbdev.h source file, line 131.
This struct is the USB device request structure. From an USB point of view and except for DEV_USBDEV_EVENT, requests are used as response to USB transactions. This type of request are appropriated to device controller exposing a transaction level interface.
| Field | Description |
|---|---|
| union <anonymous> { | |
| struct dev_request_s base; | |
| typeof(struct dev_request_s::error) error; | |
| typeof(struct dev_request_s::pvdata) pvdata; | |
| }; | |
| uint32_t size; | Size of the data buffer. For receiving data, size must be a multiple of the max packet size of the endpoint. |
| uint16_t rem; | Used for control transfer data stage only. Indicate the remaining data to send or received. This migth be modified by driver. Driver can use this field to know when data stage is terminated |
| dev_usbdev_cfgrev_t rev; | Endpoint revision. This field is used by USB device stack and must not be modified by driver |
| uint8_t ep:4; | Endpoint number. Endpoint number 0 is the default CONTROL endpoint. Others value are endpoint number sent to host in configuration descriptor |
| enum dev_usbdev_rq_type_e type:8; | Request type. Determines also the transaction data transfer direction |
| void * data; | Buffer for transmission and reception of data. Most of USB controller embedding an internal DMA constrain size and alignement of source and destination buffer. Thus buffer must be allocated and freed with the dev_usbdev_alloc_t and dev_usbdev_free_t functions. Value of data is undefined when a request is terminated. Buffer is only used for setup and data stage. |
| uint8_t event; | For endpoint 0 and only for this endpoint, when used in conjunction with the error field set to -EIO, this field contains one or more USB events that occured on controller. |
struct dev_request_s * dev_usbdev_rq_s_base(struct dev_usbdev_rq_s *x) [link]
This function is declared in device/class/usbdev.h source file, line 168.
struct dev_usbdev_rq_s * dev_usbdev_rq_s_cast(struct dev_request_s *x) [link]
This function is declared in device/class/usbdev.h source file, line 168.
const char dev_usbdev_rq_type_e[] [link]
This constant is declared in ENUM_DESCRIPTOR function like macro expansion, line 1 in device/class/usbdev.h source file, line 73.
Alternate declarations with same identifier: [1], [2].
enum dev_usbdev_rq_type_e [link]
This enum is declared in device/class/usbdev.h source file, line 76.
Alternate declarations with same identifier: [1], [2].
| Identifier | Description |
|---|---|
| DEV_USBDEV_EVENT | No transfer. Get event on USB device controller. The dev_usbdev_rq_s::event field of the request is used to return one or more events of type enum dev_usbdev_event_e |
| DEV_USBDEV_CTRL_SETUP | Get SETUP stage packet from host. The request returns only when a setup packet has been entirely received. This is only used with CONTROL endpoints |
| DEV_USBDEV_DATA_IN | Send data to host. The request is terminated only when the whole data buffer is sent. This can be achieved in multiple DATA IN transactions on the USB bus. When used in conjunction with the dev_usbdev_rq_s::size field set to 0, a Zero Length Packet is generated. |
| DEV_USBDEV_PARTIAL_DATA_IN | Send data to host. The request does not terminate until at least one byte of data has been sent to the host. When used in conjunction with the dev_usbdev_rq_s::size field set to 0, a Zero Length Packet is generated. |
| DEV_USBDEV_DATA_IN_STALL | Send a STALL PID in response to the next DATA IN stage transaction. |
| DEV_USBDEV_DATA_OUT | Get data from host. The request is terminated when either the dev_usbdev_rq_s::buffer is full or when a short packet is received. For CONTROL endpoint, the request is also terminated when the dev_usbdev_rq_s::rem field is null which means that the CONTROL data stage is terminated. |
| DEV_USBDEV_PARTIAL_DATA_OUT | Get data from host. The request does not terminated until at least one byte has been received from host. |
| DEV_USBDEV_DATA_OUT_STALL | Send a STALL PID in response to the next DATA OUT stage transaction. |
| DEV_USBDEV_CTRL_STATUS_IN | Send a Zero Length Packet in STATUS IN stage. This is only used with CONTROL endpoints |
| DEV_USBDEV_CTRL_STATUS_IN_STALL | Send a STALL PID in STATUS IN stage. This is only used with CONTROL endpoints |
| DEV_USBDEV_CTRL_STATUS_OUT | Send a ACK PID in STATUS OUT stage. This is only used with CONTROL endpoints |
| DEV_USBDEV_CTRL_STATUS_OUT_STALL | Send a STALL PID in STATUS OUT stage. This is only used with CONTROL endpoints |
struct dev_usbdev_context_s * device_usbdev_context(const struct device_usbdev_s *x) [link]
This function is declared in DRIVER_CTX_CLASS_TYPES function like macro expansion, line 49 in device/class/usbdev.h source file, line 424.
This function returns a pointer to the public context stored in the device private data. This is used by the libdevice generic code of the class, not relevant for all classes.
struct device_usbdev_s [link]
This struct is declared in DRIVER_CTX_CLASS_TYPES function like macro expansion, line 17 in device/class/usbdev.h source file, line 424.
This struct is the device accessor object type for the usbdev device class. This accessor must be initialized by calling the device_get_accessor function.
See also DRIVER_CLASS_USBDEV, struct device_accessor_s and Device accessor.
| Field | Description |
|---|---|
| union <anonymous> { | |
| struct device_accessor_s base; | |
| struct <anonymous> { | |
| struct device_s * dev; | |
| struct driver_usbdev_s * api; | |
| uint_fast8_t number; | |
| }; | |
| }; |
struct device_accessor_s * device_usbdev_s_base(struct device_usbdev_s *x) [link]
This function is declared in DRIVER_CTX_CLASS_TYPES function like macro expansion, line 38 in device/class/usbdev.h source file, line 424.
This function casts a usbdev device accessor to a generic device accessor
struct device_usbdev_s * device_usbdev_s_cast(struct device_accessor_s *x) [link]
This function is declared in DRIVER_CTX_CLASS_TYPES function like macro expansion, line 31 in device/class/usbdev.h source file, line 424.
This function casts a generic device accessor to a usbdev device accessor
struct driver_usbdev_s [link]
This struct is declared in DRIVER_CTX_CLASS_TYPES function like macro expansion, line 6 in device/class/usbdev.h source file, line 424.
This struct is the driver API descriptor for the usbdev device class.
See also DRIVER_CLASS_USBDEV and struct driver_class_s.
| Field | Description |
|---|---|
| uint16_t class_; | |
| uint16_t ctx_offset; |
void usbdev_cdc_descriptor_replace(const struct dev_usbdev_desc_iterator_s *it, const struct usb_descriptor_header_s *src, struct usb_descriptor_header_s *dst, size_t begin, size_t end) [link]
This function is declared in device/class/usbdev.h source file, line 550.
void usbdev_descriptor_replace(const struct dev_usbdev_desc_iterator_s *it, const struct usb_descriptor_header_s *src, struct usb_descriptor_header_s *dst, size_t begin, size_t end) [link]
This function is declared in device/class/usbdev.h source file, line 549.
struct usbdev_device_info_s [link]
This struct is declared in device/class/usbdev.h source file, line 465.
| Field | Description |
|---|---|
| struct usb_device_descriptor_s desc; | |
| uint8_t configuration; | |
| uint8_t power; | |
| uint8_t iconfig; | |
| const char * string; | |
| size_t str_cnt; |
struct usbdev_endpoint_s [link]
This struct is declared in device/class/usbdev.h source file, line 402.
| Field | Description |
|---|---|
| dev_request_queue_root_t queue; | |
| dev_usbdev_cfgrev_t rev; | |
| bool_t busy:1; | |
| bool_t halted:1; | |
| bool_t disabled:1; |
typedef const char *(usbdev_get_string_t)(const struct usbdev_service_s *service, uint8_t idx) [link]
This typedef is declared in device/class/usbdev.h source file, line 547.
This declaration involves expansion of the USBDEV_GET_STRING macro.
struct usbdev_interface_default_s [link]
This struct is declared in device/class/usbdev.h source file, line 509.
| Field | Description |
|---|---|
| struct usbdev_interface_s intf; | |
| const struct usbdev_interface_s *const* alt; | |
| uint8_t alt_cnt; |
struct usbdev_interface_s [link]
This struct is declared in device/class/usbdev.h source file, line 501.
| Field | Description |
|---|---|
| const struct usb_interface_descriptor_s desc; | |
| const struct usb_endpoint_descriptor_s *const* ep; |
typedef void (usbdev_replace_t)(const struct dev_usbdev_desc_iterator_s *it, const struct usb_descriptor_header_s *src, struct usb_descriptor_header_s *dst, size_t begin, size_t end) [link]
This typedef is declared in device/class/usbdev.h source file, line 539.
This declaration involves expansion of the USBDEV_REPLACE macro.
enum usbdev_service_cmd_type_e [link]
This enum is declared in device/class/usbdev.h source file, line 596.
| Identifier | Description |
|---|---|
| USBDEV_PROCESS_CONTROL | This enum_value is used by stack when a class-specific request is received for a service. the usbdev_service_rq_s::ctrl::setup field is the 8 byte SETUP packet to process. When a service needs to send/receive data for processing setup, it must use the provided usbdev_service_rq_s::buffer data buffer. The usbdev_service_rq_s::size is the size of the provided buffer. When the request is not handled by service or when there is a error in request -EINVAL is returned and a request error wil be generated to host. |
| USBDEV_DISABLE_SERVICE | This enum_value is used to disable a service. This function is called when a reset or a disconnect occurs on USB bus. It is also called when device is stoppped or when a SET CONFIGURATION command with a configuration that dos not include the service is sent by host. If endpoint transfers are pending when this kroutine is called, they will terminate later with -EPIPE error. A service must not push any endpoint transfer after this. |
| USBDEV_ENABLE_SERVICE | This enum_value is used to enable a service after a set configuration occured on device. After this, service is authorized to transfer data on its endpoints. |
| USBDEV_CHANGE_INTERFACE | This enum_value is used to inform a service that one of its interfaces has been reconfigured on usb controller due to a SET INTERFACE command on usb device. All pending endpoint transfers that do not use the new configuration ends with -EAGAIN error. The usbdev_service_rq_s::intf is the local target interface. The usbdev_service_rq_s::alternate is the alternate seting number. |
struct usbdev_service_descriptor_s [link]
This struct is declared in device/class/usbdev.h source file, line 553.
| Field | Description |
|---|---|
| const struct usb_descriptor_header_s *const* desc; | |
| uint8_t desc_cnt; | |
| const char * string; | |
| uint8_t str_cnt; | |
| const struct usbdev_interface_default_s *const* intf; | |
| uint8_t intf_cnt; | |
| usbdev_replace_t * replace; | Service dynamic patcher function |
| usbdev_get_string_t * get_string; | Service dynamic string getter |
typedef void * usbdev_service_entry_t [link]
This typedef is declared in device/class/usbdev.h source file, line 728.
struct usbdev_service_index_s [link]
This struct is declared in device/class/usbdev.h source file, line 663.
| Field | Description |
|---|---|
| dev_usbdev_ep_map_t epi[1+CONFIG_USBDEV_MAX_ALTERNATE_COUNT]; | |
| dev_usbdev_ep_map_t epo[1+CONFIG_USBDEV_MAX_ALTERNATE_COUNT]; | |
| uint8_t id; | |
| uint8_t intf; | |
| uint8_t str; |
typedef struct usbdev_service_s * usbdev_service_item_t [link]
This typedef is declared in device/class/usbdev.h source file, line 728.
enum usbdev_service_req_type_e [link]
This enum is declared in device/class/usbdev.h source file, line 577.
This enum is type of request sent by a service on USB device stack
| Identifier | Description |
|---|---|
| USBDEV_TRANSFER_DATA | This enum_value is used in response to a USBDEV_PROCESS_CONTROL command from stack. A service call the usbdev_stack_request with this value to send or receive DATA stage of a CONTROL transfer. Direction of transfer is defined by setup packet. If the number of byte to send/receive is greater than buffer size provided by stack, the service will have to perfom multiple data transfers to/from the stack. |
| USBDEV_GET_COMMAND | This enum_value is used by service to retrieve the next command from stack. At start-up, stack is waiting for all services to post this type of request before performing any operation. When processing a control transfer, a service must use this value to inform stack that DATA stage of control transfer is terminated. If usbdev_service_rq_s::error is set to -EINVAL, a STALL pid will be generated either in DATA or STATUS stage of CONTROL transfer depending of the remaining data to send/receive to/from host. |
typedef void * usbdev_service_root_t [link]
This typedef is declared in device/class/usbdev.h source file, line 728.
struct usbdev_service_rq_s [link]
This struct is declared in device/class/usbdev.h source file, line 629.
This struct is used by service with usbdev_stack_request to retrieve control commands from stack or to transfer data on endpoint 0. At initialisation USB stack is waiting for all registered services to post this request.
| Field | Description |
|---|---|
| struct kroutine_s kr; | The kroutine_exec function is called on this kroutine when a request ends. This kroutine should not be immediate. If this kroutine is immediate, a new request must not be pushed to the stack in this kroutine |
| enum usbdev_service_req_type_e type; | Request type. See enum usbdev_service_req_type_e |
| enum usbdev_service_cmd_type_e cmd; | Request command. See enum usbdev_service_cmd_type_e |
| void * pvdata; | Callback private data |
| error_t error; | |
| uint8_t intf; | |
| union <anonymous> { | |
| uint8_t alternate; | |
| struct <anonymous> { | This struct is set by stack when a SETUP token must be processed by a service. bufer must be used for data stage if present. size is the size of buffer. If data stage implies more bytes than buffer size, multiple transfers must be done. |
| struct usb_ctrl_setup_s * setup; | |
| uint8_t * buffer; | |
| size_t size; | |
| } ctrl; | |
| }; |
struct usbdev_service_s [link]
This struct is declared in device/class/usbdev.h source file, line 678.
This struct must be allocated by each service and must be attached to stack by usbdev_stack_service_register at service initialisation.
| Field | Description |
|---|---|
| const struct usbdev_service_descriptor_s * desc; | |
| struct usbdev_service_index_s start; | |
| struct usbdev_service_rq_s * rq; | |
| void * pv; |
See also usbdev_service_item_t.
void * usbdev_stack_allocate(const struct device_usbdev_s *dev, size_t size) [link]
This function is declared in device/class/usbdev.h source file, line 867.
This function allocates a buffer compliant with USB device controller. Most of USB device controller need special alignement or minimum size for receive or send buffer. Returns 0 when the required allocation failed otherwise returns a pointer on the buffer.
This is available when CONFIG_DEVICE_USBDEV is defined.
error_t usbdev_stack_cleanup(struct dev_usbdev_context_s *ctx) [link]
This function is declared in device/class/usbdev.h source file, line 498.
This is available when CONFIG_DEVICE_USBDEV is defined.
void usbdev_stack_config_done(struct dev_usbdev_context_s *ctx) [link]
This function is declared in device/class/usbdev.h source file, line 378.
This is available when CONFIG_DEVICE_USBDEV is defined.
void usbdev_stack_free(const struct device_usbdev_s *dev, void *ptr) [link]
This function is declared in device/class/usbdev.h source file, line 871.
This function frees an allocated buffer.
This is available when CONFIG_DEVICE_USBDEV is defined.
uint8_t usbdev_stack_get_ep0_mps(struct dev_usbdev_context_s *ctx) [link]
This function is declared in device/class/usbdev.h source file, line 883.
This is available when CONFIG_DEVICE_USBDEV is defined.
uint8_t usbdev_stack_get_ep_addr(const struct usb_endpoint_descriptor_s *desc, dev_usbdev_ep_map_t mapi, dev_usbdev_ep_map_t mapo) [link]
This function is declared in device/class/usbdev.h source file, line 889.
This is available when CONFIG_DEVICE_USBDEV is defined.
error_t usbdev_stack_init(struct device_s *dev, struct dev_usbdev_context_s *ctx, uint16_t epi_msk, uint16_t epo_msk, const struct dev_usbdev_driver_ops_s *ops) [link]
This function is declared in device/class/usbdev.h source file, line 495.
This function initializes an instance of the struct dev_usbdev_context_s structure. epi_msk and epo_msk are two masks of supported IN and OUT endpoints including endpoint 0.
This is available when CONFIG_DEVICE_USBDEV is defined.
error_t usbdev_stack_request(const struct device_usbdev_s *dev, struct usbdev_service_s *service, struct usbdev_service_rq_s *rq) [link]
This function is declared in device/class/usbdev.h source file, line 694.
This function is called by services to retrieve a control command or to transfer data on control endpoint 0.
This is available when CONFIG_DEVICE_USBDEV is defined.
void usbdev_stack_request_done(struct dev_usbdev_context_s *ctx, struct dev_usbdev_rq_s *tr) [link]
This function is declared in device/class/usbdev.h source file, line 260.
This is available when CONFIG_DEVICE_USBDEV is defined.
error_t usbdev_stack_service_register(const struct device_usbdev_s *dev, struct usbdev_service_s *service) [link]
This function is declared in device/class/usbdev.h source file, line 852.
This function attach an USB service to an USB device controller. This is called either by a service that wants to be registered or by a main application implementing its own service. This function can only be called when device is stopped. Otherwise it returns -EBUSY.
This is available when CONFIG_DEVICE_USBDEV is defined.
error_t usbdev_stack_service_unregister(const struct device_usbdev_s *dev, struct usbdev_service_s *service) [link]
This function is declared in device/class/usbdev.h source file, line 860.
This function detach an USB service from an USB device controller. This is called either by a service that wants to be unregistered or by a main application implementing its own service. This function can only called when device is stopped. Otherwise it returns -EBUSY
This is available when CONFIG_DEVICE_USBDEV is defined.
void usbdev_stack_set_device_info(const struct device_usbdev_s *dev, const struct usbdev_device_info_s *info) [link]
This function is declared in device/class/usbdev.h source file, line 876.
This is available when CONFIG_DEVICE_USBDEV is defined.
error_t usbdev_stack_transfer(const struct device_usbdev_s *dev, struct usbdev_service_s *service, struct dev_usbdev_rq_s *tr, const struct usb_endpoint_descriptor_s *desc) [link]
This function is declared in device/class/usbdev.h source file, line 711.
This function is called by services to transfer data on control endpoint other than endpoint 0.
When a SET INTERFACE command from host change the setting of an interface, all the associated endpoints have their revision number changed. If the dev_usbdev_rq_s::rev field of request is different from the current endpoint revision, -EAGAIN is returned either by this function or by kroutine. When a service post a request while it should not, -EPIPE error is returned either by this function or by kroutine. In this case, the dev_usbdev_rq_s::size might not be updated.
This is available when CONFIG_DEVICE_USBDEV is defined.
enum dev_usbdev_ctrl_ep_state_e [link]
This enum is declared in device/class/usbdev.h source file, line 753.
This enum is for internal use only.
Alternate declarations with same identifier: [1], [2].
| Identifier | Description |
|---|---|
| EP0_IDLE | |
| EP0_SETUP_WAIT | |
| EP0_PROCESS_CLASS | |
| EP0_PROCESS_STANDARD | |
| EP0_CTRL_SET_ADDRESS_WAIT | |
| EP0_SET_INTERFACE | |
| EP0_SET_INTERFACE_WAIT | |
| EP0_CTRL_SET_INTERFACE_WAIT | |
| EP0_SRVC_SET_INTERFACE_WAIT | |
| EP0_SET_INTERFACE_END_TRANSFER | |
| EP0_CTRL_CONFIGURATION_WAIT | |
| EP0_SRVC_ENABLE_WAIT | |
| EP0_CTRL_UNCONFIGURATION_WAIT | |
| EP0_SRVC_DISABLE_WAIT | |
| EP0_SRVC_DATA_IN | |
| EP0_SRVC_DATA_IN_WAIT | |
| EP0_DATA_IN | |
| EP0_DATA_IN_ZERO_WAIT | |
| EP0_DATA_IN_WAIT | |
| EP0_DATA_IN_ZERO | |
| EP0_SRVC_DATA_OUT | |
| EP0_SRVC_DATA_OUT_WAIT | |
| EP0_DATA_OUT | |
| EP0_DATA_OUT_WAIT | |
| EP0_STATUS_IN | |
| EP0_SRVC_STATUS_IN | |
| EP0_STATUS_OUT | |
| EP0_STATUS_WAIT | |
| EP0_STALL_WAIT |
struct dev_usbdev_desc_iterator_s [link]
This struct is declared in device/class/usbdev.h source file, line 734.
This struct is for internal use only.
| Field | Description |
|---|---|
| struct usbdev_service_s * service; | |
| size_t desc_offset:16; | |
| size_t data_pkt_size:16; | |
| size_t desc_index:8; | |
| size_t intf_index:8; | |
| bool_t done; |