nut-debian/drivers/usb-common.h

522 lines
19 KiB
C
Raw Normal View History

2010-03-26 01:20:59 +02:00
/* usb-common.h - prototypes for the common useful USB functions
2022-07-10 10:23:45 +03:00
* NOTE that it aims to consolidate use of different USB-related APIs
* such as libusb-0.1 and libusb-1.0 in a way that minimizes the coding
* difference for majority of NUT - so typedef'ing or converting various
* data types and method signatures.
*
* Beside your system headers (content varies between distros) you can
* find some documentation online:
* - libusb-1.0:
* https://github.com/libusb/libusb/blob/master/libusb/libusb.h
* https://libusb.sourceforge.io/api-1.0/
* https://libusb.sourceforge.io/api-1.0/libusb_api.html
* https://github.com/libusb/libusb/wiki
* https://nxmnpg.lemoda.net/3/libusb (one page, easy to search)
* - libusb-0.1 is nowadays hard to find, original web-site and
* sourceforge project were discontinued over the past years.
* A rendered copy of the libusb-0.1 Developers Guide was noted at:
* http://transit.iut2.upmf-grenoble.fr/doc/libusb-dev/html/index.html
* http://transit.iut2.upmf-grenoble.fr/doc/libusb-dev/html/functions.html
* Original SGML for that seems to be in source tarball such as
* http://deb.debian.org/debian/pool/main/libu/libusb/libusb_0.1.12.orig.tar.gz
*
* Related (but currently not directly used) projects include:
* - libusb-win32 port based on libusb-0.1 API (bug-fix-only mode,
* new projects should use libusb Windows backend):
* https://sourceforge.net/p/libusb-win32/wiki/Documentation/
* - (Currently not in NUT codebase scope, but might help...)
* > A compatibility layer allowing applications written for
* > libusb-0.1 to work with libusb-1.0. libusb-compat-0.1
* > attempts to look, feel, smell and walk like libusb-0.1.
* Mostly. Details (and known differences) documented at:
* https://github.com/libusb/libusb-compat-0.1
*
* Also note that at least currently this does not deal with non-libusb
* APIs (important when looking for method signatures in documentation,
* since e.g. Linux Kernel USB subsystem uses some of libusb-0.1 method
* names, but with different set, type and order of arguments!)
2010-03-26 01:20:59 +02:00
2022-07-10 10:23:45 +03:00
Copyright (C) 2008 - 2016 Arnaud Quette <arnaud.quette@gmail.com>
Copyright (C) 2021 Jim Klimov <jimklimov+nut@gmail.com>
2010-03-26 01:20:59 +02:00
This program 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#ifndef NUT_USB_COMMON_H
#define NUT_USB_COMMON_H
2022-07-10 10:23:45 +03:00
#include "config.h" /* be sure to know all about the system config */
/* Note: usb-common.h (this file) is included by nut_libusb.h,
* so not looping the includes ;)
*/
#include "nut_stdint.h" /* for uint16_t, UINT16_MAX, PRIsize, etc. */
#include "common.h" /* for fatalx() etc. */
#if defined HAVE_LIMITS_H
# include <limits.h> /* PATH_MAX for usb.h, among other stuff */
#endif
#if defined HAVE_SYS_PARAM_H
# include <sys/param.h>
#endif
2010-03-26 01:20:59 +02:00
#include <regex.h>
2022-07-10 10:23:45 +03:00
#if (!WITH_LIBUSB_1_0) && (!WITH_LIBUSB_0_1)
#error "configure script error: Neither WITH_LIBUSB_1_0 nor WITH_LIBUSB_0_1 is set"
#endif
#if (WITH_LIBUSB_1_0) && (WITH_LIBUSB_0_1)
#error "configure script error: Both WITH_LIBUSB_1_0 and WITH_LIBUSB_0_1 are set"
#endif
/* Select version-specific libusb header file and define a sort of
* "Compatibility layer" between libusb 0.1 and 1.0
*/
#if WITH_LIBUSB_1_0
# include <libusb.h>
/* Simply remap libusb functions/structures from 0.1 to 1.0 */
/* Structures */
/* #define usb_dev_handle libusb_device_handle */
typedef libusb_device_handle usb_dev_handle;
/* These typedefs are also named in libshut.h, so we can consistenly
* handle the "ifdef SHUT_MODE" handling in libhid.c and some drivers.
* These symbolic names are used in all the headers and are expected to
* match binary code of object files at (monolithic) driver build time.
*
* The MIN/MAX definitions here are primarily to generalize range-check
* code (especially if anything is done outside the libraries).
* FIXME: It may make sense to constrain the limits to lowest common
* denominator that should fit alll of libusb-0.1, libusb-1.0 and libshut,
* so that any build of the practical (driver) code knows to not exceed
* any use-case.
*/
typedef uint8_t usb_ctrl_requesttype;
#define USB_CTRL_REQUESTTYPE_MIN 0
#define USB_CTRL_REQUESTTYPE_MAX UINT8_MAX
typedef uint8_t usb_ctrl_request;
#define USB_CTRL_REQUEST_MIN 0
#define USB_CTRL_REQUEST_MAX UINT8_MAX
typedef unsigned char usb_ctrl_endpoint;
#define USB_CTRL_ENDPOINT_MIN 0
#define USB_CTRL_ENDPOINT_MAX UCHAR_MAX
typedef uint16_t usb_ctrl_msgvalue;
#define USB_CTRL_MSGVALUE_MIN 0
#define USB_CTRL_MSGVALUE_MAX UINT16_MAX
typedef uint16_t usb_ctrl_repindex;
#define USB_CTRL_REPINDEX_MIN 0
#define USB_CTRL_REPINDEX_MAX UINT16_MAX
typedef uint8_t usb_ctrl_strindex;
#define USB_CTRL_STRINDEX_MIN 0
#define USB_CTRL_STRINDEX_MAX UINT8_MAX
typedef uint8_t usb_ctrl_descindex;
#define USB_CTRL_DESCINDEX_MIN 0
#define USB_CTRL_DESCINDEX_MAX UINT8_MAX
typedef unsigned char* usb_ctrl_charbuf;
typedef unsigned char usb_ctrl_char;
#define USB_CTRL_CHAR_MIN 0
#define USB_CTRL_CHAR_MAX UCHAR_MAX
/* Here MIN/MAX should not matter much, type mostly used for casting */
typedef uint16_t usb_ctrl_charbufsize;
#define USB_CTRL_CHARBUFSIZE_MIN 0
#define USB_CTRL_CHARBUFSIZE_MAX UINT16_MAX
#define PRI_NUT_USB_CTRL_CHARBUFSIZE PRIu16
typedef unsigned int usb_ctrl_timeout_msec; /* in milliseconds */
/* Note: there does not seem to be a standard type
* for milliseconds, like there is an useconds_t */
#define USB_CTRL_TIMEOUTMSEC_MIN 0
#define USB_CTRL_TIMEOUTMSEC_MAX UINT_MAX
/* defines */
#define USB_CLASS_PER_INTERFACE LIBUSB_CLASS_PER_INTERFACE
#define USB_DT_STRING LIBUSB_DT_STRING
#define USB_ENDPOINT_IN LIBUSB_ENDPOINT_IN
#define USB_ENDPOINT_OUT LIBUSB_ENDPOINT_OUT
#define USB_RECIP_ENDPOINT LIBUSB_RECIPIENT_ENDPOINT
#define USB_RECIP_INTERFACE LIBUSB_RECIPIENT_INTERFACE
#define USB_REQ_SET_DESCRIPTOR LIBUSB_REQUEST_SET_DESCRIPTOR
#define USB_TYPE_CLASS LIBUSB_REQUEST_TYPE_CLASS
#define USB_TYPE_VENDOR LIBUSB_REQUEST_TYPE_VENDOR
#define ERROR_ACCESS LIBUSB_ERROR_ACCESS
#define ERROR_BUSY LIBUSB_ERROR_BUSY
#define ERROR_IO LIBUSB_ERROR_IO
#define ERROR_NO_DEVICE LIBUSB_ERROR_NO_DEVICE
#define ERROR_NOT_FOUND LIBUSB_ERROR_NOT_FOUND
#define ERROR_OVERFLOW LIBUSB_ERROR_OVERFLOW
#define ERROR_PIPE LIBUSB_ERROR_PIPE
#define ERROR_TIMEOUT LIBUSB_ERROR_TIMEOUT
/* Functions, including range-checks to convert data types of the two APIs.
* Follows an example from libusb-1.0 headers that liberally cast int args
* of one method to uint16_t to call another; at least we do so with checks: */
#if (defined HAVE_PRAGMA_GCC_DIAGNOSTIC_PUSH_POP_BESIDEFUNC) && (defined HAVE_PRAGMA_GCC_DIAGNOSTIC_IGNORED_UNUSED_FUNCTION)
# pragma GCC diagnostic push
#endif
#ifdef HAVE_PRAGMA_GCC_DIAGNOSTIC_IGNORED_UNUSED_FUNCTION
# pragma GCC diagnostic ignored "-Wunused-function"
#endif
/* #define usb_control_msg libusb_control_transfer */
static inline int usb_control_msg(usb_dev_handle *dev, int requesttype,
int request, int value, int index,
usb_ctrl_charbuf bytes, int size, int timeout)
{
/*
Map from libusb-0.1 API => libusb-1.0 API:
int LIBUSB_CALL libusb_control_transfer(
libusb_device_handle *dev_handle, uint8_t request_type,
uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
unsigned char *data, uint16_t wLength, unsigned int timeout);
Note: In libusb-0.1 bytes was a (char*) but our consumer code
was already fixed to use "usb_ctrl_charbuf" to match other methods.
*/
if (requesttype < 0 || (uintmax_t)requesttype > UINT8_MAX
|| request < 0 || (uintmax_t)request > UINT8_MAX
|| value < 0 || (uintmax_t)value > UINT16_MAX
|| index < 0 || (uintmax_t)index > UINT16_MAX
|| size < 0 || (uintmax_t)size > UINT16_MAX
|| timeout < 0
) {
fatalx(EXIT_FAILURE,
"usb_control_msg() args out of range for libusb_control_transfer() implementation");
}
return libusb_control_transfer(
dev,
(uint8_t)requesttype,
(uint8_t)request,
(uint16_t)value,
(uint16_t)index,
(unsigned char *)bytes,
(uint16_t)size,
(unsigned int) timeout
);
}
static inline int usb_interrupt_read(usb_dev_handle *dev, int ep,
usb_ctrl_charbuf bytes, int size, int timeout)
{
/* NOTE: Also for routines below:
Map from libusb-0.1 API => libusb-1.0 API plus change of logic per below code:
int LIBUSB_CALL libusb_interrupt_transfer(libusb_device_handle *dev_handle,
unsigned char endpoint, unsigned char *data, int length,
int *actual_length, unsigned int timeout);
Note: In libusb-0.1 bytes was a (char*) but our consumer code
was already fixed to use "usb_ctrl_charbuf" to match other methods.
*/
int ret;
if (ep < 0 || (uintmax_t)ep > UCHAR_MAX
|| timeout < 0
) {
fatalx(EXIT_FAILURE,
"usb_interrupt_read() args out of range for libusb_interrupt_transfer() implementation");
}
ret = libusb_interrupt_transfer(dev, (unsigned char)ep, (unsigned char *) bytes,
size, &size, (unsigned int)timeout);
/* In case of success, return the operation size, as done with libusb 0.1 */
return (ret == LIBUSB_SUCCESS)?size:ret;
}
static inline int usb_interrupt_write(usb_dev_handle *dev, int ep,
const usb_ctrl_charbuf bytes, int size, int timeout)
{
/* See conversion comments above */
int ret;
if (ep < 0 || (uintmax_t)ep > UCHAR_MAX
|| timeout < 0
) {
fatalx(EXIT_FAILURE,
"usb_interrupt_write() args out of range for libusb_interrupt_transfer() implementation");
}
ret = libusb_interrupt_transfer(dev, (unsigned char)ep, (unsigned char *) bytes,
size, &size, (unsigned int)timeout);
/* In case of success, return the operation size, as done with libusb 0.1 */
return (ret == LIBUSB_SUCCESS)?size:ret;
}
static inline int usb_bulk_read(usb_dev_handle *dev, int ep,
usb_ctrl_charbuf bytes, int size, int timeout)
{
/* See conversion comments above */
int ret;
if (ep < 0 || (uintmax_t)ep > UCHAR_MAX
|| timeout < 0
) {
fatalx(EXIT_FAILURE,
"usb_bulk_read() args out of range for libusb_interrupt_transfer() implementation");
}
ret = libusb_interrupt_transfer(dev, (unsigned char)ep, (unsigned char *) bytes,
size, &size, (unsigned int)timeout);
/* In case of success, return the operation size, as done with libusb 0.1 */
return (ret == LIBUSB_SUCCESS)?size:ret;
}
static inline int usb_bulk_write(usb_dev_handle *dev, int ep,
usb_ctrl_charbuf bytes, int size, int timeout)
{
/* See conversion comments above */
int ret;
if (ep < 0 || (uintmax_t)ep > UCHAR_MAX
|| timeout < 0
) {
fatalx(EXIT_FAILURE,
"usb_bulk_write() args out of range for libusb_interrupt_transfer() implementation");
}
ret = libusb_interrupt_transfer(dev, (unsigned char)ep, (unsigned char *) bytes,
size, &size, (unsigned int)timeout);
/* In case of success, return the operation size, as done with libusb 0.1 */
return (ret == LIBUSB_SUCCESS)?size:ret;
}
static inline int usb_get_string(usb_dev_handle *dev, int index, int langid,
usb_ctrl_charbuf buf, size_t buflen)
{
/*
Map from libusb-0.1 API (originally "char* buf") => libusb-1.0 API:
int libusb_get_string_descriptor(libusb_device_handle *dev_handle,
uint8_t desc_index, uint16_t langid, unsigned char *data, int length)
*/
if (index < 0 || (uintmax_t)index > UINT8_MAX
|| langid < 0 || (uintmax_t)langid > UINT16_MAX
|| (uintmax_t)buflen > INT_MAX
) {
fatalx(EXIT_FAILURE,
"usb_get_string() args out of range for libusb_get_string_descriptor() implementation");
}
return libusb_get_string_descriptor(
dev,
(uint8_t)index,
(uint16_t)langid,
(unsigned char *)buf,
(int) buflen
);
}
static inline int usb_get_string_simple(usb_dev_handle *dev, int index,
usb_ctrl_charbuf buf, size_t buflen)
{
/*
Map from libusb-0.1 API (originally "char* buf") => libusb-1.0 API:
int LIBUSB_CALL libusb_get_string_descriptor_ascii(libusb_device_handle *dev_handle,
uint8_t desc_index, unsigned char *data, int length);
*/
if (index < 0 || (uintmax_t)index > UINT8_MAX
|| (uintmax_t)buflen > INT_MAX
) {
fatalx(EXIT_FAILURE,
"usb_get_string_simple() args out of range for libusb_get_string_descriptor_ascii() implementation");
}
return libusb_get_string_descriptor_ascii(
dev,
(uint8_t)index,
(unsigned char *)buf,
(int) buflen
);
}
#if (defined HAVE_PRAGMA_GCC_DIAGNOSTIC_PUSH_POP_BESIDEFUNC) && (defined HAVE_PRAGMA_GCC_DIAGNOSTIC_IGNORED_UNUSED_FUNCTION)
# pragma GCC diagnostic pop
#endif
/* Functions for which simple mappings seem to suffice (no build warnings emitted): */
#define usb_claim_interface libusb_claim_interface
#define usb_clear_halt libusb_clear_halt
#define usb_close libusb_close
#define usb_set_configuration libusb_set_configuration
#define usb_release_interface libusb_release_interface
#define usb_reset libusb_reset_device
/* FIXME: some original libusb1.c code cast the (int) argument
* as (enum libusb_error) - should we force that in the macro? */
#define nut_usb_strerror(a) libusb_strerror(a)
#endif /* WITH_LIBUSB_1_0 */
/* Note: Checked above that in practice we handle some one libusb API */
#if WITH_LIBUSB_0_1
# include <usb.h>
/* Structures */
/* See detailed comments above, in libusb-1.0 definitions
* FIXME: It may make sense to constrain the limits to lowest common
* denominator that should fit alll of libusb-0.1, libusb-1.0 and libshut,
* so that any build of the practical (driver) code knows to not exceed
* any use-case.
*/
/* no typedef for usb_dev_handle - part of libusb-0.1 API names */
typedef int usb_ctrl_requesttype;
#define USB_CTRL_REQUESTTYPE_MIN INT_MIN
#define USB_CTRL_REQUESTTYPE_MAX INT_MAX
typedef int usb_ctrl_request;
#define USB_CTRL_REQUEST_MIN INT_MIN
#define USB_CTRL_REQUEST_MAX INT_MAX
typedef int usb_ctrl_endpoint;
#define USB_CTRL_ENDPOINT_MIN INT_MIN
#define USB_CTRL_ENDPOINT_MAX INT_MAX
typedef int usb_ctrl_msgvalue;
#define USB_CTRL_MSGVALUE_MIN INT_MIN
#define USB_CTRL_MSGVALUE_MAX INT_MAX
typedef int usb_ctrl_repindex;
#define USB_CTRL_REPINDEX_MIN INT_MIN
#define USB_CTRL_REPINDEX_MAX INT_MAX
typedef int usb_ctrl_strindex;
#define USB_CTRL_STRINDEX_MIN INT_MIN
#define USB_CTRL_STRINDEX_MAX INT_MAX
typedef int usb_ctrl_descindex;
#define USB_CTRL_DESCINDEX_MIN INT_MIN
#define USB_CTRL_DESCINDEX_MAX INT_MAX
/* Here MIN/MAX should not matter much, type mostly used for casting */
typedef char* usb_ctrl_charbuf;
typedef char usb_ctrl_char;
#define USB_CTRL_CHAR_MIN CHAR_MIN
#define USB_CTRL_CHAR_MAX CHAR_MAX
typedef int usb_ctrl_charbufsize;
#define USB_CTRL_CHARBUFSIZE_MIN INT_MIN
#define USB_CTRL_CHARBUFSIZE_MAX INT_MAX
/* There is no PRIi :) So we define directly by spec */
#define PRI_NUT_USB_CTRL_CHARBUFSIZE "i"
typedef int usb_ctrl_timeout_msec; /* in milliseconds */
#define USB_CTRL_TIMEOUTMSEC_MIN INT_MIN
#define USB_CTRL_TIMEOUTMSEC_MAX INT_MAX
/* defines */
#define ERROR_ACCESS -EACCES
#define ERROR_BUSY -EBUSY
#define ERROR_IO -EIO
#define ERROR_NO_DEVICE -ENODEV
#define ERROR_NOT_FOUND -ENOENT
#define ERROR_OVERFLOW -EOVERFLOW
#define ERROR_PIPE -EPIPE
#define ERROR_TIMEOUT -ETIMEDOUT
/* Functions for which simple mappings seem to suffice (no build warnings emitted): */
#define nut_usb_strerror(a) usb_strerror()
#endif /* WITH_LIBUSB_0_1 */
2010-03-26 01:20:59 +02:00
2014-04-22 21:39:47 +03:00
/* USB standard timeout [ms] */
#define USB_TIMEOUT 5000
2010-03-26 01:20:59 +02:00
/*!
* USBDevice_t: Describe a USB device. This structure contains exactly
* the 5 pieces of information by which a USB device identifies
* itself, so it serves as a kind of "fingerprint" of the device. This
* information must be matched exactly when reopening a device, and
* therefore must not be "improved" or updated by a client
* program. Vendor, Product, and Serial can be NULL if the
* corresponding string did not exist or could not be retrieved.
*/
typedef struct USBDevice_s {
2022-07-10 10:23:45 +03:00
/* These 5 data points are common properties of an USB device: */
2016-07-18 03:11:41 +03:00
uint16_t VendorID; /*!< Device's Vendor ID */
uint16_t ProductID; /*!< Device's Product ID */
char *Vendor; /*!< Device's Vendor Name */
char *Product; /*!< Device's Product Name */
char *Serial; /*!< Product serial number */
2022-07-10 10:23:45 +03:00
/* These data points can be determined by the driver for some devices
or by libusb to detail its connection topology: */
2016-07-18 03:11:41 +03:00
char *Bus; /*!< Bus name, e.g. "003" */
uint16_t bcdDevice; /*!< Device release number */
2022-07-10 10:23:45 +03:00
char *Device; /*!< Device name on the bus, e.g. "001" */
2010-03-26 01:20:59 +02:00
} USBDevice_t;
/*!
* USBDeviceMatcher_t: A "USB matcher" is a callback function that
* inputs a USBDevice_t structure, and returns 1 for a match and 0
* for a non-match. Thus, a matcher provides a criterion for
* selecting a USB device. The callback function further is
* expected to return -1 on error with errno set, and -2 on other
* errors. Matchers can be connected in a linked list via the
* "next" field.
*/
typedef struct USBDeviceMatcher_s {
int (*match_function)(USBDevice_t *device, void *privdata);
void *privdata;
struct USBDeviceMatcher_s *next;
} USBDeviceMatcher_t;
/* constructors and destructors for specific types of matchers. An
exact matcher matches a specific usb_device_t structure (except for
the Bus component, which is ignored). A regex matcher matches
devices based on a set of regular expressions. The USBNew* functions
return a matcher on success, or -1 on error with errno set. Note
that the "USBFree*" functions only free the current matcher, not
any others that are linked via "next" fields. */
int USBNewExactMatcher(USBDeviceMatcher_t **matcher, USBDevice_t *hd);
int USBNewRegexMatcher(USBDeviceMatcher_t **matcher, char **regex, int cflags);
void USBFreeExactMatcher(USBDeviceMatcher_t *matcher);
void USBFreeRegexMatcher(USBDeviceMatcher_t *matcher);
/* dummy USB function and macro, inspired from the Linux kernel
2012-01-24 12:22:33 +02:00
* this allows USB information extraction */
2010-03-26 01:20:59 +02:00
#define USB_DEVICE(vendorID, productID) vendorID, productID
typedef struct {
2022-07-10 10:23:45 +03:00
uint16_t vendorID;
uint16_t productID;
2013-11-24 17:00:12 +02:00
void *(*fun)(USBDevice_t *); /* handler for specific processing */
2010-03-26 01:20:59 +02:00
} usb_device_id_t;
#define NOT_SUPPORTED 0
#define POSSIBLY_SUPPORTED 1
#define SUPPORTED 2
/* Function used to match a VendorID/ProductID pair against a list of
* supported devices. Return values:
* NOT_SUPPORTED (0), POSSIBLY_SUPPORTED (1) or SUPPORTED (2) */
2022-07-10 10:23:45 +03:00
int is_usb_device_supported(usb_device_id_t *usb_device_id_list,
2013-11-24 17:00:12 +02:00
USBDevice_t *device);
2010-03-26 01:20:59 +02:00
2015-04-30 16:53:36 +03:00
void nut_usb_addvars(void);
2022-07-10 10:23:45 +03:00
/* Tell the users that port="auto" should be used for USB,
* and other values are quietly ignored. Implemented once
* here, to use in several USB-capable drivers. */
void warn_if_bad_usb_port_filename(const char *fn);
2010-03-26 01:20:59 +02:00
#endif /* NUT_USB_COMMON_H */