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 
46 #ifndef USBUS_STACKSIZE
47 #define USBUS_STACKSIZE (THREAD_STACKSIZE_DEFAULT)
48 #endif
49 
53 #ifndef USBUS_PRIO
54 #define USBUS_PRIO (THREAD_PRIORITY_MAIN - 6)
55 #endif
56 
60 #define USBUS_TNAME "usbus"
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 
91 #define USBUS_THREAD_FLAG_USBDEV (0x02)
92 #define USBUS_THREAD_FLAG_USBDEV_EP (0x04)
101 #define USBUS_HANDLER_FLAG_RESET (0x0001)
102 #define USBUS_HANDLER_FLAG_SOF (0x0002)
103 #define USBUS_HANDLER_FLAG_SUSPEND (0x0004)
104 #define USBUS_HANDLER_FLAG_RESUME (0x0008)
105 #define USBUS_HANDLER_FLAG_TR_FAIL (0x0010)
106 #define USBUS_HANDLER_FLAG_TR_STALL (0x0020)
112 typedef enum {
118 
122 typedef enum {
127 
131 typedef enum {
138 
142 typedef enum {
151 
155 typedef struct usbus_string {
156  struct usbus_string *next;
157  const char *str;
158  uint16_t idx;
160 
164 typedef struct usbus usbus_t;
169 typedef struct usbus_handler usbus_handler_t;
174 typedef enum {
178 
182 typedef struct {
192  size_t (*get_header)(usbus_t *usbus, void *arg);
193  union {
205  size_t (*get_header_len)(usbus_t *usbus, void *arg);
206  size_t fixed_len;
207  } len;
208  usbus_hdr_len_type_t len_type;
210 
220 typedef struct usbus_hdr_gen {
221  struct usbus_hdr_gen *next;
223  void *arg;
226 
230 typedef struct usbus_endpoint {
236  uint16_t maxpacketsize;
237  uint8_t interval;
238  bool active;
241 
247 typedef struct usbus_interface_alt {
254 
258 typedef struct usbus_interface {
265  struct usbus_interface_alt *alts;
266  usbus_handler_t *handler;
267  usbus_string_t *descr;
268  uint16_t idx;
270  uint8_t class;
271  uint8_t subclass;
272  uint8_t protocol;
274 
278 typedef struct usbus_handler_driver {
289  void (*init)(usbus_t * usbus, struct usbus_handler *handler);
300  void (*event_handler)(usbus_t * usbus, struct usbus_handler *handler,
302 
313  void (*transfer_handler)(usbus_t * usbus, struct usbus_handler *handler,
315 
331  int (*setup_handler)(usbus_t * usbus, struct usbus_handler *handler,
334 
340 struct usbus_handler {
341  struct usbus_handler *next;
346  uint32_t flags;
347 };
348 
352 struct usbus {
354  usbus_string_t product;
355  usbus_string_t config;
359  usbdev_t *dev;
360  usbus_handler_t *control;
361  usbus_hdr_gen_t *hdr_gen;
362  usbus_string_t *strings;
364  usbus_handler_t *handlers;
365  uint32_t ep_events;
367  uint16_t str_idx;
369  usbus_state_t pstate;
370  uint8_t addr;
371 };
372 
379 static inline void usbus_event_post(usbus_t *usbus, event_t *event)
380 {
381  event_post(&usbus->queue, event);
382 }
383 
394  const char *str);
395 
404 uint16_t usbus_add_interface(usbus_t *usbus, usbus_interface_t *iface);
405 
422  usb_ep_type_t type, usb_ep_dir_t dir,
423  size_t len);
424 
432 void usbus_add_conf_descriptor(usbus_t *usbus, usbus_hdr_gen_t *hdr_gen);
433 
445 
452 void usbus_init(usbus_t *usbus, usbdev_t *usbdev);
453 
463 void usbus_create(char *stack, int stacksize, char priority,
464  const char *name, usbus_t *usbus);
465 
473 static inline void usbus_enable_endpoint(usbus_endpoint_t *ep)
474 {
475  ep->active = true;
476 }
477 
485 static inline void usbus_disable_endpoint(usbus_endpoint_t *ep)
486 {
487  ep->active = false;
488 }
489 
496 static inline void usbus_handler_set_flag(usbus_handler_t *handler,
497  uint32_t flag)
498 {
499  handler->flags |= flag;
500 }
501 
508 static inline void usbus_handler_remove_flag(usbus_handler_t *handler,
509  uint32_t flag)
510 {
511  handler->flags &= ~flag;
512 }
513 
522 static inline bool usbus_handler_isset_flag(usbus_handler_t *handler,
523  uint32_t flag)
524 {
525  return handler->flags & flag;
526 }
527 
528 
529 #ifdef __cplusplus
530 }
531 #endif
532 #endif /* USB_USBUS_H */
533 
Transfer succesfully completed.
Definition: usbus.h:124
Types used by the kernel.
USBUS endpoint context.
Definition: usbus.h:231
usbus_hdr_gen_t * hdr_gen
Optional additional header generator.
Definition: usbus.h:250
USBUS context struct.
Definition: usbus.h:353
struct usbus_string * next
Ptr to the next registered string.
Definition: usbus.h:157
USB resume condition detected.
Definition: usbus.h:117
Data OUT expected.
Definition: usbus.h:148
usb_ep_type_t
USB endpoint types.
Definition: usb.h:123
void usbus_register_event_handler(usbus_t *usbus, usbus_handler_t *handler)
Add an event handler to the USBUS context.
void usbus_add_conf_descriptor(usbus_t *usbus, usbus_hdr_gen_t *hdr_gen)
Add a generator for generating additional top level USB descriptor content.
Expecting a zero-length ack in request from the host.
Definition: usbus.h:149
usbus_hdr_gen_t * hdr_gen
Optional additional header generators.
Definition: usbus.h:262
Definitions low-level USB driver interface.
uint16_t idx
USB string index.
Definition: usbus.h:159
USBUS interface.
Definition: usbus.h:259
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:123
const usbus_handler_driver_t * driver
driver for this handler
Definition: usbus.h:344
static bool usbus_handler_isset_flag(usbus_handler_t *handler, uint32_t flag)
check if a specific handler flag is set
Definition: usbus.h:523
USBUS string type.
Definition: usbus.h:156
Header always generates a fixed length.
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.
Peripheral is suspended by the host.
Definition: usbus.h:137
USB reset event.
Definition: usbus.h:114
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:380
static void usbus_handler_set_flag(usbus_handler_t *handler, uint32_t flag)
enable a specific handler flag
Definition: usbus.h:497
Transfer nack replied by peripheral.
Definition: usbus.h:125
int16_t kernel_pid_t
Unique process identifier.
Definition: kernel_types.h:83
USB start of frame received.
Definition: usbus.h:115
Request received with expected DATA IN stage.
Definition: usbus.h:145
usbus_endpoint_t * ep
Linked list of endpoints belonging to this interface.
Definition: usbus.h:264
unsigned int size_t
Used for sizes of objects.
Definition: msp430_types.h:88
Threading API.
USBUS header generator function pointers.
Definition: usbus.h:183
Definitions for USB protocol messages.
uint8_t interval
Poll interval for interrupt endpoints.
Definition: usbus.h:238
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:345
void usbus_init(usbus_t *usbus, usbdev_t *usbdev)
Initialize an USBUS context.
const char * str
C string to use as content.
Definition: usbus.h:158
USB suspend condition detected.
Definition: usbus.h:116
const usbus_hdr_gen_funcs_t * funcs
Function pointers.
Definition: usbus.h:223
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:237
Messaging API for inter process communication.
usbus_endpoint_t * ep
List of associated endpoints for this alternative setting.
Definition: usbus.h:252
event_queue_t queue
Event queue.
Definition: usbus.h:359
void * arg
Extra context argument for the headers functions.
Definition: usbus.h:224
Transfer stall replied by peripheral.
Definition: usbus.h:126
Device is disconnected from the host.
Definition: usbus.h:133
usbus_setuprq_state_t
USBUS setup request state machine.
Definition: usbus.h:143
Expecting a zero-length ack out request from the host.
Definition: usbus.h:146
usbus_state_t
state machine states for the global USBUS thread
Definition: usbus.h:132
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:136
USBUS header generator.
Definition: usbus.h:221
struct usbus_interface_alt usbus_interface_alt_t
USBUS interface alternative setting.
USBUS handler struct.
Definition: usbus.h:341
Ready for new setup request.
Definition: usbus.h:144
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:486
Header length is calculated by a function.
Definition: usbus.h:177
usb_ep_dir_t
USB endpoint directions.
Definition: usb.h:134
Address configured.
Definition: usbus.h:135
usbdev_ep_t * ep
ptr to the matching usbdev endpoint
Definition: usbus.h:236
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:509
bool active
If the endpoint should be activated after reset.
Definition: usbus.h:239
Circular linked list.
Reset condition received.
Definition: usbus.h:134
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:113
static void usbus_enable_endpoint(usbus_endpoint_t *ep)
Enable an endpoint.
Definition: usbus.h:474
usbdev endpoint descriptor
Definition: usbdev.h:229
uint32_t flags
Report flags.
Definition: usbus.h:347
usbdev device descriptor
Definition: usbdev.h:217
usbus_hdr_len_type_t
Header length types for USB descriptor generators.
Definition: usbus.h:175
stdlib.h wrapper for MSP430
void usbus_create(char *stack, int stacksize, char priority, const char *name, usbus_t *usbus)
Create and start the USBUS thread.
usbus_hdr_gen_t * hdr_gen
Optional additional header generator.
Definition: usbus.h:235
struct usbus_hdr_gen usbus_hdr_gen_t
USBUS header generator.
USBUS interface alternative setting.
Definition: usbus.h:248
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:279