Top

A Linux User Reference

Search tips
  • search ignores words that are less than 4 characters in length
  • searches are case insensitve
  • if a search does not return anything try it in Boolean mode then Query expansion mode by checking the appropriate radio button e.g. searching for 'cron' in just the Administration category returns nothing - presumably because the 50% threshold is reached. Boolean mode ignores this threshold so a search for 'cron' returns several hits
  • in Boolean mode preceding a word with a '+' means the result must include that word, a '-' means it must not
  • in Boolean mode '+crontab -anacron' means match articles about crontab that DO NOT mention anacron
  • to match a phrase e.g. 'manage system' check the Boolean mode radio button and enclose the phrase in quotes "some phrase ..."
  • in Query expansion mode the search context is expanded beyond the keywords you entered - relevancy of hits may well be degraded

HARDWARE

USB devices

  • Device classes and controllers

    There is no support with kernel versions 2.0 or earlier. Drivers are implemented in layers:

    (Top)         class drivers plus required modules
                  host controller drivers
    (Bottom)      usbcore.o
    

    Controllers

    • OHCI Open Host Controller Interface usb_1.112
    • UHCI Universal Controller Interface usb_1.112
    • EHCI Enhanced Controller Interface usb2.0480
    • xHCI eXtensible Host Controller Interface usb3.0

    See what controllers are supported on system

    $ lspci | grep -i usb
    00:10.0 USB controller: Advanced Micro Devices [AMD] FCH USB XHCI Controller (rev 03)
    00:12.0 USB controller: Advanced Micro Devices [AMD] FCH USB OHCI Controller (rev 11)
    00:12.2 USB controller: Advanced Micro Devices [AMD] FCH USB EHCI Controller (rev 11)
    00:13.0 USB controller: Advanced Micro Devices [AMD] FCH USB OHCI Controller (rev 11)
    00:13.2 USB controller: Advanced Micro Devices [AMD] FCH USB EHCI Controller (rev 11)
    
    Device class Example device(s)
    HID Keyboard, mouse, ...
    Communications Modems, ...
    Mass Storage Tapes, disks, pens, flash readers, ...
    Audio Sound devices
    IrDA Infra-red devices
    Printer Printers, usb-to-parallel cables
    Other Web-cams, ...
  • List USB devices
    /usr/bin/lsusb
    lsusb [options]...
    List USB devices
      -v, --verbose         Increase verbosity (show descriptors)
      -s [[bus]:][devnum]   Show only devices with specified device and/or
                            bus numbers (in decimal)
      -d vendor:[product]   Show only devices with the specified vendor and
                            product ID numbers (in hexadecimal)
      -D device             Selects which device lsusb will examine
      -t                    Dump the physical USB device hierarchy as a tree
      -V, --version         Show version of program
    

    List USB controllers and any attached devices

    $ lsusb
    Bus 001 Device 003: ID 174f:1468 Syntek 
    Bus 002 Device 002: ID 0bda:0129 Realtek Semiconductor Corp. 
    Bus 003 Device 002: ID 1bcf:0007 Sunplus Innovation Technology Inc. Optical Mouse
    Bus 005 Device 004: ID 7614:6387  
    .....
    Bus 006 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
    

    Blank entry is my usb stick .. remove, run 'lsusb', insert and run 'lsusb' to confirm device address when product/vendor info is unavailable.

    Examine a specific device - my usb stick

    $ sudo lsusb -D /dev/bus/usb/005/004
    [sudo] password for mark: 
    Device: ID 7614:6387  
    Device Descriptor:
      bLength                18
      bDescriptorType         1
      bcdUSB               2.00
    .....
    

    List only the device with bus:devnum and provide more detail

    $ lsusb -v -s 003:002
    Bus 003 Device 002: ID 07ab:fcdf Freecom Technologies 
    Device Descriptor:
    bLength 18
    bDescriptorType 1
    .....
    

    List only devices with vendor:product id

    $ lsusb -d 090c:1000
    Bus 003 Device 005: ID 090c:1000 Feiya Technology Corp.  Memory Bar
    

    List currently loaded usb modules

    (a few years back)
    $ lsmod | grep usb
    dgcusbdcp    16140   0
    usb_storage  73792   1
    libusual     19236   1  usb_storage 
    usbcore      146412  7  dgcusbdcp,rt73,usb_storage,libusual,ehci_hcd,ohci_hcd
    scsi_mod     151436  6  sbp2,usb_storage,sg,sr_mod,sd_mod,libata
    
    (2013) 
    $ lsmod | grep usb
    usb_storage            57204  1 
    usbhid                 47074  0 
    hid                   101002  2 hid_generic,usbhid
    
  • Hot and Cold plugging

    There is room for confusion here. Both terms can have different meanings depending on how they are applied. hotplug and coldplug are also applications.

    Hot plugging

    is the ability to add or remove hardware without having to power off the system.

    Cold plugging

    is the opposite, the system has to be shut down to remove the hardware.

    When used as comparative terms for hot pluggable devices, both hot and cold pluggable can mean the ability to add/remove devices without having to power down the system. In this context

    Hot pluggable

    means that the system can detect these changes by itself (e.g. via udev)

    Cold pluggable

    means that the system is unable to detect these changes and that they have to be configured manually.

  • Kernel userspace notification program
    /sbin/hotplug

    A program which is used by the kernel to notify user mode software when some significant (usually hardware-related) event takes place. This is the default 'hotplug' program.

    /proc/sys/kernel/hotplug

    A file that tells the kernel the path of the hotplug program to run.

    /etc/hotplug/*

    Hotplug configuration files are usb.rc, usb.agent, usb/$DRIVER. Inserting a USB device will 'modprobe' a driver, $DRIVER can be a custom 'init' script.

  • SuSe device detection program
    /sbin/coldplug

    A script whose responsibility is to take care of devices that hotplug has problems with detecting. It runs during the boot process before the hotplug sub system is enabled.

    • The script 'rccoldplug' calls 'hwup' for every static hardware configuration in /etc/sysconfig/hardware/hwcfg-static-*.
    • The scripts in /etc/hotplug/*.rc search for devices not yet initialised and create hotplug events. When the script runs it outputs one character for every device that has been checked

      Character Meaning
      . Device is already initialized and will be skipped.
      * Hotplug event will be created for the device.
      W Device is not on the white-list and will be skipped.
      B Device is on the blacklist and will be skipped.

    For PCI devices there is both a positive and a negative list of device types which should be initialised or skipped by coldplug. Detailed comments for this are contained in the file /etc/sysconfig/hotplug.

  • USB usermode management daemon
    usbmgr (obsolete)

    Replaced by udev

    A user-mode daemon. It loads and unloads some kernel modules (according to its configuration) and runs USB device setup scripts.

    File name Contents
    usbmgr.conf Device and module configuration information
    preload.conf Modules to load on daemon startup
  • Configure USB devices
    hotplug subsystem (obsolete)

    Replaced by udev

    At an administrative level, USB works very similarly to PCMCIA. Can chain of up to 127 devices on the same bus using a flexible radial topology of hubs and devices.

    The hotplug subsystem should handle the loading of any required drivers. Inserting a USB device will 'modprobe' a driver. Can create a script in /etc/hotplug/usb/$DRIVER to customise the initialisation of a device for a particular peripheral.

    Recognition of devices and control over the USB subsystem is contained in the /etc/hotplug/ directory:

    /etc/hotplug/usb.rc
    /etc/hotplug/usb.agent
    
  • USB pseudo filesystem
    /proc/bus/usb
    • Contains detailed information on the currently available USB devices (both hubs and peripherals).
    • Normally the USB bus is mounted as a dynamically generated filesystem similar to the /proc filesystem.
    • The filesystem type is known as either 'usbdevfs' or 'usbfs' and is mounted either in init scripts /etc/rcS.d/S02mountvirtfs or via /etc/fstab.

    An initialisation script may run something like

    # mount -t usbdevfs none /proc/bus/usb
    

    Mount via command line

    # mount -t usbdevfs none /proc/bus/usb
                                             (or)
    $ sudo mount -t usbfs none /proc/bus/usb -o devmode=0666
    

    Mount via /etc/fstab entry

    none /proc/bus/usb usbdevfs defaults 0 0
    
  • Print USB device details
    /usr/bin/usb-devices

    'usb-devices' is a (bash) shell script that can be used to display details of USB buses in the system and the devices connected to them.

    The output of the script is similar to the /proc/bus/usb/devices file if 'usbfs' is mounted or under /sys/kernel/debug if debugfs is mounted there. The script is primarily intended to be used if the file is not available.

    This script only lists active interfaces and their endpoints.

    /sys/bus/usb/devices/usb*

    The part of the 'sysfs' tree the script walks through to assemble the printed information.

    /proc/bus/usb/devices

    Location where the usb/devices file can normally be found for Linux kernels before 2.6.31, if 'usbfs' is mounted.

    /sys/kernel/debug/usb/devices

    Location where the usb/devices file can normally be found for Linux kernel 2.6.31 and later, if 'debugfs' is mounted.

    Print USB device details when no mounted 'usbfs' or 'debugfs'

    $ grep usb /etc/mtab
    $
    
    $ usb-devices
    
    T:  Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=480 MxCh= 5
    D:  Ver= 2.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS=64 #Cfgs=  1
    P:  Vendor=1d6b ProdID=0002 Rev=03.08
    S:  Manufacturer=Linux 3.8.0-31-generic ehci_hcd
    S:  Product=EHCI Host Controller
    S:  SerialNumber=0000:00:12.2
    C:  #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=0mA
    I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
    
    T:  Bus=01 Lev=01 Prnt=01 Port=03 Cnt=01 Dev#=  3 Spd=480 MxCh= 0
    .....
    
  • Determine driver and kernel parameters a usb device requires
    • Easiest way is to use a Distribution CD (or compile all modules for a device type) and let udev or modprobe determine the required driver.
    • A more labour intensive method ..

    (1) List current devices - before plugging in the device

    $ ls -al /sys/bus/usb/devices
    total 0
    drwxr-xr-x 2 root root 0 Nov 27 22:10 .
    drwxr-xr-x 4 root root 0 Nov 27 22:10 ..
    lrwxrwxrwx 1 root root 0 Nov 27 22:10 1-0:1.0 -> ../../../devices/pci0000:00/0000:00:12.2/usb1/1-0:1.0
    lrwxrwxrwx 1 root root 0 Nov 27 22:10 1-4 -> ../../../devices/pci0000:00/0000:00:12.2/usb1/1-4
    .....
    lrwxrwxrwx 1 root root 0 Nov 27 22:10 4-0:1.0 -> ../../../devices/pci0000:00/0000:00:13.0/usb4/4-0:1.0
    lrwxrwxrwx 1 root root 0 Nov 27 22:10 5-0:1.0 -> ../../../devices/pci0000:00/0000:00:10.0/usb5/5-0:1.0
    lrwxrwxrwx 1 root root 0 Nov 27 22:10 6-0:1.0 -> ../../../devices/pci0000:00/0000:00:10.0/usb6/6-0:1.0
    lrwxrwxrwx 1 root root 0 Nov 27 22:10 usb1 -> ../../../devices/pci0000:00/0000:00:12.2/usb1
    .....
    

    (2) Plug in the usb device (a pen in this case)

    .....
    lrwxrwxrwx 1 root root 0 Nov 27 22:10 5-0:1.0 -> ../../../devices/pci0000:00/0000:00:10.0/usb5/5-0:1.0
    lrwxrwxrwx 1 root root 0 Nov 27 23:07 5-2 -> ../../../devices/pci0000:00/0000:00:10.0/usb5/5-2
    lrwxrwxrwx 1 root root 0 Nov 27 23:07 5-2:1.0 -> ../../../devices/pci0000:00/0000:00:10.0/usb5/5-2/5-2:1.0
    lrwxrwxrwx 1 root root 0 Nov 27 22:10 6-0:1.0 -> ../../../devices/pci0000:00/0000:00:10.0/usb6/6-0:1.0
    .....
    

    (3) Follow links to determine module being used

    $ basename `readlink /sys/bus/usb/devices/5-2:1.0/driver/module`
    usb_storage
    

    (4) Determine kernel param(s) to enable the driver

    $ cd /usr/src/linux-headers-3.8.0-33
    $ find -type f -name Makefile | xargs grep -i usb_storage
    ./drivers/usb/storage/Makefile:obj-$(CONFIG_USB_STORAGE)    += usb-storage.o
    ./drivers/usb/storage/Makefile:usb-storage-$(CONFIG_USB_STORAGE_DEBUG) += debug.o
    .....
    

    (5) Check param and if module is loaded

    $ grep -i config_usb_storage /boot/config-3.8.0-33-generic
    CONFIG_USB_STORAGE=m
    # CONFIG_USB_STORAGE_DEBUG is not set
    .....
    
    $ lsmod | grep usb
    usb_storage            57204  1 
    

    As you would expect - kernel parameter for driver configured as a module and module is loaded.

    The above process but from scratch

    NB. this example is from a few years back - you need the source for this, headers aren't enough - the steps are the same

    (1) Plug in usb device (usb wireless adapter) and get vendor and product id

    # lsusb 
    Bus 003 Device 007: ID 148f:2573 Ralink Technology, Corp.
    .....
    

    vendor id = 148f, product id=2573

    (2) Search the kernel source tree for the vendor id

    # cd /usr/src/linux-source-2.6.24 
    
    # grep -i -R -l 148f drivers/*              
    drivers/atm/pca200e_ecd.data 
    drivers/net/wireless/rt2x00/rt2500usb.c 
    drivers/net/wireless/rt2x00/rt73usb.c 
    drivers/net/acenic_firmware.h 
    drivers/usb/misc/emi62_fw_s.h
    
    (args used)
    -i                            Ignore case
    -R                            Recurse
    -l|--files-with-matches       Print the name of file with a match
    -L|--files-without-match      Print the name of the file(s) that do not have a match
    

    Know it is a network wireless adapter so the driver source is either rt2500usb.c or rt73usb.c

    (3) Search for the vendor and product id in a driver source file

    # grep -i 148f drivers/net/wireless/rt2x00/rt73usb.c 
        { USB_DEVICE(0x148f, 0x2573), USB_DEVICE_DATA(&rt73usb_ops) }, 
        { USB_DEVICE(0x148f, 0x2671), USB_DEVICE_DATA(&rt73usb_ops) },
    

    (4) Determine the kernel parameter this driver needs to be enabled

    # find -type f -name Makefile | xargs grep -i rt73 
    ./drivers/net/wireless/rt2x00/Makefile:obj-$(CONFIG_RT73USB)        += rt73usb.o
    

    (5) Check if the kernel module is enabled

    # grep -i rt73usb /boot/config-2.6.24-21-generic 
    CONFIG_RT73USB=m
    

    If not enabled then need to enable and recompile kernel.

    Result

    USB wireless adapter requires the 'rt73usb.o' driver and kernel parameter 'CONFIG_RT73USB' enabled, which it is.