~launchpad-pqm/launchpad/devel

Hardware Database Device Tables

===============================

These tables represent devices and complete systems in the database. They

allow look up of devices by their bus IDs and by their human readable

vendor and product names. They also link devices to drivers.

HWVendorName

------------

HWVendorName is a simple list of vendor names. A new entry is created by

IHWVendorNameSet.create().

    >>> from lp.hardwaredb.interfaces.hwdb import IHWVendorNameSet

    >>> vendor_name_set = getUtility(IHWVendorNameSet)

    >>> intel_name = vendor_name_set.create(name='Intel')

    >>> print intel_name.name

    Intel

Each name in the table must be unique. The attempt to create a second

row with the same name raises an IntegrityError error.

    >>> from storm.store import Store

    >>> store = Store.of(intel_name)

    >>> from canonical.testing.layers import LaunchpadZopelessLayer

    >>> LaunchpadZopelessLayer.txn.commit()

    >>> vendor_name_set.create('Intel')

    <HWVendorName ...

    >>> store.flush()

    Traceback (most recent call last):

    ...

    IntegrityError: duplicate key... violates unique

    constraint "hwvendorname__lc_vendor_name__idx"

    <BLANKLINE>

    >>> LaunchpadZopelessLayer.txn.abort()

The database checks the uniqueness of the lower-case name, hence we

cannot insert another name like "INTEL" or "intel".

    >>> vendor_name_set.create('INTEL')

    <HWVendorName ...

    >>> store.flush()

    Traceback (most recent call last):

    ...

    IntegrityError: duplicate key... violates unique

    constraint "hwvendorname__lc_vendor_name__idx"

    <BLANKLINE>

    >>> LaunchpadZopelessLayer.txn.abort()

    >>> vendor_name_set.create('intel')

    <HWVendorName ...

    >>> store.flush()

    Traceback (most recent call last):

    ...

    IntegrityError: duplicate key... violates unique

    constraint "hwvendorname__lc_vendor_name__idx"

    <BLANKLINE>

    >>> LaunchpadZopelessLayer.txn.abort()

The lower-case uniqueness constraint works for latin characters with

diacritical marks too...

    >>> a_umlaut_upper = u'\N{LATIN CAPITAL LETTER A WITH DIAERESIS}'

    >>> a_umlaut_lower = u'\N{LATIN SMALL LETTER A WITH DIAERESIS}'

    >>> a_umlaut_name = vendor_name_set.create(name=a_umlaut_upper)

    >>> LaunchpadZopelessLayer.txn.commit()

    >>> print repr(a_umlaut_name.name)

    u'\xc4'

    >>> vendor_name_set.create(name=a_umlaut_lower)

    <HWVendorName ...

    >>> store.flush()

    Traceback (most recent call last):

    ...

    IntegrityError: duplicate key... violates unique

    constraint "hwvendorname__lc_vendor_name__idx"

    <BLANKLINE>

    >>> LaunchpadZopelessLayer.txn.abort()

...as well as for Cyrillic characters...

    >>> cyrillic_de_upper = u'\N{CYRILLIC CAPITAL LETTER DE}'

    >>> cyrillic_de_lower = u'\N{CYRILLIC SMALL LETTER DE}'

    >>> cyrillic_de_name = vendor_name_set.create(name=cyrillic_de_upper)

    >>> print repr(cyrillic_de_name.name)

    u'\u0414'

    >>> vendor_name_set.create(name=cyrillic_de_lower)

    <HWVendorName ...

    >>> store.flush()

    Traceback (most recent call last):

    ...

    IntegrityError: duplicate key... violates unique

    constraint "hwvendorname__lc_vendor_name__idx"

    <BLANKLINE>

    >>> LaunchpadZopelessLayer.txn.abort()

...and Greek characters.

    >>> alpha_upper = u'\N{GREEK CAPITAL LETTER ALPHA}'

    >>> alpha_lower = u'\N{GREEK SMALL LETTER ALPHA}'

    >>> cyrillic_de_name = vendor_name_set.create(name=alpha_upper)

    >>> print repr(cyrillic_de_name.name)

    u'\u0391'

    >>> vendor_name_set.create(name=alpha_lower)

    <HWVendorName ...

    >>> store.flush()

    Traceback (most recent call last):

    ...

    IntegrityError: duplicate key... violates unique

    constraint "hwvendorname__lc_vendor_name__idx"

    <BLANKLINE>

    >>> LaunchpadZopelessLayer.txn.abort()

Existing IHWVendorName records are retrieved by IHWVendorName.getByName().

    >>> intel_name = vendor_name_set.getByName('Intel')

    >>> print intel_name.name

    Intel

The capitalization of the name does not metter.

    >>> intel_name = vendor_name_set.getByName('INTEL')

    >>> print intel_name.name

    Intel

    >>> intel_name = vendor_name_set.getByName('intel')

    >>> print intel_name.name

    Intel

    >>> umlaut_name = vendor_name_set.getByName(

    ...     u'\N{LATIN CAPITAL LETTER A WITH DIAERESIS}')

    >>> print repr(umlaut_name.name)

    u'\xc4'

    >>> umlaut_name = vendor_name_set.getByName(

    ...     u'\N{LATIN SMALL LETTER A WITH DIAERESIS}')

    >>> print repr(umlaut_name.name)

    u'\xc4'

If no record matching the given name exists, IHWVendorName.getByName()

returns None.

    >>> print vendor_name_set.getByName('Babbage Computers')

    None

HWVendorID

----------

HWVendorID associates a bus, as enumerated by HWBus, with a bus-specific

vendor ID and a vendor name. We store the IDs as a string, because not all

all busses use numeric IDs. Numbers are represented as strings with

hexadecimal digits, prepended by '0x'.

    >>> from lp.hardwaredb.interfaces.hwdb import HWBus, IHWVendorIDSet

    >>> vendor_id_set = getUtility(IHWVendorIDSet)

    >>> intel_pci_id = vendor_id_set.create(bus=HWBus.PCI,

    ...                                     vendor_id='0x8086',

    ...                                     vendor_name=intel_name)

    >>> print intel_pci_id.bus.title, intel_pci_id.vendor_id_for_bus

    PCI 0x8086

    >>> print intel_pci_id.vendor_name.name

    Intel

The tuple (bus, vendor id, vendor name) must be unique.

    >>> LaunchpadZopelessLayer.txn.commit()

    >>> vendor_id_set.create(bus=HWBus.PCI,

    ...                      vendor_id='0x8086',

    ...                      vendor_name=intel_name)

    <HWVendorID ...

    >>> store.flush()

    Traceback (most recent call last):

    ...

    IntegrityError: duplicate key... violates unique

    constraint "hwvendorid__bus_vendor_id__vendor_name__key"

    <BLANKLINE>

    >>> LaunchpadZopelessLayer.txn.abort()

We store the (bus specific) vendor ID as a string, but several busses

have stricter constraints for their vendor ID. The PCI and USB busses use

16 bit integers, the IEEE1394 bus uses 24 bit integers, the SCSI bus

uses ASCII strings with exactly 8 characters. The constructor of

HWVendorID ensures that the vendor IDs match the bus-specific format.

USB, PCI and PCCard IDs are represented as strings with a four-digit

hexadecimal number, prefixed by '0x'; the digits a..f must be lower

cases characters. Other ID values raise a ParameterError.

The characters a..f are accepted as digits.

    >>> another_pci_vendor_id = vendor_id_set.create(bus=HWBus.PCI,

    ...                                              vendor_id='0x10ae',

    ...                                              vendor_name=intel_name)

    >>> print another_pci_vendor_id.bus.title

    PCI

    >>> print another_pci_vendor_id.vendor_id_for_bus

    0x10ae

    >>> print another_pci_vendor_id.vendor_name.name

    Intel

    >>> another_pci_vendor_id = vendor_id_set.create(bus=HWBus.PCCARD,

    ...                                              vendor_id='0x10ae',

    ...                                              vendor_name=intel_name)

    >>> print another_pci_vendor_id.bus.title

    PC Card (32 bit)

    >>> print another_pci_vendor_id.vendor_id_for_bus

    0x10ae

    >>> print another_pci_vendor_id.vendor_name.name

    Intel

    >>> another_usb_vendor_id = vendor_id_set.create(bus=HWBus.USB,

    ...                                              vendor_id='0x10ae',

    ...                                              vendor_name=intel_name)

    >>> print another_usb_vendor_id.bus.title

    USB

    >>> print another_usb_vendor_id.vendor_id_for_bus

    0x10ae

    >>> print another_usb_vendor_id.vendor_name.name

    Intel

A..F is rejected.

    >>> vendor_id_set.create(bus=HWBus.PCI,

    ...                      vendor_id='0x10AE',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0x10AE' is not a valid vendor ID for PCI

    >>> from storm.tracer import debug; debug(True)

    >>> store.flush()

    >>> debug(False)

    >>> vendor_id_set.create(bus=HWBus.PCCARD,

    ...                      vendor_id='0x10AE',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0x10AE' is not a valid vendor ID for PC Card (32 bit)

    >>> vendor_id_set.create(bus=HWBus.USB,

    ...                      vendor_id='0x10AE',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0x10AE' is not a valid vendor ID for USB

The ID must have the prefix "0x".

    >>> vendor_id_set.create(bus=HWBus.PCI,

    ...                      vendor_id='8086',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '8086' is not a valid vendor ID for PCI

    >>> vendor_id_set.create(bus=HWBus.PCCARD,

    ...                      vendor_id='8086',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '8086' is not a valid vendor ID for PC Card (32 bit)

    >>> vendor_id_set.create(bus=HWBus.USB,

    ...                      vendor_id='8086',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '8086' is not a valid vendor ID for USB

The number must have four digits.

    >>> vendor_id_set.create(bus=HWBus.PCI,

    ...                      vendor_id='0x123',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0x123' is not a valid vendor ID for PCI

    >>> vendor_id_set.create(bus=HWBus.PCCARD,

    ...                      vendor_id='0x123',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0x123' is not a valid vendor ID for PC Card (32 bit)

    >>> vendor_id_set.create(bus=HWBus.USB,

    ...                      vendor_id='0x123',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0x123' is not a valid vendor ID for USB

    >>> vendor_id_set.create(bus=HWBus.PCI,

    ...                      vendor_id='0x12345',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0x12345' is not a valid vendor ID for PCI

    >>> vendor_id_set.create(bus=HWBus.PCCARD,

    ...                      vendor_id='0x12345',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0x12345' is not a valid vendor ID for PC Card (32 bit)

    >>> vendor_id_set.create(bus=HWBus.USB,

    ...                      vendor_id='0x12345',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0x12345' is not a valid vendor ID for USB

Only hex digits are allowed.

    >>> vendor_id_set.create(bus=HWBus.PCI,

    ...                      vendor_id='0xblah',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0xblah' is not a valid vendor ID for PCI

    >>> vendor_id_set.create(bus=HWBus.PCCARD,

    ...                      vendor_id='0xblah',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0xblah' is not a valid vendor ID for PC Card (32 bit)

    >>> vendor_id_set.create(bus=HWBus.USB,

    ...                      vendor_id='0xblah',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0xblah' is not a valid vendor ID for USB

IEEE1394 IDs are represented as strings with a six-digit hexadecimal

number, prefixed by '0x'; the digits a..f must be lower cases characters.

Other ID values raise a value error.

    >>> vendor_id_1394 = vendor_id_set.create(bus=HWBus.IEEE1394,

    ...                                       vendor_id='0x0010e0',

    ...                                       vendor_name=intel_name)

    >>> print vendor_id_1394.bus.title

    IEEE1394

    >>> print vendor_id_1394.vendor_id_for_bus

    0x0010e0

    >>> print vendor_id_1394.vendor_name.name

    Intel

A..F is rejected.

    >>> vendor_id_set.create(bus=HWBus.IEEE1394,

    ...                      vendor_id='0x0010E0',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0x0010E0' is not a valid vendor ID for IEEE1394

The ID must have the prefix "0x".

    >>> vendor_id_set.create(bus=HWBus.IEEE1394,

    ...                      vendor_id='0010E0',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0010E0' is not a valid vendor ID for IEEE1394

The number must have six digits.

    >>> vendor_id_set.create(bus=HWBus.IEEE1394,

    ...                      vendor_id='0x12345',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0x12345' is not a valid vendor ID for IEEE1394

    >>> vendor_id_set.create(bus=HWBus.IEEE1394,

    ...                      vendor_id='0x1234567',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0x1234567' is not a valid vendor ID for IEEE1394

Only hex digits are allowed.

    >>> vendor_id_set.create(bus=HWBus.IEEE1394,

    ...                      vendor_id='0xfoobar',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '0xfoobar' is not a valid vendor ID for IEEE1394

SCSI vendor IDs are ASCII strings with exactly eight characters.

    >>> intel_scsi_id = vendor_id_set.create(bus=HWBus.SCSI,

    ...                                      vendor_id='INTEL   ',

    ...                                      vendor_name=intel_name)

    >>> print intel_scsi_id.bus.title

    SCSI

    >>> intel_scsi_id.vendor_id_for_bus

    u'INTEL   '

    >>> print intel_scsi_id.vendor_name.name

    Intel

Strings with less than eight characters are not allowed as SCSI vendor IDs...

    >>> vendor_id_set.create(bus=HWBus.SCSI,

    ...                      vendor_id='1234567',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '1234567' is not a valid vendor ID for SCSI

...as well as strings with more than eight characters.

    >>> vendor_id_set.create(bus=HWBus.SCSI,

    ...                      vendor_id='123456789',

    ...                      vendor_name=intel_name)

    Traceback (most recent call last):

    ...

    ParameterError: '123456789' is not a valid vendor ID for SCSI

HWVendorIDSet.getByBusAndVendorID() is used to look up a HWVendorID record.

    >>> vendor_id = vendor_id_set.getByBusAndVendorID(bus=HWBus.PCI,

    ...                                               vendor_id='0x8086')

    >>> print vendor_id.bus.title

    PCI

    >>> print vendor_id.vendor_name.name

    Intel

If no record exists for the given bus and vendor ID,

HWVendorIDSet.getByBusAndVendorID() returns None.

    >>> vendor_id = vendor_id_set.getByBusAndVendorID(bus=HWBus.PCI,

    ...                                               vendor_id='0xffff')

    >>> print vendor_id

    None

HWVendorIDSet.getByBusAndVendorID() performs the same validity tests of

the vendor ID as HWVendorSet.create(): The vendor ID passed to

HWVendorIDSet.getByBusAndVendorID() must be a valid ID for the given bus.

    >>> vendor_id_set.getByBusAndVendorID(bus=HWBus.PCI, vendor_id='8086')

    Traceback (most recent call last):

    ...

    ParameterError: '8086' is not a valid vendor ID for PCI

HWVendorIDSet.get() returns the HWVendorID record with the given ID...

    >>> vendor_id = vendor_id_set.get(1)

    >>> print vendor_id.bus.name, vendor_id.vendor_id_for_bus

    SYSTEM MSI

...or None, if no such record exists.

    >>> print vendor_id_set.get(1000000)

    None

HWVendorIDSet.idsForBus() returns all known HWVendorIDs for a given bus.

    >>> for vendor_id in vendor_id_set.idsForBus(HWBus.PCI):

    ...     print vendor_id.bus.name, vendor_id.vendor_id_for_bus

    PCI 0x10ae

    PCI 0x10de

    PCI 0x8086

HWDevice

--------

A HWDevice instance stores core data about a hardware device: The bus

it can connect to, the vendor ID, the product ID, the human readable

product name, variant (see below), and the number of submissions with

a device.

Aside from "real" devices like keyboards, mice, hard disks, PCI cards,

i.e., "thingies" one can connect to and remove from a computer, we also

store data about "systems" (computers) and "components" in the HWDevice

table. A component is a part that is "permanently built" into a system,

like a hard disk controller that is soldered onto the main board.

A new device record is created by IHWDeviceSet.create.

    >>> from lp.hardwaredb.interfaces.hwdb import IHWDeviceSet

    >>> device_set = getUtility(IHWDeviceSet)

    >>> product_name='82801GBM/GHM (ICH7 Family) USB2 EHCI Controller'

    >>> usb_controller = device_set.create(bus=HWBus.PCI,

    ...                                    vendor_id='0x8086',

    ...                                    product_id='0x27cc',

    ...                                    product_name=product_name)

Bus and vendor ID are not directly stored as HWDevice attributes; we can

access them, as well as the vendor name, either via the attribute

bus_vendor, which references HWVendorID...

    >>> print usb_controller.bus_vendor.bus.title

    PCI

    >>> print usb_controller.bus_vendor.vendor_id_for_bus

    0x8086

    >>> print usb_controller.bus_vendor.vendor_name.name

    Intel

...or via the (read-only) HWDevice properties bus, vendor_id, vendor_name.

    >>> print usb_controller.bus.title

    PCI

    >>> print usb_controller.vendor_id

    0x8086

    >>> print usb_controller.vendor_name

    Intel

Other attributes stored in HWDevice are the product ID, the product name,

the product variant and submissions. submissions is a counter of the

number of submissions with this device.

    >>> print usb_controller.bus_product_id

    0x27cc

    >>> print usb_controller.name

    82801GBM/GHM (ICH7 Family) USB2 EHCI Controller

    >>> print usb_controller.variant

    None

    >>> print usb_controller.submissions

    0

Like vendor IDs, product IDs of some busses have certain constraints.

USB and PCI product IDs are 16 bit integers; SCSI IDs are strings

with 16 characters. (Note that the IEEE1394 does _not_ define a product

ID.)

USB, PCI and PCCard IDs are represented as strings with a four-digit

hexadecimal number, prefixed by '0x'; the digits a..f must be lower

cases characters. Other ID values raise a ParameterError.

    >>> another_pci_product = device_set.create(bus=HWBus.PCI,

    ...                                         vendor_id='0x8086',

    ...                                         product_id='0xabcd',

    ...                                         product_name='A PCI card')

    >>> print another_pci_product.bus_product_id

    0xabcd

    >>> another_pci_product = device_set.create(bus=HWBus.PCCARD,

    ...                                         vendor_id='0x8086',

    ...                                         product_id='0xabcd',

    ...                                         product_name='A PC Card')

    >>> print another_pci_product.bus_product_id

    0xabcd

    >>> another_usb_product = device_set.create(bus=HWBus.USB,

    ...                                         vendor_id='0x8086',

    ...                                         product_id='0xabcd',

    ...                                         product_name='A USB device')

    >>> print another_usb_product.bus_product_id

    0xabcd

A..F is rejected.

    >>> device_set.create(bus=HWBus.PCI,

    ...                   vendor_id='0x8086',

    ...                   product_id='0xABCD',

    ...                   product_name='A PCI card')

    Traceback (most recent call last):

    ...

    ParameterError: '0xABCD' is not a valid product ID for PCI

    >>> device_set.create(bus=HWBus.PCCARD,

    ...                   vendor_id='0x8086',

    ...                   product_id='0xABCD',

    ...                   product_name='A PC Card')

    Traceback (most recent call last):

    ...

    ParameterError: '0xABCD' is not a valid product ID for PC Card (32 bit)

    >>> device_set.create(bus=HWBus.USB,

    ...                   vendor_id='0x8086',

    ...                   product_id='0xABCD',

    ...                   product_name='A USB device')

    Traceback (most recent call last):

    ...

    ParameterError: '0xABCD' is not a valid product ID for USB

The ID must have the prefix "0x".

    >>> device_set.create(bus=HWBus.PCI,

    ...                   vendor_id='0x8086',

    ...                   product_id='1234',

    ...                   product_name='A PCI card')

    Traceback (most recent call last):

    ...

    ParameterError: '1234' is not a valid product ID for PCI

    >>> device_set.create(bus=HWBus.PCCARD,

    ...                   vendor_id='0x8086',

    ...                   product_id='1234',

    ...                   product_name='A PC Card')

    Traceback (most recent call last):

    ...

    ParameterError: '1234' is not a valid product ID for PC Card (32 bit)

    >>> device_set.create(bus=HWBus.USB,

    ...                   vendor_id='0x8086',

    ...                   product_id='1234',

    ...                   product_name='A USB device')

    Traceback (most recent call last):

    ...

    ParameterError: '1234' is not a valid product ID for USB

The number must have four digits.

    >>> device_set.create(bus=HWBus.PCI,

    ...                   vendor_id='0x8086',

    ...                   product_id='0x123',

    ...                   product_name='A PCI card')

    Traceback (most recent call last):

    ...

    ParameterError: '0x123' is not a valid product ID for PCI

    >>> device_set.create(bus=HWBus.PCCARD,

    ...                   vendor_id='0x8086',

    ...                   product_id='0x123',

    ...                   product_name='A PC Card')

    Traceback (most recent call last):

    ...

    ParameterError: '0x123' is not a valid product ID for PC Card (32 bit)

    >>> device_set.create(bus=HWBus.USB,

    ...                   vendor_id='0x8086',

    ...                   product_id='0x123',

    ...                   product_name='A USB device')

    Traceback (most recent call last):

    ...

    ParameterError: '0x123' is not a valid product ID for USB

    >>> device_set.create(bus=HWBus.PCI,

    ...                   vendor_id='0x8086',

    ...                   product_id='0x12345',

    ...                   product_name='A PCI card')

    Traceback (most recent call last):

    ...

    ParameterError: '0x12345' is not a valid product ID for PCI

    >>> device_set.create(bus=HWBus.PCCARD,

    ...                   vendor_id='0x8086',

    ...                   product_id='0x12345',

    ...                   product_name='A PC Card')

    Traceback (most recent call last):

    ...

    ParameterError: '0x12345' is not a valid product ID for PC Card (32 bit)

    >>> device_set.create(bus=HWBus.USB,

    ...                   vendor_id='0x8086',

    ...                   product_id='0x12345',

    ...                   product_name='A USB device')

    Traceback (most recent call last):

    ...

    ParameterError: '0x12345' is not a valid product ID for USB

Only hex digits are allowed.

    >>> device_set.create(bus=HWBus.PCI,

    ...                   vendor_id='0x8086',

    ...                   product_id='0xblah',

    ...                   product_name='A PCI card')

    Traceback (most recent call last):

    ...

    ParameterError: '0xblah' is not a valid product ID for PCI

    >>> device_set.create(bus=HWBus.PCCARD,

    ...                   vendor_id='0x8086',

    ...                   product_id='0xblah',

    ...                   product_name='A PC Card')

    Traceback (most recent call last):

    ...

    ParameterError: '0xblah' is not a valid product ID for PC Card (32 bit)

    >>> device_set.create(bus=HWBus.USB,

    ...                   vendor_id='0x8086',

    ...                   product_id='0xblah',

    ...                   product_name='A USB device')

    Traceback (most recent call last):

    ...

    ParameterError: '0xblah' is not a valid product ID for USB

SCSI product IDs are ASCII strings with 16 characters.

    >>> scsi_device = device_set.create(bus=HWBus.SCSI,

    ...                                 vendor_id='INTEL   ',

    ...                                 product_id='12345678901234  ',

    ...                                 product_name='A SCSI device')

    >>> scsi_device.bus_product_id

    u'12345678901234  '

Strings with less than 16 characters are not allowed as SCSI product IDs...

    >>> device_set.create(bus=HWBus.SCSI,

    ...                   vendor_id='INTEL   ',

    ...                   product_id='123456789012345',

    ...                   product_name='A SCSI device')

    Traceback (most recent call last):

    ...

    ParameterError: '123456789012345' is not a valid product ID for SCSI

...as well as strings with more than 16 characters.

    >>> device_set.create(bus=HWBus.SCSI,

    ...                   vendor_id='INTEL   ',

    ...                   product_id='12345678901234567',

    ...                   product_name='A SCSI device')

    Traceback (most recent call last):

    ...

    ParameterError: '12345678901234567' is not a valid product ID for SCSI

Unknown Vendor IDs

..................

If IHWDevice.create is called with a vendor ID that for which there

is no IHWVendorID record, the latter is automatically created. Since

we do not pass the vendor name to IHWDevice.create, this method

cannot set the real vendor name for the new IHWVendorID record.

Instead, the vendor name is set to "Unknown".

Reason: IHWDevice will be populated with data collected by the

HWDB client, which gets most of the device data from HAL, and HAL

quite often does not know the vendor name. Hence we will populate

and update IHWVendorID from sources like

http://www.linux-usb.org/usb.ids

http://www.pcidatabase.com/reports.php?type=csv

http://standards.ieee.org/regauth/oui/oui.txt

    >>> new_vendor_device = device_set.create(bus=HWBus.PCI,

    ...                                       vendor_id='0x4321',

    ...                                       product_id='0x8765',

    ...                                       product_name='mind sensor')

    >>> print new_vendor_device.bus_vendor.vendor_name.name

    Unknown

Device Variants

...............

While most devices can be uniquely identified by their vendor and product

IDs, there are some cases, where different devices have identical IDs:

(a) The IDs are assigned to a USB chipset that is used in different

    devices.

(b) A vendor may inadvertently "recycle" a product ID

(c) A chip manufacturer who does not have its own vendor ID may "forge"

    the vendor ID.

A real world example of the first case is the scanner chipset from

Plustek with the USB ID 0x07b3/0x0017. This chipset is used in devices

that differ for example in the maximum scan window size.

We do not necessarily know in advance that there are different devices

with identical IDs, so we may have a HWDevice record without the variant

attribute set.

    >>> plustek_name = vendor_name_set.create('Plustek')

    >>> plustek_usb_id = vendor_id_set.create(bus=HWBus.USB,

    ...                                       vendor_id='0x07b3',

    ...                                       vendor_name=plustek_name)

    >>> some_plustek_scanner = device_set.create(bus=HWBus.USB,

    ...                                          vendor_id='0x07b3',

    ...                                          product_id='0x0017',

    ...                                          product_name='some scanner')

    >>> print some_plustek_scanner.bus_vendor.vendor_id_for_bus

    0x07b3

    >>> print some_plustek_scanner.bus_vendor.vendor_name.name

    Plustek

    >>> print some_plustek_scanner.name

    some scanner

    >>> print some_plustek_scanner.variant

    None

Once we know that (bus, vendor ID, product ID) does not uniquely

identify a device, we can disambiguate these devices by creating

IHWDevice records, where the attribute variant is, for example, set

to the product name.

    >>> optic_pro_ut12 = device_set.create(bus=HWBus.USB,

    ...                                    vendor_id='0x07b3',

    ...                                    product_id='0x0017',

    ...                                    variant='OpticPro UT12',

    ...                                    product_name='OpticPro UT12')

    >>> optic_pro_ut16 = device_set.create(bus=HWBus.USB,

    ...                                    vendor_id='0x07b3',

    ...                                    product_id='0x0017',

    ...                                    variant='OpticPro UT16',

    ...                                    product_name='OpticPro UT16')

For systems, we use HWBus.SYSTEM as the "bus name"; the HAL property

system.vendor is stored as the vendor ID and vendor name, and the HAL

property system.product is stored as the product ID and the product

name.

    >>> hal_vendor_name = 'Tonka'

    >>> hal_product_name = 'Tuffbook 2600'

    >>> tonka_name = vendor_name_set.create(name=hal_vendor_name)

    >>> tonka_system_id = vendor_id_set.create(bus=HWBus.SYSTEM,

    ...                                        vendor_id=hal_vendor_name,

    ...                                        vendor_name=tonka_name)

    >>> tuffbook_2600 = device_set.create(bus=HWBus.SYSTEM,

    ...                                   vendor_id=hal_vendor_name,

    ...                                   product_id=hal_product_name,

    ...                                   product_name=hal_product_name)

    >>> print tuffbook_2600.bus_vendor.bus.title

    System

    >>> print tuffbook_2600.bus_vendor.vendor_id_for_bus

    Tonka

    >>> print tuffbook_2600.bus_vendor.vendor_name.name

    Tonka

    >>> print tuffbook_2600.bus_product_id

    Tuffbook 2600

    >>> print tuffbook_2600.name

    Tuffbook 2600

The tuple (bus_vendor, bus_product_id, variant) must be unique.

The attempt to create two rows with the same data raises a

IntegrityError error.

    >>> LaunchpadZopelessLayer.txn.commit()

    >>> another_scanner = device_set.create(bus=HWBus.USB,

    ...                                     vendor_id='0x07b3',

    ...                                     product_id='0x0017',

    ...                                     product_name='some scanner')

    >>> store.flush()

    Traceback (most recent call last):

    ...

    IntegrityError: duplicate key... violates unique

    constraint "hwdevice__bus_vendor_id__bus_product_id__key"

    <BLANKLINE>

    >>> LaunchpadZopelessLayer.txn.abort()

    >>> another_scanner = device_set.create(bus=HWBus.USB,

    ...                                     vendor_id='0x07b3',

    ...                                     product_id='0x0017',

    ...                                     variant='OpticPro UT16',

    ...                                     product_name='OpticPro UT16')

    >>> store.flush()

    Traceback (most recent call last):

    ...

    IntegrityError: duplicate key... violates unique

    constraint "hwdevice__bus_vendor_id__bus_product_id__variant__key"

    <BLANKLINE>

    >>> LaunchpadZopelessLayer.txn.abort()

Retrieving HWDevice records

...........................

Existing HWDevice records can be retrieved by calling

HWDeviceSet.getByDeviceID()

    >>> device = device_set.getByDeviceID(HWBus.USB, '0x07b3', '0x0017')

    >>> print device.bus_vendor.bus.title

    USB

    >>> print device.bus_vendor.vendor_id_for_bus

    0x07b3

    >>> print device.bus_product_id

    0x0017

    >>> print device.name

    some scanner

The call to HWDeviceSet.getByDeviceID() above did not specify a product

variant. In such a case, the record having variant==None is returned

    >>> print device.variant

    None

If a variant name is given, we get the HWDevice record of that variant.

    >>> device = device_set.getByDeviceID(HWBus.USB, '0x07b3', '0x0017',

    ...                                   'OpticPro UT16')

    >>> print device.bus_vendor.bus.title

    USB

    >>> print device.bus_vendor.vendor_id_for_bus

    0x07b3

    >>> print device.bus_product_id

    0x0017

    >>> print device.name

    OpticPro UT16

    >>> print device.variant

    OpticPro UT16

If the given parameters do not match any existing record, None is

returned.

    >>> print device_set.getByDeviceID(HWBus.PCI, '0x07b3', '0x0017',

    ...                                'OpticPro UT16')

    None

    >>> print device_set.getByDeviceID(HWBus.USB, '0xffff', '0x0017',

    ...                                'OpticPro UT16')

    None

    >>> print device_set.getByDeviceID(HWBus.PCI, '0x07b3', '0xffff',

    ...                                'OpticPro UT16')

    None

    >>> print device_set.getByDeviceID(HWBus.PCI, '0x07b3', '0x0017',

    ...                                'nonsense')

    None

The parameters vendor_id and product_id must be valid IDs for the

given bus.

    >>> device_set.getByDeviceID(HWBus.USB, '07b3', '0x0017')

    Traceback (most recent call last):

    ...

    ParameterError: '07b3' is not a valid vendor ID for USB

    >>> device_set.getByDeviceID(HWBus.USB, '0x07b3', '0017')

    Traceback (most recent call last):

    ...

    ParameterError: '0017' is not a valid product ID for USB

HWDeviceSet.getOrCreate() returns an existing record matching the given

parameters or creates a new one, if no existing record matches.

    >>> device2 = device_set.getOrCreate(bus=HWBus.USB,

    ...                                  vendor_id='0x07b3',

    ...                                  product_id='0x0017',

    ...                                  product_name='OpticPro UT16',

    ...                                  variant='OpticPro UT16')

    >>> print device2.bus_vendor.bus.title

    USB

    >>> print device2.bus_vendor.vendor_id_for_bus

    0x07b3

    >>> print device2.bus_product_id

    0x0017

    >>> print device2.name

    OpticPro UT16

    >>> print device2.variant

    OpticPro UT16

    >>> print device2.id == device.id

    True

    >>> device3 = device_set.getByDeviceID(bus=HWBus.USB,

    ...                                    vendor_id='0x07b3',

    ...                                    product_id='0x0017',

    ...                                    variant='Some other scanner')

    >>> print device3

    None

    >>> device3 = device_set.getOrCreate(bus=HWBus.USB,

    ...                                  vendor_id='0x07b3',

    ...                                  product_id='0x0017',

    ...                                  product_name='Some other scanner',

    ...                                  variant='Some other scanner')

    >>> print device3.bus_vendor.bus.title

    USB

    >>> print device3.bus_vendor.vendor_id_for_bus

    0x07b3

    >>> print device3.bus_product_id

    0x0017

    >>> print device3.name

    Some other scanner

    >>> print device3.variant

    Some other scanner

    >>> device4 = device_set.getOrCreate(bus=HWBus.USB,

    ...                                  vendor_id='0x07b3',

    ...                                  product_id='0x0015',

    ...                                  product_name='OpticPro U24')

    >>> print device4.bus_vendor.bus.title

    USB

    >>> print device4.bus_vendor.vendor_id_for_bus

    0x07b3

    >>> print device4.bus_product_id

    0x0015

    >>> print device4.name

    OpticPro U24

    >>> print device4.variant

    None

HWDeviceSet.getByID() returns a HWDevice record with the given database ID.

    >>> device = device_set.getByID(1)

    >>> print device.id

    1

    >>> print device.vendor_id

    MSI

    >>> print device.bus_product_id

    MS-7369

HWDeviceSet.getByID() returns None if no record with the passed ID exists.

    >>> device = device_set.getByID(1000000)

    >>> print device

    None

HWDeviceSet.search() returns all devices with a given bus and vendor ID.

    >>> devices = device_set.search(bus=HWBus.USB, vendor_id='0x07b3')

    >>> for device in devices:

    ...     print device.bus.title, device.vendor_id, device.bus_product_id,

    ...     print device.variant

    USB 0x07b3 0x0017 None

    USB 0x07b3 0x0017 OpticPro UT12

    USB 0x07b3 0x0017 OpticPro UT16

    USB 0x07b3 0x0017 Some other scanner

    USB 0x07b3 0x0015 None

Searching can be limited to a single product ID.

    >>> devices = device_set.search(

    ...     bus=HWBus.USB, vendor_id='0x07b3', product_id='0x0017')

    >>> for device in devices:

    ...     print device.bus.title, device.vendor_id, device.bus_product_id,

    ...     print device.variant

    USB 0x07b3 0x0017 None

    USB 0x07b3 0x0017 OpticPro UT12

    USB 0x07b3 0x0017 OpticPro UT16

    USB 0x07b3 0x0017 Some other scanner

HWDeviceSet.search() raises a ParameterError for vendor or product IDs

that are not valid for the given bus.

    >>> devices = device_set.search(

    ...     bus=HWBus.USB, vendor_id='invalid', product_id='0x0017')

    Traceback (most recent call last):

    ...

    ParameterError: 'invalid' is not a valid vendor ID for USB

    >>> devices = device_set.search(

    ...     bus=HWBus.USB, vendor_id='0x07b3', product_id='nonsense')

    Traceback (most recent call last):

    ...

    ParameterError: 'nonsense' is not a valid product ID for USB

HWDevice.getSubmissions() returns submissions which contain this device.

We'll switch the DB user from hwdb-submission-processor to the ordinary

Launchpad user, because the former has no access to the table

distribution, which we want to access in this test.

    >>> LaunchpadZopelessLayer.switchDbUser('launchpad')

    >>> sata_controller = device_set.getByDeviceID(

    ...     bus=HWBus.PCI, vendor_id='0x10de', product_id='0x045d')

    >>> for submission in sata_controller.getSubmissions():

    ...     print submission.submission_key

    sample-submission

We can limit the results to a specific driver. (See below for details about

HWDriver.)

    >>> from lp.hardwaredb.interfaces.hwdb import IHWDriverSet

    >>> ahci_driver = getUtility(IHWDriverSet).getByPackageAndName(

    ...     'linux-image-2.6.24-19-generic', 'ahci')

    >>> for submission in sata_controller.getSubmissions(

    ...     driver=ahci_driver):

    ...     print submission.submission_key

    sample-submission

    >>> usb_storage_driver = getUtility(IHWDriverSet).getByPackageAndName(

    ...     'linux-image-2.6.24-19-generic', 'usb-storage')

    >>> print list(sata_controller.getSubmissions(

    ...     driver=usb_storage_driver))

    []

We can limit the results to a specific distribution.

    >>> from lp.registry.interfaces.distribution import (

    ...     IDistributionSet)

    >>> distribution_set = getUtility(IDistributionSet)

    >>> ubuntu = distribution_set.getByName('ubuntu')

    >>> for submission in sata_controller.getSubmissions(

    ...     distribution=ubuntu):

    ...     print submission.submission_key

    sample-submission

    >>> debian = distribution_set.getByName('debian')

    >>> sata_controller.getSubmissions(distribution=debian).count()

    0

We can limit the results to a specific architecture.

    >>> for submission in sata_controller.getSubmissions(

    ...     architecture='i386'):

    ...     print submission.submission_key

    sample-submission

    >>> sata_controller.getSubmissions(architecture='amd64').count()

    0

We can limit the results to a specific distro series.

    >>> for submission in sata_controller.getSubmissions(

    ...     distroseries=ubuntu['hoary']):

    ...     print submission.submission_key

    sample-submission

    >>> sata_controller.getSubmissions(distroseries=ubuntu['warty']).count()

    0

We can even limit the results to a specific distro series and architecture.

    >>> for submission in sata_controller.getSubmissions(

    ...     distroseries=ubuntu['hoary'], architecture='i386'):

    ...     print submission.submission_key

    sample-submission

    >>> sata_controller.getSubmissions(

    ...     distroseries=ubuntu['hoary'], architecture='powerpc').count()

    0

We can also search for submissions from a particular user.

    >>> from lp.registry.interfaces.person import IPersonSet

    >>> owner = getUtility(IPersonSet).getByName('name12')

    >>> for submission in sata_controller.getSubmissions(owner=owner):

    ...     print submission.submission_key

    sample-submission

    >>> not_owner = getUtility(IPersonSet).getByName('name20')

    >>> sata_controller.getSubmissions(owner=not_owner).count()