Chapter 2. C A.P.I.

Table of Contents

1. usb/sys
1.1. ccall.h
1.2. errors.h
1.3. memory.h
1.4. events.h
1.5. fastacc.h
1.6. usb-defs.h
1.7. waiting.h
2. usb/lib
2.1. data-fast.h
2.2. data.h
2.3. dev-utils.h
2.4. lib.h
2.5. pipe-utils.h
2.6. log.h
2.7. time.h
2.8. decode.h
2.9. ctrlmsg.h
2.10. selectif.h
2.11. getnewdev.h
2.12. parsecmd.h
3. usb/
3.1. buffer.h
3.2. controller.h
3.3. defs.h
3.4. events.h
3.5. list.h
3.6. msg.h
3.7. pipe.h
3.8. reference.h
3.9. request.h
3.10. semaphor.h
3.11. sortmatr.h
3.12. structs.h
3.13. transaction.h
3.14. waiting.h
3.15. endpoint.h
3.16. slist.h

1. usb/sys

Header files in the usb/sys directory

1.1. ccall.h

Table of Contents

ccall_create - Inter C module calling wrapper.
ccall_free - Free inter C module calling wrapper.

Synopsis of function. macros and structures contained in ccall.h

1.2. errors.h

Table of Contents

USB_RESULT_OK - USB Error OK.
USB_RESULT_ALIAS_FILE_NOT_FOUND - USB Error alias not found.
USB_RESULT_STRUCTUR_DROPPED - USB Error structure dropped.
USB_RESULT_INVALID_PARAMETER - USB Error invalid parameter.
USB_RESULT_CONTROLLER_ALREADY_EXISTS - USB Error controller already exists.
USB_RESULT_BUS_INVALID_INTERNAL_2 - USB Error bus invalid internal 2.
USB_RESULT_ILLEGAL_SPEED - USB Error illegal speed
USB_RESULT_ALL_DEVICES_USED - USB Error all devices used
USB_RESULT_DEVICE_ADDRESS_USED - USB Error device address used
USB_RESULT_ENDPOINT_ADDRESS_USED - USB Error endpoint address used
USB_RESULT_INVALID_PIPE_STATE - USB Error invalid pipe state
USB_RESULT_NO_TRANSACTION_PENDING - USB Error no transaction pending
USB_RESULT_ERROR_GENERATED - USB Error error generated
USB_RESULT_NO_OBJECT_FOUND - USB Error no object found
USB_RESULT_BUS_CAPACITY_TO_SMALL - USB Error bus capacity too small
USB_RESULT_BUS_INVALID_PAYLOAD_SIZE - USB Error bus invalid payload size
USB_RESULT_BUS_INVALID_TRANSFER_TYPE - USB Error invalid transfer type
USB_RESULT_BUS_INVALID_INTERNAL_1 - USB Error invalid internal 1
USB_RESULT_NOT_ENOUGH_MEMORY - USB Error out of memory
USB_RESULT_TEMPORARY_FAILURE - Temporary failiure

Synopsis of function. macros and structures contained in errors.h

1.3. memory.h

Table of Contents

usb_dynamic_area_s - USB dynamic area structure

Synopsis of function. macros and structures contained in memory.h

1.4. events.h

Table of Contents

SERVICE_USB - USB system service call number
SERVICE_USB_PIPE_RELEASE - USB system service call reason code
SERVICE_USB_PIPE_EXCLUSIV - USB system service call reason code
SERVICE_USB_CONFIGURATION - USB system service call reason code
SERVICE_USB_INTERFACE - USB system service call reason code
SERVICE_USB_TRANSFER_CAP - USB system service call reason code
SERVICE_USB_POWER_CAP - USB system service call reason code
SERVICE_USB_CONTROLLER_STARTING - USB system service call reason code
SERVICE_USB_CONTROLLER_DYING - USB system service call reason code
SERVICE_USB_MODULE_STARTING - USB system service call reason code
SERVICE_USB_MODULE_DYING - USB system service call reason code
SERVICE_USB_MODULE_WANTS_TO_STOP - USB system service call reason code
SERVICE_USB_MODULE_STOP_RECOVER - USB system service call reason code
SERVICE_USB_HUB_EVENT - USB system service call reason code
SERVICE_USB_ROOT_HUB_EVENT - USB system service call reason code

Synopsis of function. macros and structures contained in events.h

1.5. fastacc.h

Table of Contents

usb_fast_access_init - Initialise fast acces library routines.
usb_fast_access_information - Gets fast access information
usb_endpoint_information - Returns information about a given endpoint.
usb_reqstart - USB request start structure.
usb_fast_access_struct - fast access structure.

Synopsis of function. macros and structures contained in fastacc.h

1.6. usb-defs.h

Table of Contents

USB_DRIVER_BASE - Base path for USB Device Drivers

Synopsis of function. macros and structures contained in usb-defs.h

1.7. waiting.h

Table of Contents

WAITING_TYPE_POLL - Waiting type for taskwindow
WAITING_TYPE_MESSAGE - Waiting type for wimp message
WAITING_TYPE_SWI - Waiting type for SWI
WAITING_TYPE_APCS - Waiting type for APCS function call
WAITING_TYPE_CALLBACK - Waiting type for OS_AddCallback
WAITING_TYPE_POLLWORD - Waiting type for use with Wimp Poll Word Non Zero
waiting_poll_s - poll waiting structure
waiting_message_s - waiting message structure
waiting_swi_s - waiting swi struct
waiting_apcs_s - waiting apcs call struct
waiting_pollword_s - waiting structure for pollword

Synopsis of function. macros and structures contained in waiting.h

2. usb/lib

Header files in the usb/lib directory

2.1. data-fast.h

Table of Contents

get_u8 - get unsigned 8bit value from the given pointer
get_u16 - get unsigned 16bit value from the given pointer
usb_addrof - convert the arguments into an 'unsigned long' pointing to the item of data in question
usb_do_dcg - version of usb_data_content_get() without any checks
usb_fast_dca - fast version of usb_data_content_address()
usb_fast_dcg - fast version of usb_data_content_get
get_off - convert off and arry paramters to a 'real' offset
usb_fast_dcs - Fast version of usb_data_content_set.

Synopsis of function. macros and structures contained in data-fast.h

2.2. data.h

Table of Contents

usblib_data_content_get - usblib_data_content_get
usblib_data_content_set - usblib_data_content_set
usblib_data_content_address - usblib_data_content_address
usb_data_content_get - general usb_data_content_get function call - switched between a function or macro depending on USB_DATA_FAST
usb_data_content_set - general usb_data_content_set function call - switched between a function or macro depending on USB_DATA_FAST
usb_data_content_address - general usb_data_content_address function call - switched between a function or macro depending on USB_DATA_FAST

Synopsis of function. macros and structures contained in data.h

2.3. dev-utils.h

Table of Contents

usb_find_device_ref - Obtains a device reference

Synopsis of function. macros and structures contained in dev-utils.h

2.4. lib.h

Table of Contents

usblib_init - USB Library initialisation
usblib_stop - USB Library finalisation
usblib_core_start - USB Library Core starting notification
usblib_core_stop - USB Library core stopping notifications
usblib_get_version - USB library version information

Synopsis of function. macros and structures contained in lib.h

2.5. pipe-utils.h

Table of Contents

usb_get_default_pipe - Obtains the default pipe on an endpoint

Synopsis of function. macros and structures contained in pipe-utils.h

2.6. log.h

Table of Contents

usb_log_create - creates a usb logging endpoint
usb_log_create_sub - creates a usb sub logging filehandle
usb_log_free - frees a logging filehandle
usb_log_restart - restarts a log
usb_log_clear - clears all memory resident entries from a log
usb_log_show_to_file - a function for usb_show_log to write current entries to the log's file
usb_show_log - send all currently memory buffered log entries to the supplied routine
usb_logf - logs a formated string to a log file

Synopsis of function. macros and structures contained in log.h

2.7. time.h

Table of Contents

usb_time_cs - obtains the time in teh usb system

Synopsis of function. macros and structures contained in time.h

2.8. decode.h

Table of Contents

usb_decode_transaction_result - usb_decode_transaction_result
usb_decode_result - decode a result returned from an USB function call

Synopsis of function. macros and structures contained in decode.h

2.9. ctrlmsg.h

Table of Contents

usblib_ctrl_msg - Sends an USB standard contrl message

Synopsis of function. macros and structures contained in ctrlmsg.h

2.10. selectif.h

Table of Contents

usblib_select_if - Select an setting for an interface of a device

Synopsis of function. macros and structures contained in selectif.h

2.11. getnewdev.h

Table of Contents

usblib_init_getdevice - find a new device either from command line or from unclaimed pool

Synopsis of function. macros and structures contained in getnewdev.h

2.12. parsecmd.h

Table of Contents

*usblib_parse_cmd_line - Parse command line for details of usb device

Synopsis of function. macros and structures contained in parsecmd.h

3. usb/

Header files in the usb/ directory

3.1. buffer.h

Table of Contents

usb_buffer_malloc - Allocates a buffer apropriate for a usb transaction.
usb_buffer_free - Frees a previously allocated buffer

Synopsis of function. macros and structures contained in buffer.h

3.2. controller.h

Table of Contents

usb_frame_sync_number - obtains the USB systems frame sync number.

Synopsis of function. macros and structures contained in controller.h

3.3. defs.h

Table of Contents

USB_OFFSET_TAG_GENERAL - general transaction substructure tag
USB_OFFSET_TAG_REQUEST - request transaction substructure tag
USB_OFFSET_TAG_FRAME - frame transaction substructure tag
USB_OFFSET_TAG_CONTROLLER - controller transaction substructure tag
USB_TRANSACTION_EXACT_SIZE - USB transaction Exact size flag
USB_TRANSACTION_FRAME_START - USB transaction frame start flag
USB_TRANSACTION_SETUP_EVAL - USB transaction setup eval flag
USB_TRANSACTION_STATUS_STAGE - USB transaction status stage flag
USB_TRANSACTION_TIMEOUT - USB transaction timeout enable
USB_TRANSACTION_REQUEST_FIRST - USB transaction request first flag
USB_TRANSACTION_CANCELLED - USB transaction cancelled flag
USB_TRANSACTION_RESULT_OK - USB transaction result ok
USB_TRANSACTION_RESULT_HALTED - USB transaction result halted
USB_TRANSACTION_RESULT_ABORTED - USB transaction result aborted
USB_TRANSACTION_RESULT_TRANSMISSION_FAILED - USB transaction result transmission failed
USB_TRANSACTION_RESULT_INVALID_SIZE - USB transaction result invalid size
USB_TRANSACTION_RESULT_WORKING - USB transaction result. The transaction is still working.
USB_TRANSACTION_RESULT_BUSPROTO_ERR - USB transaction result. Physical transmission protocol error
USB_TRANSACTION_RESULT_STALL - USB transaction result. Transfer stalled
USB_TRANSACTION_RESULT_NORESPONSE - USB transaction result. The device did not respond to the transaction
USB_TRANSACTION_RESULT_HC_BUFF_ERR - USB transaction result. Controller either ran out of buffer, or could not keep up with the data transfer
USB_TRANSACTION_RESULT_BUS_DATASZ - USB transaction result. Controller either ran out of buffer, or got too much data
USB_TRANSACTION_RESULT_INTERNAL - USB transaction result. Internal system error
USB_TRANSACTION_RESULT_TIMEOUT - USB transaction result - transaction timed out
USB_PIPE_TYPE_CONTROL - Pipe type for control pipe
USB_PIPE_TYPE_ISOCHRONUS - Pipe type for ISOCHRONOUS pipe
USB_PIPE_TYPE_BULK - Pipe type for a BULK pipe
USB_PIPE_TYPE_INTERRUPT - Pipe type for an INTERRUPT pipe
USB_PIPE_TYPE_MAX - Maximum value for USB_PIPE_TYPE
USB_PIPE_ADDRESS_MASK - Mask for pipe endpoint address
USB_PIPE_ADDRESS_BOTH - Bit definition for pipe being bi-directional
USB_PIPE_ADDRESS_IN - Bit definition for pipe being IN pipe
USB_PIPE_ADDRESS_OUT - Bit definition for pipe being OUT pipe
USB_PIPE_DEFAULT - Definition for address of default control pipe
USB_PIPE_CLEAR_ACTIVATE - USB_PIPE_CLEAR_ACTIVATE
USB_PIPE_OPEN_SHARED - Constant to use with usb_pipe_open to open a shared pipe
USB_REFERENCE_ENDPOINT - reference type for enpoint
USB_REFERENCE_DEVICE - reference type for enpoint
USB_REFERENCE_CONTROLLER - reference type for a host controller
USB_FIND_KEEP_REFERENCE - usb_find_object automatically increments the object reference
USB_FIND_NEXT_OBJECT - Enable searching with usb_find_object

Synopsis of function. macros and structures contained in defs.h

3.4. events.h

Table of Contents

usb_internal_broadcast_closing_event - Generate a broadcast closing event
usb_internal_claim_capacity - Generate a capacity claim event.
usb_internal_release_capacity - Generate a capacity release event.
usb_internal_core_start - Generate a core start event

Synopsis of function. macros and structures contained in events.h

3.5. list.h

Table of Contents

list_element_s - list element structure
list_element_storage_s - list element storage
list_head_s - list head structure
list_element_adress - obtains the address of a list element
list_reserve_element_storage - reserves list storage
list_note_position - remembers current list node position
list_initialize_storage - initializes list storage
list_release_storage - frees list storage
list_insert_element - inserts an element into a list
list_insert_element_no - insets an element at a given position
list_delete_actual_element_pi - deletes element pi
list_find_element - finds a given element
list_get_data_of_actual_element - gets data of an actual element
list_initialize_head - initialise a new list head
list_delete_element - removes a list entry
list_find_start - moves list enumerator to list start
list_find_first_element - obtains firs element in list
list_find_next_element - enumerates next list element and returns it
list_find_previous_element - enumerates previous element and returns
list_find_last_element - position list enumerator at the list end
list_delete_actual_element - removes element from list

Synopsis of function. macros and structures contained in list.h

3.6. msg.h

Table of Contents

usbmsg_class - enum of the permitted message classes
USBMSG_CLASS_USER - Base for user message class codes
usbmsg_hdr - usb message header structure
usbmsg_capacity_type - capacity types for capacity message class
usbmsg_capacity - capacity struct for capacity message class
usbmsg_hub_type - hub types for hub message class
usbmsg_hub - hub struct for hub message class
usbmsg_pipeexclusive - pipeexclusive struct for pipeexclusive message class
usbmsg_claiminterface - claim interface structure for claiminterface message class
usbmsg_configchange_type - configuration changed types for configchange message class
usbmsg_configchange - configchange structure for configchange message class
usbmsg_powercap_type - power capacity types for powercap message class
usbmsg_powercap - power capacity structure for powercap message class
usbmsg_new_device_try - new device phases for new_device message class
usbmsg_new_device_type - new device types for new_device message class
usbmsg_new_device - New device structure for new_device message class
usbmsg_contoller_type_e - controller types for contoller message class
usbmsg_controller - Controller structure for controller message class.
usbmsg_unclaimed_dev - message structure for unclaimed device management
USB_SETCONFIG_RESULT_UNKNOWN_TYPE - USB SetConfig result - unknown config type in type field
usbmsg_setconfig - USB Message to set configuration of a device / interface
usbmsg - USB message union for all represented message classes
usbmsg_send - Send a message to the USB system.
(*usbmsg_handler_t) - typedef for message handler function
usbmsg_register_handler - Register a message handler with USB system
usbmsg_deregister_handler - De register a message handler with USB system
usbmsg_filter - Adds a message class filter to a handler.
usbmsg_filterall - sets the filter for all message types

Synopsis of function. macros and structures contained in msg.h

3.7. pipe.h

Table of Contents

usb_pipe_t - USB Pipe type
usb_pipe_open - Opens a pipe on a given endpoint
usb_pipe_close - Closes a pipe on a given endpoint.
usb_pipe_clear - Clears all transactions from a given endpoint
usb_pipe_halt - Stops transaction processing on an endpoint

Synopsis of function. macros and structures contained in pipe.h

3.8. reference.h

Table of Contents

usb_reference_deregister - De-register reference to a structure
usb_find_object - find an object, or enumerate current objects

Synopsis of function. macros and structures contained in reference.h

3.9. request.h

Table of Contents

usb_request_start - start a request
usb_request_start2 - start a request with timeout
usb_request_get_state - get a request state on a given waiting structure

Synopsis of function. macros and structures contained in request.h

3.10. semaphor.h

Table of Contents

semaphor_s - Semaphor structure
semaphor_create - creates a semaphor
semaphor_drop - free a semaphor
semaphor_drop_request - free a request on a semaphor
semaphor_claim - Claim a semaphor
semaphor_release_and_check - Releases a semaphor and checks it
semaphor_release - Releases a semaphor
semaphor_reference_register - Adds a reference to a Semophore
semaphor_reference_deregister - Removes a reference to a semophore

Synopsis of function. macros and structures contained in semaphor.h

3.11. sortmatr.h

Table of Contents

sorted_matrix_initialize - initialize a sorted matrix
sorted_matrix_free - free a sorted matrix
sorted_matrix_find_element - find element in sorted matrix
sorted_matrix_find_next_element - Next element in sorted matrix
sorted_matrix_insert_element - insert element into sorted matrix
sorted_matrix_delete_element - Remove element from sorted matrix

Synopsis of function. macros and structures contained in sortmatr.h

3.12. structs.h

Table of Contents

usb_io_buffer_s - IO buffer structure
usb_io_buffer - definied type for usb_io_buffer
usb_transaction_basic_s - basic transaction structure
usb_hc_property_s - host controller property structure

Synopsis of function. macros and structures contained in structs.h

3.13. transaction.h

Table of Contents

usb_transaction_result - set the result of an transaction
(*usb_tracking_fn_t) - Tracking function typedef
usb_transaction_tracking - transaction tracking

Synopsis of function. macros and structures contained in transaction.h

3.14. waiting.h

Table of Contents

WAITING_TYPE_RETURN - Waiting type for immediate return
WAITING_TYPE_LOOP - Waiting type for busy waiting
waiting_s - waiting struct
waiting_initialize - initialize waiting structure
waiting_get_state - get waiting state
waiting_do - perform a given wait
waiting_inform - inform waiting task
waiting_copy - copy one waiting struct to another

Synopsis of function. macros and structures contained in waiting.h

3.15. endpoint.h

Table of Contents

usb_endpoint_register - Register an enpoint with the USB system.
usb_endpoint_deregister - De-register an endpoint with the USB system.

Synopsis of function. macros and structures contained in endpoint.h

3.16. slist.h

Table of Contents

slist_head - head structure for slist
slist_item - slist item structure
slist_inithead - initialise the head structure for an slist
slist_init - initialise an slist item structure
slist_add_front - add an item to the front of an slist
slist_get_front - Return the first item's data from the front of a list
slist_empty - Is an slist empty
slist_foreach - slist enumeration function.
slist_remove - remove item from an slist

Synopsis of function. macros and structures contained in slist.h