6.9.1 ‘Anonymous Login’ Convention
9. Keyboard Controller Style (KCS) Interface
9.15 KCS Flow Diagrams
The following flow diagrams have been updated from corresponding diagrams in the original IPMI v1.0, rev. 1.1 specification. This information applies to the following flow diagrams:
• All system software wait loops should include error timeouts. For simplicity, such timeouts are not shown explicitly in the flow diagrams. A five-second timeout or greater is recommended.
• The phase values represent state information that could be kept across different activations of an interrupt handler, and corresponding entry points. Based on the 'phase' the interrupt handler would branch to the corresponding point when an OBF interrupt occurred. The information may also be useful for error reporting and handling for both polled- and interrupt-driven drivers. Note that other state may need to be kept as well. For example, during the 'wr_data’ phase, the handler may also need to preserve a byte counter in order to track when the last byte of the write was to be sent.
• The symbol of a circle with an arrow and the text ‘OBF’ inside the circle represents the points where the BMC would write a dummy data byte to the output buffer in order to create an OBF interrupt. The label above the circle indicates where an interrupt handler would branch to when the OBF interrupt occurs under in the corresponding phase. An interrupt handler would exit upon completing the step that occurs before where the OBF interrupt symbol points.
Figure 9-6, KCS Interface SMS to BMC Write Transfer Flow Chart
wait for IBF=0 clear OBF
WR_START to CMD phase=wr_start
wait for IBF=0
WRITE_STATE?
Clear OBF phase=wr_data
Yes
data byte to DATA
wait for IBF=0
WRITE_STATE?
Yes
No Error Exit
Clear OBF
Last write byte?
No
WR_END to CMD phase=wr_end_cmd
wait for IBF=0
Yes
Clear OBF
data byte to DATA phase=read WRITE
OBF
OBF
OBF
Yes BMC sets status to
WRITE_STATE immediately after receiving any control code in the command register unless it needs to force an ERROR_STATE. The status is set before reading the control code from the input buffer.
In the unlikely event that an asynchronous interrupt occurs after clearing OBF the interrupt handler may spin waiting for IBF=0.
WRITE_STATE? No Error Exit
The BMC sets state to READ_STATE before reading data byte from data register. This ensures state change to READ_STATE occurs while IBF=1.
wr_start
wr_data
wr_end_cmd
READ No Error_Exit
BMC updates state after receiving data byte in DATA_IN, but before reading the byte out of the input buffer. I.e. it changes state while IBF=1
Figure 9-7, KCS Interface BMC to SMS Read Transfer Flow Chart
write READ byte to DATA_IN READ
OBF
READ_STATE?
wait for OBF=1 wait for IBF=0
This OBF is normally caused by the BMC returning a data byte for the read operation. After the last data byte, the BMC sets the state to IDLE_STATE while IBF=1 and then reads the input buffer to check the control code = READ. The status will be set to ERROR_STATE if the control code is not READ. The BMC then writes a dummy data byte to the output buffer to generate an interrupt so the driver can see the status change.
Note that software must track that it has received an interrupt from 'IDLE_STATE' while it is still in the 'read' phase in order to differentiate it from a non-communication interrupt. If the BMC needs to set the status to ERROR_STATE it will do so before writing a dummy 00h byte to the output buffer. (The BMC always places a dummy byte in the output buffer whenever it sets the status to ERROR_STATE.)
Yes
Read data byte from DATA_OUT
read
IDLE_STATE?
phase = idle
Error Exit
No No
Yes
Exit wait for OBF=1
Read dummy data byte from DATA_OUT
The BMC must wait for software to read the output buffer before writing OBF to generate a non-communications interrupt.
That is, if there are any pending interrupts while in IDLE_STATE, but OBF is already set, it must hold off the interrupt until it sees OBF go clear. Software must be careful, since missing any read of the output buffer will effectively disable interrupt generation. It may be a prudent safeguard for a driver to poll for OBF occassionallywhen waiting for an interrupt from the IDLE state.
Note that for IPMI v1.5, the last OBF interrupt is allowed to be shared with a pending non-communications interrupt.
See text.
The following figure shows a flow diagram for aborting KCS transactions in progress and/or retrieving KCS error status.
Figure 9-8, Aborting KCS Transactions in-progress and/or Retrieving KCS Error Status
wait for IBF=0
Yes Error Exit
OBF
READ_STATE?
Write READ dummy byte to DATA_IN phase = error3
Comm Failure wait for IBF=0
GET_STATUS/ABORT to CMD phase = error1
00h to DATA_IN phase = error2
clear OBF
OBF
wait for IBF=0
RETRY LIMIT?
No
Yes BMC writes dummy byte.
Required for interrupt driven systems. Optional if BMC supports polled access only.
OBF BMC sets status to
READ_STATE and writes the error status byte to the DATA_OUT register.
IDLE_STATE?
Yes
phase = idle
Exit
No Yes
increment retry count No
wait for IBF=0 error3
error2 error1
wait for OBF=1
Read error status code byte from DATA_OUT
BMC sets status to 'WRITE_STATE' (BMC always sets status to WRITE_STATE upon getting a control code in the command register).
The BMC then generates OBF interrupt to signal that it has read the byte from the command register.
This dummy byte interrupts the BMC and tells it that the software has handled the OBF interrupt and is ready for the next state.
This write interrupts the BMC and tells it that the software has retrieved the error status byte
wait for OBF=1
clear OBF Note that this last interrupt
occurs when the BMC is in IDLE_STATE. The driver must track that this interrupt is expected, otherwise it might interpret it as a non-communications interrupt.