1 // SPDX-License-Identifier: GPL-2.0+
5 * State machine for handling IPMI KCS interfaces.
7 * Author: MontaVista Software, Inc.
8 * Corey Minyard <minyard@mvista.com>
11 * Copyright 2002 MontaVista Software Inc.
15 * This state machine is taken from the state machine in the IPMI spec,
16 * pretty much verbatim. If you have questions about the states, see
20 #define DEBUG /* So dev_dbg() is always available. */
22 #include <linux/kernel.h> /* For printk. */
23 #include <linux/module.h>
24 #include <linux/moduleparam.h>
25 #include <linux/string.h>
26 #include <linux/jiffies.h>
27 #include <linux/ipmi_msgdefs.h> /* for completion codes */
28 #include "ipmi_si_sm.h"
30 /* kcs_debug is a bit-field
31 * KCS_DEBUG_ENABLE - turned on for now
32 * KCS_DEBUG_MSG - commands and their responses
33 * KCS_DEBUG_STATES - state machine
35 #define KCS_DEBUG_STATES 4
36 #define KCS_DEBUG_MSG 2
37 #define KCS_DEBUG_ENABLE 1
40 module_param(kcs_debug, int, 0644);
41 MODULE_PARM_DESC(kcs_debug, "debug bitmask, 1=enable, 2=messages, 4=states");
43 /* The states the KCS driver may be in. */
45 /* The KCS interface is currently doing nothing. */
49 * We are starting an operation. The data is in the output
50 * buffer, but nothing has been done to the interface yet. This
51 * was added to the state machine in the spec to wait for the
56 /* We have written a write cmd to the interface. */
59 /* We are writing bytes to the interface. */
63 * We have written the write end cmd to the interface, and
64 * still need to write the last byte.
68 /* We are waiting to read data from the interface. */
72 * State to transition to the error handler, this was added to
73 * the state machine in the spec to be sure IBF was there.
78 * First stage error handler, wait for the interface to
84 * The abort cmd has been written, wait for the interface to
90 * We wrote some data to the interface, wait for it to switch
95 /* The hardware failed to follow the state machine. */
99 #define MAX_KCS_READ_SIZE IPMI_MAX_MSG_LENGTH
100 #define MAX_KCS_WRITE_SIZE IPMI_MAX_MSG_LENGTH
102 /* Timeouts in microseconds. */
103 #define IBF_RETRY_TIMEOUT (5*USEC_PER_SEC)
104 #define OBF_RETRY_TIMEOUT (5*USEC_PER_SEC)
105 #define MAX_ERROR_RETRIES 10
106 #define ERROR0_OBF_WAIT_JIFFIES (2*HZ)
109 enum kcs_states state;
111 unsigned char write_data[MAX_KCS_WRITE_SIZE];
114 int orig_write_count;
115 unsigned char read_data[MAX_KCS_READ_SIZE];
119 unsigned int error_retries;
122 unsigned long error0_timeout;
125 static unsigned int init_kcs_data(struct si_sm_data *kcs,
128 kcs->state = KCS_IDLE;
131 kcs->write_count = 0;
132 kcs->orig_write_count = 0;
134 kcs->error_retries = 0;
136 kcs->ibf_timeout = IBF_RETRY_TIMEOUT;
137 kcs->obf_timeout = OBF_RETRY_TIMEOUT;
139 /* Reserve 2 I/O bytes. */
143 static inline unsigned char read_status(struct si_sm_data *kcs)
145 return kcs->io->inputb(kcs->io, 1);
148 static inline unsigned char read_data(struct si_sm_data *kcs)
150 return kcs->io->inputb(kcs->io, 0);
153 static inline void write_cmd(struct si_sm_data *kcs, unsigned char data)
155 kcs->io->outputb(kcs->io, 1, data);
158 static inline void write_data(struct si_sm_data *kcs, unsigned char data)
160 kcs->io->outputb(kcs->io, 0, data);
164 #define KCS_GET_STATUS_ABORT 0x60
165 #define KCS_WRITE_START 0x61
166 #define KCS_WRITE_END 0x62
167 #define KCS_READ_BYTE 0x68
170 #define GET_STATUS_STATE(status) (((status) >> 6) & 0x03)
171 #define KCS_IDLE_STATE 0
172 #define KCS_READ_STATE 1
173 #define KCS_WRITE_STATE 2
174 #define KCS_ERROR_STATE 3
175 #define GET_STATUS_ATN(status) ((status) & 0x04)
176 #define GET_STATUS_IBF(status) ((status) & 0x02)
177 #define GET_STATUS_OBF(status) ((status) & 0x01)
180 static inline void write_next_byte(struct si_sm_data *kcs)
182 write_data(kcs, kcs->write_data[kcs->write_pos]);
184 (kcs->write_count)--;
187 static inline void start_error_recovery(struct si_sm_data *kcs, char *reason)
189 (kcs->error_retries)++;
190 if (kcs->error_retries > MAX_ERROR_RETRIES) {
191 if (kcs_debug & KCS_DEBUG_ENABLE)
192 dev_dbg(kcs->io->dev, "ipmi_kcs_sm: kcs hosed: %s\n",
194 kcs->state = KCS_HOSED;
196 kcs->error0_timeout = jiffies + ERROR0_OBF_WAIT_JIFFIES;
197 kcs->state = KCS_ERROR0;
201 static inline void read_next_byte(struct si_sm_data *kcs)
203 if (kcs->read_pos >= MAX_KCS_READ_SIZE) {
204 /* Throw the data away and mark it truncated. */
208 kcs->read_data[kcs->read_pos] = read_data(kcs);
211 write_data(kcs, KCS_READ_BYTE);
214 static inline int check_ibf(struct si_sm_data *kcs, unsigned char status,
217 if (GET_STATUS_IBF(status)) {
218 kcs->ibf_timeout -= time;
219 if (kcs->ibf_timeout < 0) {
220 start_error_recovery(kcs, "IBF not ready in time");
221 kcs->ibf_timeout = IBF_RETRY_TIMEOUT;
226 kcs->ibf_timeout = IBF_RETRY_TIMEOUT;
230 static inline int check_obf(struct si_sm_data *kcs, unsigned char status,
233 if (!GET_STATUS_OBF(status)) {
234 kcs->obf_timeout -= time;
235 if (kcs->obf_timeout < 0) {
236 kcs->obf_timeout = OBF_RETRY_TIMEOUT;
237 start_error_recovery(kcs, "OBF not ready in time");
242 kcs->obf_timeout = OBF_RETRY_TIMEOUT;
246 static void clear_obf(struct si_sm_data *kcs, unsigned char status)
248 if (GET_STATUS_OBF(status))
252 static void restart_kcs_transaction(struct si_sm_data *kcs)
254 kcs->write_count = kcs->orig_write_count;
257 kcs->state = KCS_WAIT_WRITE_START;
258 kcs->ibf_timeout = IBF_RETRY_TIMEOUT;
259 kcs->obf_timeout = OBF_RETRY_TIMEOUT;
260 write_cmd(kcs, KCS_WRITE_START);
263 static int start_kcs_transaction(struct si_sm_data *kcs, unsigned char *data,
269 return IPMI_REQ_LEN_INVALID_ERR;
270 if (size > MAX_KCS_WRITE_SIZE)
271 return IPMI_REQ_LEN_EXCEEDED_ERR;
273 if ((kcs->state != KCS_IDLE) && (kcs->state != KCS_HOSED)) {
274 dev_warn(kcs->io->dev, "KCS in invalid state %d\n", kcs->state);
275 return IPMI_NOT_IN_MY_STATE_ERR;
278 if (kcs_debug & KCS_DEBUG_MSG) {
279 dev_dbg(kcs->io->dev, "%s -", __func__);
280 for (i = 0; i < size; i++)
281 pr_cont(" %02x", data[i]);
284 kcs->error_retries = 0;
285 memcpy(kcs->write_data, data, size);
286 kcs->write_count = size;
287 kcs->orig_write_count = size;
290 kcs->state = KCS_START_OP;
291 kcs->ibf_timeout = IBF_RETRY_TIMEOUT;
292 kcs->obf_timeout = OBF_RETRY_TIMEOUT;
296 static int get_kcs_result(struct si_sm_data *kcs, unsigned char *data,
299 if (length < kcs->read_pos) {
300 kcs->read_pos = length;
304 memcpy(data, kcs->read_data, kcs->read_pos);
306 if ((length >= 3) && (kcs->read_pos < 3)) {
307 /* Guarantee that we return at least 3 bytes, with an
308 error in the third byte if it is too short. */
309 data[2] = IPMI_ERR_UNSPECIFIED;
312 if (kcs->truncated) {
314 * Report a truncated error. We might overwrite
315 * another error, but that's too bad, the user needs
316 * to know it was truncated.
318 data[2] = IPMI_ERR_MSG_TRUNCATED;
322 return kcs->read_pos;
326 * This implements the state machine defined in the IPMI manual, see
327 * that for details on how this works. Divide that flowchart into
328 * sections delimited by "Wait for IBF" and this will become clear.
330 static enum si_sm_result kcs_event(struct si_sm_data *kcs, long time)
332 unsigned char status;
335 status = read_status(kcs);
337 if (kcs_debug & KCS_DEBUG_STATES)
338 dev_dbg(kcs->io->dev,
339 "KCS: State = %d, %x\n", kcs->state, status);
341 /* All states wait for ibf, so just do it here. */
342 if (!check_ibf(kcs, status, time))
343 return SI_SM_CALL_WITH_DELAY;
345 /* Just about everything looks at the KCS state, so grab that, too. */
346 state = GET_STATUS_STATE(status);
348 switch (kcs->state) {
350 /* If there's and interrupt source, turn it off. */
351 clear_obf(kcs, status);
353 if (GET_STATUS_ATN(status))
359 if (state != KCS_IDLE_STATE) {
360 start_error_recovery(kcs,
361 "State machine not idle at start");
365 clear_obf(kcs, status);
366 write_cmd(kcs, KCS_WRITE_START);
367 kcs->state = KCS_WAIT_WRITE_START;
370 case KCS_WAIT_WRITE_START:
371 if (state != KCS_WRITE_STATE) {
372 start_error_recovery(
374 "Not in write state at write start");
378 if (kcs->write_count == 1) {
379 write_cmd(kcs, KCS_WRITE_END);
380 kcs->state = KCS_WAIT_WRITE_END;
382 write_next_byte(kcs);
383 kcs->state = KCS_WAIT_WRITE;
388 if (state != KCS_WRITE_STATE) {
389 start_error_recovery(kcs,
390 "Not in write state for write");
393 clear_obf(kcs, status);
394 if (kcs->write_count == 1) {
395 write_cmd(kcs, KCS_WRITE_END);
396 kcs->state = KCS_WAIT_WRITE_END;
398 write_next_byte(kcs);
402 case KCS_WAIT_WRITE_END:
403 if (state != KCS_WRITE_STATE) {
404 start_error_recovery(kcs,
409 clear_obf(kcs, status);
410 write_next_byte(kcs);
411 kcs->state = KCS_WAIT_READ;
415 if ((state != KCS_READ_STATE) && (state != KCS_IDLE_STATE)) {
416 start_error_recovery(
418 "Not in read or idle in read state");
422 if (state == KCS_READ_STATE) {
423 if (!check_obf(kcs, status, time))
424 return SI_SM_CALL_WITH_DELAY;
428 * We don't implement this exactly like the state
429 * machine in the spec. Some broken hardware
430 * does not write the final dummy byte to the
431 * read register. Thus obf will never go high
432 * here. We just go straight to idle, and we
433 * handle clearing out obf in idle state if it
434 * happens to come in.
436 clear_obf(kcs, status);
437 kcs->orig_write_count = 0;
438 kcs->state = KCS_IDLE;
439 return SI_SM_TRANSACTION_COMPLETE;
444 clear_obf(kcs, status);
445 status = read_status(kcs);
446 if (GET_STATUS_OBF(status))
447 /* controller isn't responding */
448 if (time_before(jiffies, kcs->error0_timeout))
449 return SI_SM_CALL_WITH_TICK_DELAY;
450 write_cmd(kcs, KCS_GET_STATUS_ABORT);
451 kcs->state = KCS_ERROR1;
455 clear_obf(kcs, status);
457 kcs->state = KCS_ERROR2;
461 if (state != KCS_READ_STATE) {
462 start_error_recovery(kcs,
463 "Not in read state for error2");
466 if (!check_obf(kcs, status, time))
467 return SI_SM_CALL_WITH_DELAY;
469 clear_obf(kcs, status);
470 write_data(kcs, KCS_READ_BYTE);
471 kcs->state = KCS_ERROR3;
475 if (state != KCS_IDLE_STATE) {
476 start_error_recovery(kcs,
477 "Not in idle state for error3");
481 if (!check_obf(kcs, status, time))
482 return SI_SM_CALL_WITH_DELAY;
484 clear_obf(kcs, status);
485 if (kcs->orig_write_count) {
486 restart_kcs_transaction(kcs);
488 kcs->state = KCS_IDLE;
489 return SI_SM_TRANSACTION_COMPLETE;
497 if (kcs->state == KCS_HOSED) {
498 init_kcs_data(kcs, kcs->io);
502 return SI_SM_CALL_WITHOUT_DELAY;
505 static int kcs_size(void)
507 return sizeof(struct si_sm_data);
510 static int kcs_detect(struct si_sm_data *kcs)
513 * It's impossible for the KCS status register to be all 1's,
514 * (assuming a properly functioning, self-initialized BMC)
515 * but that's what you get from reading a bogus address, so we
518 if (read_status(kcs) == 0xff)
524 static void kcs_cleanup(struct si_sm_data *kcs)
528 const struct si_sm_handlers kcs_smi_handlers = {
529 .init_data = init_kcs_data,
530 .start_transaction = start_kcs_transaction,
531 .get_result = get_kcs_result,
533 .detect = kcs_detect,
534 .cleanup = kcs_cleanup,