Add README for V4L2 Camera HAL
Change-Id: Ic4038d471b79685ee6139bfb4613aa5b87b03e72
diff --git a/modules/camera/3_4/README.md b/modules/camera/3_4/README.md
new file mode 100644
index 0000000..73d0c13
--- /dev/null
+++ b/modules/camera/3_4/README.md
@@ -0,0 +1,151 @@
+# V4L2 Camera HALv3
+
+The camera.v4l2 library implements a Camera HALv3 using the
+Video For Linux 2 (V4L2) interface. This allows it to theoretically
+work with a wide variety of devices, though the limitations of V4L2
+introduce some [caveats](#V4L2-Deficiencies), causing this HAL to
+not be fully spec-compliant.
+
+## Building a Device with the HAL
+
+To ensure the HAL is built for a device, include the following in your
+`<device>.mk`:
+
+```
+USE_CAMERA_V4L2_HAL := true
+PRODUCT_PACKAGES += camera.v4l2
+PRODUCT_PROPERTY_OVERRIDES += ro.hardware.camera=v4l2
+```
+
+The first line ensures the V4L2 HAL module is visible to the build system.
+This prevents checkbuilds on devices that don't have the necessary support
+from failing. The product packages tells the build system to include the V4L2
+HALv3 library in the system image. The final line tells the hardware manager
+to load the V4L2 HAL instead of a default Camera HAL.
+
+## Requirements for Using the HAL
+
+Devices and cameras wishing to use this HAL must meet
+the following requirements:
+
+* The camera must support BGR32, YUV420, and JPEG formats.
+* The gralloc and other graphics modules used by the device must use
+`HAL_PIXEL_FORMAT_RGBA_8888` as the `HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED`
+
+## Understanding the HAL Code
+
+There are three large pieces to the V4L2 Camera HAL: the general HALv3
+Camera & HAL code, the specific implementation using V4L2,
+and the Metadata system.
+
+For context, you may also wish to read some of the documentation in
+libhardware/include/camera3.h about how the framework interacts with the HAL.
+
+### Camera & HAL Interface
+
+The camera and HAL interfaces are implemented by the Camera and
+V4L2CameraHAL classes.
+
+The V4L2CameraHAL class deals primarily with initialization of the system.
+On creation, it searches /dev/video* nodes for ones with the necessary
+capabilities. These are then all presented to the framework as available
+for use. Further operations are passed to the individual Cameras as appropriate.
+
+The Camera class implements the general logic for handling the camera -
+opening and closing, configuring streams, preparing and tracking requests, etc.
+While it handles the logistics surrounding the camera, actual image
+capture and settings logic are implemented by calling down into the
+[V4L2 Camera](#V4L2-Camera). The Camera (using helper classes) enforces
+restrictions given in the [Metadata](#Metadata) initialized by the V4L2Camera,
+such as limits on the number of in-flight requests per stream.
+Notably, this means you should be able to replace the V4L2 implementation
+with something else, and as long as you fill in the metadata correctly the
+Camera class should "just work".
+
+### V4L2 Specific Implementation
+
+The V4L2Camera class is the implementation of all the capture functionality.
+It includes some methods for the Camera class to verify the setup, but the
+bulk of the class is the request queue. The Camera class submits CaptureRequests
+as they come in and are verified. The V4L2Camera runs these through a three
+stage asynchronous pipeline:
+
+* Acceptance: the V4L2Camera accepts the request, and puts it into waiting to be
+picked up by the enqueuer.
+* Enqueuing: the V4L2Camera reads the request settings, applies them to the
+device, takes a snapshot of the settings, and hands the buffer over to the
+V4L2 driver.
+* Dequeueing: A completed frame is reclaimed from the driver, and sent
+back to the Camera class for final processing (validation, filling in the
+result object, and sending the data back to the framework).
+
+Much of this work is aided by the V4L2Wrapper helper class,
+which provides simpler inputs and outputs around the V4L2 ioctls
+based on their known use by the HAL; filling in common values automatically
+and extracting the information useful to the HAL from the results.
+This wrapper is also used to expose V4L2 controls to their corresponding
+Metadata components.
+
+### Metadata
+
+The Metadata subsystem attempts to organize and simplify handling of
+camera metadata (system/media/camera/docs/docs.html). At the top level
+is the Metadata class and the PartialMetadataInterface. The Metadata
+class provides high level interaction with the individual components -
+filling the static metadata, validating, getting, and setting settings,
+etc. The Metadata class passes all of these things on to the component
+PartialMetadataInterfaces, each of which filter for their specific
+metadata components and perform the requested task.
+
+Some generalized metadata classes are provided to simplify common logic
+for this filtering and application. At a high level, there are three
+types:
+
+* Properties: a static value.
+* Controls: dynamically adjustable values, and optionally an
+associated static property indicating what allowable values are.
+* States: a dynamic read-only value.
+
+The Metadata system uses further interfaces and subclasses to distinguish
+the variety of different functionalities necessary for different metadata
+tags.
+
+#### Metadata Factory
+
+This V4L2 Camera HAL implementation utilizes a metadata factory method.
+This method initializes all the 100+ required metadata components for
+basic HAL spec compliance. Most do nothing/report fixed values,
+but a few are hooked up to the V4L2 driver.
+
+This HAL was initially designed for use with the Raspberry Pi camera module
+v2.1, so the fixed defaults are usually assigned based on that camera.
+
+## V4L2 Deficiencies
+
+* One stream at a time is supported. Notably, this means you must re-configure
+the stream between preview and capture if they're not the same format.
+This makes this HAL not backwards compatible with the Android Camera (v1) API
+as many of its methods attempt to do just that; Camera2 must be used instead.
+* A variety of metadata properties can't be filled in from V4L2,
+such as physical properties of the camera. Thus this HAL will never be capable
+of providing perfectly accurate information for all cameras it can theoretically
+support.
+* Android requires HALs support YUV420, JPEG, and a format of the graphics
+stack's choice ("implementation defined"). Very few cameras actually support
+all of these formats (so far the Raspberry Pi cameras are the only known ones),
+so some form of format conversion built in to the HAL would be a useful feature
+to expand the reach/usefulness of this HAL.
+* V4L2 doesn't make promises about how fast settings will apply, and there's no
+good way to determine what settings were in effect for a given frame. Thus,
+the settings passed into requests and out with results are applied/read as
+a best effort and may be incorrect.
+* Many features V4L2 is capable of are not hooked up to the HAL, so the HAL
+is underfeatured compared to the ideal/what is possible.
+
+## Other Known Issues
+
+* A variety of features are unimplemented: High speed capture,
+flash torch mode, hotplugging/unplugging.
+* The HAL uses BGR for RGBA. Again, the HAL was designed for the Raspberry Pi
+camera, which doesn't support RGB, but RGB is a common default format for
+graphics stacks.