kernel/linux/Documentation/dvb/firmware.txt

   1 Some DVB cards and many newer frontends require proprietary,
   2 binary-only firmware.
   3
   4 The DVB drivers will be converted to use the request_firmware()
   5 hotplug interface (see Documentation/firmware_class/).
   6 (CONFIG_FW_LOADER)
   7
   8 The firmware can be loaded automatically via the hotplug manager
   9 or manually with the steps described below.
  10
  11 Currently the drivers still use various different methods
  12 to load their firmwares, so here's just a short list of the
  13 current state:
  14
  15 - dvb-ttpci: driver uses firmware hotplug interface
  16 - ttusb-budget: firmware is compiled in (dvb-ttusb-dspbootcode.h)
  17 - sp887x: firmware is compiled in (sp887x_firm.h)
  18 - alps_tdlb7: firmware is loaded from path specified by
  19                 "mcfile" module parameter; the binary must be
  20                 extracted from the Windows driver (Sc_main.mc).
  21 - tda1004x: firmware is loaded from path specified in
  22                 DVB_TDA1004X_FIRMWARE_FILE kernel config
  23                 variable (default /usr/lib/hotplug/firmware/tda1004x.bin); the
  24                 firmware binary must be extracted from the windows
  25                 driver
  26 - ttusb-dec: see "ttusb-dec.txt" for details
  27
  28 1) Automatic firmware loading
  29
  30 You need to install recent hotplug scripts if your distribution did not do it
  31 for you already, especially the  /etc/hotplug/firmware.agent.
  32 http://linux-hotplug.sourceforge.net/ (Call /sbin/hotplug without arguments
  33 to find out if the firmware agent is installed.)
  34
  35 The firmware.agent script expects firmware binaries in
  36 /usr/lib/hotplug/firmware/. To avoid naming and versioning
  37 conflicts we propose the following naming scheme:
  38
  39   /usr/lib/hotplug/firmware/dvb-{driver}-{ver}.fw       for MPEG decoders etc.
  40   /usr/lib/hotplug/firmware/dvb-fe-{driver}-{ver}.fw    for frontends
  41
  42   {driver} name is the basename of the driver kernel module (e.g. dvb-ttpci)
  43   {ver} is a version number/name that should change only when the
  44   driver/firmware internal API changes (so users are free to install the
  45   latest firmware compatible with the driver).
  46
  47 2) Manually loading the firmware into a driver
  48    (currently only the dvb-ttpci / av7110 driver supports this)
  49
  50 Step a) Mount sysfs-filesystem.
  51
  52 Sysfs provides a means to export kernel data structures, their attributes,
  53 and the linkages between them to userspace.
  54
  55 For detailed informations have a look at Documentation/filesystems/sysfs.txt
  56 All you need to know at the moment is that firmware loading only works through
  57 sysfs.
  58
  59 > mkdir /sys
  60 > mount -t sysfs sysfs /sys
  61
  62 Step b) Exploring the firmware loading facilities
  63
  64 Firmware_class support is located in
  65 /sys/class/firmware
  66
  67 > dir /sys/class/firmware
  68
  69 The "timeout" values specifies the amount of time that is waited before the
  70 firmware upload  process is cancelled. The default values is 10 seconds. If
  71 you use a hotplug script for the firmware upload, this is sufficient. If
  72 you want to upload the firmware by hand, however, this might be too fast.
  73
  74 > echo "180" > /sys/class/firmware/timeout
  75
  76 Step c) Getting a usable firmware file for the dvb-ttpci driver/av7110 card.
  77
  78 You can download the firmware files from
  79 http://linuxtv.org/download/dvb/
  80
  81 Please note that in case of the dvb-ttpci driver this is *not* the "Root"
  82 file you probably know from the 2.4 DVB releases driver.
  83
  84 The ttpci-firmware utility from linuxtv.org CVS can be used to
  85 convert Dpram and Root files into a usable firmware image.
  86 See dvb-kerrnel/scripts/ in http://linuxtv.org/cvs/.
  87
  88 > wget http://www.linuxtv.org/download/dvb/dvb-ttpci-01.fw
  89 gets you the version 01 of the firmware fot the ttpci driver.
  90
  91 Step d) Loading the dvb-ttpci driver and loading the firmware
  92
  93 "modprobe" will take care that every needed module will be loaded
  94 automatically (except the frontend driver)
  95
  96 > modprobe dvb-ttpci
  97
  98 The "modprobe" process will hang until
  99 a) you upload the firmware or
 100 b) the timeout occurs.
 101
 102 Change to another terminal and have a look at
 103
 104 > dir /sys/class/firmware/
 105
 106 total 0
 107 drwxr-xr-x    2 root     root            0 Jul 29 11:00 0000:03:05.0
 108 -rw-r--r--    1 root     root            0 Jul 29 10:41 timeout
 109
 110 "0000:03:05.0" is the id for my dvb-c card. It depends on the pci slot,
 111 so it changes if you plug the card to different slots.
 112
 113 You can upload the firmware like that:
 114
 115 > export DEVDIR=/sys/class/firmware/0000\:03\:05.0
 116 > echo 1 > $DEVDIR/loading
 117 > cat dvb-ttpci-01.fw > $DEVDIR/data
 118 > echo 0 > $DEVDIR/loading
 119
 120 That's it. The driver should be up and running now.