blob: 3d5a7ce496eb630197f5d01bd8e93a1d35f4c9c4 [file] [view]
<link rel="stylesheet" href="../style.css" />
[TOC]
# fuchsia.hardware.radar
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 7</span></div>
## **PROTOCOLS**
## RadarBurstReader {#RadarBurstReader}
*Defined in [fuchsia.hardware.radar/radar.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.radar/radar.fidl;l=63)*
### GetBurstSize {#RadarBurstReader.GetBurstSize}
<p>Returns the size in bytes of each burst reported by this driver. Clients
should use this size to create VMOs to be registered by the driver.</p>
<ul>
<li>response <code>burst_size</code> the size of each radar burst in bytes.</li>
</ul>
#### Request {#RadarBurstReader.GetBurstSize_Request}
&lt;EMPTY&gt;
#### Response {#RadarBurstReader.GetBurstSize_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>burst_size</code></td>
<td>
<code>uint32</code>
</td>
</tr>
</table>
### OnBurst {#RadarBurstReader.OnBurst}
<p>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 <code>UnlockVmo()</code>, and won't be written by the driver until then.
See the doc for the burst format specification.</p>
<p>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, <code>OnBurst()</code> will be called with
<code>OUT_OF_VMOS</code> set as the error. <code>OnBurst</code> will not be called again until
at least one VMO has been unlocked.</p>
<ul>
<li>request <code>burst</code> the ID of a VMO containing the burst, as well as the
time the burst was received.</li>
</ul>
<ul>
<li>error one of the following <code>StatusCode</code> values:</li>
<li>
<pre><code>`OUT_OF_VMOS`: No unlocked VMOs were available to hold the burst.
</code></pre>
</li>
<li>
<pre><code> The driver will wait for at least one VMO to become available
</code></pre>
</li>
<li>
<pre><code> before sending more events to this client.
</code></pre>
</li>
<li>
<pre><code>`SENSOR_TIMEOUT`: The driver could not drain the sensor FIFO
</code></pre>
</li>
<li>
<pre><code> quickly enough.
</code></pre>
</li>
<li>
<pre><code>`SENSOR_ERROR`: An unspecified driver or sensor error occurred
</code></pre>
</li>
<li>
<pre><code> when trying to read the burst.
</code></pre>
</li>
</ul>
#### Response {#RadarBurstReader.OnBurst_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#RadarBurstReader_OnBurst_Result'>RadarBurstReader_OnBurst_Result</a></code>
</td>
</tr>
</table>
### RegisterVmos {#RadarBurstReader.RegisterVmos}
<p>Registers the VMOs for future use and associates them with vmo_ids,
which can be used with <code>UnregisterVmos()</code> and <code>OnBurst()</code>. vmos will be
mapped by the driver using <code>ZX_VM_PERM_WRITE</code>. The client should only
read registered VMOs that are sent via <code>OnBurst()</code>. The size of vmo is
assumed to be at least the burst size, and the sizes of <code>vmo_ids</code> and
<code>vmos</code> must be the same.</p>
<ul>
<li>request <code>vmo_ids</code> the ID numbers to associate with each VMO.</li>
<li>request <code>vmos</code> the VMO handles corresponding to each ID.</li>
</ul>
<ul>
<li>error one of the following <code>StatusCode</code> values:</li>
<li>
<pre><code>`INVALID_ARGS`: `vmo_ids` and `vmos` were of different sizes.
</code></pre>
</li>
<li>
<pre><code>`VMO_BAD_HANDLE`: A handle in `vmos` was invalid.
</code></pre>
</li>
<li>
<pre><code>`VMO_ALREADY_REGISTERED`: An ID in `vmo_ids` was already
</code></pre>
</li>
<li>
<pre><code> registered.
</code></pre>
</li>
<li>
<pre><code>`VMO_ACCESS_DENIED`: A VMO in `vmos` could not be mapped due to
</code></pre>
</li>
<li>
<pre><code> insufficient permissions.
</code></pre>
</li>
<li>
<pre><code>`VMO_TOO_SMALL`: A VMO in `vmos` was smaller than the burst size.
</code></pre>
</li>
</ul>
#### Request {#RadarBurstReader.RegisterVmos_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>vmo_ids</code></td>
<td>
<code>vector&lt;uint32&gt;[300]</code>
</td>
</tr>
<tr>
<td><code>vmos</code></td>
<td>
<code>vector&lt;vmo&gt;[300]</code>
</td>
</tr>
</table>
#### Response {#RadarBurstReader.RegisterVmos_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#RadarBurstReader_RegisterVmos_Result'>RadarBurstReader_RegisterVmos_Result</a></code>
</td>
</tr>
</table>
### StartBursts {#RadarBurstReader.StartBursts}
<p>Tells the driver to start sending bursts via <code>OnBurst()</code>.</p>
#### Request {#RadarBurstReader.StartBursts_Request}
&lt;EMPTY&gt;
### StopBursts {#RadarBurstReader.StopBursts}
<p>Tells the driver to stop sending bursts via <code>OnBurst()</code>. If all clients
call <code>StopBursts()</code> 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.</p>
<p>Note that already inflight <code>OnBurst()</code> bursts may still be received by
the client.</p>
#### Request {#RadarBurstReader.StopBursts_Request}
&lt;EMPTY&gt;
#### Response {#RadarBurstReader.StopBursts_Response}
&lt;EMPTY&gt;
### UnlockVmo {#RadarBurstReader.UnlockVmo}
<p>Signals to the driver that the client is no longer reading the VMO. The
client must not access the VMO after calling this.</p>
<ul>
<li>request <code>vmo_id</code> the ID of the VMO to return to the driver.</li>
</ul>
#### Request {#RadarBurstReader.UnlockVmo_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>vmo_id</code></td>
<td>
<code>uint32</code>
</td>
</tr>
</table>
### UnregisterVmos {#RadarBurstReader.UnregisterVmos}
<p>Removes the associations with the given VMO IDs and returns the VMOs to
the client. The driver will not send any more <code>OnBurst()</code> 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.</p>
<ul>
<li>request <code>vmo_ids</code> the IDs of the VMOs to unregister and return.</li>
</ul>
<ul>
<li>response <code>vmos</code> the VMO handles corresponding to <code>vmo_ids</code>.</li>
</ul>
<ul>
<li>error one of the following <code>StatusCode</code> values:</li>
<li>
<pre><code>`INVALID_ARGS`: `vmo_ids` was too big.
</code></pre>
</li>
<li>
<pre><code>`VMO_NOT_FOUND`: An ID in `vmo_ids` was not registered.
</code></pre>
</li>
</ul>
#### Request {#RadarBurstReader.UnregisterVmos_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>vmo_ids</code></td>
<td>
<code>vector&lt;uint32&gt;[300]</code>
</td>
</tr>
</table>
#### Response {#RadarBurstReader.UnregisterVmos_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#RadarBurstReader_UnregisterVmos_Result'>RadarBurstReader_UnregisterVmos_Result</a></code>
</td>
</tr>
</table>
## RadarBurstReaderProvider {#RadarBurstReaderProvider}
*Defined in [fuchsia.hardware.radar/radar.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.radar/radar.fidl;l=162)*
<p>The main protocol implemented by radar drivers. Clients use this protocol to
establish a <code>RadarBurstReader</code> connection with the driver.</p>
### Connect {#RadarBurstReaderProvider.Connect}
<ul>
<li>request <code>server</code> the <code>RadarBurstReader</code> server end for the driver to
bind to.</li>
</ul>
<ul>
<li>error one of the following <code>StatusCode</code> values:
<code>BIND_ERROR</code>: An error was encountered while trying to bind to the
provided server channel.
<code>ALREADY_BOUND</code>: Another client has already established a
<code>RadarBurstReader</code> connection with the driver.</li>
</ul>
#### Request {#RadarBurstReaderProvider.Connect_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>server</code></td>
<td>
<code>server_end&lt;<a class='link' href='#RadarBurstReader'>RadarBurstReader</a>&gt;</code>
</td>
</tr>
</table>
#### Response {#RadarBurstReaderProvider.Connect_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#RadarBurstReaderProvider_Connect_Result'>RadarBurstReaderProvider_Connect_Result</a></code>
</td>
</tr>
</table>
## **STRUCTS**
### Burst {#Burst data-text="Burst"}
*Defined in [fuchsia.hardware.radar/radar.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.radar/radar.fidl;l=58)*
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="Burst.vmo_id">
<td><code>vmo_id</code></td>
<td>
<code>uint32</code>
</td>
<td></td>
<td>No default</td>
</tr>
<tr id="Burst.timestamp">
<td><code>timestamp</code></td>
<td>
<code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#time'>time</a></code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### RadarBurstReaderProvider_Connect_Response {#RadarBurstReaderProvider_Connect_Response data-text="RadarBurstReaderProvider_Connect_Response"}
*Defined in [fuchsia.hardware.radar/radar.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.radar/radar.fidl;l=172)*
&lt;EMPTY&gt;
### RadarBurstReader_OnBurst_Response {#RadarBurstReader_OnBurst_Response data-text="RadarBurstReader_OnBurst_Response"}
*Defined in [fuchsia.hardware.radar/radar.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.radar/radar.fidl;l=146)*
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="RadarBurstReader_OnBurst_Response.burst">
<td><code>burst</code></td>
<td>
<code><a class='link' href='#Burst'>Burst</a></code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### RadarBurstReader_RegisterVmos_Response {#RadarBurstReader_RegisterVmos_Response data-text="RadarBurstReader_RegisterVmos_Response"}
*Defined in [fuchsia.hardware.radar/radar.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.radar/radar.fidl;l=92)*
&lt;EMPTY&gt;
### RadarBurstReader_UnregisterVmos_Response [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#RadarBurstReader_UnregisterVmos_Response data-text="RadarBurstReader_UnregisterVmos_Response"}
*Defined in [fuchsia.hardware.radar/radar.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.radar/radar.fidl;l=109)*
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="RadarBurstReader_UnregisterVmos_Response.vmos">
<td><code>vmos</code></td>
<td>
<code>vector&lt;vmo&gt;[300]</code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
## **ENUMS**
### StatusCode [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#StatusCode data-text="StatusCode"}
Type: <code>uint32</code>
*Defined in [fuchsia.hardware.radar/radar.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.radar/radar.fidl;l=13)*
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="StatusCode.UNSPECIFIED">
<td><h3 id="StatusCode.UNSPECIFIED" class="add-link hide-from-toc">UNSPECIFIED</h3></td>
<td><code>0</code></td>
<td><p>An unspecified error occurred (generally should not be used).</p>
</td>
</tr>
<tr id="StatusCode.SUCCESS">
<td><h3 id="StatusCode.SUCCESS" class="add-link hide-from-toc">SUCCESS</h3></td>
<td><code>1</code></td>
<td><p>The request completed successfully.</p>
</td>
</tr>
<tr id="StatusCode.ALREADY_BOUND">
<td><h3 id="StatusCode.ALREADY_BOUND" class="add-link hide-from-toc">ALREADY_BOUND</h3></td>
<td><code>2</code></td>
<td><p><code>Connect()</code> 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.</p>
</td>
</tr>
<tr id="StatusCode.BIND_ERROR">
<td><h3 id="StatusCode.BIND_ERROR" class="add-link hide-from-toc">BIND_ERROR</h3></td>
<td><code>3</code></td>
<td><p><code>Connect()</code> encountered an error trying to bind to the provided server
channel.</p>
</td>
</tr>
<tr id="StatusCode.INVALID_ARGS">
<td><h3 id="StatusCode.INVALID_ARGS" class="add-link hide-from-toc">INVALID_ARGS</h3></td>
<td><code>4</code></td>
<td><p>The vectors passed to <code>RegisterVmos()</code> did not have the same size.</p>
</td>
</tr>
<tr id="StatusCode.VMO_BAD_HANDLE">
<td><h3 id="StatusCode.VMO_BAD_HANDLE" class="add-link hide-from-toc">VMO_BAD_HANDLE</h3></td>
<td><code>5</code></td>
<td><p>A VMO handle was invalid.</p>
</td>
</tr>
<tr id="StatusCode.VMO_ALREADY_REGISTERED">
<td><h3 id="StatusCode.VMO_ALREADY_REGISTERED" class="add-link hide-from-toc">VMO_ALREADY_REGISTERED</h3></td>
<td><code>6</code></td>
<td><p>A VMO was already registered with this ID.</p>
</td>
</tr>
<tr id="StatusCode.VMO_NOT_FOUND">
<td><h3 id="StatusCode.VMO_NOT_FOUND" class="add-link hide-from-toc">VMO_NOT_FOUND</h3></td>
<td><code>7</code></td>
<td><p>No registered VMO was found for the given ID.</p>
</td>
</tr>
<tr id="StatusCode.VMO_ACCESS_DENIED">
<td><h3 id="StatusCode.VMO_ACCESS_DENIED" class="add-link hide-from-toc">VMO_ACCESS_DENIED</h3></td>
<td><code>8</code></td>
<td><p>A client VMO could not be written to or mapped due to insufficient
permissions.</p>
</td>
</tr>
<tr id="StatusCode.VMO_TOO_SMALL">
<td><h3 id="StatusCode.VMO_TOO_SMALL" class="add-link hide-from-toc">VMO_TOO_SMALL</h3></td>
<td><code>9</code></td>
<td><p>A client VMO was smaller than the burst size (see <code>GetBurstSize()</code>).</p>
</td>
</tr>
<tr id="StatusCode.OUT_OF_VMOS">
<td><h3 id="StatusCode.OUT_OF_VMOS" class="add-link hide-from-toc">OUT_OF_VMOS</h3></td>
<td><code>10</code></td>
<td><p>A burst was received, but no unlocked VMOs are available.</p>
</td>
</tr>
<tr id="StatusCode.SENSOR_TIMEOUT">
<td><h3 id="StatusCode.SENSOR_TIMEOUT" class="add-link hide-from-toc">SENSOR_TIMEOUT</h3></td>
<td><code>11</code></td>
<td><p>A burst was not received within the expected window.</p>
</td>
</tr>
<tr id="StatusCode.SENSOR_ERROR">
<td><h3 id="StatusCode.SENSOR_ERROR" class="add-link hide-from-toc">SENSOR_ERROR</h3></td>
<td><code>12</code></td>
<td><p>An unspecified driver or sensor error was encountered.</p>
</td>
</tr>
</table>
## **UNIONS**
### RadarBurstReaderProvider_Connect_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#RadarBurstReaderProvider_Connect_Result data-text="RadarBurstReaderProvider_Connect_Result"}
*Defined in [fuchsia.hardware.radar/radar.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.radar/radar.fidl;l=172)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="RadarBurstReaderProvider_Connect_Result.response">
<td><h3 id="RadarBurstReaderProvider_Connect_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#RadarBurstReaderProvider_Connect_Response'>RadarBurstReaderProvider_Connect_Response</a></code>
</td>
<td></td>
</tr>
<tr id="RadarBurstReaderProvider_Connect_Result.err">
<td><h3 id="RadarBurstReaderProvider_Connect_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#StatusCode'>StatusCode</a></code>
</td>
<td></td>
</tr>
</table>
### RadarBurstReader_OnBurst_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#RadarBurstReader_OnBurst_Result data-text="RadarBurstReader_OnBurst_Result"}
*Defined in [fuchsia.hardware.radar/radar.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.radar/radar.fidl;l=146)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="RadarBurstReader_OnBurst_Result.response">
<td><h3 id="RadarBurstReader_OnBurst_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#RadarBurstReader_OnBurst_Response'>RadarBurstReader_OnBurst_Response</a></code>
</td>
<td></td>
</tr>
<tr id="RadarBurstReader_OnBurst_Result.err">
<td><h3 id="RadarBurstReader_OnBurst_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#StatusCode'>StatusCode</a></code>
</td>
<td></td>
</tr>
</table>
### RadarBurstReader_RegisterVmos_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#RadarBurstReader_RegisterVmos_Result data-text="RadarBurstReader_RegisterVmos_Result"}
*Defined in [fuchsia.hardware.radar/radar.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.radar/radar.fidl;l=92)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="RadarBurstReader_RegisterVmos_Result.response">
<td><h3 id="RadarBurstReader_RegisterVmos_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#RadarBurstReader_RegisterVmos_Response'>RadarBurstReader_RegisterVmos_Response</a></code>
</td>
<td></td>
</tr>
<tr id="RadarBurstReader_RegisterVmos_Result.err">
<td><h3 id="RadarBurstReader_RegisterVmos_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#StatusCode'>StatusCode</a></code>
</td>
<td></td>
</tr>
</table>
### RadarBurstReader_UnregisterVmos_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#RadarBurstReader_UnregisterVmos_Result data-text="RadarBurstReader_UnregisterVmos_Result"}
*Defined in [fuchsia.hardware.radar/radar.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.radar/radar.fidl;l=109)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="RadarBurstReader_UnregisterVmos_Result.response">
<td><h3 id="RadarBurstReader_UnregisterVmos_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#RadarBurstReader_UnregisterVmos_Response'>RadarBurstReader_UnregisterVmos_Response</a></code>
</td>
<td></td>
</tr>
<tr id="RadarBurstReader_UnregisterVmos_Result.err">
<td><h3 id="RadarBurstReader_UnregisterVmos_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#StatusCode'>StatusCode</a></code>
</td>
<td></td>
</tr>
</table>
## **CONSTANTS**
<table>
<tr><th>Name</th><th>Value</th><th>Type</th><th>Description</th></tr>
<tr id="VMO_VECTOR_MAX_COUNT">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.radar/radar.fidl;l=11">VMO_VECTOR_MAX_COUNT</a></td>
<td>
<code>300</code>
</td>
<td><code>uint32</code></td>
<td><p>Arbitrary limit on the number of VMOs in one call to <code>RegisterVmos()</code> or
<code>UnregisterVmos()</code>; enough for ten seconds of radar data for the existing
driver.</p>
</td>
</tr>
</table>