sdk/fidl/fuchsia.virtualization.hardware/device.fidl - fuchsia - Git at Google

 // 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.virtualization.hardware;

 using fuchsia.net;
 using fuchsia.sysmem;
 using fuchsia.ui.composition;
 using fuchsia.ui.input3;
 using fuchsia.ui.pointer;
 using fuchsia.virtualization;
 using fuchsia.wayland;
 using zx;

 // The following EVENT_* constants indicate which user signal is associated with an event.
 // The value 0 is `ZX_USER_SIGNAL_0`, 1 is `ZX_USER_SIGNAL_1` etc.

 /// Set a flag to inspect queues on the next interrupt.
 const EVENT_SET_QUEUE uint32 = 0;
 /// Set a flag to inspect configs on the next interrupt.
 const EVENT_SET_CONFIG uint32 = 1;
 /// If a flag is set, send an interrupt to the device.
 const EVENT_SET_INTERRUPT uint32 = 2;

 /// Contains the details of a device trap.
 type Trap = struct {
     /// The address of the device trap. This must be page-aligned.
     addr uint64;

     /// The size of the device trap. This must be a multiple of the page size.
     size uint64;
 };

 /// Contains the basic information required to start execution of a device.
 type StartInfo = resource struct {
     /// The trap associated with a device. It is up to the device to set this
     /// trap during device setup.
     trap Trap;

     /// The guest associated with a device. This handle should be used to setup
     /// device traps, and then be released before device operation begins.
     guest zx.Handle:<GUEST, optional>;

     /// The event associated with a device interrupt. This is how the device will
     /// notify the guest of events it should process.
     ///
     /// The meaning of the different signals that can be raised on the event are
     /// documented by the EVENT_* constants above.
     event zx.Handle:EVENT;

     /// The VMO used to represent guest physical memory.
     vmo zx.Handle:VMO;
 };

 closed protocol VirtioDevice {
     /// Configure a `queue` for the device. This specifies the `size` and the
     /// guest physical addresses of the queue: `desc`, `avail`, and `used`.
     strict ConfigureQueue(struct {
         queue uint16;
         size uint16;
         desc uint64;
         avail uint64;
         used uint64;
     }) -> ();

     /// Notify a `queue` for the device. Primarily used for black-box testing.
     strict NotifyQueue(struct {
         queue uint16;
     });

     /// Ready a device. This provides the set of `negotiated_features` that the
     /// driver and device have agreed upon.
     strict Ready(struct {
         negotiated_features uint32;
     }) -> ();
 };

 @discoverable
 closed protocol VirtioBalloon {
     compose VirtioDevice;

     /// Start the balloon device.
     strict Start(resource struct {
         start_info StartInfo;
     }) -> ();

     /// Get memory statistics from the balloon device.
     strict GetMemStats() -> (struct {
         status zx.Status;
         mem_stats vector<fuchsia.virtualization.MemStat>:optional;
     });
 };

 @discoverable
 closed protocol VirtioBlock {
     compose VirtioDevice;

     /// Start the block device.
     strict Start(resource struct {
         start_info StartInfo;
         spec fuchsia.virtualization.BlockSpec;
     }) -> (struct {
         capacity uint64;
         block_size uint32;
     });
 };

 @discoverable
 closed protocol VirtioConsole {
     compose VirtioDevice;

     /// Start the console device. This uses `socket` to handle input and output.
     strict Start(resource struct {
         start_info StartInfo;
         socket zx.Handle:SOCKET;
     }) -> ();
 };

 @discoverable
 closed protocol VirtioGpu {
     compose VirtioDevice;

     /// Start the GPU device.
     strict Start(resource struct {
         start_info StartInfo;
         keyboard_listener client_end:<fuchsia.ui.input3.KeyboardListener, optional>;
         mouse_source server_end:<fuchsia.ui.pointer.MouseSource, optional>;
     }) -> ();

     /// Called when a device's configuration is changed.
     strict -> OnConfigChanged();
 };

 type InputType = strict resource union {
     1: keyboard server_end:<fuchsia.ui.input3.KeyboardListener>;
     2: mouse client_end:<fuchsia.ui.pointer.MouseSource>;
 };

 @discoverable
 closed protocol VirtioInput {
     compose VirtioDevice;

     /// Start the input device.
     strict Start(resource struct {
         start_info StartInfo;
         input_type InputType;
     }) -> ();
 };

 @discoverable
 closed protocol VirtioMagma {
     compose VirtioDevice;

     /// Start the magma device.
     strict Start(resource struct {
         start_info StartInfo;
         vmar zx.Handle:VMAR;
         wayland_importer client_end:<VirtioWaylandImporter, optional>;
     }) -> (struct {
         status zx.Status;
     });
 };

 @discoverable
 closed protocol VirtioNet {
     compose VirtioDevice;

     /// Start the net device.
     strict Start(resource struct {
         start_info StartInfo;
         mac_address fuchsia.net.MacAddress;
         enable_bridge bool;
     }) -> () error zx.Status;
 };

 @discoverable
 closed protocol VirtioRng {
     compose VirtioDevice;

     /// Start the RNG device.
     strict Start(resource struct {
         start_info StartInfo;
     }) -> ();
 };

 @discoverable
 closed protocol VirtioSound {
     compose VirtioDevice;

     /// Start the sound device.
     /// The response contains the device's expected static configuration.
     ///
     /// + request `start_info` basic info to start the device
     /// + request `enable_input` whether audio input (capture) should be enabled
     /// + request `enable_verbose_logging` whether verbose logging should be enabled
     /// - response `features` supported features
     /// - response `jacks` the virtio_snd_config.jacks value to advertise
     /// - response `streams` the virtio_snd_config.streams value to advertise
     /// - response `chmaps` the virtio_snd_config.chaps value to advertise
     strict Start(resource struct {
         start_info StartInfo;
         enable_input bool;
         enable_verbose_logging bool;
     }) -> (struct {
         features uint32;
         jacks uint32;
         streams uint32;
         chmaps uint32;
     });
 };

 @discoverable
 closed protocol VirtioVsock {
     compose VirtioDevice;

     /// Start the vsock device, setting the guest_cid to the provided value.
     ///
     /// Returns:
     ///   - ZX_OK if device startup succeeded
     ///   - ZX_ERR_INVALID_ARGS if guest_cid is a reserved value
     ///   - Any errors returned from fuchsia.virtualization.HostVsockEndpoint::Listen
     strict Start(resource struct {
         start_info StartInfo;
         guest_cid uint32;
         listeners vector<fuchsia.virtualization.Listener>:MAX;
     }) -> () error zx.Status;
 };

 /// Sufficient to contain the opaque image info.
 const VIRTIO_WAYLAND_MAX_IMAGE_INFO_SIZE uint32 = 128;

 /// VirtioImages are shared with VirtioMagma, enabling guest clients to allocate
 /// GBM and Vulkan compatible images and share them with Sommelier as dma-bufs.
 /// An image corresponds to a single buffer collection, and also contains some
 /// opaque image info needed by VirtioMagma.
 type VirtioImage = resource struct {
     vmo zx.Handle:VMO;
     token zx.Handle:<EVENTPAIR, optional>;
     info vector<uint8>:VIRTIO_WAYLAND_MAX_IMAGE_INFO_SIZE;
 };

 const VIRTIO_WAYLAND_INVALID_VFD_ID uint32 = 0;

 // Provides an interface to import images into the wayland device.
 closed protocol VirtioWaylandImporter {
     strict ImportImage(resource struct {
         image VirtioImage;
     }) -> (struct {
         vfd_id uint32;
     });
     strict ExportImage(struct {
         vfd_id uint32;
     }) -> (resource struct {
         status zx.Status;
         image box<VirtioImage>;
     });
 };

 @discoverable
 closed protocol VirtioWayland {
     compose VirtioDevice;

     /// Start the wayland device using the built-in wayland server.
     strict Start(resource struct {
         start_info StartInfo;
         vmar zx.Handle:VMAR;
         sysmem_allocator client_end:fuchsia.sysmem.Allocator;
         scenic_allocator client_end:fuchsia.ui.composition.Allocator;
     }) -> ();

     /// Start the wayland device using the provided wayland server.
     strict StartWithWaylandServer(resource struct {
         start_info StartInfo;
         vmar zx.Handle:VMAR;
         wayland_server client_end:<fuchsia.wayland.Server, optional>;
         sysmem_allocator client_end:fuchsia.sysmem.Allocator;
         scenic_allocator client_end:fuchsia.ui.composition.Allocator;
     }) -> ();

     // Get the VMO importer for this wayland device.
     strict GetImporter(resource struct {
         importer server_end:VirtioWaylandImporter;
     });
 };

 @discoverable
 closed protocol VirtioMem {
     compose VirtioDevice;

     /// Start the mem device.
     strict Start(resource struct {
         start_info StartInfo;
         region_addr uint64;
         plugged_block_size uint64;
         region_size uint64;
     }) -> ();

     /// Called when a device's configuration is changed.
     strict -> OnConfigChanged(struct {
         plugged_size uint64;
     });
 };
	// 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.virtualization.hardware;

	using fuchsia.net;
	using fuchsia.sysmem;
	using fuchsia.ui.composition;
	using fuchsia.ui.input3;
	using fuchsia.ui.pointer;
	using fuchsia.virtualization;
	using fuchsia.wayland;
	using zx;

	// The following EVENT_* constants indicate which user signal is associated with an event.
	// The value 0 is `ZX_USER_SIGNAL_0`, 1 is `ZX_USER_SIGNAL_1` etc.

	/// Set a flag to inspect queues on the next interrupt.
	const EVENT_SET_QUEUE uint32 = 0;
	/// Set a flag to inspect configs on the next interrupt.
	const EVENT_SET_CONFIG uint32 = 1;
	/// If a flag is set, send an interrupt to the device.
	const EVENT_SET_INTERRUPT uint32 = 2;

	/// Contains the details of a device trap.
	type Trap = struct {
	/// The address of the device trap. This must be page-aligned.
	addr uint64;

	/// The size of the device trap. This must be a multiple of the page size.
	size uint64;
	};

	/// Contains the basic information required to start execution of a device.
	type StartInfo = resource struct {
	/// The trap associated with a device. It is up to the device to set this
	/// trap during device setup.
	trap Trap;

	/// The guest associated with a device. This handle should be used to setup
	/// device traps, and then be released before device operation begins.
	guest zx.Handle:<GUEST, optional>;

	/// The event associated with a device interrupt. This is how the device will
	/// notify the guest of events it should process.
	///
	/// The meaning of the different signals that can be raised on the event are
	/// documented by the EVENT_* constants above.
	event zx.Handle:EVENT;

	/// The VMO used to represent guest physical memory.
	vmo zx.Handle:VMO;
	};

	closed protocol VirtioDevice {
	/// Configure a `queue` for the device. This specifies the `size` and the
	/// guest physical addresses of the queue: `desc`, `avail`, and `used`.
	strict ConfigureQueue(struct {
	queue uint16;
	size uint16;
	desc uint64;
	avail uint64;
	used uint64;
	}) -> ();

	/// Notify a `queue` for the device. Primarily used for black-box testing.
	strict NotifyQueue(struct {
	queue uint16;
	});

	/// Ready a device. This provides the set of `negotiated_features` that the
	/// driver and device have agreed upon.
	strict Ready(struct {
	negotiated_features uint32;
	}) -> ();
	};

	@discoverable
	closed protocol VirtioBalloon {
	compose VirtioDevice;

	/// Start the balloon device.
	strict Start(resource struct {
	start_info StartInfo;
	}) -> ();

	/// Get memory statistics from the balloon device.
	strict GetMemStats() -> (struct {
	status zx.Status;
	mem_stats vector<fuchsia.virtualization.MemStat>:optional;
	});
	};

	@discoverable
	closed protocol VirtioBlock {
	compose VirtioDevice;

	/// Start the block device.
	strict Start(resource struct {
	start_info StartInfo;
	spec fuchsia.virtualization.BlockSpec;
	}) -> (struct {
	capacity uint64;
	block_size uint32;
	});
	};

	@discoverable
	closed protocol VirtioConsole {
	compose VirtioDevice;

	/// Start the console device. This uses `socket` to handle input and output.
	strict Start(resource struct {
	start_info StartInfo;
	socket zx.Handle:SOCKET;
	}) -> ();
	};

	@discoverable
	closed protocol VirtioGpu {
	compose VirtioDevice;

	/// Start the GPU device.
	strict Start(resource struct {
	start_info StartInfo;
	keyboard_listener client_end:<fuchsia.ui.input3.KeyboardListener, optional>;
	mouse_source server_end:<fuchsia.ui.pointer.MouseSource, optional>;
	}) -> ();

	/// Called when a device's configuration is changed.
	strict -> OnConfigChanged();
	};

	type InputType = strict resource union {
	1: keyboard server_end:<fuchsia.ui.input3.KeyboardListener>;
	2: mouse client_end:<fuchsia.ui.pointer.MouseSource>;
	};

	@discoverable
	closed protocol VirtioInput {
	compose VirtioDevice;

	/// Start the input device.
	strict Start(resource struct {
	start_info StartInfo;
	input_type InputType;
	}) -> ();
	};

	@discoverable
	closed protocol VirtioMagma {
	compose VirtioDevice;

	/// Start the magma device.
	strict Start(resource struct {
	start_info StartInfo;
	vmar zx.Handle:VMAR;
	wayland_importer client_end:<VirtioWaylandImporter, optional>;
	}) -> (struct {
	status zx.Status;
	});
	};

	@discoverable
	closed protocol VirtioNet {
	compose VirtioDevice;

	/// Start the net device.
	strict Start(resource struct {
	start_info StartInfo;
	mac_address fuchsia.net.MacAddress;
	enable_bridge bool;
	}) -> () error zx.Status;
	};

	@discoverable
	closed protocol VirtioRng {
	compose VirtioDevice;

	/// Start the RNG device.
	strict Start(resource struct {
	start_info StartInfo;
	}) -> ();
	};

	@discoverable
	closed protocol VirtioSound {
	compose VirtioDevice;

	/// Start the sound device.
	/// The response contains the device's expected static configuration.
	///
	/// + request `start_info` basic info to start the device
	/// + request `enable_input` whether audio input (capture) should be enabled
	/// + request `enable_verbose_logging` whether verbose logging should be enabled
	/// - response `features` supported features
	/// - response `jacks` the virtio_snd_config.jacks value to advertise
	/// - response `streams` the virtio_snd_config.streams value to advertise
	/// - response `chmaps` the virtio_snd_config.chaps value to advertise
	strict Start(resource struct {
	start_info StartInfo;
	enable_input bool;
	enable_verbose_logging bool;
	}) -> (struct {
	features uint32;
	jacks uint32;
	streams uint32;
	chmaps uint32;
	});
	};

	@discoverable
	closed protocol VirtioVsock {
	compose VirtioDevice;

	/// Start the vsock device, setting the guest_cid to the provided value.
	///
	/// Returns:
	/// - ZX_OK if device startup succeeded
	/// - ZX_ERR_INVALID_ARGS if guest_cid is a reserved value
	/// - Any errors returned from fuchsia.virtualization.HostVsockEndpoint::Listen
	strict Start(resource struct {
	start_info StartInfo;
	guest_cid uint32;
	listeners vector<fuchsia.virtualization.Listener>:MAX;
	}) -> () error zx.Status;
	};

	/// Sufficient to contain the opaque image info.
	const VIRTIO_WAYLAND_MAX_IMAGE_INFO_SIZE uint32 = 128;

	/// VirtioImages are shared with VirtioMagma, enabling guest clients to allocate
	/// GBM and Vulkan compatible images and share them with Sommelier as dma-bufs.
	/// An image corresponds to a single buffer collection, and also contains some
	/// opaque image info needed by VirtioMagma.
	type VirtioImage = resource struct {
	vmo zx.Handle:VMO;
	token zx.Handle:<EVENTPAIR, optional>;
	info vector<uint8>:VIRTIO_WAYLAND_MAX_IMAGE_INFO_SIZE;
	};

	const VIRTIO_WAYLAND_INVALID_VFD_ID uint32 = 0;

	// Provides an interface to import images into the wayland device.
	closed protocol VirtioWaylandImporter {
	strict ImportImage(resource struct {
	image VirtioImage;
	}) -> (struct {
	vfd_id uint32;
	});
	strict ExportImage(struct {
	vfd_id uint32;
	}) -> (resource struct {
	status zx.Status;
	image box<VirtioImage>;
	});
	};

	@discoverable
	closed protocol VirtioWayland {
	compose VirtioDevice;

	/// Start the wayland device using the built-in wayland server.
	strict Start(resource struct {
	start_info StartInfo;
	vmar zx.Handle:VMAR;
	sysmem_allocator client_end:fuchsia.sysmem.Allocator;
	scenic_allocator client_end:fuchsia.ui.composition.Allocator;
	}) -> ();

	/// Start the wayland device using the provided wayland server.
	strict StartWithWaylandServer(resource struct {
	start_info StartInfo;
	vmar zx.Handle:VMAR;
	wayland_server client_end:<fuchsia.wayland.Server, optional>;
	sysmem_allocator client_end:fuchsia.sysmem.Allocator;
	scenic_allocator client_end:fuchsia.ui.composition.Allocator;
	}) -> ();

	// Get the VMO importer for this wayland device.
	strict GetImporter(resource struct {
	importer server_end:VirtioWaylandImporter;
	});
	};

	@discoverable
	closed protocol VirtioMem {
	compose VirtioDevice;

	/// Start the mem device.
	strict Start(resource struct {
	start_info StartInfo;
	region_addr uint64;
	plugged_block_size uint64;
	region_size uint64;
	}) -> ();

	/// Called when a device's configuration is changed.
	strict -> OnConfigChanged(struct {
	plugged_size uint64;
	});
	};