sdk/fidl/fuchsia.hardware.radar/radar.fidl - fuchsia - Git at Google

 // Copyright 2021 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 @available(added=7)
 library fuchsia.hardware.radar;
 using zx;

 /// Arbitrary limit on the number of VMOs in one call to `RegisterVmos()` or
 /// `UnregisterVmos()`; enough for ten seconds of radar data for the existing
 /// driver.
 const VMO_VECTOR_MAX_COUNT uint32 = 300;

 type StatusCode = strict enum {
     /// An unspecified error occurred (generally should not be used).
     UNSPECIFIED = 0;

     /// The request completed successfully.
     SUCCESS = 1;

     /// `Connect()` was called but the driver is busy handling another client.
     /// The other client will have to close its channel for the driver to become
     /// available again.
     ALREADY_BOUND = 2;

     /// `Connect()` encountered an error trying to bind to the provided server
     /// channel.
     BIND_ERROR = 3;

     /// The vectors passed to `RegisterVmos()` did not have the same size.
     INVALID_ARGS = 4;

     /// A VMO handle was invalid.
     VMO_BAD_HANDLE = 5;

     /// A VMO was already registered with this ID.
     VMO_ALREADY_REGISTERED = 6;

     /// No registered VMO was found for the given ID.
     VMO_NOT_FOUND = 7;

     /// A client VMO could not be written to or mapped due to insufficient
     /// permissions.
     VMO_ACCESS_DENIED = 8;

     /// A client VMO was smaller than the burst size (see `GetBurstSize()`).
     VMO_TOO_SMALL = 9;

     /// A burst was received, but no unlocked VMOs are available.
     OUT_OF_VMOS = 10;

     /// A burst was not received within the expected window.
     SENSOR_TIMEOUT = 11;

     /// An unspecified driver or sensor error was encountered.
     SENSOR_ERROR = 12;

     /// The radar driver or proxy was not in the correct state for this call.
     BAD_STATE = 13;
 };

 type Burst = struct {
     vmo_id uint32;
     timestamp zx.Time;
 };

 closed protocol RadarBurstReader {
     strict GetBurstProperties() -> (struct {
         size uint32;
         period zx.Duration;
     });

     /// Registers the VMOs for future use and associates them with vmo_ids,
     /// which can be used with `UnregisterVmos()` and `OnBurst()`. vmos will be
     /// mapped by the driver using `ZX_VM_PERM_WRITE`. The client should only
     /// read registered VMOs that are sent via `OnBurst()`. The size of vmo is
     /// assumed to be at least the burst size, and the sizes of `vmo_ids` and
     /// `vmos` must be the same.
     ///
     /// + request `vmo_ids` the ID numbers to associate with each VMO.
     /// + request `vmos` the VMO handles corresponding to each ID.
     /// * error one of the following `StatusCode` values:
     /// *     `INVALID_ARGS`: `vmo_ids` and `vmos` were of different sizes.
     /// *     `VMO_BAD_HANDLE`: A handle in `vmos` was invalid.
     /// *     `VMO_ALREADY_REGISTERED`: An ID in `vmo_ids` was already
     /// *         registered.
     /// *     `VMO_ACCESS_DENIED`: A VMO in `vmos` could not be mapped due to
     /// *         insufficient permissions.
     /// *     `VMO_TOO_SMALL`: A VMO in `vmos` was smaller than the burst size.
     strict RegisterVmos(resource struct {
         vmo_ids vector<uint32>:VMO_VECTOR_MAX_COUNT;
         vmos vector<zx.Handle:VMO>:VMO_VECTOR_MAX_COUNT;
     }) -> () error StatusCode;

     /// Removes the associations with the given VMO IDs and returns the VMOs to
     /// the client. The driver will not send any more `OnBurst()` events with
     /// these VMO IDs after replying, however the client may still receive
     /// bursts with these IDs if they were in flight during this call. The
     /// driver must return all of the requested VMOs, or return an error. In
     /// case of an error, the driver may have unregistered some or all of the
     /// requested VMOs.
     ///
     /// + request `vmo_ids` the IDs of the VMOs to unregister and return.
     /// - response `vmos` the VMO handles corresponding to `vmo_ids`.
     /// * error one of the following `StatusCode` values:
     /// *     `INVALID_ARGS`: `vmo_ids` was too big.
     /// *     `VMO_NOT_FOUND`: An ID in `vmo_ids` was not registered.
     strict UnregisterVmos(struct {
         vmo_ids vector<uint32>:VMO_VECTOR_MAX_COUNT;
     }) -> (resource struct {
         vmos vector<zx.Handle:VMO>:VMO_VECTOR_MAX_COUNT;
     }) error StatusCode;

     /// Tells the driver to start sending bursts via `OnBurst()`.
     strict StartBursts();

     /// Tells the driver to stop sending bursts via `OnBurst()`. If all clients
     /// call `StopBursts()` then the driver may choose to stop its worker thread.
     /// The driver may wait for a single burst read to complete, but will not
     /// access any of the client’s VMOs or call its observer after replying.
     ///
     /// Note that already inflight `OnBurst()` bursts may still be received by
     /// the client.
     strict StopBursts() -> ();

     /// Returns the ID of a VMO containing a single burst, the time the burst
     /// was received. Ownership of the VMO must be returned to the driver by
     /// calling `UnlockVmo()`, and won't be written by the driver until then.
     /// See the doc for the burst format specification.
     ///
     /// The driver will drop bursts if there are no unlocked VMOs. This also
     /// provides flow control for the number of events in flight. When a burst
     /// is received and no VMOs are unlocked, `OnBurst()` will be called with
     /// `OUT_OF_VMOS` set as the error. `OnBurst` will not be called again until
     /// at least one VMO has been unlocked.
     ///
     /// + request `burst` the ID of a VMO containing the burst, as well as the
     ///     time the burst was received.
     /// * error one of the following `StatusCode` values:
     /// *     `OUT_OF_VMOS`: No unlocked VMOs were available to hold the burst.
     /// *         The driver will wait for at least one VMO to become available
     /// *         before sending more events to this client.
     /// *     `SENSOR_TIMEOUT`: The driver could not drain the sensor FIFO
     /// *         quickly enough.
     /// *     `SENSOR_ERROR`: An unspecified driver or sensor error occurred
     /// *         when trying to read the burst.
     @available(added=14)
     strict -> OnBurst(flexible union {
         1: burst Burst;
         2: error StatusCode;
     });

     @available(removed=17, legacy=true)
     strict -> OnBurst2(flexible union {
         1: burst Burst;
         2: error StatusCode;
     });

     /// Signals to the driver that the client is no longer reading the VMO. The
     /// client must not access the VMO after calling this.
     ///
     /// + request `vmo_id` the ID of the VMO to return to the driver.
     strict UnlockVmo(struct {
         vmo_id uint32;
     });
 };

 /// The main protocol implemented by radar drivers. Clients use this protocol to
 /// establish a `RadarBurstReader` connection with the driver.
 @discoverable
 closed protocol RadarBurstReaderProvider {
     /// + request `server` the `RadarBurstReader` server end for the driver to
     ///     bind to.
     /// * error one of the following `StatusCode` values:
     ///     `BIND_ERROR`: An error was encountered while trying to bind to the
     ///         provided server channel.
     ///     `ALREADY_BOUND`: Another client has already established a
     ///         `RadarBurstReader` connection with the driver.
     strict Connect(resource struct {
         server server_end:RadarBurstReader;
     }) -> () error StatusCode;
 };

 closed protocol RadarSensorInfo {
     /// Returns the size and period of bursts reported by the sensor.
     ///
     /// - response `size` the size of each radar burst in bytes.
     /// - response `period` the time between bursts in nanoseconds.
     strict GetBurstProperties() -> (struct {
         size uint32;
         period zx.Duration;
     });
 };

 type BurstData = resource struct {
     /// A VMO holding zero or more radar bursts of the size reported by
     /// `GetBurstProperties()`. Bursts are stored contiguously with no padding
     /// between them.
     vmo zx.Handle:<VMO, zx.Rights.READ | zx.Rights.MAP>;
     /// The number of bursts stored in `vmo`.
     burst_count uint32;
 };

 /// Test clients may use this protocol to inject burst data to radar clients
 /// through a virtual radar driver. Only one client of this protocol can be
 /// connected at a time. radar-proxy will send epitaph status code
 /// `ZX_ERR_ALREADY_BOUND` to and close channels from any additional clients
 /// that attempt to connect.
 @discoverable
 closed protocol RadarBurstInjector {
     compose RadarSensorInfo;

     /// Enqueues the given VMO with burst data to be injected. After all bursts
     /// from this VMO have been injected, radar-proxy will move on to the next
     /// VMO in the queue. The caller must not write to the VMO until it has been
     /// returned by `OnBurstsDelivered()`. The VMO will be closed and unmapped
     /// if the injector client unexpectedly disconnects.
     ///
     /// Bursts are injected by radar-proxy at the rate reported by the
     /// underlying driver's `GetBurstProperties()` method. If no VMOs are in the
     /// queue at the time that a burst is to be delivered, radar-proxy will stop
     /// sending bursts until either `EnqueueBursts()` or `StopBurstInjection()`
     /// is called.
     ///
     /// + request `bursts` the `BurstData` struct containing bursts to inject.
     /// - response `bursts_id` the ID to be passed back through
     ///     `OnBurstsDelivered()` after the final burst from this buffer has
     ///     been injected.
     /// * error one of the following `StatusCode` values:
     /// *   `VMO_BAD_HANDLE`: The VMO handle was invalid.
     /// *   `VMO_ACCESS_DENIED`: The VMO had insufficient rights.
     /// *   `VMO_TOO_SMALL`: The VMO was too small to hold the indicated number
     /// *     of bursts.
     /// *   `INVALID_ARGS`: The number of bursts was zero.
     /// *   `BAD_STATE`: A previous call to `StopBurstInjection()` is still
     /// *     pending.
     strict EnqueueBursts(resource struct {
         bursts BurstData;
     }) -> (struct {
         bursts_id uint32;
     }) error StatusCode;

     /// Returns an ID corresponding to a `BurstData` struct previously passed to
     /// `EnqueueBursts()`. Upon receiving this event the client is free to write
     /// to the VMO, and if desired, pass it back to radar-proxy for injection.
     ///
     /// + request `bursts_id` the ID returned by a previous call to
     ///     `EnqueueBursts()`.
     strict -> OnBurstsDelivered(struct {
         bursts_id uint32;
     });

     /// Tells radar-proxy to read future bursts from enqueued VMOs rather than
     /// from the real radar driver. radar-proxy will attempt to deliver the
     /// first injected burst at the time that the radar driver would have done
     /// so. If the queue is or becomes empty then sending of bursts will stop
     /// until more bursts are available in the queue. See `EnqueueBursts()`
     /// above.
     ///
     /// radar-proxy will call `StopBursts()` on the real radar driver before
     /// it starts to deliver the enqueued bursts.
     ///
     /// * error one of the following `StatusCode` values:
     /// *   `BAD_STATE`: Injection has already been started, or a previous call
     /// *     to `StopBurstInjection()` is still pending.
     strict StartBurstInjection() -> () error StatusCode;

     /// Tells radar-proxy to finish injecting bursts from VMOs currently on the
     /// queue then switch back to delivering bursts from the real radar driver.
     /// The reply to this call will not be sent until `OnBurstsDelivered()` has
     /// been called for the final VMO to be injected, and any other calls made
     /// in that time will return errors.
     ///
     /// radar-proxy will call `StartBursts()` on the real radar driver as part
     /// of this call. There may be a delay before RadarBurstReader clients start
     /// to receive bursts from the driver again.
     ///
     /// * error one of the following `StatusCode` values:
     /// *   `BAD_STATE`: Injection has already been stopped, or a call to this
     /// *     method is still pending.
     strict StopBurstInjection() -> () error StatusCode;
 };
	// Copyright 2021 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.
	@available(added=7)
	library fuchsia.hardware.radar;
	using zx;

	/// Arbitrary limit on the number of VMOs in one call to `RegisterVmos()` or
	/// `UnregisterVmos()`; enough for ten seconds of radar data for the existing
	/// driver.
	const VMO_VECTOR_MAX_COUNT uint32 = 300;

	type StatusCode = strict enum {
	/// An unspecified error occurred (generally should not be used).
	UNSPECIFIED = 0;

	/// The request completed successfully.
	SUCCESS = 1;

	/// `Connect()` was called but the driver is busy handling another client.
	/// The other client will have to close its channel for the driver to become
	/// available again.
	ALREADY_BOUND = 2;

	/// `Connect()` encountered an error trying to bind to the provided server
	/// channel.
	BIND_ERROR = 3;

	/// The vectors passed to `RegisterVmos()` did not have the same size.
	INVALID_ARGS = 4;

	/// A VMO handle was invalid.
	VMO_BAD_HANDLE = 5;

	/// A VMO was already registered with this ID.
	VMO_ALREADY_REGISTERED = 6;

	/// No registered VMO was found for the given ID.
	VMO_NOT_FOUND = 7;

	/// A client VMO could not be written to or mapped due to insufficient
	/// permissions.
	VMO_ACCESS_DENIED = 8;

	/// A client VMO was smaller than the burst size (see `GetBurstSize()`).
	VMO_TOO_SMALL = 9;

	/// A burst was received, but no unlocked VMOs are available.
	OUT_OF_VMOS = 10;

	/// A burst was not received within the expected window.
	SENSOR_TIMEOUT = 11;

	/// An unspecified driver or sensor error was encountered.
	SENSOR_ERROR = 12;

	/// The radar driver or proxy was not in the correct state for this call.
	BAD_STATE = 13;
	};

	type Burst = struct {
	vmo_id uint32;
	timestamp zx.Time;
	};

	closed protocol RadarBurstReader {
	strict GetBurstProperties() -> (struct {
	size uint32;
	period zx.Duration;
	});

	/// Registers the VMOs for future use and associates them with vmo_ids,
	/// which can be used with `UnregisterVmos()` and `OnBurst()`. vmos will be
	/// mapped by the driver using `ZX_VM_PERM_WRITE`. The client should only
	/// read registered VMOs that are sent via `OnBurst()`. The size of vmo is
	/// assumed to be at least the burst size, and the sizes of `vmo_ids` and
	/// `vmos` must be the same.
	///
	/// + request `vmo_ids` the ID numbers to associate with each VMO.
	/// + request `vmos` the VMO handles corresponding to each ID.
	/// * error one of the following `StatusCode` values:
	/// * `INVALID_ARGS`: `vmo_ids` and `vmos` were of different sizes.
	/// * `VMO_BAD_HANDLE`: A handle in `vmos` was invalid.
	/// * `VMO_ALREADY_REGISTERED`: An ID in `vmo_ids` was already
	/// * registered.
	/// * `VMO_ACCESS_DENIED`: A VMO in `vmos` could not be mapped due to
	/// * insufficient permissions.
	/// * `VMO_TOO_SMALL`: A VMO in `vmos` was smaller than the burst size.
	strict RegisterVmos(resource struct {
	vmo_ids vector<uint32>:VMO_VECTOR_MAX_COUNT;
	vmos vector<zx.Handle:VMO>:VMO_VECTOR_MAX_COUNT;
	}) -> () error StatusCode;

	/// Removes the associations with the given VMO IDs and returns the VMOs to
	/// the client. The driver will not send any more `OnBurst()` events with
	/// these VMO IDs after replying, however the client may still receive
	/// bursts with these IDs if they were in flight during this call. The
	/// driver must return all of the requested VMOs, or return an error. In
	/// case of an error, the driver may have unregistered some or all of the
	/// requested VMOs.
	///
	/// + request `vmo_ids` the IDs of the VMOs to unregister and return.
	/// - response `vmos` the VMO handles corresponding to `vmo_ids`.
	/// * error one of the following `StatusCode` values:
	/// * `INVALID_ARGS`: `vmo_ids` was too big.
	/// * `VMO_NOT_FOUND`: An ID in `vmo_ids` was not registered.
	strict UnregisterVmos(struct {
	vmo_ids vector<uint32>:VMO_VECTOR_MAX_COUNT;
	}) -> (resource struct {
	vmos vector<zx.Handle:VMO>:VMO_VECTOR_MAX_COUNT;
	}) error StatusCode;

	/// Tells the driver to start sending bursts via `OnBurst()`.
	strict StartBursts();

	/// Tells the driver to stop sending bursts via `OnBurst()`. If all clients
	/// call `StopBursts()` then the driver may choose to stop its worker thread.
	/// The driver may wait for a single burst read to complete, but will not
	/// access any of the client’s VMOs or call its observer after replying.
	///
	/// Note that already inflight `OnBurst()` bursts may still be received by
	/// the client.
	strict StopBursts() -> ();

	/// Returns the ID of a VMO containing a single burst, the time the burst
	/// was received. Ownership of the VMO must be returned to the driver by
	/// calling `UnlockVmo()`, and won't be written by the driver until then.
	/// See the doc for the burst format specification.
	///
	/// The driver will drop bursts if there are no unlocked VMOs. This also
	/// provides flow control for the number of events in flight. When a burst
	/// is received and no VMOs are unlocked, `OnBurst()` will be called with
	/// `OUT_OF_VMOS` set as the error. `OnBurst` will not be called again until
	/// at least one VMO has been unlocked.
	///
	/// + request `burst` the ID of a VMO containing the burst, as well as the
	/// time the burst was received.
	/// * error one of the following `StatusCode` values:
	/// * `OUT_OF_VMOS`: No unlocked VMOs were available to hold the burst.
	/// * The driver will wait for at least one VMO to become available
	/// * before sending more events to this client.
	/// * `SENSOR_TIMEOUT`: The driver could not drain the sensor FIFO
	/// * quickly enough.
	/// * `SENSOR_ERROR`: An unspecified driver or sensor error occurred
	/// * when trying to read the burst.
	@available(added=14)
	strict -> OnBurst(flexible union {
	1: burst Burst;
	2: error StatusCode;
	});

	@available(removed=17, legacy=true)
	strict -> OnBurst2(flexible union {
	1: burst Burst;
	2: error StatusCode;
	});

	/// Signals to the driver that the client is no longer reading the VMO. The
	/// client must not access the VMO after calling this.
	///
	/// + request `vmo_id` the ID of the VMO to return to the driver.
	strict UnlockVmo(struct {
	vmo_id uint32;
	});
	};

	/// The main protocol implemented by radar drivers. Clients use this protocol to
	/// establish a `RadarBurstReader` connection with the driver.
	@discoverable
	closed protocol RadarBurstReaderProvider {
	/// + request `server` the `RadarBurstReader` server end for the driver to
	/// bind to.
	/// * error one of the following `StatusCode` values:
	/// `BIND_ERROR`: An error was encountered while trying to bind to the
	/// provided server channel.
	/// `ALREADY_BOUND`: Another client has already established a
	/// `RadarBurstReader` connection with the driver.
	strict Connect(resource struct {
	server server_end:RadarBurstReader;
	}) -> () error StatusCode;
	};

	closed protocol RadarSensorInfo {
	/// Returns the size and period of bursts reported by the sensor.
	///
	/// - response `size` the size of each radar burst in bytes.
	/// - response `period` the time between bursts in nanoseconds.
	strict GetBurstProperties() -> (struct {
	size uint32;
	period zx.Duration;
	});
	};

	type BurstData = resource struct {
	/// A VMO holding zero or more radar bursts of the size reported by
	/// `GetBurstProperties()`. Bursts are stored contiguously with no padding
	/// between them.
	vmo zx.Handle:<VMO, zx.Rights.READ \| zx.Rights.MAP>;
	/// The number of bursts stored in `vmo`.
	burst_count uint32;
	};

	/// Test clients may use this protocol to inject burst data to radar clients
	/// through a virtual radar driver. Only one client of this protocol can be
	/// connected at a time. radar-proxy will send epitaph status code
	/// `ZX_ERR_ALREADY_BOUND` to and close channels from any additional clients
	/// that attempt to connect.
	@discoverable
	closed protocol RadarBurstInjector {
	compose RadarSensorInfo;

	/// Enqueues the given VMO with burst data to be injected. After all bursts
	/// from this VMO have been injected, radar-proxy will move on to the next
	/// VMO in the queue. The caller must not write to the VMO until it has been
	/// returned by `OnBurstsDelivered()`. The VMO will be closed and unmapped
	/// if the injector client unexpectedly disconnects.
	///
	/// Bursts are injected by radar-proxy at the rate reported by the
	/// underlying driver's `GetBurstProperties()` method. If no VMOs are in the
	/// queue at the time that a burst is to be delivered, radar-proxy will stop
	/// sending bursts until either `EnqueueBursts()` or `StopBurstInjection()`
	/// is called.
	///
	/// + request `bursts` the `BurstData` struct containing bursts to inject.
	/// - response `bursts_id` the ID to be passed back through
	/// `OnBurstsDelivered()` after the final burst from this buffer has
	/// been injected.
	/// * error one of the following `StatusCode` values:
	/// * `VMO_BAD_HANDLE`: The VMO handle was invalid.
	/// * `VMO_ACCESS_DENIED`: The VMO had insufficient rights.
	/// * `VMO_TOO_SMALL`: The VMO was too small to hold the indicated number
	/// * of bursts.
	/// * `INVALID_ARGS`: The number of bursts was zero.
	/// * `BAD_STATE`: A previous call to `StopBurstInjection()` is still
	/// * pending.
	strict EnqueueBursts(resource struct {
	bursts BurstData;
	}) -> (struct {
	bursts_id uint32;
	}) error StatusCode;

	/// Returns an ID corresponding to a `BurstData` struct previously passed to
	/// `EnqueueBursts()`. Upon receiving this event the client is free to write
	/// to the VMO, and if desired, pass it back to radar-proxy for injection.
	///
	/// + request `bursts_id` the ID returned by a previous call to
	/// `EnqueueBursts()`.
	strict -> OnBurstsDelivered(struct {
	bursts_id uint32;
	});

	/// Tells radar-proxy to read future bursts from enqueued VMOs rather than
	/// from the real radar driver. radar-proxy will attempt to deliver the
	/// first injected burst at the time that the radar driver would have done
	/// so. If the queue is or becomes empty then sending of bursts will stop
	/// until more bursts are available in the queue. See `EnqueueBursts()`
	/// above.
	///
	/// radar-proxy will call `StopBursts()` on the real radar driver before
	/// it starts to deliver the enqueued bursts.
	///
	/// * error one of the following `StatusCode` values:
	/// * `BAD_STATE`: Injection has already been started, or a previous call
	/// * to `StopBurstInjection()` is still pending.
	strict StartBurstInjection() -> () error StatusCode;

	/// Tells radar-proxy to finish injecting bursts from VMOs currently on the
	/// queue then switch back to delivering bursts from the real radar driver.
	/// The reply to this call will not be sent until `OnBurstsDelivered()` has
	/// been called for the final VMO to be injected, and any other calls made
	/// in that time will return errors.
	///
	/// radar-proxy will call `StartBursts()` on the real radar driver as part
	/// of this call. There may be a delay before RadarBurstReader clients start
	/// to receive bursts from the driver again.
	///
	/// * error one of the following `StatusCode` values:
	/// * `BAD_STATE`: Injection has already been stopped, or a call to this
	/// * method is still pending.
	strict StopBurstInjection() -> () error StatusCode;
	};