diff --git a/camera/docs/CameraMetadataKeys.mako b/camera/docs/CameraMetadataKeys.mako
index f9ce15e..6006c8d 100644
--- a/camera/docs/CameraMetadataKeys.mako
+++ b/camera/docs/CameraMetadataKeys.mako
@@ -52,6 +52,7 @@
   % endif
   % if entry.deprecated:
      * @deprecated
+${entry.deprecation_description | javadoc(metadata)}
   % endif
   % if entry.applied_visibility in ('hidden', 'ndk_public'):
      * @hide
diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 21c9eb4..6719a54 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -517,9 +517,12 @@
             <li
             ><a href="#static_android.lens.intrinsicCalibration">android.lens.intrinsicCalibration</a></li>
             <li
+                class="toc_deprecated"
             ><a href="#static_android.lens.radialDistortion">android.lens.radialDistortion</a></li>
             <li
             ><a href="#static_android.lens.poseReference">android.lens.poseReference</a></li>
+            <li
+            ><a href="#static_android.lens.distortion">android.lens.distortion</a></li>
           </ul>
         </li>
         <li>
@@ -546,7 +549,10 @@
             <li
             ><a href="#dynamic_android.lens.intrinsicCalibration">android.lens.intrinsicCalibration</a></li>
             <li
+                class="toc_deprecated"
             ><a href="#dynamic_android.lens.radialDistortion">android.lens.radialDistortion</a></li>
+            <li
+            ><a href="#dynamic_android.lens.distortion">android.lens.distortion</a></li>
           </ul>
         </li>
       </ul> <!-- toc_section -->
@@ -13531,7 +13537,7 @@
 from the main sensor along the +X axis (to the right from the user's perspective) will
 report <code>(0.<wbr/>03,<wbr/> 0,<wbr/> 0)</code>.<wbr/></p>
 <p>To transform a pixel coordinates between two cameras facing the same direction,<wbr/> first
-the source camera <a href="#static_android.lens.radialDistortion">android.<wbr/>lens.<wbr/>radial<wbr/>Distortion</a> must be corrected for.<wbr/>  Then the source
+the source camera <a href="#static_android.lens.distortion">android.<wbr/>lens.<wbr/>distortion</a> must be corrected for.<wbr/>  Then the source
 camera <a href="#static_android.lens.intrinsicCalibration">android.<wbr/>lens.<wbr/>intrinsic<wbr/>Calibration</a> needs to be applied,<wbr/> followed by the
 <a href="#static_android.lens.poseRotation">android.<wbr/>lens.<wbr/>pose<wbr/>Rotation</a> of the source camera,<wbr/> the translation of the source camera
 relative to the destination camera,<wbr/> the <a href="#static_android.lens.poseRotation">android.<wbr/>lens.<wbr/>pose<wbr/>Rotation</a> of the destination
@@ -13640,7 +13646,7 @@
 where <code>(0,<wbr/>0)</code> is the top-left of the
 preCorrectionActiveArraySize rectangle.<wbr/> Once the pose and
 intrinsic calibration transforms have been applied to a
-world point,<wbr/> then the <a href="#static_android.lens.radialDistortion">android.<wbr/>lens.<wbr/>radial<wbr/>Distortion</a>
+world point,<wbr/> then the <a href="#static_android.lens.distortion">android.<wbr/>lens.<wbr/>distortion</a>
 transform needs to be applied,<wbr/> and the result adjusted to
 be in the <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a> coordinate
 system (where <code>(0,<wbr/> 0)</code> is the top-left of the
@@ -13657,6 +13663,7 @@
                 
           <tr class="entry" id="static_android.lens.radialDistortion">
             <td class="entry_name
+                entry_name_deprecated
              " rowspan="3">
               android.<wbr/>lens.<wbr/>radial<wbr/>Distortion
             </td>
@@ -13671,6 +13678,7 @@
 
 
 
+              <span class="entry_type_deprecated">[deprecated] </span>
 
 
 
@@ -13688,6 +13696,7 @@
             </td>
 
             <td class="entry_range">
+              <p><span class="entry_range_deprecated">Deprecated</span>. Do not use.</p>
             </td>
 
             <td class="entry_hal_version">
@@ -13802,6 +13811,91 @@
           <tr class="entry_spacer"><td class="entry_spacer" colspan="7"></td></tr>
            <!-- end of entry -->
         
+                
+          <tr class="entry" id="static_android.lens.distortion">
+            <td class="entry_name
+             " rowspan="3">
+              android.<wbr/>lens.<wbr/>distortion
+            </td>
+            <td class="entry_type">
+                <span class="entry_type_name">float</span>
+                <span class="entry_type_container">x</span>
+
+                <span class="entry_type_array">
+                  5
+                </span>
+              <span class="entry_type_visibility"> [public]</span>
+
+
+
+
+
+
+            </td> <!-- entry_type -->
+
+            <td class="entry_description">
+              <p>The correction coefficients to correct for this camera device's
+radial and tangential lens distortion.<wbr/></p>
+<p>Replaces the deprecated <a href="#static_android.lens.radialDistortion">android.<wbr/>lens.<wbr/>radial<wbr/>Distortion</a> field,<wbr/> which was
+inconsistently defined.<wbr/></p>
+            </td>
+
+            <td class="entry_units">
+              
+            Unitless coefficients.<wbr/>
+          
+            </td>
+
+            <td class="entry_range">
+            </td>
+
+            <td class="entry_hal_version">
+              <p>3.<wbr/>3</p>
+            </td>
+
+            <td class="entry_tags">
+              <ul class="entry_tags">
+                  <li><a href="#tag_DEPTH">DEPTH</a></li>
+              </ul>
+            </td>
+
+          </tr>
+          <tr class="entries_header">
+            <th class="th_details" colspan="6">Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="6">
+              <p>Three radial distortion coefficients <code>[kappa_<wbr/>1,<wbr/> kappa_<wbr/>2,<wbr/>
+kappa_<wbr/>3]</code> and two tangential distortion coefficients
+<code>[kappa_<wbr/>4,<wbr/> kappa_<wbr/>5]</code> that can be used to correct the
+lens's geometric distortion with the mapping equations:</p>
+<pre><code> x_<wbr/>c = x_<wbr/>i * ( 1 + kappa_<wbr/>1 * r^2 + kappa_<wbr/>2 * r^4 + kappa_<wbr/>3 * r^6 ) +
+       kappa_<wbr/>4 * (2 * x_<wbr/>i * y_<wbr/>i) + kappa_<wbr/>5 * ( r^2 + 2 * x_<wbr/>i^2 )
+ y_<wbr/>c = y_<wbr/>i * ( 1 + kappa_<wbr/>1 * r^2 + kappa_<wbr/>2 * r^4 + kappa_<wbr/>3 * r^6 ) +
+       kappa_<wbr/>5 * (2 * x_<wbr/>i * y_<wbr/>i) + kappa_<wbr/>4 * ( r^2 + 2 * y_<wbr/>i^2 )
+</code></pre>
+<p>Here,<wbr/> <code>[x_<wbr/>c,<wbr/> y_<wbr/>c]</code> are the coordinates to sample in the
+input image that correspond to the pixel values in the
+corrected image at the coordinate <code>[x_<wbr/>i,<wbr/> y_<wbr/>i]</code>:</p>
+<pre><code> correctedImage(x_<wbr/>i,<wbr/> y_<wbr/>i) = sample_<wbr/>at(x_<wbr/>c,<wbr/> y_<wbr/>c,<wbr/> inputImage)
+</code></pre>
+<p>The pixel coordinates are defined in a coordinate system
+related to the <a href="#static_android.lens.intrinsicCalibration">android.<wbr/>lens.<wbr/>intrinsic<wbr/>Calibration</a>
+calibration fields; see that entry for details of the mapping stages.<wbr/>
+Both <code>[x_<wbr/>i,<wbr/> y_<wbr/>i]</code> and <code>[x_<wbr/>c,<wbr/> y_<wbr/>c]</code>
+have <code>(0,<wbr/>0)</code> at the lens optical center <code>[c_<wbr/>x,<wbr/> c_<wbr/>y]</code>,<wbr/> and
+the range of the coordinates depends on the focal length
+terms of the intrinsic calibration.<wbr/></p>
+<p>Finally,<wbr/> <code>r</code> represents the radial distance from the
+optical center,<wbr/> <code>r^2 = x_<wbr/>i^2 + y_<wbr/>i^2</code>.<wbr/></p>
+<p>The distortion model used is the Brown-Conrady model.<wbr/></p>
+            </td>
+          </tr>
+
+
+          <tr class="entry_spacer"><td class="entry_spacer" colspan="7"></td></tr>
+           <!-- end of entry -->
+        
         
 
       <!-- end of kind -->
@@ -14460,7 +14554,7 @@
 from the main sensor along the +X axis (to the right from the user's perspective) will
 report <code>(0.<wbr/>03,<wbr/> 0,<wbr/> 0)</code>.<wbr/></p>
 <p>To transform a pixel coordinates between two cameras facing the same direction,<wbr/> first
-the source camera <a href="#static_android.lens.radialDistortion">android.<wbr/>lens.<wbr/>radial<wbr/>Distortion</a> must be corrected for.<wbr/>  Then the source
+the source camera <a href="#static_android.lens.distortion">android.<wbr/>lens.<wbr/>distortion</a> must be corrected for.<wbr/>  Then the source
 camera <a href="#static_android.lens.intrinsicCalibration">android.<wbr/>lens.<wbr/>intrinsic<wbr/>Calibration</a> needs to be applied,<wbr/> followed by the
 <a href="#static_android.lens.poseRotation">android.<wbr/>lens.<wbr/>pose<wbr/>Rotation</a> of the source camera,<wbr/> the translation of the source camera
 relative to the destination camera,<wbr/> the <a href="#static_android.lens.poseRotation">android.<wbr/>lens.<wbr/>pose<wbr/>Rotation</a> of the destination
@@ -14569,7 +14663,7 @@
 where <code>(0,<wbr/>0)</code> is the top-left of the
 preCorrectionActiveArraySize rectangle.<wbr/> Once the pose and
 intrinsic calibration transforms have been applied to a
-world point,<wbr/> then the <a href="#static_android.lens.radialDistortion">android.<wbr/>lens.<wbr/>radial<wbr/>Distortion</a>
+world point,<wbr/> then the <a href="#static_android.lens.distortion">android.<wbr/>lens.<wbr/>distortion</a>
 transform needs to be applied,<wbr/> and the result adjusted to
 be in the <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a> coordinate
 system (where <code>(0,<wbr/> 0)</code> is the top-left of the
@@ -14586,6 +14680,7 @@
                 
           <tr class="entry" id="dynamic_android.lens.radialDistortion">
             <td class="entry_name
+                entry_name_deprecated
              " rowspan="3">
               android.<wbr/>lens.<wbr/>radial<wbr/>Distortion
             </td>
@@ -14600,6 +14695,7 @@
 
 
 
+              <span class="entry_type_deprecated">[deprecated] </span>
 
 
 
@@ -14617,6 +14713,7 @@
             </td>
 
             <td class="entry_range">
+              <p><span class="entry_range_deprecated">Deprecated</span>. Do not use.</p>
             </td>
 
             <td class="entry_hal_version">
@@ -14668,6 +14765,91 @@
           <tr class="entry_spacer"><td class="entry_spacer" colspan="7"></td></tr>
            <!-- end of entry -->
         
+                
+          <tr class="entry" id="dynamic_android.lens.distortion">
+            <td class="entry_name
+             " rowspan="3">
+              android.<wbr/>lens.<wbr/>distortion
+            </td>
+            <td class="entry_type">
+                <span class="entry_type_name">float</span>
+                <span class="entry_type_container">x</span>
+
+                <span class="entry_type_array">
+                  5
+                </span>
+              <span class="entry_type_visibility"> [public]</span>
+
+
+
+
+
+
+            </td> <!-- entry_type -->
+
+            <td class="entry_description">
+              <p>The correction coefficients to correct for this camera device's
+radial and tangential lens distortion.<wbr/></p>
+<p>Replaces the deprecated <a href="#static_android.lens.radialDistortion">android.<wbr/>lens.<wbr/>radial<wbr/>Distortion</a> field,<wbr/> which was
+inconsistently defined.<wbr/></p>
+            </td>
+
+            <td class="entry_units">
+              
+            Unitless coefficients.<wbr/>
+          
+            </td>
+
+            <td class="entry_range">
+            </td>
+
+            <td class="entry_hal_version">
+              <p>3.<wbr/>3</p>
+            </td>
+
+            <td class="entry_tags">
+              <ul class="entry_tags">
+                  <li><a href="#tag_DEPTH">DEPTH</a></li>
+              </ul>
+            </td>
+
+          </tr>
+          <tr class="entries_header">
+            <th class="th_details" colspan="6">Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="6">
+              <p>Three radial distortion coefficients <code>[kappa_<wbr/>1,<wbr/> kappa_<wbr/>2,<wbr/>
+kappa_<wbr/>3]</code> and two tangential distortion coefficients
+<code>[kappa_<wbr/>4,<wbr/> kappa_<wbr/>5]</code> that can be used to correct the
+lens's geometric distortion with the mapping equations:</p>
+<pre><code> x_<wbr/>c = x_<wbr/>i * ( 1 + kappa_<wbr/>1 * r^2 + kappa_<wbr/>2 * r^4 + kappa_<wbr/>3 * r^6 ) +
+       kappa_<wbr/>4 * (2 * x_<wbr/>i * y_<wbr/>i) + kappa_<wbr/>5 * ( r^2 + 2 * x_<wbr/>i^2 )
+ y_<wbr/>c = y_<wbr/>i * ( 1 + kappa_<wbr/>1 * r^2 + kappa_<wbr/>2 * r^4 + kappa_<wbr/>3 * r^6 ) +
+       kappa_<wbr/>5 * (2 * x_<wbr/>i * y_<wbr/>i) + kappa_<wbr/>4 * ( r^2 + 2 * y_<wbr/>i^2 )
+</code></pre>
+<p>Here,<wbr/> <code>[x_<wbr/>c,<wbr/> y_<wbr/>c]</code> are the coordinates to sample in the
+input image that correspond to the pixel values in the
+corrected image at the coordinate <code>[x_<wbr/>i,<wbr/> y_<wbr/>i]</code>:</p>
+<pre><code> correctedImage(x_<wbr/>i,<wbr/> y_<wbr/>i) = sample_<wbr/>at(x_<wbr/>c,<wbr/> y_<wbr/>c,<wbr/> inputImage)
+</code></pre>
+<p>The pixel coordinates are defined in a coordinate system
+related to the <a href="#static_android.lens.intrinsicCalibration">android.<wbr/>lens.<wbr/>intrinsic<wbr/>Calibration</a>
+calibration fields; see that entry for details of the mapping stages.<wbr/>
+Both <code>[x_<wbr/>i,<wbr/> y_<wbr/>i]</code> and <code>[x_<wbr/>c,<wbr/> y_<wbr/>c]</code>
+have <code>(0,<wbr/>0)</code> at the lens optical center <code>[c_<wbr/>x,<wbr/> c_<wbr/>y]</code>,<wbr/> and
+the range of the coordinates depends on the focal length
+terms of the intrinsic calibration.<wbr/></p>
+<p>Finally,<wbr/> <code>r</code> represents the radial distance from the
+optical center,<wbr/> <code>r^2 = x_<wbr/>i^2 + y_<wbr/>i^2</code>.<wbr/></p>
+<p>The distortion model used is the Brown-Conrady model.<wbr/></p>
+            </td>
+          </tr>
+
+
+          <tr class="entry_spacer"><td class="entry_spacer" colspan="7"></td></tr>
+           <!-- end of entry -->
+        
         
 
       <!-- end of kind -->
@@ -16777,7 +16959,7 @@
 <li><a href="#static_android.lens.poseTranslation">android.<wbr/>lens.<wbr/>pose<wbr/>Translation</a></li>
 <li><a href="#static_android.lens.poseRotation">android.<wbr/>lens.<wbr/>pose<wbr/>Rotation</a></li>
 <li><a href="#static_android.lens.intrinsicCalibration">android.<wbr/>lens.<wbr/>intrinsic<wbr/>Calibration</a></li>
-<li><a href="#static_android.lens.radialDistortion">android.<wbr/>lens.<wbr/>radial<wbr/>Distortion</a></li>
+<li><a href="#static_android.lens.distortion">android.<wbr/>lens.<wbr/>distortion</a></li>
 </ul>
 </li>
 <li>The <a href="#static_android.depth.depthIsExclusive">android.<wbr/>depth.<wbr/>depth<wbr/>Is<wbr/>Exclusive</a> entry is listed by this device.<wbr/></li>
@@ -16889,7 +17071,7 @@
 <li><a href="#static_android.lens.poseRotation">android.<wbr/>lens.<wbr/>pose<wbr/>Rotation</a></li>
 <li><a href="#static_android.lens.poseTranslation">android.<wbr/>lens.<wbr/>pose<wbr/>Translation</a></li>
 <li><a href="#static_android.lens.intrinsicCalibration">android.<wbr/>lens.<wbr/>intrinsic<wbr/>Calibration</a></li>
-<li><a href="#static_android.lens.radialDistortion">android.<wbr/>lens.<wbr/>radial<wbr/>Distortion</a></li>
+<li><a href="#static_android.lens.distortion">android.<wbr/>lens.<wbr/>distortion</a></li>
 </ul>
 </li>
 <li>The SENSOR_<wbr/>INFO_<wbr/>TIMESTAMP_<wbr/>SOURCE of the logical device and physical devices must be
@@ -20894,7 +21076,7 @@
 <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/></p>
 <p>The currently supported fields that correct for geometric distortion are:</p>
 <ol>
-<li><a href="#static_android.lens.radialDistortion">android.<wbr/>lens.<wbr/>radial<wbr/>Distortion</a>.<wbr/></li>
+<li><a href="#static_android.lens.distortion">android.<wbr/>lens.<wbr/>distortion</a>.<wbr/></li>
 </ol>
 <p>If all of the geometric distortion fields are no-ops,<wbr/> this rectangle will be the same
 as the post-distortion-corrected rectangle given in
@@ -24131,7 +24313,7 @@
             </td>
 
             <td class="entry_range">
-              <p>android.<wbr/>Statistics.<wbr/>info.<wbr/>available<wbr/>Ois<wbr/>Data<wbr/>Modes</p>
+              <p><a href="#static_android.statistics.info.availableOisDataModes">android.<wbr/>statistics.<wbr/>info.<wbr/>available<wbr/>Ois<wbr/>Data<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_hal_version">
@@ -25995,7 +26177,7 @@
             </td>
 
             <td class="entry_range">
-              <p>android.<wbr/>Statistics.<wbr/>info.<wbr/>available<wbr/>Ois<wbr/>Data<wbr/>Modes</p>
+              <p><a href="#static_android.statistics.info.availableOisDataModes">android.<wbr/>statistics.<wbr/>info.<wbr/>available<wbr/>Ois<wbr/>Data<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_hal_version">
@@ -29781,6 +29963,7 @@
           <li><a href="#static_android.lens.poseTranslation">android.lens.poseTranslation</a> (static)</li>
           <li><a href="#static_android.lens.intrinsicCalibration">android.lens.intrinsicCalibration</a> (static)</li>
           <li><a href="#static_android.lens.radialDistortion">android.lens.radialDistortion</a> (static)</li>
+          <li><a href="#static_android.lens.distortion">android.lens.distortion</a> (static)</li>
           <li><a href="#static_android.depth.maxDepthSamples">android.depth.maxDepthSamples</a> (static)</li>
           <li><a href="#static_android.depth.availableDepthStreamConfigurations">android.depth.availableDepthStreamConfigurations</a> (static)</li>
           <li><a href="#static_android.depth.availableDepthMinFrameDurations">android.depth.availableDepthMinFrameDurations</a> (static)</li>
diff --git a/camera/docs/metadata_definitions.xml b/camera/docs/metadata_definitions.xml
index 9443f98..e96a0a6 100644
--- a/camera/docs/metadata_definitions.xml
+++ b/camera/docs/metadata_definitions.xml
@@ -2268,6 +2268,9 @@
         <entry name="aePrecaptureId" type="int32" visibility="system" deprecated="true">
           <description>The ID sent with the latest
           CAMERA2_TRIGGER_PRECAPTURE_METERING call</description>
+          <deprecation_description>
+            Removed in camera HAL v3
+          </deprecation_description>
           <details>Must be 0 if no
           CAMERA2_TRIGGER_PRECAPTURE_METERING trigger received yet
           by HAL. Always updated even if AE algorithm ignores the
@@ -2570,6 +2573,9 @@
         <entry name="afTriggerId" type="int32" visibility="system" deprecated="true">
           <description>The ID sent with the latest
           CAMERA2_TRIGGER_AUTOFOCUS call</description>
+          <deprecation_description>
+            Removed in camera HAL v3
+          </deprecation_description>
           <details>Must be 0 if no CAMERA2_TRIGGER_AUTOFOCUS trigger
           received yet by HAL. Always updated even if AF algorithm
           ignores the trigger</details>
@@ -3890,7 +3896,7 @@
             report `(0.03, 0, 0)`.
 
             To transform a pixel coordinates between two cameras facing the same direction, first
-            the source camera android.lens.radialDistortion must be corrected for.  Then the source
+            the source camera android.lens.distortion must be corrected for.  Then the source
             camera android.lens.intrinsicCalibration needs to be applied, followed by the
             android.lens.poseRotation of the source camera, the translation of the source camera
             relative to the destination camera, the android.lens.poseRotation of the destination
@@ -4047,7 +4053,7 @@
             where `(0,0)` is the top-left of the
             preCorrectionActiveArraySize rectangle. Once the pose and
             intrinsic calibration transforms have been applied to a
-            world point, then the android.lens.radialDistortion
+            world point, then the android.lens.distortion
             transform needs to be applied, and the result adjusted to
             be in the android.sensor.info.activeArraySize coordinate
             system (where `(0, 0)` is the top-left of the
@@ -4058,7 +4064,7 @@
           <tag id="DEPTH" />
         </entry>
         <entry name="radialDistortion" type="float" visibility="public"
-               container="array">
+               deprecated="true" container="array">
           <array>
             <size>6</size>
           </array>
@@ -4066,6 +4072,10 @@
             The correction coefficients to correct for this camera device's
             radial and tangential lens distortion.
           </description>
+          <deprecation_description>
+            This field was inconsistently defined in terms of its
+            normalization. Use android.lens.distortion instead.
+          </deprecation_description>
           <units>
             Unitless coefficients.
           </units>
@@ -4134,7 +4144,58 @@
             depending on the selected coordinate origin.
           </details>
         </entry>
+        <entry name="distortion" type="float" visibility="public" container="array"
+               hal_version="3.3">
+          <array>
+            <size>5</size>
+          </array>
+          <description>
+            The correction coefficients to correct for this camera device's
+            radial and tangential lens distortion.
+
+            Replaces the deprecated android.lens.radialDistortion field, which was
+            inconsistently defined.
+          </description>
+          <units>
+            Unitless coefficients.
+          </units>
+          <details>
+            Three radial distortion coefficients `[kappa_1, kappa_2,
+            kappa_3]` and two tangential distortion coefficients
+            `[kappa_4, kappa_5]` that can be used to correct the
+            lens's geometric distortion with the mapping equations:
+
+                 x_c = x_i * ( 1 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) +
+                       kappa_4 * (2 * x_i * y_i) + kappa_5 * ( r^2 + 2 * x_i^2 )
+                 y_c = y_i * ( 1 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) +
+                       kappa_5 * (2 * x_i * y_i) + kappa_4 * ( r^2 + 2 * y_i^2 )
+
+            Here, `[x_c, y_c]` are the coordinates to sample in the
+            input image that correspond to the pixel values in the
+            corrected image at the coordinate `[x_i, y_i]`:
+
+                 correctedImage(x_i, y_i) = sample_at(x_c, y_c, inputImage)
+
+            The pixel coordinates are defined in a coordinate system
+            related to the android.lens.intrinsicCalibration
+            calibration fields; see that entry for details of the mapping stages.
+            Both `[x_i, y_i]` and `[x_c, y_c]`
+            have `(0,0)` at the lens optical center `[c_x, c_y]`, and
+            the range of the coordinates depends on the focal length
+            terms of the intrinsic calibration.
+
+            Finally, `r` represents the radial distance from the
+            optical center, `r^2 = x_i^2 + y_i^2`.
+
+            The distortion model used is the Brown-Conrady model.
+          </details>
+          <tag id="DEPTH" />
+        </entry>
       </static>
+      <dynamic>
+        <clone entry="android.lens.distortion" kind="static">
+        </clone>
+      </dynamic>
     </section>
     <section name="noiseReduction">
       <controls>
@@ -4270,6 +4331,9 @@
           scale 'normalized' coordinates with respect to the crop
           region. This applies to metering input (a{e,f,wb}Region
           and output (face rectangles).</description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <details>Normalized coordinates refer to those in the
           (-1000,1000) range mentioned in the
           android.hardware.Camera API.
@@ -4283,6 +4347,9 @@
           <description>If set to 1, then the camera service always
           switches to FOCUS_MODE_AUTO before issuing a AF
           trigger.</description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <details>HAL implementations should implement AF trigger
           modes for AUTO, MACRO, CONTINUOUS_FOCUS, and
           CONTINUOUS_PICTURE modes instead of using this flag. Does
@@ -4294,6 +4361,9 @@
           CAMERA2_PIXEL_FORMAT_ZSL instead of
           HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED for the zero
           shutter lag stream</description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <details>HAL implementations should use gralloc usage flags
           to determine that a stream will be used for
           zero-shutter-lag, instead of relying on an explicit
@@ -4307,6 +4377,9 @@
           metadata for a single capture into multiple buffers,
           returned using multiple process_capture_result calls.
           </description>
+          <deprecation_description>
+          Not used in HALv3 or newer; replaced by better partials mechanism
+          </deprecation_description>
           <details>
           Does not need to be listed in static
           metadata. Support for partial results will be reworked in
@@ -4339,6 +4412,9 @@
           final one for the capture, or only a partial that contains a
           subset of the full set of dynamic metadata
           values.</description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <range>Optional. Default value is FINAL.</range>
           <details>
           The entries in the result metadata buffers for a
@@ -4366,6 +4442,9 @@
           increases with every new result (that is, each new result has a unique
           frameCount value).
           </description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <units>incrementing integer</units>
           <range>Any int.</range>
         </entry>
@@ -4384,6 +4463,9 @@
           </array>
           <description>List which camera reprocess stream is used
           for the source of reprocessing data.</description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <units>List of camera reprocess stream IDs</units>
           <range>
           Typically, only one entry allowed, must be a valid reprocess stream ID.
@@ -4420,6 +4502,9 @@
           </array>
           <description>Lists which camera output streams image data
           from this capture must be sent to</description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <units>List of camera stream IDs</units>
           <range>List must only include streams that have been
           created</range>
@@ -4444,6 +4529,9 @@
           <description>The type of the request; either CAPTURE or
           REPROCESS. For legacy HAL3, this tag is redundant.
           </description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <tag id="HAL2" />
         </entry>
       </controls>
@@ -4591,6 +4679,9 @@
           </array>
           <description>How many reprocessing streams of any type
           can be allocated at the same time.</description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <range>&amp;gt;= 0</range>
           <details>
           Only used by HAL2.x.
@@ -4634,6 +4725,9 @@
           <description>A frame counter set by the framework. This value monotonically
           increases with every new result (that is, each new result has a unique
           frameCount value).</description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <units>count of frames</units>
           <range>&amp;gt; 0</range>
           <details>Reset on release()</details>
@@ -5000,7 +5094,7 @@
                   - android.lens.poseTranslation
                   - android.lens.poseRotation
                   - android.lens.intrinsicCalibration
-                  - android.lens.radialDistortion
+                  - android.lens.distortion
               * The android.depth.depthIsExclusive entry is listed by this device.
               * As of Android P, the android.lens.poseReference entry is listed by this device.
               * A LIMITED camera with only the DEPTH_OUTPUT capability does not have to support
@@ -5125,7 +5219,7 @@
                   - android.lens.poseRotation
                   - android.lens.poseTranslation
                   - android.lens.intrinsicCalibration
-                  - android.lens.radialDistortion
+                  - android.lens.distortion
               * The SENSOR_INFO_TIMESTAMP_SOURCE of the logical device and physical devices must be
                 the same.
               * The logical camera device must be LIMITED or higher device.
@@ -5607,6 +5701,9 @@
           </enum>
           <description>The list of image formats that are supported by this
           camera device for output streams.</description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <details>
           All camera devices will support JPEG and YUV_420_888 formats.
 
@@ -5642,6 +5739,9 @@
           <description>The minimum frame duration that is supported
           for each resolution in android.scaler.availableJpegSizes.
           </description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <units>Nanoseconds</units>
           <range>TODO: Remove property.</range>
           <details>
@@ -5661,6 +5761,9 @@
             <size>2</size>
           </array>
           <description>The JPEG resolutions that are supported by this camera device.</description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <range>TODO: Remove property.</range>
           <details>
           The resolutions are listed as `(width, height)` pairs. All camera devices will support
@@ -5701,6 +5804,9 @@
           android.scaler.availableProcessedSizes), this property lists the
           minimum supportable frame duration for that size.
           </description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <units>Nanoseconds</units>
           <details>
           This should correspond to the frame duration when only that processed
@@ -5722,6 +5828,9 @@
           processed output streams, such as YV12, NV12, and
           platform opaque YUV/RGB streams to the GPU or video
           encoders.</description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <details>
           The resolutions are listed as `(width, height)` pairs.
 
@@ -5761,6 +5870,9 @@
           android.scaler.availableRawSizes), this property lists the minimum
           supportable frame duration for that size.
           </description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
           <units>Nanoseconds</units>
           <details>
           Should correspond to the frame duration when only the raw stream is
@@ -5780,6 +5892,9 @@
           <description>The resolutions available for use with raw
           sensor output streams, listed as width,
           height</description>
+          <deprecation_description>
+          Not used in HALv3 or newer
+          </deprecation_description>
         </entry>
       </static>
       <dynamic>
@@ -6649,7 +6764,7 @@
 
             The currently supported fields that correct for geometric distortion are:
 
-            1. android.lens.radialDistortion.
+            1. android.lens.distortion.
 
             If all of the geometric distortion fields are no-ops, this rectangle will be the same
             as the post-distortion-corrected rectangle given in
@@ -8167,6 +8282,9 @@
           <description>The best-fit color channel gains calculated
           by the camera device's statistics units for the current output frame.
           </description>
+          <deprecation_description>
+          Never fully implemented or specified; do not use
+          </deprecation_description>
           <details>
           This may be different than the gains used for this frame,
           since statistics processing on data from a new frame
@@ -8193,6 +8311,9 @@
           <description>The best-fit color transform matrix estimate
           calculated by the camera device's statistics units for the current
           output frame.</description>
+          <deprecation_description>
+          Never fully implemented or specified; do not use
+          </deprecation_description>
           <details>The camera device will provide the estimate from its
           statistics unit on the white balance transforms to use
           for the next frame. These are the values the camera device believes
@@ -8322,7 +8443,7 @@
           </enum>
           <description>A control for selecting whether OIS position information is included in output
           result metadata.</description>
-          <range>android.Statistics.info.availableOisDataModes</range>
+          <range>android.statistics.info.availableOisDataModes</range>
         </entry>
       </controls>
       <dynamic>
diff --git a/camera/docs/metadata_definitions.xsd b/camera/docs/metadata_definitions.xsd
index d8c15ab..cd021bd 100644
--- a/camera/docs/metadata_definitions.xsd
+++ b/camera/docs/metadata_definitions.xsd
@@ -133,6 +133,9 @@
             <element name="description" type="string" maxOccurs="1"
                 minOccurs="0">
             </element>
+            <element name="deprecation_description" type="string" maxOccurs="1"
+                     minOccurs="0">
+            </element>
             <element name="units" type="string" maxOccurs="1"
                 minOccurs="0">
             </element>
diff --git a/camera/docs/metadata_helpers.py b/camera/docs/metadata_helpers.py
index 5f03d40..ed303bb 100644
--- a/camera/docs/metadata_helpers.py
+++ b/camera/docs/metadata_helpers.py
@@ -818,7 +818,7 @@
     "    * @see CaptureRequest#CONTROL_MODE\n"
   """
   def javadoc_formatter(text):
-    comment_prefix = " " * indent + " * ";
+    comment_prefix = " " * indent + " * "
 
     # render with markdown => HTML
     javatext = md(text, JAVADOC_IMAGE_SRC_METADATA)
diff --git a/camera/docs/metadata_model.py b/camera/docs/metadata_model.py
index 4485ad8..daebcb2 100644
--- a/camera/docs/metadata_model.py
+++ b/camera/docs/metadata_model.py
@@ -1132,6 +1132,8 @@
     tuple_values: A sequence of strings describing the tuple values,
                   None if container is not 'tuple'.
     description: A string description, or None.
+    deprecation_description: A string describing the reason for deprecation. Must be present
+                 if deprecated is true, otherwise may be None.
     range: A string range, or None.
     units: A string units, or None.
     tags: A sequence of Tag nodes associated with this Entry.
@@ -1171,6 +1173,10 @@
       enum_ids: A dictionary of value->id strings.
       enum_hal_versions: A dictionary of value->hal version strings
 
+    Args (if the 'deprecated' attribute is true):
+      deprecation_description: A string explaining the deprecation, to be added
+                               to the Java-layer @deprecated tag
+
     Args (optional):
       description: A string with a description of the entry.
       range: A string with the range of the values of the entry, e.g. '>= 0'
@@ -1246,6 +1252,10 @@
   def deprecated(self):
     return self._deprecated
 
+  @property
+  def deprecation_description(self):
+    return self._deprecation_description
+
   # TODO: optional should just return hwlevel is None
   @property
   def optional(self):
@@ -1399,6 +1409,8 @@
     self._synthetic = kwargs.get('synthetic', False)
     self._hwlevel = kwargs.get('hwlevel')
     self._deprecated = kwargs.get('deprecated', False)
+    self._deprecation_description = kwargs.get('deprecation_description')
+
     self._optional = kwargs.get('optional')
     self._ndk_visible = kwargs.get('ndk_visible')
 
@@ -1585,7 +1597,8 @@
       entry: An Entry or Clone instance
     """
     props_distinct = ['description', 'units', 'range', 'details',
-                      'hal_details', 'ndk_details', 'tags', 'kind']
+                      'hal_details', 'ndk_details', 'tags', 'kind',
+                      'deprecation_description']
 
     for p in props_distinct:
       p = '_' + p
diff --git a/camera/docs/metadata_parser_xml.py b/camera/docs/metadata_parser_xml.py
index 1daf02b..db2c154 100755
--- a/camera/docs/metadata_parser_xml.py
+++ b/camera/docs/metadata_parser_xml.py
@@ -293,7 +293,8 @@
   def _parse_entry_optional(self, entry):
     d = {}
 
-    optional_elements = ['description', 'range', 'units', 'details', 'hal_details', 'ndk_details']
+    optional_elements = ['description', 'range', 'units', 'details', 'hal_details', 'ndk_details',\
+                         'deprecation_description']
     for i in optional_elements:
       prop = find_child_tag(entry, i)
 
diff --git a/camera/docs/metadata_template.mako b/camera/docs/metadata_template.mako
index fc909c1..22c68a5 100644
--- a/camera/docs/metadata_template.mako
+++ b/camera/docs/metadata_template.mako
@@ -180,6 +180,10 @@
                 <description>${prop.description | x}</description>
               % endif
 
+              % if prop.deprecation_description is not None:
+                <deprecation_description>${prop.deprecation_description | x}</deprecation_description>
+              % endif
+
               % if prop.units is not None:
                 <units>${prop.units | x}</units>
               % endif
diff --git a/camera/docs/metadata_validate.py b/camera/docs/metadata_validate.py
index 8260005..44f860a 100755
--- a/camera/docs/metadata_validate.py
+++ b/camera/docs/metadata_validate.py
@@ -281,6 +281,20 @@
                                   ))
         success = False
 
+    deprecated = entry.attrs.get('deprecated')
+    if deprecated and deprecated == 'true':
+      if entry.deprecation_description is None:
+        validate_error(("Entry '%s' in kind '%s' is deprecated, but missing deprecation description") \
+                       % (fully_qualified_name(entry), find_kind(entry),
+                       ))
+        success = False
+    else:
+      if entry.deprecation_description is not None:
+        validate_error(("Entry '%s' in kind '%s' has deprecation description, but is not deprecated") \
+                       % (fully_qualified_name(entry), find_kind(entry),
+                       ))
+        success = False
+
   return success
 
 def validate_xml(xml):
diff --git a/camera/include/system/camera_metadata_tags.h b/camera/include/system/camera_metadata_tags.h
index 3b57902..823c414 100644
--- a/camera/include/system/camera_metadata_tags.h
+++ b/camera/include/system/camera_metadata_tags.h
@@ -224,6 +224,7 @@
     ANDROID_LENS_INTRINSIC_CALIBRATION,               // float[]      | public       | HIDL v3.2
     ANDROID_LENS_RADIAL_DISTORTION,                   // float[]      | public       | HIDL v3.2
     ANDROID_LENS_POSE_REFERENCE,                      // enum         | public       | HIDL v3.3
+    ANDROID_LENS_DISTORTION,                          // float[]      | public       | HIDL v3.3
     ANDROID_LENS_END,
 
     ANDROID_LENS_INFO_AVAILABLE_APERTURES =           // float[]      | public       | HIDL v3.2
diff --git a/camera/src/camera_metadata_tag_info.c b/camera/src/camera_metadata_tag_info.c
index e943f79..b420fc1 100644
--- a/camera/src/camera_metadata_tag_info.c
+++ b/camera/src/camera_metadata_tag_info.c
@@ -325,6 +325,8 @@
     { "radialDistortion",              TYPE_FLOAT  },
     [ ANDROID_LENS_POSE_REFERENCE - ANDROID_LENS_START ] =
     { "poseReference",                 TYPE_BYTE   },
+    [ ANDROID_LENS_DISTORTION - ANDROID_LENS_START ] =
+    { "distortion",                    TYPE_FLOAT  },
 };
 
 static tag_info_t android_lens_info[ANDROID_LENS_INFO_END -
@@ -1693,6 +1695,9 @@
             }
             break;
         }
+        case ANDROID_LENS_DISTORTION: {
+            break;
+        }
 
         case ANDROID_LENS_INFO_AVAILABLE_APERTURES: {
             break;