Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de>
32.1. Terminology¶
IP Security Cameras. At uniview tec, we offer an extensive range of IP Security cameras to dealers and distributors at wholesale prices. The wide range includes Bullet, Turret, PTZ, Panoramic and Vandal Dome Cameras. Uniview tec IP surveillance cameras make it possible. The soc-camera subsystem initially provided a unified API between camera host drivers and camera sensor drivers. Later the soc-camera sensor API has been replaced with the V4L2 standard subdev API. This also made camera driver re-use with non-soc-camera hosts possible. The camera host API to the soc-camera core has been preserved.
- camera / camera device / camera sensor - a video-camera sensor chip, capableof connecting to a variety of systems and interfaces, typically uses i2c forcontrol and configuration, and a parallel or a serial bus for data.
- camera host - an interface, to which a camera is connected. Typically aspecialised interface, present on many SoCs, e.g. PXA27x and PXA3xx, SuperH,i.MX27, i.MX31.
- camera host bus - a connection between a camera host and a camera. Can beparallel or serial, consists of data and control lines, e.g. clock, verticaland horizontal synchronization signals.
32.2. Purpose of the soc-camera subsystem¶
The soc-camera subsystem initially provided a unified API between camera hostdrivers and camera sensor drivers. Later the soc-camera sensor API has beenreplaced with the V4L2 standard subdev API. This also made camera driver re-usewith non-soc-camera hosts possible. The camera host API to the soc-camera corehas been preserved.
Soc-camera implements a V4L2 interface to the user, currently only the “mmap”method is supported by host drivers. However, the soc-camera core also providessupport for the “read” method.
The subsystem has been designed to support multiple camera host interfaces andmultiple cameras per interface, although most applications have only one camerasensor.
32.3. Existing drivers¶
As of 3.7 there are seven host drivers in the mainline: atmel-isi.c,mx1_camera.c (broken, scheduled for removal), mx2_camera.c, mx3_camera.c,omap1_camera.c, pxa_camera.c, sh_mobile_ceu_camera.c, and multiple sensordrivers under drivers/media/i2c/soc_camera/.
32.4. Camera host API¶
A host camera driver is registered using the
function. The host object can be initialized as follows:
All camera host methods are passed in a struct soc_camera_host_ops:
.add and .remove methods are called when a sensor is attached to or detachedfrom the host. .set_bus_param is used to configure physical connectionparameters between the host and the sensor. .init_videobuf2 is called bysoc-camera core when a video-device is opened, the host driver would typicallycall vb2_queue_init() in this method. Further video-buffer management isimplemented completely by the specific camera host driver. If the host driversupports non-standard pixel format conversion, it should implement a.get_formats and, possibly, a .put_formats operations. See below for moredetails about format conversion. The rest of the methods are called fromrespective V4L2 operations.
32.5. Camera API¶
Sensor drivers can use struct soc_camera_link, typically provided by theplatform, and used to specify to which camera host bus the sensor is connected,and optionally provide platform .power and .reset methods for the camera. Thisstruct is provided to the camera driver via the I2C client device platform dataand can be obtained, using the soc_camera_i2c_to_link() macro. Care should betaken, when using soc_camera_vdev_to_subdev() and when accessing structsoc_camera_device, using v4l2_get_subdev_hostdata(): both only work, whenrunning on an soc-camera host. The actual camera driver operation is implementedusing the V4L2 subdev API. Additionally soc-camera camera drivers can useauxiliary soc-camera helper functions like soc_camera_power_on() andsoc_camera_power_off(), which switch regulators, provided by the platform and callboard-specific power switching methods. soc_camera_apply_board_flags() takescamera bus configuration capability flags and applies any board transformations,e.g. signal polarity inversion. soc_mbus_get_fmtdesc() can be used to obtain apixel format descriptor, corresponding to a certain media-bus pixel format code.soc_camera_limit_side() can be used to restrict beginning and length of a frameside, based on camera capabilities.
32.6. VIDIOC_S_CROP and VIDIOC_S_FMT behaviour¶
Above user ioctls modify image geometry as follows:
VIDIOC_S_CROP: sets location and sizes of the sensor window. Unit is one sensorpixel. Changing sensor window sizes preserves any scaling factors, thereforeuser window sizes change as well.
VIDIOC_S_FMT: sets user window. Should preserve previously set sensor window asmuch as possible by modifying scaling factors. If the sensor window cannot bepreserved precisely, it may be changed too.
In soc-camera there are two locations, where scaling and cropping can takeplace: in the camera driver and in the host driver. User ioctls are first passedto the host driver, which then generally passes them down to the camera driver.It is more efficient to perform scaling and cropping in the camera driver tosave camera bus bandwidth and maximise the framerate. However, if the cameradriver failed to set the required parameters with sufficient precision, the hostdriver may decide to also use its own scaling and cropping to fulfill the user’srequest.
Camera drivers are interfaced to the soc-camera core and to host drivers overthe v4l2-subdev API, which is completely functional, it doesn’t pass any data.Therefore all camera drivers shall reply to .g_fmt() requests with their currentoutput geometry. This is necessary to correctly configure the camera bus..s_fmt() and .try_fmt() have to be implemented too. Sensor window and scalingfactors have to be maintained by camera drivers internally. According to theV4L2 API all capture drivers must support the VIDIOC_CROPCAP ioctl, hence werely on camera drivers implementing .cropcap(). If the camera driver does notsupport cropping, it may choose to not implement .s_crop(), but to enablecropping support by the camera host driver at least the .g_crop method must beimplemented.
User window geometry is kept in .user_width and .user_height fields in structsoc_camera_device and used by the soc-camera core and host drivers. The coreupdates these fields upon successful completion of a .s_fmt() call, but if thesefields change elsewhere, e.g. during .s_crop() processing, the host driver isresponsible for updating them.
32.7. Format conversion¶
V4L2 distinguishes between pixel formats, as they are stored in memory, and asthey are transferred over a media bus. Soc-camera provides support toconveniently manage these formats. A table of standard transformations ismaintained by soc-camera core, which describes, what FOURCC pixel format willbe obtained, if a media-bus pixel format is stored in memory according tocertain rules. E.g. if MEDIA_BUS_FMT_YUYV8_2X8 data is sampled with 8 bits persample and stored in memory in the little-endian order with no gaps betweenbytes, data in memory will represent the V4L2_PIX_FMT_YUYV FOURCC format. Thesestandard transformations will be used by soc-camera or by camera host drivers toconfigure camera drivers to produce the FOURCC format, requested by the user,using the VIDIOC_S_FMT ioctl(). Apart from those standard format conversions,host drivers can also provide their own conversion rules by implementing a.get_formats and, if required, a .put_formats methods.
-->This topic provides info about supporting internal cameras on systems in Windows 8.1. It describes how to identify the physical location of built-in cameras so that they work correctly with UWP apps. It also describes how to set the Model ID so that the camera works with UWP device apps. To learn more about UWP device apps in general, see Meet UWP device apps.
Providing physical location
Systems with built-in cameras with mechanically fixed direction must report the physical location of the cameras. This physical location info indicates which direction the camera is facing, such as front or back, so that apps for using the camera in Windows 8.1 function correctly.
The following two Windows Hardware Certification Requirements, which allow Windows to recognize a camera’s location, are required:
System.Client.PCContainer.PCAppearsAsSingleObject. The camera must be grouped into the computer’s device container, which contains the device functions located physically inside the computer. A camera must be grouped into the computer’s device container to expose its physical location to apps, because devices external to the computer container aren’t assumed to have a mechanically fixed direction.
System.Client.Webcam.PhysicalLocation. The firmware must provide physical location info, by using the _PLD information in ACPI tables to indicate the location and orientation of the camera.
Why Windows requires the physical location cameras
Windows needs to know the physical location of internal cameras for the following reasons:
- UWP apps use the physical location to determine which camera to use if multiple cameras are present. For example, a chat application will default to using the front camera that faces the user when the app starts up.
- UWP apps use the physical location to determine how to mirror or rotate the video preview.
- If the camera is facing the user, the preview should look as if the user is looking into a mirror. To do this, the app will flip the left and right sides of the preview, so that the preview mirrors the video. If the camera is facing away from the user, the app does not need to mirror the video.
- If the app rotates the preview, the degree of rotation differs depending on the position of the camera.
How to group the camera into the computers device container
In accordance with certification requirement System.Client.PCContainer.PCAppearsAsSingleObject, also known as SYSFUND-0200, the internal camera device nodes must be grouped under the PC device container. In other words, the internal camera should not be displayed in Devices and Printers and must be consolidated into the PC container.
The way to implement this requirement depends on the bus type of the internal camera. If the device can expose information on the physical device location in ACPI tables, the correct grouping can be specified in the ACPI layer by including _PLD information in the tables and modifying the UserVisible flag in the ACPI table, as described in Multifunction Device Support and Device Container Groupings. Otherwise, override the removable flag by using the DeviceOverrides registry key. For more info, see DeviceOverrides Registry Key.
How to provide physical location using _PLD info in the ACPI table
In accordance with certification requirement System.Client.Webcam.PhysicalLocation, the _PLD value that indicates the camera’s location must be provided in the ACPI (Advanced Configuration and Power Interface) table. This applies to any camera device that is built into the chassis of the system and has mechanically fixed direction. The firmware must provide the _PLD method and set the Panel field (bits[69:67]) to the appropriate value for the panel on which the camera is mounted. For example, Front indicates the camera faces the user (webcam), while Back indicates that the camera faces away from the end user (still or video camera).
| Value of bits [69:67] | Panel |
|---|---|
| 0 | Top |
| 1 | Bottom |
| 2 | Left |
| 3 | Right |
| 4 | Front |
| 5 | Back |
| 6 | Unknown |
In addition, bit 143:128 (Vertical Offset), and bits 159:144 (Horizontal Offset) must provide the relative location of the camera with respect to the display. This origin is relative to the native pixel addressing in the display component and should match the present display orientation of landscape or portrait. The origin is the lower left hand corner of the display, where positive Horizontal and Vertical Offset values are to the right and up, respectively.
For a USB-connected internal camera, the device node for the USB device would be created in the ACPI table under a USB Port device node.
To specify the address (_ADR):
- Install Windows to the target PC
- Go to Device Manager
- Select and hold (or right-click) your target webcam and select Properties
- Open the Details tab and select Address in the Property menu
- The value in the Value box is the address that your device is located at
- Set the value in _ADR in the ACPI table
- Set the _PLD value based on the ACPI spec and the design of PC
This example is an ACPI table for a USB-connected camera. In this example, the value is 0x1. The ninth byte contains the panel code for the location (bits[69:67]). Note that if the device is a USB composite device, PLD must be on the video FUNCTION. This means an additional Device() entry would be needed.
Refer to the ACPI specification for more detailed information for _PLD.
For nodes downstream of USBCCGP, the address value is calculated by adding the port number to the first interface number of the camera function. If USBCCGP isn’t loaded for the device, then the address is simply the port number. If you need to predict the address number without installing Windows, please use this formula to calculate it. If the target device is a single function device (without using the USB composite style device), the address value is calculated using only the port number.
Providing Model ID
The Windows device metadata system is able to query for an internally embedded camera’s device metadata package only if the camera’s device node has a Model ID property and the device category is Imaging.Webcam. To make an internal camera’s metadata discoverable by Windows so that the device metadata package is correctly associated with the device and the camera-specific UWP device app, an OEM needs to do the following:
- Set the Model ID in the device node, by using the
InternalDeviceModificationflag in the device registry key
How to set the Model ID for the internal camera's device node
For internal cameras, the OEM creates a GUID to use for the Model ID and creates a registry key for it. The Model ID property is added to the device node by using the InternalDeviceModification mechanism, which is a registry-based lookup table (LUT) that consists of registry keys that map to specific devices. This InternalDeviceModification table is maintained under the following registry key:
HKEY_LOCAL_MACHINESYSTEMCurrentControlSetControlInternalDeviceModification
The subkey entry to create under the InternalDeviceModification registry key is the OEM-supplied GUID for ModelID. The presence of this key adds the Model ID to the camera’s device node, based on the device hardware ID and the location information indicated by the _PLD value in the ACPI table.
Cached
InternalDeviceModification registry key
The InternalDeviceModification registry key indicates that at least one camera uses the ModelID.
| Registry key name | InternalDeviceModification |
|---|---|
| Required/optional | Required |
| Path | HKEY_LOCAL_MACHINESYSTEMCurrentControlSetControl |
| Format requirements | None |
| Valid subkeys | Model ID registry key (see the following subkey format requirements and examples) |
Model ID registry key
| Registry key name | Model ID (exact model ID value is the key name) |
|---|---|
| Required/optional | Required |
| Format requirements | The key name is a GUID created by the OEM. It must have both opening and closing brackets. |
| Valid values | Hardware ID registry values or PLD_Panel |
| Examples | {43922620-DAD9-4C05-BE3F-F65B089D84D8} |
Hardware ID registry value
| Registry value name | HardwareIDs |
|---|---|
| Required/optional | Required |
| Type | Multi-string |
| Format requirements | Must include the bus prefix of the Hardware ID. All ' characters must be replaced with a '#'. |
| Examples | USB#VID_1234&PID_ABCD&REV_0001PCI#VEN_ABCD&DEV_1234&SUBSYS_000 |
| Comment | Multiple hardware ID values can be provided. When any of the hardware IDs occur in the list more than once, the system sets the Model ID of the device node based on the hardware ID. |
PLD_Panel registry value
| Registry value name | PLD_Panel |
|---|---|
| Required/optional | Optional |
| Type | DWORD |
| Format requirements | Must include the bus prefix of the HardwareID. All ' characters must be replaced with a '#'. |
| Examples | 4,5 |
PLD_Panel Details
The PLD_Panel value provided in ACPI tables enables cameras to be distinguished from each other when a system has two identical camera devices and both have identical hardware IDs. To create different Model IDs, the combination of hardware IDs and PLD_Panel value is used.
Drivers Sysnucleus Cameras Review
Note The PLD_Panel setting in the registry key is optional. Windows determines the camera’s physical location by the settings in the ACPI table.
The PLD_Panel registry value is defined as _PLD (Physical Device Location) in the ACPI specification. This value, which indicates the camera’s physical location in its enclosure, must be one of the following.
| Value | Description |
|---|---|
| 0 | Top |
| 1 | Bottom |
| 2 | Left |
| 3 | Right |
| 4 | Front |
| 5 | Back |
| 6 | Unknown (Vertical position and Horizontal position will be ignored) |
InternalDeviceModification registry key examples
The following examples demonstrate the format of the InternalDeviceModification registry key.
Metadata structure
The device metadata package for an internal camera has the same structure as the device metadata package for any other device. The MetadataKey in packageinfo.xml within the device metadata package is the Model ID defined by using the InternalDeviceModification registry key. The Windows metadata system downloads the device metadata package based on the Model ID. The hardware ID of the internal camera is not used.
For more info about creating device metadata for your UWP device app, see Building UWP device apps.
Pre-installation
Drivers Sysnucleus Cameras App
Both the Microsoft Store device app and the device metadata package can be preinstalled on the device using the OEM Preinstallation Kit (OPK).