README.md
1 # V4L2 Camera HALv3 2 3 The camera.v4l2 library implements a Camera HALv3 using the 4 Video For Linux 2 (V4L2) interface. This allows it to theoretically 5 work with a wide variety of devices, though the limitations of V4L2 6 introduce some [caveats](#V4L2-Deficiencies), causing this HAL to 7 not be fully spec-compliant. 8 9 ## Building a Device with the HAL 10 11 To ensure the HAL is built for a device, include the following in your 12 `<device>.mk`: 13 14 ``` 15 USE_CAMERA_V4L2_HAL := true 16 PRODUCT_PACKAGES += camera.v4l2 17 PRODUCT_PROPERTY_OVERRIDES += ro.hardware.camera=v4l2 18 ``` 19 20 The first line ensures the V4L2 HAL module is visible to the build system. 21 This prevents checkbuilds on devices that don't have the necessary support 22 from failing. The product packages tells the build system to include the V4L2 23 HALv3 library in the system image. The final line tells the hardware manager 24 to load the V4L2 HAL instead of a default Camera HAL. 25 26 ## Requirements for Using the HAL 27 28 Devices and cameras wishing to use this HAL must meet 29 the following requirements: 30 31 * The camera must support BGR32, YUV420, and JPEG formats. 32 * The gralloc and other graphics modules used by the device must use 33 `HAL_PIXEL_FORMAT_RGBA_8888` as the `HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED` 34 35 ## Understanding the HAL Code 36 37 There are three large pieces to the V4L2 Camera HAL: the general HALv3 38 Camera & HAL code, the specific implementation using V4L2, 39 and the Metadata system. 40 41 For context, you may also wish to read some of the documentation in 42 libhardware/include/camera3.h about how the framework interacts with the HAL. 43 44 ### Camera & HAL Interface 45 46 The camera and HAL interfaces are implemented by the Camera and 47 V4L2CameraHAL classes. 48 49 The V4L2CameraHAL class deals primarily with initialization of the system. 50 On creation, it searches /dev/video* nodes for ones with the necessary 51 capabilities. These are then all presented to the framework as available 52 for use. Further operations are passed to the individual Cameras as appropriate. 53 54 The Camera class implements the general logic for handling the camera - 55 opening and closing, configuring streams, preparing and tracking requests, etc. 56 While it handles the logistics surrounding the camera, actual image 57 capture and settings logic are implemented by calling down into the 58 [V4L2 Camera](#V4L2-Camera). The Camera (using helper classes) enforces 59 restrictions given in the [Metadata](#Metadata) initialized by the V4L2Camera, 60 such as limits on the number of in-flight requests per stream. 61 Notably, this means you should be able to replace the V4L2 implementation 62 with something else, and as long as you fill in the metadata correctly the 63 Camera class should "just work". 64 65 ### V4L2 Specific Implementation 66 67 The V4L2Camera class is the implementation of all the capture functionality. 68 It includes some methods for the Camera class to verify the setup, but the 69 bulk of the class is the request queue. The Camera class submits CaptureRequests 70 as they come in and are verified. The V4L2Camera runs these through a three 71 stage asynchronous pipeline: 72 73 * Acceptance: the V4L2Camera accepts the request, and puts it into waiting to be 74 picked up by the enqueuer. 75 * Enqueuing: the V4L2Camera reads the request settings, applies them to the 76 device, takes a snapshot of the settings, and hands the buffer over to the 77 V4L2 driver. 78 * Dequeueing: A completed frame is reclaimed from the driver, and sent 79 back to the Camera class for final processing (validation, filling in the 80 result object, and sending the data back to the framework). 81 82 Much of this work is aided by the V4L2Wrapper helper class, 83 which provides simpler inputs and outputs around the V4L2 ioctls 84 based on their known use by the HAL; filling in common values automatically 85 and extracting the information useful to the HAL from the results. 86 This wrapper is also used to expose V4L2 controls to their corresponding 87 Metadata components. 88 89 ### Metadata 90 91 The Metadata subsystem attempts to organize and simplify handling of 92 camera metadata (system/media/camera/docs/docs.html). At the top level 93 is the Metadata class and the PartialMetadataInterface. The Metadata 94 class provides high level interaction with the individual components - 95 filling the static metadata, validating, getting, and setting settings, 96 etc. The Metadata class passes all of these things on to the component 97 PartialMetadataInterfaces, each of which filter for their specific 98 metadata components and perform the requested task. 99 100 Some generalized metadata classes are provided to simplify common logic 101 for this filtering and application. At a high level, there are three 102 types: 103 104 * Properties: a static value. 105 * Controls: dynamically adjustable values, and optionally an 106 associated static property indicating what allowable values are. 107 * States: a dynamic read-only value. 108 109 The Metadata system uses further interfaces and subclasses to distinguish 110 the variety of different functionalities necessary for different metadata 111 tags. 112 113 #### Metadata Factory 114 115 This V4L2 Camera HAL implementation utilizes a metadata factory method. 116 This method initializes all the 100+ required metadata components for 117 basic HAL spec compliance. Most do nothing/report fixed values, 118 but a few are hooked up to the V4L2 driver. 119 120 This HAL was initially designed for use with the Raspberry Pi camera module 121 v2.1, so the fixed defaults are usually assigned based on that camera. 122 123 ## V4L2 Deficiencies 124 125 * One stream at a time is supported. Notably, this means you must re-configure 126 the stream between preview and capture if they're not the same format. 127 This makes this HAL not backwards compatible with the Android Camera (v1) API 128 as many of its methods attempt to do just that; Camera2 must be used instead. 129 * A variety of metadata properties can't be filled in from V4L2, 130 such as physical properties of the camera. Thus this HAL will never be capable 131 of providing perfectly accurate information for all cameras it can theoretically 132 support. 133 * Android requires HALs support YUV420, JPEG, and a format of the graphics 134 stack's choice ("implementation defined"). Very few cameras actually support 135 all of these formats (so far the Raspberry Pi cameras are the only known ones), 136 so some form of format conversion built in to the HAL would be a useful feature 137 to expand the reach/usefulness of this HAL. 138 * V4L2 doesn't make promises about how fast settings will apply, and there's no 139 good way to determine what settings were in effect for a given frame. Thus, 140 the settings passed into requests and out with results are applied/read as 141 a best effort and may be incorrect. 142 * Many features V4L2 is capable of are not hooked up to the HAL, so the HAL 143 is underfeatured compared to the ideal/what is possible. 144 145 ## Other Known Issues 146 147 * A variety of features are unimplemented: High speed capture, 148 flash torch mode, hotplugging/unplugging. 149
