USB3 Vision cameras on Linux: usbfs and file limits that need tuning

You plugged a USB3 Vision camera into a Linux host, and half the advice you find says to raise the kernel's USB memory cap and the file-handle limit before anything will stream. On current stacks that advice is mostly outdated. The GenTL producer your vision software loads sets the USB transfer size itself, raises the usbfs memory limit to about one quarter of system RAM, and holds fewer than about 10 file handles per camera against the 1024-per-process default. Below are the three numbers to check once the software has run, the arithmetic that decides whether they are enough, and the two commands that matter on the host that genuinely needs them.

What the driver already configures

A USB3 Vision camera on Linux enumerates through libusb, and the transport layer your software loads — the GenTL producer — owns every performance-relevant USB setting. During enumeration it negotiates the transfer size with the camera's streaming registers and currently uses 3 MByte per transfer. There is no kernel parameter or application setting that improves on this, and a value forced from outside can only fight the handshake.

That leaves the two settings older guides tell you to tune by hand: the kernel's usbfs memory cap and the per-process file-handle limit. Both are real, both deserve one look after installation, and neither should be changed by reflex.

The usbfs memory cap and the quarter-RAM rule

usbfs is the kernel interface libusb uses to submit transfers, and usbfs_memory_mb caps how much memory it may lock for transfers that are in flight. The kernel ships the parameter at 16 MB. A streaming USB3 Vision camera holds whole image buffers as pending bulk transfers, so 16 MB cannot carry a modern sensor — which is why the producer raises the cap itself when it starts. Current GenTL producers write one quarter of the available RAM into /sys/module/usbcore/parameters/usbfs_memory_mb:

When the cap is too low, the producer cannot queue full-size transfers. It falls back to small ones or drops them, and the symptom is a camera that connects, delivers a few frames, then collapses to a crawl with transfer errors in the kernel log. The value to compare against the cap is the sum of your streams, which comes next.

How much usbfs memory one stream needs

Use 1 byte per pixel for 8-bit mono and 3 for RGB. Producers typically queue about 10 request buffers per camera. A 5 MP color camera at 3 bytes per pixel therefore holds 5,000,000 × 3 × 10 ≈ 150 MB of usbfs memory while streaming — the standard checklist estimate for this calculation.

Big mono sensors are the usual stress case on small hosts, and a USB3 area scan camera such as the MV-CS200-10UM is a good example of the class.

At 20 MP in 8-bit mono, one frame is about 20 MB (20,000,000 pixels × 1 byte). A 10-buffer pool puts roughly 200 MB of usbfs memory behind that single camera — over twelve times the kernel's 16 MB starting value, yet still only a tenth of the cap an 8 GB host receives.

Worked example: four 20 MP mono cameras on two hosts

Inputs: four cameras at 20 MP each, 8-bit mono at 1 byte per pixel, a 10-buffer pool per camera, one process owning all four. The hosts: a workstation with 8 GB of RAM and an embedded controller with 2 GB.

Rule: total need = cameras × pixels × bytes per pixel × buffers, and it must sit under the driver's cap of RAM ÷ 4 with room to spare.

The arithmetic, written out:

• Per camera: 20,000,000 × 1 × 10 = 200 MB.
• Four cameras: 4 × 200 MB = 800 MB.
• 8 GB host: cap = 8192 ÷ 4 = 2048 MB. The 800 MB need is 39% of the cap — change nothing.
• 2 GB host: cap = 2048 ÷ 4 = 512 MB. The need exceeds the cap by 288 MB — act before the first launch.

On the 2 GB host, pick one of two fixes:

1. Raise the cap. 800 MB × 1.25 = 1000 MB, so write 1000 to usbfs_memory_mb (the command is below). The stream then fills 80% of the cap — acceptable, with no fifth camera added later.
2. Trim the buffer pool to 5 per camera: 4 × 100 MB = 400 MB, under the 512 MB cap without touching the kernel.

Decision: at 8 GB and up to four 20 MP cameras, the automatic value holds. Below 4 GB, or beyond four high-resolution cameras, run this sum before you order the host — it sizes the RAM as surely as the frame rate does.

File handles: about ten per camera against 1024

Each USB3 Vision camera costs fewer than about 10 file descriptors: the libusb device nodes, event pipes, and the producer's own handles. The soft limit is 1024 per process by default, so a twelve-camera rig spends about 120 descriptors — 12% of the budget. Run many cameras on Linux and the practical problems are elsewhere, such as device path conflicts between identical USB cameras, not the handle count.

The limit earns attention when the same process does more than cameras. Image logging that opens a file per frame, model files, GUI sockets and database connections all draw from the same 1024. Count what you actually hold while every camera streams:

ls /proc/$(pidof your_vision_process)/fd | wc -l

Under a quarter of the soft cap, leave it alone. Above that, raise it: ulimit -Sn 4096 in the shell that launches the process, a line in /etc/security/limits.conf to make it survive login, LimitNOFILE in the unit file for a systemd vision service, or the nofile ulimit (soft:hard) on the container run command.

When the automatic values are wrong

The quarter-RAM rule fails in four recognizable situations:

1. Small embedded hosts. On 1 to 2 GB of RAM the cap is 256 to 512 MB. One 20 MP camera at 200 MB fits; three do not. The GigE side has its own analogue in socket buffer sizing, and it bites the same hosts — see GigE camera buffer timeouts on embedded Linux.
2. Dense high-resolution rigs. Six 20 MP cameras need 1200 MB of usbfs memory no matter the handle count: it fits an 8 GB host (2048 MB cap), never a 4 GB host (1024 MB cap).
3. Heavy in-process file traffic. Frame logging plus cameras in one process is the common way to climb toward 1024 handles.
4. Constrained virtual machines and containers. A VM sees only the RAM it was given and a container carries its own descriptor caps — the same arithmetic with lower ceilings, as in squeezing services and limits into a small Linux VM.

Compact builds pair 6 MP board-level models like the MV-CB060-10UM-B with 12 MP USB3 heads like the MV-CH120-11UC:

The commands, if you need them

Read the current cap and the host RAM first:

cat /sys/module/usbcore/parameters/usbfs_memory_mb
free -m

Set the cap at run time, with the value in megabytes:

sudo sh -c 'echo 1000 > /sys/module/usbcore/parameters/usbfs_memory_mb'

The write lasts until reboot, and it overrides the producer's automatic value only until the driver re-applies its own at the next camera start. Treat a manual write as the fix for producers that do not raise the cap themselves; for a value that survives boot, add usbcore.usbfs_memory_mb=1000 to the kernel command line. For handles, ulimit -Sn 4096 covers the current shell, while limits.conf and the service unit's LimitNOFILE setting cover the persistent cases.

The five-minute verification checklist

1. free -g — note total RAM; one quarter of it is the cap the driver should write.
2. Start your vision software and stream once, then cat /sys/module/usbcore/parameters/usbfs_memory_mb. A value near RAM ÷ 4 confirms the producer manages it; a 16 after streaming means it does not — set the cap by hand.
3. ulimit -Sn from the owning service or shell — expect 1024 or better.
4. ls /proc/$(pidof your_vision_process)/fd | wc -l with every camera streaming — below a quarter of the soft cap, you are done.
5. dmesg | tail after ten minutes of streaming — no USB transfer errors.

All five pass and the cameras hold their rated frame rate: change nothing. On current software that is the common case.

When tuning is not the fix

If every check passes and frames still drop, work this list in order:

1. Exposure. A frame cannot arrive faster than its exposure allows, and a long shutter caps frame rate regardless of any limit. The diagnosis for a USB3 camera that runs slow starts there, not in the kernel.
2. Bus bandwidth. USB 3.0 bulk traffic shares roughly 400 to 450 MB/s per controller after encoding overhead. Four 20 MB frames at 5 fps is 400 MB/s — one controller is full. Put cameras on separate controllers, or crop the region of interest at the source so each frame carries fewer bytes.
3. Signal integrity. Retries after long or moving cable runs behave like low limits from the software's seat; the pattern and its fixes are in USB3 Vision transfer errors: bandwidth and buffers. Keep runs short and use drag-chain rated USB3 camera cable on moving heads.

For a moving head, a 3 m high-flex USB3.0 cable such as the LS-CBL-0219 is built for drag-chain duty:

Before you order, run the sum from the worked example against the host you plan to use and give the cap 20% headroom. Then pick parts in the USB3 camera finder or among board-level cameras, or let the system configurator walk camera, cable and controller in order. If the arithmetic lands on a host you already own, send the rig details to our applications team and we will size the limits with you.