gnss/1.0/IGnssBatching.hal

   1 /*
   2  * Copyright (C) 2016 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package android.hardware.gnss@1.0;
  18
  19 import IGnssBatchingCallback;
  20
  21 /**
  22  * Extended interface for GNSS Batching support.
  23  *
  24  * If this interface is supported, this batching request must be able to run in
  25  * parallel with, or without, non-batched location requested by the
  26  * IGnss start() & stop() - i.e. both requests must be handled independently,
  27  * and not interfere with each other.
  28  *
  29  * For example, if a 1Hz continuous output is underway on the IGnssCallback,
  30  * due to an IGnss start() operation,
  31  * and then a IGnssBatching start() is called for a location every 10
  32  * seconds, the newly added batching request must not disrupt the 1Hz
  33  * continuous location output on the IGnssCallback.
  34  *
  35  * As with GNSS Location outputs, source of location must be GNSS satellite
  36  * measurements, optionally using interial and baro sensors to improve
  37  * relative motion filtering. No additional absolute positioning information,
  38  * such as WiFi derived location, may be mixed with the GNSS information.
  39  */
  40
  41 interface IGnssBatching {
  42     /**
  43      * Enum which holds the bit masks for batching control.
  44      */
  45     @export(name="", value_prefix="FLP_BATCH_")
  46     enum Flag : uint8_t {
  47         /**
  48          * If this flag is set, the hardware implementation
  49          * must wake up the application processor when the FIFO is full, and
  50          * call IGnssBatchingCallback to return the locations.
  51          *
  52          * If the flag is not set, the hardware implementation must drop
  53          * the oldest data when the FIFO is full.
  54          */
  55         WAKEUP_ON_FIFO_FULL = 0x01
  56     };
  57
  58     struct Options {
  59         /**
  60          * Time interval between samples in the location batch, in nano
  61          * seconds.
  62          */
  63         int64_t periodNanos;
  64
  65         /**
  66          * Flags controlling how batching should behave.
  67          */
  68         bitfield<Flag> flags;
  69     };
  70
  71     /**
  72      * Opens the interface and provides the callback routines
  73      * to the implementation of this interface.
  74      *
  75      * @param callback Callback interface for IGnssBatching.
  76      *
  77      * @return success Returns true on success.
  78      */
  79     init(IGnssBatchingCallback callback) generates (bool success);
  80
  81     /**
  82      * Return the batch size (in number of GnssLocation objects)
  83      * available in this hardware implementation.
  84      *
  85      * If the available size is variable, for example, based on other operations
  86      * consuming memory, this is the minimum size guaranteed to be available
  87      * for batching operations.
  88      *
  89      * This may, for example, be used by the upper layer, to decide on the
  90      * batching interval and whether the AP should be woken up or not.
  91      *
  92      * @return batchSize number of location objects supported per batch
  93      */
  94     getBatchSize() generates (uint16_t batchSize);
  95
  96     /**
  97      * Start batching locations. This API is primarily used when the AP is
  98      * asleep and the device can batch locations in the hardware.
  99      *
 100      * IGnssBatchingCallback is used to return the locations.
 101      *
 102      * When the buffer is full and WAKEUP_ON_FIFO_FULL is used,
 103      * IGnssBatchingCallback must be called to return the locations.
 104      *
 105      * When the buffer is full and WAKEUP_ON_FIFO_FULL is not set,
 106      * the oldest location object is dropped. In this case the AP must not be
 107      * woken up. The AP would then generally be responsible for using
 108      * flushBatchedLocation to explicitly ask for the location as needed,
 109      * to avoid it being dropped.
 110      *
 111      * @param options See struct Options definition.
 112      *
 113      * @return success Returns true on success.
 114      */
 115     start(Options options) generates (bool success);
 116
 117     /**
 118      * Retrieve all batched locations currently stored.
 119      *
 120      * IGnssBatchingCallback is used to return the location.
 121      *
 122      * IGnssBatchingCallback must be called in response, even if there are
 123      * no locations to flush (in which case the Location vector must be empty).
 124      *
 125      * Subsequent calls to flushBatchedLocation
 126      * must not return any of the locations returned in this call.
 127      */
 128     flush();
 129
 130     /**
 131      * Stop batching.
 132      *
 133      * @return success Returns true on success.
 134      */
 135     stop() generates (bool success);
 136
 137     /**
 138      * Closes the interface. If any batch operations are in progress,
 139      * they must be stopped.  If any locations are in the hardware batch, they
 140      * must be deleted (and not sent via callback.)
 141      *
 142      * init() may be called again, after this, if the interface is to be restored
 143      */
 144     cleanup();
 145
 146 };