MIPI CSI device link failed: fix the camera node graph

The kernel reports your camera is present, then refuses to give it a capture node. At boot you get a pair of lines — the sensor subdevice bound, followed by "Failed to create device link (0x180)" — and no /dev/video node for that camera appears afterwards. This guide is for engineers bringing up a MIPI CSI or GMSL camera on an embedded board where you control, or can request, the device tree. You will read the two log lines to pin the failing stage, find the broken endpoint in the camera graph, fix the remote-endpoint and data-lanes pairs, and prove the result with media-ctl and a captured frame. If the sensor never binds at all, start instead with sensor probes but no video node: fix the devicetree chain.

What the error means

The two log lines describe two different planes. The "subdev ... bound" line is the control plane: the receiver's driver found the sensor on its I2C bus, matched it to a device-tree node, and registered it as a V4L2 subdevice. Power, reset and the bus path are proven. The "Failed to create device link" line is the data plane: the receiver asks the kernel to order the sensor behind itself for power management and streaming, and to build that relationship it walks the device-tree graph of ports, endpoints and remote-endpoint references.

When that walk cannot connect the sensor's endpoint to the receiver's endpoint, the request is refused and the capture video device is never registered. The media controller core returns an error, not zero, when device node registration fails, which is exactly why you see a bound subdevice and no capture node at the same time. It is the graph-level face of a camera that enumerates but sends no data; the runtime face is covered in camera detected but no image data: separate control from data links.

The graph the receiver walks

A camera connection in the device tree has three nested levels. The camera node carries its I2C address in reg. A port inside it, such as port@0, describes one physical connection. An endpoint inside the port describes the electrical details of that connection, and the two properties a receiver binding will not parse without are remote-endpoint and data-lanes.

/* illustrative fragment: labels and addresses are your own */
sensor@21 {
	reg = <0x21>;
	port@0 {
		sensor_out: endpoint {
			remote-endpoint = <&csi_in0>;
			data-lanes = <1 2 3 4>;
		};
	};
};

The receiving side carries the mirror image: its endpoint's remote-endpoint points back at sensor_out, and its data-lanes lists the same lanes. Endpoints come in pairs, and each pair holds two references. Point a remote-endpoint at a device node instead of at the other endpoint, leave one side out, or disagree on the lane count, and the pair is not a link.

Causes in order of probability

1. The sensor endpoint does not point back. After a camera include is ported from a reference board, the sensor's remote-endpoint is missing or still names the previous CSI node. Test: print the topology with media-ctl -p -d /dev/media0; a receiver sink pad with no link means no counterpart endpoint was found.
2. The receiver endpoint is missing or swapped. A CSI node exposes endpoint@0 and endpoint@1 for its two inputs, and the camera must sit on the index the driver expects; a reference aimed at the other index connects to nothing. Test: read the CSI node's endpoints in the include and match every phandle in both directions.
3. data-lanes is missing or the counts disagree. A four-lane sensor feeding an endpoint that lists two lanes is a broken pair even when both remote-endpoint properties exist. Test: same count, same order, on both ends — <1 2 3 4> against <1 2 3 4>. What a lane count can carry is worked through in MIPI CSI-2 frame rate estimation: lanes and data rate.
4. A GMSL hop is not described. A GMSL chain is sensor → serializer → deserializer → CSI receiver → capture, and every arrow is an endpoint pair. A missing deserializer port leaves the sensor bound on I2C with no data path to walk. Test: count the arrows described in the include against the chain; the parser-side symptoms of a half-described port are in GMSL camera fail to parse port info: fix the sensor port bindings.
5. The tree you edited is not the tree running. A bootloader overlay can override your camera include, so the endpoints you fixed never load. Test: follow MIPI camera device tree overlay not applied: verify what UEFI loaded and confirm the live tree before doubting your endpoints.

Fix it step by step

1. Print the topology: media-ctl -p -d /dev/media0. Note the sensor entity name and every sink pad on the CSI receiver entity.
2. Write the chain on paper: sensor → serializer → deserializer → CSI receiver → capture, or sensor → CSI receiver → capture for a plain MIPI module. One arrow, one endpoint pair.
3. Open the camera include and the CSI node side by side. For every arrow, confirm both endpoints exist and each remote-endpoint names the other endpoint — never the parent device node.
4. Match the address: the sensor node's reg must equal the address inside the bound-subdevice name, and the node must sit under the I2C controller that owns that adapter number.
5. Make the lane lists identical on both ends of the sensor-facing pair — same count, same order.
6. Rebuild and apply: recompile the device tree or reapply the overlay, reboot, and grep the boot log for "Failed to create device link".
7. Prove it: v4l2-ctl --list-devices shows the new capture node, media-ctl -p shows the link into the receiver's sink pad, and one frame captures cleanly. The full sensor-to-host path is walked in MIPI CSI-2 image capture pipeline: sensor to host step by step.

Worked example: tracing the failed link for subdevice 9-0021

Inputs, from a real GMSL bring-up on a custom board: a bound line at 13.935260 s reading "subdev sensor 9-0021 bound", a failure line at 13.953401 s reading "Failed to create device link (0x180) with 9-0021", and a four-hop GMSL chain. The rule in words: decode the subdevice name into bus and address, measure how close the two lines are, and count the references the chain needs.

• Name decode: 9-0021 means I2C adapter 9, 7-bit address 0x21. In decimal, 0x21 = 2 × 16 + 1 = 33, so the sensor node needs reg = 0x21 under the controller owning adapter 9.
• Timing: 13.953401 - 13.935260 = 0.018141 s, about 18 ms. The receiver attempted the link immediately after the sensor bound — the normal sequence, not a race.
• Chain length: 4 hops × 2 references per pair = 8 remote-endpoint references that must all exist and agree.

Decision: the bound line proves the control plane, so the fault is inside those 8 references. When the two log lines land within roughly 100 ms of each other, commit to the graph — print the topology and repair the endpoint whose counterpart is missing. When the bound line is absent altogether, stop; that is a power or I2C fault, and the page you want is MIPI camera not detected: I2C bus and device tree checks. Treat 0x180 as part of the message signature; the token that names the fault is the subdevice identifier printed beside it.

When the graph is not yours to fix

If the board support package is an early-access release that is not public, the driver's graph parsing can change between drops, and the binding your device tree follows may be older than the driver that parses it. The legitimate route for that case is the vendor's support channel for the release: quote both log lines and your camera include, and keep your device-tree diff minimal so the case reproduces cleanly. Do not fork the driver to silence the message — that link keeps power and streaming ordered, and removing the check buys a hang later.

The second route sidesteps the graph. USB3 and GigE cameras enumerate themselves as standard host devices: no ports, no endpoints, no capture node tied to a device tree, and your code opens them through the host stack. That is why they dominate first bring-up on custom boards.

The LS-BCM-0003 is a 3.1 MP USB3 board-level camera with a global shutter. The MV-CB016-10GM-M-W is a 1.6 MP GigE board-level camera with an M12 lens mount. On the host side, the MV-GE2002P is a dual-port PoE NIC, and the LS-CBL-0199 is a 3 m high-flex GigE camera cable built for drag-chain use.

Compare modules in board-level cameras, host cards in frame grabbers and interconnects in cables, or run the board camera evaluation checklist before you commit. The camera finder filters modules by interface and lens mount.

When the usual answer is wrong

• The capture node appears, but stream start fails with Invalid argument, errno -22. The graph is fine; the format negotiation is not. Set the frame size on the sensor subdevice — typically /dev/v4l-subdev0 — before starting the capture node, because the controls live on the subdevice.
• The node appears, streams, then times out after minutes or hours. That is a cable and signal-integrity class of failure, not a graph fault: read CSI camera timeout after a working period.
• The endpoints are correct and the message survives two boards. The device tree follows a binding revision the driver in your build no longer accepts. Take both log lines to the vendor channel; a driver-side expectation moved, not your wiring.

Checklist before you close the ticket

• Every endpoint pair references each other, endpoint to endpoint.
• data-lanes lists the same lanes in the same order on both ends of the sensor-facing pair.
• Every hop — sensor, serializer, deserializer, receiver, capture — has its port described.
• The sensor node's reg equals the address inside the bound-subdevice line.
• media-ctl -p shows the link into the receiver's sink pad.
• One frame captured in your software, then a second boot to prove the fix survives restart.

To plan the whole station in one pass, start at the camera step of the system configurator. For a vendor case on a non-public release, we can help you package the two log lines through the contact page.