Update comments on EVS 1.0 interfaces (1d0f024b) · Commits · e / os / android_hardware_interfaces

automotive/evs/1.0/IEvsCamera.hal

+23 −8

Original line number	Diff line number	Diff line
		@@ -16,7 +16,6 @@

		package android.hardware.automotive.evs@1.0;

		import types;
		import IEvsCameraStream;


		@@ -28,8 +27,8 @@ interface IEvsCamera {
		/**
		* 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 @@ interface IEvsCamera {
		* 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 calls with various events
		* including new image frame ready until stopVideoStream() is called.
		*
		* The IEvsCameraStream must begin receiving periodic calls with new image
		* frames 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 @@ interface IEvsCamera {
		* 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 @@ interface IEvsCamera {
		* 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 @@ interface IEvsCamera {
		* 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);
		};

automotive/evs/1.0/IEvsCameraStream.hal

+2 −0

Original line number	Diff line number	Diff line
		@@ -31,6 +31,8 @@ interface IEvsCameraStream {
		* 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);
		};

automotive/evs/1.0/IEvsDisplay.hal

+16 −5

Original line number	Diff line number	Diff line
		@@ -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 @@ interface IEvsDisplay {
		* 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 @@ interface IEvsDisplay {
		* 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 @@ interface IEvsDisplay {
		* 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 @@ interface IEvsDisplay {
		/**
		* 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 @@ interface IEvsDisplay {
		* 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);
		};

automotive/evs/1.0/IEvsEnumerator.hal

+13 −6

Original line number	Diff line number	Diff line
		@@ -16,7 +16,6 @@

		package android.hardware.automotive.evs@1.0;

		import types;
		import IEvsCamera;
		import IEvsDisplay;

		@@ -28,6 +27,8 @@ interface IEvsEnumerator {

		/**
		* 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 @@ interface IEvsEnumerator {
		* 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 @@ interface IEvsEnumerator {
		*
		* 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 @@ interface IEvsEnumerator {
		* 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 @@ interface IEvsEnumerator {
		*
		* 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 @@ interface IEvsEnumerator {
		* 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);
		};

automotive/evs/1.0/types.hal

+54 −16

Original line number	Diff line number	Diff line
		@@ -24,8 +24,15 @@ package android.hardware.automotive.evs@1.0;
		* 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 @@ struct CameraDesc {
		* 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 @@ struct DisplayDesc {
		* 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 @@ struct BufferDesc {
		* 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
		};