l.h.s.h.BaseDevice : class documentation

Part of lp.hardwaredb.scripts.hwdbsubmissions View In Hierarchy

Known subclasses: lp.hardwaredb.scripts.hwdbsubmissions.HALDevice, lp.hardwaredb.scripts.hwdbsubmissions.UdevDevice

A base class to represent device data from HAL and udev.
Method __init__ Undocumented
Method addChild Add a child device and set the child's parent.
Method device_id A unique ID for this device.
Method pci_class The PCI device class of the device or None for Non-PCI devices.
Method pci_subclass The PCI device sub-class of the device or None for Non-PCI devices.
Method usb_vendor_id The USB vendor ID of the device or None for Non-USB devices.
Method usb_product_id The USB product ID of the device or None for Non-USB devices.
Method scsi_vendor The SCSI vendor name of the device or None for Non-SCSI devices.
Method scsi_model The SCSI model name of the device or None for Non-SCSI devices.
Method vendor The vendor of this device.
Method product The vendor of this device.
Method vendor_id The vendor ID of this device.
Method product_id The product ID of this device.
Method vendor_id_for_db The vendor ID in the representation needed for the HWDB tables.
Method product_id_for_db The product ID in the representation needed for the HWDB tables.
Method driver_name The name of the driver contolling this device. May be None.
Method scsi_controller Return the SCSI host controller for this device.
Method translateScsiBus Return the real bus of a device where raw_bus=='scsi'.
Method translatePciBus Undocumented
Method is_root_device Return True is this is the root node of all devicese, else False.
Method raw_bus Return the device bus as specified by HAL or udev.
Method real_bus Return the bus this device connects to on the host side.
Method is_real_device True, if the HAL device correspends to a real device.
Method getRealChildren Return the list of real child devices of this devices.
Method has_reliable_data Can this device be stored in the HWDB?
Method getScsiVendorAndModelName Separate vendor and model name of SCSI decvices.
Method getDriver Return the HWDriver instance associated with this device.
Method ensureVendorIDVendorNameExists Ensure that a useful HWVendorID record for self.vendor_id exists.
Method createDBData Create HWDB records for this HAL device and its children.
Method createDBDriverData Create HWDB records for drivers of this device and its children.
def __init__(self, parser):
Undocumented
def addChild(self, child):
Add a child device and set the child's parent.
@property
def device_id(self):
A unique ID for this device.
@property
def pci_class(self):
The PCI device class of the device or None for Non-PCI devices.
@property
def pci_subclass(self):
The PCI device sub-class of the device or None for Non-PCI devices.
@property
def usb_vendor_id(self):
The USB vendor ID of the device or None for Non-USB devices.
@property
def usb_product_id(self):
The USB product ID of the device or None for Non-USB devices.
@property
def scsi_vendor(self):
The SCSI vendor name of the device or None for Non-SCSI devices.
@property
def scsi_model(self):
The SCSI model name of the device or None for Non-SCSI devices.
@property
def vendor(self):
The vendor of this device.
@property
def product(self):
The vendor of this device.
@property
def vendor_id(self):
The vendor ID of this device.
@property
def product_id(self):
The product ID of this device.
@property
def vendor_id_for_db(self):
The vendor ID in the representation needed for the HWDB tables.

USB and PCI IDs are represented in the database in hexadecimal, while the IDs provided by HAL are integers.

The SCSI vendor name is right-padded with spaces to 8 bytes.

@property
def product_id_for_db(self):
The product ID in the representation needed for the HWDB tables.

USB and PCI IDs are represented in the database in hexadecimal, while the IDs provided by HAL are integers.

The SCSI product name is right-padded with spaces to 16 bytes.

@property
def driver_name(self):
The name of the driver contolling this device. May be None.
@property
def scsi_controller(self):
Return the SCSI host controller for this device.
def translateScsiBus(self):
Return the real bus of a device where raw_bus=='scsi'.

The kernel uses the SCSI layer to access storage devices connected via the USB, IDE, SATA buses. See is_real_device for more details. This method determines the real bus of a device accessed via the kernel's SCSI subsystem.

def translatePciBus(self):
Undocumented
@property
def is_root_device(self):
Return True is this is the root node of all devicese, else False.
@property
def raw_bus(self):
Return the device bus as specified by HAL or udev.
@property
def real_bus(self):
Return the bus this device connects to on the host side.
ReturnsA bus as enumerated in HWBus or None, if the bus cannot be determined.
@property
def is_real_device(self):
True, if the HAL device correspends to a real device.

In many cases HAL has more than one device entry for the
same physical device. We are only interested in real, physical,
devices but not in the fine details, how HAL represents different
aspects of them.

For example, the HAL device node hiearchy for a SATA disk and
its host controller looks like this:

HAL device node of the host controller
    udi: .../pci_8086_27c5
    HAL properties:
        info.bus: pci
        pci.device_class: 1 (storage)
        pci.device_subclass: 6 (SATA)
        info.linux.driver: ahci

HAL device node of the "output aspect" of the host controller
    udi: .../pci_8086_27c5_scsi_host
    HAL properties:
        info.bus: n/a
        info.driver: n/a
        info.parent: .../pci_8086_27c5

HAL device node of a hard disk.
    udi: .../pci_8086_27c5_scsi_host_scsi_device_lun0
    HAL properties:
        info.bus: scsi
        info.driver: sd
        info.parent: .../pci_8086_27c5_scsi_host

HAL device node of the "storage aspect" of the hard disk
    udi: .../storage_serial_1ATA_Hitachi_HTS541616J9SA00_SB...
    HAL properties
        info.driver: n/a
        info.parent: .../pci_8086_27c5_scsi_host_scsi_device_lun0

HAL device node of a disk partition:
    udi: .../volume_uuid_0ee803cf_...
    HAL properties
        info.driver: n/a
        info.parent: .../storage_serial_1ATA_Hitachi_HTS541616J...

(optionally more nodes for more partitions)

HAL device node of the "generic SCSI aspect" of the hard disk:
    udi: .../pci_8086_27c5_scsi_host_scsi_device_lun0_scsi_generic
        info.driver: n/a
        info.parent: .../pci_8086_27c5_scsi_host_scsi_device_lun0

This disk is _not_ a SCSI disk, but a SATA disk. In other words,
the SCSI details are in this case just an artifact of the Linux
kernel, which uses its SCSI subsystem as a "central hub" to access
IDE, SATA, USB, IEEE1394 storage devices. The only interesting
detail for us is that the sd driver is involved in accesses to the
disk.

Heuristics:

- Most real devices have the property info.bus; we consider only
  those devices to be real which have this property set.

- As written above, the SCSI bus often appears as an artifact;
  for PCI host controllers, their properties pci.device_class
  and pci.device_subclass tell us if we have a real SCSI host
  controller: pci.device_class == 1 means a storage controller,
  pci.device_subclass == 0 means a SCSI controller. This works
  too for PCCard controllers, which use the PCI device class
  numbers too.

- The value "usb_device" of the HAL property info.bus identifies
  USB devices, with one exception: The USB host controller, which
  itself has an info.bus property with the value "pci", has a
  sub-device with info.bus='usb_device' for its "output aspect".
  These sub-devices can be identified by the device class their
  parent and by their USB vendor/product IDs, which are 0:0.

Several info.bus/info.subsystem values always relate to HAL nodes
which describe only "aspects" of physical devcies which are
represented by other HAL nodes:

  - bus is None for a number of "virtual components", like
    /org/freedesktop/Hal/devices/computer_alsa_timer or
    /org/freedesktop/Hal/devices/computer_oss_sequencer, so
    we ignore them. (The real sound devices appear with
    other UDIs in HAL.)

    XXX Abel Deuring 20080425: This ignores a few components
    like laptop batteries or the CPU, where info.bus is None.
    Since these components are not the most important ones
    for the HWDB, we'll ignore them for now. Bug 237038.

  - 'disk' is used udev submissions for a node related to the
    sd or sr driver of (real or fake) SCSI block devices.

  - info.bus == 'drm' is used by the HAL for the direct
    rendering interface of a graphics card.

  - info.bus == 'dvb' is used by HAL for the "input aspect"
    of DVB receivers

  - info.bus == 'memstick_host' is used by HAL for the "output aspect"
    of memory sticks.

  - info.bus == 'net' is used by the HAL version in
    Intrepid for the "output aspects" of network devices.

  - 'partition' is used in udev submissions for a node
    related to disk partition

  - 'scsi_disk' is used in udev submissions for a sub-node of
    the real device node.

    info.bus == 'scsi_generic' is used by the HAL version in
    Intrepid for a HAL node representing the generic
    interface of a SCSI device.

    info.bus == 'scsi_host' is used by the HAL version in
    Intrepid for real and "fake" SCSI host controllers.
    (On Hardy, these nodes have no info.bus property.)
    HAL nodes with this bus value are sub-nodes for the
    "SCSI aspect" of another HAL node which represents the
    real device.

    'scsi_target' is used in udev data for SCSI target nodes,
    the parent of a SCSI device (or LUN) node.

    'spi_transport' (SCSI Parallel Transport) is used in
    udev data for a sub-node of real SCSI devices.

    info.bus == 'sound' is used by the HAL version in
    Intrepid for "aspects" of sound devices.

    info.bus == 'ssb' is used for "aspects" of Broadcom
    Ethernet and WLAN devices, but like 'usb', they do not
    represent separate devices.

    info.bus == 'tty' is used for the "output aspect"
    of serial output devices (RS232, modems etc). It appears
    for USB and PCI devices as well as for legacy devices
    like the 8250/16450/16550 controllers.

    info.bus == 'usb' is used for end points of USB devices;
    the root node of a USB device has info.bus == 'usb_device'.

    'usb_interface' is used in udv submissions for interface
    nodes of USB devices.

    info.bus == 'video4linux' is used for the "input aspect"
    of video devices.

    'ac97' is used in submissions with udev data for a sub-node
    of sound devices.

    'hid' is used in submissions with udev data for a sub-node
    of USB input devices.

    'drm_minor', 'pci_express', 'tifm_adapter', 'gameport',
    'spi_host', 'tifm', 'wlan' are used in submissions with
    udev data for sub-nodes of PCI devices.

    'pcmcia_socket' is used in submissions with udev data for
    a sub-node of PC Card and PCMCIA bridges.

    'ieee80211'  is used in submissions with udev data for
    sub-nodes IEEE 802.11 WLAN devices.

    'host', 'link' are used in submissions with udev data for
    sub.nodes of bluetooth devices.

    'usb_host' and 'usbmon' are used in submissions with udev
    data for sub-nodes of USB controllers.

    'usb_endpoint', 'usb-serial', 'lirc' are used in
    submissions with udev data for sub-nodes of USB devices.

    'enclosure' is used in submissions with udev data for a
    sub.node of SCSI devices.

    'graphics' is used  in submissions with udev data for a
    sub-node of graphics cards.

    'hwmon' is is used  in submissions with udev data in
    many sub-nodes.

    'sas_phy', 'sas_device', 'sas_end_device', 'sas_port',
    'sas_host' is used in submissions with udev data for
    details of SAS controllers.

    'mISDN' is used  in submissions with udev data for the
    I/O aspects of ISDN adapters.

    'pvrusb2' is used  in submissions with udev data for the
    input aspect of some DVB adapters.

    'memstick' is used  in submissions with udev data for the
    I/O aspect of memory stick controllers.

    'bttv-sub' is used  in submissions with udev data for the
    I/O aspects of some TV receivers.

    'scsi_tape' is used  in submissions with udev data for
    details of SCSI tape drives.
    
def getRealChildren(self):
Return the list of real child devices of this devices.

The list of real child devices consists of the direct child devices of this device where child.is_real_device == True, and of the (recursively collected) list of real sub-devices of those child devices where child.is_real_device == False.

@property
def has_reliable_data(self):
Can this device be stored in the HWDB?

Devices are identifed by (bus, vendor_id, product_id). At present we cannot generate reliable vendor and/or product IDs for devices with the following values of the HAL property info.bus resp. info.subsystem.

info.bus == 'backlight' is used by the HAL version in Intrepid for the LC display. Useful vendor and product names are not available.

info.bus == 'bluetooth': HAL does not provide any vendor/product ID data, so we can't store these devices in HWDevice.

info.bus == 'input' is used by the HAL version in Intrepid for quite different devices like keyboards, mice, special laptop switches and buttons, sometimes with odd product names like "Video Bus".

info.bus == 'misc' and info.bus == 'unknown' are obviously not very useful, except for the computer itself, which has the bus 'unknown'.

info.bus in ('mmc', 'mmc_host') is used for SD/MMC cards resp. the "output aspect" of card readers. We do not not have at present enough background information to properly extract a vendor and product ID from these cards.

info.bus == 'platform' is used for devices like the i8042 which controls keyboard and mouse; HAL has no vendor information for these devices, so there is no point to treat them as real devices.

info.bus == 'pnp' is used for components like the ancient AT DMA controller or the keyboard. Like for the bus 'platform', HAL does not provide any vendor data.

info.bus == 'power_supply' is used by the HAL version in Intrepid for AC adapters an laptop batteries. We don't have at present enough information about possible problems with missing vendor/product information in order to store the data reliably in the HWDB.

raw_bus == 'acpi' is used in udev data for the main system, for CPUs, power supply etc. Except for the main sytsem, none of them provides a vendor or product id, so we ignore them.

raw_bus == 'video_output', 'thermal', 'vtconsole', 'bdi', 'mem', 'ppp', 'vc', 'dmi', 'hidraw', 'hwmon', 'heci', 'rfkill', 'i2c-adapter', 'ttm', 'ppdev', 'printer', 'cardman_4040', 'msr', 'ieee1394_protocol', 'dahdi', 'atm', 'asus_oled', 'pktcdvd' is used in submissions with udev data for virtual devices.

'pci_bus' is used in submissions with udev data for a node describing a PCI bus.

'leds' is used in submissions with udev data to describe LEDs.

XXX Abel Deuring 2008-05-06: IEEE1394 devices are a bit nasty: The standard does not define any specification for product IDs or product names, hence HAL often uses the value 0 for the property ieee1394.product_id and a value like "Unknown (0x00d04b)" for ieee.product, where 0x00d04b is the vendor ID. I have currently no idea how to find or generate something that could be used as the product ID, so IEEE1394 devices are at present simply not stored in the HWDB. Otherwise, we'd pollute the HWDB with unreliable data. Bug #237044.

While PCMCIA devices have a manufacturer ID, at least its value as provided by HAL in pcmcia.manf_id it is not very reliable. The HAL property pcmcia.prod_id1 is too not reliable. Sometimes it contains a useful vendor name like "O2Micro" or "ATMEL", but sometimes useless values like "IEEE 802.11b". See for example drivers/net/wireless/atmel_cs.c in the Linux kernel sources.

Provided that a device is not excluded by the above criteria, ensure that we have vendor ID, product ID and product name.

def getScsiVendorAndModelName(self):
Separate vendor and model name of SCSI decvices.

SCSI devcies are identified by an 8 charcter vendor name and an 16 character model name. The Linux kernel use the the SCSI command set to access block devices connected via USB, IEEE1394 and ATA buses too.

For ATA disks, the Linux kernel sets the vendor name to "ATA" and prepends the model name with the real vendor name, but only if the combined length if not larger than 16. Otherwise the real vendor name is omitted.

This method provides a safe way to retrieve the the SCSI vendor and model name.

If the vendor name is 'ATA', and if the model name contains at least one ' ' character, the string before the first ' ' is returned as the vendor name, and the string after the first ' ' is returned as the model name.

In all other cases, vendor and model name are returned unmodified.

def getDriver(self):
Return the HWDriver instance associated with this device.

Create a HWDriver record, if it does not already exist.

def ensureVendorIDVendorNameExists(self):
Ensure that a useful HWVendorID record for self.vendor_id exists.

A vendor ID is associated with a vendor name. For many devices we rely on the information from the submission to create this association in the HWVendorID table.

We do _not_ use the submitted vendor name for USB, PCI and PCCard devices, because we can get them from independent sources. See l/c/l/doc/hwdb-device-tables.txt.

def createDBData(self, submission, parent_submission_device):
Create HWDB records for this HAL device and its children.

A HWDevice record for (bus, vendor ID, product ID) of this device and a HWDeviceDriverLink record (device, None) are created, if they do not already exist.

A HWSubmissionDevice record is created for (HWDeviceDriverLink, submission).

HWSubmissionDevice records and missing HWDeviceDriverLink records for known drivers of this device are created.

createDBData is called recursively for all real child devices.

This method may only be called, if self.real_device == True.

def createDBDriverData(self, submission, db_device, submission_device):
Create HWDB records for drivers of this device and its children.

This method creates HWDeviceDriverLink and HWSubmissionDevice records for this device and its children.

API Documentation for Launchpad, generated by pydoctor at 2022-06-16 00:00:12.