This directory contains a USB device report filter component. It filters the
device report coming from the USB driver by checking each device reported
against the given list of devices. Only approved devices are reported to a
consumer of the report coming from the filter component.


Configuration
~~~~~~~~~~~~~

A typical example configuration looks as follows:

!<config>
!  <client label="component_xyz"/>
!  <device vendor_id="0x13fe" product_id="0x5200"/>
!  <device vendor_id="0x148f" product_id="0x2573"/>
!  <device vendor_id="0x04f9" product_id="0x0051"/>
!  <device vendor_id="0x1b1c" product_id="0x1a09"/>
</config>

The component that may use the devices is identified by the 'client' node.
In addition to the 'vendor_id' and 'product_id' attribute a 'device' node
can contain a 'bus' and 'dev' attribute. If these attributes are present they
have a stronger significance than the 'vendor_id' and the 'product_id'.

Whenever the 'usb_report_filter' component receives a new USB device report
from the driver it will generate a new driver configuration that contains
a policy entry for each matching device. After the driver's configuration has
been updated, the filter component will generate a new USB device report that
only contains the devices the component is allowed to access.


Example
~~~~~~~

In the following example we will give a VirtualBox instance access to a
Corsair Voyager USB stick:

!<start name="usb_report_filter">
![...]
!  <config>
!    <client label="vbox"
!    <device vendor_id="0x1b1c" product_id="0x1a09"/>
!  </config>
!</start>

!<start name="report_rom">
!  <resource name="RAM" quantum="1M"/>
!  <provides> <service name="Report"/> <service name="ROM"/> </provides>
!  <config>
!    <policy label="usb_report_filter -> devices"        report="usb_drv -> devices"/>
!    <policy label="usb_report_filter -> usb_drv_config" report="usb_drv -> config"/>
!    <policy label="vbox -> usb_devices"                 report="usb_report_filter -> usb_devices"/>
!  </config>
!</start>

After the USB stick has been plugged in, the filter will generate the
following USB driver configuration:

!<start name="usb_drv">
![...]
!  <config uhci="yes" ehci="yes" xhci="yes">
!    <hid/>
!    <raw>
!      <report devices="yes"/>
!      <policy label="vbox -> usb-1-3" vendor_id="0x1b1c" product_id="0x1a09" bus="0x0001" device="0x0003"/>
!    </raw>
!  </config>
!</start>

After the driver has reloaded its configuration it will send a config report
that provokes the filter component to send the following USB device report to
VirtualBox:

!<devices>
!  <device label="usb-1-3" vendor_id="0x1b1c" product_id="0x1a09" bus="0x0001" device="0x0003"/>
!</device>

In return, VirtualBox will try to access the USB device. Since the configuration
of the USB driver contains a matching policy entry the access attempt will
succeed.
