libosmousb  1.9.0
Osmocom USB library
libusb.h File Reference
#include <libusb.h>

Go to the source code of this file.

Data Structures

struct  dev_id
 
struct  usb_interface_match
 
struct  osmo_usb_matchspec
 Description of the USB device+interface we're looking for. More...
 

Macros

#define USB_MAX_PATH_LEN   20
 

Functions

char * osmo_libusb_dev_get_path_buf (char *buf, size_t bufsize, libusb_device *dev)
 obtain the string representation of the USB device path of given device. More...
 
char * osmo_libusb_dev_get_path_c (void *ctx, libusb_device *dev)
 obtain the string representation of the USB device path of given device. More...
 
libusb_device ** osmo_libusb_find_matching_usb_devs (void *ctx, struct libusb_context *luctx, const struct dev_id *dev_ids)
 Find USB devices matching the specified list of USB VendorID/ProductIDs. More...
 
libusb_device * osmo_libusb_find_matching_dev_path (struct libusb_context *luctx, const struct dev_id *dev_ids, const char *path)
 Find a USB device of matching VendorID/ProductID at given path. More...
 
libusb_device * osmo_libusb_find_matching_dev_serial (struct libusb_context *luctx, const struct dev_id *dev_ids, const char *serial)
 Find a USB device of matching VendorID/ProductID and given iSerial string. More...
 
int osmo_libusb_dev_find_matching_interfaces (libusb_device *dev, int class, int sub_class, int protocol, struct usb_interface_match *out, unsigned int out_len)
 find a matching interface among all interfaces of the given USB device. More...
 
int osmo_libusb_find_matching_interfaces (libusb_context *luctx, const struct dev_id *dev_ids, int class, int sub_class, int protocol, struct usb_interface_match *out, unsigned int out_len)
 find matching interfaces among a list devices of specified VendorId/ProductID tuples. More...
 
libusb_device_handle * osmo_libusb_open_claim_interface (void *ctx, libusb_context *luctx, const struct usb_interface_match *ifm)
 open matching USB device and claim interface More...
 
void osmo_libusb_match_init (struct osmo_usb_matchspec *cfg, int if_class, int if_subclass, int if_proto)
 
libusb_device_handle * osmo_libusb_find_open_claim (const struct osmo_usb_matchspec *cfg, const struct dev_id *default_dev_ids)
 high-level all-in-one function for USB device, config + interface matching + opening. More...
 
int osmo_libusb_get_ep_addrs (libusb_device_handle *devh, unsigned int if_num, uint8_t *out, uint8_t *in, uint8_t *irq)
 obtain the endpoint addresses for a given USB interface. More...
 
int osmo_libusb_init (libusb_context **luctx)
 
void osmo_libusb_exit (libusb_context *luctx)
 

Macro Definition Documentation

◆ USB_MAX_PATH_LEN

#define USB_MAX_PATH_LEN   20

Function Documentation

◆ osmo_libusb_dev_find_matching_interfaces()

int osmo_libusb_dev_find_matching_interfaces ( libusb_device *  dev,
int  class,
int  sub_class,
int  protocol,
struct usb_interface_match out,
unsigned int  out_len 
)

find a matching interface among all interfaces of the given USB device.

Parameters
[in]devUSB device in which we shall search
[in]classUSB Interface Class to look for
[in]sub_classUSB Interface Subclass to look for
[in]protocolUSB Interface Protocol to look for
[out]outUser-allocated array for storing matches
[in]out_lenLength of out array
Returns
number of matching interfaces; negative in case of error

References usb_interface_match::addr, usb_interface_match::altsetting, usb_interface_match::class, usb_interface_match::configuration, usb_interface_match::interface, osmo_libusb_dev_get_path_buf(), usb_interface_match::path, usb_interface_match::product, usb_interface_match::protocol, usb_interface_match::string_idx, usb_interface_match::sub_class, usb_interface_match::usb_dev, USB_MAX_PATH_LEN, and usb_interface_match::vendor.

Referenced by osmo_libusb_find_matching_interfaces(), and osmo_libusb_find_open_claim().

◆ osmo_libusb_dev_get_path_buf()

char* osmo_libusb_dev_get_path_buf ( char *  buf,
size_t  bufsize,
libusb_device *  dev 
)

obtain the string representation of the USB device path of given device.

Parameters
[out]bufOutput string buffer
[in]bufsizeSize of output string buffer in bytes
[in]devUSB device whose bus path we want to obtain
Returns
pointer to 'buf' in case of success; NULL in case of error

Referenced by osmo_libusb_dev_find_matching_interfaces(), osmo_libusb_dev_get_path_c(), osmo_libusb_find_matching_dev_path(), and osmo_libusb_open_claim_interface().

◆ osmo_libusb_dev_get_path_c()

char* osmo_libusb_dev_get_path_c ( void *  ctx,
libusb_device *  dev 
)

obtain the string representation of the USB device path of given device.

Parameters
[in]talloccontext from which to dynamically allocate output string buffer
[in]devUSB device whose bus path we want to obtain
Returns
pointer to 'buf' in case of success; NULL in case of error

References osmo_libusb_dev_get_path_buf(), and USB_MAX_PATH_LEN.

◆ osmo_libusb_exit()

void osmo_libusb_exit ( libusb_context *  luctx)

◆ osmo_libusb_find_matching_dev_path()

libusb_device* osmo_libusb_find_matching_dev_path ( struct libusb_context *  luctx,
const struct dev_id dev_ids,
const char *  path 
)

Find a USB device of matching VendorID/ProductID at given path.

Parameters
[in]luctxlibusb context on which to operate
[in]dev_idszer-oterminated array of VendorId/ProductId tuples
[in]pathstring representation of USB path
Returns
libusb_device if there was exactly one match; NULL otherwise

References DLUSB, match_dev_ids(), and osmo_libusb_dev_get_path_buf().

Referenced by osmo_libusb_find_open_claim().

◆ osmo_libusb_find_matching_dev_serial()

libusb_device* osmo_libusb_find_matching_dev_serial ( struct libusb_context *  luctx,
const struct dev_id dev_ids,
const char *  serial 
)

Find a USB device of matching VendorID/ProductID and given iSerial string.

Parameters
[in]luctxlibusb context on which to operate
[in]dev_idszer-oterminated array of VendorId/ProductId tuples
[in]serialstring representation of serial number
Returns
libusb_device if there was exactly one match; NULL otherwise

References DLUSB, and match_dev_ids().

◆ osmo_libusb_find_matching_interfaces()

int osmo_libusb_find_matching_interfaces ( libusb_context *  luctx,
const struct dev_id dev_ids,
int  class,
int  sub_class,
int  protocol,
struct usb_interface_match out,
unsigned int  out_len 
)

find matching interfaces among a list devices of specified VendorId/ProductID tuples.

Parameters
[in]luctxlibusb context on which to operate
[in]dev_idszero-terminated array of VendorId/ProductId tuples
[in]classUSB Interface Class to look for
[in]sub_classUSB Interface Subclass to look for
[in]protocolUSB Interface Protocol to look for
[out]outUser-allocated array for storing matches
[in]out_lenLength of out array
Returns
number of matching interfaces; negative in case of error

References osmo_libusb_dev_find_matching_interfaces(), and osmo_libusb_find_matching_usb_devs().

◆ osmo_libusb_find_matching_usb_devs()

libusb_device** osmo_libusb_find_matching_usb_devs ( void *  ctx,
struct libusb_context *  luctx,
const struct dev_id dev_ids 
)

Find USB devices matching the specified list of USB VendorID/ProductIDs.

Parameters
[in]ctxtalloc context from which to allocate output data
[in]luctxlibusb context on which to operate
[in]dev_idszero-terminated array of VendorId/ProductId tuples
Returns
array of up to 256 libusb_device pointers; NULL in case of error

References match_dev_ids().

Referenced by osmo_libusb_find_matching_interfaces(), and osmo_libusb_open_claim_interface().

◆ osmo_libusb_find_open_claim()

libusb_device_handle* osmo_libusb_find_open_claim ( const struct osmo_usb_matchspec cfg,
const struct dev_id default_dev_ids 
)

high-level all-in-one function for USB device, config + interface matching + opening.

This function offers the highest level of API among all libosmousb helper functions. It is intended as a one-stop shop for everything related to grabbing an interface.

1) looks for a device matching either the VID/PID from 'cfg' or 'default_dev_ids', if more than one is found, the user is expected to fill in cfg->dev.path to disambiguate. 2) find any interfaces on the device that match the specification in 'cfg'. The match could be done based on any of (class, subclass, proto, interface number). If there are multiple matches, the caller must disambiguate by specifying the interface number. 3) open the USB device; set the configuration (if needed); claim the interface and set the altsetting

Parameters
[in]cfguser-supplied match configuration (from command line or config file)
[in]default_dev_idsDefault list of supported VendorId/ProductIds
Returns
libusb_device_handle on success, NULL on error

References osmo_usb_matchspec::class, osmo_usb_matchspec::dev, DLUSB, osmo_usb_matchspec::intf, osmo_usb_matchspec::num, osmo_libusb_dev_find_matching_interfaces(), osmo_libusb_find_matching_dev_path(), osmo_libusb_open_claim_interface(), osmo_usb_matchspec::path, osmo_usb_matchspec::product_id, osmo_usb_matchspec::proto, osmo_usb_matchspec::subclass, and osmo_usb_matchspec::vendor_id.

◆ osmo_libusb_get_ep_addrs()

int osmo_libusb_get_ep_addrs ( libusb_device_handle *  devh,
unsigned int  if_num,
uint8_t *  out,
uint8_t *  in,
uint8_t *  irq 
)

obtain the endpoint addresses for a given USB interface.

Parameters
[in]devhUSB device handle on which to operate
[in]if_numUSB Interface number on which to operate
[out]outuser-provided storage for OUT endpoint number
[out]inuser-provided storage for IN endpoint number
[out]irquser-provided storage for IRQ endpoint number
Returns
0 in case of success; negative in case of error

◆ osmo_libusb_init()

int osmo_libusb_init ( libusb_context **  luctx)

◆ osmo_libusb_match_init()

◆ osmo_libusb_open_claim_interface()

libusb_device_handle* osmo_libusb_open_claim_interface ( void *  ctx,
libusb_context *  luctx,
const struct usb_interface_match ifm 
)

open matching USB device and claim interface

Parameters
[in]ctxtalloc context to use for related allocations
[in]luctxlibusb context on which to operate
[in]ifminterface match describing interface to claim
Returns
libusb device chandle on success; NULL on error

References usb_interface_match::addr, usb_interface_match::altsetting, usb_interface_match::configuration, usb_interface_match::interface, osmo_libusb_dev_get_path_buf(), osmo_libusb_find_matching_usb_devs(), usb_interface_match::path, usb_interface_match::product, USB_MAX_PATH_LEN, and usb_interface_match::vendor.

Referenced by osmo_libusb_find_open_claim().

usb_interface_match
Definition: libusb.h:27
osmo_usb_matchspec
Description of the USB device+interface we're looking for.
Definition: libusb.h:55
dev_id::vendor_id
uint16_t vendor_id
Definition: libusb.h:22
osmo_libusb_dev_get_path_buf
char * osmo_libusb_dev_get_path_buf(char *buf, size_t bufsize, libusb_device *dev)
obtain the string representation of the USB device path of given device.
Definition: osmo_libusb.c:117
osmo_libusb_find_matching_interfaces
int osmo_libusb_find_matching_interfaces(libusb_context *luctx, const struct dev_id *dev_ids, int class, int sub_class, int protocol, struct usb_interface_match *out, unsigned int out_len)
find matching interfaces among a list devices of specified VendorId/ProductID tuples.
Definition: osmo_libusb.c:457
osmo_libusb_match_init
void osmo_libusb_match_init(struct osmo_usb_matchspec *cfg, int if_class, int if_subclass, int if_proto)
Definition: osmo_libusb.c:590
match_dev_ids
static int match_dev_ids(const struct libusb_device_descriptor *desc, const struct dev_id *ids)
Definition: osmo_libusb.c:157
usb_interface_match::usb_dev
libusb_device * usb_dev
Definition: libusb.h:29
osmo_libusb_find_open_claim
libusb_device_handle * osmo_libusb_find_open_claim(const struct osmo_usb_matchspec *cfg, const struct dev_id *default_dev_ids)
high-level all-in-one function for USB device, config + interface matching + opening.
Definition: osmo_libusb.c:622
osmo_usb_added_cb
static void osmo_usb_added_cb(int fd, short events, void *user_data)
Definition: osmo_libusb.c:80
usb_interface_match::string_idx
uint8_t string_idx
Definition: libusb.h:51
osmo_libusb_find_matching_usb_devs
libusb_device ** osmo_libusb_find_matching_usb_devs(void *ctx, struct libusb_context *luctx, const struct dev_id *dev_ids)
Find USB devices matching the specified list of USB VendorID/ProductIDs.
Definition: osmo_libusb.c:173
usb_interface_match::class
uint8_t class
Definition: libusb.h:45
libusb.h
osmo_usb_matchspec::intf
struct osmo_usb_matchspec::@1 intf
specify the USB interface
DLUSB
#define DLUSB
Definition: osmo_libusb.c:38
usb_interface_match::protocol
uint8_t protocol
Definition: libusb.h:49
osmo_libusb_get_ep_addrs
int osmo_libusb_get_ep_addrs(libusb_device_handle *devh, unsigned int if_num, uint8_t *out, uint8_t *in, uint8_t *irq)
obtain the endpoint addresses for a given USB interface.
Definition: osmo_libusb.c:693
match_dev_id
static int match_dev_id(const struct libusb_device_descriptor *desc, const struct dev_id *id)
Definition: osmo_libusb.c:150
usb_interface_match::addr
uint8_t addr
Definition: libusb.h:35
osmo_libusb_find_matching_dev_path
libusb_device * osmo_libusb_find_matching_dev_path(struct libusb_context *luctx, const struct dev_id *dev_ids, const char *path)
Find a USB device of matching VendorID/ProductID at given path.
Definition: osmo_libusb.c:227
usb_interface_match::configuration
uint8_t configuration
Definition: libusb.h:39
osmo_libusb_dev_find_matching_interfaces
int osmo_libusb_dev_find_matching_interfaces(libusb_device *dev, int class, int sub_class, int protocol, struct usb_interface_match *out, unsigned int out_len)
find a matching interface among all interfaces of the given USB device.
Definition: osmo_libusb.c:382
usb_interface_match::sub_class
uint8_t sub_class
Definition: libusb.h:47
usb_interface_match::vendor
uint16_t vendor
Definition: libusb.h:31
osmo_libusb_exit
void osmo_libusb_exit(libusb_context *luctx)
Definition: osmo_libusb.c:772
osmo_usb_matchspec::path
char * path
used for disambiguation when multiple matches; can be NULL
Definition: libusb.h:60
dev_id::product_id
uint16_t product_id
Definition: libusb.h:23
osmo_usb_matchspec::proto
int proto
-1 or a user-specified protocol
Definition: libusb.h:71
usb_interface_match::path
char path[USB_MAX_PATH_LEN]
Definition: libusb.h:37
osmo_usb_matchspec::vendor_id
int vendor_id
typically -1 for compile time defaults
Definition: libusb.h:58
osmo_libusb_open_claim_interface
libusb_device_handle * osmo_libusb_open_claim_interface(void *ctx, libusb_context *luctx, const struct usb_interface_match *ifm)
open matching USB device and claim interface
Definition: osmo_libusb.c:517
osmo_usb_matchspec::product_id
int product_id
typically -1 for compile time defaults
Definition: libusb.h:59
osmo_usb_fd_cb
static int osmo_usb_fd_cb(struct osmo_fd *ofd, unsigned int what)
Definition: osmo_libusb.c:65
osmo_usb_matchspec::config_id
int config_id
specify the USB configuration
Definition: libusb.h:64
osmo_usb_matchspec::num
int num
Definition: libusb.h:74
osmo_usb_removed_cb
static void osmo_usb_removed_cb(int fd, void *user_data)
Definition: osmo_libusb.c:99
USB_MAX_PATH_LEN
#define USB_MAX_PATH_LEN
Definition: libusb.h:19
osmo_usb_matchspec::class
int class
-1 or a user-specified class
Definition: libusb.h:69
osmo_libusb_init
int osmo_libusb_init(libusb_context **pluctx)
Definition: osmo_libusb.c:736
dev_id
Definition: libusb.h:21
usb_interface_match::product
uint16_t product
Definition: libusb.h:33
usb_interface_match::interface
uint8_t interface
Definition: libusb.h:41
osmo_usb_matchspec::altsetting
int altsetting
Definition: libusb.h:75
osmo_usb_matchspec::subclass
int subclass
-1 or a user-specified subclass
Definition: libusb.h:70
osmo_libusb_dev_get_path_c
char * osmo_libusb_dev_get_path_c(void *ctx, libusb_device *dev)
obtain the string representation of the USB device path of given device.
Definition: osmo_libusb.c:142
osmo_libusb_find_matching_dev_serial
libusb_device * osmo_libusb_find_matching_dev_serial(struct libusb_context *luctx, const struct dev_id *dev_ids, const char *serial)
Find a USB device of matching VendorID/ProductID and given iSerial string.
Definition: osmo_libusb.c:293
osmo_usb_matchspec::dev
struct osmo_usb_matchspec::@0 dev
specify the USB device
usb_interface_match::altsetting
uint8_t altsetting
Definition: libusb.h:43