projects / GitHub / LineageOS / android_kernel_motorola_exynos9610.git / blame
| 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. |