Raritan PX2/PX3 JSON-RPC API
Firmware.idl
1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /*
3  * Copyright 2009 Raritan Inc. All rights reserved.
4  */
5 
6 #include <UserEvent.idl>
7 #include <Event.idl>
8 
9 /**
10  * %Firmware Management
11  */
12 module firmware {
13 
14  /**
15  * %Firmware update history status
16  */
17  enumeration UpdateHistoryStatus {
18  SUCCESSFUL, ///< The update was successfully completed
19  FAILED, ///< The update failed
20  INCOMPLETE ///< The update was not completed
21  };
22 
23  /**
24  * %Firmware update history entry
25  * TODO: implement CR# 45668 on next interface change
26  * add comment field based on firmware tag "char tag[64];"
27  * to improve firmware update history entries without rootfs images
28  */
29  structure UpdateHistoryEntry {
30  time timestamp; ///< Timestamp when the update was started
31  string oldVersion; ///< Previous firmware version
32  string imageVersion; ///< Firmware version of update image
33  string imageMD5; ///< MD5 hash of update image
34  UpdateHistoryStatus status; ///< Update status
35  };
36 
37  /**
38  * Image upload/download state
39  */
40  enumeration ImageState {
41  NONE, ///< No firmware image has been uploaded/downloaded
42  UPLOADING, ///< A firmware image is currently being uploaded
43  UPLOAD_FAILED, ///< There was a problem uploading an image to the device
44  DOWNLOADING, ///< The device is downloading a firmware image from a URL
45  DOWNLOAD_FAILED, ///< There was a problem downloading the image from a URL
46  COMPLETE ///< A complete image has been successfully uploaded/downloaded
47  };
48 
49  /**
50  * Image upload/download status
51  */
52  structure ImageStatus {
53  ImageState state; ///< Image upload/download state
54  string error_message; ///< Error message; empty if there was no error
55  time time_started; ///< Timestamp of the last state change (if available)
56  int size_total; ///< Total size of the image (if available)
57  int size_done; ///< Progress of the running upload or download (if available)
58  };
59 
60  /**
61  * %Firmware image information
62  */
63  structure ImageInfo_1_0_1 {
64  boolean valid; ///< The file is a valid firmware image
65 
66  string version; ///< %Firmware image version
67  string min_required_version; ///< Minimum running firmware version for image
68  string min_downgrade_version; ///< Minimum image version for running firmware
69 
70  string product; ///< Product name
71  string platform; ///< Platform name
72  string oem; ///< OEM name
73  string hwid_whitelist; ///< Hardware ID whitelist
74  string hwid_blacklist; ///< Hardware ID blacklist
75 
76  boolean compatible; ///< \c true if the image is compatible with this device
77 
78  boolean signature_present; ///< \c true if the image is signed
79  string signed_by; ///< Signature issuer
80  boolean signature_good; ///< \c true if the signature is valid
81  string certified_by; ///< Key certificate issuer
82  boolean certificate_good; ///< \c true if the key certificate is valid
83 
84  boolean model_list_present; ///< \c true if the image includes a supported models list
85  boolean model_supported; ///< \c true if the model is found on the support list
86  };
87 
88  /**
89  * Flags for startUpdate() method
90  */
91  enumeration UpdateFlags {
92  CROSS_OEM, ///< Ignore version, product and OEM constraints
93  CROSS_HW, ///< Ignore hardware constraints
94  ALLOW_UNTRUSTED ///< Allow untrusted firmwares
95  };
96 
97  /** Event: System startup finished */
98  valueobject SystemStartupEvent extends idl.Event {};
99  /** Event: System shutdown started */
100  valueobject SystemShutdownEvent extends event.UserEvent {};
101 
102  /** Event: Firmware validation failed */
103  valueobject FirmwareValidationFailedEvent extends event.UserEvent {};
104 
105  /** Event: Firmware update base event */
106  valueobject FirmwareUpdateEvent extends event.UserEvent {
107  string oldVersion; ///< Firmware version the device is being upgraded from
108  string newVersion; ///< Firmware version the device is being upgraded to
109  };
110 
111  /** Event: Firmware update started */
112  valueobject FirmwareUpdateStartedEvent extends FirmwareUpdateEvent {};
113  /** Event: Firmware updated successfully */
115  /** Event: Firmware update failed */
117 
118  /**
119  * %Firmware management methods
120  */
121  interface Firmware_2_0_1 {
122 
123  /**
124  * Reboot the device.
125  *
126  * This function will fail if a firmware update is in progress.
127  */
128  void reboot();
129 
130  /**
131  * Reset the device configuration to factory defaults.
132  */
133  void factoryReset();
134 
135  /**
136  * Reset all device data to factory defaults. This includes energy
137  * counters, firmware update history and reliability data.
138  *
139  * @note This command is only available during manufacturing!
140  *
141  * @return 0 if OK
142  * @return 1 if not in production mode
143  */
144  int hardFactoryReset();
145 
146  /**
147  * Returns the currently installed firmware version.
148  *
149  * @return %Firmware version
150  */
151  string getVersion();
152 
153  /**
154  * Fetch the firmware update history.
155  *
156  * @return Vector of firmware update history entries
157  */
158  vector<UpdateHistoryEntry> getUpdateHistory();
159 
160  /**
161  * Get the current firmware image upload/download status.
162  *
163  * @return Image status structure.
164  */
165  ImageStatus getImageStatus();
166 
167  /**
168  * Discard the currently uploaded firmware image, cancel the update.
169  */
170  void discardImage();
171 
172  /**
173  * Return information about a currently uploaded firmware image.
174  *
175  * @param info %Firmware image information
176  *
177  * @return \c true if a firmware image is uploaded, \c false otherwise.
178  */
179  boolean getImageInfo(out ImageInfo_1_0_1 info);
180 
181  /**
182  * Launch the firmware update process. The device will stop handling
183  * RPC requests shortly after this method has been successfully called.
184  * The client should poll the fwupdate_progress.cgi page to monitor the
185  * update progress.
186  *
187  * @param flags List of firmware update flags; may be empty
188  */
189  void startUpdate(in vector<UpdateFlags> flags);
190 
191  };
192 
193 }
Allow untrusted firmwares.
Definition: Firmware.idl:94
string platform
Platform name.
Definition: Firmware.idl:71
string version
Firmware image version
Definition: Firmware.idl:66
string imageMD5
MD5 hash of update image.
Definition: Firmware.idl:33
string error_message
Error message; empty if there was no error.
Definition: Firmware.idl:54
string newVersion
Firmware version the device is being upgraded to.
Definition: Firmware.idl:108
Firmware update history entry TODO: implement CR# 45668 on next interface change add comment field ba...
Definition: Firmware.idl:29
string signed_by
Signature issuer.
Definition: Firmware.idl:79
int size_total
Total size of the image (if available)
Definition: Firmware.idl:56
ImageState state
Image upload/download state.
Definition: Firmware.idl:53
valueobject FirmwareUpdateFailedEvent
Event: Firmware update failed.
Definition: Firmware.idl:116
UpdateFlags
Flags for startUpdate() method.
Definition: Firmware.idl:91
string oem
OEM name.
Definition: Firmware.idl:72
string imageVersion
Firmware version of update image.
Definition: Firmware.idl:32
Image upload/download status.
Definition: Firmware.idl:52
boolean model_list_present
true if the image includes a supported models list
Definition: Firmware.idl:84
int size_done
Progress of the running upload or download (if available)
Definition: Firmware.idl:57
valueobject FirmwareValidationFailedEvent
Event: Firmware validation failed.
Definition: Firmware.idl:103
The update was not completed.
Definition: Firmware.idl:20
The device is downloading a firmware image from a URL.
Definition: Firmware.idl:44
UpdateHistoryStatus status
Update status.
Definition: Firmware.idl:34
boolean signature_present
true if the image is signed
Definition: Firmware.idl:78
Firmware Management
Definition: Firmware.idl:12
Basic IDL definitions.
Definition: Event.idl:10
There was a problem downloading the image from a URL.
Definition: Firmware.idl:45
valueobject SystemStartupEvent
Event: System startup finished.
Definition: Firmware.idl:98
Ignore version, product and OEM constraints.
Definition: Firmware.idl:92
boolean signature_good
true if the signature is valid
Definition: Firmware.idl:80
string certified_by
Key certificate issuer.
Definition: Firmware.idl:81
valueobject FirmwareUpdateEvent
Event: Firmware update base event.
Definition: Firmware.idl:107
string product
Product name.
Definition: Firmware.idl:70
string min_downgrade_version
Minimum image version for running firmware.
Definition: Firmware.idl:68
UpdateHistoryStatus
Firmware update history status
Definition: Firmware.idl:17
The update was successfully completed.
Definition: Firmware.idl:18
string min_required_version
Minimum running firmware version for image.
Definition: Firmware.idl:67
Ignore hardware constraints.
Definition: Firmware.idl:93
boolean compatible
true if the image is compatible with this device
Definition: Firmware.idl:76
Firmware management methods
Definition: Firmware.idl:121
boolean certificate_good
true if the key certificate is valid
Definition: Firmware.idl:82
valueobject FirmwareUpdateCompletedEvent
Event: Firmware updated successfully.
Definition: Firmware.idl:114
No firmware image has been uploaded/downloaded.
Definition: Firmware.idl:41
boolean valid
The file is a valid firmware image.
Definition: Firmware.idl:64
string hwid_whitelist
Hardware ID whitelist.
Definition: Firmware.idl:73
valueobject SystemShutdownEvent
Event: System shutdown started.
Definition: Firmware.idl:100
time time_started
Timestamp of the last state change (if available)
Definition: Firmware.idl:55
boolean model_supported
true if the model is found on the support list
Definition: Firmware.idl:85
string hwid_blacklist
Hardware ID blacklist.
Definition: Firmware.idl:74
string oldVersion
Previous firmware version.
Definition: Firmware.idl:31
ImageState
Image upload/download state.
Definition: Firmware.idl:40
There was a problem uploading an image to the device.
Definition: Firmware.idl:43
The update failed.
Definition: Firmware.idl:19
A firmware image is currently being uploaded.
Definition: Firmware.idl:42
A complete image has been successfully uploaded/downloaded.
Definition: Firmware.idl:46
time timestamp
Timestamp when the update was started.
Definition: Firmware.idl:30
Firmware image information
Definition: Firmware.idl:63