[sensors] Format, wording and naming changes
* replace all "should" description with more precise wording.
* replace "aidl" name in parameter to avoid confusion.
* reformat files and method description.
Test: m -j32
Change-Id: Id1129b816b3c364c76f0a24fabba1e1418dbd8db
diff --git a/sensors/1.0/ISensors.hal b/sensors/1.0/ISensors.hal
index bb57f73..a60cc10 100644
--- a/sensors/1.0/ISensors.hal
+++ b/sensors/1.0/ISensors.hal
@@ -23,7 +23,7 @@
getSensorsList() generates (vec<SensorInfo> list);
/**
- * Place the module in a specific mode. The following modes are defined
+ * Place the module in a specific mode. The following modes are defined
*
* SENSOR_HAL_NORMAL_MODE - Normal operation. Default state of the module.
*
@@ -39,25 +39,28 @@
/* Activate/de-activate one sensor.
*
- * sensorHandle is the handle of the sensor to change.
- * enabled set to true to enable, or false to disable the sensor.
- *
* After sensor de-activation, existing sensor events that have not
- * been picked up by poll() should be abandoned immediately so that
+ * been picked up by poll() must be abandoned immediately so that
* subsequent activation will not get stale sensor events (events
* that are generated prior to the latter activation).
*
- * Returns OK on success, BAD_VALUE if sensorHandle is invalid.
+ * @param sensorHandle is the handle of the sensor to change.
+ * @param enabled set to true to enable, or false to disable the sensor.
+ *
+ * @return result OK on success, BAD_VALUE if sensorHandle is invalid.
*/
activate(int32_t sensorHandle, bool enabled) generates (Result result);
/**
* Set the sampling period in nanoseconds for a given sensor.
+ *
* If samplingPeriodNs > maxDelay it will be truncated to
* maxDelay and if samplingPeriodNs < minDelay it will be
* replaced by minDelay.
*
- * Returns OK on success, BAD_VALUE if sensorHandle is invalid.
+ * @param sensorHandle handle of sensor to be changed.
+ * @param samplngPeriodNs specified sampling period in nanoseconds.
+ * @return result OK on success, BAD_VALUE if sensorHandle is invalid.
*/
setDelay(int32_t sensorHandle, int64_t samplingPeriodNs)
generates (Result result);
@@ -69,10 +72,15 @@
* Additionally a vector of SensorInfos is returned for any dynamic sensors
* connected as notified by returned events of type DYNAMIC_SENSOR_META.
*
- * This function should block if there is no sensor event
- * available when being called.
+ * If there is no sensor event when this function is being called, block
+ * until there are sensor events available.
*
- * Returns OK on success or BAD_VALUE if maxCount <= 0.
+ * @param maxCount max number of samples can be returned.
+ * @return result OK on success or BAD_VALUE if maxCount <= 0.
+ * @return data vector of Event contains sensor events.
+ * @return dynamicSensorsAdded vector of SensorInfo contains dynamic sensor
+ * added. Each element corresponds to a dynamic sensor meta events
+ * in data.
*/
poll(int32_t maxCount)
generates (
@@ -90,7 +98,11 @@
* See the Batching sensor results page for details:
* http://source.android.com/devices/sensors/batching.html
*
- * Returns OK on success, BAD_VALUE if any parameters are invalid.
+ * @param sensorHandle handle of sensor to be changed.
+ * @param samplingPeriodNs specifies sensor sample period in nanoseconds.
+ * @param maxReportLatencyNs allowed delay time before an event is sampled
+ * to time of report.
+ * @return result OK on success, BAD_VALUE if any parameters are invalid.
*/
batch(int32_t sensorHandle,
int32_t flags,
@@ -98,17 +110,19 @@
int64_t maxReportLatencyNs) generates (Result result);
/*
+ * Trigger a flush of internal FIFO.
+ *
* Flush adds a FLUSH_COMPLETE metadata event to the end of the "batch mode"
- * FIFO for the specified sensor and flushes the FIFO.
- * If the FIFO is empty or if the sensor doesn't support batching
- * (FIFO size zero), it should return SUCCESS along with a trivial
- * FLUSH_COMPLETE event added to the event stream.
- * This applies to all sensors other than one-shot sensors.
- * If the sensor is a one-shot sensor, flush must return BAD_VALUE and not
- * generate any flush complete metadata.
- * If the sensor is not active at the time flush() is called, flush() should
- * return BAD_VALUE.
- * Returns OK on success and BAD_VALUE if sensorHandle is invalid.
+ * FIFO for the specified sensor and flushes the FIFO. If the FIFO is empty
+ * or if the sensor doesn't support batching (FIFO size zero), return
+ * SUCCESS and add a trivial FLUSH_COMPLETE event added to the event stream.
+ * This applies to all sensors other than one-shot sensors. If the sensor
+ * is a one-shot sensor, flush must return BAD_VALUE and not generate any
+ * flush complete metadata. If the sensor is not active at the time flush()
+ * is called, flush() return BAD_VALUE.
+ *
+ * @param sensorHandle handle of sensor to be flushed.
+ * @return result OK on success and BAD_VALUE if sensorHandle is invalid.
*/
flush(int32_t sensorHandle) generates (Result result);
@@ -145,8 +159,8 @@
* Unregister direct report channel.
*
* Unregister a direct channel previously registered using
- * registerDirectChannel. If there is still active sensor report configured
- * in the direct channel, HAL should remove them.
+ * registerDirectChannel, and remove all active sensor report configured in
+ * still active sensor report configured in the direct channel.
*
* @param channelHandle handle of direct channel to be unregistered.
* @return result OK if direct report is supported; INVALID_OPERATION
diff --git a/sensors/1.0/default/Sensors.cpp b/sensors/1.0/default/Sensors.cpp
index d79f5c7..f9f1ca6 100644
--- a/sensors/1.0/default/Sensors.cpp
+++ b/sensors/1.0/default/Sensors.cpp
@@ -102,7 +102,7 @@
return mInitCheck;
}
-Return<void> Sensors::getSensorsList(getSensorsList_cb _aidl_cb) {
+Return<void> Sensors::getSensorsList(getSensorsList_cb _hidl_cb) {
sensor_t const *list;
size_t count = mSensorModule->get_sensors_list(mSensorModule, &list);
@@ -116,7 +116,7 @@
convertFromSensor(*src, dst);
}
- _aidl_cb(out);
+ _hidl_cb(out);
return Void();
}
@@ -151,12 +151,12 @@
sampling_period_ns));
}
-Return<void> Sensors::poll(int32_t maxCount, poll_cb _aidl_cb) {
+Return<void> Sensors::poll(int32_t maxCount, poll_cb _hidl_cb) {
hidl_vec<Event> out;
hidl_vec<SensorInfo> dynamicSensorsAdded;
if (maxCount <= 0) {
- _aidl_cb(Result::BAD_VALUE, out, dynamicSensorsAdded);
+ _hidl_cb(Result::BAD_VALUE, out, dynamicSensorsAdded);
return Void();
}
@@ -168,7 +168,7 @@
maxCount);
if (err < 0) {
- _aidl_cb(ResultFromStatus(err), out, dynamicSensorsAdded);
+ _hidl_cb(ResultFromStatus(err), out, dynamicSensorsAdded);
return Void();
}
@@ -199,7 +199,7 @@
out.resize(count);
convertFromSensorEvents(err, data.get(), &out);
- _aidl_cb(Result::OK, out, dynamicSensorsAdded);
+ _hidl_cb(Result::OK, out, dynamicSensorsAdded);
return Void();
}
@@ -235,10 +235,10 @@
}
Return<void> Sensors::registerDirectChannel(
- const SharedMemInfo& mem, registerDirectChannel_cb _aidl_cb) {
+ const SharedMemInfo& mem, registerDirectChannel_cb _hidl_cb) {
//TODO(b/30985702): finish implementation
(void) mem;
- _aidl_cb(Result::INVALID_OPERATION, -1);
+ _hidl_cb(Result::INVALID_OPERATION, -1);
return Void();
}
diff --git a/sensors/1.0/default/Sensors.h b/sensors/1.0/default/Sensors.h
index abe7f43..a33f283 100644
--- a/sensors/1.0/default/Sensors.h
+++ b/sensors/1.0/default/Sensors.h
@@ -32,7 +32,7 @@
status_t initCheck() const;
- Return<void> getSensorsList(getSensorsList_cb _aidl_cb) override;
+ Return<void> getSensorsList(getSensorsList_cb _hidl_cb) override;
Return<Result> setOperationMode(OperationMode mode) override;
@@ -55,7 +55,7 @@
Return<Result> injectSensorData(const Event& event) override;
Return<void> registerDirectChannel(
- const SharedMemInfo& mem, registerDirectChannel_cb _aidl_cb) override;
+ const SharedMemInfo& mem, registerDirectChannel_cb _hidl_cb) override;
Return<Result> unregisterDirectChannel(int32_t channelHandle) override;
diff --git a/sensors/1.0/types.hal b/sensors/1.0/types.hal
index 6c72c39..3527106 100644
--- a/sensors/1.0/types.hal
+++ b/sensors/1.0/types.hal
@@ -99,7 +99,7 @@
* different rates independently of each other.
*
* Note: Proximity sensor and significant motion sensor which were defined in
- * previous releases are also wake-up sensors and should be treated as such.
+ * previous releases are also wake-up sensors and must be treated as such.
* Wake-up one-shot sensors like SIGNIFICANT_MOTION cannot be batched, hence
* the text about batch above doesn't apply to them. See the definitions of
* SENSOR_TYPE_PROXIMITY and SENSOR_TYPE_SIGNIFICANT_MOTION for more info.
@@ -364,7 +364,7 @@
* when heart_rate.bpm or heart_rate.status have changed since the last
* event. In particular, upon the first activation, unless the device is
* known to not be on the body, the status field of the first event must be
- * set to SENSOR_STATUS_UNRELIABLE. The event should be generated no faster
+ * set to SENSOR_STATUS_UNRELIABLE. The event must not be generated faster
* than every period_ns passed to setDelay() or to batch().
* See the definition of the on-change reporting mode for more information.
*
@@ -380,7 +380,7 @@
* reporting-mode: special (setDelay has no impact)
*
* A sensor of this type generates an event each time a tilt event is
- * detected. A tilt event should be generated if the direction of the
+ * detected. A tilt event must be generated if the direction of the
* 2-seconds window average gravity changed by at least 35 degrees since the
* activation or the last trigger of the sensor.
*
@@ -395,16 +395,16 @@
* angle(reference_estimated_gravity, current_estimated_gravity)
* > 35 degrees
*
- * Large accelerations without a change in phone orientation should not
+ * Large accelerations without a change in phone orientation must not
* trigger a tilt event.
* For example, a sharp turn or strong acceleration while driving a car
- * should not trigger a tilt event, even though the angle of the average
+ * must not trigger a tilt event, even though the angle of the average
* acceleration might vary by more than 35 degrees.
*
* Typically, this sensor is implemented with the help of only an
* accelerometer. Other sensors can be used as well if they do not increase
* the power consumption significantly. This is a low power sensor that
- * should allow the AP to go into suspend mode. Do not emulate this sensor
+ * must allow the AP to go into suspend mode. Do not emulate this sensor
* in the HAL.
* Like other wake up sensors, the driver is expected to a hold a wake_lock
* with a timeout of 200 ms while reporting this event. The only allowed
@@ -440,7 +440,7 @@
* reporting-mode: one-shot
*
* A sensor enabling briefly turning the screen on to enable the user to
- * glance content on screen based on a specific motion. The device should
+ * glance content on screen based on a specific motion. The device must
* turn the screen off after a few moments.
*
* When this sensor triggers, the device turns the screen on momentarily
@@ -491,7 +491,7 @@
* SENSOR_TYPE_DEVICE_ORIENTATION
* reporting-mode: on-change
*
- * The current orientation of the device. The value should be reported in
+ * The current orientation of the device. The value is reported in
* the "scalar" element of the EventPayload in Event. The
* only values that can be reported are (please refer to Android Sensor
* Coordinate System to understand the X and Y axis direction with respect
@@ -505,17 +505,17 @@
* (X axis is vertical and points down)
*
* Moving the device to an orientation where the Z axis is vertical (either
- * up or down) should not cause a new event to be reported.
+ * up or down) must not cause a new event to be reported.
*
* To improve the user experience of this sensor, it is recommended to
* implement some physical (i.e., rotation angle) and temporal (i.e., delay)
- * hysteresis.
- * In other words, minor or transient rotations should not cause a new event
- * to be reported.
+ * hysteresis. In other words, minor or transient rotations must not cause
+ * a new event to be reported.
*
- * This sensor should only be implemented with the help of an accelerometer.
- * This is a low power sensor that should reduce the number of interrupts of
- * the AP. Do not emulate this sensor in the HAL.
+ * This is a low power sensor that intended to reduce interrupts of
+ * application processor and thus allow it to go sleep. Use hardware
+ * implementation based on low power consumption sensors, such as
+ * accelerometer. Device must not emulate this sensor in the HAL.
*
* Both wake-up and non wake-up versions are useful.
*/
@@ -544,8 +544,8 @@
* trigger mode: one shot
*
* A sensor of this type returns an event if the device is still/stationary
- * for a while. The period of time to monitor for statinarity should be
- * greater than 5 seconds, and less than 10 seconds.
+ * for a while. The period of time to monitor for stationarity must be
+ * greater than 5 seconds. The latency must be less than 10 seconds.
*
* Stationarity here refers to absolute stationarity. eg: device on desk.
*
@@ -558,8 +558,8 @@
* trigger mode: one shot
*
* A sensor of this type returns an event if the device is not still for
- * a while. The period of time to monitor for statinarity should be greater
- * than 5 seconds, and less than 10 seconds.
+ * for a while. The period of time to monitor for stationarity must be
+ * greater than 5 seconds. The latency must be less than 10 seconds.
*
* Motion here refers to any mechanism in which the device is causes to be
* moved in its inertial frame. eg: Pickin up the device and walking with it
@@ -582,9 +582,8 @@
* and ECG signal.
*
* The sensor is not expected to be optimized for latency. As a guide, a
- * latency of up to 10 seconds is acceptable. However the timestamp attached
- * to the event should be accurate and should correspond to the time the
- * peak occured.
+ * latency of up to 10 seconds is acceptable. However, the timestamp attached
+ * to the event must be accuratly correspond to the time the peak occured.
*
* The sensor event contains a parameter for the confidence in the detection
* of the peak where 0.0 represent no information at all, and 1.0 represents
@@ -601,30 +600,30 @@
* present in one sensor HAL implementation and presence of a sensor of this
* type in sensor HAL implementation indicates that this sensor HAL supports
* dynamic sensor feature. Operations, such as batch, activate and setDelay,
- * to this special purpose sensor should be treated as no-op and return
+ * to this special purpose sensor must be treated as no-op and return
* successful; flush() also has to generate flush complete event as if this
* is a sensor that does not support batching.
*
* A dynamic sensor connection indicates connection of a physical device or
* instantiation of a virtual sensor backed by algorithm; and a dynamic
* sensor disconnection indicates the the opposite. A sensor event of
- * SENSOR_TYPE_DYNAMIC_SENSOR_META type should be delivered regardless of
+ * SENSOR_TYPE_DYNAMIC_SENSOR_META type must be delivered regardless of
* the activation status of the sensor in the event of dynamic sensor
* connection and disconnection. In the sensor event, besides the common
* data entries, "dynamic_sensor_meta", which includes fields for connection
* status, handle of the sensor involved, pointer to sensor_t structure and
- * a uuid field, should be populated.
+ * a uuid field, must be populated.
*
* At a dynamic sensor connection event, fields of sensor_t structure
- * referenced by a pointer in dynamic_sensor_meta should be filled as if it
+ * referenced by a pointer in dynamic_sensor_meta must be filled as if it
* was regular sensors. Sensor HAL is responsible for recovery of memory if
* the corresponding data is dynamicially allocated. However, the the
* pointer must be valid until the first activate call to the sensor
* reported in this connection event. At a dynamic sensor disconnection,
- * the sensor_t pointer should be NULL.
+ * the sensor_t pointer must be NULL.
*
- * The sensor handle assigned to dynamic sensors should never be the same as
- * that of any regular static sensors, and should be unique until next boot.
+ * The sensor handle assigned to dynamic sensors must never be the same as
+ * that of any regular static sensors, and must be unique until next boot.
* In another word, if a handle h is used for a dynamic sensor A, that same
* number cannot be used for the same dynamic sensor A or another dynamic
* sensor B even after disconnection of A until reboot.
@@ -632,7 +631,7 @@
* The UUID field will be used for identifying the sensor in addition to
* name, vendor and version and type. For physical sensors of the same
* model, all sensors will have the same values in sensor_t, but the UUID
- * should be unique and persistent for each individual unit. An all zero
+ * must be unique and persistent for each individual unit. An all zero
* UUID indicates it is not possible to differentiate individual sensor
* unit.
*
@@ -650,7 +649,7 @@
* etc.
*
* This type will never bind to a sensor. In other words, no sensor in the
- * sensor list should be of the type SENSOR_TYPE_ADDITIONAL_INFO. If a
+ * sensor list can have the type SENSOR_TYPE_ADDITIONAL_INFO. If a
* sensor HAL supports sensor additional information feature, it reports
* sensor_event_t with "sensor" field set to handle of the reporting sensor
* and "type" field set to SENSOR_TYPE_ADDITIONAL_INFO. Delivery of
@@ -909,16 +908,12 @@
};
struct HeartRate {
- /* Heart rate in beats per minute.
- * Set to 0 when status is SENSOR_STATUS_UNRELIABLE or ..._NO_CONTACT
+ /* Heart rate in beats per minute. Set to 0 when status is
+ * SENSOR_STATUS_UNRELIABLE or SENSOR_STATUS_NO_CONTACT.
*/
float bpm;
- /* Status of the sensor for this reading. Set to one SENSOR_STATUS_...
- * Note that this value should only be set for sensors that explicitly
- * define the meaning of this field. This field is not piped through the
- * framework for other sensors.
- */
+ /* Status of the heart rate sensor for this reading. */
SensorStatus status;
};
@@ -936,7 +931,7 @@
int32_t sensorHandle;
/* UUID of a dynamic sensor (using RFC 4122 byte order)
- * For UUID 12345678-90AB-CDEF-1122-334455667788 the uuid field should be
+ * For UUID 12345678-90AB-CDEF-1122-334455667788 the uuid field is
* initialized as:
* {0x12, 0x34, 0x56, 0x78, 0x90, 0xAB, 0xCD, 0xEF, 0x11, ...}
*/
@@ -1035,9 +1030,6 @@
int32_t serial;
union Payload {
- /* for each frame, a single data type, either int32_t or float,
- * should be used.
- */
int32_t[14] data_int32;
float[14] data_float;
} u;
@@ -1119,9 +1111,14 @@
/**
* Direct report rate level definition. Except for SENSOR_DIRECT_RATE_STOP, each
* rate level covers the range (55%, 220%] * nominal report rate. For example,
- * if config direct report specify a rate level SENSOR_DIRECT_RATE_FAST, sensor
- * hardware should report event at a rate greater than 110Hz, and less or equal
- * to 440Hz.
+ * if config direct report specify a rate level SENSOR_DIRECT_RATE_FAST, it is
+ * legal for sensor hardware to report event at a rate greater than 110Hz, and
+ * less or equal to 440Hz. Note that rate has to remain steady without variation
+ * before new rate level is configured, i.e. if a sensor is configured to
+ * SENSOR_DIRECT_RATE_FAST and starts to report event at 256Hz, it cannot
+ * change rate to 128Hz after a few seconds of running even if 128Hz is also in
+ * the legal range of SENSOR_DIRECT_RATE_FAST. Thus, it is recommended to
+ * associate report rate with RateLvel statically for single sensor.
*/
@export(name="direct_rate_level_t", value_prefix="SENSOR_DIRECT_RATE_")
enum RateLevel : int32_t {
@@ -1144,9 +1141,10 @@
/**
- * Direct channel lock-free queue format, this defines how the shared memory
- * should be interpreted by both sensor hardware and application. See struct
- * SharedMemInfo.
+ * Direct channel lock-free queue format, this defines how the shared memory is
+ * interpreted by both sensor hardware and application.
+ *
+ * @see SharedMemInfo.
*/
@export(name="direct_format_t", value_prefix="SENSOR_DIRECT_FMT_")
enum SharedMemFormat : int32_t {