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 17package android.hardware.gnss@1.0; 18 19import 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 41interface 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}; 147