Support overriding pkg-config.
[bmusb] / 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.