fuchsia.hardware.radar

Added: 7

PROTOCOLS

RadarBurstInjector

Defined in fuchsia.hardware.radar/radar.fidl

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.

EnqueueBursts

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.

Request

NameType
bursts BurstData

Response

NameType
payload RadarBurstInjector_EnqueueBursts_Result

GetBurstProperties

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.

Request

<EMPTY>

Response

NameType
size uint32
period zx/Duration

OnBurstsDelivered

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().

Response

NameType
bursts_id uint32

StartBurstInjection

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.

Request

<EMPTY>

Response

NameType
payload RadarBurstInjector_StartBurstInjection_Result

StopBurstInjection

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.

Request

<EMPTY>

Response

NameType
payload RadarBurstInjector_StopBurstInjection_Result

RadarBurstReader

Defined in fuchsia.hardware.radar/radar.fidl

GetBurstProperties

Request

<EMPTY>

Response

NameType
size uint32
period zx/Duration

OnBurst

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.
Added: 14

Response

NameType
payload RadarBurstReaderOnBurstRequest

RegisterVmos

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.

Request

NameType
vmo_ids vector<uint32>:300
vmos vector<handle<vmo>>:300

Response

NameType
payload RadarBurstReader_RegisterVmos_Result

StartBursts

Tells the driver to start sending bursts via OnBurst().

Request

<EMPTY>

StopBursts

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.

Request

<EMPTY>

Response

<EMPTY>

UnlockVmo

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.

Request

NameType
vmo_id uint32

UnregisterVmos

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.

Request

NameType
vmo_ids vector<uint32>:300

Response

NameType
payload RadarBurstReader_UnregisterVmos_Result

RadarBurstReaderProvider

Defined in fuchsia.hardware.radar/radar.fidl

The main protocol implemented by radar drivers. Clients use this protocol to establish a RadarBurstReader connection with the driver.

Connect

  • 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.

Request

NameType
server server_end:RadarBurstReader

Response

NameType
payload RadarBurstReaderProvider_Connect_Result

RadarSensorInfo

Defined in fuchsia.hardware.radar/radar.fidl

GetBurstProperties

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.

Request

<EMPTY>

Response

NameType
size uint32
period zx/Duration

STRUCTS

Burst

Defined in fuchsia.hardware.radar/radar.fidl

FieldTypeDescriptionDefault
vmo_id uint32 No default
timestamp zx/Time No default

BurstData resource

Defined in fuchsia.hardware.radar/radar.fidl

FieldTypeDescriptionDefault
vmo handle<vmo>

A VMO holding zero or more radar bursts of the size reported by GetBurstProperties(). Bursts are stored contiguously with no padding between them.

 No default
burst_count uint32

The number of bursts stored in vmo.

 No default

RadarBurstInjector_EnqueueBursts_Response

Defined in fuchsia.hardware.radar/radar.fidl

FieldTypeDescriptionDefault
bursts_id uint32 No default

RadarBurstInjector_StartBurstInjection_Response

Defined in fuchsia.hardware.radar/radar.fidl

<EMPTY>

RadarBurstInjector_StopBurstInjection_Response

Defined in fuchsia.hardware.radar/radar.fidl

<EMPTY>

RadarBurstReaderProvider_Connect_Response

Defined in fuchsia.hardware.radar/radar.fidl

<EMPTY>

RadarBurstReader_RegisterVmos_Response

Defined in fuchsia.hardware.radar/radar.fidl

<EMPTY>

RadarBurstReader_UnregisterVmos_Response resource

Defined in fuchsia.hardware.radar/radar.fidl

FieldTypeDescriptionDefault
vmos vector<handle<vmo>>:300 No default

ENUMS

StatusCode strict

Type: uint32

Defined in fuchsia.hardware.radar/radar.fidl

NameValueDescription
0

An unspecified error occurred (generally should not be used).
1

The request completed successfully.
2

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.
3

Connect() encountered an error trying to bind to the provided server channel.
4

The vectors passed to RegisterVmos() did not have the same size.
5

A VMO handle was invalid.
6

A VMO was already registered with this ID.
7

No registered VMO was found for the given ID.
8

A client VMO could not be written to or mapped due to insufficient permissions.
9

A client VMO was smaller than the burst size (see GetBurstSize()).
10

A burst was received, but no unlocked VMOs are available.
11

A burst was not received within the expected window.
12

An unspecified driver or sensor error was encountered.
13

The radar driver or proxy was not in the correct state for this call.

UNIONS

RadarBurstInjector_EnqueueBursts_Result strict

Defined in fuchsia.hardware.radar/radar.fidl

OrdinalVariantTypeDescription
response RadarBurstInjector_EnqueueBursts_Response
err StatusCode

RadarBurstInjector_StartBurstInjection_Result strict

Defined in fuchsia.hardware.radar/radar.fidl

OrdinalVariantTypeDescription
response RadarBurstInjector_StartBurstInjection_Response
err StatusCode

RadarBurstInjector_StopBurstInjection_Result strict

Defined in fuchsia.hardware.radar/radar.fidl

OrdinalVariantTypeDescription
response RadarBurstInjector_StopBurstInjection_Response
err StatusCode

RadarBurstReaderOnBurstRequest flexible

Defined in fuchsia.hardware.radar/radar.fidl

OrdinalVariantTypeDescription
burst Burst
error StatusCode

RadarBurstReaderProvider_Connect_Result strict

Defined in fuchsia.hardware.radar/radar.fidl

OrdinalVariantTypeDescription
response RadarBurstReaderProvider_Connect_Response
err StatusCode

RadarBurstReader_RegisterVmos_Result strict

Defined in fuchsia.hardware.radar/radar.fidl

OrdinalVariantTypeDescription
response RadarBurstReader_RegisterVmos_Response
err StatusCode

RadarBurstReader_UnregisterVmos_Result strict resource

Defined in fuchsia.hardware.radar/radar.fidl

OrdinalVariantTypeDescription
response RadarBurstReader_UnregisterVmos_Response
err StatusCode

CONSTANTS

NameValueTypeDescription
VMO_VECTOR_MAX_COUNT 300 uint32

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.