Add common, media_ctrl and v4l2_ctrl modules with CLI drivers and docs
Modules (src/modules/): - common/error: App_Error struct with structured detail union, error codes, app_error_print(); designed for future upgrade to preprocessor-generated location codes - media_ctrl: media device enumeration, topology query (entities/pads/links), link enable/disable via Media Controller API (/dev/media*) - v4l2_ctrl: control enumeration (with menu item fetching), get/set via V4L2 ext controls API, device discovery (/dev/video*) All modules use -std=c11 -D_GNU_SOURCE, build artifacts go to build/ only. Kernel-version-dependent constants guarded with #ifdef + #warning. CLI drivers (dev/cli/): - media_ctrl_cli: list, info, topology, set-link subcommands - v4l2_ctrl_cli: list, controls, get, set subcommands Docs (docs/cli/): - media_ctrl_cli.md and v4l2_ctrl_cli.md with usage, examples, and context within the video routing system Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
129
docs/cli/media_ctrl_cli.md
Normal file
129
docs/cli/media_ctrl_cli.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# media_ctrl_cli
|
||||
|
||||
A development tool for exploring and configuring the Linux Media Controller pipeline. It wraps the `media_ctrl` module and provides a command-line interface to the Media Controller API (`/dev/media*`).
|
||||
|
||||
This tool is the counterpart to `media-ctl` from the `v4l-utils` package. It covers the same ground but is built on our own `media_ctrl` translation unit.
|
||||
|
||||
---
|
||||
|
||||
## Build
|
||||
|
||||
From the repository root:
|
||||
|
||||
```sh
|
||||
make
|
||||
```
|
||||
|
||||
Or from `dev/cli/` directly:
|
||||
|
||||
```sh
|
||||
make media_ctrl_cli
|
||||
```
|
||||
|
||||
The binary is placed in `dev/cli/`.
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
|
||||
### `list`
|
||||
|
||||
Enumerate all media devices present on the system.
|
||||
|
||||
```sh
|
||||
./media_ctrl_cli list
|
||||
```
|
||||
|
||||
Example output:
|
||||
|
||||
```
|
||||
Media devices:
|
||||
/dev/media0
|
||||
/dev/media1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `info <device>`
|
||||
|
||||
Show identification information for a media device.
|
||||
|
||||
```sh
|
||||
./media_ctrl_cli info /dev/media0
|
||||
```
|
||||
|
||||
Example output:
|
||||
|
||||
```
|
||||
Device: /dev/media0
|
||||
Driver: unicam
|
||||
Model: unicam
|
||||
Serial:
|
||||
Bus info: platform:fe801000.csi
|
||||
Media version: 5.15.0
|
||||
Hardware rev: 0x00000000
|
||||
Driver version: 5.15.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `topology <device>`
|
||||
|
||||
Show the full pipeline topology: all entities, their pads, and all links between them. This is the main tool for understanding how a camera pipeline is structured.
|
||||
|
||||
```sh
|
||||
./media_ctrl_cli topology /dev/media0
|
||||
```
|
||||
|
||||
Example output on a Raspberry Pi with an IMX477 camera:
|
||||
|
||||
```
|
||||
Device: unicam (/dev/media0)
|
||||
|
||||
Entity 1: imx477 4-001a
|
||||
type: v4l2-subdev (0x00020001)
|
||||
flags: 0x00000000
|
||||
pads: 1 links: 1
|
||||
pad 0: source
|
||||
link: entity 1 pad 0 -> entity 2 pad 0 [enabled]
|
||||
|
||||
Entity 2: unicam-image
|
||||
type: devnode (0x00010001)
|
||||
flags: 0x00000000
|
||||
pads: 1 links: 1
|
||||
device: 81:1
|
||||
pad 0: sink
|
||||
link: entity 1 pad 0 -> entity 2 pad 0 [enabled]
|
||||
```
|
||||
|
||||
Each entity shows:
|
||||
- **type** — the kernel entity function code and its human-readable name
|
||||
- **pads** — each pad with its direction (source or sink)
|
||||
- **links** — connections to other entity pads, with enabled/disabled state and whether the link is immutable
|
||||
|
||||
---
|
||||
|
||||
### `set-link <device> <src_entity>:<src_pad> <sink_entity>:<sink_pad> <0|1>`
|
||||
|
||||
Enable or disable a link between two pads. Entity IDs and pad indices are the numeric values shown in the `topology` output.
|
||||
|
||||
```sh
|
||||
# Enable a link
|
||||
./media_ctrl_cli set-link /dev/media0 1:0 2:0 1
|
||||
|
||||
# Disable a link
|
||||
./media_ctrl_cli set-link /dev/media0 1:0 2:0 0
|
||||
```
|
||||
|
||||
Immutable links cannot be changed and will return an error.
|
||||
|
||||
---
|
||||
|
||||
## Relationship to the Video Routing System
|
||||
|
||||
`media_ctrl_cli` exercises the `media_ctrl` module, which is used in the video routing system for:
|
||||
|
||||
- **Remote device enumeration** — a connecting node can query the media topology of a remote host to discover available cameras before opening any streams
|
||||
- **Pipeline configuration** — setting pad formats and enabling links is required before a V4L2 capture node can be used, particularly on platforms like the Raspberry Pi where the sensor and capture node are separate media entities
|
||||
|
||||
See also: [`v4l2_ctrl_cli.md`](v4l2_ctrl_cli.md) for runtime camera parameter control.
|
||||
Reference in New Issue
Block a user