Building Pyramids

Matt Polnik's blog

Device Drivers Installation on Linux

Linux

USB Network Card

Linux operating system family has not yet came with a robust solution to automatically detect missing drivers and install relevant firmware in the background. Fortune favours the bold, so don’t be discouraged by the lack of this feature. This post aims to provide you with general purpose instructions how to find packages with drivers that are required by your hardware assuming firmware is available for your Linux distribution.

Let’s take a popular USB network card as an example.

Tutorial

  1. Plug off the network card from the USB port, get a coffee and plug it back.

  2. Open a terminal window and print the latest messages in the kernel ring buffer using the dmesg command.

    dmesg
    [  405.865412] usb 2-2: USB disconnect, device number 2
    [  442.751965] usb 2-2: new high-speed USB device number 11 using xhci_hcd
    [  442.952428] usb 2-2: New USB device found, idVendor=0cf3, idProduct=9271
    [  442.952431] usb 2-2: New USB device strings: Mfr=16, Product=32, SerialNumber=48
    [  442.952433] usb 2-2: Product: USB2.0 WLAN
    [  442.952434] usb 2-2: Manufacturer: ATHEROS
    [  442.952435] usb 2-2: SerialNumber: 12345
    [  442.952973] usb 2-2: ath9k_htc: Firmware htc_9271.fw requested
    [  442.953077] usb 2-2: firmware: failed to load htc_9271.fw (-2)
    [  442.953080] usb 2-2: Direct firmware load failed with error -2
    [  442.953081] usb 2-2: Falling back to user helper
    [  442.953636] usb 2-2: ath9k_htc: USB layer deinitialized
    

    The console output contains a name of the firmware htc_9271.fw which has not been successfully loaded.

    If you are not such lucky to find relevant names here. Try the manufacturer or the engineering name for your product which may be different from the marketing name.

    Use the lsusb command to check the name of device connected to USB port and review messages logged to /var/log/syslog.

    lsusb
    sudo tail -f /var/log/syslog
    
  3. Find relevant package name for your Linux distribution in the package search using the firmware name. The following links point to Debian and Ubuntu package search respectively.

    Instead of the package search on website you may use the Debian REST API directly.

    Endpoint Operation
    https://packages.debian.org/name Search on package names
    https://packages.debian.org/src:name Search on source package names
    https://packages.debian.org/file:path Search for paths ending in the keyword

    If you don’t get any meaningful results by search on package names, consider advanced search on package directories or the contents of packages. Indeed, in the tutorial example htc_9271.fw the relevant package can be found using the last option: https://packages.debian.org/file:htc_9271.fw.

  4. Open the firmware-atheros package description from the search results.

    You should quickly spot the non-free label next to the package name. Packages marked with this tag do not comply with Debian Free Software Guidelines (DFSG) or were not assessed for such compliance. It is often the case for a third-party device drivers, especially if their codebase is not available open source.

    It is still possible to install packages marked as non-free using the apt-get tool chain. However, it requires a prior update of the package manager configuration, because by default third-party packages are not mentioned in the list of available sources in the package repository.

  5. Enable the non-free source in official package repositories by editing the sources.list file.

    sudo vim /etc/apt/sources.list
    

    After your changes the sources.list file should resemble the following example.

    deb http://httpredir.debian.org/debian jessie main contrib non-free
    deb-src http://httpredir.debian.org/debian jessie main contrib non-free
    deb http://httpredir.debian.org/debian jessie-updates main contrib non-free
    deb-src http://httpredir.debian.org/debian jessie-updates main contrib non-free
    deb http://security.debian.org/ jessie/updates main contrib non-free
    deb-src http://security.debian.org/ jessie/updates main contrib non-free
    deb http://httpredir.debian.org/debian jessie-backports main contrib non-free
    
  6. Update the list of packages and install the firmware-atheros package.

    sudo apt-get update
    sudo apt-get install firmware-atheros
    
  7. Disconnect the USB network card and plug it again. If your network card is equipped with a status diode, it should start blinking.

  8. Finally, print the latest kernel messages to confirm that the firmware has been successfully loaded.

    [ 6972.212991] usb 2-2: new high-speed USB device number 12 using xhci_hcd
    [ 6972.413663] usb 2-2: New USB device found, idVendor=0cf3, idProduct=9271
    [ 6972.413666] usb 2-2: New USB device strings: Mfr=16, Product=32, SerialNumber=48
    [ 6972.413667] usb 2-2: Product: USB2.0 WLAN
    [ 6972.413668] usb 2-2: Manufacturer: ATHEROS
    [ 6972.413669] usb 2-2: SerialNumber: 12345
    [ 6972.414213] usb 2-2: ath9k_htc: Firmware htc_9271.fw requested
    [ 6972.414345] usb 2-2: firmware: direct-loading firmware htc_9271.fw
    [ 6972.697655] usb 2-2: ath9k_htc: Transferred FW: htc_9271.fw, size: 51272
    [ 6972.935153] ath9k_htc 2-2:1.0: ath9k_htc: HTC initialized with 33 credits
    [ 6973.200832] ath9k_htc 2-2:1.0: ath9k_htc: FW Version: 1.3
    

I hope this example contributed to better understanding of Linux device drivers ecosystem and provided you with a set of clues ready to use while investigating missing driver issues.