usbus.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2018 Koen Zandberg
3  *
4  * This file is subject to the terms and conditions of the GNU Lesser
5  * General Public License v2.1. See the file LICENSE in the top level
6  * directory for more details.
7  */
8 
23 #ifndef USB_USBUS_H
24 #define USB_USBUS_H
25 
26 #include <stdint.h>
27 #include <stdlib.h>
28 
29 #include "clist.h"
30 #include "event.h"
31 #include "kernel_types.h"
32 #include "kernel_defines.h"
33 #include "msg.h"
34 #include "thread.h"
35 
36 #include "usb.h"
37 #include "periph/usbdev.h"
38 #include "usb/descriptor.h"
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43 
52 #ifndef USBUS_STACKSIZE
53 #define USBUS_STACKSIZE (THREAD_STACKSIZE_DEFAULT)
54 #endif
55 
59 #ifndef USBUS_PRIO
60 #define USBUS_PRIO (THREAD_PRIORITY_MAIN - 6)
61 #endif
62 
70 #ifndef CONFIG_USBUS_AUTO_ATTACH
71 #if !IS_ACTIVE(KCONFIG_MODULE_USBUS)
72 #define CONFIG_USBUS_AUTO_ATTACH 1
73 #endif
74 #endif
75 
83 #if IS_ACTIVE(CONFIG_USBUS_EP0_SIZE_8)
84 #define CONFIG_USBUS_EP0_SIZE 8
85 #elif IS_ACTIVE(CONFIG_USBUS_EP0_SIZE_16)
86 #define CONFIG_USBUS_EP0_SIZE 16
87 #elif IS_ACTIVE(CONFIG_USBUS_EP0_SIZE_32)
88 #define CONFIG_USBUS_EP0_SIZE 32
89 #elif IS_ACTIVE(CONFIG_USBUS_EP0_SIZE_64)
90 #define CONFIG_USBUS_EP0_SIZE 64
91 #endif
92 
93 #ifndef CONFIG_USBUS_EP0_SIZE
94 #define CONFIG_USBUS_EP0_SIZE 64
95 #endif
96 
101 #define USBUS_TNAME "usbus"
102 
110 #define USBUS_THREAD_FLAG_USBDEV (0x02)
111 #define USBUS_THREAD_FLAG_USBDEV_EP (0x04)
120 #define USBUS_HANDLER_FLAG_RESET (0x0001)
121 #define USBUS_HANDLER_FLAG_SOF (0x0002)
122 #define USBUS_HANDLER_FLAG_SUSPEND (0x0004)
123 #define USBUS_HANDLER_FLAG_RESUME (0x0008)
124 #define USBUS_HANDLER_FLAG_TR_FAIL (0x0010)
125 #define USBUS_HANDLER_FLAG_TR_STALL (0x0020)
131 typedef enum {
137 
141 typedef enum {
146 
150 typedef enum {
157 
161 typedef enum {
171 
175 typedef struct usbus_string {
176  struct usbus_string *next;
177  const char *str;
178  uint16_t idx;
180 
184 typedef struct usbus usbus_t;
189 typedef struct usbus_handler usbus_handler_t;
194 typedef enum {
198 
202 typedef struct {
213  size_t (*fmt_pre_descriptor)(usbus_t *usbus, void *arg);
225  size_t (*fmt_post_descriptor)(usbus_t *usbus, void *arg);
226  union {
240  size_t (*get_descriptor_len)(usbus_t *usbus, void *arg);
249  size_t fixed_len;
250  } len;
251  usbus_descr_len_type_t len_type;
253 
263 typedef struct usbus_descr_gen {
266  void *arg;
269 
273 typedef struct usbus_endpoint {
279  usbdev_ep_t *ep;
280  uint16_t maxpacketsize;
281  uint8_t interval;
282  bool active;
285 
291 typedef struct usbus_interface_alt {
298 
302 typedef struct usbus_interface {
309  struct usbus_interface_alt *alts;
310  usbus_handler_t *handler;
311  usbus_string_t *descr;
312  uint16_t idx;
314  uint8_t class;
315  uint8_t subclass;
316  uint8_t protocol;
318 
322 typedef struct usbus_handler_driver {
333  void (*init)(usbus_t * usbus, struct usbus_handler *handler);
344  void (*event_handler)(usbus_t * usbus, struct usbus_handler *handler,
346 
357  void (*transfer_handler)(usbus_t * usbus, struct usbus_handler *handler,
359 
375  int (*control_handler)(usbus_t * usbus, struct usbus_handler *handler,
377  usb_setup_t *request);
379 
385 struct usbus_handler {
386  struct usbus_handler *next;
391  uint32_t flags;
392 };
393 
397 struct usbus {
399  usbus_string_t product;
400  usbus_string_t config;
404  usbdev_t *dev;
405  usbus_handler_t *control;
406  usbus_descr_gen_t *descr_gen;
408  usbus_string_t *strings;
410  usbus_handler_t *handlers;
411  uint32_t ep_events;
413  uint16_t str_idx;
415  usbus_state_t pstate;
416  uint8_t addr;
417 };
418 
425 static inline void usbus_event_post(usbus_t *usbus, event_t *event)
426 {
427  event_post(&usbus->queue, event);
428 }
429 
440  const char *str);
441 
450 uint16_t usbus_add_interface(usbus_t *usbus, usbus_interface_t *iface);
451 
467  usb_ep_type_t type,
468  usb_ep_dir_t dir);
469 
486  usb_ep_type_t type, usb_ep_dir_t dir,
487  size_t len);
488 
496 void usbus_add_conf_descriptor(usbus_t *usbus, usbus_descr_gen_t *descr_gen);
497 
509 
516 void usbus_init(usbus_t *usbus, usbdev_t *usbdev);
517 
527 void usbus_create(char *stack, int stacksize, char priority,
528  const char *name, usbus_t *usbus);
529 
537 static inline void usbus_enable_endpoint(usbus_endpoint_t *ep)
538 {
539  ep->active = true;
540 }
541 
549 static inline void usbus_disable_endpoint(usbus_endpoint_t *ep)
550 {
551  ep->active = false;
552 }
553 
560 static inline void usbus_handler_set_flag(usbus_handler_t *handler,
561  uint32_t flag)
562 {
563  handler->flags |= flag;
564 }
565 
572 static inline void usbus_handler_remove_flag(usbus_handler_t *handler,
573  uint32_t flag)
574 {
575  handler->flags &= ~flag;
576 }
577 
586 static inline bool usbus_handler_isset_flag(usbus_handler_t *handler,
587  uint32_t flag)
588 {
589  return handler->flags & flag;
590 }
591 
592 
593 #ifdef __cplusplus
594 }
595 #endif
596 #endif /* USB_USBUS_H */
597 
Transfer successfully completed.
Definition: usbus.h:143
Types used by the kernel.
USBUS endpoint context.
Definition: usbus.h:274
USBUS context struct.
Definition: usbus.h:398
struct usbus_string * next
Ptr to the next registered string.
Definition: usbus.h:177
USB resume condition detected.
Definition: usbus.h:136
usb_ep_type_t
USB endpoint types.
Definition: usb.h:179
Expecting a zero-length ack IN request from the host.
Definition: usbus.h:169
usbus_descr_len_type_t
descriptor length types for USB descriptor generators
Definition: usbus.h:195
void usbus_register_event_handler(usbus_t *usbus, usbus_handler_t *handler)
Add an event handler to the USBUS context.
Definitions low-level USB driver interface.
uint16_t idx
USB string index.
Definition: usbus.h:179
USBUS interface.
Definition: usbus.h:303
struct usbus_interface usbus_interface_t
USBUS interface.
event structure
Definition: event.h:139
usbus_event_transfer_t
USB endpoint transfer status events.
Definition: usbus.h:142
const usbus_handler_driver_t * driver
driver for this handler
Definition: usbus.h:389
static bool usbus_handler_isset_flag(usbus_handler_t *handler, uint32_t flag)
check if a specific handler flag is set
Definition: usbus.h:587
USBUS string type.
Definition: usbus.h:176
uint16_t usbus_add_string_descriptor(usbus_t *usbus, usbus_string_t *desc, const char *str)
Add a string descriptor to the USBUS thread context.
Descriptor length is calculated by a function.
Definition: usbus.h:197
Peripheral is suspended by the host.
Definition: usbus.h:156
USB reset event.
Definition: usbus.h:133
void event_post(event_queue_t *queue, event_t *event)
Queue an event.
static void usbus_event_post(usbus_t *usbus, event_t *event)
Submit an event to the usbus thread.
Definition: usbus.h:426
static void usbus_handler_set_flag(usbus_handler_t *handler, uint32_t flag)
enable a specific handler flag
Definition: usbus.h:561
Transfer nack replied by peripheral.
Definition: usbus.h:144
int16_t kernel_pid_t
Unique process identifier.
Definition: kernel_types.h:83
USB start of frame received.
Definition: usbus.h:134
usbus_endpoint_t * ep
Linked list of endpoints belonging to this interface.
Definition: usbus.h:308
unsigned int size_t
Used for sizes of objects.
Definition: msp430_types.h:88
Definitions for USB protocol messages.
Request received with expected DATA IN stage.
Definition: usbus.h:164
uint8_t interval
Poll interval for interrupt endpoints.
Definition: usbus.h:282
struct usbus_handler_driver usbus_handler_driver_t
USBUS event handler function pointers.
usbus_interface_t * iface
Interface this handler belongs to.
Definition: usbus.h:390
void usbus_init(usbus_t *usbus, usbdev_t *usbdev)
Initialize an USBUS context.
void * arg
Extra context argument for the descriptor functions.
Definition: usbus.h:267
Ready for new control request.
Definition: usbus.h:163
USBUS descriptor generator.
Definition: usbus.h:264
const char * str
C string to use as content.
Definition: usbus.h:178
void usbus_add_conf_descriptor(usbus_t *usbus, usbus_descr_gen_t *descr_gen)
Add a generator for generating additional top level USB descriptor content.
USB suspend condition detected.
Definition: usbus.h:135
usbus_descr_gen_t * descr_gen
Linked list of optional additional descriptor generators.
Definition: usbus.h:306
USB setup packet (USB 2.0 spec table 9-2)
Definition: descriptor.h:200
uint16_t maxpacketsize
Max packet size of this endpoint.
Definition: usbus.h:281
usbus_control_request_state_t
USBUS control request state machine.
Definition: usbus.h:162
struct usbus_descr_gen usbus_descr_gen_t
USBUS descriptor generator.
Messaging API for inter process communication.
usbus_endpoint_t * ep
List of associated endpoints for this alternative setting.
Definition: usbus.h:296
event_queue_t queue
Event queue.
Definition: usbus.h:404
Transfer stall replied by peripheral.
Definition: usbus.h:145
Device is disconnected from the host.
Definition: usbus.h:152
Data OUT expected.
Definition: usbus.h:168
usbus_endpoint_t * usbus_interface_find_endpoint(usbus_interface_t *interface, usb_ep_type_t type, usb_ep_dir_t dir)
Find an endpoint from an interface based on the endpoint properties.
const usbus_descr_gen_funcs_t * funcs
Function pointers.
Definition: usbus.h:266
usbus_state_t
state machine states for the global USBUS thread
Definition: usbus.h:151
usbus_descr_gen_t * descr_gen
Linked list of optional additional descriptor generators.
Definition: usbus.h:278
USBUS descriptor generator function pointers.
Definition: usbus.h:203
uint16_t usbus_add_interface(usbus_t *usbus, usbus_interface_t *iface)
Add an interface to the USBUS thread context.
event queue structure
Definition: event.h:147
Peripheral is configured.
Definition: usbus.h:155
struct usbus_interface_alt usbus_interface_alt_t
USBUS interface alternative setting.
USBUS handler struct.
Definition: usbus.h:386
struct usbus_string usbus_string_t
USBUS string type.
Common macros and compiler attributes/pragmas configuration.
static void usbus_disable_endpoint(usbus_endpoint_t *ep)
Disable an endpoint.
Definition: usbus.h:550
usb_ep_dir_t
USB endpoint directions.
Definition: usb.h:190
Address configured.
Definition: usbus.h:154
usbdev_ep_t * ep
ptr to the matching usbdev endpoint
Definition: usbus.h:280
Definition of global compile time configuration options.
static void usbus_handler_remove_flag(usbus_handler_t *handler, uint32_t flag)
disable a specific handler flag
Definition: usbus.h:573
bool active
If the endpoint should be activated after reset.
Definition: usbus.h:283
Circular linked list.
Reset condition received.
Definition: usbus.h:153
usbus_endpoint_t * usbus_add_endpoint(usbus_t *usbus, usbus_interface_t *iface, usb_ep_type_t type, usb_ep_dir_t dir, size_t len)
Add an endpoint to the specified interface.
usbus_event_usb_t
USB handler events.
Definition: usbus.h:132
static void usbus_enable_endpoint(usbus_endpoint_t *ep)
Enable an endpoint.
Definition: usbus.h:538
usbdev endpoint descriptor
Definition: usbdev.h:229
uint32_t flags
Report flags.
Definition: usbus.h:392
usbdev device descriptor
Definition: usbdev.h:217
stdlib.h wrapper for MSP430
Expecting a zero-length ack OUT request from the host.
Definition: usbus.h:166
Descriptor always generates a fixed length.
Definition: usbus.h:196
void usbus_create(char *stack, int stacksize, char priority, const char *name, usbus_t *usbus)
Create and start the USBUS thread.
usbus_descr_gen_t * descr_gen
Linked list of optional additional descriptor generators.
Definition: usbus.h:294
USBUS interface alternative setting.
Definition: usbus.h:292
struct usbus_endpoint usbus_endpoint_t
USBUS endpoint context.
#define USBDEV_NUM_ENDPOINTS
Number of USB IN and OUT endpoints allocated.
Definition: usbdev.h:113
USBUS event handler function pointers.
Definition: usbus.h:323