git.sesse.net Git - bmusb/blob - README

   1 bmusb is a free driver for BlackMagic's Intensity Shuttle and
   2 UltraStudio SDI USB3 cards, which have no official Linux driver.
   3 (The two seem to speak exactly the same protocol.) It runs in userspace
   4 through usbfs, which may mean it could also probably run on FreeBSD,
   5 but it's untested.
   6
   7 Current tested features (note, some of these are not exposed in the
   8 driver except by changing the source code):
   9
  10  * HDMI and SDI capture on a variety of modes including 720p60, 1080p30 and
  11    1080i60. 1080p60 is unfortunately not supported, despite earlier (now
  12    retracted) promises by Blackmagic that it would come in a future firmware
  13    revision (this is unlike the Thunderbolt versions, where some older firmware
  14    revisions _do_ support it).
  15  * 8-channel 24-bit 48 kHz locked audio capture.
  16  * Analog audio capture, including setting levels.
  17  * 8-bit 4:2:2 and 10-bit 4:2:2 capture.
  18
  19 The BlackMagic cards follow a protocol whose exact format is still
  20 unknown, and the driver is still in beta stage. (The API/ABI is nearing
  21 stability, but is still not really locked.)
  22
  23 It seems to want about 10–15% of one CPU core; a significant chunk of this is
  24 copying data from the kernel over to userspace, which can be skipped by means
  25 of zerocopy USB if you have a very recent libusb (>= 1.0.21) and a recent
  26 kernel (>= 4.6.0). There's a decode step which also takes some time and memory
  27 bandwidth, but it supports custom memory allocators, so that once the USB
  28 packets are available to userspace, you can decode directly into e.g. pinned
  29 GPU memory.
  30
  31 The driver itself lives in bmusb.cpp; main.cpp contains a very simple
  32 client that just checks for frame continuity. It's recommended to run
  33 as root or some other user that can run the USB thread at realtime
  34 priority, as USB3 isochronous transfers are very timing sensitive.
  35
  36 The driver has been tested with various firmware versions; they seem to
  37 behave mostly the same. There is currently no tool to upgrade or downgrade
  38 the firmware on the card.
  39
  40 bmusb is Copyright 2015 Steinar H. Gunderson <steinar+bmusb@gunderson.no>
  41 and licensed under the GNU General Public License, version 2, or at your
  42 option, any later version. See the COPYING file.