Mirrors
/
MicroAPRS
mirror of https://github.com/markqvist/MicroAPRS.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
MicroAPRS/bertos/drv/usb.h

532 lines
15 KiB
C
Raw Blame History

/**
* \file
* <!--
* This file is part of BeRTOS.
*
* Bertos is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*
* As a special exception, you may use this file as part of a free software
* library without restriction. Specifically, if other files instantiate
* templates or use macros or inline functions from this file, or you compile
* this file and link it with other files to produce an executable, this
* file does not by itself cause the resulting executable to be covered by
* the GNU General Public License. This exception does not however
* invalidate any other reasons why the executable file might be covered by
* the GNU General Public License.
*
* Copyright 2010 Develer S.r.l. (http://www.develer.com/)
*
* -->
*
* \author Andrea Righi <arighi@develer.com>
*
* \brief USB 2.0 standard descriptors
*
* This file holds USB constants and structures that are needed for USB device
* APIs, as defined in the USB 2.0 specification.
*
* \attention The API is work in progress and may change in future versions.
*
* $WIZ$ module_name = "usb"
* $WIZ$ module_configuration = "bertos/cfg/cfg_usb.h"
* $WIZ$ module_supports = "stm32"
*/
#ifndef USB_H
#define USB_H
#include <cpu/byteorder.h>
#define usb_cpu_to_le16(x) cpu_to_le16(x)
#define usb_le16_to_cpu(x) le16_to_cpu(x)
#define usb_cpu_to_le32(x) cpu_to_le32(x)
#define usb_le32_to_cpu(x) le32_to_cpu(x)
/* State of a USB device */
enum usb_device_state {
USB_STATE_NOTATTACHED = 0,
/* chapter 9 device states */
USB_STATE_ATTACHED,
USB_STATE_POWERED, /* wired */
USB_STATE_DEFAULT, /* limited function */
USB_STATE_ADDRESS,
USB_STATE_CONFIGURED, /* most functions */
};
/*
* USB directions
*
* This bit flag is used in endpoint descriptors' bEndpointAddress field.
* It's also one of three fields in control requests bRequestType.
*/
#define USB_DIR_OUT 0 /* to device */
#define USB_DIR_IN 0x80 /* to host */
#define USB_DIR_MASK 0x80
/*
* USB types, the second of three bRequestType fields
*/
#define USB_TYPE_MASK (0x03 << 5)
#define USB_TYPE_STANDARD (0x00 << 5)
#define USB_TYPE_CLASS (0x01 << 5)
#define USB_TYPE_VENDOR (0x02 << 5)
#define USB_TYPE_RESERVED (0x03 << 5)
/*
* USB recipients, the third of three bRequestType fields
*/
#define USB_RECIP_MASK 0x1f
#define USB_RECIP_DEVICE 0x00
#define USB_RECIP_INTERFACE 0x01
#define USB_RECIP_ENDPOINT 0x02
#define USB_RECIP_OTHER 0x03
/*
* USB standard requests, for the bRequest field of a SETUP packet.
*/
#define USB_REQ_GET_STATUS 0x00
#define USB_REQ_CLEAR_FEATURE 0x01
#define USB_REQ_SET_FEATURE 0x03
#define USB_REQ_SET_ADDRESS 0x05
#define USB_REQ_GET_DESCRIPTOR 0x06
#define USB_REQ_SET_DESCRIPTOR 0x07
#define USB_REQ_GET_CONFIGURATION 0x08
#define USB_REQ_SET_CONFIGURATION 0x09
#define USB_REQ_GET_INTERFACE 0x0A
#define USB_REQ_SET_INTERFACE 0x0B
#define USB_REQ_SYNCH_FRAME 0x0C
/*
* Descriptor types ... USB 2.0 spec table 9.5
*/
#define USB_DT_DEVICE 0x01
#define USB_DT_CONFIG 0x02
#define USB_DT_STRING 0x03
#define USB_DT_INTERFACE 0x04
#define USB_DT_ENDPOINT 0x05
#define USB_DT_DEVICE_QUALIFIER 0x06
#define USB_DT_OTHER_SPEED_CONFIG 0x07
#define USB_DT_INTERFACE_POWER 0x08
/*
* Conventional codes for class-specific descriptors. The convention is
* defined in the USB "Common Class" Spec (3.11). Individual class specs
* are authoritative for their usage, not the "common class" writeup.
*/
#define USB_DT_CS_DEVICE (USB_TYPE_CLASS | USB_DT_DEVICE)
#define USB_DT_CS_CONFIG (USB_TYPE_CLASS | USB_DT_CONFIG)
#define USB_DT_CS_STRING (USB_TYPE_CLASS | USB_DT_STRING)
#define USB_DT_CS_INTERFACE (USB_TYPE_CLASS | USB_DT_INTERFACE)
#define USB_DT_CS_ENDPOINT (USB_TYPE_CLASS | USB_DT_ENDPOINT)
/**
*
* USB Control Request descriptor
*
* This structure is used to send control requests to a USB device.
*
* It matches the different fields of the USB 2.0 specification (section 9.3,
* table 9-2).
*/
typedef struct UsbCtrlRequest
{
uint8_t mRequestType;
uint8_t bRequest;
uint16_t wValue;
uint16_t wIndex;
uint16_t wLength;
} PACKED UsbCtrlRequest;
/**
* USB common descriptor header.
*
* \note All the USB standard descriptors have these 2 fields at the beginning.
*/
typedef struct UsbDescHeader
{
uint8_t bLength;
uint8_t bDescriptorType;
} PACKED UsbDescHeader;
/**
* USB Device descriptor
*
* \note See USB 2.0 specification.
*/
typedef struct UsbDeviceDesc
{
uint8_t bLength;
uint8_t bDescriptorType;
uint16_t bcdUSB;
uint8_t bDeviceClass;
uint8_t bDeviceSubClass;
uint8_t bDeviceProtocol;
uint8_t bMaxPacketSize0;
uint16_t idVendor;
uint16_t idProduct;
uint16_t bcdDevice;
uint8_t iManufacturer;
uint8_t iProduct;
uint8_t iSerialNumber;
uint8_t bNumConfigurations;
} PACKED UsbDeviceDesc;
/**
* USB string descriptor.
*
* \note See USB 2.0 specification.
*/
typedef struct UsbStringDesc
{
uint8_t bLength;
uint8_t bDescriptorType;
uint8_t data[0];
} PACKED UsbStringDesc;
#define USB_STRING_1(__a, ...) __a "\x00"
#define USB_STRING_2(__a, ...) __a "\x00" USB_STRING_1(__VA_ARGS__)
#define USB_STRING_3(__a, ...) __a "\x00" USB_STRING_2(__VA_ARGS__)
#define USB_STRING_4(__a, ...) __a "\x00" USB_STRING_3(__VA_ARGS__)
#define USB_STRING_5(__a, ...) __a "\x00" USB_STRING_4(__VA_ARGS__)
#define USB_STRING_6(__a, ...) __a "\x00" USB_STRING_5(__VA_ARGS__)
#define USB_STRING_7(__a, ...) __a "\x00" USB_STRING_6(__VA_ARGS__)
#define USB_STRING_8(__a, ...) __a "\x00" USB_STRING_7(__VA_ARGS__)
#define USB_STRING_9(__a, ...) __a "\x00" USB_STRING_8(__VA_ARGS__)
#define USB_STRING_10(__a, ...) __a "\x00" USB_STRING_9(__VA_ARGS__)
#define USB_STRING_11(__a, ...) __a "\x00" USB_STRING_10(__VA_ARGS__)
#define USB_STRING_12(__a, ...) __a "\x00" USB_STRING_11(__VA_ARGS__)
#define USB_STRING_13(__a, ...) __a "\x00" USB_STRING_12(__VA_ARGS__)
#define USB_STRING_14(__a, ...) __a "\x00" USB_STRING_13(__VA_ARGS__)
#define USB_STRING_15(__a, ...) __a "\x00" USB_STRING_14(__VA_ARGS__)
#define USB_STRING_16(__a, ...) __a "\x00" USB_STRING_15(__VA_ARGS__)
/**
* Pack a list with a variable number of elements into a UTF-16LE USB string.
*
* \note The macro is recursively defined according the number of elements
* passed as argument. At the moment we support strings with up to 16
* characters.
*/
#define USB_STRING(...) PP_CAT(USB_STRING_, PP_COUNT(__VA_ARGS__))(__VA_ARGS__)
/**
* Define and initialize an USB string descriptor.
*
* This macro is reuquired to properly declare and initialize a constant USB
* string in UTF-16LE format.
*
* The structure must contain the standard common USB header (UsbDescHeader)
* and the UTF-16LE string all packed in a contiguous memory region.
*/
#define DEFINE_USB_STRING(__name, __text) \
struct { \
UsbDescHeader __header; \
uint8_t __body[sizeof(__text)]; \
} PACKED __name = { \
.__header = { \
.bLength = \
cpu_to_le16((uint16_t)sizeof(__name)), \
.bDescriptorType = USB_DT_STRING, \
}, \
.__body = {__text}, \
}
/*
* Device and/or Interface Class codes as found in bDeviceClass or
* bInterfaceClass and defined by www.usb.org documents.
*/
#define USB_CLASS_PER_INTERFACE 0 /* for DeviceClass */
#define USB_CLASS_AUDIO 1
#define USB_CLASS_COMM 2
#define USB_CLASS_HID 3
#define USB_CLASS_PHYSICAL 5
#define USB_CLASS_STILL_IMAGE 6
#define USB_CLASS_PRINTER 7
#define USB_CLASS_MASS_STORAGE 8
#define USB_CLASS_HUB 9
#define USB_CLASS_CDC_DATA 0x0a
#define USB_CLASS_CSCID 0x0b /* chip+ smart card */
#define USB_CLASS_CONTENT_SEC 0x0d /* content security */
#define USB_CLASS_VIDEO 0x0e
#define USB_CLASS_WIRELESS_CONTROLLER 0xe0
#define USB_CLASS_MISC 0xef
#define USB_CLASS_APP_SPEC 0xfe
#define USB_CLASS_VENDOR_SPEC 0xff
/* USB Device subclasses */
#define USB_CDC_SUBCLASS_ACM 0x02
#define USB_CDC_SUBCLASS_ETHERNET 0x06
#define USB_CDC_SUBCLASS_WHCM 0x08
#define USB_CDC_SUBCLASS_DMM 0x09
#define USB_CDC_SUBCLASS_MDLM 0x0a
#define USB_CDC_SUBCLASS_OBEX 0x0b
#define USB_CDC_SUBCLASS_EEM 0x0c
#define USB_CDC_SUBCLASS_NCM 0x0d
/**
* Device configuration descriptor
*
* \note See USB 2.0 specification.
*/
typedef struct UsbConfigDesc
{
uint8_t bLength;
uint8_t bDescriptorType;
uint16_t wTotalLength;
uint8_t bNumInterfaces;
uint8_t bConfigurationValue;
uint8_t iConfiguration;
uint8_t bmAttributes;
uint8_t bMaxPower;
} PACKED UsbConfigDesc;
/* from config descriptor bmAttributes */
#define USB_CONFIG_ATT_ONE (1 << 7) /* must be set */
#define USB_CONFIG_ATT_SELFPOWER (1 << 6) /* self powered */
#define USB_CONFIG_ATT_WAKEUP (1 << 5) /* can wakeup */
#define USB_CONFIG_ATT_BATTERY (1 << 4) /* battery powered */
/**
* Device interface descriptor
*
* \note See USB 2.0 specification.
*/
typedef struct UsbInterfaceDesc
{
uint8_t bLength;
uint8_t bDescriptorType;
uint8_t bInterfaceNumber;
uint8_t bAlternateSetting;
uint8_t bNumEndpoints;
uint8_t bInterfaceClass;
uint8_t bInterfaceSubClass;
uint8_t bInterfaceProtocol;
uint8_t iInterface;
} PACKED UsbInterfaceDesc;
/**
* Endpoint descriptor
*
* \note See USB 2.0 specification.
*/
typedef struct UsbEndpointDesc
{
uint8_t bLength;
uint8_t bDescriptorType;
uint8_t bEndpointAddress;
uint8_t bmAttributes;
uint16_t wMaxPacketSize;
uint8_t bInterval;
} PACKED UsbEndpointDesc;
/*
* Endpoints
*/
#define USB_ENDPOINT_NUMBER_MASK 0x0f /* in bEndpointAddress */
#define USB_ENDPOINT_DIR_MASK USB_DIR_MASK
#define USB_ENDPOINT_SYNCTYPE 0x0c
#define USB_ENDPOINT_SYNC_NONE (0 << 2)
#define USB_ENDPOINT_SYNC_ASYNC (1 << 2)
#define USB_ENDPOINT_SYNC_ADAPTIVE (2 << 2)
#define USB_ENDPOINT_SYNC_SYNC (3 << 2)
#define USB_ENDPOINT_XFERTYPE_MASK 0x03 /* in bmAttributes */
#define USB_ENDPOINT_XFER_CONTROL 0
#define USB_ENDPOINT_XFER_ISOC 1
#define USB_ENDPOINT_XFER_BULK 2
#define USB_ENDPOINT_XFER_INT 3
#define USB_ENDPOINT_MAX_ADJUSTABLE 0x80
/**
* USB: generic device descriptor
*/
typedef struct UsbDevice
{
UsbDeviceDesc *device; ///< USB 2.0 device descriptor
const UsbDescHeader **config; ///< USB 2.0 configuration descriptors
const UsbStringDesc **strings; ///< USB strings
/* Callbacks */
void (*event_cb)(UsbCtrlRequest *); ///< Called to handle control requests.
/* Private data */
bool configured; ///< True when the device has been correctly initialized.
} UsbDevice;
/**
* Get the endpoint's address number of \a epd.
*/
INLINE int usb_endpointNum(const UsbEndpointDesc *epd)
{
return epd->bEndpointAddress & USB_ENDPOINT_NUMBER_MASK;
}
/**
* Get the transfer type of the endpoint \a epd.
*/
INLINE int usb_endpointType(const struct UsbEndpointDesc *epd)
{
return epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK;
}
/**
* Check if the endpoint \a epd has IN direction.
*/
INLINE int usb_endpointDirIn(const struct UsbEndpointDesc *epd)
{
return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_IN);
}
/**
* Check if the endpoint \a epd has OUT direction.
*/
INLINE int usb_endpointDirOut(const struct UsbEndpointDesc *epd)
{
return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_OUT);
}
/**
* Check if the endpoint \a epd has bulk transfer type.
*/
INLINE int usb_endpointXferBulk(const struct UsbEndpointDesc *epd)
{
return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
USB_ENDPOINT_XFER_BULK);
}
/**
* Check if the endpoint \a epd has control transfer type.
*/
INLINE int usb_endpointXferControl(const struct UsbEndpointDesc *epd)
{
return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
USB_ENDPOINT_XFER_CONTROL);
}
/**
* Check if the endpoint \a epd has interrupt transfer type.
*/
INLINE int usb_endpointXferInt(const struct UsbEndpointDesc *epd)
{
return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
USB_ENDPOINT_XFER_INT);
}
/**
* Check if the endpoint \a epd has isochronous transfer type.
*/
INLINE int usb_endpointXferIsoc(const struct UsbEndpointDesc *epd)
{
return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
USB_ENDPOINT_XFER_ISOC);
}
/**
* Check if the endpoint \a epd is bulk IN.
*/
INLINE int usb_endpointIsBulkIn(const struct UsbEndpointDesc *epd)
{
return usb_endpointXferBulk(epd) && usb_endpointDirIn(epd);
}
/**
* Check if the endpoint \a epd is bulk OUT.
*/
INLINE int usb_endpointIsBulkOut(const struct UsbEndpointDesc *epd)
{
return usb_endpointXferBulk(epd) && usb_endpointDirOut(epd);
}
/**
* Check if the endpoint \a epd is interrupt IN.
*/
INLINE int usb_endpointIsIntIn(const struct UsbEndpointDesc *epd)
{
return usb_endpointXferInt(epd) && usb_endpointDirIn(epd);
}
/**
* Check if the endpoint \a epd is interrupt OUT.
*/
INLINE int usb_endpointIsIntOut(const struct UsbEndpointDesc *epd)
{
return usb_endpointXferInt(epd) && usb_endpointDirOut(epd);
}
/**
* Check if the endpoint \a epd is isochronous IN.
*/
INLINE int usb_endpointIsIsocIn(const struct UsbEndpointDesc *epd)
{
return usb_endpointXferIsoc(epd) && usb_endpointDirIn(epd);
}
/**
* Check if the endpoint \a epd is isochronous OUT.
*/
INLINE int usb_endpointIsIsocOut(const struct UsbEndpointDesc *epd)
{
return usb_endpointXferIsoc(epd) && usb_endpointDirOut(epd);
}
/**
* Read up to \a size bytes from the USB endpoint identified by the address
* \a ep and store them in \a buffer.
*
* The \a timeout is an upper bound on the amount of time (in ticks) elapsed
* before returns. If \a timeout is zero, the the function returns immediatly
* and it basically works in non-blocking fashion. A negative value for \a
* timeout means that the function can block indefinitely.
*
* \return number of bytes actually read, or a negative value in case of
* errors.
*/
ssize_t usb_endpointReadTimeout(int ep, void *buffer, ssize_t size,
ticks_t timeout);
INLINE ssize_t usb_endpointRead(int ep, void *buffer, ssize_t size)
{
return usb_endpointReadTimeout(ep, buffer, size, -1);
}
/**
* Write up to \a size bytes from the buffer pointed \a buffer to the USB
* endpoint identified by the address \a ep.
*
* The \a timeout is an upper bound on the amount of time (in ticks) elapsed
* before returns. If \a timeout is zero, the the function returns immediatly
* and it basically works in non-blocking fashion. A negative value for \a
* timeout means that the function can block indefinitely.
*
* \return number of bytes actually wrote, or a negative value in case of
* errors.
*/
ssize_t usb_endpointWriteTimeout(int ep, const void *buffer, ssize_t size,
ticks_t timeout);
INLINE ssize_t usb_endpointWrite(int ep, const void *buffer, ssize_t size)
{
return usb_endpointWriteTimeout(ep, buffer, size, -1);
}
/**
* Register a generic USB device driver \a dev in the USB controller.
*/
int usb_deviceRegister(UsbDevice *dev);
#endif /* USB_H */
Reference in New Issue View Git Blame Copy Permalink