1*c18ec02fSPetter ReinholdtsenThis document was last updated for release 1.8.8. 2*c18ec02fSPetter Reinholdtsen 3*c18ec02fSPetter ReinholdtsenThis document explains how Serial Over Lan is implemented on in the 4*c18ec02fSPetter Reinholdtsenipmitool IPMI client. Obviously, the code itself is authoritative, but 5*c18ec02fSPetter Reinholdtsenthis document should serve as a good starting point. 6*c18ec02fSPetter Reinholdtsen 7*c18ec02fSPetter ReinholdtsenSerial Over Lan (SOL) is defined in the IPMI v2 specification published by 8*c18ec02fSPetter ReinholdtsenIntel and available at http://www.intel.com/design/servers/ipmi/. SOL 9*c18ec02fSPetter Reinholdtsenfunctionality is built on top of the RMCP+ protocol as an additional 10*c18ec02fSPetter Reinholdtsenpayload type (type 1). 11*c18ec02fSPetter Reinholdtsen 12*c18ec02fSPetter ReinholdtsenThe high end SOL logic is implemented in src/ipmitool/lib/ipmi_sol.c. SOL 13*c18ec02fSPetter Reinholdtsensessions are begun in ipmitool using the "sol activate" command. This 14*c18ec02fSPetter Reinholdtsencommand maps directly to the IPMI Activate Payload command. It first 15*c18ec02fSPetter Reinholdtsenverifies that an RMCP+ session (lanplus interface) is being used to 16*c18ec02fSPetter Reinholdtsenestablish the session. Although the spec allows for a SOL connection to be 17*c18ec02fSPetter Reinholdtsenestablished on a port different than the RMCP+ port that the "activate 18*c18ec02fSPetter Reinholdtsenpayload" command issued, ipmitool does not support this. 19*c18ec02fSPetter Reinholdtsen 20*c18ec02fSPetter ReinholdtsenOnce a session has been established (the activate payload command 21*c18ec02fSPetter Reinholdtsensucceeds), ipmitool simply loops over a select() on user input and data 22*c18ec02fSPetter Reinholdtsenreturned from the BMC. All user input is first filtered so that special 23*c18ec02fSPetter Reinholdtsenescape sequences can suspend or deactivate the SOL session and so that data 24*c18ec02fSPetter Reinholdtsencan be broken into chunks no greater than N bytes. This maximum is 25*c18ec02fSPetter Reinholdtsenspecified by the BMC in the response to the Activate Payload command. 26*c18ec02fSPetter Reinholdtsen 27*c18ec02fSPetter ReinholdtsenUser input to the BMC is handled in ipmitool/src/plugins/lanplus/lanplus.c. 28*c18ec02fSPetter ReinholdtsenEvery SOL packet (with one exception) traveling in either direction causes 29*c18ec02fSPetter Reinholdtsenthe recipient to return an acknowledgement packet, though acks themself are 30*c18ec02fSPetter Reinholdtsennot acknowledged. The transport layer in lanplus.c handles the logic 31*c18ec02fSPetter Reinholdtsenregarding acks, partial acks, sequence numbers. SOL acknowledgements 32*c18ec02fSPetter Reinholdtsenpackets be acks, partial acks (the remote destination processed only some 33*c18ec02fSPetter Reinholdtsenof the data), and nacks (requests to stop sending packets). Nacks are not 34*c18ec02fSPetter Reinholdtsenhonored by ipmitool. 35*c18ec02fSPetter Reinholdtsen 36*c18ec02fSPetter ReinholdtsenNote that one way that SOL communication differs from standard IPMI 37*c18ec02fSPetter Reinholdtsencommands, is that it is not simply a request response protocol. Packets 38*c18ec02fSPetter Reinholdtsenmay be returned asyncrhonously from the BMC. When establishing a SOL 39*c18ec02fSPetter Reinholdtsensession, ipmitool registers a callback for asynchonously received data. 40*c18ec02fSPetter ReinholdtsenThis call back simply prints text returned from the BMC. 41*c18ec02fSPetter Reinholdtsen 42*c18ec02fSPetter ReinholdtsenOnce a user has chosen to exit the SOL session (with ~.) ipmitool sends the 43*c18ec02fSPetter ReinholdtsenIPMI SOL Deactivate command to the BMC. 44*c18ec02fSPetter Reinholdtsen 45*c18ec02fSPetter ReinholdtsenThe standard code path for SOL logic follows: 46*c18ec02fSPetter Reinholdtsen ipmi_sol_main (ipmi_sol.c): 47*c18ec02fSPetter Reinholdtsen 48*c18ec02fSPetter Reinholdtsen ipmi_sol_activate (ipmi_sol.c): 49*c18ec02fSPetter Reinholdtsen Argument validation 50*c18ec02fSPetter Reinholdtsen Creation and dispatch of IPMI Activate Payload command 51*c18ec02fSPetter Reinholdtsen 52*c18ec02fSPetter Reinholdtsen ipmi_sol_red_pill (ipmi_sol.c): 53*c18ec02fSPetter Reinholdtsen Loop on select() for user input and data returned from the BMC 54*c18ec02fSPetter Reinholdtsen Periodic dispatch of "keep alive" packet to the BMC. 55*c18ec02fSPetter Reinholdtsen Send user input to the BMC and BMC data to the console. 56*c18ec02fSPetter Reinholdtsen 57*c18ec02fSPetter Reinholdtsen processSolUserInput (ipmi_sol.c): 58*c18ec02fSPetter Reinholdtsen Process possible escape sequences (~., ~B, etc.) 59*c18ec02fSPetter Reinholdtsen Send (with retries) user data to the BMC 60*c18ec02fSPetter Reinholdtsen Partial creation of packet payload 61*c18ec02fSPetter Reinholdtsen 62*c18ec02fSPetter Reinholdtsen ipmi_lanplus_send_sol (lanplus.c): 63*c18ec02fSPetter Reinholdtsen Completion of packet payload 64*c18ec02fSPetter Reinholdtsen Send (with retries) of SOL packet 65*c18ec02fSPetter Reinholdtsen 66*c18ec02fSPetter Reinholdtsen ipmi_lanplus_send_payload (lanplus.c): 67*c18ec02fSPetter Reinholdtsen Creation of RMCP+ packet 68*c18ec02fSPetter Reinholdtsen Details general to all V2 packet processing, as 69*c18ec02fSPetter Reinholdtsen well as a some logic to handle ack reception. 70*c18ec02fSPetter Reinholdtsen 71*c18ec02fSPetter Reinholdtsen is_sol_partial_ack (lanplus.c): 72*c18ec02fSPetter Reinholdtsen Determine whether a data needs to be resent 73*c18ec02fSPetter Reinholdtsen 74*c18ec02fSPetter Reinholdtsen ipmi_lanplus_recv_sol (lanplus.c): 75*c18ec02fSPetter Reinholdtsen Handle data received by the BMC. Ack as appropriate. 76*c18ec02fSPetter Reinholdtsen 77