facedancer.backends.base module

class facedancer.backends.base.FacedancerBackend(device: USBDevice = None, verbose: int = 0, quirks: List[str] = [])

Bases: object

__init__(device: USBDevice = None, verbose: int = 0, quirks: List[str] = [])

Initializes the backend.

Parameters:

• device – The device that will act as our Facedancer. (Optional)

• verbose – The verbosity level of the given application. (Optional)

• quirks – List of USB platform quirks. (Optional)

ack_status_stage(direction: USBDirection = USBDirection.OUT, endpoint_number: int = 0, blocking: bool = False)

Handles the status stage of a correctly completed control request, by priming the appropriate endpoint to handle the status phase.

Parameters:

• direction – Determines if we’re ACK’ing an IN or OUT vendor request. (This should match the direction of the DATA stage.)

• endpoint_number – The endpoint number on which the control request occurred.

• blocking – True if we should wait for the ACK to be fully issued before returning.

classmethod appropriate_for_environment(backend_name: str) → bool

Determines if the current environment seems appropriate for using this backend.

Parameters:

backend_name – Backend name being requested. (Optional)

clear_halt(endpoint_number: int, direction: USBDirection)

Clears a halt condition on the provided non-control endpoint.

Parameters:

• endpoint_number – The endpoint number

• direction – The endpoint direction; or OUT if not provided.

configured(configuration: USBConfiguration)

Callback that’s issued when a USBDevice is configured, e.g. by the SET_CONFIGURATION request. Allows us to apply the new configuration.

Parameters:

configuration – The USBConfiguration object applied by the SET_CONFIG request.

connect(usb_device: USBDevice, max_packet_size_ep0: int = 64, device_speed: DeviceSpeed = DeviceSpeed.FULL)

Prepares backend to connect to the target host and emulate a given device.

Parameters:

• usb_device – The USBDevice object that represents the emulated device.

• max_packet_size_ep0 – Max packet size for control endpoint.

• device_speed – Requested usb speed for the Facedancer board.

disconnect()

Disconnects Facedancer from the target host.

get_version()

Returns information about the active Facedancer version.

read_from_endpoint(endpoint_number: int) → bytes

Reads a block of data from the given endpoint.

Parameters:

endpoint_number – The number of the OUT endpoint on which data is to be rx’d.

reset()

Triggers the Facedancer to handle its side of a bus reset.

send_on_control_endpoint(endpoint_number: int, in_request: USBControlRequest, data: bytes, blocking: bool = True)

Sends a collection of USB data in response to a IN control request by the host.

Parameters:

• endpoint_number – The number of the IN endpoint on which data should be sent.

• in_request – The control request being responded to.

• data – The data to be sent.

• blocking – If true, this function should wait for the transfer to complete.

send_on_endpoint(endpoint_number: int, data: bytes, blocking: bool = True)

Sends a collection of USB data on a given endpoint.

Parameters:

• endpoint_number – The number of the IN endpoint on which data should be sent.

• data – The data to be sent.

• blocking – If true, this function should wait for the transfer to complete.

service_irqs()

Core routine of the Facedancer execution/event loop. Continuously monitors the Facedancer’s execution status, and reacts as events occur.

set_address(address: int, defer: bool = False)

Sets the device address of the Facedancer. Usually only used during initial configuration.

Parameters:

• address – The address the Facedancer should assume.

• defer – True iff the set_address request should wait for an active transaction to finish.

stall_endpoint(endpoint_number: int, direction: USBDirection = USBDirection.OUT)

Stalls the provided endpoint, as defined in the USB spec.

Parameters:

endpoint_number – The number of the endpoint to be stalled.

validate_configuration(configuration: USBConfiguration)

Check if this backend is able to support this configuration. Raises an exception if it is not.

Parameters:

configuration – The configuration to validate.