usbus.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2018 Koen Zandberg
 * SPDX-License-Identifier: LGPL-2.1-only
 */
 
#pragma once
 
#include <stdint.h>
#include <stdlib.h>
 
#include "clist.h"
#include "event.h"
#include "sched.h"
#include "modules.h"
#include "msg.h"
#include "thread.h"
 
#include "usb.h"
#include "periph/usbdev.h"
#include "usb/descriptor.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#ifndef USBUS_STACKSIZE
#define USBUS_STACKSIZE             (THREAD_STACKSIZE_DEFAULT)
#endif
 
#ifndef USBUS_PRIO
#define USBUS_PRIO                  (THREAD_PRIORITY_MAIN - 6)
#endif
 
#ifndef CONFIG_USBUS_AUTO_ATTACH
/* Check for Kconfig usage */
#if !IS_ACTIVE(CONFIG_MODULE_USBUS)
#define CONFIG_USBUS_AUTO_ATTACH            1
#endif
#endif
 
#ifndef CONFIG_USBUS_MSC_AUTO_MTD
#define CONFIG_USBUS_MSC_AUTO_MTD           1
#endif
 
#if IS_ACTIVE(CONFIG_USBUS_EP0_SIZE_8)
#define CONFIG_USBUS_EP0_SIZE               8
#elif IS_ACTIVE(CONFIG_USBUS_EP0_SIZE_16)
#define CONFIG_USBUS_EP0_SIZE              16
#elif IS_ACTIVE(CONFIG_USBUS_EP0_SIZE_32)
#define CONFIG_USBUS_EP0_SIZE              32
#elif IS_ACTIVE(CONFIG_USBUS_EP0_SIZE_64)
#define CONFIG_USBUS_EP0_SIZE              64
#endif
 
#ifndef CONFIG_USBUS_EP0_SIZE
#define CONFIG_USBUS_EP0_SIZE              64
#endif
#define USBUS_TNAME                 "usbus"
 
#define USBUS_THREAD_FLAG_USBDEV    (0x02)  
#define USBUS_THREAD_FLAG_USBDEV_EP (0x04)  
#define USBUS_HANDLER_FLAG_RESET    (0x0001)    
#define USBUS_HANDLER_FLAG_SOF      (0x0002)    
#define USBUS_HANDLER_FLAG_SUSPEND  (0x0004)    
#define USBUS_HANDLER_FLAG_RESUME   (0x0008)    
#define USBUS_HANDLER_FLAG_TR_STALL (0x0020)    
#define USBUS_URB_FLAG_AUTO_ZLP     (0x0001)
 
#define USBUS_URB_FLAG_NEEDS_ZLP    (0x1000)
 
#define USBUS_URB_FLAG_CANCELLED    (0x2000)
typedef enum {
    USBUS_EVENT_USB_RESET,      
    USBUS_EVENT_USB_SOF,        
    USBUS_EVENT_USB_SUSPEND,    
    USBUS_EVENT_USB_RESUME,     
} usbus_event_usb_t;
 
typedef enum {
    USBUS_EVENT_TRANSFER_COMPLETE,  
    USBUS_EVENT_TRANSFER_FAIL,      
    USBUS_EVENT_TRANSFER_STALL,     
} usbus_event_transfer_t;
 
typedef enum {
    USBUS_STATE_DISCONNECT, 
    USBUS_STATE_RESET,      
    USBUS_STATE_ADDR,       
    USBUS_STATE_CONFIGURED, 
    USBUS_STATE_SUSPEND,    
} usbus_state_t;
 
typedef enum {
    USBUS_CONTROL_REQUEST_STATE_READY,    
    USBUS_CONTROL_REQUEST_STATE_INDATA,   
    USBUS_CONTROL_REQUEST_STATE_OUTACK,   
    USBUS_CONTROL_REQUEST_STATE_OUTDATA,  
    USBUS_CONTROL_REQUEST_STATE_INACK,    
} usbus_control_request_state_t;
 
typedef struct usbus_string {
    struct usbus_string *next;  
    const char *str;            
    uint16_t idx;               
} usbus_string_t;
 
typedef struct usbus usbus_t;
 
typedef struct usbus_handler usbus_handler_t;
 
typedef enum {
    USBUS_DESCR_LEN_FIXED,  
    USBUS_DESCR_LEN_FUNC,   
} usbus_descr_len_type_t;
 
typedef struct {
    size_t (*fmt_pre_descriptor)(usbus_t *usbus, void *arg);
 
    size_t (*fmt_post_descriptor)(usbus_t *usbus, void *arg);
    union {
        size_t (*get_descriptor_len)(usbus_t *usbus, void *arg);
        size_t fixed_len;
    } len;                            
    usbus_descr_len_type_t len_type;  
} usbus_descr_gen_funcs_t;
 
typedef struct usbus_descr_gen {
    struct usbus_descr_gen *next;         
    const usbus_descr_gen_funcs_t *funcs; 
    void *arg;                            
} usbus_descr_gen_t;
 
typedef struct usbus_endpoint {
    struct usbus_endpoint *next;    
    usbus_descr_gen_t *descr_gen;   
    usbdev_ep_t *ep;                
#ifdef MODULE_USBUS_URB
    clist_node_t urb_list;          
#endif
    uint16_t maxpacketsize;         
    uint8_t interval;               
    bool active;                    
    bool halted;                    
} usbus_endpoint_t;
 
typedef struct usbus_urb {
    clist_node_t list;  
    uint32_t flags;     
    uint8_t *buf;       
    size_t len;         
    size_t transferred; 
} usbus_urb_t;
 
typedef struct usbus_interface_alt {
    struct usbus_interface_alt *next;   
    usbus_descr_gen_t *descr_gen;       
    usbus_endpoint_t *ep;               
    usbus_string_t *descr;              
} usbus_interface_alt_t;
 
typedef struct usbus_interface {
    struct usbus_interface *next;       
    usbus_descr_gen_t *descr_gen;       
    usbus_endpoint_t *ep;               
    struct usbus_interface_alt *alts;   
    usbus_handler_t *handler;           
    usbus_string_t *descr;              
    uint16_t idx;                       
    uint8_t class;                      
    uint8_t subclass;                   
    uint8_t protocol;                   
} usbus_interface_t;
 
typedef struct usbus_handler_driver {
 
    void (*init)(usbus_t * usbus, struct usbus_handler *handler);
 
    void (*event_handler)(usbus_t * usbus, struct usbus_handler *handler,
                          usbus_event_usb_t event);
 
    void (*transfer_handler)(usbus_t * usbus, struct usbus_handler *handler,
                             usbdev_ep_t *ep, usbus_event_transfer_t event);
 
    int (*control_handler)(usbus_t * usbus, struct usbus_handler *handler,
                           usbus_control_request_state_t state,
                           usb_setup_t *request);
} usbus_handler_driver_t;
 
struct usbus_handler {
    struct usbus_handler *next;             
    const usbus_handler_driver_t *driver;   
    usbus_interface_t *iface;               
    uint32_t flags;                         
};
 
struct usbus {
    usbus_string_t manuf;                           
    usbus_string_t product;                         
    usbus_string_t config;                          
    usbus_string_t serial;                          
    usbus_endpoint_t ep_out[USBDEV_NUM_ENDPOINTS];  
    usbus_endpoint_t ep_in[USBDEV_NUM_ENDPOINTS];   
    event_queue_t queue;                            
    usbdev_t *dev;                                  
    usbus_handler_t *control;                       
    usbus_descr_gen_t *descr_gen;                   
    usbus_string_t *strings;                        
    usbus_interface_t *iface;                       
    usbus_handler_t *handlers;                      
    uint32_t ep_events;                             
    kernel_pid_t pid;                               
    uint16_t str_idx;                               
    usbus_state_t state;                            
    usbus_state_t pstate;                           
    uint8_t addr;                                   
    bool wakeup_enabled;                            
#ifndef CONFIG_USB_SERIAL_STR
    char serial_str[2 * CONFIG_USB_SERIAL_BYTE_LENGTH + 1];
#endif
};
 
static inline void usbus_event_post(usbus_t *usbus, event_t *event)
{
    event_post(&usbus->queue, event);
}
 
uint16_t usbus_add_string_descriptor(usbus_t *usbus, usbus_string_t *desc,
                                     const char *str);
 
uint16_t usbus_add_interface(usbus_t *usbus, usbus_interface_t *iface);
 
void usbus_add_interface_alt(usbus_interface_t *iface,
                                 usbus_interface_alt_t *alt);
 
usbus_endpoint_t *usbus_interface_find_endpoint(usbus_interface_t *interface,
                                                usb_ep_type_t type,
                                                usb_ep_dir_t dir);
 
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);
 
void usbus_add_conf_descriptor(usbus_t *usbus, usbus_descr_gen_t *descr_gen);
 
void usbus_register_event_handler(usbus_t *usbus, usbus_handler_t *handler);
 
void usbus_init(usbus_t *usbus, usbdev_t *usbdev);
 
size_t usbus_max_bulk_endpoint_size(usbus_t *usbus);
 
size_t usbus_max_interrupt_endpoint_size(usbus_t *usbus);
 
void usbus_create(char *stack, int stacksize, char priority,
                  const char *name, usbus_t *usbus);
 
static inline void usbus_urb_init(usbus_urb_t *urb,
                                  uint8_t *buf,
                                  size_t len,
                                  uint32_t flags)
{
    urb->buf = buf;
    urb->len = len;
    urb->flags = flags;
    urb->transferred = 0;
}
 
void usbus_urb_submit(usbus_t *usbus, usbus_endpoint_t *endpoint, usbus_urb_t *urb);
 
int usbus_urb_cancel(usbus_t *usbus, usbus_endpoint_t *endpoint, usbus_urb_t *urb);
 
void usbus_endpoint_halt(usbus_endpoint_t *ep);
 
void usbus_endpoint_clear_halt(usbus_endpoint_t *ep);
 
static inline void usbus_enable_endpoint(usbus_endpoint_t *ep)
{
    ep->active = true;
}
 
static inline void usbus_disable_endpoint(usbus_endpoint_t *ep)
{
    ep->active = false;
}
 
static inline void usbus_handler_set_flag(usbus_handler_t *handler,
                                          uint32_t flag)
{
    handler->flags |= flag;
}
 
static inline void usbus_handler_remove_flag(usbus_handler_t *handler,
                                             uint32_t flag)
{
    handler->flags &= ~flag;
}
 
static inline bool usbus_handler_isset_flag(usbus_handler_t *handler,
                                            uint32_t flag)
{
    return handler->flags & flag;
}
 
static inline void usbus_urb_set_flag(usbus_urb_t *urb,
                                      uint32_t flag)
{
    urb->flags |= flag;
}
 
static inline void usbus_urb_remove_flag(usbus_urb_t *urb,
                                         uint32_t flag)
{
    urb->flags &= ~flag;
}
 
static inline bool usbus_urb_isset_flag(usbus_urb_t *urb,
                                        uint32_t flag)
{
    return urb->flags & flag;
}
 
#ifdef __cplusplus
}
#endif