View Javadoc
1   package org.metricshub.ipmi.core.coding.payload;
2   
3   /*-
4    * ╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲
5    * IPMI Java Client
6    * ჻჻჻჻჻჻
7    * Copyright 2023 Verax Systems, MetricsHub
8    * ჻჻჻჻჻჻
9    * This program is free software: you can redistribute it and/or modify
10   * it under the terms of the GNU Lesser General Public License as
11   * published by the Free Software Foundation, either version 3 of the
12   * License, or (at your option) any later version.
13   *
14   * This program is distributed in the hope that it will be useful,
15   * but WITHOUT ANY WARRANTY; without even the implied warranty of
16   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17   * GNU General Lesser Public License for more details.
18   *
19   * You should have received a copy of the GNU General Lesser Public
20   * License along with this program.  If not, see
21   * <http://www.gnu.org/licenses/lgpl-3.0.html>.
22   * ╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱
23   */
24  public enum CompletionCode {
25  	/**
26  	 * Command completed normally.
27  	 */
28  	Ok(CompletionCode.OK),
29  	/**
30  	 * Insufficient resources to create a session.
31  	 */
32  	InsufficientResources(CompletionCode.INSUFFICIENTRESOURCES),
33  	/**
34  	 * Unauthorized role or privilege level requested.
35  	 */
36  	UnauthorizedRole(CompletionCode.UNAUTHORIZEDROLE),
37  	/**
38  	 * Insufficient resources to create a session at the requested role.
39  	 */
40  	InsufficientResourcesForRole(CompletionCode.INSUFFICIENTRESOURCESFORROLE),
41  	/**
42  	 * Invalid name length.
43  	 */
44  	InvalidNameLength(CompletionCode.INVALIDNAMELENGTH),
45  	/**
46  	 * FRU device busy. The requested cannot be completed because the implementation of the logical FRU device is in a
47  	 * state where the FRU information is temporarily unavailable. This could be due to a condition such as a los s of
48  	 * arbitration if the FRU is implemented as a device on a shared bus.
49  	 */
50  	Frudevicebusy(CompletionCode.FRUDEVICEBUSY),
51  	/**
52  	 * Unauthorized name.
53  	 */
54  	UnauthorizedName(CompletionCode.UNAUTHORIZEDNAME),
55  	/**
56  	 * Invalid Session ID in request.
57  	 */
58  	InvalidSessionId(CompletionCode.INVALIDSESSIONID),
59  	/**
60  	 * Invalid Session Handle in request.
61  	 */
62  	InvalidSessionHandle(CompletionCode.INVALIDSESSIONHANDLE),
63  	/**
64  	 * GUID that BMC submitted in RAKP Message 2 was not accepted by remote console.
65  	 */
66  	UnauthorizedGuid(CompletionCode.UNAUTHORIZEDGUID),
67  	/**
68  	 * Invalid integrity check value.
69  	 */
70  	InvalidIntegrityCheckValue(CompletionCode.INVALIDINTEGRITYCHECKVALUE),
71  	/**
72  	 * Invalid confidentiality algorithm.
73  	 */
74  	InvalidConfidentialityAlgorithm(CompletionCode.INVALIDCONFIDENTIALITYALGORITHM),
75  	/**
76  	 * No Cipher Suite match with proposed security algorithms.
77  	 */
78  	NoMatchingCipherSuite(CompletionCode.NOMATCHINGCIPHERSUITE),
79  	/**
80  	 * Illegal or unrecognized parameter.
81  	 */
82  	IllegalOrUnrecognizedParameter(CompletionCode.ILLEGALORUNRECOGNIZEDPARAMETER),
83  	/**
84  	 * Command could not be processed because command processing resources are temporarily unavailable.
85  	 */
86  	NodeBusy(CompletionCode.NODEBUSY),
87  	/**
88  	 * Used to indicate an unrecognized or unsupported command.
89  	 */
90  	InvalidCommand(CompletionCode.INVALIDCOMMAND),
91  	/**
92  	 * Command invalid for given LUN.
93  	 */
94  	InvalidLun(CompletionCode.INVALIDLUN),
95  	/**
96  	 * Timeout while processing command. Response unavailable.
97  	 */
98  	Timeout(CompletionCode.TIMEOUT),
99  	/**
100 	 * Out of space. Command could not be completed because of a lack of storage space required to execute the given
101 	 * command operation.
102 	 */
103 	OutOfSpace(CompletionCode.OUTOFSPACE),
104 	/**
105 	 * Reservation Canceled or Invalid Reservation ID.
106 	 */
107 	ReservationCanceled(CompletionCode.RESERVATIONCANCELED),
108 	/**
109 	 * Request data truncated.
110 	 */
111 	RequestTruncated(CompletionCode.REQUESTTRUNCATED),
112 	/**
113 	 * Request data length invalid.
114 	 */
115 	InvalidRequestLength(CompletionCode.INVALIDREQUESTLENGTH),
116 	/**
117 	 * Invalid session ID.
118 	 */
119 	InvalidId(CompletionCode.INVALIDID),
120 	/**
121 	 * Request data field length limit exceeded.
122 	 */
123 	LengthLimitExceeded(CompletionCode.LENGTHLIMITEXCEEDED),
124 	/**
125 	 * Parameter out of range. One or more parameters in the data field of the Request are out of range. This is different
126 	 * from {@link #InvalidData} (CCh) code in that it indicates that the erroneous field(s) has a contiguous range of
127 	 * possible values.
128 	 */
129 	ParameterOutOfRange(CompletionCode.PARAMETEROUTOFRANGE),
130 	/**
131 	 * Cannot return number of requested data bytes.
132 	 */
133 	CannotRespond(CompletionCode.CANNOTRESPOND),
134 	/**
135 	 * Requested Sensor, data, or record not present.
136 	 */
137 	DataNotPresent(CompletionCode.DATANOTPRESENT),
138 	/**
139 	 * Invalid data field in Request.
140 	 */
141 	InvalidData(CompletionCode.INVALIDDATA),
142 	/**
143 	 * Command illegal for specified sensor or record type.
144 	 */
145 	IllegalCommand(CompletionCode.ILLEGALCOMMAND),
146 	/**
147 	 * Command response could not be provided.
148 	 */
149 	ResponseUnavailable(CompletionCode.RESPONSEUNAVAILABLE),
150 	/**
151 	 * Cannot execute duplicated request. This completion code is for devices which cannot return the response that was
152 	 * returned for the original instance of the request. Such devices should provide separate commands that allow the
153 	 * completion status of the original request to be determined. An Event Receiver does not use this completion code,
154 	 * but returns the 00h completion code in the response to (valid) duplicated requests.
155 	 */
156 	DuplicatedRequest(CompletionCode.DUPLICATEDREQUEST),
157 	/**
158 	 * Command response could not be provided. SDR Repository in update mode.
159 	 */
160 	SdrUpdating(CompletionCode.SDRUPDATING),
161 	/**
162 	 * Command response could not be provided. Device in firmware update mode.
163 	 */
164 	FirmwareUpdating(CompletionCode.FIRMWAREUPDATING),
165 	/**
166 	 * Command response could not be provided. BMC initialization or initialization agent in progress.
167 	 */
168 	InitializationInProgress(CompletionCode.INITIALIZATIONINPROGRESS),
169 	/**
170 	 * Destination unavailable. Cannot deliver request to selected destination. E.g. this code can be returned if a
171 	 * request message is targeted to SMS, but receive message queue reception is disabled for the particular channel.
172 	 */
173 	DestinationUnavailable(CompletionCode.DESTINATIONUNAVAILABLE),
174 	/**
175 	 * Cannot execute command due to insufficient privilege level or other security - based restriction (e.g. disabled for
176 	 * 'firmware firewall').
177 	 */
178 	InsufficientPrivilege(CompletionCode.INSUFFICIENTPRIVILEGE),
179 	/**
180 	 * Cannot execute command. Command, or request parameter(s), not supported in present state.
181 	 */
182 	CommandNotSupported(CompletionCode.COMMANDNOTSUPPORTED),
183 	/**
184 	 * Cannot execute command. Parameter is illegal because command sub-function has been disabled or is unavailable (e.g.
185 	 * disabled for 'firmware firewall').
186 	 */
187 	IllegalParameter(CompletionCode.ILLEGALPARAMETER),
188 	/**
189 	 * Unspecified error.
190 	 */
191 	UnspecifiedError(CompletionCode.UNSPECIFIEDERROR),
192 	/**
193 	 * Invalid payload type.
194 	 */
195 	InvalidPayloadType(CompletionCode.INVALIDPAYLOADTYPE),
196 	/**
197 	 * Invalid authentication algorithm.
198 	 */
199 	InvalidAuthenticationAlgorithm(CompletionCode.INVALIDAUTHENTICATIONALGORITHM),
200 	/**
201 	 * Invalid integrity algorithm.
202 	 */
203 	InvalidIntegrityAlgorithm(CompletionCode.INVALIDINTEGRITYALGORITHM),
204 	/**
205 	 * No matching authentication payload.
206 	 */
207 	NoMatchingAuthenticationPayload(CompletionCode.NOMATCHINGAUTHENTICATIONPAYLOAD),
208 	/**
209 	 * No matching integrity payload.
210 	 */
211 	NoMatchingIntegrityPayload(CompletionCode.NOMATCHINGINTEGRITYPAYLOAD),
212 	/**
213 	 * Inactive session ID.
214 	 */
215 	InactiveSessionID(CompletionCode.INACTIVESESSIONID),
216 	/**
217 	 * Invalid role.
218 	 */
219 	InvalidRole(CompletionCode.INVALIDROLE),
220 	/**
221 	 * A code this enumeration does not list: OEM, command-specific or reserved. The raw value is available on the
222 	 * {@link org.metricshub.ipmi.core.coding.payload.lan.IPMIException}.
223 	 */
224 	Unknown(CompletionCode.UNKNOWN),;
225 
226 	/**
227 	 * The misspelled name of {@link #InsufficientPrivilege}, kept so that code built against 2.0 keeps working: it is
228 	 * the same constant, so {@link #values()}, {@link #name()} and {@link #valueOf(String)} only know the new spelling.
229 	 *
230 	 * @deprecated use {@link #InsufficientPrivilege}; this alias will be removed in 3.0.
231 	 */
232 	// CHECKSTYLE.OFF: ConstantName
233 	@Deprecated
234 	public static final CompletionCode InsufficentPrivilege = InsufficientPrivilege;
235 	// CHECKSTYLE.ON: ConstantName
236 
237 	private static final int OK = 0;
238 	private static final int INSUFFICIENTRESOURCES = 1;
239 	private static final int UNAUTHORIZEDROLE = 10;
240 	private static final int INSUFFICIENTRESOURCESFORROLE = 11;
241 	private static final int INVALIDNAMELENGTH = 12;
242 	private static final int FRUDEVICEBUSY = 129;
243 	private static final int UNAUTHORIZEDNAME = 13;
244 	private static final int INVALIDSESSIONID = 135;
245 	private static final int INVALIDSESSIONHANDLE = 136;
246 	private static final int UNAUTHORIZEDGUID = 14;
247 	private static final int INVALIDINTEGRITYCHECKVALUE = 15;
248 	private static final int INVALIDCONFIDENTIALITYALGORITHM = 16;
249 	private static final int NOMATCHINGCIPHERSUITE = 17;
250 	private static final int ILLEGALORUNRECOGNIZEDPARAMETER = 18;
251 	private static final int NODEBUSY = 192;
252 	private static final int INVALIDCOMMAND = 193;
253 	private static final int INVALIDLUN = 194;
254 	private static final int TIMEOUT = 195;
255 	private static final int OUTOFSPACE = 196;
256 	private static final int RESERVATIONCANCELED = 197;
257 	private static final int REQUESTTRUNCATED = 198;
258 	private static final int INVALIDREQUESTLENGTH = 199;
259 	private static final int INVALIDID = 2;
260 	private static final int LENGTHLIMITEXCEEDED = 200;
261 	private static final int PARAMETEROUTOFRANGE = 201;
262 	private static final int CANNOTRESPOND = 202;
263 	private static final int DATANOTPRESENT = 203;
264 	private static final int INVALIDDATA = 204;
265 	private static final int ILLEGALCOMMAND = 205;
266 	private static final int RESPONSEUNAVAILABLE = 206;
267 	private static final int DUPLICATEDREQUEST = 207;
268 	private static final int SDRUPDATING = 208;
269 	private static final int FIRMWAREUPDATING = 209;
270 	private static final int INITIALIZATIONINPROGRESS = 210;
271 	private static final int DESTINATIONUNAVAILABLE = 211;
272 	private static final int INSUFFICIENTPRIVILEGE = 212;
273 	private static final int COMMANDNOTSUPPORTED = 213;
274 	private static final int ILLEGALPARAMETER = 214;
275 	private static final int UNSPECIFIEDERROR = 255;
276 	private static final int UNKNOWN = -1;
277 	private static final int INVALIDPAYLOADTYPE = 3;
278 	private static final int INVALIDAUTHENTICATIONALGORITHM = 4;
279 	private static final int INVALIDINTEGRITYALGORITHM = 5;
280 	private static final int NOMATCHINGAUTHENTICATIONPAYLOAD = 6;
281 	private static final int NOMATCHINGINTEGRITYPAYLOAD = 7;
282 	private static final int INACTIVESESSIONID = 8;
283 	private static final int INVALIDROLE = 9;
284 
285 	private int code;
286 
287 	CompletionCode(int code) {
288 		this.code = code;
289 	}
290 
291 	public int getCode() {
292 		return code;
293 	}
294 
295 	/**
296 	 * Tells whether the BMC may answer the same request successfully a little later.
297 	 *
298 	 * @return true for the completion codes that only report a passing condition of the BMC (busy, out of resources,
299 	 *         initializing, internal timeout), false for every other code
300 	 */
301 	public boolean isTransient() {
302 		return this == InitializationInProgress || this == InsufficientResources || this == NodeBusy || this == Timeout;
303 	}
304 
305 	public static CompletionCode parseInt(int value) {
306 		switch (value) {
307 		case OK:
308 			return Ok;
309 		case INSUFFICIENTRESOURCES:
310 			return InsufficientResources;
311 		case UNAUTHORIZEDROLE:
312 			return UnauthorizedRole;
313 		case INSUFFICIENTRESOURCESFORROLE:
314 			return InsufficientResourcesForRole;
315 		case INVALIDNAMELENGTH:
316 			return InvalidNameLength;
317 		case FRUDEVICEBUSY:
318 			return Frudevicebusy;
319 		case UNAUTHORIZEDNAME:
320 			return UnauthorizedName;
321 		case INVALIDSESSIONID:
322 			return InvalidSessionId;
323 		case INVALIDSESSIONHANDLE:
324 			return InvalidSessionHandle;
325 		case UNAUTHORIZEDGUID:
326 			return UnauthorizedGuid;
327 		case INVALIDINTEGRITYCHECKVALUE:
328 			return InvalidIntegrityCheckValue;
329 		case INVALIDCONFIDENTIALITYALGORITHM:
330 			return InvalidConfidentialityAlgorithm;
331 		case NOMATCHINGCIPHERSUITE:
332 			return NoMatchingCipherSuite;
333 		case ILLEGALORUNRECOGNIZEDPARAMETER:
334 			return IllegalOrUnrecognizedParameter;
335 		case NODEBUSY:
336 			return NodeBusy;
337 		case INVALIDCOMMAND:
338 			return InvalidCommand;
339 		case INVALIDLUN:
340 			return InvalidLun;
341 		case TIMEOUT:
342 			return Timeout;
343 		case OUTOFSPACE:
344 			return OutOfSpace;
345 		case RESERVATIONCANCELED:
346 			return ReservationCanceled;
347 		case REQUESTTRUNCATED:
348 			return RequestTruncated;
349 		case INVALIDREQUESTLENGTH:
350 			return InvalidRequestLength;
351 		case INVALIDID:
352 			return InvalidId;
353 		case LENGTHLIMITEXCEEDED:
354 			return LengthLimitExceeded;
355 		case PARAMETEROUTOFRANGE:
356 			return ParameterOutOfRange;
357 		case CANNOTRESPOND:
358 			return CannotRespond;
359 		case DATANOTPRESENT:
360 			return DataNotPresent;
361 		case INVALIDDATA:
362 			return InvalidData;
363 		case ILLEGALCOMMAND:
364 			return IllegalCommand;
365 		case RESPONSEUNAVAILABLE:
366 			return ResponseUnavailable;
367 		case DUPLICATEDREQUEST:
368 			return DuplicatedRequest;
369 		case SDRUPDATING:
370 			return SdrUpdating;
371 		case FIRMWAREUPDATING:
372 			return FirmwareUpdating;
373 		case INITIALIZATIONINPROGRESS:
374 			return InitializationInProgress;
375 		case DESTINATIONUNAVAILABLE:
376 			return DestinationUnavailable;
377 		case INSUFFICIENTPRIVILEGE:
378 			return InsufficientPrivilege;
379 		case COMMANDNOTSUPPORTED:
380 			return CommandNotSupported;
381 		case ILLEGALPARAMETER:
382 			return IllegalParameter;
383 		case UNSPECIFIEDERROR:
384 			return UnspecifiedError;
385 		case INVALIDPAYLOADTYPE:
386 			return InvalidPayloadType;
387 		case INVALIDAUTHENTICATIONALGORITHM:
388 			return InvalidAuthenticationAlgorithm;
389 		case INVALIDINTEGRITYALGORITHM:
390 			return InvalidIntegrityAlgorithm;
391 		case NOMATCHINGAUTHENTICATIONPAYLOAD:
392 			return NoMatchingAuthenticationPayload;
393 		case NOMATCHINGINTEGRITYPAYLOAD:
394 			return NoMatchingIntegrityPayload;
395 		case INACTIVESESSIONID:
396 			return InactiveSessionID;
397 		case INVALIDROLE:
398 			return InvalidRole;
399 		default:
400 			// IPMI 2.0 Table 5-2 lets every command use OEM (01h-7Eh) and command-specific (80h-BEh) codes, and
401 			// reserves the rest: a code this table does not list must not abort the decoding of the response
402 			return Unknown;
403 		}
404 	}
405 
406 	public String getMessage() {
407 		switch (code) {
408 		case OK:
409 			return "Command completed normally.";
410 		case INSUFFICIENTRESOURCES:
411 			return "Insufficient resources to create a session.";
412 		case UNAUTHORIZEDROLE:
413 			return "Unauthorized role or privilege level requested.";
414 		case INSUFFICIENTRESOURCESFORROLE:
415 			return "Insufficient resources to create a session at the requested role.";
416 		case INVALIDNAMELENGTH:
417 			return "Invalid name length.";
418 		case FRUDEVICEBUSY:
419 			return "FRU device busy. The requested cannot be completed because the implementation of the logical FRU device is in a state where the FRU information is temporarily unavailable. This could be due to a condition such as a los s of arbitration if the FRU is implemented as a device on a shared bus.";
420 		case UNAUTHORIZEDNAME:
421 			return "Unauthorized name.";
422 		case INVALIDSESSIONID:
423 			return "Invalid Session ID in request.";
424 		case INVALIDSESSIONHANDLE:
425 			return "Invalid Session Handle in request.";
426 		case UNAUTHORIZEDGUID:
427 			return "GUID that BMC submitted in RAKP Message 2 was not accepted by remote console.";
428 		case INVALIDINTEGRITYCHECKVALUE:
429 			return "Invalid integrity check value.";
430 		case INVALIDCONFIDENTIALITYALGORITHM:
431 			return "Invalid confidentiality algorithm.";
432 		case NOMATCHINGCIPHERSUITE:
433 			return "No Cipher Suite match with proposed security algorithms.";
434 		case ILLEGALORUNRECOGNIZEDPARAMETER:
435 			return "Illegal or unrecognized parameter.";
436 		case NODEBUSY:
437 			return "Command could not be processed because command processing resources are temporarily unavailable.";
438 		case INVALIDCOMMAND:
439 			return "Used to indicate an unrecognized or unsupported command.";
440 		case INVALIDLUN:
441 			return "Command invalid for given LUN.";
442 		case TIMEOUT:
443 			return "Timeout while processing command. Response unavailable.";
444 		case OUTOFSPACE:
445 			return "Out of space. Command could not be completed because of a lack of storage space required to execute the given command operation.";
446 		case RESERVATIONCANCELED:
447 			return "Reservation Canceled or Invalid Reservation ID.";
448 		case REQUESTTRUNCATED:
449 			return "Request data truncated.";
450 		case INVALIDREQUESTLENGTH:
451 			return "Request data length invalid.";
452 		case INVALIDID:
453 			return "Invalid session ID.";
454 		case LENGTHLIMITEXCEEDED:
455 			return "Request data field length limit exceeded.";
456 		case PARAMETEROUTOFRANGE:
457 			return "Parameter out of range. One or more parameters in the data field of the Request are out of range. This is different from the Invalid data field (CCh) code in that it indicates that the erroneous field(s) has a contiguous range of possible values.";
458 		case CANNOTRESPOND:
459 			return "Cannot return number of requested data bytes.";
460 		case DATANOTPRESENT:
461 			return "Requested Sensor, data, or record not present.";
462 		case INVALIDDATA:
463 			return "Invalid data field in Request.";
464 		case ILLEGALCOMMAND:
465 			return "Command illegal for specified sensor or record type.";
466 		case RESPONSEUNAVAILABLE:
467 			return "Command response could not be provided.";
468 		case DUPLICATEDREQUEST:
469 			return "Cannot execute duplicated request. This completion code is for devices which cannot return the response that was returned for the original instance of the request. Such devices should provide separate commands that allow the completion status of the original request to be determined. An Event Receiver does not use this completion code, but returns the 00h completion code in the response to (valid) duplicated requests.";
470 		case SDRUPDATING:
471 			return "Command response could not be provided. SDR Repository in update mode.";
472 		case FIRMWAREUPDATING:
473 			return "Command response could not be provided. Device in firmware update mode.";
474 		case INITIALIZATIONINPROGRESS:
475 			return "Command response could not be provided. BMC initialization or initialization agent in progress.";
476 		case DESTINATIONUNAVAILABLE:
477 			return "Destination unavailable. Cannot deliver request to selected destination. E.g. this code can be returned if a request message is targeted to SMS, but receive message queue reception is disabled for the particular channel.";
478 		case INSUFFICIENTPRIVILEGE:
479 			return "Cannot execute command due to insufficient privilege level or other security - based restriction (e.g. disabled for 'firmware firewall').";
480 		case COMMANDNOTSUPPORTED:
481 			return "Cannot execute command. Command, or request parameter(s), not supported in present state.";
482 		case ILLEGALPARAMETER:
483 			return "Cannot execute command. Parameter is illegal because command sub-function has been disabled or is unavailable (e.g. disabled for 'firmware firewall').";
484 		case UNSPECIFIEDERROR:
485 			return "Unspecified error.";
486 		case INVALIDPAYLOADTYPE:
487 			return "Invalid payload type.";
488 		case INVALIDAUTHENTICATIONALGORITHM:
489 			return "Invalid authentication algorithm.";
490 		case INVALIDINTEGRITYALGORITHM:
491 			return "Invalid integrity algorithm.";
492 		case NOMATCHINGAUTHENTICATIONPAYLOAD:
493 			return "No matching authentication payload.";
494 		case NOMATCHINGINTEGRITYPAYLOAD:
495 			return "No matching integrity payload.";
496 		case INACTIVESESSIONID:
497 			return "Inactive session ID.";
498 		case INVALIDROLE:
499 			return "Invalid role.";
500 		case UNKNOWN:
501 			return "Unknown completion code.";
502 		default:
503 			throw new IllegalArgumentException("Invalid value: " + code);
504 		}
505 	}
506 }