blob: f12aa05ae49489bfc057130c6d0dcd2eb6e249f7 [file] [log] [blame]
// Copyright 2018 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.vsock;
using zx;
// Vsock address where 'local' always means the driver and 'remote' always means
// the device. As such there is no 'local_cid' as it can only ever be the driver cid
// and so specifying is redundant and a source of errors.
type Addr = struct {
local_port uint32;
remote_cid uint32;
remote_port uint32;
};
// Callbacks sent from the device to whomever registered them (typically a service)
// in response to events from host.
closed protocol Callbacks {
// Indicates a 'request' op was received from the host. One of Device.SendResponse
// or Device.SendRst should be done in response to this.
strict Request(struct {
addr Addr;
});
// Indicates a response was received for a connection that was trying to be
// established from Device.SendRequest.
strict Response(struct {
addr Addr;
});
// Indicates a 'rst' op was received from the host, and that the driver has
// has freed the resources for any potential connection relating to `addr`.
strict Rst(struct {
addr Addr;
});
// Indicates a 'shutdown' op was received from the host.
strict Shutdown(struct {
addr Addr;
});
// Indicates a 'transport reset' op was received from the host. Responding to
// this method indicates that you have processed all preceding Callbacks and
// dropped any active connections.
strict TransportReset(struct {
new_cid uint32;
}) -> ();
// Indicates that a previous Device.SendVmo request has completed.
strict SendVmoComplete(struct {
addr Addr;
});
};
// Low level vsock device operations. Users of this interface are responsible for
// adhering to the vsock protocol and must use ensure they do not reuse addresses
// for active connections, perform SendRst and SendResponse only when it is correct
// to do so, etc.
closed protocol Device {
// Causes the device to start and gives it Callbacks to use for forwarding messages
// from the host. The rest of the methods on this interface are only valid to use
// after calling Start and whilst the passed Callbacks remain valid. The device
// will stop if it detects the other end of the Callbacks channel has closed.
strict Start(resource struct {
cb client_end:Callbacks;
}) -> (struct {
status zx.Status;
});
// Will send a request to open a connection with the remote specified in the
// `addr`. The `data` socket is stored and will be used for data transmission
// should the connection get established successfully, otherwise it will close
// the handle. The `status` returned indicates whether the request was sent
// successfully. Callbacks.Response or Callbacks.Rst will be called to indicate
// if the connection was successfully established or not.
strict SendRequest(resource struct {
addr Addr;
data zx.Handle:SOCKET;
}) -> (struct {
status zx.Status;
});
// Request a shutdown to begin for the connection indicated by the given `addr`.
// This immediately stops any data from being sent on the connection, although
// data may still be received up until Callbacks.Rst is called to indicate the
// shutdown has complete. This is only valid on a connection established with
// SendRequest or SendResponse.
strict SendShutdown(struct {
addr Addr;
}) -> (struct {
status zx.Status;
});
// Request a rst be sent to the host. The device will also release the resources
// for any connection that may exist for `addr`.
strict SendRst(struct {
addr Addr;
}) -> (struct {
status zx.Status;
});
// Causes a 'response' to get sent to the host, gives the driver a `data` socket
// to use for sending and receiving data on the established connection. It is
// only correct to use this in response to a Callbacks.Request.
strict SendResponse(resource struct {
addr Addr;
data zx.Handle:SOCKET;
}) -> (struct {
status zx.Status;
});
// Query the current context id of the driver. The local CID is never needed
// in interactions with the same device, and retrieving it is only useful for
// debugging or if you have some other communication channel to a different host
// and you would like to send them your CID to then establish a vsock connection on.
strict GetCid() -> (struct {
local_cid uint32;
});
// Send the contents of a vmo over an already established connection. A
// connection may only have a single outstanding vmo at a time, and trying
// to send whilst one is already in progress will generate an error. If there
// is pending data to transmit in the `data` socket of a connection and there
// is a vmo pending then it is undefined which one will be sent. Once the vmo
// contents have finished sending Callbacks.SendVmoComplete will be called.
strict SendVmo(resource struct {
addr Addr;
vmo zx.Handle:VMO;
off uint64;
len uint64;
}) -> (struct {
status zx.Status;
});
};