USB library for device drivers
[USB]

Library for writing drivers of endpoint devices (functions). More...


Files

file  altiface.c
 Handling alternate interface settings.
file  devdrv.c
 USB device driver framework.
file  devpoll.c
 USB device driver framework - automatic interrupt polling.
file  dp.c
 USB descriptor parser (implementation).
file  dp.h
 USB descriptor parser.
file  driver.h
 USB device driver framework.
file  hub.c
 Functions needed by hub drivers.
file  hub.h
 Functions needed by hub drivers.
file  pipepriv.c
 Library internal functions on USB pipes (implementation).
file  pipepriv.h
 Library internal functions on USB pipes.
file  pipes.c
 USB endpoint pipes miscellaneous functions.
file  pipes.h
 USB pipes representation.
file  pipesinit.c
 Initialization of endpoint pipes.
file  pipesio.c
 Input and output functions (reads and writes) on endpoint pipes.
file  poll.h
 USB device polling functions.
file  recognise.c
 Functions for recognition of attached devices.
file  recognise.h
 USB device recognition.
file  request.c
 Standard USB requests (implementation).
file  request.h
 Standard USB requests.

Data Structures

struct  polling_data_t
 Data needed for polling. More...
struct  usb_alternate_interface_descriptors_t
 Wrapper for data related to alternate interface setting. More...
struct  usb_alternate_interfaces_t
 Alternate interface settings. More...
struct  usb_device_auto_polling_t
struct  usb_device_connection_t
 Abstraction of a physical connection to the device. More...
struct  usb_device_descriptors_t
 Descriptors for USB device. More...
struct  usb_device_request_setup_packet_t
 Device request setup packet. More...
struct  usb_device_t
 USB device structure. More...
struct  usb_dp_descriptor_nesting_t
 USB descriptors nesting. More...
struct  usb_dp_parser_data_t
 Descriptor parser data. More...
struct  usb_dp_parser_t
 Descriptor parser structure. More...
struct  usb_driver_ops_t
 USB driver ops. More...
struct  usb_driver_t
 USB driver structure. More...
struct  usb_endpoint_description_t
 Description of endpoint characteristics. More...
struct  usb_endpoint_mapping_t
 Mapping of endpoint pipes and endpoint descriptions. More...
struct  usb_hc_attached_device_t
 Info about device attached to host controller. More...
struct  usb_pipe_t
 Abstraction of a logical connection to USB device endpoint. More...

Defines

#define ADD_MATCHID_OR_RETURN(match_ids, score, format,)
 Add match id to list or return with error code.
#define BCD_ARGS(a)   BCD_INT((a)), BCD_FRAC((a))
 Arguments to printf for BCD coded number.
#define BCD_FMT   "%x.%x"
 Format for BCD coded number to be used in printf.
#define BCD_FRAC(a)   (((unsigned int)(a)) % 256)
 Get fraction part from BCD coded number (as an integer, no less).
#define BCD_INT(a)   (((unsigned int)(a)) / 256)
 Get integer part from BCD coded number.
#define CHECK_CONNECTION(conn)
 Check that HC connection is alright.
#define CTRL_PIPE_MIN_PACKET_SIZE   8
#define DEV_DESCR_MAX_PACKET_SIZE_OFFSET   7
#define ENDPOINT_0_0_REGISTER_ATTEMPT_DELAY_USEC   (1000 * (10 + 2))
 How much time to wait between attempts to register endpoint 0:0.
#define IPC_AGAIN_DELAY   (1000 * 2)
#define LAST_NESTING   { -1, -1 }
#define LAST_NESTING   { -1, -1 }
#define MATCH_STRING_MAX   256
#define MAX_DATA_LENGTH   ((size_t)(0xFFFF))
#define MAX_FAILED_ATTEMPTS   3
 Maximum number of failed consecutive requests before announcing failure.
#define NESTING(parentname, childname)
#define NESTING(parentname, childname)
#define USB_DEVICE_STATUS_REMOTE_WAKEUP   ((uint16_t)(1 << 1))
 USB device status - remote wake-up signaling is enabled.
#define USB_DEVICE_STATUS_SELF_POWERED   ((uint16_t)(1 << 0))
 USB device status - device is self powered (opposed to bus powered).
#define USB_ENDPOINT_STATUS_HALTED   ((uint16_t)(1 << 0))
 USB endpoint status - endpoint is halted (stalled).
#define USB_FEATURE_SELECTOR_ENDPOINT_HALT   (0)
 USB feature selector - endpoint halt (stall).
#define USB_FEATURE_SELECTOR_REMOTE_WAKEUP   (1)
 USB feature selector - device remote wake-up.

Typedefs

typedef bool(*) usb_polling_callback_t (usb_device_t *, uint8_t *, size_t, void *)
typedef void(*) usb_polling_terminted_callback_t (usb_device_t *, bool, void *)

Enumerations

enum  usb_stddevreq_t
 Standard device request.

Functions

static void clear_self_endpoint_halt (usb_pipe_t *pipe)
 Try to clear endpoint halt of default control pipe.
static size_t count_other_pipes (usb_endpoint_description_t **endpoints)
 Count number of pipes the driver expects.
static int destroy_current_pipes (usb_device_t *dev)
 Destroy existing pipes of a USB device.
static bool endpoint_fits_description (const usb_endpoint_description_t *wanted, usb_endpoint_description_t *found)
 Tells whether found endpoint corresponds to endpoint described by user.
static FIBRIL_MUTEX_INITIALIZE (device_name_index_mutex)
 Mutex guard for device_name_index.
static usb_endpoint_mapping_t * find_endpoint_mapping (usb_endpoint_mapping_t *mapping, size_t mapping_count, usb_endpoint_description_t *found_endpoint, int interface_number, int interface_setting)
 Find endpoint mapping for a found endpoint.
static int generic_add_device (ddf_dev_t *gen_dev)
 Callback when new device is supposed to be controlled by this driver.
static int get_descriptor_type (usb_dp_parser_data_t *data, uint8_t *start)
 Get descriptor type.
static usb_address_t get_my_address (int phone, ddf_dev_t *dev)
 Tell USB address assigned to given device.
static uint8_t * get_next_descriptor (usb_dp_parser_data_t *data, uint8_t *current)
 Get next descriptor regardless of the nesting.
static int init_wire_and_ctrl_pipe (usb_device_t *dev, const char **errmsg)
 Initialize control pipe in a device.
static int initialize_other_pipes (usb_endpoint_description_t **endpoints, usb_device_t *dev, int alternate_setting)
 Initialize endpoint pipes, excluding default control one.
static bool is_endpoint_descriptor (uint8_t *descriptor)
 Tells whether given descriptor is of endpoint type.
static bool is_nested_descriptor (usb_dp_parser_t *parser, usb_dp_parser_data_t *data, uint8_t *child, uint8_t *parent)
 Tells whether descriptors could be nested.
static bool is_nested_descriptor_type (usb_dp_parser_t *parser, int child, int parent)
 Tells whether descriptors could be nested.
static bool is_valid_descriptor_pointer (usb_dp_parser_data_t *data, uint8_t *ptr)
 Tells whether pointer points inside descriptor data.
void pipe_acquire (usb_pipe_t *pipe)
 Ensure exclusive access to the pipe as a whole.
int pipe_add_ref (usb_pipe_t *pipe, bool hide_failure)
 Add reference of active transfers over the pipe.
void pipe_drop_ref (usb_pipe_t *pipe)
 Drop active transfer reference on the pipe.
void pipe_end_transaction (usb_pipe_t *pipe)
 Terminate exclusive access to the IPC phone of given pipe.
void pipe_release (usb_pipe_t *pipe)
 Terminate exclusive access to the pipe as a whole.
void pipe_start_transaction (usb_pipe_t *pipe)
 Ensure exclusive access to the IPC phone of given pipe.
static int polling_fibril (void *arg)
 Polling fibril.
static int process_endpoint (usb_endpoint_mapping_t *mapping, size_t mapping_count, usb_standard_interface_descriptor_t *interface, usb_standard_endpoint_descriptor_t *endpoint, usb_device_connection_t *wire)
 Process endpoint descriptor.
static int process_interface (usb_endpoint_mapping_t *mapping, size_t mapping_count, usb_dp_parser_t *parser, usb_dp_parser_data_t *parser_data, uint8_t *interface_descriptor)
 Process whole USB interface.
static uint8_t * skip_nested_descriptors (usb_dp_parser_t *parser, usb_dp_parser_data_t *data, uint8_t *parent)
 Skip all nested descriptors.
static void unregister_control_endpoint_on_default_address (usb_hc_connection_t *connection)
static int usb_add_match_id (match_id_list_t *matches, int score, const char *format,...)
 Add formatted match id.
int usb_alternate_interfaces_create (uint8_t *config_descr, size_t config_descr_size, int interface_number, usb_alternate_interfaces_t **alternates_ptr)
 Create alternate interface representation structure.
int usb_control_request_get (usb_pipe_t *pipe, usb_request_type_t request_type, usb_request_recipient_t recipient, uint8_t request, uint16_t value, uint16_t index, void *data, size_t data_size, size_t *actual_data_size)
 Generic wrapper for GET requests using standard control request format.
int usb_control_request_set (usb_pipe_t *pipe, usb_request_type_t request_type, usb_request_recipient_t recipient, uint8_t request, uint16_t value, uint16_t index, void *data, size_t data_size)
 Generic wrapper for SET requests using standard control request format.
int usb_device_auto_poll (usb_device_t *dev, size_t pipe_index, usb_polling_callback_t callback, size_t request_size, usb_polling_terminted_callback_t terminated_callback, void *arg)
 Start automatic device polling over interrupt in pipe.
int usb_device_auto_polling (usb_device_t *dev, size_t pipe_index, usb_device_auto_polling_t *polling, size_t request_size, void *arg)
 Start automatic device polling over interrupt in pipe.
int usb_device_connection_initialize (usb_device_connection_t *connection, devman_handle_t host_controller_handle, usb_address_t device_address)
 Initialize connection to USB device.
int usb_device_connection_initialize_from_device (usb_device_connection_t *connection, ddf_dev_t *dev)
 Initialize connection to USB device.
int usb_device_connection_initialize_on_default_address (usb_device_connection_t *dev_connection, usb_hc_connection_t *hc_connection)
 Initialize connection to USB device on default address.
int usb_device_create (ddf_dev_t *ddf_dev, usb_endpoint_description_t **endpoints, usb_device_t **dev_ptr, const char **errstr_ptr)
 Create new instance of USB device.
int usb_device_create_match_ids (usb_pipe_t *ctrl_pipe, match_id_list_t *matches)
 Create match ids describing attached device.
int usb_device_create_match_ids_from_device_descriptor (const usb_standard_device_descriptor_t *device_descriptor, match_id_list_t *matches)
 Create DDF match ids from USB device descriptor.
int usb_device_create_match_ids_from_interface (const usb_standard_device_descriptor_t *desc_device, const usb_standard_interface_descriptor_t *desc_interface, match_id_list_t *matches)
 Create device match ids based on its interface.
int usb_device_create_pipes (ddf_dev_t *dev, usb_device_connection_t *wire, usb_endpoint_description_t **endpoints, uint8_t *config_descr, size_t config_descr_size, int interface_no, int interface_setting, usb_endpoint_mapping_t **pipes_ptr, size_t *pipes_count_ptr)
 Create pipes for a device.
void usb_device_destroy (usb_device_t *dev)
 Destroy instance of a USB device.
int usb_device_destroy_pipes (ddf_dev_t *dev, usb_endpoint_mapping_t *pipes, size_t pipes_count)
 Destroy pipes previously created by usb_device_create_pipes.
int usb_device_get_assigned_interface (ddf_dev_t *device)
 Tell USB interface assigned to given device.
int usb_device_register_child_in_devman (usb_address_t address, devman_handle_t hc_handle, ddf_dev_t *parent, devman_handle_t *child_handle, ddf_dev_ops_t *dev_ops, void *dev_data, ddf_fun_t **child_fun)
 Probe for device kind and register it in devman.
int usb_device_retrieve_descriptors (usb_pipe_t *ctrl_pipe, usb_device_descriptors_t *descriptors)
 Retrieve basic descriptors from the device.
int usb_device_select_interface (usb_device_t *dev, uint8_t alternate_setting, usb_endpoint_description_t **endpoints)
 Change interface setting of a device.
static void usb_dp_browse_simple_internal (usb_dp_parser_t *parser, usb_dp_parser_data_t *data, uint8_t *root, size_t depth, void(*callback)(uint8_t *, size_t, void *), void *arg)
 Browser of the descriptor tree.
uint8_t * usb_dp_get_nested_descriptor (usb_dp_parser_t *parser, usb_dp_parser_data_t *data, uint8_t *parent)
 Find first nested descriptor of given parent.
uint8_t * usb_dp_get_sibling_descriptor (usb_dp_parser_t *parser, usb_dp_parser_data_t *data, uint8_t *parent, uint8_t *sibling)
 Get sibling descriptor.
void usb_dp_walk_simple (uint8_t *descriptors, size_t descriptors_size, usb_dp_descriptor_nesting_t *descriptor_nesting, void(*callback)(uint8_t *, size_t, void *), void *arg)
 Browse flatten descriptor tree.
int usb_driver_main (usb_driver_t *drv)
 Main routine of USB device driver.
int usb_hc_new_device_wrapper (ddf_dev_t *parent, usb_hc_connection_t *connection, usb_speed_t dev_speed, int(*enable_port)(int port_no, void *arg), int port_no, void *arg, usb_address_t *assigned_address, devman_handle_t *assigned_handle, ddf_dev_ops_t *dev_ops, void *new_dev_data, ddf_fun_t **new_fun)
 Wrapper for registering attached device to the hub.
int usb_hc_register_device (usb_hc_connection_t *connection, const usb_hc_attached_device_t *attached_device)
 Inform host controller about new device.
usb_address_t usb_hc_request_address (usb_hc_connection_t *connection, usb_speed_t speed)
 Ask host controller for free address assignment.
int usb_hc_unregister_device (usb_hc_connection_t *connection, usb_address_t address)
 Inform host controller about device removal.
size_t usb_interface_count_alternates (uint8_t *config_descr, size_t config_descr_size, uint8_t interface_no)
 Count number of alternate settings of a interface.
int usb_pipe_clear_halt (usb_pipe_t *ctrl_pipe, usb_pipe_t *target_pipe)
 Clear halt bit of an endpoint pipe (after pipe stall).
int usb_pipe_control_read (usb_pipe_t *pipe, void *setup_buffer, size_t setup_buffer_size, void *data_buffer, size_t data_buffer_size, size_t *data_transfered_size)
 Request a control read transfer on an endpoint pipe.
static int usb_pipe_control_read_no_check (usb_pipe_t *pipe, void *setup_buffer, size_t setup_buffer_size, void *data_buffer, size_t data_buffer_size, size_t *data_transfered_size)
 Request a control read transfer, no checking of input parameters.
int usb_pipe_control_write (usb_pipe_t *pipe, void *setup_buffer, size_t setup_buffer_size, void *data_buffer, size_t data_buffer_size)
 Request a control write transfer on an endpoint pipe.
static int usb_pipe_control_write_no_check (usb_pipe_t *pipe, void *setup_buffer, size_t setup_buffer_size, void *data_buffer, size_t data_buffer_size)
 Request a control write transfer, no checking of input parameters.
void usb_pipe_end_long_transfer (usb_pipe_t *pipe)
 Terminate a long transfer on a pipe.
int usb_pipe_initialize (usb_pipe_t *pipe, usb_device_connection_t *connection, usb_endpoint_t endpoint_no, usb_transfer_type_t transfer_type, size_t max_packet_size, usb_direction_t direction)
 Initialize USB endpoint pipe.
int usb_pipe_initialize_default_control (usb_pipe_t *pipe, usb_device_connection_t *connection)
 Initialize USB endpoint pipe as the default zero control pipe.
int usb_pipe_initialize_from_configuration (usb_endpoint_mapping_t *mapping, size_t mapping_count, uint8_t *configuration_descriptor, size_t configuration_descriptor_size, usb_device_connection_t *connection)
 Initialize endpoint pipes from configuration descriptor.
int usb_pipe_probe_default_control (usb_pipe_t *pipe)
 Probe default control pipe for max packet size.
int usb_pipe_read (usb_pipe_t *pipe, void *buffer, size_t size, size_t *size_transfered)
 Request a read (in) transfer on an endpoint pipe.
static int usb_pipe_read_no_checks (usb_pipe_t *pipe, void *buffer, size_t size, size_t *size_transfered)
 Request an in transfer, no checking of input parameters.
int usb_pipe_register (usb_pipe_t *pipe, unsigned int interval, usb_hc_connection_t *hc_connection)
 Register endpoint with the host controller.
int usb_pipe_register_with_speed (usb_pipe_t *pipe, usb_speed_t speed, unsigned int interval, usb_hc_connection_t *hc_connection)
 Register endpoint with a speed at the host controller.
void usb_pipe_start_long_transfer (usb_pipe_t *pipe)
 Prepare pipe for a long transfer.
int usb_pipe_unregister (usb_pipe_t *pipe, usb_hc_connection_t *hc_connection)
 Revert endpoint registration with the host controller.
int usb_pipe_write (usb_pipe_t *pipe, void *buffer, size_t size)
 Request a write (out) transfer on an endpoint pipe.
static int usb_pipe_write_no_check (usb_pipe_t *pipe, void *buffer, size_t size)
 Request an out transfer, no checking of input parameters.
int usb_request_clear_endpoint_halt (usb_pipe_t *pipe, uint16_t ep_index)
 Clear halt bit of an endpoint pipe (after pipe stall).
int usb_request_clear_feature (usb_pipe_t *pipe, usb_request_type_t request_type, usb_request_recipient_t recipient, uint16_t feature_selector, uint16_t index)
 Clear or disable specific device feature.
int usb_request_get_bare_configuration_descriptor (usb_pipe_t *pipe, int index, usb_standard_configuration_descriptor_t *descriptor)
 Retrieve configuration descriptor of a USB device.
int usb_request_get_configuration (usb_pipe_t *pipe, uint8_t *configuration_value)
 Get current configuration value of USB device.
int usb_request_get_descriptor (usb_pipe_t *pipe, usb_request_type_t request_type, usb_request_recipient_t recipient, uint8_t descriptor_type, uint8_t descriptor_index, uint16_t language, void *buffer, size_t size, size_t *actual_size)
 Retrieve USB descriptor of a USB device.
int usb_request_get_descriptor_alloc (usb_pipe_t *pipe, usb_request_type_t request_type, usb_request_recipient_t recipient, uint8_t descriptor_type, uint8_t descriptor_index, uint16_t language, void **buffer_ptr, size_t *buffer_size)
 Retrieve USB descriptor, allocate space for it.
int usb_request_get_device_descriptor (usb_pipe_t *pipe, usb_standard_device_descriptor_t *descriptor)
 Retrieve standard device descriptor of a USB device.
int usb_request_get_endpoint_status (usb_pipe_t *ctrl_pipe, usb_pipe_t *pipe, uint16_t *status)
 Get endpoint status.
int usb_request_get_full_configuration_descriptor (usb_pipe_t *pipe, int index, void *descriptor, size_t descriptor_size, size_t *actual_size)
 Retrieve full configuration descriptor of a USB device.
int usb_request_get_full_configuration_descriptor_alloc (usb_pipe_t *pipe, int index, void **descriptor_ptr, size_t *descriptor_size)
 Retrieve full configuration descriptor, allocate space for it.
int usb_request_get_interface (usb_pipe_t *pipe, uint8_t interface_index, uint8_t *alternate_setting)
 Get selected alternate setting for USB interface.
int usb_request_get_status (usb_pipe_t *pipe, usb_request_recipient_t recipient, uint16_t index, uint16_t *status)
 Retrieve status of a USB device.
int usb_request_get_string (usb_pipe_t *pipe, size_t index, l18_win_locales_t lang, char **string_ptr)
 Get string (descriptor) from USB device.
int usb_request_get_supported_languages (usb_pipe_t *pipe, l18_win_locales_t **languages_ptr, size_t *languages_count)
 Get list of supported languages by USB device.
int usb_request_set_address (usb_pipe_t *pipe, usb_address_t new_address)
 Change address of connected device.
int usb_request_set_configuration (usb_pipe_t *pipe, uint8_t configuration_value)
 Set configuration of USB device.
int usb_request_set_descriptor (usb_pipe_t *pipe, usb_request_type_t request_type, usb_request_recipient_t recipient, uint8_t descriptor_type, uint8_t descriptor_index, uint16_t language, void *buffer, size_t size)
 Update existing or add new USB descriptor to a USB device.
int usb_request_set_feature (usb_pipe_t *pipe, usb_request_type_t request_type, usb_request_recipient_t recipient, uint16_t feature_selector, uint16_t index)
 Set or enable specific device feature.
int usb_request_set_interface (usb_pipe_t *pipe, uint8_t interface_index, uint8_t alternate_setting)
 Select alternate setting for USB interface.

Variables

ddf_dev_ops_t child_ops
 DDF operations of child devices.
static usb_dp_descriptor_nesting_t descriptor_nesting []
 Nesting pairs of standard descriptors.
static size_t device_name_index = 0
 Index to append after device name for uniqueness.
static usb_driver_t * driver = NULL
static driver_t generic_driver
static driver_ops_t generic_driver_ops
usb_dp_descriptor_nesting_t usb_dp_standard_descriptor_nesting []
 Nesting of standard USB descriptors.
usb_dp_descriptor_nesting_t usb_dp_standard_descriptor_nesting []
 Nesting of standard USB descriptors.

Detailed Description

Library for writing drivers of endpoint devices (functions).

Define Documentation

#define ADD_MATCHID_OR_RETURN ( match_ids,
score,
format   ) 

Value:

do { \
                int __rc = usb_add_match_id((match_ids), (score), \
                    format, ##__VA_ARGS__); \
                if (__rc != EOK) { \
                        return __rc; \
                } \
        } while (0)
Add match id to list or return with error code.

Parameters:
match_ids List of match ids.
score Match id score.
format Format of the matching string
... Arguments for the format.

Definition at line 129 of file recognise.c.

#define CHECK_CONNECTION ( conn   ) 

Value:

do { \
                assert((conn)); \
                if (!usb_hc_connection_is_opened((conn))) { \
                        return ENOENT; \
                } \
        } while (false)
Check that HC connection is alright.

Parameters:
conn Connection to be checked.

Definition at line 54 of file hub.c.

#define ENDPOINT_0_0_REGISTER_ATTEMPT_DELAY_USEC   (1000 * (10 + 2))

How much time to wait between attempts to register endpoint 0:0.

The value is based on typical value for port reset + some overhead.

Definition at line 48 of file hub.c.

Function Documentation

static void clear_self_endpoint_halt ( usb_pipe_t *  pipe  )  [static]

Try to clear endpoint halt of default control pipe.

Parameters:
pipe Pipe for control endpoint zero.

Definition at line 314 of file pipesio.c.

static size_t count_other_pipes ( usb_endpoint_description_t **  endpoints  )  [static]

Count number of pipes the driver expects.

Parameters:
drv USB driver.
Returns:
Number of pipes (excluding default control pipe).

Definition at line 79 of file devdrv.c.

static int destroy_current_pipes ( usb_device_t *  dev  )  [static]

Destroy existing pipes of a USB device.

Parameters:
dev Device where to destroy the pipes.
Returns:
Error code.

Definition at line 158 of file devdrv.c.

static bool endpoint_fits_description ( const usb_endpoint_description_t *  wanted,
usb_endpoint_description_t *  found 
) [static]

Tells whether found endpoint corresponds to endpoint described by user.

Parameters:
wanted Endpoint description as entered by driver author.
found Endpoint description obtained from endpoint descriptor.
Returns:
Whether the found descriptor fits the wanted descriptor.

Definition at line 81 of file pipesinit.c.

static usb_endpoint_mapping_t* find_endpoint_mapping ( usb_endpoint_mapping_t *  mapping,
size_t  mapping_count,
usb_endpoint_description_t *  found_endpoint,
int  interface_number,
int  interface_setting 
) [static]

Find endpoint mapping for a found endpoint.

Parameters:
mapping Endpoint mapping list.
mapping_count Number of endpoint mappings in mapping.
found_endpoint Description of found endpoint.
interface_number Number of currently processed interface.
Returns:
Endpoint mapping corresponding to found_endpoint.
Return values:
NULL No corresponding endpoint found.

Definition at line 120 of file pipesinit.c.

int generic_add_device ( ddf_dev_t *  gen_dev  )  [static]

Callback when new device is supposed to be controlled by this driver.

This callback is a wrapper for USB specific version of add_device.

Parameters:
gen_dev Device structure as prepared by DDF.
Returns:
Error code.

Definition at line 133 of file devdrv.c.

static int get_descriptor_type ( usb_dp_parser_data_t *  data,
uint8_t *  start 
) [static]

Get descriptor type.

See also:
usb_descriptor_type_t
Parameters:
data Parser data.
start Pointer to start of the descriptor.
Returns:
Descriptor type.
Return values:
-1 Invalid input.

Definition at line 126 of file dp.c.

static usb_address_t get_my_address ( int  phone,
ddf_dev_t *  dev 
) [static]

Tell USB address assigned to given device.

Parameters:
phone Phone to parent device.
dev Device in question.
Returns:
USB address or error code.

Definition at line 54 of file pipes.c.

static uint8_t* get_next_descriptor ( usb_dp_parser_data_t *  data,
uint8_t *  current 
) [static]

Get next descriptor regardless of the nesting.

Parameters:
data Parser data.
current Pointer to current descriptor.
Returns:
Pointer to start of next descriptor.
Return values:
NULL Invalid input or no next descriptor.

Definition at line 102 of file dp.c.

static int init_wire_and_ctrl_pipe ( usb_device_t *  dev,
const char **  errmsg 
) [static]

Initialize control pipe in a device.

Parameters:
dev USB device in question.
errmsg Where to store error context.
Returns:

Definition at line 441 of file devdrv.c.

static int initialize_other_pipes ( usb_endpoint_description_t **  endpoints,
usb_device_t *  dev,
int  alternate_setting 
) [static]

Initialize endpoint pipes, excluding default control one.

Parameters:
drv The device driver.
dev Device to be initialized.
Returns:
Error code.

Definition at line 99 of file devdrv.c.

static bool is_endpoint_descriptor ( uint8_t *  descriptor  )  [inline, static]

Tells whether given descriptor is of endpoint type.

Parameters:
descriptor Descriptor in question.
Returns:
Whether the given descriptor is endpoint descriptor.

Definition at line 70 of file pipesinit.c.

static bool is_nested_descriptor ( usb_dp_parser_t *  parser,
usb_dp_parser_data_t *  data,
uint8_t *  child,
uint8_t *  parent 
) [static]

Tells whether descriptors could be nested.

Parameters:
parser Parser.
data Parser data.
child Pointer to child descriptor.
parent Pointer to parent descriptor.
Returns:
Whether child could be child of parent.

Definition at line 168 of file dp.c.

static bool is_nested_descriptor_type ( usb_dp_parser_t *  parser,
int  child,
int  parent 
) [static]

Tells whether descriptors could be nested.

Parameters:
parser Parser.
child Child descriptor type.
parent Parent descriptor type.
Returns:
Whether child could be child of parent.

Definition at line 147 of file dp.c.

static bool is_valid_descriptor_pointer ( usb_dp_parser_data_t *  data,
uint8_t *  ptr 
) [static]

Tells whether pointer points inside descriptor data.

Parameters:
data Parser data.
ptr Pointer to be verified.
Returns:
Whether ptr points inside data->data field.

Definition at line 77 of file dp.c.

void pipe_acquire ( usb_pipe_t *  pipe  ) 

Ensure exclusive access to the pipe as a whole.

Parameters:
pipe Pipe to be exclusively accessed.

Definition at line 62 of file pipepriv.c.

int pipe_add_ref ( usb_pipe_t *  pipe,
bool  hide_failure 
)

Add reference of active transfers over the pipe.

Parameters:
pipe The USB pipe.
hide_failure Whether to hide failure when adding reference (use soft refcount).
Returns:
Error code.
Return values:
EOK Currently always.

Definition at line 84 of file pipepriv.c.

void pipe_drop_ref ( usb_pipe_t *  pipe  ) 

Drop active transfer reference on the pipe.

Parameters:
pipe The USB pipe.

Definition at line 116 of file pipepriv.c.

void pipe_end_transaction ( usb_pipe_t *  pipe  ) 

Terminate exclusive access to the IPC phone of given pipe.

Parameters:
pipe Pipe to be released from exclusive usage.

Definition at line 53 of file pipepriv.c.

void pipe_release ( usb_pipe_t *  pipe  ) 

Terminate exclusive access to the pipe as a whole.

Parameters:
pipe Pipe to be released from exclusive usage.

Definition at line 71 of file pipepriv.c.

void pipe_start_transaction ( usb_pipe_t *  pipe  ) 

Ensure exclusive access to the IPC phone of given pipe.

Parameters:
pipe Pipe to be exclusively accessed.

Definition at line 44 of file pipepriv.c.

static int polling_fibril ( void *  arg  )  [static]

Polling fibril.

Parameters:
arg Pointer to polling_data_t.
Returns:
Always EOK.

Definition at line 69 of file devpoll.c.

static int process_endpoint ( usb_endpoint_mapping_t *  mapping,
size_t  mapping_count,
usb_standard_interface_descriptor_t *  interface,
usb_standard_endpoint_descriptor_t *  endpoint,
usb_device_connection_t *  wire 
) [static]

Process endpoint descriptor.

Parameters:
mapping Endpoint mapping list.
mapping_count Number of endpoint mappings in mapping.
interface Interface descriptor under which belongs the endpoint.
endpoint Endpoint descriptor.
wire Connection backing the endpoint pipes.
Returns:
Error code.

Definition at line 156 of file pipesinit.c.

static int process_interface ( usb_endpoint_mapping_t *  mapping,
size_t  mapping_count,
usb_dp_parser_t *  parser,
usb_dp_parser_data_t *  parser_data,
uint8_t *  interface_descriptor 
) [static]

Process whole USB interface.

Parameters:
mapping Endpoint mapping list.
mapping_count Number of endpoint mappings in mapping.
parser Descriptor parser.
parser_data Descriptor parser data.
interface_descriptor Interface descriptor.
Returns:
Error code.

Definition at line 224 of file pipesinit.c.

static uint8_t* skip_nested_descriptors ( usb_dp_parser_t *  parser,
usb_dp_parser_data_t *  data,
uint8_t *  parent 
) [static]

Skip all nested descriptors.

Parameters:
parser Parser.
data Parser data.
parent Pointer to the beginning of parent descriptor.
Returns:
Pointer to first non-child descriptor.
Return values:
NULL No next descriptor.
NULL Invalid input.

Definition at line 213 of file dp.c.

static int usb_add_match_id ( match_id_list_t *  matches,
int  score,
const char *  format,
  ... 
) [static]

Add formatted match id.

Parameters:
matches List of match ids where to add to.
score Score of the match.
format Printf-like format
Returns:
Error code.

Definition at line 76 of file recognise.c.

int usb_alternate_interfaces_create ( uint8_t *  config_descr,
size_t  config_descr_size,
int  interface_number,
usb_alternate_interfaces_t **  alternates_ptr 
)

Create alternate interface representation structure.

Parameters:
[in] config_descr Configuration descriptor.
[in] config_descr_size Size of configuration descriptor.
[in] interface_number Interface number.
[out] alternates_ptr Where to store pointer to allocated structure.
Returns:
Error code.

Definition at line 92 of file altiface.c.

int usb_control_request_get ( usb_pipe_t *  pipe,
usb_request_type_t  request_type,
usb_request_recipient_t  recipient,
uint8_t  request,
uint16_t  value,
uint16_t  index,
void *  data,
size_t  data_size,
size_t *  actual_data_size 
)

Generic wrapper for GET requests using standard control request format.

See also:
usb_pipe_control_read
Parameters:
pipe Pipe used for the communication.
request_type Request type (standard/class/vendor).
recipient Request recipient (e.g. device or endpoint).
request Actual request (e.g. GET_DESCRIPTOR).
value Value of wValue field of setup packet (must be in USB endianness).
index Value of wIndex field of setup packet (must be in USB endianness).
data Buffer where to store data accepted during the DATA stage. (they will come in USB endianness).
data_size Size of the data buffer (in native endianness).
actual_data_size Actual size of transfered data (in native endianness).
Returns:
Error code.
Return values:
EBADMEM pipe is NULL.
EBADMEM data is NULL and data_size is not zero.
ERANGE Data buffer too large.

Definition at line 122 of file request.c.

int usb_control_request_set ( usb_pipe_t *  pipe,
usb_request_type_t  request_type,
usb_request_recipient_t  recipient,
uint8_t  request,
uint16_t  value,
uint16_t  index,
void *  data,
size_t  data_size 
)

Generic wrapper for SET requests using standard control request format.

See also:
usb_pipe_control_write
Parameters:
pipe Pipe used for the communication.
request_type Request type (standard/class/vendor).
recipient Request recipient (e.g. device or endpoint).
request Actual request (e.g. GET_DESCRIPTOR).
value Value of wValue field of setup packet (must be in USB endianness).
index Value of wIndex field of setup packet (must be in USB endianness).
data Data to be sent during DATA stage (expected to be in USB endianness).
data_size Size of the data buffer (in native endianness).
Returns:
Error code.
Return values:
EBADMEM pipe is NULL.
EBADMEM data is NULL and data_size is not zero.
ERANGE Data buffer too large.

Definition at line 62 of file request.c.

int usb_device_auto_poll ( usb_device_t *  dev,
size_t  pipe_index,
usb_polling_callback_t  callback,
size_t  request_size,
usb_polling_terminted_callback_t  terminated_callback,
void *  arg 
)

Start automatic device polling over interrupt in pipe.

Warning:
It is up to the callback to produce delays between individual requests.

There is no guarantee when the request to the device will be sent for the first time (it is possible that this first request would be executed prior to return from this function).

Parameters:
dev Device to be periodically polled.
pipe_index Index of the endpoint pipe used for polling.
callback Callback when data are available.
request_size How many bytes to ask for in each request.
terminated_callback Callback when polling is terminated.
arg Custom argument (passed as is to the callbacks).
Returns:
Error code.
Return values:
EOK New fibril polling the device was already started.

Definition at line 200 of file devpoll.c.

int usb_device_auto_polling ( usb_device_t *  dev,
size_t  pipe_index,
usb_device_auto_polling_t *  polling,
size_t  request_size,
void *  arg 
)

Start automatic device polling over interrupt in pipe.

The polling settings is copied thus it is okay to destroy the structure after this function returns.

Warning:
There is no guarantee when the request to the device will be sent for the first time (it is possible that this first request would be executed prior to return from this function).
Parameters:
dev Device to be periodically polled.
pipe_index Index of the endpoint pipe used for polling.
polling Polling settings.
request_size How many bytes to ask for in each request.
arg Custom argument (passed as is to the callbacks).
Returns:
Error code.
Return values:
EOK New fibril polling the device was already started.

Definition at line 254 of file devpoll.c.

int usb_device_connection_initialize ( usb_device_connection_t *  connection,
devman_handle_t  host_controller_handle,
usb_address_t  device_address 
)

Initialize connection to USB device.

Parameters:
connection Connection structure to be initialized.
host_controller_handle Devman handle of host controller device is connected to.
device_address Device USB address.
Returns:
Error code.

Definition at line 169 of file pipes.c.

int usb_device_connection_initialize_from_device ( usb_device_connection_t *  connection,
ddf_dev_t *  dev 
)

Initialize connection to USB device.

Parameters:
connection Connection structure to be initialized.
dev Generic device backing the USB device.
Returns:
Error code.

Definition at line 107 of file pipes.c.

int usb_device_connection_initialize_on_default_address ( usb_device_connection_t *  dev_connection,
usb_hc_connection_t *  hc_connection 
)

Initialize connection to USB device on default address.

Parameters:
dev_connection Device connection structure to be initialized.
hc_connection Initialized connection to host controller.
Returns:
Error code.

Definition at line 190 of file pipes.c.

int usb_device_create ( ddf_dev_t *  ddf_dev,
usb_endpoint_description_t **  endpoints,
usb_device_t **  dev_ptr,
const char **  errstr_ptr 
)

Create new instance of USB device.

Parameters:
[in] ddf_dev Generic DDF device backing the USB one.
[in] endpoints NULL terminated array of endpoints (NULL for none).
[out] dev_ptr Where to store pointer to the new device.
[out] errstr_ptr Where to store description of context (in case error occurs).
Returns:
Error code.

Definition at line 472 of file devdrv.c.

int usb_device_create_match_ids ( usb_pipe_t *  ctrl_pipe,
match_id_list_t *  matches 
)

Create match ids describing attached device.

Warning:
The list of match ids matches may change even when function exits with error.
Parameters:
ctrl_pipe Control pipe to given device (session must be already started).
matches Initialized list of match ids.
Returns:
Error code.

Definition at line 313 of file recognise.c.

int usb_device_create_match_ids_from_device_descriptor ( const usb_standard_device_descriptor_t *  device_descriptor,
match_id_list_t *  matches 
)

Create DDF match ids from USB device descriptor.

Parameters:
matches List of match ids to extend.
device_descriptor Device descriptor returned by given device.
Returns:
Error code.

Definition at line 262 of file recognise.c.

int usb_device_create_match_ids_from_interface ( const usb_standard_device_descriptor_t *  desc_device,
const usb_standard_interface_descriptor_t *  desc_interface,
match_id_list_t *  matches 
)

Create device match ids based on its interface.

Parameters:
[in] desc_device Device descriptor.
[in] desc_interface Interface descriptor.
[out] matches Initialized list of match ids.
Returns:
Error code (the two mentioned are not the only ones).
Return values:
EINVAL Invalid input parameters (expects non NULL pointers).
ENOENT Device class is not "use interface".

Definition at line 147 of file recognise.c.

int usb_device_create_pipes ( ddf_dev_t *  dev,
usb_device_connection_t *  wire,
usb_endpoint_description_t **  endpoints,
uint8_t *  config_descr,
size_t  config_descr_size,
int  interface_no,
int  interface_setting,
usb_endpoint_mapping_t **  pipes_ptr,
size_t *  pipes_count_ptr 
)

Create pipes for a device.

This is more or less a wrapper that does following actions:

Parameters:
[in] dev Generic DDF device backing the USB one.
[in] wire Initialized backing connection to the host controller.
[in] endpoints Endpoints description, NULL terminated.
[in] config_descr Configuration descriptor of active configuration.
[in] config_descr_size Size of config_descr in bytes.
[in] interface_no Interface to map from.
[in] interface_setting Interface setting (default is usually 0).
[out] pipes_ptr Where to store array of created pipes (not NULL terminated).
[out] pipes_count_ptr Where to store number of pipes (set to if you wish to ignore the count).
Returns:
Error code.

Definition at line 277 of file devdrv.c.

void usb_device_destroy ( usb_device_t *  dev  ) 

Destroy instance of a USB device.

Parameters:
dev Device to be destroyed.

Definition at line 539 of file devdrv.c.

int usb_device_destroy_pipes ( ddf_dev_t *  dev,
usb_endpoint_mapping_t *  pipes,
size_t  pipes_count 
)

Destroy pipes previously created by usb_device_create_pipes.

Parameters:
[in] dev Generic DDF device backing the USB one.
[in] pipes Endpoint mapping to be destroyed.
[in] pipes_count Number of endpoints.

Definition at line 397 of file devdrv.c.

int usb_device_get_assigned_interface ( ddf_dev_t *  device  ) 

Tell USB interface assigned to given device.

Parameters:
device Device in question.
Returns:
Interface number (negative code means any).

Definition at line 79 of file pipes.c.

int usb_device_register_child_in_devman ( usb_address_t  address,
devman_handle_t  hc_handle,
ddf_dev_t *  parent,
devman_handle_t *  child_handle,
ddf_dev_ops_t *  dev_ops,
void *  dev_data,
ddf_fun_t **  child_fun 
)

Probe for device kind and register it in devman.

Parameters:
[in] address Address of the (unknown) attached device.
[in] hc_handle Handle of the host controller.
[in] parent Parent device.
[out] child_handle Handle of the child device.
[in] dev_ops Child device ops.
[in] dev_data Arbitrary pointer to be stored in the child as driver_data.
[out] child_fun Storage where pointer to allocated child function will be written.
Returns:
Error code.

Definition at line 349 of file recognise.c.

int usb_device_retrieve_descriptors ( usb_pipe_t *  ctrl_pipe,
usb_device_descriptors_t *  descriptors 
)

Retrieve basic descriptors from the device.

Parameters:
[in] ctrl_pipe Control endpoint pipe.
[out] descriptors Where to store the descriptors.
Returns:
Error code.

Definition at line 228 of file devdrv.c.

int usb_device_select_interface ( usb_device_t *  dev,
uint8_t  alternate_setting,
usb_endpoint_description_t **  endpoints 
)

Change interface setting of a device.

This function selects new alternate setting of an interface by issuing proper USB command to the device and also creates new USB pipes under dev->pipes.

Warning:
This function is intended for drivers working at interface level. For drivers controlling the whole device, you need to change interface manually using usb_request_set_interface() and creating new pipes with usb_pipe_initialize_from_configuration().

This is a wrapper function that does several operations that can fail and that cannot be rollbacked easily. That means that a failure during the SET_INTERFACE request would result in having a device with no pipes at all (except the default control one). That is because the old pipes needs to be unregistered at HC first and the new ones could not be created.

Parameters:
dev USB device.
alternate_setting Alternate setting to choose.
endpoints New endpoint descriptions.
Returns:
Error code.

Definition at line 194 of file devdrv.c.

static void usb_dp_browse_simple_internal ( usb_dp_parser_t *  parser,
usb_dp_parser_data_t *  data,
uint8_t *  root,
size_t  depth,
void(*)(uint8_t *, size_t, void *)  callback,
void *  arg 
) [static]

Browser of the descriptor tree.

See also:
usb_dp_walk_simple
Parameters:
parser Descriptor parser.
data Data for descriptor parser.
root Pointer to current root of the tree.
depth Current nesting depth.
callback Callback for each found descriptor.
arg Custom (user) argument.

Definition at line 271 of file dp.c.

uint8_t * usb_dp_get_nested_descriptor ( usb_dp_parser_t *  parser,
usb_dp_parser_data_t *  data,
uint8_t *  parent 
)

Find first nested descriptor of given parent.

Parameters:
parser Parser.
data Parser data.
parent Pointer to the beginning of parent descriptor.
Returns:
Pointer to the beginning of the first nested (child) descriptor.
Return values:
NULL No child descriptor found.
NULL Invalid input.

Definition at line 185 of file dp.c.

uint8_t * usb_dp_get_sibling_descriptor ( usb_dp_parser_t *  parser,
usb_dp_parser_data_t *  data,
uint8_t *  parent,
uint8_t *  sibling 
)

Get sibling descriptor.

Parameters:
parser Parser.
data Parser data.
parent Pointer to common parent descriptor.
sibling Left sibling.
Returns:
Pointer to first right sibling of sibling.
Return values:
NULL No sibling exist.
NULL Invalid input.

Definition at line 238 of file dp.c.

void usb_dp_walk_simple ( uint8_t *  descriptors,
size_t  descriptors_size,
usb_dp_descriptor_nesting_t *  descriptor_nesting,
void(*)(uint8_t *, size_t, void *)  callback,
void *  arg 
)

Browse flatten descriptor tree.

The callback is called with following arguments: pointer to the start of the descriptor (somewhere inside descriptors), depth of the nesting (starting from 0 for the first descriptor) and the custom argument. Note that the size of the descriptor is not passed because it can be read from the first byte of the descriptor.

Parameters:
descriptors Descriptor data.
descriptors_size Size of descriptor data (in bytes).
descriptor_nesting Possible descriptor nesting.
callback Callback for each found descriptor.
arg Custom (user) argument.

Definition at line 302 of file dp.c.

int usb_driver_main ( usb_driver_t *  drv  ) 

Main routine of USB device driver.

Under normal conditions, this function never returns.

Parameters:
drv USB device driver structure.
Returns:
Task exit status.

Definition at line 62 of file devdrv.c.

int usb_hc_new_device_wrapper ( ddf_dev_t *  parent,
usb_hc_connection_t *  connection,
usb_speed_t  dev_speed,
int(*)(int port_no, void *arg)  enable_port,
int  port_no,
void *  arg,
usb_address_t *  assigned_address,
devman_handle_t *  assigned_handle,
ddf_dev_ops_t *  dev_ops,
void *  new_dev_data,
ddf_fun_t **  new_fun 
)

Wrapper for registering attached device to the hub.

The enable_port function is expected to enable signaling on given port. The two arguments to it can have arbitrary meaning (the port_no is only a suggestion) and are not touched at all by this function (they are passed as is to the enable_port function).

If the enable_port fails (i.e. does not return EOK), the device addition is canceled. The return value is then returned (it is good idea to use different error codes than those listed as return codes by this function itself).

The connection representing connection with host controller does not need to be started. This function duplicates the connection to allow simultaneous calls of this function (i.e. from different fibrils).

Parameters:
[in] parent Parent device (i.e. the hub device).
[in] connection Connection to host controller.
[in] dev_speed New device speed.
[in] enable_port Function for enabling signaling through the port the device is attached to.
[in] port_no Port number (passed through to enable_port).
[in] arg Any data argument to enable_port.
[out] assigned_address USB address of the device.
[out] assigned_handle Devman handle of the new device.
[in] dev_ops Child device ops.
[in] new_dev_data Arbitrary pointer to be stored in the child as driver_data.
[out] new_fun Storage where pointer to allocated child function will be written.
Returns:
Error code.
Return values:
ENOENT Connection to HC not opened.
EADDRNOTAVAIL Failed retrieving free address from host controller.
EBUSY Failed reserving default USB address.
ENOTCONN Problem connecting to the host controller via USB pipe.
ESTALL Problem communication with device (either SET_ADDRESS request or requests for descriptors when creating match ids).

Definition at line 184 of file hub.c.

int usb_hc_register_device ( usb_hc_connection_t *  connection,
const usb_hc_attached_device_t *  attached_device 
)

Inform host controller about new device.

Parameters:
connection Opened connection to host controller.
attached_device Information about the new device.
Returns:
Error code.

Definition at line 92 of file hub.c.

usb_address_t usb_hc_request_address ( usb_hc_connection_t *  connection,
usb_speed_t  speed 
)

Ask host controller for free address assignment.

Parameters:
connection Opened connection to host controller.
speed Speed of the new device (device that will be assigned the returned address).
Returns:
Assigned USB address or negative error code.

Definition at line 69 of file hub.c.

int usb_hc_unregister_device ( usb_hc_connection_t *  connection,
usb_address_t  address 
)

Inform host controller about device removal.

Parameters:
connection Opened connection to host controller.
address Address of the device that is being removed.
Returns:
Error code.

Definition at line 112 of file hub.c.

size_t usb_interface_count_alternates ( uint8_t *  config_descr,
size_t  config_descr_size,
uint8_t  interface_no 
)

Count number of alternate settings of a interface.

Parameters:
config_descr Full configuration descriptor.
config_descr_size Size of config_descr in bytes.
interface_no Interface number.
Returns:
Number of alternate interfaces for interface_no interface.

Definition at line 50 of file altiface.c.

int usb_pipe_clear_halt ( usb_pipe_t *  ctrl_pipe,
usb_pipe_t *  target_pipe 
)

Clear halt bit of an endpoint pipe (after pipe stall).

Parameters:
ctrl_pipe Control pipe.
target_pipe Which pipe is halted and shall be cleared.
Returns:
Error code.

Definition at line 893 of file request.c.

int usb_pipe_control_read ( usb_pipe_t *  pipe,
void *  setup_buffer,
size_t  setup_buffer_size,
void *  data_buffer,
size_t  data_buffer_size,
size_t *  data_transfered_size 
)

Request a control read transfer on an endpoint pipe.

This function encapsulates all three stages of a control transfer.

Parameters:
[in] pipe Pipe used for the transfer.
[in] setup_buffer Buffer with the setup packet.
[in] setup_buffer_size Size of the setup packet (in bytes).
[out] data_buffer Buffer for incoming data.
[in] data_buffer_size Size of the buffer for incoming data (in bytes).
[out] data_transfered_size Number of bytes that were actually transfered during the DATA stage.
Returns:
Error code.

Definition at line 428 of file pipesio.c.

static int usb_pipe_control_read_no_check ( usb_pipe_t *  pipe,
void *  setup_buffer,
size_t  setup_buffer_size,
void *  data_buffer,
size_t  data_buffer_size,
size_t *  data_transfered_size 
) [static]

Request a control read transfer, no checking of input parameters.

Parameters:
[in] pipe Pipe used for the transfer.
[in] setup_buffer Buffer with the setup packet.
[in] setup_buffer_size Size of the setup packet (in bytes).
[out] data_buffer Buffer for incoming data.
[in] data_buffer_size Size of the buffer for incoming data (in bytes).
[out] data_transfered_size Number of bytes that were actually transfered during the DATA stage.
Returns:
Error code.

Definition at line 341 of file pipesio.c.

int usb_pipe_control_write ( usb_pipe_t *  pipe,
void *  setup_buffer,
size_t  setup_buffer_size,
void *  data_buffer,
size_t  data_buffer_size 
)

Request a control write transfer on an endpoint pipe.

This function encapsulates all three stages of a control transfer.

Parameters:
[in] pipe Pipe used for the transfer.
[in] setup_buffer Buffer with the setup packet.
[in] setup_buffer_size Size of the setup packet (in bytes).
[in] data_buffer Buffer with data to be sent.
[in] data_buffer_size Size of the buffer with outgoing data (in bytes).
Returns:
Error code.

Definition at line 556 of file pipesio.c.

static int usb_pipe_control_write_no_check ( usb_pipe_t *  pipe,
void *  setup_buffer,
size_t  setup_buffer_size,
void *  data_buffer,
size_t  data_buffer_size 
) [static]

Request a control write transfer, no checking of input parameters.

Parameters:
[in] pipe Pipe used for the transfer.
[in] setup_buffer Buffer with the setup packet.
[in] setup_buffer_size Size of the setup packet (in bytes).
[in] data_buffer Buffer with data to be sent.
[in] data_buffer_size Size of the buffer with outgoing data (in bytes).
Returns:
Error code.

Definition at line 486 of file pipesio.c.

void usb_pipe_end_long_transfer ( usb_pipe_t *  pipe  ) 

Terminate a long transfer on a pipe.

See also:
usb_pipe_start_long_transfer
Parameters:
pipe Pipe where to end the long transfer.

Definition at line 225 of file pipes.c.

int usb_pipe_initialize ( usb_pipe_t *  pipe,
usb_device_connection_t *  connection,
usb_endpoint_t  endpoint_no,
usb_transfer_type_t  transfer_type,
size_t  max_packet_size,
usb_direction_t  direction 
)

Initialize USB endpoint pipe.

Parameters:
pipe Endpoint pipe to be initialized.
connection Connection to the USB device backing this pipe (the wire).
endpoint_no Endpoint number (in USB 1.1 in range 0 to 15).
transfer_type Transfer type (e.g. interrupt or bulk).
max_packet_size Maximum packet size in bytes.
direction Endpoint direction (in/out).
Returns:
Error code.

Definition at line 350 of file pipesinit.c.

int usb_pipe_initialize_default_control ( usb_pipe_t *  pipe,
usb_device_connection_t *  connection 
)

Initialize USB endpoint pipe as the default zero control pipe.

Parameters:
pipe Endpoint pipe to be initialized.
connection Connection to the USB device backing this pipe (the wire).
Returns:
Error code.

Definition at line 380 of file pipesinit.c.

int usb_pipe_initialize_from_configuration ( usb_endpoint_mapping_t *  mapping,
size_t  mapping_count,
uint8_t *  configuration_descriptor,
size_t  configuration_descriptor_size,
usb_device_connection_t *  connection 
)

Initialize endpoint pipes from configuration descriptor.

The mapping array is expected to conform to following rules:

After processing the configuration descriptor, the mapping is updated in the following fashion:

Parameters:
mapping Endpoint mapping list.
mapping_count Number of endpoint mappings in mapping.
configuration_descriptor Full configuration descriptor (is expected to be in USB endianness: i.e. as-is after being retrieved from the device).
configuration_descriptor_size Size of configuration_descriptor in bytes.
connection Connection backing the endpoint pipes.
Returns:
Error code.

Definition at line 284 of file pipesinit.c.

int usb_pipe_probe_default_control ( usb_pipe_t *  pipe  ) 

Probe default control pipe for max packet size.

The function tries to get the correct value of max packet size several time before giving up.

The session on the pipe shall not be started.

Parameters:
pipe Default control pipe.
Returns:
Error code.

Definition at line 405 of file pipesinit.c.

int usb_pipe_read ( usb_pipe_t *  pipe,
void *  buffer,
size_t  size,
size_t *  size_transfered 
)

Request a read (in) transfer on an endpoint pipe.

Parameters:
[in] pipe Pipe used for the transfer.
[out] buffer Buffer where to store the data.
[in] size Size of the buffer (in bytes).
[out] size_transfered Number of bytes that were actually transfered.
Returns:
Error code.

Definition at line 153 of file pipesio.c.

static int usb_pipe_read_no_checks ( usb_pipe_t *  pipe,
void *  buffer,
size_t  size,
size_t *  size_transfered 
) [static]

Request an in transfer, no checking of input parameters.

Parameters:
[in] pipe Pipe used for the transfer.
[out] buffer Buffer where to store the data.
[in] size Size of the buffer (in bytes).
[out] size_transfered Number of bytes that were actually transfered.
Returns:
Error code.

Definition at line 62 of file pipesio.c.

int usb_pipe_register ( usb_pipe_t *  pipe,
unsigned int  interval,
usb_hc_connection_t *  hc_connection 
)

Register endpoint with the host controller.

Parameters:
pipe Pipe to be registered.
interval Polling interval.
hc_connection Connection to the host controller (must be opened).
Returns:
Error code.

Definition at line 457 of file pipesinit.c.

int usb_pipe_register_with_speed ( usb_pipe_t *  pipe,
usb_speed_t  speed,
unsigned int  interval,
usb_hc_connection_t *  hc_connection 
)

Register endpoint with a speed at the host controller.

You will rarely need to use this function because it is needed only if the registered endpoint is of address 0 and there is no other way to tell speed of the device at address 0.

Parameters:
pipe Pipe to be registered.
speed Speed of the device (invalid speed means use previously specified one).
interval Polling interval.
hc_connection Connection to the host controller (must be opened).
Returns:
Error code.

Definition at line 478 of file pipesinit.c.

void usb_pipe_start_long_transfer ( usb_pipe_t *  pipe  ) 

Prepare pipe for a long transfer.

By a long transfer is mean transfer consisting of several requests to the HC. Calling such function is optional and it has positive effect of improved performance because IPC session is initiated only once.

Parameters:
pipe Pipe over which the transfer will happen.
Returns:
Error code.

Definition at line 214 of file pipes.c.

int usb_pipe_unregister ( usb_pipe_t *  pipe,
usb_hc_connection_t *  hc_connection 
)

Revert endpoint registration with the host controller.

Parameters:
pipe Pipe to be unregistered.
hc_connection Connection to the host controller (must be opened).
Returns:
Error code.

Definition at line 508 of file pipesinit.c.

int usb_pipe_write ( usb_pipe_t *  pipe,
void *  buffer,
size_t  size 
)

Request a write (out) transfer on an endpoint pipe.

Parameters:
[in] pipe Pipe used for the transfer.
[in] buffer Buffer with data to transfer.
[in] size Size of the buffer (in bytes).
Returns:
Error code.

Definition at line 275 of file pipesio.c.

static int usb_pipe_write_no_check ( usb_pipe_t *  pipe,
void *  buffer,
size_t  size 
) [static]

Request an out transfer, no checking of input parameters.

Parameters:
[in] pipe Pipe used for the transfer.
[in] buffer Buffer with data to transfer.
[in] size Size of the buffer (in bytes).
Returns:
Error code.

Definition at line 208 of file pipesio.c.

int usb_request_clear_endpoint_halt ( usb_pipe_t *  pipe,
uint16_t  ep_index 
)

Clear halt bit of an endpoint pipe (after pipe stall).

Parameters:
pipe Control pipe.
ep_index Endpoint index (in native endianness).
Returns:
Error code.

Definition at line 879 of file request.c.

int usb_request_clear_feature ( usb_pipe_t *  pipe,
usb_request_type_t  request_type,
usb_request_recipient_t  recipient,
uint16_t  feature_selector,
uint16_t  index 
)

Clear or disable specific device feature.

Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[in] request_type Request type (standard/class/vendor).
[in] recipient Recipient of the CLEAR_FEATURE request.
[in] feature_selector Feature selector (in native endianness).
[in] index Recipient index (in native endianness).
Returns:
Error code.

Definition at line 205 of file request.c.

int usb_request_get_bare_configuration_descriptor ( usb_pipe_t *  pipe,
int  index,
usb_standard_configuration_descriptor_t *  descriptor 
)

Retrieve configuration descriptor of a USB device.

The function does not retrieve additional data binded with configuration descriptor (such as its interface and endpoint descriptors) - use usb_request_get_full_configuration_descriptor() instead.

Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[in] index Descriptor index.
[out] descriptor Storage for the device descriptor.
Returns:
Error code.

Definition at line 444 of file request.c.

int usb_request_get_configuration ( usb_pipe_t *  pipe,
uint8_t *  configuration_value 
)

Get current configuration value of USB device.

Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[out] configuration_value Current configuration value.
Returns:
Error code.

Definition at line 608 of file request.c.

int usb_request_get_descriptor ( usb_pipe_t *  pipe,
usb_request_type_t  request_type,
usb_request_recipient_t  recipient,
uint8_t  descriptor_type,
uint8_t  descriptor_index,
uint16_t  language,
void *  buffer,
size_t  size,
size_t *  actual_size 
)

Retrieve USB descriptor of a USB device.

Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[in] request_type Request type (standard/class/vendor).
[in] recipient Request recipient (device/interface/endpoint).
[in] descriptor_type Descriptor type (device/configuration/HID/...).
[in] descriptor_index Descriptor index.
[in] language Language index.
[out] buffer Buffer where to store the retrieved descriptor.
[in] size Size of the buffer.
[out] actual_size Number of bytes actually transferred.
Returns:
Error code.

Definition at line 299 of file request.c.

int usb_request_get_descriptor_alloc ( usb_pipe_t *  pipe,
usb_request_type_t  request_type,
usb_request_recipient_t  recipient,
uint8_t  descriptor_type,
uint8_t  descriptor_index,
uint16_t  language,
void **  buffer_ptr,
size_t *  buffer_size 
)

Retrieve USB descriptor, allocate space for it.

Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[in] request_type Request type (standard/class/vendor).
[in] recipient Request recipient (device/interface/endpoint).
[in] descriptor_type Descriptor type (device/configuration/HID/...).
[in] descriptor_index Descriptor index.
[in] language Language index.
[out] buffer_ptr Where to store pointer to allocated buffer.
[out] buffer_size Where to store the size of the descriptor.
Returns:

Definition at line 333 of file request.c.

int usb_request_get_device_descriptor ( usb_pipe_t *  pipe,
usb_standard_device_descriptor_t *  descriptor 
)

Retrieve standard device descriptor of a USB device.

Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[out] descriptor Storage for the device descriptor.
Returns:
Error code.

Definition at line 402 of file request.c.

int usb_request_get_endpoint_status ( usb_pipe_t *  ctrl_pipe,
usb_pipe_t *  pipe,
uint16_t *  status 
)

Get endpoint status.

Parameters:
[in] ctrl_pipe Control pipe.
[in] pipe Of which pipe the status shall be received.
[out] status Where to store pipe status (in native endianness).
Returns:
Error code.

Definition at line 909 of file request.c.

int usb_request_get_full_configuration_descriptor ( usb_pipe_t *  pipe,
int  index,
void *  descriptor,
size_t  descriptor_size,
size_t *  actual_size 
)

Retrieve full configuration descriptor of a USB device.

Warning:
The buffer might be touched (i.e. its contents changed) even when error occurs.
Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[in] index Descriptor index.
[out] descriptor Storage for the device descriptor.
[in] descriptor_size Size of descriptor buffer.
[out] actual_size Number of bytes actually transferred.
Returns:
Error code.

Definition at line 490 of file request.c.

int usb_request_get_full_configuration_descriptor_alloc ( usb_pipe_t *  pipe,
int  index,
void **  descriptor_ptr,
size_t *  descriptor_size 
)

Retrieve full configuration descriptor, allocate space for it.

The function takes care that full configuration descriptor is returned (i.e. the function will fail when less data then descriptor.totalLength is returned).

Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[in] index Configuration index.
[out] descriptor_ptr Where to store pointer to allocated buffer.
[out] descriptor_size Where to store the size of the descriptor.
Returns:
Error code.

Definition at line 515 of file request.c.

int usb_request_get_interface ( usb_pipe_t *  pipe,
uint8_t  interface_index,
uint8_t *  alternate_setting 
)

Get selected alternate setting for USB interface.

Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[in] interface_index Interface index.
[out] alternate_setting Alternate setting for the interface.
Returns:
Error code.

Definition at line 659 of file request.c.

int usb_request_get_status ( usb_pipe_t *  pipe,
usb_request_recipient_t  recipient,
uint16_t  index,
uint16_t *  status 
)

Retrieve status of a USB device.

Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[in] index Recipient index (in native endianness).
[in] recipient Recipient of the GET_STATUS request.
[out] status Recipient status (in native endianness).
Returns:
Error code.

Definition at line 167 of file request.c.

int usb_request_get_string ( usb_pipe_t *  pipe,
size_t  index,
l18_win_locales_t  lang,
char **  string_ptr 
)

Get string (descriptor) from USB device.

The string is returned in native encoding of the operating system. For HelenOS, that is UTF-8.

Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[in] index String index (in native endianness), first index has number 1 (index from descriptors can be used directly).
[in] lang String language (in native endianness).
[out] string_ptr Where to store allocated string in native encoding.
Returns:
Error code.

Definition at line 783 of file request.c.

int usb_request_get_supported_languages ( usb_pipe_t *  pipe,
l18_win_locales_t **  languages_ptr,
size_t *  languages_count 
)

Get list of supported languages by USB device.

Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[out] languages_ptr Where to store pointer to allocated array of supported languages.
[out] languages_count Number of supported languages.
Returns:
Error code.

Definition at line 711 of file request.c.

int usb_request_set_address ( usb_pipe_t *  pipe,
usb_address_t  new_address 
)

Change address of connected device.

This function automatically updates the backing connection to point to the new address.

Parameters:
pipe Control endpoint pipe (session must be already started).
new_address New USB address to be set (in native endianness).
Returns:
Error code.

Definition at line 260 of file request.c.

int usb_request_set_configuration ( usb_pipe_t *  pipe,
uint8_t  configuration_value 
)

Set configuration of USB device.

Parameters:
pipe Control endpoint pipe (session must be already started).
configuration_value New configuration value.
Returns:
Error code.

Definition at line 640 of file request.c.

int usb_request_set_descriptor ( usb_pipe_t *  pipe,
usb_request_type_t  request_type,
usb_request_recipient_t  recipient,
uint8_t  descriptor_type,
uint8_t  descriptor_index,
uint16_t  language,
void *  buffer,
size_t  size 
)

Update existing or add new USB descriptor to a USB device.

Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[in] request_type Request type (standard/class/vendor).
[in] recipient Request recipient (device/interface/endpoint).
[in] descriptor_type Descriptor type (device/configuration/HID/...).
[in] descriptor_index Descriptor index.
[in] language Language index (in native endianness).
[in] buffer Buffer with the new descriptor (in USB endianness).
[in] size Size of the buffer in bytes (in native endianness).
Returns:
Error code.

Definition at line 579 of file request.c.

int usb_request_set_feature ( usb_pipe_t *  pipe,
usb_request_type_t  request_type,
usb_request_recipient_t  recipient,
uint16_t  feature_selector,
uint16_t  index 
)

Set or enable specific device feature.

Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[in] request_type Request type (standard/class/vendor).
[in] recipient Recipient of the SET_FEATURE request.
[in] feature_selector Feature selector (in native endianness).
[in] index Recipient index (in native endianness).
Returns:
Error code.

Definition at line 233 of file request.c.

int usb_request_set_interface ( usb_pipe_t *  pipe,
uint8_t  interface_index,
uint8_t  alternate_setting 
)

Select alternate setting for USB interface.

Parameters:
[in] pipe Control endpoint pipe (session must be already started).
[in] interface_index Interface index.
[in] alternate_setting Alternate setting to select.
Returns:
Error code.

Definition at line 692 of file request.c.

Generated on Thu Jun 2 07:45:56 2011 for HelenOS/USB by  doxygen 1.4.7