[VOL-3996] Updating Image Protos
Change-Id: Id293cca9ea9b68ec337e73e9d4a9e3ad444e335c
diff --git a/protos/voltha_protos/device.proto b/protos/voltha_protos/device.proto
index 142f8e9..9e65bee 100644
--- a/protos/voltha_protos/device.proto
+++ b/protos/voltha_protos/device.proto
@@ -70,38 +70,65 @@
uint32 max_skew = 7; //Default value is set to 5 seconds
}
-// Describes instance of software image on the device
+//Object representing an image
message Image {
+
string name = 1; // software patch name
- string version = 2; // version of software
- string hash = 3; // md5 hash
+
+ // Version, this is the sole identifier of the image. it's the vendor specified OMCI version
+ // must be known at the time of initiating a download, activate, commit image on an onu.
+ string version = 2;
+
+ // hash of the image to be verified against
+ // Deprecated in voltha 2.8, will be removed
+ uint32 hash = 3;
+
+ // Deprecated in voltha 2.8, will be removed
string install_datetime = 4; // combined date and time expressed in UTC.
- // use ISO 8601 format for date and time
+ // use ISO 8601 format for date and time
// The active software image is one that is currently loaded and executing
// in the ONU or circuit pack. Under normal operation, one software image
// is always active while the other is inactive. Under no circumstances are
// both software images allowed to be active at the same time
+ // Deprecated in voltha 2.8, will be removed
bool is_active = 5; // True if the image is active
// The committed software image is loaded and executed upon reboot of the
// ONU and/or circuit pack. During normal operation, one software image is
// always committed, while the other is uncommitted.
+ // Deprecated in voltha 2.8, will be removed
bool is_committed = 6; // True if the image is committed
// A software image is valid if it has been verified to be an executable
// code image. The verification mechanism is not subject to standardization;
// however, it should include at least a data integrity (e.g., CRC) check of
// the entire code image.
+ // Deprecated in voltha 2.8, will be removed
bool is_valid = 7; // True if the image is valid
+
+ // URL where the image is available
+ // URL MUST be fully qualified,
+ // including filename, username and password
+ string url = 8;
+
+ // Represents the vendor/device mfr
+ // Needs to match the vendor of the device the image will be installed on
+ // optional, if not matched no check will be performed
+ string vendor = 9;
+
+ // Represents the ONU Image CRC value.
+ // Default to value 0 if not specified.
+ // If different then 0 it's used to verify the image retrieved from outside before sending it to the ONU.
+ // Calculation of this needs to be done according to ITU-T I.363.5 as per OMCI spec (section A.2.27)
+ uint32 crc32 = 10;
+
+ //TODO augment with RecommendedWindowsSize, Timeout and other valuable attributes.
+
}
-// List of software on the device
-message Images {
- repeated Image image = 1;
-}
-
-//TODO: ImageDownload is not actively used (05/19/2020). When this is tackled, can remove extra/unnecessary fields.
+// Older version of the API please see DeviceImageDownloadRequest
+// Deprecated in voltha 2.8, will be removed
message ImageDownload {
enum ImageDownloadState {
DOWNLOAD_UNKNOWN = 0;
@@ -172,10 +199,91 @@
uint32 file_size = 13;
}
+// Deprecated in voltha 2.8, will be removed
message ImageDownloads {
repeated ImageDownload items = 2;
}
+message Images {
+ repeated Image image = 1;
+}
+
+// OnuImage represents the OMCI information as per OMCI spec
+// the information will be populates exactly as extracted from the device.
+message OnuImage {
+ //image version
+ string version = 1;
+ bool isCommited = 2;
+ bool isActive = 3;
+ bool isValid = 4;
+ string productCode = 5;
+ // Hash is computed by the ONU and is optional as per OMCI spec (paragraph 9.1.4)
+ // No assumption should be made on the existence of this attribute at any time.
+ string hash = 6;
+}
+
+message OnuImages {
+ repeated OnuImage items = 1;
+}
+
+message DeviceImageState {
+ string device_id = 1;
+ ImageState imageState = 2;
+}
+
+message ImageState {
+ enum ImageDownloadState {
+ DOWNLOAD_UNKNOWN = 0;
+ DOWNLOAD_SUCCEEDED = 1;
+ DOWNLOAD_REQUESTED = 2;
+ DOWNLOAD_STARTED = 3;
+ DOWNLOAD_FAILED = 4;
+ DOWNLOAD_UNSUPPORTED = 5;
+ DOWNLOAD_CANCELLING = 6;
+ DOWNLOAD_CANCELLED = 7;
+ }
+
+ enum ImageFailureReason {
+ NO_ERROR = 0;
+ INVALID_URL = 1;
+ DEVICE_BUSY = 2;
+ INSUFFICIENT_SPACE = 3; // VOLTHA ONU ADAPTER has no more space to store images
+ UNKNOWN_ERROR = 4; // Used also for Checksum failure on ONU
+ CANCELLED_ON_REQUEST = 5;
+ CANCELLED_ON_ONU_STATE = 6;
+ VENDOR_DEVICE_MISMATCH = 7;
+ OMCI_TRANSFER_ERROR = 8;
+ IMAGE_REFUSED_BY_ONU = 9;
+ }
+
+ enum ImageActivationState {
+ IMAGE_UNKNOWN = 0;
+ IMAGE_INACTIVE = 1;
+ IMAGE_ACTIVATING = 2; // Happens during Reboot of the ONU after activate call.
+ IMAGE_ACTIVE = 3;
+ IMAGE_COMMITTING = 4;
+ IMAGE_COMMITTED = 5;
+ IMAGE_ACTIVATION_ABORTING = 6;
+ IMAGE_ACTIVATION_ABORTED = 7;
+ IMAGE_COMMIT_ABORTING = 8;
+ IMAGE_COMMIT_ABORTED = 9;
+ IMAGE_DOWNLOADING = 10;
+ }
+
+ // image version
+ string version = 1;
+
+ // Download state
+ ImageDownloadState download_state = 2;
+
+ // Image Operation Failure reason (use for both Download and Activate)
+ ImageFailureReason reason= 3;
+
+ // Image activation state
+ ImageActivationState image_state = 4;
+
+}
+
message Port {
enum PortType {
UNKNOWN = 0;
@@ -249,7 +357,7 @@
string serial_number = 10 [(access) = READ_ONLY];
string vendor_id = 24 [(access) = READ_ONLY];
- // Addapter that takes care of device
+ // Adapter that takes care of device
string adapter = 11 [(access) = READ_ONLY];
// Device contact on vlan (if 0, no vlan)
@@ -302,6 +410,7 @@
PmConfigs pm_configs = 131 [(child_node) = {}];
repeated ImageDownload image_downloads = 133 [(child_node) = {key: "name"}];
+
}
message Devices {
diff --git a/protos/voltha_protos/voltha.proto b/protos/voltha_protos/voltha.proto
index c2d5459..56bcf18 100644
--- a/protos/voltha_protos/voltha.proto
+++ b/protos/voltha_protos/voltha.proto
@@ -162,6 +162,42 @@
string id = 2;
}
+message DeviceImageDownloadRequest {
+
+ // Device Id
+ // allows for operations on multiple devices.
+ repeated common.ID device_id = 1;
+
+ //The image for the device containing all the information
+ Image image = 2;
+
+ //Activate the image if the download to the device is successful
+ bool activateOnSuccess = 3;
+
+ //Automatically commit the image if the activation on the device is successful
+ bool commitOnSuccess = 4;
+}
+
+message DeviceImageRequest {
+
+ //Device Id
+ //allows for operations on multiple adapters.
+ repeated common.ID device_id = 1;
+
+ // Image Version, this is the sole identifier of the image. it's the vendor specified OMCI version
+ // must be known at the time of initiating a download, activate, commit image on an onu.
+ string version = 2;
+
+ //Automatically commit the image if the activation on the device is successful
+ bool commitOnSuccess = 3;
+}
+
+message DeviceImageResponse {
+
+ //Image state for the different devices
+ repeated DeviceImageState device_image_states = 1;
+}
+
// Additional information required to process flow at device adapters
message FlowMetadata {
// Meters associated with flow-update to adapter
@@ -369,18 +405,19 @@
}
// Delete a device
- rpc DeleteDevice(common.ID) returns(google.protobuf.Empty) {
+ rpc DeleteDevice (common.ID) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/api/v1/devices/{id}/delete"
};
}
// Forcefully delete a device
- rpc ForceDeleteDevice(common.ID) returns(google.protobuf.Empty) {
+ rpc ForceDeleteDevice (common.ID) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/api/v1/devices/{id}/force_delete"
};
}
+
// Request an image download to the standby partition
// of a device.
// Note that the call is expected to be non-blocking.
@@ -393,6 +430,7 @@
// Get image download status on a device
// The request retrieves progress on device and updates db record
+ // Deprecated in voltha 2.8, will be removed
rpc GetImageDownloadStatus(ImageDownload) returns(ImageDownload) {
option (google.api.http) = {
get: "/api/v1/devices/{id}/image_downloads/{name}/status"
@@ -400,6 +438,7 @@
}
// Get image download db record
+ // Deprecated in voltha 2.8, will be removed
rpc GetImageDownload(ImageDownload) returns(ImageDownload) {
option (google.api.http) = {
get: "/api/v1/devices/{id}/image_downloads/{name}"
@@ -407,6 +446,7 @@
}
// List image download db records for a given device
+ // Deprecated in voltha 2.8, will be removed
rpc ListImageDownloads(common.ID) returns(ImageDownloads) {
option (google.api.http) = {
get: "/api/v1/devices/{id}/image_downloads"
@@ -414,6 +454,7 @@
}
// Cancel an existing image download process on a device
+ // Deprecated in voltha 2.8, will be removed
rpc CancelImageDownload(ImageDownload) returns(common.OperationResp) {
option (google.api.http) = {
delete: "/api/v1/devices/{id}/image_downloads/{name}"
@@ -427,6 +468,7 @@
// If no reboot, then a reboot is required to make the
// activated image running on device
// Note that the call is expected to be non-blocking.
+ // Deprecated in voltha 2.8, will be removed
rpc ActivateImageUpdate(ImageDownload) returns(common.OperationResp) {
option (google.api.http) = {
post: "/api/v1/devices/{id}/image_downloads/{name}/image_update"
@@ -441,6 +483,7 @@
// If no reboot, then a reboot is required to make the
// previous image running on device
// Note that the call is expected to be non-blocking.
+ // Deprecated in voltha 2.8, will be removed
rpc RevertImageUpdate(ImageDownload) returns(common.OperationResp) {
option (google.api.http) = {
post: "/api/v1/devices/{id}/image_downloads/{name}/image_revert"
@@ -448,15 +491,75 @@
};
}
+ // Downloads a certain image to the standby partition of the devices
+ // Note that the call is expected to be non-blocking.
+ rpc DownloadImageToDevice (DeviceImageDownloadRequest) returns (DeviceImageResponse) {
+ option (google.api.http) = {
+ get: "/api/v1/devices/images/download_images"
+ };
+ }
+
+ // Get image status on a number of devices devices
+ // Polled from northbound systems to get state of download/activate/commit
+ rpc GetImageStatus (DeviceImageRequest) returns (DeviceImageResponse) {
+ option (google.api.http) = {
+ get: "/api/v1/devices/images/images_status"
+ };
+ }
+
+ // Aborts the upgrade of an image on a device
+ // To be used carefully, stops any further operations for the Image on the given devices
+ // Might also stop if possible existing work, but no guarantees are given,
+ // depends on implementation and procedure status.
+ rpc AbortImageUpgradeToDevice (DeviceImageRequest) returns (DeviceImageResponse) {
+ option (google.api.http) = {
+ get: "/api/v1/devices/images/abort_upgrade_images"
+ };
+ }
+
+ // Get Both Active and Standby image for a given device
+ rpc GetOnuImages (common.ID) returns (OnuImages) {
+ option (google.api.http) = {
+ get: "/api/v1/devices/{id}/onu_images"
+ };
+ }
+
+ // Activate the specified image from a standby partition
+ // to active partition.
+ // Depending on the device implementation, this call
+ // may or may not cause device reboot.
+ // If no reboot, then a reboot is required to make the
+ // activated image running on device
+ // Note that the call is expected to be non-blocking.
+ rpc ActivateImage (DeviceImageRequest) returns (DeviceImageResponse) {
+ option (google.api.http) = {
+ post: "/api/v1/devices/images/activate_images"
+ body: "*"
+ };
+ }
+
+ // Commit the specified image to be default.
+ // Depending on the device implementation, this call
+ // may or may not cause device reboot.
+ // If no reboot, then a reboot is required to make the
+ // activated image running on device upon next reboot
+ // Note that the call is expected to be non-blocking.
+ rpc CommitImage (DeviceImageRequest) returns (DeviceImageResponse) {
+ option (google.api.http) = {
+ post: "/api/v1/devices/images/commit_images"
+ body: "*"
+ };
+ }
+
// List ports of a device
- rpc ListDevicePorts(common.ID) returns(Ports) {
+ rpc ListDevicePorts (common.ID) returns (Ports) {
option (google.api.http) = {
get: "/api/v1/devices/{id}/ports"
};
}
// List pm config of a device
- rpc ListDevicePmConfigs(common.ID) returns(PmConfigs) {
+ rpc ListDevicePmConfigs (common.ID) returns (PmConfigs) {
option (google.api.http) = {
get: "/api/v1/devices/{id}/pm_configs"
};