Introduction

Starting in 20.04, Ubuntu Desktop ISOs will support installing hardware specific metapackages if the machine being installed on has a corresponding enablement package available.

Ubiquity will use ubuntu-drivers to discover if an enablement package exists. The user will then be asked if they want to install the package, and it will be installed if they say “yes”.

Installing the package implies that it is on the ISO image. Packages on the ISO image must be in main. We expect there to be several of these at any given moment. Going through the full formal MIR process for each package is likely to be too much of a burden on the OEM / desktop / MIR teams, and so here we propose a streamlined process.

These packages enable an additional APT archive. This is the subject of a discussion with the Technical Board. See OEMArchive for further details.

Process

If packages meet the subscriber, naming and content requirements defined below, they may be promoted or NEWed directly into main without recourse to the MIR team. No future update may cause the package to not follow the requirements.

Archive admins can use the oem-metapackage-mir-check script from lp:ubuntu-archive-tools to view a debdiff against a reference package which is in the Ubuntu archive. If any of the differences are not covered in this document or trivially understandable, go back to the uploader.

Subscriber

As the packages are going to be in main, they need to have an 'owning' team which is subscribed to the bugs for the package in Launchpad. The team ~canonical-mainstream must be subscribed to the package before it is promoted.

Naming

The source and binary packages must follow the form oem-<product name>-meta.

Content

The packages must follow the following structure. They must be otherwise empty.

.
├── oem-foo-meta.list
└── debian
        ├── changelog
        ├── control
        ├── copyright
        ├── install
        ├── modaliases
        ├── rules
        └── source
            └── format

oem-foo-meta.list is installed into /etc/apt/sources.list.d/ and enables the OEM archive. No other files may be installed by the metapackage itself. If there is a case for installing other files, the package loses this MIR exception and must go through the normal process. The control file should look similar to

Source: oem-foo-meta
Section: misc
Priority: optional
Maintainer: Commercial Engineering <commercial-engineering@canonical.com>
Build-Depends: debhelper-compat (= 12), dh-modaliases
Standards-Version: 4.5.0

Package: oem-foo-meta
Architecture: all
Depends: ${misc:Depends},
        ubuntu-oem-keyring,
        fwupd,
        xserver-xorg-hwe-20.04,
XB-Modaliases: ${modaliases}
Description: hardware support for foo
 This is a metapackage for foo. It installs packages needed to support this
 hardware fully.

The list of dependencies may vary slightly. As usual, since they will be on the ISO these metapackages may depend on packages in main only. It is intended that the OEM archive offers upgrades to the metapackage itself if it needs to pull in other packages that can’t be on the ISO (this is the subject of the TB discussion).

The control file can optionally specify a field XB-Ubuntu-OEM-Kernel-Flavour to select a different kernel. Acceptable values are default (use the distribution's default kernel, i.e. generic or HWE) and oem. If this field isn't specified, oem is assumed.

The rules file should be minimal

%:
    dh $@ --with modaliases

so that the package is auditable. It must use dh-modalias to fill in the XB-Modalias field.

debian/{oem-foo-meta.,}modaliases contains the modaliases that will eventually end up in XB-Modaliases and represents the hardware set that this metapackage is designed to work with.

Known modaliases matching patterns

More information about modaliases in OEM meta packages

Matching types

• Matching by PCI ID
  • Modalias convention
    • pci:*sv0000${OEM_ID}sd0000${BIOS_ID}bc0Csc05*
    • OEM_ID
      • PCI Vendor ID of OEM (4 hexadecimal ASCII characters).
    • BIOS_ID
      • The unique ID of OEM System ID (4 hexadecimal ASCII characters).
    • bc0Csc05
      • bc (base class) 0C and sc (sub class) 05, matching SMBus (System Management Bus).
      • The purpose of comparing the SMBus is to avoid some add-on cards with incorrect subsystem IDs, which can cause the system to install unexpected platform meta-packages. E.g. A thunderbolt card which has subsystem ID “0739”, it makes the system installed an unexpected platform meta package for BIOS_ID “0739”.
  • Example of modaliases
    • E.g. “pci:*sv00001028sd0000084Abc0Csc05*”
    • sv 00001028 (subvendor)
    • sd 0000084A (subdevice)
  • OEM platforms using this matching type
    • Dell, HP
• Matching by DMI string
  • Modaliase convention
    • dmi:*bvn${OEM_NAME}:bvr${BIOS_ID}:pvr${PRODUCT_NAME}*
    • OEM_NAME:
      • DMI_BIOS_VENDOR
    • BIOS_ID:
      • DMI_BIOS_VERSION
      • The unique ID of the OEM platforms.
    • PRODUCT_NAME:
      • DMI_PRODUCT_VERSION
  • Example of modaliases
    • dmi:*bvnLENOVO:bvrR29*:pvrThinkPad*
  • OEM platform using this matching type
    • Lenovo

Known issue

• [1869867] Gives package-installs-apt-sources lintian error