1/*
2 * Copyright 2020 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 [email protected];
18
19import @1.0::EvsResult;
20import UltrasonicsArrayDesc;
21import UltrasonicsDataFrameDesc;
22import IEvsUltrasonicsArrayStream;
23
24/**
25 * HAL interface for ultrasonics sensor array.
26 */
27interface IEvsUltrasonicsArray {
28   /**
29    * Returns the ultrasonic sensor array information.
30    *
31    * @return  info  The description of this ultrasonic array. This must be the
32    *                same value as reported by IEvsEnumerator::getUltrasonicsArrayList().
33    */
34   getUltrasonicArrayInfo() generates (UltrasonicsArrayDesc info);
35
36   /**
37    * Specifies the depth of the buffer chain the ultrasonic sensors is
38    * asked to support.
39    *
40    * Up to this many data frames may be held concurrently by the client of IEvsUltrasonicsArray.
41    * If this many frames have been delivered to the receiver without being returned
42    * by doneWithFrame, the stream must skip frames until a buffer is returned for reuse.
43    * It is legal for this call to come at any time, even while streams are already running,
44    * in which case buffers should be added or removed from the chain as appropriate.
45    * If no call is made to this entry point, the IEvsUltrasonicsArray must support at least one
46    * data frame by default. More is acceptable.
47    *
48    * @param  bufferCount Number of buffers the client of
49    *                     IEvsUltrasonicsArray may hold concurrently.
50    * @return result      EvsResult::OK is returned if this call is successful.
51    *                     Will return EvsResult::INVALID_ARG on invalid bufferCount.
52    */
53   setMaxFramesInFlight(uint32_t bufferCount) generates (EvsResult result);
54
55   /**
56    * Requests to start the stream.
57    *
58    * @param  stream Implementation of IEvsUltrasonicsArrayStream.
59    * @return result EvsResult::OK is returned if this call is successful. Returns
60    *                EvsResult::STREAM_ALREADY_RUNNING if stream is already running.
61    */
62   startStream(IEvsUltrasonicsArrayStream stream) generates (EvsResult result);
63
64   /**
65    * Requests to stop the delivery of the ultrasonic array data frames.
66    *
67    * Because delivery is asynchronous, frames may continue to arrive for
68    * some time after this call returns. Each must be returned until the
69    * closure of the stream is signaled to the IEvsCameraStream.
70    * This function cannot fail and is ignored if the stream isn't running.
71    */
72   stopStream();
73
74   /**
75    * Notifies the UltrasonicsDataDesc is consumed that was received from
76    * IEvsUltrasonicsArrayStream.
77    *
78    * @param  dataFrameDesc Ultrasonics data descriptor.
79    */
80    doneWithDataFrame(UltrasonicsDataFrameDesc dataFrameDesc);
81};
82