pw_software_update: add update_helper and update_service
No-Docs-Update-Reason: this module is far from stablized
Change-Id: I408d575308bcfeb69d6fcb23448472734c729e95
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/59544
Reviewed-by: David Rogers <davidrogers@google.com>
Commit-Queue: Zihan Chen <zihanchen@google.com>
diff --git a/pw_software_update/BUILD.bazel b/pw_software_update/BUILD.bazel
index ce2c69a..861302e 100644
--- a/pw_software_update/BUILD.bazel
+++ b/pw_software_update/BUILD.bazel
@@ -46,6 +46,26 @@
],
)
+pw_cc_library(
+ name = "update_backend",
+ hdrs = ["public/pw_software_update/update_backend.h"],
+ includes = ["public"],
+ deps = [
+ ":update_bundle_proto",
+ "//pw_status",
+ ],
+)
+
+pw_cc_library(
+ name = "update_service",
+ srcs = ["service.cc"],
+ hdrs = ["public/pw_software_update/service.h"],
+ includes = ["public"],
+ deps = [
+ ":update_bundle_proto",
+ ],
+)
+
pw_cc_test(
name = "update_bundle_test",
srcs = ["update_bundle_test.cc"],
diff --git a/pw_software_update/BUILD.gn b/pw_software_update/BUILD.gn
index 16ba387..6f431d7 100644
--- a/pw_software_update/BUILD.gn
+++ b/pw_software_update/BUILD.gn
@@ -16,41 +16,40 @@
import("$dir_pw_docgen/docs.gni")
import("$dir_pw_protobuf_compiler/proto.gni")
+import("$dir_pw_third_party/protobuf/protobuf.gni")
import("$dir_pw_unit_test/test.gni")
-config("default_config") {
+config("public_include_path") {
include_dirs = [ "public" ]
+ visibility = [ ":*" ]
}
-pw_proto_library("protos") {
- sources = [
- "tuf.proto",
- "update_bundle.proto",
- ]
- prefix = "pw_software_update"
- python_package = "py"
-}
-
-pw_source_set("update_bundle") {
- public_configs = [ ":default_config" ]
- public_deps = [
- dir_pw_blob_store,
- dir_pw_kvs,
- ]
- deps = [ dir_pw_log ]
- public = [
- "public/pw_software_update/config.h",
- "public/pw_software_update/update_bundle.h",
- ]
-}
-
-pw_test("update_bundle_test") {
- sources = [ "update_bundle_test.cc" ]
- public_deps = [
- ":update_bundle",
- "$dir_pw_kvs:fake_flash",
- "$dir_pw_kvs:fake_flash_test_key_value_store",
- ]
+if (dir_pw_third_party_protobuf != "") {
+ pw_proto_library("protos") {
+ deps = [
+ "$dir_pw_protobuf:common_protos",
+ "$dir_pw_third_party/protobuf:wellknown_types",
+ ]
+ sources = [
+ "service.proto",
+ "tuf.proto",
+ "update_bundle.proto",
+ ]
+ prefix = "pw_software_update"
+ python_package = "py"
+ }
+} else {
+ # placeholder target to allow py package to build
+ pw_proto_library("protos") {
+ deps = [ "$dir_pw_protobuf:common_protos" ]
+ sources = [
+ "service.proto",
+ "tuf.proto",
+ "update_bundle.proto",
+ ]
+ prefix = "pw_software_update"
+ python_package = "py"
+ }
}
pw_test_group("tests") {
@@ -60,3 +59,55 @@
pw_doc_group("docs") {
sources = [ "docs.rst" ]
}
+
+if (dir_pw_third_party_nanopb != "" && dir_pw_third_party_protobuf != "") {
+ pw_source_set("rpc_service") {
+ public_configs = [ ":public_include_path" ]
+ public_deps = [ ":protos.nanopb_rpc" ]
+ deps = [ dir_pw_log ]
+ sources = [
+ "public/pw_software_update/service.h",
+ "service.cc",
+ ]
+ }
+
+ pw_source_set("update_backend") {
+ public_configs = [ ":public_include_path" ]
+ public_deps = [
+ ":protos.nanopb",
+ dir_pw_status,
+ ]
+ sources = [ "public/pw_software_update/update_backend.h" ]
+ }
+
+ pw_source_set("update_bundle") {
+ public_configs = [ ":public_include_path" ]
+ public_deps = [
+ ":update_backend",
+ dir_pw_blob_store,
+ dir_pw_kvs,
+ ]
+ deps = [ dir_pw_log ]
+ public = [
+ "public/pw_software_update/config.h",
+ "public/pw_software_update/update_bundle.h",
+ ]
+ }
+} else {
+ group("rpc_service") {
+ }
+ group("update_bundle") {
+ }
+}
+
+pw_test("update_bundle_test") {
+ enable_if =
+ dir_pw_third_party_nanopb != "" && dir_pw_third_party_protobuf != ""
+ sources = [ "update_bundle_test.cc" ]
+ public_deps = [
+ ":rpc_service",
+ ":update_bundle",
+ "$dir_pw_kvs:fake_flash",
+ "$dir_pw_kvs:fake_flash_test_key_value_store",
+ ]
+}
diff --git a/pw_software_update/public/pw_software_update/service.h b/pw_software_update/public/pw_software_update/service.h
new file mode 100644
index 0000000..4caedea
--- /dev/null
+++ b/pw_software_update/public/pw_software_update/service.h
@@ -0,0 +1,17 @@
+// 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.
+
+#pragma once
+
+#include "pw_software_update/service.rpc.pb.h"
diff --git a/pw_software_update/public/pw_software_update/update_backend.h b/pw_software_update/public/pw_software_update/update_backend.h
new file mode 100644
index 0000000..856df65
--- /dev/null
+++ b/pw_software_update/public/pw_software_update/update_backend.h
@@ -0,0 +1,88 @@
+// 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.
+
+#pragma once
+
+#include "pw_software_update/update_bundle.pb.h"
+#include "pw_status/status.h"
+
+namespace pw::software_update {
+
+// TODO(pwbug/478): update documentation for backend api contract
+class BundledUpdateBackend {
+ public:
+ virtual ~BundledUpdateBackend() = default;
+
+ // Perform any product-specific abort tasks before mark as aborted in bundled
+ // updater.
+ // This should set any downstream state to a default no-update-pending state.
+ virtual Status BeforeUpdateAbort() { return OkStatus(); };
+
+ // Perform any product-specific tasks needed before starting update sequence.
+ virtual Status BeforeUpdateStart() { return OkStatus(); };
+
+ // Perform any product-specific tasks needed before starting verification.
+ virtual Status BeforeUpdateVerify() { return OkStatus(); };
+
+ // Perform any product-specific bundle verification tasks (e.g. hw version
+ // match check), done after TUF bundle verification process.
+ virtual Status VerifyMetadata(
+ [[maybe_unused]] const pw_software_update_Manifest& manifest) {
+ return OkStatus();
+ };
+
+ // Perform product-specific tasks after all bundle verifications are complete.
+ virtual Status AfterBundleVerified() { return OkStatus(); };
+
+ // Optionally verify that the instance/content of the target file in use
+ // on-device matches the metadata in the given manifest, called before apply.
+ // (e.g. by checksum, if failed abort partial update and wipe/mark-invalid
+ // running manifest)
+ virtual Status VerifyTargetFile(
+ [[maybe_unused]] const pw_software_update_Manifest& manifest,
+ [[maybe_unused]] std::string_view target_file_name) {
+ return OkStatus();
+ };
+
+ // Perform any product-specific tasks before apply sequence started
+ virtual Status BeforeUpdateApply() { return OkStatus(); };
+
+ // Get status information from update backend. This will not be called when
+ // BundledUpdater is in a step where it has entire control with no operation
+ // handed over to update backend.
+ virtual int64_t GetStatus() { return 0; }
+
+ // Update the specific target file on the device.
+ virtual Status ApplyTargetFile(
+ [[maybe_unused]] std::string_view target_file_name,
+ [[maybe_unused]] stream::Reader& target_payload) {
+ return OkStatus();
+ };
+
+ // Perform any product-specific tasks needed after completion of the update.
+ virtual Status AfterUpdateComplete() { return OkStatus(); };
+
+ // Get reader of the device's root metadata.
+ virtual Status GetRootMetadataReader([[maybe_unused]] stream::Reader* out) {
+ return Status::Unimplemented();
+ };
+
+ // Use a reader that provides a new root metadata for the device to save.
+ virtual Status UpdateRootMetadata(
+ [[maybe_unused]] stream::Reader& root_metadata) {
+ return OkStatus();
+ };
+};
+
+} // namespace pw::software_update
\ No newline at end of file
diff --git a/pw_software_update/public/pw_software_update/update_bundle.h b/pw_software_update/public/pw_software_update/update_bundle.h
index 7ab889b..5f56a21 100644
--- a/pw_software_update/public/pw_software_update/update_bundle.h
+++ b/pw_software_update/public/pw_software_update/update_bundle.h
@@ -17,13 +17,13 @@
#include <cstddef>
#include "pw_blob_store/blob_store.h"
+#include "pw_software_update/update_backend.h"
namespace pw::software_update {
// TODO(pwbug/456): Place-holder declaration for now. To be imlemented
// and moved elsewhere.
class ElementPayloadReader {};
-class BundledUpdateHelper {};
class Manifest;
// UpdateBundle is responsible for parsing, verifying and providing
@@ -76,8 +76,8 @@
// update_bundle - The software update bundle data on storage.
// helper - project-specific BundledUpdateHelper
UpdateBundle(blob_store::BlobStore& update_bundle,
- BundledUpdateHelper& helper)
- : bundle_(update_bundle), helper_(helper) {}
+ BundledUpdateBackend& backend)
+ : bundle_(update_bundle), backend_(backend) {}
// Opens and verifies the software update bundle, using the TUF process.
//
@@ -120,7 +120,7 @@
private:
blob_store::BlobStore& bundle_;
- BundledUpdateHelper& helper_;
+ BundledUpdateBackend& backend_;
};
} // namespace pw::software_update
\ No newline at end of file
diff --git a/pw_software_update/service.cc b/pw_software_update/service.cc
new file mode 100644
index 0000000..8ad1afd
--- /dev/null
+++ b/pw_software_update/service.cc
@@ -0,0 +1,17 @@
+// 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.
+
+#include "pw_software_update/service.h"
+
+namespace pw_software_update {}
\ No newline at end of file
diff --git a/pw_software_update/service.proto b/pw_software_update/service.proto
new file mode 100644
index 0000000..b8ad924
--- /dev/null
+++ b/pw_software_update/service.proto
@@ -0,0 +1,99 @@
+// 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_endpoint = 2;
+}
+
+// TODO(pwbug/478): add documentation for details of api contract
+service BundledUpdateService {
+ // 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 (OperationResult) {};
+
+ // Verify the bundle that has been transferred to the staging area. Close the
+ // pw_transfer channel used for staging bundle.
+ //
+ // Device UpdateState should be READY_FOR_UPDATE when calling, will otherwise
+ // be rejected.
+ rpc VerifyStagedBundle(pw.protobuf.Empty) returns (OperationResult) {};
+
+ // Trigger the application 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 ApplyUpdate(pw.protobuf.Empty) returns (OperationResult) {};
+}
diff --git a/pw_software_update/update_bundle_test.cc b/pw_software_update/update_bundle_test.cc
index 9f2ba3f..4522cac 100644
--- a/pw_software_update/update_bundle_test.cc
+++ b/pw_software_update/update_bundle_test.cc
@@ -17,6 +17,7 @@
#include "gtest/gtest.h"
#include "pw_kvs/fake_flash_memory.h"
#include "pw_kvs/test_key_value_store.h"
+#include "pw_software_update/update_backend.h"
namespace pw::software_update {
namespace {
@@ -31,27 +32,27 @@
UpdateBundleTest()
: blob_flash_(kFlashAlignment),
blob_partition_(&blob_flash_),
- bunble_blob_("TestBundle",
+ bundle_blob_("TestBundle",
blob_partition_,
nullptr,
kvs::TestKvs(),
kBufferSize) {}
- blob_store::BlobStoreBuffer<kBufferSize>& bunble_blob() {
- return bunble_blob_;
+ blob_store::BlobStoreBuffer<kBufferSize>& bundle_blob() {
+ return bundle_blob_;
}
- BundledUpdateHelper& helper() { return helper_; }
+ BundledUpdateBackend& backend() { return backend_; }
private:
kvs::FakeFlashMemoryBuffer<kSectorSize, kSectorCount> blob_flash_;
kvs::FlashPartition blob_partition_;
- blob_store::BlobStoreBuffer<kBufferSize> bunble_blob_;
- BundledUpdateHelper helper_;
+ blob_store::BlobStoreBuffer<kBufferSize> bundle_blob_;
+ BundledUpdateBackend backend_;
};
} // namespace
-TEST_F(UpdateBundleTest, Create) { UpdateBundle(bunble_blob(), helper()); }
+TEST_F(UpdateBundleTest, Create) { UpdateBundle(bundle_blob(), backend()); }
} // namespace pw::software_update
