Update comments on EVS 1.0 interfaces
This change fixes hidl-lint errors and warnings in EVS 1.0 interface
definitions.
Bug: 135472573
Change-Id: I4b6b5df792875a8dde2ee146f88fb401a4d5e860
Signed-off-by: Changyeon Jo <changyeon@google.com>
diff --git a/automotive/evs/1.0/IEvsCamera.hal b/automotive/evs/1.0/IEvsCamera.hal
index dbcaf92..464dafb 100644
--- a/automotive/evs/1.0/IEvsCamera.hal
+++ b/automotive/evs/1.0/IEvsCamera.hal
@@ -16,7 +16,6 @@
package android.hardware.automotive.evs@1.0;
-import types;
import IEvsCameraStream;
@@ -28,8 +27,8 @@
/**
* Returns the ID of this camera.
*
- * Returns the description of this camera. This must be the same value as reported
- * by EvsEnumerator::getCamerList().
+ * @return info The description of this camera. This must be the same value as
+ * reported by EvsEnumerator::getCameraList().
*/
getCameraInfo() generates (CameraDesc info);
@@ -43,16 +42,20 @@
* in which case buffers should be added or removed from the chain as appropriate.
* If no call is made to this entry point, the IEvsCamera must support at least one
* frame by default. More is acceptable.
- * BUFFER_NOT_AVAILABLE is returned if the implementation cannot support the
- * requested number of concurrent frames.
+ *
+ * @param bufferCount Number of buffers the client of IEvsCamera may hold concurrently.
+ * @return result EvsResult::OK is returned if this call is successful.
*/
setMaxFramesInFlight(uint32_t bufferCount) generates (EvsResult result);
/**
- * Request delivery of EVS camera frames from this camera.
+ * Request to start EVS camera stream from this camera.
*
- * The IEvsCameraStream must begin receiving periodic calls with new image
- * frames until stopVideoStream() is called.
+ * The IEvsCameraStream must begin receiving calls with various events
+ * including new image frame ready until stopVideoStream() is called.
+ *
+ * @param receiver IEvsCameraStream implementation.
+ * @return result EvsResult::OK is returned if this call is successful.
*/
startVideoStream(IEvsCameraStream receiver) generates (EvsResult result);
@@ -64,6 +67,8 @@
* A small, finite number of buffers are available (possibly as small
* as one), and if the supply is exhausted, no further frames may be
* delivered until a buffer is returned.
+ *
+ * @param buffer A buffer to be returned.
*/
oneway doneWithFrame(BufferDesc buffer);
@@ -83,6 +88,11 @@
* The values allowed for opaqueIdentifier are driver specific,
* but no value passed in may crash the driver. The driver should
* return 0 for any unrecognized opaqueIdentifier.
+ *
+ * @param opaqueIdentifier An unique identifier of the information to
+ * request.
+ * @return value Requested information. Zero is returned if the
+ * driver does not recognize a given identifier.
*/
getExtendedInfo(uint32_t opaqueIdentifier) generates (int32_t value);
@@ -94,6 +104,11 @@
* in order to function in a default state.
* INVALID_ARG is returned if the opaqueValue is not meaningful to
* the driver implementation.
+ *
+ * @param opaqueIdentifier An unique identifier of the information to
+ * program.
+ * opaqueValue A value to program.
+ * @return result EvsResult::OK is returned if this call is successful.
*/
setExtendedInfo(uint32_t opaqueIdentifier, int32_t opaqueValue) generates (EvsResult result);
};
diff --git a/automotive/evs/1.0/IEvsCameraStream.hal b/automotive/evs/1.0/IEvsCameraStream.hal
index 4e743b2..ec18f6a 100644
--- a/automotive/evs/1.0/IEvsCameraStream.hal
+++ b/automotive/evs/1.0/IEvsCameraStream.hal
@@ -31,6 +31,8 @@
* When the last frame in the stream has been delivered, a NULL bufferHandle
* must be delivered, signifying the end of the stream. No further frame
* deliveries may happen thereafter.
+ *
+ * @param buffer a buffer descriptor of a delivered image frame.
*/
oneway deliverFrame(BufferDesc buffer);
};
diff --git a/automotive/evs/1.0/IEvsDisplay.hal b/automotive/evs/1.0/IEvsDisplay.hal
index 12541f3..72f767e 100644
--- a/automotive/evs/1.0/IEvsDisplay.hal
+++ b/automotive/evs/1.0/IEvsDisplay.hal
@@ -16,8 +16,6 @@
package android.hardware.automotive.evs@1.0;
-import types;
-
/**
* Represents a single camera and is the primary interface for capturing images.
@@ -28,6 +26,9 @@
* Returns basic information about the EVS display provided by the system.
*
* See the description of the DisplayDesc structure for details.
+ *
+ * @return info The description of this display. Please see the description
+ * of the DisplayDesc structure for details.
*/
getDisplayInfo() generates (DisplayDesc info);
@@ -42,6 +43,9 @@
* video. When the display is no longer required, the client is expected to request
* the NOT_VISIBLE state after passing the last video frame.
* Returns INVALID_ARG if the requested state is not a recognized value.
+ *
+ * @param state Desired new DisplayState.
+ * @return result EvsResult::OK is returned if this call is successful.
*/
setDisplayState(DisplayState state) generates (EvsResult result);
@@ -54,6 +58,8 @@
* the logic responsible for changing display states should generally live above
* the device layer, making it undesirable for the HAL implementation to spontaneously
* change display states.
+ *
+ * @return state Current DisplayState of this Display.
*/
getDisplayState() generates (DisplayState state);
@@ -61,9 +67,11 @@
/**
* This call returns a handle to a frame buffer associated with the display.
*
- * The returned buffer may be locked and written to by software and/or GL. This buffer
- * must be returned via a call to returnTargetBufferForDisplay() even if the
- * display is no longer visible.
+ * @return buffer A handle to a frame buffer. The returned buffer may be
+ * locked and written to by software and/or GL. This buffer
+ * must be returned via a call to
+ * returnTargetBufferForDisplay() even if the display is no
+ * longer visible.
*/
getTargetBuffer() generates (BufferDesc buffer);
@@ -75,6 +83,9 @@
* There is no maximum time the caller may hold onto the buffer before making this
* call. The buffer may be returned at any time and in any DisplayState, but all
* buffers are expected to be returned before the IEvsDisplay interface is destroyed.
+ *
+ * @param buffer A buffer handle to the frame that is ready for display.
+ * @return result EvsResult::OK is returned if this call is successful.
*/
returnTargetBufferForDisplay(BufferDesc buffer) generates (EvsResult result);
};
diff --git a/automotive/evs/1.0/IEvsEnumerator.hal b/automotive/evs/1.0/IEvsEnumerator.hal
index ee51e7e..e5633df 100644
--- a/automotive/evs/1.0/IEvsEnumerator.hal
+++ b/automotive/evs/1.0/IEvsEnumerator.hal
@@ -16,7 +16,6 @@
package android.hardware.automotive.evs@1.0;
-import types;
import IEvsCamera;
import IEvsDisplay;
@@ -28,6 +27,8 @@
/**
* Returns a list of all EVS cameras available to the system
+ *
+ * @return cameras A list of cameras availale for EVS service.
*/
getCameraList() generates (vec<CameraDesc> cameras);
@@ -37,9 +38,9 @@
* Given a camera's unique cameraId from CameraDesc, returns the
* IEvsCamera interface associated with the specified camera. When
* done using the camera, the caller may release it by calling closeCamera().
- * Note: Reliance on the sp<> going out of scope is not recommended
- * because the resources may not be released right away due to asynchronos
- * behavior in the hardware binder (ref b/36122635).
+ *
+ * @param cameraId A unique identifier of the camera.
+ * @return carCamera EvsCamera object associated with a given cameraId.
*/
openCamera(string cameraId) generates (IEvsCamera carCamera);
@@ -48,6 +49,8 @@
*
* When the IEvsCamera object is no longer required, it must be released.
* NOTE: Video streaming must be cleanly stopped before making this call.
+ *
+ * @param carCamera EvsCamera object to be closed.
*/
closeCamera(IEvsCamera carCamera);
@@ -60,8 +63,8 @@
* the old instance shall be closed and give the new caller exclusive
* access.
* When done using the display, the caller may release it by calling closeDisplay().
- * TODO(b/36122635) Reliance on the sp<> going out of scope is not recommended because the
- * resources may not be released right away due to asynchronos behavior in the hardware binder.
+ *
+ * @return display EvsDisplay object to be used.
*/
openDisplay() generates (IEvsDisplay display);
@@ -70,6 +73,8 @@
*
* When the IEvsDisplay object is no longer required, it must be released.
* NOTE: All buffers must have been returned to the display before making this call.
+ *
+ * @param display EvsDisplay object to be closed.
*/
closeDisplay(IEvsDisplay display);
@@ -80,6 +85,8 @@
* the actual state of the active display. This call is replicated on the IEvsEnumerator
* interface in order to allow secondary clients to monitor the state of the EVS display
* without acquiring exclusive ownership of the display.
+ *
+ * @return state Current DisplayState of this Display.
*/
getDisplayState() generates (DisplayState state);
};
diff --git a/automotive/evs/1.0/types.hal b/automotive/evs/1.0/types.hal
index 7cebf6d..1efd5eb 100644
--- a/automotive/evs/1.0/types.hal
+++ b/automotive/evs/1.0/types.hal
@@ -24,8 +24,15 @@
* EVS camera in the system.
*/
struct CameraDesc {
+ /* Unique identifier for camera devices. This may be a path to detected
+ * camera device; for example, "/dev/video0".
+ */
string cameraId;
- uint32_t vendorFlags; // Opaque value from driver
+
+ /* Opaque value from driver. Vendor may use this field to store additional
+ * information; for example, sensor and bridge chip id.
+ */
+ uint32_t vendorFlags;
};
@@ -38,8 +45,11 @@
* presentation device.
*/
struct DisplayDesc {
+ /* Unique identifier for the display */
string displayId;
- uint32_t vendorFlags; // Opaque value from driver
+
+ /* Opaque value from driver */
+ uint32_t vendorFlags;
};
@@ -56,14 +66,31 @@
* Specifically consider if format and/or usage should become enumerated types.
*/
struct BufferDesc {
- uint32_t width; // Units of pixels
- uint32_t height; // Units of pixels
- uint32_t stride; // Units of pixels to match gralloc
- uint32_t pixelSize; // Units of bytes
- uint32_t format; // May contain values from android_pixel_format_t
- uint32_t usage; // May contain values from from Gralloc.h
- uint32_t bufferId; // Opaque value from driver
- handle memHandle; // gralloc memory buffer handle
+ /* A frame width in the units of pixels */
+ uint32_t width;
+
+ /* A frame height in the units of pixels */
+ uint32_t height;
+
+ /* A frame stride in the units of pixels, to match gralloc */
+ uint32_t stride;
+
+ /* The size of a pixel in the units of bytes */
+ uint32_t pixelSize;
+
+ /* The image format of the frame; may contain values from
+ * android_pixel_format_t
+ */
+ uint32_t format;
+
+ /* May contain values from Gralloc.h */
+ uint32_t usage;
+
+ /* Opaque value from driver */
+ uint32_t bufferId;
+
+ /* Gralloc memory buffer handle */
+ handle memHandle;
};
@@ -77,12 +104,23 @@
* presentation device.
*/
enum DisplayState : uint32_t {
- NOT_OPEN = 0, // Display has not been requested by any application
- NOT_VISIBLE, // Display is inhibited
- VISIBLE_ON_NEXT_FRAME, // Will become visible with next frame
- VISIBLE, // Display is currently active
- DEAD, // Driver is in an undefined state. Interface should be closed.
- NUM_STATES // Must be last
+ /* Display has not been requested by any application yet */
+ NOT_OPEN = 0,
+
+ /* Display is inhibited */
+ NOT_VISIBLE,
+
+ /* Will become visible with next frame */
+ VISIBLE_ON_NEXT_FRAME,
+
+ /* Display is currently active */
+ VISIBLE,
+
+ /* Driver is in an undefined state. Interface should be closed. */
+ DEAD,
+
+ /* Must be the last */
+ NUM_STATES
};