Zihan Chen | f463acd | 2021-09-01 14:32:28 -0700 | [diff] [blame] | 1 | // Copyright 2021 The Pigweed Authors |
| 2 | // |
| 3 | // Licensed under the Apache License, Version 2.0 (the "License"); you may not |
| 4 | // use this file except in compliance with the License. You may obtain a copy of |
| 5 | // the License at |
| 6 | // |
| 7 | // https://www.apache.org/licenses/LICENSE-2.0 |
| 8 | // |
| 9 | // Unless required by applicable law or agreed to in writing, software |
| 10 | // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| 11 | // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| 12 | // License for the specific language governing permissions and limitations under |
| 13 | // the License. |
| 14 | syntax = "proto3"; |
| 15 | |
| 16 | package pw_software_update; |
| 17 | |
| 18 | import "pw_software_update/tuf.proto"; |
| 19 | import "pw_software_update/update_bundle.proto"; |
| 20 | import "pw_protobuf_protos/common.proto"; |
| 21 | import "google/protobuf/any.proto"; |
| 22 | |
| 23 | message BundledUpdateState { |
| 24 | enum State { |
| 25 | UNKNOWN = 0; |
| 26 | INACTIVE = 1; |
| 27 | READY_FOR_UPDATE = 2; |
| 28 | VERIFYING_UPDATE_BUNDLE = 3; |
| 29 | VERIFIED_AND_READY_TO_APPLY = 4; |
| 30 | APPLYING_UPDATE = 5; |
| 31 | } |
| 32 | |
| 33 | State manager_state = 1; |
| 34 | |
| 35 | // This is the percentage of estimated progress for the current update |
| 36 | // state in hundreths of a percent. (e.g. 5.00% = 500u) |
| 37 | optional uint32 current_state_progress_hundreth_percent = 2; |
| 38 | } |
| 39 | |
| 40 | message OperationResult { |
| 41 | BundledUpdateState state = 1; |
| 42 | optional google.protobuf.Any extended_status = 2; |
| 43 | } |
| 44 | |
| 45 | message PrepareUpdateResult { |
| 46 | OperationResult result = 1; |
| 47 | optional uint32 transfer_endpoint = 2; |
| 48 | } |
| 49 | |
| 50 | // TODO(pwbug/478): add documentation for details of api contract |
| 51 | service BundledUpdateService { |
| 52 | // Abort any current software update in progress. |
| 53 | // |
| 54 | // Safe to call at any point. |
| 55 | rpc Abort(pw.protobuf.Empty) returns (OperationResult) {}; |
| 56 | |
| 57 | // Get current state of software update. |
| 58 | // |
| 59 | // Safe to call at any point. |
| 60 | rpc SoftwareUpdateState(pw.protobuf.Empty) returns (OperationResult) {}; |
| 61 | |
| 62 | // Get the manifest of the software currently active on the device. |
| 63 | // |
| 64 | // Safe to call at any point. |
| 65 | rpc GetCurrentManifest(pw.protobuf.Empty) returns (stream Manifest) {}; |
| 66 | |
| 67 | // Verify the manifest of the software currently active on device. Do any |
| 68 | // device-specific checks of device contents as needed. |
| 69 | // |
| 70 | // Safe to call at any point. |
| 71 | rpc VerifyCurrentManifest(pw.protobuf.Empty) returns (OperationResult) {}; |
| 72 | |
| 73 | // Get the manifest of any verified and staged update. |
| 74 | // |
| 75 | // Safe to call at any point. |
| 76 | rpc GetStagedManifest(pw.protobuf.Empty) returns (Manifest) {}; |
| 77 | |
| 78 | // Prepare for software update. Do any device-specific tasks needed to be |
| 79 | // ready for update. Open pw_transfer channel used for staging bundle. Device |
| 80 | // UpdateState set to READY_FOR_UPDATE. |
| 81 | // |
| 82 | // Device UpdateState should be INACTIVE when calling, will otherwise be |
| 83 | // rejected. |
| 84 | rpc PrepareForUpdate(pw.protobuf.Empty) returns (OperationResult) {}; |
| 85 | |
| 86 | // Verify the bundle that has been transferred to the staging area. Close the |
| 87 | // pw_transfer channel used for staging bundle. |
| 88 | // |
| 89 | // Device UpdateState should be READY_FOR_UPDATE when calling, will otherwise |
| 90 | // be rejected. |
| 91 | rpc VerifyStagedBundle(pw.protobuf.Empty) returns (OperationResult) {}; |
| 92 | |
| 93 | // Trigger the application of the device, which might result in a device |
| 94 | // becoming slow to respond and possibly reboot. |
| 95 | // |
| 96 | // Device UpdateState should be VERIFIED_AND_READY_TO_APPLY when calling, will |
| 97 | // otherwise be rejected. |
| 98 | rpc ApplyUpdate(pw.protobuf.Empty) returns (OperationResult) {}; |
| 99 | } |