1/*
2 * Copyright (C) 2024 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16syntax = "proto3";
17
18package android.virtualdevice.proto;
19
20option java_package = "android.virtualdevice.proto";
21
22option java_multiple_files = true;
23option java_generic_services = true;
24
25// Request to lease a virtual device with specific hardware and software
26// configurations.
27message LeaseAvdDeviceRequest {
28  // Specifications for the device to be leased.
29  VirtualDeviceSpec device_specification = 1;
30  // User account associated with the device lease.
31  string accounting_user = 2;
32}
33
34// Response containing details of the leased virtual device.
35message LeaseAvdDeviceResponse {
36  // Specifications of the leased device. This can be null or empty if there's
37  // an error.
38  VirtualDeviceSpec leased_device_spec = 1;
39  // Error details if the leasing process fails. This should be null or empty on
40  // success.
41  ErrorDetails error = 2;
42}
43
44// Request to release a virtual device that was previously leased.
45message ReleaseAvdDeviceRequest {
46  // Specifications of the device to be released.
47  VirtualDeviceSpec device_specification = 1;
48}
49
50// Response indicating the status of the virtual device release operation.
51message ReleaseAvdDeviceResponse {
52  // Error details if the release process fails. This should be null or empty on
53  // success.
54  ErrorDetails error = 1;
55}
56
57// Specifications defining a virtual device.
58message VirtualDeviceSpec {
59  // Base specifications for a Cuttlefish device.
60  CuttlefishBuildInfo cuttlefish_spec = 1;
61  // Options for launching the device.
62  CuttlefishLaunchOptions launch_options = 2;
63  // Network ports exposed by the virtual device.
64  repeated ExposedPort ports = 3;
65  // Session ID associated with the device lease.
66  string session_id = 4;
67  // URL for remote access to the device.
68  string server_url = 5;
69  // Duration of the lease in seconds.
70  uint32 lease_length_secs = 6;
71  // Hardware size of the device instance(GENERIC_CF, GENERIC_CF_LARGE,
72  // GENERIC_CF_EXTRA_LARGE)
73  string instance_size = 7;
74}
75
76// Detailed specifications of a Cuttlefish virtual device.
77message CuttlefishBuildInfo {
78  // Build ID of the Cuttlefish device.
79  string build_id = 1;
80  // Build target of the Cuttlefish device.
81  string build_target = 2;
82  // Build branch of the Cuttlefish device.
83  string build_branch = 3;
84}
85
86// Options to customize the launch of a Cuttlefish device.
87message CuttlefishLaunchOptions {
88  // Extra arguments to pass during launch.
89  repeated string extra_launch_args = 1;
90}
91
92// Description of network ports exposed by the virtual device.
93message ExposedPort {
94  // Port number on the remote host machine.
95  uint32 host_port = 1;
96  // Corresponding port in local environment.
97  uint32 guest_port = 2;
98  // Network protocol used (e.g. ADB).
99  string protocol_type = 3;
100}
101
102// Request to set up a connection for a leased virtual device.
103message SetupDeviceConnectionRequest {
104  // Specifications of the device to be connected.
105  VirtualDeviceSpec device_specification = 1;
106}
107
108// Response to a request for setting up a device connection.
109message SetupDeviceConnectionResponse {
110  // Specifications of the connected device. This can be null or empty if
111  // there's an error.
112  VirtualDeviceSpec device_specification = 1;
113
114  // Error details if the connection setup fails. This should be null or empty
115  // on success.
116  ErrorDetails error = 2;
117}
118
119// Request to retrieve logs from a specific virtual device.
120message PullLogsRequest {
121  // Type of log to be retrieved.
122  LogType log_type = 1;
123  // Specifications of the device from which logs are to be pulled.
124  VirtualDeviceSpec device_specification = 2;
125}
126
127// Response containing logs retrieved from a virtual device.
128message PullLogsResponse {
129  // Error details if the log retrieval process fails. This should be null or
130  // empty on success.
131  ErrorDetails error_details = 1;
132  // Location where the logs are stored or accessible locally after being
133  // successfully pulled from the virtual device service. This field is
134  // populated only if the retrieval is successful. It typically contains a
135  // local file path.
136  string log_location = 2;
137}
138
139// Detailed information about errors encountered in using the virtual device
140// component.
141message ErrorDetails {
142  // Human-readable description of the error.
143  string message = 1;
144  // Numeric error code for categorizing the error type.
145  int32 code = 2;
146}
147
148// Enum to specify the type of log to be retrieved.
149enum LogType {
150  // Default value, unspecified log type.
151  LOG_TYPE_UNSPECIFIED = 0;
152  // General log from the Cuttlefish instance.
153  GENERAL_CF_LOG = 1;
154  // Kernel log from the virtual device hosting machine.
155  HOST_KERNEL_LOG = 2;
156  // Log from the host orchestrator.
157  HOST_ORCHESTRATOR_LOG = 3;
158}
159
160// VirtualDeviceManagerInterface provides an interface for managing virtual
161// devices in a virtual device service, including leasing, releasing, and
162// managing device connections.
163service VirtualDeviceManagerInterface {
164  // Leases a virtual device based on the specified requirements and returns
165  // VirtualDeviceSpec with the leased device details.
166  rpc LeaseAvdDevice(LeaseAvdDeviceRequest) returns (LeaseAvdDeviceResponse) {}
167
168  // Releases a previously leased virtual device. Returns an error if failed to
169  // release the device.
170  rpc ReleaseAvdDevice(ReleaseAvdDeviceRequest)
171      returns (ReleaseAvdDeviceResponse) {}
172
173  // Sets up a connection for a leased virtual device.
174  rpc SetupDeviceConnection(SetupDeviceConnectionRequest)
175      returns (SetupDeviceConnectionResponse) {}
176
177  // Retrieves specified logs from a leased virtual device.
178  rpc PullLogs(PullLogsRequest) returns (PullLogsResponse) {}
179}
180