pw_software_update: land initial service implementation
Also renames the pw_software_update proto package to instead
use the canonical pw.software_update. As part of this the
Manifest and UpdateBundle C++ classes were renamed to
ManifestAccessor and UpdateBundleAccessor.
Moves the service.proto to bundled_update.proto and renames the source
files accordingly.
No-Docs-Update-Reason: Module still in early development
Requires: pigweed-internal:15503
Change-Id: I6531ee5772c17331e9c5ce7e16f4b72002656834
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/61960
Commit-Queue: Auto-Submit <auto-submit@pigweed.google.com.iam.gserviceaccount.com>
Reviewed-by: Wyatt Hepler <hepler@google.com>
Reviewed-by: David Rogers <davidrogers@google.com>
Pigweed-Auto-Submit: Ewout van Bekkum <ewout@google.com>
diff --git a/pw_software_update/bundled_update.proto b/pw_software_update/bundled_update.proto
new file mode 100644
index 0000000..39e042e
--- /dev/null
+++ b/pw_software_update/bundled_update.proto
@@ -0,0 +1,113 @@
+// Copyright 2021 The Pigweed Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may not
+// use this file except in compliance with the License. You may obtain a copy of
+// the License at
+//
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations under
+// the License.
+syntax = "proto3";
+
+package pw.software_update;
+
+import "pw_software_update/tuf.proto";
+import "pw_software_update/update_bundle.proto";
+import "pw_protobuf_protos/common.proto";
+import "google/protobuf/any.proto";
+
+message BundledUpdateState {
+ enum State {
+ UNKNOWN = 0;
+ INACTIVE = 1;
+ READY_FOR_UPDATE = 2;
+ VERIFYING_UPDATE_BUNDLE = 3;
+ VERIFIED_AND_READY_TO_APPLY = 4;
+ APPLYING_UPDATE = 5;
+ }
+
+ State manager_state = 1;
+
+ // This is the percentage of estimated progress for the current update
+ // state in hundreths of a percent. (e.g. 5.00% = 500u)
+ optional uint32 current_state_progress_hundreth_percent = 2;
+}
+
+message OperationResult {
+ BundledUpdateState state = 1;
+ optional google.protobuf.Any extended_status = 2;
+}
+
+message PrepareUpdateResult {
+ OperationResult result = 1;
+ optional uint32 transfer_id = 2;
+}
+
+// TODO(pwbug/478): add documentation for details of api contract
+service BundledUpdate {
+ // Abort any current software update in progress.
+ //
+ // Safe to call at any point.
+ rpc Abort(pw.protobuf.Empty) returns (OperationResult) {};
+
+ // Get current state of software update.
+ //
+ // Safe to call at any point.
+ rpc SoftwareUpdateState(pw.protobuf.Empty) returns (OperationResult) {};
+
+ // Get the manifest of the software currently active on the device.
+ //
+ // Safe to call at any point.
+ rpc GetCurrentManifest(pw.protobuf.Empty) returns (stream Manifest) {};
+
+ // Verify the manifest of the software currently active on device. Do any
+ // device-specific checks of device contents as needed.
+ //
+ // Safe to call at any point.
+ rpc VerifyCurrentManifest(pw.protobuf.Empty) returns (OperationResult) {};
+
+ // Get the manifest of any verified and staged update.
+ //
+ // Safe to call at any point.
+ rpc GetStagedManifest(pw.protobuf.Empty) returns (Manifest) {};
+
+ // Prepare for software update. Do any device-specific tasks needed to be
+ // ready for update. Open pw_transfer channel used for staging bundle. Device
+ // UpdateState set to READY_FOR_UPDATE.
+ //
+ // Device UpdateState should be INACTIVE when calling, will otherwise be
+ // rejected.
+ rpc PrepareForUpdate(pw.protobuf.Empty) returns (PrepareUpdateResult) {};
+
+ // Verifies the bundle that has been transferred to the traging area. Closes
+ // the pw_transfer channel used for the staging bundle. If the verification is
+ // successful it immediately triggers the update of the device, which might
+ // result in a device becoming slow to respond and possibly reboot.
+ //
+ // Device UpdateState should be READY_FOR_UPDATE when calling, will otherwise
+ // be rejected.
+ rpc VerifyAndApplyStagedBundle(pw.protobuf.Empty) returns (OperationResult) {
+ };
+
+ // Verify the bundle that has been transferred to the staging area. Closes the
+ // pw_transfer channel used for the staging bundle.
+ //
+ // Device UpdateState should be READY_FOR_UPDATE when calling, will otherwise
+ // be rejected.
+ //
+ // Note: VerifyAndApplyStagedBundle is preferred if possible to minimize the
+ // duration of time between verification and the apply from a data integrity
+ // and security risk point of view.
+ rpc VerifyStagedBundle(pw.protobuf.Empty) returns (OperationResult) {};
+
+ // Trigger the update of the device, which might result in a device
+ // becoming slow to respond and possibly reboot.
+ //
+ // Device UpdateState should be VERIFIED_AND_READY_TO_APPLY when calling, will
+ // otherwise be rejected.
+ rpc ApplyStagedBundle(pw.protobuf.Empty) returns (OperationResult) {};
+}