Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
usbfs.h File Reference

Minimal header-only Linux usbfs access for one CHDKbridge camera. More...

#include <dirent.h>
#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <linux/usbdevice_fs.h>
#include <poll.h>
#include <signal.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/ioctl.h>
#include <sys/stat.h>
#include <sys/sysmacros.h>
#include <time.h>
#include <unistd.h>
Include dependency graph for usbfs.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  usbfs_device
 One enumerated USB device; a value copy, valid after enumeration ends. More...
struct  usbfs_endpoint
struct  usbfs_interface
struct  usbfs_devices
struct  usbfs_handle
 Open usbfs file; fd is -1 when closed or dropped after a lost URB. More...

Macros

#define USBFS_SYSFS_ROOT   "/sys/bus/usb/devices"
#define USBFS_DEVICE_ROOT   "/dev/bus/usb"

Enumerations

enum  {
  USBFS_SUCCESS = 0 , USBFS_ERROR_IO = -1 , USBFS_ERROR_INVALID_PARAM = -2 , USBFS_ERROR_ACCESS = -3 ,
  USBFS_ERROR_NO_DEVICE = -4 , USBFS_ERROR_NOT_FOUND = -5 , USBFS_ERROR_BUSY = -6 , USBFS_ERROR_TIMEOUT = -7 ,
  USBFS_ERROR_OVERFLOW = -8 , USBFS_ERROR_PIPE = -9 , USBFS_ERROR_INTERRUPTED = -10 , USBFS_ERROR_NO_MEM = -11 ,
  USBFS_ERROR_OTHER = -99
}
 Result codes; negative values are errors, as in libusb. More...
enum  {
  USBFS_ENDPOINT_IN = 0x80 , USBFS_TRANSFER_TYPE_MASK = 0x03 , USBFS_TRANSFER_TYPE_BULK = 2 , USBFS_TRANSFER_TYPE_INTERRUPT = 3 ,
  USBFS_MAX_ENDPOINTS = 30 , USBFS_MAX_PORTS = 7 , USBFS_DESCRIPTOR_CAPACITY = 16384 , USBFS_LEGACY_TRANSFER = 16384 ,
  USBFS_DISCARD_MS = 1000 , USBFS_DEVICE_MAJOR = 189
}

Functions

static const char * usbfs_error_name (int error)
 Get the diagnostic name of a usbfs result.
static bool usbfs_available (void)
 True when sysfs device listing and usbfs nodes are reachable.
static bool usbfs_read_number (const char *device, const char *attribute, int base, unsigned long maximum, unsigned long *value)
 Read one bounded unsigned numeric sysfs attribute.
static bool usbfs_parse_name (const char *name, struct usbfs_device *device)
 Parse "BUS-PORT[.PORT...]"; rejects root hubs and interface entries.
static int usbfs_devices_open (struct usbfs_devices *devices)
 Start a streaming sysfs enumeration.
static int usbfs_devices_next (struct usbfs_devices *devices, struct usbfs_device *device)
static void usbfs_devices_close (struct usbfs_devices *devices)
 Release the sysfs enumeration stream.
static int usbfs_select_config (const uint8_t *descriptors, size_t length, unsigned value, const uint8_t **config, size_t *config_length)
 Locate configuration value in raw sysfs descriptors.
static int usbfs_active_config (const struct usbfs_device *device, uint8_t *buffer, size_t capacity, const uint8_t **config, size_t *config_length)
 Read the active configuration into buffer; config points inside it.
static bool usbfs_next_interface (const uint8_t *config, size_t length, size_t *offset, struct usbfs_interface *interface)
 Return the next complete interface/alternate setting in a configuration.
static bool usbfs_same_device (const struct usbfs_device *device)
 Compare a previously discovered USB identity with current sysfs.
static int usbfs_open (const struct usbfs_device *device, struct usbfs_handle *handle)
 Open the device node, rejecting a node now owned by a different device.
static void usbfs_close (struct usbfs_handle *handle)
 Close the node; the kernel releases claimed interfaces and kills pending URBs.
static int usbfs_interface_ioctl (struct usbfs_handle *handle, unsigned long request, void *argument)
 Run a synchronous interface ioctl and translate its result.
static int usbfs_claim_interface (struct usbfs_handle *handle, int interface)
 Claim without detaching another owner; EBUSY is reported to the caller.
static int usbfs_release_interface (struct usbfs_handle *handle, int interface)
 Release the numbered interface on an open device.
static int usbfs_set_alternate (struct usbfs_handle *handle, int interface, int alternate)
 Select an alternate setting for an interface.
static int usbfs_control_transfer (struct usbfs_handle *handle, uint8_t request_type, uint8_t request, uint16_t value, uint16_t index, unsigned char *data, uint16_t length, unsigned timeout)
 Synchronous control transfer on endpoint zero.
static int usbfs_clear_halt (struct usbfs_handle *handle, unsigned char endpoint)
 Clear a halted endpoint of a claimed interface; data toggles are reset by the kernel.
static uint64_t usbfs_now_ms (void)
 Read the clock used for bulk transfer deadlines.
static int usbfs_drop (struct usbfs_handle *handle, int result)
 Abandon the fd; closing it is the only way the kernel guarantees the URB is gone.
static int usbfs_bulk_urb (struct usbfs_handle *handle, unsigned char endpoint, unsigned char *data, int length, int *actual, uint64_t deadline)
 Submit one bulk URB and wait until it is reaped or deadline passes.
static int usbfs_bulk_transfer (struct usbfs_handle *handle, unsigned char endpoint, unsigned char *data, int length, int *transferred, unsigned timeout)
 Synchronous bulk transfer with libusb_bulk_transfer() semantics.

Detailed Description

Minimal header-only Linux usbfs access for one CHDKbridge camera.

Discovers devices through sysfs, parses the active configuration, owns one interface and performs synchronous bulk transfers through /dev/bus/usb ioctls. The wrapper allocates no heap storage and creates no threads.

Warning
Serialize all access to a handle, including close. A bulk call owns its submitted URB until completion or descriptor teardown; another caller must not reap it or close and reuse the descriptor.

Definition in file usbfs.h.

Macro Definition Documentation

◆ USBFS_DEVICE_ROOT

#define USBFS_DEVICE_ROOT   "/dev/bus/usb"

Definition at line 51 of file usbfs.h.

◆ USBFS_SYSFS_ROOT

#define USBFS_SYSFS_ROOT   "/sys/bus/usb/devices"

Definition at line 50 of file usbfs.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Result codes; negative values are errors, as in libusb.

Enumerator
USBFS_SUCCESS 
USBFS_ERROR_IO 
USBFS_ERROR_INVALID_PARAM 
USBFS_ERROR_ACCESS 
USBFS_ERROR_NO_DEVICE 
USBFS_ERROR_NOT_FOUND 
USBFS_ERROR_BUSY 
USBFS_ERROR_TIMEOUT 
USBFS_ERROR_OVERFLOW 
USBFS_ERROR_PIPE 
USBFS_ERROR_INTERRUPTED 
USBFS_ERROR_NO_MEM 
USBFS_ERROR_OTHER 

Definition at line 54 of file usbfs.h.

◆ anonymous enum

anonymous enum
Enumerator
USBFS_ENDPOINT_IN 
USBFS_TRANSFER_TYPE_MASK 
USBFS_TRANSFER_TYPE_BULK 
USBFS_TRANSFER_TYPE_INTERRUPT 
USBFS_MAX_ENDPOINTS 
USBFS_MAX_PORTS 
USBFS_DESCRIPTOR_CAPACITY 
USBFS_LEGACY_TRANSFER 

Per-URB limit without NO_PACKET_SIZE_LIM.

USBFS_DISCARD_MS 

Grace for a cancelled URB before the fd is dropped.

USBFS_DEVICE_MAJOR 

Definition at line 62 of file usbfs.h.

Function Documentation

◆ usbfs_active_config()

int usbfs_active_config ( const struct usbfs_device * device,
uint8_t * buffer,
size_t capacity,
const uint8_t ** config,
size_t * config_length )
inlinestatic

Read the active configuration into buffer; config points inside it.

Definition at line 256 of file usbfs.h.

◆ usbfs_available()

bool usbfs_available ( void )
inlinestatic

True when sysfs device listing and usbfs nodes are reachable.

Definition at line 127 of file usbfs.h.

◆ usbfs_bulk_transfer()

int usbfs_bulk_transfer ( struct usbfs_handle * handle,
unsigned char endpoint,
unsigned char * data,
int length,
int * transferred,
unsigned timeout )
inlinestatic

Synchronous bulk transfer with libusb_bulk_transfer() semantics.

Parameters
handleSerialized device handle holding the interface claim.
endpointBulk endpoint address including the direction bit.
[in,out]dataBuffer for length bytes.
lengthRequested bytes, nonnegative.
[out]transferredRequired byte count; may be nonzero on failure.
timeoutNonzero total timeout in milliseconds.
Returns
USBFS_SUCCESS or a negative wrapper error.

IN transfers are capped at one URB; OUT transfers are split only on kernels without NO_PACKET_SIZE_LIM, sharing one deadline.

Definition at line 563 of file usbfs.h.

◆ usbfs_bulk_urb()

int usbfs_bulk_urb ( struct usbfs_handle * handle,
unsigned char endpoint,
unsigned char * data,
int length,
int * actual,
uint64_t deadline )
inlinestatic

Submit one bulk URB and wait until it is reaped or deadline passes.

On expiry the URB is discarded and reaped, preserving any bytes already received. Data reaches data only when the URB is reaped, so a URB that cannot be reaped within the discard grace is made harmless by closing.

Definition at line 494 of file usbfs.h.

◆ usbfs_claim_interface()

int usbfs_claim_interface ( struct usbfs_handle * handle,
int interface )
inlinestatic

Claim without detaching another owner; EBUSY is reported to the caller.

Definition at line 400 of file usbfs.h.

◆ usbfs_clear_halt()

int usbfs_clear_halt ( struct usbfs_handle * handle,
unsigned char endpoint )
inlinestatic

Clear a halted endpoint of a claimed interface; data toggles are reset by the kernel.

Definition at line 465 of file usbfs.h.

◆ usbfs_close()

void usbfs_close ( struct usbfs_handle * handle)
inlinestatic

Close the node; the kernel releases claimed interfaces and kills pending URBs.

Definition at line 371 of file usbfs.h.

◆ usbfs_control_transfer()

int usbfs_control_transfer ( struct usbfs_handle * handle,
uint8_t request_type,
uint8_t request,
uint16_t value,
uint16_t index,
unsigned char * data,
uint16_t length,
unsigned timeout )
inlinestatic

Synchronous control transfer on endpoint zero.

Parameters
handleSerialized device handle.
request_typeUSB bmRequestType, including direction.
requestUSB bRequest.
valueUSB wValue.
indexUSB wIndex.
[in,out]dataCaller buffer; may be NULL only for a zero-length transfer.
lengthSize of the data stage in bytes.
timeoutNonzero kernel transfer timeout in milliseconds.
Returns
Bytes transferred (>= 0) or a negative USBFS error.

A short successful transfer can be meaningful; callers validate the returned length against the particular request's contract.

Definition at line 444 of file usbfs.h.

◆ usbfs_devices_close()

void usbfs_devices_close ( struct usbfs_devices * devices)
inlinestatic

Release the sysfs enumeration stream.

Parameters
[in,out]devicesInitialized iterator.

Clear the stream pointer so repeated cleanup is safe.

Definition at line 225 of file usbfs.h.

◆ usbfs_devices_next()

int usbfs_devices_next ( struct usbfs_devices * devices,
struct usbfs_device * device )
inlinestatic
Returns
1 with a device, 0 at the end, or a negative error. Vanishing devices are skipped.

Definition at line 200 of file usbfs.h.

◆ usbfs_devices_open()

int usbfs_devices_open ( struct usbfs_devices * devices)
inlinestatic

Start a streaming sysfs enumeration.

Parameters
[out]devicesIterator receiving the directory stream.
Returns
USBFS_SUCCESS or a negative access/I/O error.

Scan at iteration time rather than allocating a device list.

Definition at line 192 of file usbfs.h.

◆ usbfs_drop()

int usbfs_drop ( struct usbfs_handle * handle,
int result )
inlinestatic

Abandon the fd; closing it is the only way the kernel guarantees the URB is gone.

Definition at line 482 of file usbfs.h.

◆ usbfs_error_name()

const char * usbfs_error_name ( int error)
inlinestatic

Get the diagnostic name of a usbfs result.

Parameters
errorResult from this wrapper.
Returns
Borrowed static name, with OTHER for unknown values.

Keep the diagnostic vocabulary stable independently of errno.

Definition at line 107 of file usbfs.h.

◆ usbfs_interface_ioctl()

int usbfs_interface_ioctl ( struct usbfs_handle * handle,
unsigned long request,
void * argument )
inlinestatic

Run a synchronous interface ioctl and translate its result.

Parameters
handleSerialized open device handle.
requestLinux usbfs ioctl number.
argumentRequest-specific argument storage.
Returns
USBFS_SUCCESS or a negative wrapper error.

Retry interruptions, preserving the distinction between busy, disconnected and inaccessible devices for the calling policy.

Definition at line 384 of file usbfs.h.

◆ usbfs_next_interface()

bool usbfs_next_interface ( const uint8_t * config,
size_t length,
size_t * offset,
struct usbfs_interface * interface )
inlinestatic

Return the next complete interface/alternate setting in a configuration.

Parameters
configBorrowed descriptor block for the active configuration.
lengthReadable bytes in config.
offsetStart with 0; advanced past the returned interface.
[out]interfaceParsed interface; use only when the function returns true.
Returns
True when a complete interface was found.

Interfaces whose endpoint descriptors disagree with bNumEndpoints are skipped. Parsing stops at the first malformed descriptor header.

Definition at line 293 of file usbfs.h.

◆ usbfs_now_ms()

uint64_t usbfs_now_ms ( void )
inlinestatic

Read the clock used for bulk transfer deadlines.

Returns
Monotonic milliseconds, or zero on failure.

Keep a single time base across submit, wait and discard.

Definition at line 474 of file usbfs.h.

◆ usbfs_open()

int usbfs_open ( const struct usbfs_device * device,
struct usbfs_handle * handle )
inlinestatic

Open the device node, rejecting a node now owned by a different device.

Definition at line 343 of file usbfs.h.

◆ usbfs_parse_name()

bool usbfs_parse_name ( const char * name,
struct usbfs_device * device )
inlinestatic

Parse "BUS-PORT[.PORT...]"; rejects root hubs and interface entries.

Definition at line 166 of file usbfs.h.

◆ usbfs_read_number()

bool usbfs_read_number ( const char * device,
const char * attribute,
int base,
unsigned long maximum,
unsigned long * value )
inlinestatic

Read one bounded unsigned numeric sysfs attribute.

Parameters
deviceSysfs device directory name.
attributeAttribute basename.
baseNumber base, 10 or 16 for supported callers.
maximumLargest acceptable value.
[out]valueResult written only on success.
Returns
True if the attribute could be read and parsed in range.

Allow the newline used by sysfs, but reject signs and nonnumeric prefixes before conversion.

Definition at line 141 of file usbfs.h.

◆ usbfs_release_interface()

int usbfs_release_interface ( struct usbfs_handle * handle,
int interface )
inlinestatic

Release the numbered interface on an open device.

Parameters
handleSerialized device handle.
interfaceNonnegative USB interface number.
Returns
USBFS_SUCCESS or a negative wrapper error.

Release the claim without closing the device descriptor.

Definition at line 411 of file usbfs.h.

◆ usbfs_same_device()

bool usbfs_same_device ( const struct usbfs_device * device)
inlinestatic

Compare a previously discovered USB identity with current sysfs.

Parameters
deviceDevice snapshot with sysfs name, bus, address and IDs.
Returns
True if the checked attributes still match.

Recheck after opening because disconnects and re-enumeration can invalidate a previously discovered bus address.

Definition at line 333 of file usbfs.h.

◆ usbfs_select_config()

int usbfs_select_config ( const uint8_t * descriptors,
size_t length,
unsigned value,
const uint8_t ** config,
size_t * config_length )
inlinestatic

Locate configuration value in raw sysfs descriptors.

sysfs stores the device descriptor followed by every configuration in bus (little-endian) order; a short final configuration is clamped.

Definition at line 236 of file usbfs.h.

◆ usbfs_set_alternate()

int usbfs_set_alternate ( struct usbfs_handle * handle,
int interface,
int alternate )
inlinestatic

Select an alternate setting for an interface.

Parameters
handleSerialized device handle.
interfaceNonnegative USB interface number.
alternateNonnegative alternate-setting number.
Returns
USBFS_SUCCESS or a negative wrapper error.

The caller must pair the setting with its matching endpoint descriptors.

Definition at line 423 of file usbfs.h.