Camera: Rename timestampCalibration -> timestampSource

Improves clarity.

Bug: 16402755
Change-Id: I181186427ce3eb5e2b4a609fbbc0643fca3acce8

4 files changed, 41 insertions, 38 deletions

diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index badf4ca3..b7c0caff 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -746,7 +746,7 @@
             <li
             ><a href="#static_android.sensor.info.whiteLevel">android.sensor.info.whiteLevel</a></li>
             <li
-            ><a href="#static_android.sensor.info.timestampCalibration">android.sensor.info.timestampCalibration</a></li>
+            ><a href="#static_android.sensor.info.timestampSource">android.sensor.info.timestampSource</a></li>
 
             <li
             ><a href="#static_android.sensor.referenceIlluminant1">android.sensor.referenceIlluminant1</a></li>
@@ -3108,8 +3108,7 @@ use case.<wbr/></p></span>
 image while recording video) use case.<wbr/></p>
 <p>The camera device should take the highest-quality image
 possible (given the other settings) without disrupting the
-frame rate of video recording.<wbr/><br/>
-</p></span>
+frame rate of video recording.<wbr/>  </p></span>
                   </li>
                   <li>
                     <span class="entry_type_enum_name">ZERO_SHUTTER_LAG</span>
@@ -6766,8 +6765,7 @@ use case.<wbr/></p></span>
 image while recording video) use case.<wbr/></p>
 <p>The camera device should take the highest-quality image
 possible (given the other settings) without disrupting the
-frame rate of video recording.<wbr/><br/>
-</p></span>
+frame rate of video recording.<wbr/>  </p></span>
                   </li>
                   <li>
                     <span class="entry_type_enum_name">ZERO_SHUTTER_LAG</span>
@@ -16343,10 +16341,10 @@ than maximum raw value supported,<wbr/> i.<wbr/>e.<wbr/> 2^(sensor bits per pixe
            <!-- end of entry -->
         
                 
-          <tr class="entry" id="static_android.sensor.info.timestampCalibration">
+          <tr class="entry" id="static_android.sensor.info.timestampSource">
             <td class="entry_name
              " rowspan="3">
-              android.<wbr/>sensor.<wbr/>info.<wbr/>timestamp<wbr/>Calibration
+              android.<wbr/>sensor.<wbr/>info.<wbr/>timestamp<wbr/>Source
             </td>
             <td class="entry_type">
                 <span class="entry_type_name entry_type_name_enum">byte</span>
@@ -16358,7 +16356,7 @@ than maximum raw value supported,<wbr/> i.<wbr/>e.<wbr/> 2^(sensor bits per pixe
 
                 <ul class="entry_type_enum">
                   <li>
-                    <span class="entry_type_enum_name">UNCALIBRATED</span>
+                    <span class="entry_type_enum_name">UNKNOWN</span>
                     <span class="entry_type_enum_notes"><p>Timestamps from <a href="#dynamic_android.sensor.timestamp">android.<wbr/>sensor.<wbr/>timestamp</a> are in nanoseconds and monotonic,<wbr/>
 but can not be compared to timestamps from other subsystems
 (e.<wbr/>g.<wbr/> accelerometer,<wbr/> gyro etc.<wbr/>),<wbr/> or other instances of the same or different
@@ -16367,7 +16365,7 @@ a single camera instance are comparable,<wbr/> and the timestamps for all buffer
 and the result metadata generated by a single capture are identical.<wbr/></p></span>
                   </li>
                   <li>
-                    <span class="entry_type_enum_name">CALIBRATED</span>
+                    <span class="entry_type_enum_name">REALTIME</span>
                     <span class="entry_type_enum_notes"><p>Timestamps from <a href="#dynamic_android.sensor.timestamp">android.<wbr/>sensor.<wbr/>timestamp</a> are in the same timebase as
 android.<wbr/>os.<wbr/>System<wbr/>Clock#elapsed<wbr/>Realtime<wbr/>Nanos(),<wbr/>
 and they can be compared to other timestamps using that base.<wbr/></p></span>
@@ -16377,7 +16375,7 @@ and they can be compared to other timestamps using that base.<wbr/></p></span>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The sensor timestamp calibration quality.<wbr/></p>
+              <p>The time base source for sensor capture start timestamps.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -16398,8 +16396,10 @@ and they can be compared to other timestamps using that base.<wbr/></p></span>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>The sensor timestamp calibration quality determines the reliability of
-<a href="#dynamic_android.sensor.timestamp">android.<wbr/>sensor.<wbr/>timestamp</a> provided by the camera device.<wbr/></p>
+              <p>The timestamps provided for captures are always in nanoseconds and monotonic,<wbr/> but
+may not based on a time source that can be compared to other system time sources.<wbr/></p>
+<p>This characteristic defines the source for the timestamps,<wbr/> and therefore whether they
+can be compared against other system time sources/<wbr/>timestamps.<wbr/></p>
             </td>
           </tr>
 
@@ -17644,12 +17644,12 @@ row of the image sensor active array,<wbr/> in nanoseconds.<wbr/></p>
               <p>The timestamps are also included in all image
 buffers produced for the same capture,<wbr/> and will be identical
 on all the outputs.<wbr/></p>
-<p>When <a href="#static_android.sensor.info.timestampCalibration">android.<wbr/>sensor.<wbr/>info.<wbr/>timestamp<wbr/>Calibration</a> <code>==</code> UNCALIBRATED,<wbr/>
+<p>When <a href="#static_android.sensor.info.timestampSource">android.<wbr/>sensor.<wbr/>info.<wbr/>timestamp<wbr/>Source</a> <code>==</code> UNKNOWN,<wbr/>
 the timestamps measure time since an unspecified starting point,<wbr/>
 and are monotonically increasing.<wbr/> They can be compared with the
 timestamps for other captures from the same camera device,<wbr/> but are
 not guaranteed to be comparable to any other time source.<wbr/></p>
-<p>When <a href="#static_android.sensor.info.timestampCalibration">android.<wbr/>sensor.<wbr/>info.<wbr/>timestamp<wbr/>Calibration</a> <code>==</code> CALIBRATED,<wbr/>
+<p>When <a href="#static_android.sensor.info.timestampSource">android.<wbr/>sensor.<wbr/>info.<wbr/>timestamp<wbr/>Source</a> <code>==</code> REALTIME,<wbr/>
 the timestamps measure time in the same timebase as
 android.<wbr/>os.<wbr/>System<wbr/>Clock#elapsed<wbr/>Realtime<wbr/>Nanos(),<wbr/> and they can be
 compared to other timestamps from other subsystems that are using
@@ -17667,7 +17667,7 @@ CLOCK_<wbr/>BOOTTIME monotonic clock,<wbr/> which properly accounts for
 time spent asleep.<wbr/> This allows for synchronization with
 sensors that continue to operate while the system is
 otherwise asleep.<wbr/></p>
-<p>If <a href="#static_android.sensor.info.timestampCalibration">android.<wbr/>sensor.<wbr/>info.<wbr/>timestamp<wbr/>Calibration</a> <code>==</code> CALIBRATED,<wbr/>
+<p>If <a href="#static_android.sensor.info.timestampSource">android.<wbr/>sensor.<wbr/>info.<wbr/>timestamp<wbr/>Source</a> <code>==</code> REALTIME,<wbr/>
 The timestamp must be synchronized with the timestamps from other
 sensor subsystems that are using the same timebase.<wbr/></p>
             </td>
@@ -22464,7 +22464,7 @@ to know when sensor settings have been applied.<wbr/></p>
           <li><a href="#static_android.sensor.info.exposureTimeRange">android.sensor.info.exposureTimeRange</a> (static)</li>
           <li><a href="#static_android.sensor.info.maxFrameDuration">android.sensor.info.maxFrameDuration</a> (static)</li>
           <li><a href="#static_android.sensor.info.physicalSize">android.sensor.info.physicalSize</a> (static)</li>
-          <li><a href="#static_android.sensor.info.timestampCalibration">android.sensor.info.timestampCalibration</a> (static)</li>
+          <li><a href="#static_android.sensor.info.timestampSource">android.sensor.info.timestampSource</a> (static)</li>
           <li><a href="#static_android.sensor.maxAnalogSensitivity">android.sensor.maxAnalogSensitivity</a> (static)</li>
           <li><a href="#dynamic_android.sensor.rollingShutterSkew">android.sensor.rollingShutterSkew</a> (dynamic)</li>
           <li><a href="#controls_android.statistics.hotPixelMapMode">android.statistics.hotPixelMapMode</a> (controls)</li>
diff --git a/camera/docs/metadata_properties.xml b/camera/docs/metadata_properties.xml
index 0abe5372..b98a1165 100644
--- a/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@ -4844,9 +4844,9 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             </hal_details>
             <tag id="RAW" />
           </entry>
-          <entry name="timestampCalibration" type="byte" visibility="public" enum="true">
+          <entry name="timestampSource" type="byte" visibility="public" enum="true">
             <enum>
-              <value>UNCALIBRATED
+              <value>UNKNOWN
                 <notes>
                 Timestamps from android.sensor.timestamp are in nanoseconds and monotonic,
                 but can not be compared to timestamps from other subsystems
@@ -4856,7 +4856,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
                 and the result metadata generated by a single capture are identical.
                 </notes>
               </value>
-              <value>CALIBRATED
+              <value>REALTIME
                 <notes>
                 Timestamps from android.sensor.timestamp are in the same timebase as
                 android.os.SystemClock#elapsedRealtimeNanos(),
@@ -4864,10 +4864,13 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
                 </notes>
               </value>
             </enum>
-            <description>The sensor timestamp calibration quality.</description>
+            <description>The time base source for sensor capture start timestamps.</description>
             <details>
-            The sensor timestamp calibration quality determines the reliability of
-            android.sensor.timestamp provided by the camera device.
+            The timestamps provided for captures are always in nanoseconds and monotonic, but
+            may not based on a time source that can be compared to other system time sources.
+
+            This characteristic defines the source for the timestamps, and therefore whether they
+            can be compared against other system time sources/timestamps.
             </details>
           <tag id="V1" />
         </entry>
@@ -5238,13 +5241,13 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           buffers produced for the same capture, and will be identical
           on all the outputs.
 
-          When android.sensor.info.timestampCalibration `==` UNCALIBRATED,
+          When android.sensor.info.timestampSource `==` UNKNOWN,
           the timestamps measure time since an unspecified starting point,
           and are monotonically increasing. They can be compared with the
           timestamps for other captures from the same camera device, but are
           not guaranteed to be comparable to any other time source.
 
-          When android.sensor.info.timestampCalibration `==` CALIBRATED,
+          When android.sensor.info.timestampSource `==` REALTIME,
           the timestamps measure time in the same timebase as
           android.os.SystemClock#elapsedRealtimeNanos(), and they can be
           compared to other timestamps from other subsystems that are using
@@ -5257,7 +5260,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           sensors that continue to operate while the system is
           otherwise asleep.
 
-          If android.sensor.info.timestampCalibration `==` CALIBRATED,
+          If android.sensor.info.timestampSource `==` REALTIME,
           The timestamp must be synchronized with the timestamps from other
           sensor subsystems that are using the same timebase.
           </hal_details>
diff --git a/camera/include/system/camera_metadata_tags.h b/camera/include/system/camera_metadata_tags.h
index 6859320b..3f3213ab 100644
--- a/camera/include/system/camera_metadata_tags.h
+++ b/camera/include/system/camera_metadata_tags.h
@@ -310,7 +310,7 @@ typedef enum camera_metadata_tag {
     ANDROID_SENSOR_INFO_PHYSICAL_SIZE,                // float[]      | public
     ANDROID_SENSOR_INFO_PIXEL_ARRAY_SIZE,             // int32[]      | public
     ANDROID_SENSOR_INFO_WHITE_LEVEL,                  // int32        | public
-    ANDROID_SENSOR_INFO_TIMESTAMP_CALIBRATION,        // enum         | public
+    ANDROID_SENSOR_INFO_TIMESTAMP_SOURCE,             // enum         | public
     ANDROID_SENSOR_INFO_END,
 
     ANDROID_SHADING_MODE =                            // enum         | public
@@ -732,11 +732,11 @@ typedef enum camera_metadata_enum_android_sensor_info_color_filter_arrangement {
     ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGB,
 } camera_metadata_enum_android_sensor_info_color_filter_arrangement_t;
 
-// ANDROID_SENSOR_INFO_TIMESTAMP_CALIBRATION
-typedef enum camera_metadata_enum_android_sensor_info_timestamp_calibration {
-    ANDROID_SENSOR_INFO_TIMESTAMP_CALIBRATION_UNCALIBRATED,
-    ANDROID_SENSOR_INFO_TIMESTAMP_CALIBRATION_CALIBRATED,
-} camera_metadata_enum_android_sensor_info_timestamp_calibration_t;
+// ANDROID_SENSOR_INFO_TIMESTAMP_SOURCE
+typedef enum camera_metadata_enum_android_sensor_info_timestamp_source {
+    ANDROID_SENSOR_INFO_TIMESTAMP_SOURCE_UNKNOWN,
+    ANDROID_SENSOR_INFO_TIMESTAMP_SOURCE_REALTIME,
+} camera_metadata_enum_android_sensor_info_timestamp_source_t;
 
 
 // ANDROID_SHADING_MODE
diff --git a/camera/src/camera_metadata_tag_info.c b/camera/src/camera_metadata_tag_info.c
index 11d95aed..0e68e090 100644
--- a/camera/src/camera_metadata_tag_info.c
+++ b/camera/src/camera_metadata_tag_info.c
@@ -497,8 +497,8 @@ static tag_info_t android_sensor_info[ANDROID_SENSOR_INFO_END -
     { "pixelArraySize",                TYPE_INT32  },
     [ ANDROID_SENSOR_INFO_WHITE_LEVEL - ANDROID_SENSOR_INFO_START ] =
     { "whiteLevel",                    TYPE_INT32  },
-    [ ANDROID_SENSOR_INFO_TIMESTAMP_CALIBRATION - ANDROID_SENSOR_INFO_START ] =
-    { "timestampCalibration",          TYPE_BYTE   },
+    [ ANDROID_SENSOR_INFO_TIMESTAMP_SOURCE - ANDROID_SENSOR_INFO_START ] =
+    { "timestampSource",               TYPE_BYTE   },
 };
 
 static tag_info_t android_shading[ANDROID_SHADING_END -
@@ -1997,14 +1997,14 @@ int camera_metadata_enum_snprint(uint32_t tag,
         case ANDROID_SENSOR_INFO_WHITE_LEVEL: {
             break;
         }
-        case ANDROID_SENSOR_INFO_TIMESTAMP_CALIBRATION: {
+        case ANDROID_SENSOR_INFO_TIMESTAMP_SOURCE: {
             switch (value) {
-                case ANDROID_SENSOR_INFO_TIMESTAMP_CALIBRATION_UNCALIBRATED:
-                    msg = "UNCALIBRATED";
+                case ANDROID_SENSOR_INFO_TIMESTAMP_SOURCE_UNKNOWN:
+                    msg = "UNKNOWN";
                     ret = 0;
                     break;
-                case ANDROID_SENSOR_INFO_TIMESTAMP_CALIBRATION_CALIBRATED:
-                    msg = "CALIBRATED";
+                case ANDROID_SENSOR_INFO_TIMESTAMP_SOURCE_REALTIME:
+                    msg = "REALTIME";
                     ret = 0;
                     break;
                 default: