GnssBatching API, port from Fused Location
New HAL APIs for Gnss location batches,
still to be connected (default implementation)
similarly to this aspect of fused_location.h,
initially as a single client system API.
Bug: 31974439
Test: Ensured it builds and runs GPS & FLP (in Test app & maps)
Change-Id: I27d3fd2cffad25039b006e60c4496a440dc86c13
diff --git a/gnss/1.0/IGnssBatching.hal b/gnss/1.0/IGnssBatching.hal
new file mode 100644
index 0000000..4f0695d
--- /dev/null
+++ b/gnss/1.0/IGnssBatching.hal
@@ -0,0 +1,144 @@
+/*
+ * Copyright (C) 2016 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.hardware.gnss@1.0;
+
+import IGnssBatchingCallback;
+
+/*
+ * Extended interface for GNSS Batching support.
+ *
+ * If this interface is supported, this batching request must be able to run in
+ * parallel with, or without, non-batched location requested by the
+ * IGnss start() & stop() - i.e. both requests must be handled independently,
+ * and not interfere with each other.
+ *
+ * For example, if a 1Hz continuous output is underway on the IGnssCallback,
+ * due to an IGnss start() operation,
+ * and then a IGnssBatching start() is called for a location every 10
+ * seconds, the newly added batching request must not disrupt the 1Hz
+ * continuous location output on the IGnssCallback.
+ *
+ * As with GNSS Location outputs, source of location must be GNSS satellite
+ * measurements, optionally using interial and baro sensors to improve
+ * relative motion filtering. No additional absolute positioning information,
+ * such as WiFi derived location, may be mixed with the GNSS information.
+ */
+
+interface IGnssBatching {
+ /*
+ * Enum which holds the bit masks for batching control.
+ */
+ enum Flag : uint8_t {
+ /*
+ * If this flag is set, the hardware implementation
+ * must wake up the application processor when the FIFO is full, and
+ * call IGnssBatchingCallback to return the locations.
+ *
+ * If the flag is not set, the hardware implementation must drop
+ * the oldest data when the FIFO is full.
+ */
+ WAKEUP_ON_FIFO_FULL = 0x01
+ };
+
+ struct Options {
+ /*
+ * Time interval between samples in the location batch, in nano
+ * seconds.
+ */
+ int64_t periodNanos;
+
+ /*
+ * Flags controlling how batching should behave.
+ */
+ bitfield<Flag> flags;
+ };
+
+ /*
+ * Opens the interface and provides the callback routines
+ * to the implementation of this interface.
+ *
+ * @param callback Callback interface for IGnssBatching.
+ *
+ * @return success Returns true on success.
+ */
+ init(IGnssBatchingCallback callback) generates (bool success);
+
+ /*
+ * Return the batch size (in number of GnssLocation objects)
+ * available in this hardware implementation.
+ *
+ * If the available size is variable, for example, based on other operations
+ * consuming memory, this is the minimum size guaranteed to be available
+ * for batching operations.
+ *
+ * This may, for example, be used by the upper layer, to decide on the
+ * batching interval and whether the AP should be woken up or not.
+ *
+ * @return batchSize number of location objects supported per batch
+ */
+ getBatchSize() generates (uint16_t batchSize);
+
+ /*
+ * Start batching locations. This API is primarily used when the AP is
+ * asleep and the device can batch locations in the hardware.
+ *
+ * IGnssBatchingCallback is used to return the locations.
+ *
+ * When the buffer is full and WAKEUP_ON_FIFO_FULL is used,
+ * IGnssBatchingCallback must be called to return the locations.
+ *
+ * When the buffer is full and WAKEUP_ON_FIFO_FULL is not set,
+ * the oldest location object is dropped. In this case the AP must not be
+ * woken up. The AP would then generally be responsible for using
+ * flushBatchedLocation to explicitly ask for the location as needed,
+ * to avoid it being dropped.
+ *
+ * @param options See struct Options definition.
+ *
+ * @return success Returns true on success.
+ */
+ start(Options options) generates (bool success);
+
+ /**
+ * Retrieve all batched locations currently stored.
+ *
+ * IGnssBatchingCallback is used to return the location.
+ *
+ * IGnssBatchingCallback must be called in response, even if there are
+ * no locations to flush (in which case the Location vector must be empty).
+ *
+ * Subsequent calls to flushBatchedLocation
+ * must not return any of the locations returned in this call.
+ */
+ flush();
+
+ /**
+ * Stop batching.
+ *
+ * @return success Returns true on success.
+ */
+ stop() generates (bool success);
+
+ /**
+ * Closes the interface. If any batch operations are in progress,
+ * they should be stopped.
+ *
+ * init() may be called again, after this, if the interface is to be restored
+ */
+ cleanup();
+
+};