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 "msg.h"
33 #include "thread.h"
34 
35 #include "usb.h"
36 #include "periph/usbdev.h"
37 #include "usb/descriptor.h"
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
51 #ifndef USBUS_STACKSIZE
52 #define USBUS_STACKSIZE (THREAD_STACKSIZE_DEFAULT)
53 #endif
54 
58 #ifndef USBUS_PRIO
59 #define USBUS_PRIO (THREAD_PRIORITY_MAIN - 6)
60 #endif
61 
69 #ifndef USBUS_AUTO_ATTACH
70 #define USBUS_AUTO_ATTACH (1)
71 #endif
72 
80 #ifndef USBUS_EP0_SIZE
81 #define USBUS_EP0_SIZE 64
82 #endif
83 
88 #define USBUS_TNAME "usbus"
89 
97 #define USBUS_THREAD_FLAG_USBDEV (0x02)
98 #define USBUS_THREAD_FLAG_USBDEV_EP (0x04)
107 #define USBUS_HANDLER_FLAG_RESET (0x0001)
108 #define USBUS_HANDLER_FLAG_SOF (0x0002)
109 #define USBUS_HANDLER_FLAG_SUSPEND (0x0004)
110 #define USBUS_HANDLER_FLAG_RESUME (0x0008)
111 #define USBUS_HANDLER_FLAG_TR_FAIL (0x0010)
112 #define USBUS_HANDLER_FLAG_TR_STALL (0x0020)
118 typedef enum {
124 
128 typedef enum {
133 
137 typedef enum {
144 
148 typedef enum {
158 
162 typedef struct usbus_string {
163  struct usbus_string *next;
164  const char *str;
165  uint16_t idx;
167 
171 typedef struct usbus usbus_t;
176 typedef struct usbus_handler usbus_handler_t;
181 typedef enum {
185 
189 typedef struct {
200  size_t (*fmt_pre_descriptor)(usbus_t *usbus, void *arg);
212  size_t (*fmt_post_descriptor)(usbus_t *usbus, void *arg);
213  union {
227  size_t (*get_descriptor_len)(usbus_t *usbus, void *arg);
236  size_t fixed_len;
237  } len;
238  usbus_descr_len_type_t len_type;
240 
250 typedef struct usbus_descr_gen {
253  void *arg;
256 
260 typedef struct usbus_endpoint {
266  usbdev_ep_t *ep;
267  uint16_t maxpacketsize;
268  uint8_t interval;
269  bool active;
272 
278 typedef struct usbus_interface_alt {
285 
289 typedef struct usbus_interface {
296  struct usbus_interface_alt *alts;
297  usbus_handler_t *handler;
298  usbus_string_t *descr;
299  uint16_t idx;
301  uint8_t class;
302  uint8_t subclass;
303  uint8_t protocol;
305 
309 typedef struct usbus_handler_driver {
320  void (*init)(usbus_t * usbus, struct usbus_handler *handler);
331  void (*event_handler)(usbus_t * usbus, struct usbus_handler *handler,
333 
344  void (*transfer_handler)(usbus_t * usbus, struct usbus_handler *handler,
346 
362  int (*control_handler)(usbus_t * usbus, struct usbus_handler *handler,
364  usb_setup_t *request);
366 
372 struct usbus_handler {
373  struct usbus_handler *next;
378  uint32_t flags;
379 };
380 
384 struct usbus {
386  usbus_string_t product;
387  usbus_string_t config;
391  usbdev_t *dev;
392  usbus_handler_t *control;
393  usbus_descr_gen_t *descr_gen;
395  usbus_string_t *strings;
397  usbus_handler_t *handlers;
398  uint32_t ep_events;
400  uint16_t str_idx;
402  usbus_state_t pstate;
403  uint8_t addr;
404 };
405 
412 static inline void usbus_event_post(usbus_t *usbus, event_t *event)
413 {
414  event_post(&usbus->queue, event);
415 }
416 
427  const char *str);
428 
437 uint16_t usbus_add_interface(usbus_t *usbus, usbus_interface_t *iface);
438 
454  usb_ep_type_t type,
455  usb_ep_dir_t dir);
456 
473  usb_ep_type_t type, usb_ep_dir_t dir,
474  size_t len);
475 
483 void usbus_add_conf_descriptor(usbus_t *usbus, usbus_descr_gen_t *descr_gen);
484 
496 
503 void usbus_init(usbus_t *usbus, usbdev_t *usbdev);
504 
514 void usbus_create(char *stack, int stacksize, char priority,
515  const char *name, usbus_t *usbus);
516 
524 static inline void usbus_enable_endpoint(usbus_endpoint_t *ep)
525 {
526  ep->active = true;
527 }
528 
536 static inline void usbus_disable_endpoint(usbus_endpoint_t *ep)
537 {
538  ep->active = false;
539 }
540 
547 static inline void usbus_handler_set_flag(usbus_handler_t *handler,
548  uint32_t flag)
549 {
550  handler->flags |= flag;
551 }
552 
559 static inline void usbus_handler_remove_flag(usbus_handler_t *handler,
560  uint32_t flag)
561 {
562  handler->flags &= ~flag;
563 }
564 
573 static inline bool usbus_handler_isset_flag(usbus_handler_t *handler,
574  uint32_t flag)
575 {
576  return handler->flags & flag;
577 }
578 
579 
580 #ifdef __cplusplus
581 }
582 #endif
583 #endif /* USB_USBUS_H */
584 
Transfer successfully completed.
Definition: usbus.h:130
Types used by the kernel.
USBUS endpoint context.
Definition: usbus.h:261
USBUS context struct.
Definition: usbus.h:385
struct usbus_string * next
Ptr to the next registered string.
Definition: usbus.h:164
USB resume condition detected.
Definition: usbus.h:123
usb_ep_type_t
USB endpoint types.
Definition: usb.h:140
Expecting a zero-length ack IN request from the host.
Definition: usbus.h:156
usbus_descr_len_type_t
descriptor length types for USB descriptor generators
Definition: usbus.h:182
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:166
USBUS interface.
Definition: usbus.h:290
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:129
const usbus_handler_driver_t * driver
driver for this handler
Definition: usbus.h:376
static bool usbus_handler_isset_flag(usbus_handler_t *handler, uint32_t flag)
check if a specific handler flag is set
Definition: usbus.h:574
USBUS string type.
Definition: usbus.h:163
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:184
Peripheral is suspended by the host.
Definition: usbus.h:143
USB reset event.
Definition: usbus.h:120
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:413
static void usbus_handler_set_flag(usbus_handler_t *handler, uint32_t flag)
enable a specific handler flag
Definition: usbus.h:548
Transfer nack replied by peripheral.
Definition: usbus.h:131
int16_t kernel_pid_t
Unique process identifier.
Definition: kernel_types.h:83
USB start of frame received.
Definition: usbus.h:121
usbus_endpoint_t * ep
Linked list of endpoints belonging to this interface.
Definition: usbus.h:295
unsigned int size_t
Used for sizes of objects.
Definition: msp430_types.h:88
Threading API.
Definitions for USB protocol messages.
Request received with expected DATA IN stage.
Definition: usbus.h:151
uint8_t interval
Poll interval for interrupt endpoints.
Definition: usbus.h:269
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:377
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:254
Ready for new control request.
Definition: usbus.h:150
USBUS descriptor generator.
Definition: usbus.h:251
const char * str
C string to use as content.
Definition: usbus.h:165
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:122
usbus_descr_gen_t * descr_gen
Linked list of optional additional descriptor generators.
Definition: usbus.h:293
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:268
usbus_control_request_state_t
USBUS control request state machine.
Definition: usbus.h:149
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:283
event_queue_t queue
Event queue.
Definition: usbus.h:391
Transfer stall replied by peripheral.
Definition: usbus.h:132
Device is disconnected from the host.
Definition: usbus.h:139
Data OUT expected.
Definition: usbus.h:155
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:253
usbus_state_t
state machine states for the global USBUS thread
Definition: usbus.h:138
usbus_descr_gen_t * descr_gen
Linked list of optional additional descriptor generators.
Definition: usbus.h:265
USBUS descriptor generator function pointers.
Definition: usbus.h:190
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:142
struct usbus_interface_alt usbus_interface_alt_t
USBUS interface alternative setting.
USBUS handler struct.
Definition: usbus.h:373
struct usbus_string usbus_string_t
USBUS string type.
Event API.
static void usbus_disable_endpoint(usbus_endpoint_t *ep)
Disable an endpoint.
Definition: usbus.h:537
usb_ep_dir_t
USB endpoint directions.
Definition: usb.h:151
Address configured.
Definition: usbus.h:141
usbdev_ep_t * ep
ptr to the matching usbdev endpoint
Definition: usbus.h:267
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:560
bool active
If the endpoint should be activated after reset.
Definition: usbus.h:270
Circular linked list.
Reset condition received.
Definition: usbus.h:140
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:119
static void usbus_enable_endpoint(usbus_endpoint_t *ep)
Enable an endpoint.
Definition: usbus.h:525
usbdev endpoint descriptor
Definition: usbdev.h:229
uint32_t flags
Report flags.
Definition: usbus.h:379
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:153
Descriptor always generates a fixed length.
Definition: usbus.h:183
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:281
USBUS interface alternative setting.
Definition: usbus.h:279
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:310