Commit | Line | Data |
---|---|---|
176fb0d1 LP |
1 | Linux kernel media framework |
2 | ============================ | |
3 | ||
4 | This document describes the Linux kernel media framework, its data structures, | |
5 | functions and their usage. | |
6 | ||
7 | ||
8 | Introduction | |
9 | ------------ | |
10 | ||
11 | The media controller API is documented in DocBook format in | |
12 | Documentation/DocBook/v4l/media-controller.xml. This document will focus on | |
13 | the kernel-side implementation of the media framework. | |
14 | ||
15 | ||
16 | Media device | |
17 | ------------ | |
18 | ||
19 | A media device is represented by a struct media_device instance, defined in | |
20 | include/media/media-device.h. Allocation of the structure is handled by the | |
21 | media device driver, usually by embedding the media_device instance in a | |
22 | larger driver-specific structure. | |
23 | ||
24 | Drivers register media device instances by calling | |
25 | ||
26 | media_device_register(struct media_device *mdev); | |
27 | ||
28 | The caller is responsible for initializing the media_device structure before | |
29 | registration. The following fields must be set: | |
30 | ||
31 | - dev must point to the parent device (usually a pci_dev, usb_interface or | |
32 | platform_device instance). | |
33 | ||
34 | - model must be filled with the device model name as a NUL-terminated UTF-8 | |
35 | string. The device/model revision must not be stored in this field. | |
36 | ||
37 | The following fields are optional: | |
38 | ||
39 | - serial is a unique serial number stored as a NUL-terminated ASCII string. | |
40 | The field is big enough to store a GUID in text form. If the hardware | |
41 | doesn't provide a unique serial number this field must be left empty. | |
42 | ||
43 | - bus_info represents the location of the device in the system as a | |
44 | NUL-terminated ASCII string. For PCI/PCIe devices bus_info must be set to | |
45 | "PCI:" (or "PCIe:") followed by the value of pci_name(). For USB devices, | |
46 | the usb_make_path() function must be used. This field is used by | |
47 | applications to distinguish between otherwise identical devices that don't | |
48 | provide a serial number. | |
49 | ||
50 | - hw_revision is the hardware device revision in a driver-specific format. | |
51 | When possible the revision should be formatted with the KERNEL_VERSION | |
52 | macro. | |
53 | ||
54 | - driver_version is formatted with the KERNEL_VERSION macro. The version | |
55 | minor must be incremented when new features are added to the userspace API | |
56 | without breaking binary compatibility. The version major must be | |
57 | incremented when binary compatibility is broken. | |
58 | ||
59 | Upon successful registration a character device named media[0-9]+ is created. | |
60 | The device major and minor numbers are dynamic. The model name is exported as | |
61 | a sysfs attribute. | |
62 | ||
63 | Drivers unregister media device instances by calling | |
64 | ||
65 | media_device_unregister(struct media_device *mdev); | |
66 | ||
67 | Unregistering a media device that hasn't been registered is *NOT* safe. |