/* usb-common.h - prototypes for the common useful USB functions * 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!) Copyright (C) 2008 - 2016 Arnaud Quette Copyright (C) 2021 Jim Klimov 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 #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 /* PATH_MAX for usb.h, among other stuff */ #endif #if defined HAVE_SYS_PARAM_H # include #endif #include #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 /* 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 /* 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 */ /* USB standard timeout [ms] */ #define USB_TIMEOUT 5000 /*! * 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 { /* These 5 data points are common properties of an USB device: */ 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 */ /* These data points can be determined by the driver for some devices or by libusb to detail its connection topology: */ char *Bus; /*!< Bus name, e.g. "003" */ uint16_t bcdDevice; /*!< Device release number */ char *Device; /*!< Device name on the bus, e.g. "001" */ } 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 * this allows USB information extraction */ #define USB_DEVICE(vendorID, productID) vendorID, productID typedef struct { uint16_t vendorID; uint16_t productID; void *(*fun)(USBDevice_t *); /* handler for specific processing */ } 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) */ int is_usb_device_supported(usb_device_id_t *usb_device_id_list, USBDevice_t *device); void nut_usb_addvars(void); /* 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); #endif /* NUT_USB_COMMON_H */