| // Copyright 2023 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. |
| |
| library fuchsia.hardware.usb.endpoint; |
| |
| using zx; |
| using fuchsia.hardware.usb.request; |
| |
| /// Bulk Endpoint Information |
| type BulkEndpointInfo = table {}; |
| |
| /// Control Endpoint Information |
| type ControlEndpointInfo = table {}; |
| |
| /// Isochronous Endpoint Information |
| type IsochronousEndpointInfo = table { |
| /// Lead time described in number of transfers. |
| 1: lead_time uint64; |
| }; |
| |
| /// Interrupt Endpoint Information |
| type InterruptEndpointInfo = table {}; |
| |
| /// Endpoint Information |
| type EndpointInfo = flexible union { |
| /// Bulk endpoint information |
| 1: bulk BulkEndpointInfo; |
| /// Control endpoint information |
| 2: control ControlEndpointInfo; |
| /// Isochronous endpoint information |
| 3: isochronous IsochronousEndpointInfo; |
| /// Interrupt endpoint information |
| 4: interrupt InterruptEndpointInfo; |
| }; |
| |
| /// Arbitrary limit on the number of VMOs in one call to `RegisterVmos()` or `UnregisterVmos()`. |
| const VMO_VECTOR_MAX uint32 = 300; |
| /// Arbitrary limit on the number of Requests in one call to `QueueRequest()`. |
| const REQUEST_MAX uint32 = 300; |
| |
| /// VMO information for registering VMOs. Only used for `RegisterVmos()` to convey the ID to register |
| /// a VMO to and its size. |
| type VmoInfo = table { |
| /// ID corresponding to the VMO to be registered. |
| 1: id fuchsia.hardware.usb.request.VmoId; |
| /// Size of VMO to register. |
| 2: size uint64; |
| }; |
| |
| /// VMO handle returned for registered VMOs. Only used as a return value for `UnregisterVmos()` to |
| /// associate a VMO handle with the VmoId it was registered to. |
| type VmoHandle = resource table { |
| /// ID corresponding to the registered VMO as passed in by `RegisterVmos()` through `VmoInfo`. |
| 1: id fuchsia.hardware.usb.request.VmoId; |
| /// Handle to VMO. |
| 2: vmo zx.Handle:VMO; |
| }; |
| |
| /// Completion |
| type Completion = resource table { |
| /// Request completed. |
| 1: request fuchsia.hardware.usb.request.Request; |
| /// Completion status. |
| 2: status zx.Status; |
| /// Bytes successfully transferred. |
| 3: transfer_size uint64; |
| }; |
| |
| /// Endpoint Interface. |
| /// Pre-registered VMOs associated with the Endpoint are tied to the lifetime of the Endpoint. When |
| /// the Endpoint is closed, all outstanding registered VMOs are unregistered, references to their |
| /// handles dropped and any necessary actions for DisableEndpoint will be called. |
| @discoverable |
| closed protocol Endpoint { |
| /// Gets endpoint information |
| strict GetInfo() -> (struct { |
| info EndpointInfo; |
| }) error zx.Status; |
| |
| /// Registers and pins VMOs to the vmo_ids. Returns |
| /// * vmo: Handles to successfully registered vmo_ids. |
| /// VMO IDs that are already are registered to will fail. |
| strict RegisterVmos(resource struct { |
| vmo_ids vector<VmoInfo>:VMO_VECTOR_MAX; |
| }) -> (resource struct { |
| vmos vector<VmoHandle>:VMO_VECTOR_MAX; |
| }); |
| /// Unregisters the VMOs corresponding to the vmo_ids. Returns |
| /// * failed_vmo_ids: vmo_ids that failed to unregister. |
| /// * errors: Error values that correspond 1:1 to failed_vmo_ids above. |
| strict UnregisterVmos(struct { |
| vmo_ids vector<fuchsia.hardware.usb.request.VmoId>:VMO_VECTOR_MAX; |
| }) -> (resource struct { |
| failed_vmo_ids vector<fuchsia.hardware.usb.request.VmoId>:VMO_VECTOR_MAX; |
| errors vector<zx.Status>:VMO_VECTOR_MAX; |
| }); |
| |
| /// Submit Requests to queue. Processed starting with the 0th Request. Submitting a vector of |
| /// Requests allows for pre-buffering. |
| /// |
| /// Clients are responsible for cache management and ensuring cache coherency. |
| /// |
| /// After read requests: |
| /// - Call zx_cache_flush with ZX_CACHE_FLUSH_DATA | ZX_CACHE_FLUSH_INVALIDATE on buffers that |
| /// have been mapped by the client. |
| /// - Call zx_vmo_op_range with ZX_VMO_OP_CACHE_CLEAN_INVALIDATE on all other buffers. |
| /// |
| /// Note that writing to any portion of a buffer before OnCompletion is called for that buffer |
| /// can corrupt the received data. |
| /// |
| /// Before write requests: |
| /// - Call zx_cache_flush with ZX_CACHE_FLUSH_DATA on buffers that have been mapped by the |
| /// client. |
| /// - Call zx_vmo_op_range with ZX_VMO_OP_CACHE_CLEAN on all other buffers. |
| /// |
| /// Requests may be pre-buffered. In other words, requests may be queued for data that is not |
| /// present/ready in the buffer yet. The USB Endpoint Server consuming requests does not care |
| /// if the data in the buffer is ready or not and will always process requests on schedule. It |
| /// is the responsibility of the USB Endpoint Client that submits requests to ensure that data |
| /// is ready on schedule. |
| /// * Definition of "on schedule" varies for different endpoints and controllers. In general, |
| /// this will be communicated by the `lead_time` parameter returned by `GetInfo`. |
| strict QueueRequests(resource struct { |
| req vector<fuchsia.hardware.usb.request.Request>:REQUEST_MAX; |
| }); |
| /// Called on a completion to notify the device driver of an completion event. |
| /// Note that if more than REQUEST_MAX successful requests with defer_completion == true have |
| /// been seen, driver may call OnCompletion multiple times when defer_completion == false is |
| /// seen (or failure happens) to return all seen requests to the client. |
| strict -> OnCompletion(resource struct { |
| completion vector<Completion>:REQUEST_MAX; |
| }); |
| |
| /// Cancels all requests. Returns |
| /// * ZX_ERR_IO_NOT_PRESENT: If device is not running, disconnected, or inactive. |
| /// * ZX_ERR_IO: If cancel failed due to an unsuccessful request. |
| strict CancelAll() -> () error zx.Status; |
| }; |