1 /* 2 * ipmi_sol.h 3 * 4 * IPMI Serial-over-LAN Client Code 5 * 6 * Author: Cyclades Australia Pty. Ltd. 7 * Darius Davis <darius.davis@cyclades.com> 8 * 9 * Copyright 2005 Cyclades Australia Pty. Ltd. 10 * 11 * This program is free software; you can redistribute it and/or 12 * modify it under the terms of the GNU Lesser General Public License 13 * as published by the Free Software Foundation; either version 2 of 14 * the License, or (at your option) any later version. 15 * 16 * 17 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED 18 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 19 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 22 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 23 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 24 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR 25 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE 26 * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 * 28 * You should have received a copy of the GNU Lesser General Public 29 * License along with this program; if not, write to the Free 30 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 31 */ 32 33 /** 34 * @file include/OpenIPMI/ipmi_sol.h 35 * Interface for OpenIPMI Serial-over-LAN support. 36 * 37 * In keeping with the design of OpenIPMI, the SoL (Serial over LAN) API is 38 * designed for asynchronous, event-based use. Once you have an ipmi_con_t 39 * representing a LAN-based connection to a BMC, you can pass that structure 40 * to ipmi_sol_create to create an ipmi_sol_conn_t structure which will 41 * represent the SoL connection. 42 * 43 * At this point, one registers callbacks for events as required (i.e. data 44 * received, break received, connection state change), configures the bit rate, 45 * authentication and encryption, then calls ipmi_sol_open. 46 * 47 * The client software can then call ipmi_write(...) to send data to the BMC, 48 * and will receive data through the callback(s) that have been registered. 49 * 50 * When the connection is no longer required, the client is to call 51 * ipmi_sol_close, which closes the SoL connection. ipmi_sol_free is then 52 * used to dispose of the connection structure if it is no longer required. 53 * 54 * SoL supports a number of nonvolatile configuration parameters. These 55 * parameters are supported through a series of functions to set the 56 * default bit rate, required levels of permission, authentication and 57 * encryption, as well as flow-control parameters (Character Accumulate 58 * Interval and Character Send Threshold) and retry parameters (Retry 59 * Count and Retry Interval). These functions are a part of the separate 60 * ipmi_sol_config interface. (YET TO BE IMPLEMENTED) 61 * 62 * 63 * Reference: 64 * [1] "IPMI - Intelligent Platform Management Interface Specification 65 * Second Generation v2.0", Document Revision 1.0, February 12, 2004, 66 * with June 1, 2004 Markup. Accessed at: 67 * ftp://download.intel.com/design/servers/ipmi/IPMIv2_0rev1_0markup.pdf 68 * 69 * For configuration of SoL parameters, refer to: 70 * include/OpenIPMI/include/ipmi_sol.h 71 */ 72 73 #ifndef OPENIPMI_SOL_H 74 #define OPENIPMI_SOL_H 75 76 #ifdef __cplusplus 77 extern "C" { 78 #endif 79 80 /** 81 * Queue identification constants for ipmi_sol_flush(...). 82 */ 83 #define IPMI_SOL_BMC_TRANSMIT_QUEUE 0x01 84 #define IPMI_SOL_BMC_RECEIVE_QUEUE 0x02 85 #define IPMI_SOL_MANAGEMENT_CONSOLE_TRANSMIT_QUEUE 0x04 86 #define IPMI_SOL_MANAGEMENT_CONSOLE_RECEIVE_QUEUE 0x08 87 88 #define IPMI_SOL_BMC_QUEUES (IPMI_SOL_BMC_TRANSMIT_QUEUE \ 89 | IPMI_SOL_BMC_RECEIVE_QUEUE) 90 91 #define IPMI_SOL_MANAGEMENT_CONSOLE_QUEUES \ 92 (IPMI_SOL_MANAGEMENT_CONSOLE_TRANSMIT_QUEUE \ 93 | IPMI_SOL_MANAGEMENT_CONSOLE_RECEIVE_QUEUE) 94 95 #define IPMI_SOL_ALL_QUEUES (IPMI_SOL_BMC_QUEUES \ 96 | IPMI_SOL_MANAGEMENT_CONSOLE_QUEUES) 97 98 99 /** 100 * Bit rate constants (almost the same as baud rates) 101 */ 102 #define IPMI_SOL_BIT_RATE_DEFAULT 0x00 103 #define IPMI_SOL_BIT_RATE_9600 0x06 104 #define IPMI_SOL_BIT_RATE_19200 0x07 105 #define IPMI_SOL_BIT_RATE_38400 0x08 106 #define IPMI_SOL_BIT_RATE_57600 0x09 107 #define IPMI_SOL_BIT_RATE_115200 0x0a 108 109 110 /** 111 * The possible states of a SoL connection object. 112 */ 113 typedef enum 114 { 115 /* The connection is closed; no data transfer is possible. */ 116 ipmi_sol_state_closed, 117 118 /* The connection is currently starting up; no data transfer yet. */ 119 ipmi_sol_state_connecting, 120 121 /* The connection is up and operational. */ 122 ipmi_sol_state_connected, 123 124 /* The connection is up, but the BMC has reported Character 125 Transfer Unavailable. This means the BMC is flow-controlling 126 us. */ 127 ipmi_sol_state_connected_ctu, 128 129 /* The connection is going down. No data transfer. */ 130 ipmi_sol_state_closing 131 } ipmi_sol_state; 132 133 134 /** 135 * Values to specify serial alert behavior while SoL is activated. 136 */ 137 typedef enum 138 { 139 ipmi_sol_serial_alerts_fail = 0, 140 ipmi_sol_serial_alerts_deferred = 1, 141 ipmi_sol_serial_alerts_succeed = 2 142 } ipmi_sol_serial_alert_behavior; 143 144 145 /** 146 * Opaque data structure representing an IPMI SoL connection. 147 */ 148 typedef struct ipmi_sol_conn_s ipmi_sol_conn_t; 149 150 151 /** 152 * IPMI SoL callbacks 153 */ 154 155 /** 156 * This callback is used to indicate a change in the state of a connection. 157 * 158 * @param [in] conn The IPMI SoL connection. 159 * @param [in] state Identifies the state of the SoL connection. 160 * @param [in] error A value indicating the circumstances causing the change. 161 * - zero: The state change was due to a request from the client library. 162 * - IPMI_SOL_DISCONNECTED: The state change was due to the loss of a 163 * connection to the managed system. 164 * - IPMI_SOL_NOT_AVAILABLE: This indicates that the management console 165 * responded inappropriately while the library was trying to 166 * connect to SoL on the BMC, so the connection attempt has been 167 * abandoned. Only given on a transition from ipmi_sol_state_connecting 168 * to ipmi_sol_state_closed. 169 * - IPMI_RMCPP_INVALID_PAYLOAD_TYPE: The remote indicates that it can not 170 * support a compatible version of the SoL payload. This error 171 * will only be given on a transition from ipmi_sol_state_connecting 172 * to ipmi_sol_state_closed. 173 * - IPMI_SOL_DEACTIVATED: The change is because SoL has been deactivated on the 174 * managed system. 175 * - Another error code from IPMI or the Operating System. 176 * @param [in] cb_data The user-defined value provided when registering 177 * for the callback. 178 */ 179 typedef void (*ipmi_sol_connection_state_cb)(ipmi_sol_conn_t *conn, 180 ipmi_sol_state state, 181 int error, 182 void *cb_data); 183 184 185 /** 186 * This callback is called for each write request or control-line status 187 * request. 188 * 189 * @param [in] conn The IPMI SoL connection. 190 * @param [in] error The result of the transmit operation: 191 * - zero: The request has been ACKed and was successful. 192 * - IPMI_SOL_DISCONNECTED: A packet has failed to be delivered 193 * after the configured number of retries. The connection is lost 194 * and the request is discarded. 195 * - IPMI_SOL_CHARACTER_TRANSFER_UNAVAIL: The managed system is powered down 196 * or is otherwise unable to accept a character transfer. 197 * - IPMI_SOL_DEACTIVATED: The BMC has lost the serial connection 198 * due to intervention at the managed system. 199 * - IPMI_SOL_UNCONFIRMABLE_OPERATION: The request has been transmitted to 200 * the managed system, but the managed system is not expected 201 * acknowledge receipt. 202 * - Another error code (i.e. ENOMEM) to indicate another type of failure. 203 * @param [in] cb_data The user-defined value provided when registering 204 * for the callback. 205 */ 206 typedef void (*ipmi_sol_transmit_complete_cb)(ipmi_sol_conn_t *conn, 207 int error, 208 void *cb_data); 209 210 211 /** 212 * This callback is called asynchronously when characters have been received 213 * from the remote. 214 * 215 * This callback is registered using 216 * ipmi_register_data_received_callback. The recipient of this 217 * callback has the opportunity to refuse (NACK) the data by returning 218 * a nonzero value; conversely, it should return zero if the packet 219 * contents have been accepted. Note that if a NACK is returned, the 220 * BMC will hold packets until ipmi_sol_release_nack() is called or 221 * a flush is done. 222 * 223 * @param [in] conn The IPMI SoL connection. 224 * @param [in] buf A pointer to the character data. 225 * @param [in] count The number of characters in the buffer. 226 * @param [in] cb_data The user-defined value provided when registering 227 * for the callback. 228 * @return Zero if the data is accepted, nonzero if the data should be 229 * NACKed. 230 */ 231 typedef int (*ipmi_sol_data_received_cb)(ipmi_sol_conn_t *conn, 232 const void *buf, 233 size_t count, 234 void *cb_data); 235 236 237 /** 238 * This callback will be called upon the successful completion of a flush 239 * operation, or upon the determination of an error condition during the 240 * flush operation. 241 * 242 * @param [in] conn The IPMI SoL connection. 243 * @param [in] error The result of the flush operation: 244 * - zero: The flush operation completed successfully. 245 * - IPMI_SOL_DISCONNECTED: A packet has failed to be delivered 246 * after the configured number of retries. The connection is lost. 247 * - IPMI_SOL_DEACTIVATED: The BMC has lost the serial connection 248 * due to intervention at the managed system. 249 * - IPMI_SOL_UNCONFIRMABLE_OPERATION: The data has been transmitted to the 250 * managed system, the managed system can not be expected confirm 251 * receipt. 252 * @param [in] queue_selectors_flushed A bit mask indicating which queues 253 * were successfully flushed. 254 * @param [in] cb_data The user-defined value provided when registering 255 * for the callback. 256 */ 257 typedef void (*ipmi_sol_flush_complete_cb)(ipmi_sol_conn_t *conn, 258 int error, 259 int queue_selectors_flushed, 260 void *cb_data); 261 262 263 /** 264 * This callback is called asynchronously when the remote indicates it has 265 * detected a serial "break". 266 * 267 * This callback is registered using ipmi_register_break_detected_callback. 268 * 269 * @param [in] conn The IPMI SoL connection. 270 * @param [in] cb_data The user-defined value provided when registering 271 * for the callback. 272 */ 273 typedef void (*ipmi_sol_break_detected_cb)(ipmi_sol_conn_t *conn, 274 void *cb_data); 275 276 277 /** 278 * This callback is called asynchronously when the remote BMC indicates that 279 * it has encountered a transmitter overrun. Some incoming data may have 280 * been lost. 281 * 282 * This callback is registered using ipmi_register_bmc_transmit_overrun_callback. 283 * 284 * @param [in] conn The IPMI SoL connection. 285 * @param [in] cb_data The user-defined value provided when registering 286 * for the callback. 287 */ 288 typedef void (*ipmi_sol_bmc_transmit_overrun_cb)(ipmi_sol_conn_t *conn, 289 void *cb_data); 290 291 292 /** 293 * Constructs a handle for managing an SoL session. 294 * 295 * This function does NOT communicate with the BMC or activate the SoL payload. 296 * 297 * @param [in] ipmi the existing IPMI over LAN session. 298 * @param [out] sol_conn the address into which to store the allocated 299 * IPMI SoL connection structure. 300 * @return zero on success, or ENOMEM if memory allocation fails. 301 */ 302 int ipmi_sol_create(ipmi_con_t *ipmi, 303 ipmi_sol_conn_t **sol_conn); 304 305 306 307 /************************************************************************** 308 ** IPMI SoL connection configuration 309 **/ 310 311 312 /** 313 * Register for callbacks. For each of the following eight functions, the 314 * parameters are as follows: 315 * 316 * @param [in] conn The IPMI SoL connection. 317 * @param [in] cb The callback to register. 318 * @param [in] cb_data The user-defined data to pass to the callback. 319 * @return Zero on success, or a nonzero error code. 320 */ 321 int ipmi_sol_register_connection_state_callback(ipmi_sol_conn_t *conn, 322 ipmi_sol_connection_state_cb cb, 323 void *cb_data); 324 int ipmi_sol_deregister_connection_state_callback(ipmi_sol_conn_t *conn, 325 ipmi_sol_connection_state_cb cb, 326 void *cb_data); 327 328 int ipmi_sol_register_data_received_callback(ipmi_sol_conn_t *conn, 329 ipmi_sol_data_received_cb cb, 330 void *cb_data); 331 int ipmi_sol_deregister_data_received_callback(ipmi_sol_conn_t *conn, 332 ipmi_sol_data_received_cb cb, 333 void *cb_data); 334 335 int ipmi_sol_register_break_detected_callback(ipmi_sol_conn_t *conn, 336 ipmi_sol_break_detected_cb cb, 337 void *cb_data); 338 int ipmi_sol_deregister_break_detected_callback(ipmi_sol_conn_t *conn, 339 ipmi_sol_break_detected_cb cb, 340 void *cb_data); 341 342 int ipmi_sol_register_bmc_transmit_overrun_callback(ipmi_sol_conn_t *conn, 343 ipmi_sol_bmc_transmit_overrun_cb cb, 344 void *cb_data); 345 int ipmi_sol_deregister_bmc_transmit_overrun_callback(ipmi_sol_conn_t *conn, 346 ipmi_sol_bmc_transmit_overrun_cb cb, 347 void *cb_data); 348 349 350 /** 351 * Set the timeout to wait for an ACK from the BMC (for packets that expect an 352 * ACK). 353 * 354 * @param [in] conn The IPMI SoL connection to configure. 355 * @param [in] timeout_usec The timeout, in microseconds. 356 */ 357 void ipmi_sol_set_ACK_timeout(ipmi_sol_conn_t *conn, int timeout_usec); 358 359 /** 360 * Get the timeout to wait for an ACK from the BMC (for packets that expect an 361 * ACK). 362 * 363 * @param [in] conn The IPMI SoL connection to configure. 364 * 365 * @return The timeout 366 */ 367 int ipmi_sol_get_ACK_timeout(ipmi_sol_conn_t *conn); 368 369 370 /** 371 * Set the number of retries that we make before declaring a packet "lost". 372 * 373 * @param [in] conn The IPMI SoL connection to configure. 374 * @param [in] retries The number of retries before a packet is declared lost. 375 */ 376 void ipmi_sol_set_ACK_retries(ipmi_sol_conn_t *conn, int retries); 377 378 /** 379 * Get the number of retries that we make before declaring a packet "lost". 380 * 381 * @param [in] conn The IPMI SoL connection to configure. 382 * 383 * @return The number of retries 384 */ 385 int ipmi_sol_get_ACK_retries(ipmi_sol_conn_t *conn); 386 387 /** 388 * Configure the authentication to use for the SoL packets. 389 * 390 * @param [in] conn The IPMI SoL connection to configure. 391 * @param [in] use_authentication Nonzero to use authentication for the 392 * SoL packets. 393 * @return Zero on success, otherwise an error code. 394 */ 395 int ipmi_sol_set_use_authentication(ipmi_sol_conn_t *conn, 396 int use_authentication); 397 398 /** 399 * Query the authentication configuration for the SoL packets. 400 * 401 * @param [in] conn The IPMI SoL connection to query. 402 * @return Nonzero iff the connection will attempt to use authentication 403 * for SoL packets. 404 */ 405 int ipmi_sol_get_use_authentication(ipmi_sol_conn_t *conn); 406 407 408 /** 409 * Configure the encryption to use for the SoL packets. 410 * 411 * @param [in] conn The IPMI SoL connection to configure. 412 * @param [in] use_encryption Nonzero to use encryption for the 413 * SoL packets. 414 * @return Zero on success, otherwise an error code. 415 */ 416 int ipmi_sol_set_use_encryption(ipmi_sol_conn_t *conn, int use_encryption); 417 418 /** 419 * Query the encryption configuration for the SoL packets. 420 * 421 * @param [in] conn The IPMI SoL connection to query. 422 * @return Nonzero iff the connection will attempt to use encryption 423 * for SoL packets. 424 */ 425 int ipmi_sol_get_use_encryption(ipmi_sol_conn_t *conn); 426 427 428 /** 429 * Configure the shared serial alert behavior for the SoL connection. 430 * 431 * @param [in] conn The IPMI SoL connection to configure. 432 * @param [in] behavior A constant identifying the desired shared serial alert 433 * behavior during the SoL connection. 434 * @return Zero on success, otherwise an error code. 435 */ 436 int ipmi_sol_set_shared_serial_alert_behavior(ipmi_sol_conn_t *conn, 437 ipmi_sol_serial_alert_behavior behavior); 438 439 /** 440 * Query the shared serial alerts behavior configuration for the SoL connection. 441 * 442 * @param [in] conn The IPMI SoL connection to query. 443 * @return A value identifying the shared serial alert behavior that 444 * will be in force during the connection. 445 */ 446 ipmi_sol_serial_alert_behavior ipmi_sol_get_shared_serial_alert_behavior 447 (ipmi_sol_conn_t *conn); 448 449 450 /** 451 * Configure the CTS, DCD and DSR deassert-on-connect behavior to use for 452 * the SoL connection. 453 * 454 * @param [in] conn The IPMI SoL connection to configure. 455 * @param [in] assert Nonzero to deassert the handshaking signals at the 456 * start of the SoL connection. 457 * @return Zero on success, otherwise an error code. 458 */ 459 int ipmi_sol_set_deassert_CTS_DCD_DSR_on_connect(ipmi_sol_conn_t *conn, 460 int assert); 461 462 /** 463 * Query the CTS, DCD and DSR deassert-on-connect configuration for the 464 * SoL connection. 465 * 466 * @param [in] conn The IPMI SoL connection to query. 467 * @return Nonzero iff the connection will deassert CTS, DCD and DSR upon 468 * connection. 469 */ 470 int ipmi_sol_get_deassert_CTS_DCD_DSR_on_connect(ipmi_sol_conn_t *conn); 471 472 473 /** 474 * Configure the bit rate to use on connection. 475 * 476 * @param [in] conn The IPMI SoL connection to configure. 477 * @param [in] rate The bit rate constant (IPMI_SOL_BIT_RATE_xxxxx) 478 * @return Zero on success, otherwise an error code. 479 */ 480 int ipmi_sol_set_bit_rate(ipmi_sol_conn_t *conn, unsigned char rate); 481 482 483 /** 484 * Query the bit rate to be used upon connection. 485 * 486 * @param [in] conn The IPMI SoL connection to query. 487 * @return The bit rate that will be used (IPMI_SOL_BIT_RATE_xxxxx) 488 */ 489 unsigned char ipmi_sol_get_bit_rate(ipmi_sol_conn_t *conn); 490 491 492 /** 493 * Opens the SoL connection using the previously set nonvolatile and 494 * volatile parameters. 495 * 496 * This contacts the BMC and checks that we share a compatible revision of 497 * SoL, and that this connection has the privileges to activate SoL. If this 498 * function returns an ERROR, the callback will never be called. If it returns 499 * no error, the callback WILL be called, indicating whether the connection was 500 * successful or not. 501 * 502 * @param [in] conn The IPMI SoL connection handle from ipmi_sol_create. 503 * @param [in] cb The callback to use to indicate success or failure 504 * of the operation. This is only used if ipmi_sol_open 505 * returns zero. 506 * @param [in] cb_data User-defined data to pass to the callback. 507 * 508 * @return Zero on success. 509 * EINVAL if this handle is already connected. 510 * A nonzero IPMI error code on other failure. 511 */ 512 int ipmi_sol_open(ipmi_sol_conn_t *conn); 513 514 515 /** 516 * Requests the closure of the SoL session. 517 * 518 * Closing the SoL session also restores the baseboard serial mux to its 519 * initial state. 520 * 521 * @param [in] conn The IPMI SoL connection to close. 522 * @return Zero on success. 523 * EINVAL if this handle was already closing or closed. If the 524 * handle is closing, consider using ipmi_sol_force_close 525 * to hurry it along. 526 * A nonzero error code on other failure. 527 */ 528 int ipmi_sol_close(ipmi_sol_conn_t *conn); 529 530 /** 531 * Requests the closure of the SoL session. 532 * 533 * Closing the SoL session also restores the baseboard serial mux to its 534 * initial state. 535 * 536 * @param [in] conn The IPMI SoL connection to close. 537 * @param [in] rem_close Nonzero if the connection should send a close to 538 * the remote end. If false, don't inform the remote 539 * end of the close. 540 * @return Zero on success. 541 * EINVAL if this handle was already closing or closed. If the 542 * handle is closing, consider using ipmi_sol_force_close 543 * to hurry it along. 544 * A nonzero error code on other failure. 545 */ 546 int ipmi_sol_force_close_wsend(ipmi_sol_conn_t *conn, int rem_close); 547 548 /** 549 * Forces the closure of the SoL session. 550 * 551 * The BMC is notified that the connection will should close, but no attempt 552 * is made to wait for a response from the BMC. Otherwise, this function does 553 * purely local cleanup of outstanding transmit callbacks and connection- 554 * oriented memory allocations. 555 * 556 * @param [in] conn The IPMI SoL connection to close. 557 * @return Zero on success. 558 * EINVAL if this handle was already closed. 559 * A nonzero IPMI error code on other failure. 560 */ 561 int ipmi_sol_force_close(ipmi_sol_conn_t *conn); 562 563 564 /** 565 * Frees the memory used by the SoL connection structure. No callbacks will 566 * occur after this function is called. The connection will be forced closed 567 * if it was still open when the function was called. 568 * 569 * @param [in] conn The IPMI SoL connection to release. 570 * @return Zero on success, or a nonzero IPMI error code on failure. 571 */ 572 int ipmi_sol_free(ipmi_sol_conn_t *conn); 573 574 575 576 /****************************************************************************** 577 ** IPMI SoL write operations (and sundry operations that cause a transmit) 578 **/ 579 580 /** 581 * Send a sequence of bytes to the remote. 582 * 583 * This function (like all the others!) will either return an ERROR and 584 * never call the callback, or will return success and then WILL call 585 * the callback, indicating an error later if necessary. The callback is 586 * an indication that the BMC has ACKed *all* of the bytes in this request. 587 * There is no guarantee that the packet will not be fragmented or 588 * coalesced in transmission. 589 * 590 * @param [in] conn The IPMI SoL connection over which to transmit. 591 * @param [in] buf A pointer to the data to transmit. 592 * @param [in] count The nonzero number of bytes to send. 593 * @param [in] cb The callback to call when the transmission is complete. 594 * This callback will only be called if this function call 595 * returns zero. 596 * @param [in] cb_data User-defined data to pass to the callback. 597 * @return Zero on success 598 * EINVAL if a request is made to transmit zero bytes 599 * or a nonzero IPMI error code on failure. 600 */ 601 int ipmi_sol_write(ipmi_sol_conn_t *conn, 602 const void *buf, 603 int count, 604 ipmi_sol_transmit_complete_cb cb, 605 void *cb_data); 606 607 608 /** 609 * Release a NACK 610 * 611 * This function will release a NACK returned by the receive routine. 612 * For every NACK a receive routine returns, this must be called to 613 * reactivate receiving packets from the BMC. 614 * 615 * @param [in] conn The IPMI SoL connection over which to transmit. 616 * @return Zero on success 617 * EINVAL No NACK is pending. 618 */ 619 int ipmi_sol_release_nack(ipmi_sol_conn_t *conn); 620 621 622 /** 623 * Request that the BMC send a serial "break" to the managed system. 624 * 625 * @param [in] conn The IPMI SoL connection over which to transmit. 626 * @param [in] cb The callback to call when the transmission is complete. 627 * This callback will only be called if this function call 628 * returns zero. 629 * @param [in] cb_data User-defined data to pass to the callback. 630 * @return Zero on success, or a nonzero IPMI error code on failure. 631 * Callback is likely to receive IPMI_SOL_UNCONFIRMABLE_OPERATION 632 * because the BMC will not bother to acknowledge the receipt of 633 * this request unless it is sent at the same time as a block of 634 * data. 635 */ 636 int ipmi_sol_send_break(ipmi_sol_conn_t *conn, 637 ipmi_sol_transmit_complete_cb cb, 638 void *cb_data); 639 640 641 /** 642 * Controls CTS at the BMC, to request that the system attached to the BMC 643 * ceases transmitting characters. No guarantee is given that the BMC and/or 644 * baseboard will honour this request. Further buffered characters might still 645 * be received after CTS is deasserted. 646 * 647 * Choosing to "deassert" CTS here really puts CTS under the control of the BMC 648 * for its own flow control. 649 * 650 * @param [in] conn The IPMI SoL connection. 651 * @param [in] assertable Nonzero puts the CTS signal in the control of 652 * the BMC. Zero prevents the BMC from asserting 653 * the CTS signal. 654 * @param [in] cb The callback to call when the operation is complete. 655 * This callback will only be called if this function call 656 * returns zero. 657 * @param [in] cb_data User-defined data to pass to the callback. 658 * @return Zero on success, or a nonzero IPMI error code on failure. 659 * Callback is likely to receive IPMI_SOL_UNCONFIRMABLE_OPERATION 660 * because the BMC will not bother to acknowledge the receipt of 661 * this request unless it is sent at the same time as a block of 662 * data. 663 */ 664 int ipmi_sol_set_CTS_assertable(ipmi_sol_conn_t *conn, 665 int asserted, 666 ipmi_sol_transmit_complete_cb cb, 667 void *cb_data); 668 669 670 /** 671 * Asserts DCD and DSR at the BMC, as if we've answered the phone line. 672 * 673 * @param [in] conn The IPMI SoL connection. 674 * @param [in] asserted Nonzero if DCD and DSR should be asserted. 675 * @param [in] cb The callback to call when the operation is complete. 676 * This callback will only be called if this function call 677 * returns zero. 678 * @param [in] cb_data User-defined data to pass to the callback. 679 * @return Zero on success, or a nonzero IPMI error code on failure. 680 * Callback is likely to receive IPMI_SOL_UNCONFIRMABLE_OPERATION 681 * because the BMC will not bother to acknowledge the receipt of 682 * this request unless it is sent at the same time as a block of 683 * data. 684 */ 685 int ipmi_sol_set_DCD_DSR_asserted(ipmi_sol_conn_t *conn, 686 int asserted, 687 ipmi_sol_transmit_complete_cb cb, 688 void *cb_data); 689 690 691 /** 692 * Asserts RI, as if the phone line is ringing. 693 * 694 * The stated aim of this operation is to allow use of the Wake-on-Ring feature 695 * to power-up and gain the attention of a system. 696 * 697 * @param [in] conn The IPMI SoL connection. 698 * @param [in] asserted Nonzero if RI should be asserted by the BMC. 699 * @param [in] cb The callback to call when the operation is complete. 700 * This callback will only be called if this function call 701 * returns zero. 702 * @param [in] cb_data User-defined data to pass to the callback. 703 * @return Zero on success, or a nonzero IPMI error code on failure. 704 * Callback is likely to receive IPMI_SOL_UNCONFIRMABLE_OPERATION 705 * because the BMC will not bother to acknowledge the receipt of 706 * this request unless it is sent at the same time as a block of 707 * data. 708 */ 709 int ipmi_sol_set_RI_asserted(ipmi_sol_conn_t *conn, 710 int asserted, 711 ipmi_sol_transmit_complete_cb cb, 712 void *cb_data); 713 714 715 /** 716 * Requests a flush of the transmit queue(s) identified by queue_selector. 717 * 718 * If no error is returned, the callback will be called in a synchronous 719 * manner if the flush does not involve the BMC, asynchronous if it does. 720 * 721 * @param [in] conn The IPMI SoL connection. 722 * @param [in] queue_selectors Identifies the queues to flush. This is 723 * specified as a bitwise-OR of the following: 724 * 725 * - IPMI_SOL_BMC_TRANSMIT_QUEUE 726 * - IPMI_SOL_BMC_RECEIVE_QUEUE 727 * - IPMI_SOL_MANAGEMENT_CONSOLE_TRANSMIT_QUEUE 728 * - IPMI_SOL_MANAGEMENT_CONSOLE_RECEIVE_QUEUE 729 * 730 * or use IPMI_SOL_ALL_QUEUES, IPMI_SOL_BMC_QUEUES or 731 * IPMI_SOL_MANAGEMENT_CONSOLE_QUEUES 732 * 733 * @param [in] cb The callback to call when the operation is complete. 734 * This callback will only be called if this function call 735 * returns zero. 736 * @param [in] cb_data User-defined data to pass to the callback. 737 * @return Zero on success, or a nonzero IPMI error code on failure. 738 * Callback is likely to receive IPMI_SOL_UNCONFIRMABLE_OPERATION 739 * because the BMC will not bother to acknowledge the receipt of 740 * this request unless it is sent at the same time as a block of 741 * data. 742 */ 743 int ipmi_sol_flush(ipmi_sol_conn_t *conn, 744 int queue_selectors, 745 ipmi_sol_flush_complete_cb cb, 746 void *cb_data); 747 748 #ifdef __cplusplus 749 } 750 #endif 751 752 #endif /* OPENIPMI_SOL_H */ 753