Main Page | Class List | Directories | File List | Class Members | File Members

ipmi_sol.h File Reference

Go to the source code of this file.

Defines

#define IPMI_SOL_BMC_TRANSMIT_QUEUE   0x01
#define IPMI_SOL_BMC_RECEIVE_QUEUE   0x02
#define IPMI_SOL_MANAGEMENT_CONSOLE_TRANSMIT_QUEUE   0x04
#define IPMI_SOL_MANAGEMENT_CONSOLE_RECEIVE_QUEUE   0x08
#define IPMI_SOL_BMC_QUEUES
#define IPMI_SOL_MANAGEMENT_CONSOLE_QUEUES
#define IPMI_SOL_ALL_QUEUES
#define IPMI_SOL_BIT_RATE_DEFAULT   0x00
#define IPMI_SOL_BIT_RATE_9600   0x06
#define IPMI_SOL_BIT_RATE_19200   0x07
#define IPMI_SOL_BIT_RATE_38400   0x08
#define IPMI_SOL_BIT_RATE_57600   0x09
#define IPMI_SOL_BIT_RATE_115200   0x0a

Typedefs

typedef ipmi_sol_conn_s ipmi_sol_conn_t
typedef void(* ipmi_sol_connection_state_cb )(ipmi_sol_conn_t *conn, ipmi_sol_state state, int error, void *cb_data)
typedef void(* ipmi_sol_transmit_complete_cb )(ipmi_sol_conn_t *conn, int error, void *cb_data)
typedef int(* ipmi_sol_data_received_cb )(ipmi_sol_conn_t *conn, const void *buf, size_t count, void *cb_data)
typedef void(* ipmi_sol_flush_complete_cb )(ipmi_sol_conn_t *conn, int error, int queue_selectors_flushed, void *cb_data)
typedef void(* ipmi_sol_break_detected_cb )(ipmi_sol_conn_t *conn, void *cb_data)
typedef void(* ipmi_sol_bmc_transmit_overrun_cb )(ipmi_sol_conn_t *conn, void *cb_data)

Enumerations

enum  ipmi_sol_state {
  ipmi_sol_state_closed, ipmi_sol_state_connecting, ipmi_sol_state_connected, ipmi_sol_state_connected_ctu,
  ipmi_sol_state_closing
}
enum  ipmi_sol_serial_alert_behavior { ipmi_sol_serial_alerts_fail = 0, ipmi_sol_serial_alerts_deferred = 1, ipmi_sol_serial_alerts_succeed = 2 }

Functions

int ipmi_sol_create (ipmi_con_t *ipmi, ipmi_sol_conn_t **sol_conn)
int ipmi_sol_register_connection_state_callback (ipmi_sol_conn_t *conn, ipmi_sol_connection_state_cb cb, void *cb_data)
int ipmi_sol_deregister_connection_state_callback (ipmi_sol_conn_t *conn, ipmi_sol_connection_state_cb cb, void *cb_data)
int ipmi_sol_register_data_received_callback (ipmi_sol_conn_t *conn, ipmi_sol_data_received_cb cb, void *cb_data)
int ipmi_sol_deregister_data_received_callback (ipmi_sol_conn_t *conn, ipmi_sol_data_received_cb cb, void *cb_data)
int ipmi_sol_register_break_detected_callback (ipmi_sol_conn_t *conn, ipmi_sol_break_detected_cb cb, void *cb_data)
int ipmi_sol_deregister_break_detected_callback (ipmi_sol_conn_t *conn, ipmi_sol_break_detected_cb cb, void *cb_data)
int ipmi_sol_register_bmc_transmit_overrun_callback (ipmi_sol_conn_t *conn, ipmi_sol_bmc_transmit_overrun_cb cb, void *cb_data)
int ipmi_sol_deregister_bmc_transmit_overrun_callback (ipmi_sol_conn_t *conn, ipmi_sol_bmc_transmit_overrun_cb cb, void *cb_data)
void ipmi_sol_set_ACK_timeout (ipmi_sol_conn_t *conn, int timeout_usec)
int ipmi_sol_get_ACK_timeout (ipmi_sol_conn_t *conn)
void ipmi_sol_set_ACK_retries (ipmi_sol_conn_t *conn, int retries)
int ipmi_sol_get_ACK_retries (ipmi_sol_conn_t *conn)
int ipmi_sol_set_use_authentication (ipmi_sol_conn_t *conn, int use_authentication)
int ipmi_sol_get_use_authentication (ipmi_sol_conn_t *conn)
int ipmi_sol_set_use_encryption (ipmi_sol_conn_t *conn, int use_encryption)
int ipmi_sol_get_use_encryption (ipmi_sol_conn_t *conn)
int ipmi_sol_set_shared_serial_alert_behavior (ipmi_sol_conn_t *conn, ipmi_sol_serial_alert_behavior behavior)
ipmi_sol_serial_alert_behavior ipmi_sol_get_shared_serial_alert_behavior (ipmi_sol_conn_t *conn)
int ipmi_sol_set_deassert_CTS_DCD_DSR_on_connect (ipmi_sol_conn_t *conn, int assert)
int ipmi_sol_get_deassert_CTS_DCD_DSR_on_connect (ipmi_sol_conn_t *conn)
int ipmi_sol_set_bit_rate (ipmi_sol_conn_t *conn, unsigned char rate)
unsigned char ipmi_sol_get_bit_rate (ipmi_sol_conn_t *conn)
int ipmi_sol_open (ipmi_sol_conn_t *conn)
int ipmi_sol_close (ipmi_sol_conn_t *conn)
int ipmi_sol_force_close (ipmi_sol_conn_t *conn)
int ipmi_sol_free (ipmi_sol_conn_t *conn)
int ipmi_sol_write (ipmi_sol_conn_t *conn, const void *buf, int count, ipmi_sol_transmit_complete_cb cb, void *cb_data)
int ipmi_sol_release_nack (ipmi_sol_conn_t *conn)
int ipmi_sol_send_break (ipmi_sol_conn_t *conn, ipmi_sol_transmit_complete_cb cb, void *cb_data)
int ipmi_sol_set_CTS_assertable (ipmi_sol_conn_t *conn, int asserted, ipmi_sol_transmit_complete_cb cb, void *cb_data)
int ipmi_sol_set_DCD_DSR_asserted (ipmi_sol_conn_t *conn, int asserted, ipmi_sol_transmit_complete_cb cb, void *cb_data)
int ipmi_sol_set_RI_asserted (ipmi_sol_conn_t *conn, int asserted, ipmi_sol_transmit_complete_cb cb, void *cb_data)
int ipmi_sol_flush (ipmi_sol_conn_t *conn, int queue_selectors, ipmi_sol_flush_complete_cb cb, void *cb_data)


Detailed Description

Interface for OpenIPMI Serial-over-LAN support.

In keeping with the design of OpenIPMI, the SoL (Serial over LAN) API is designed for asynchronous, event-based use. Once you have an ipmi_con_t representing a LAN-based connection to a BMC, you can pass that structure to ipmi_sol_create to create an ipmi_sol_conn_t structure which will represent the SoL connection.

At this point, one registers callbacks for events as required (i.e. data received, break received, connection state change), configures the bit rate, authentication and encryption, then calls ipmi_sol_open.

The client software can then call ipmi_write(...) to send data to the BMC, and will receive data through the callback(s) that have been registered.

When the connection is no longer required, the client is to call ipmi_sol_close, which closes the SoL connection. ipmi_sol_free is then used to dispose of the connection structure if it is no longer required.

SoL supports a number of nonvolatile configuration parameters. These parameters are supported through a series of functions to set the default bit rate, required levels of permission, authentication and encryption, as well as flow-control parameters (Character Accumulate Interval and Character Send Threshold) and retry parameters (Retry Count and Retry Interval). These functions are a part of the separate ipmi_sol_config interface. (YET TO BE IMPLEMENTED)

Reference: [1] "IPMI - Intelligent Platform Management Interface Specification Second Generation v2.0", Document Revision 1.0, February 12, 2004, with June 1, 2004 Markup. Accessed at: ftp://download.intel.com/design/servers/ipmi/IPMIv2_0rev1_0markup.pdf

For configuration of SoL parameters, refer to: include/OpenIPMI/include/ipmi_sol.h

Definition in file ipmi_sol.h.


Define Documentation

#define IPMI_SOL_ALL_QUEUES
 

Value:

Definition at line 95 of file ipmi_sol.h.

Referenced by sol_do_flush().

#define IPMI_SOL_BIT_RATE_115200   0x0a
 

Definition at line 107 of file ipmi_sol.h.

Referenced by parse_sol_bit_rate().

#define IPMI_SOL_BIT_RATE_19200   0x07
 

Definition at line 104 of file ipmi_sol.h.

Referenced by parse_sol_bit_rate().

#define IPMI_SOL_BIT_RATE_38400   0x08
 

Definition at line 105 of file ipmi_sol.h.

Referenced by parse_sol_bit_rate().

#define IPMI_SOL_BIT_RATE_57600   0x09
 

Definition at line 106 of file ipmi_sol.h.

Referenced by parse_sol_bit_rate().

#define IPMI_SOL_BIT_RATE_9600   0x06
 

Definition at line 103 of file ipmi_sol.h.

Referenced by parse_sol_bit_rate().

#define IPMI_SOL_BIT_RATE_DEFAULT   0x00
 

Bit rate constants (almost the same as baud rates)

Definition at line 102 of file ipmi_sol.h.

#define IPMI_SOL_BMC_QUEUES
 

Value:

Definition at line 88 of file ipmi_sol.h.

Referenced by ipmi_sol_flush().

#define IPMI_SOL_BMC_RECEIVE_QUEUE   0x02
 

Definition at line 84 of file ipmi_sol.h.

Referenced by ipmi_sol_flush().

#define IPMI_SOL_BMC_TRANSMIT_QUEUE   0x01
 

Queue identification constants for ipmi_sol_flush(...).

Definition at line 83 of file ipmi_sol.h.

Referenced by ipmi_sol_flush().

#define IPMI_SOL_MANAGEMENT_CONSOLE_QUEUES
 

Value:

Definition at line 91 of file ipmi_sol.h.

Referenced by ipmi_sol_flush().

#define IPMI_SOL_MANAGEMENT_CONSOLE_RECEIVE_QUEUE   0x08
 

Definition at line 86 of file ipmi_sol.h.

Referenced by ipmi_sol_flush().

#define IPMI_SOL_MANAGEMENT_CONSOLE_TRANSMIT_QUEUE   0x04
 

Definition at line 85 of file ipmi_sol.h.

Referenced by ipmi_sol_flush().


Typedef Documentation

typedef void(* ipmi_sol_bmc_transmit_overrun_cb)(ipmi_sol_conn_t *conn, void *cb_data)
 

This callback is called asynchronously when the remote BMC indicates that it has encountered a transmitter overrun. Some incoming data may have been lost.

This callback is registered using ipmi_register_bmc_transmit_overrun_callback.

Parameters:
[in] conn The IPMI SoL connection.
[in] cb_data The user-defined value provided when registering for the callback.

Definition at line 288 of file ipmi_sol.h.

typedef void(* ipmi_sol_break_detected_cb)(ipmi_sol_conn_t *conn, void *cb_data)
 

This callback is called asynchronously when the remote indicates it has detected a serial "break".

This callback is registered using ipmi_register_break_detected_callback.

Parameters:
[in] conn The IPMI SoL connection.
[in] cb_data The user-defined value provided when registering for the callback.

Definition at line 273 of file ipmi_sol.h.

typedef struct ipmi_sol_conn_s ipmi_sol_conn_t
 

Opaque data structure representing an IPMI SoL connection.

Definition at line 148 of file ipmi_sol.h.

typedef void(* ipmi_sol_connection_state_cb)(ipmi_sol_conn_t *conn, ipmi_sol_state state, int error, void *cb_data)
 

This callback is used to indicate a change in the state of a connection.

Parameters:
[in] conn The IPMI SoL connection.
[in] state Identifies the state of the SoL connection.
[in] error A value indicating the circumstances causing the change.
  • zero: The state change was due to a request from the client library.
  • IPMI_SOL_DISCONNECTED: The state change was due to the loss of a connection to the managed system.
  • IPMI_SOL_NOT_AVAILABLE: This indicates that the management console responded inappropriately while the library was trying to connect to SoL on the BMC, so the connection attempt has been abandoned. Only given on a transition from ipmi_sol_state_connecting to ipmi_sol_state_closed.
  • IPMI_RMCPP_INVALID_PAYLOAD_TYPE: The remote indicates that it can not support a compatible version of the SoL payload. This error will only be given on a transition from ipmi_sol_state_connecting to ipmi_sol_state_closed.
  • IPMI_SOL_DEACTIVATED: The change is because SoL has been deactivated on the managed system.
  • Another error code from IPMI or the Operating System.
[in] cb_data The user-defined value provided when registering for the callback.

Definition at line 179 of file ipmi_sol.h.

typedef int(* ipmi_sol_data_received_cb)(ipmi_sol_conn_t *conn, const void *buf, size_t count, void *cb_data)
 

This callback is called asynchronously when characters have been received from the remote.

This callback is registered using ipmi_register_data_received_callback. The recipient of this callback has the opportunity to refuse (NACK) the data by returning a nonzero value; conversely, it should return zero if the packet contents have been accepted. Note that if a NACK is returned, the BMC will hold packets until ipmi_sol_release_nack() is called or a flush is done.

Parameters:
[in] conn The IPMI SoL connection.
[in] buf A pointer to the character data.
[in] count The number of characters in the buffer.
[in] cb_data The user-defined value provided when registering for the callback.
Returns:
Zero if the data is accepted, nonzero if the data should be NACKed.

Definition at line 231 of file ipmi_sol.h.

typedef void(* ipmi_sol_flush_complete_cb)(ipmi_sol_conn_t *conn, int error, int queue_selectors_flushed, void *cb_data)
 

This callback will be called upon the successful completion of a flush operation, or upon the determination of an error condition during the flush operation.

Parameters:
[in] conn The IPMI SoL connection.
[in] error The result of the flush operation:
  • zero: The flush operation completed successfully.
  • IPMI_SOL_DISCONNECTED: A packet has failed to be delivered after the configured number of retries. The connection is lost.
  • IPMI_SOL_DEACTIVATED: The BMC has lost the serial connection due to intervention at the managed system.
  • IPMI_SOL_UNCONFIRMABLE_OPERATION: The data has been transmitted to the managed system, the managed system can not be expected confirm receipt.
[in] queue_selectors_flushed A bit mask indicating which queues were successfully flushed.
[in] cb_data The user-defined value provided when registering for the callback.

Definition at line 257 of file ipmi_sol.h.

typedef void(* ipmi_sol_transmit_complete_cb)(ipmi_sol_conn_t *conn, int error, void *cb_data)
 

This callback is called for each write request or control-line status request.

Parameters:
[in] conn The IPMI SoL connection.
[in] error The result of the transmit operation:
  • zero: The request has been ACKed and was successful.
  • IPMI_SOL_DISCONNECTED: A packet has failed to be delivered after the configured number of retries. The connection is lost and the request is discarded.
  • IPMI_SOL_CHARACTER_TRANSFER_UNAVAIL: The managed system is powered down or is otherwise unable to accept a character transfer.
  • IPMI_SOL_DEACTIVATED: The BMC has lost the serial connection due to intervention at the managed system.
  • IPMI_SOL_UNCONFIRMABLE_OPERATION: The request has been transmitted to the managed system, but the managed system is not expected acknowledge receipt.
  • Another error code (i.e. ENOMEM) to indicate another type of failure.
[in] cb_data The user-defined value provided when registering for the callback.

Definition at line 206 of file ipmi_sol.h.


Enumeration Type Documentation

enum ipmi_sol_serial_alert_behavior
 

Values to specify serial alert behavior while SoL is activated.

Enumerator:
ipmi_sol_serial_alerts_fail 
ipmi_sol_serial_alerts_deferred 
ipmi_sol_serial_alerts_succeed 

Definition at line 137 of file ipmi_sol.h.

enum ipmi_sol_state
 

The possible states of a SoL connection object.

Enumerator:
ipmi_sol_state_closed 
ipmi_sol_state_connecting 
ipmi_sol_state_connected 
ipmi_sol_state_connected_ctu 
ipmi_sol_state_closing 

Definition at line 113 of file ipmi_sol.h.

00114 {
00115     /* The connection is closed; no data transfer is possible. */
00116     ipmi_sol_state_closed,
00117 
00118     /* The connection is currently starting up; no data transfer yet. */
00119     ipmi_sol_state_connecting,
00120 
00121     /* The connection is up and operational. */
00122     ipmi_sol_state_connected,
00123 
00124     /* The connection is up, but the BMC has reported Character
00125        Transfer Unavailable.  This means the BMC is flow-controlling
00126        us. */
00127     ipmi_sol_state_connected_ctu,
00128 
00129     /* The connection is going down.  No data transfer. */
00130     ipmi_sol_state_closing
00131 } ipmi_sol_state;


Function Documentation

int ipmi_sol_close ipmi_sol_conn_t conn  ) 
 

Requests the closure of the SoL session.

Closing the SoL session also restores the baseboard serial mux to its initial state.

Parameters:
[in] conn The IPMI SoL connection to close.
[in] force Nonzero if the connection should be forced to close. Forcing the connection to close will be a synchronous operation. All outstanding transmits will be cancelled and the transmit_complete callbacks will be called indicating that the transmit failed. The connection_ state callback will also be called before this function returns.
Returns:
Zero on success. EINVAL if this handle was already closing or closed. If the handle is closing, consider using ipmi_sol_force_close to hurry it along. A nonzero error code on other failure.

Definition at line 3103 of file ipmi_sol.c.

References handle_deactivate_payload_response(), ipmi_lock(), ipmi_sol_state_closed, ipmi_sol_state_closing, ipmi_unlock(), ipmi_sol_transmitter_context_s::packet_lock, send_close(), ipmi_sol_conn_s::state, and ipmi_sol_conn_s::transmitter.

Referenced by solterm_disconnect().

03104 {
03105     ipmi_lock(conn->transmitter.packet_lock);
03106     if ((conn->state == ipmi_sol_state_closing)
03107         || (conn->state == ipmi_sol_state_closed))
03108     {
03109         ipmi_unlock(conn->transmitter.packet_lock);
03110         return EINVAL;
03111     }
03112         
03113     send_close(conn, handle_deactivate_payload_response);
03114     ipmi_unlock(conn->transmitter.packet_lock);
03115     return 0;
03116 }

int ipmi_sol_create ipmi_con_t ipmi,
ipmi_sol_conn_t **  sol_conn
 

Constructs a handle for managing an SoL session.

This function does NOT communicate with the BMC or activate the SoL payload.

Parameters:
[in] ipmi the existing IPMI over LAN session.
[out] sol_conn the address into which to store the allocated IPMI SoL connection structure.
Returns:
zero on success, or ENOMEM if memory allocation fails.

Definition at line 2359 of file ipmi_sol.c.

References add_connection(), ipmi_create_lock_os_hnd(), ipmi_destroy_lock(), ipmi_mem_alloc(), ipmi_mem_free(), IPMI_SOL_AUX_USE_AUTHENTICATION, IPMI_SOL_AUX_USE_ENCRYPTION, ipmi_sol_state_closed, ipmi_sol_transmitter_context_s::latest_outgoing_seqnr, locked_list_alloc(), locked_list_destroy(), ipmi_sol_transmitter_context_s::oob_op_lock, os_hnd, ipmi_con_s::os_hnd, ipmi_sol_transmitter_context_s::packet_lock, ipmi_sol_transmitter_context_s::queue_lock, ipmi_sol_transmitter_context_s::sol_conn, and ipmi_sol_transmitter_context_s::transmitted_packet.

Referenced by main().

02361 {
02362     ipmi_sol_conn_t                *new_conn;
02363     os_handler_t                   *os_hnd = ipmi->os_hnd;
02364     ipmi_sol_transmitter_context_t *xmitter;
02365     int                            rv;
02366 
02367     new_conn = ipmi_mem_alloc(sizeof(*new_conn));
02368     if (!new_conn)
02369         return ENOMEM;
02370 
02371     memset(new_conn, 0, sizeof(*new_conn));
02372 
02373     new_conn->refcount = 1;
02374 
02375     xmitter = &new_conn->transmitter;
02376 
02377     /* Enable authentication and encryption by default. */
02378     new_conn->auxiliary_payload_data = (IPMI_SOL_AUX_USE_ENCRYPTION
02379                                         | IPMI_SOL_AUX_USE_AUTHENTICATION);
02380 
02381     rv = ipmi_create_lock_os_hnd(os_hnd, &xmitter->packet_lock);
02382     if (rv)
02383         goto out_err;
02384 
02385     rv = ipmi_create_lock_os_hnd(os_hnd, &xmitter->queue_lock);
02386     if (rv)
02387         goto out_err;
02388 
02389     rv = ipmi_create_lock_os_hnd(os_hnd, &xmitter->oob_op_lock);
02390     if (rv)
02391         goto out_err;
02392 
02393     new_conn->ipmi = ipmi;
02394     new_conn->data_received_callback_list = locked_list_alloc(os_hnd);
02395     if (! new_conn->data_received_callback_list) {
02396         rv = ENOMEM;
02397         goto out_err;
02398     }
02399     new_conn->break_detected_callback_list = locked_list_alloc(os_hnd);
02400     if (! new_conn->break_detected_callback_list) {
02401         rv = ENOMEM;
02402         goto out_err;
02403     }
02404     new_conn->bmc_transmit_overrun_callback_list = locked_list_alloc(os_hnd);
02405     if (! new_conn->bmc_transmit_overrun_callback_list) {
02406         rv = ENOMEM;
02407         goto out_err;
02408     }
02409     new_conn->connection_state_callback_list = locked_list_alloc(os_hnd);
02410     if (! new_conn->connection_state_callback_list) {
02411         rv = ENOMEM;
02412         goto out_err;
02413     }
02414 
02415     new_conn->prev_received_seqnr = 0;
02416     new_conn->prev_character_count = 0;
02417 
02418     new_conn->state = ipmi_sol_state_closed;
02419     new_conn->try_fast_connect = 1;
02420 
02421     xmitter->sol_conn = new_conn;
02422     xmitter->transmitted_packet = NULL;
02423     xmitter->latest_outgoing_seqnr = 1;
02424 
02425     new_conn->ACK_retries = 10;
02426     new_conn->ACK_timeout_usec = 1000000;
02427 
02428     rv = add_connection(new_conn);
02429     if (rv)
02430         goto out_err;
02431 
02432     *sol_conn = new_conn;
02433 
02434     return 0;
02435 
02436  out_err:
02437     if (xmitter->packet_lock)
02438         ipmi_destroy_lock(xmitter->packet_lock);
02439     if (xmitter->queue_lock)
02440         ipmi_destroy_lock(xmitter->queue_lock);
02441     if (xmitter->oob_op_lock)
02442         ipmi_destroy_lock(xmitter->oob_op_lock);
02443     if (new_conn->data_received_callback_list)
02444         locked_list_destroy(new_conn->data_received_callback_list);
02445     if (new_conn->break_detected_callback_list)
02446         locked_list_destroy(new_conn->break_detected_callback_list);
02447     if (new_conn->bmc_transmit_overrun_callback_list)
02448         locked_list_destroy(new_conn->bmc_transmit_overrun_callback_list);
02449     if (new_conn->connection_state_callback_list)
02450         locked_list_destroy(new_conn->connection_state_callback_list);
02451     ipmi_mem_free(new_conn);
02452     return rv;
02453 }

int ipmi_sol_deregister_bmc_transmit_overrun_callback ipmi_sol_conn_t conn,
ipmi_sol_bmc_transmit_overrun_cb  cb,
void *  cb_data
 

Definition at line 833 of file ipmi_sol.c.

References ipmi_sol_conn_s::bmc_transmit_overrun_callback_list, and locked_list_remove().

00836 {
00837     if (locked_list_remove(conn->bmc_transmit_overrun_callback_list, cb,
00838                            cb_data))
00839         return 0;
00840     else
00841         return EINVAL;
00842 }

int ipmi_sol_deregister_break_detected_callback ipmi_sol_conn_t conn,
ipmi_sol_break_detected_cb  cb,
void *  cb_data
 

Definition at line 810 of file ipmi_sol.c.

References ipmi_sol_conn_s::break_detected_callback_list, and locked_list_remove().

00813 {
00814     if (locked_list_remove(conn->break_detected_callback_list, cb, cb_data))
00815         return 0;
00816     else
00817         return EINVAL;
00818 }

int ipmi_sol_deregister_connection_state_callback ipmi_sol_conn_t conn,
ipmi_sol_connection_state_cb  cb,
void *  cb_data
 

Definition at line 857 of file ipmi_sol.c.

References ipmi_sol_conn_s::connection_state_callback_list, and locked_list_remove().

00860 {
00861     if (locked_list_remove(conn->connection_state_callback_list, cb, cb_data))
00862         return 0;
00863     else
00864         return EINVAL;
00865 }

int ipmi_sol_deregister_data_received_callback ipmi_sol_conn_t conn,
ipmi_sol_data_received_cb  cb,
void *  cb_data
 

Definition at line 787 of file ipmi_sol.c.

References ipmi_sol_conn_s::data_received_callback_list, and locked_list_remove().

00790 {
00791     if (locked_list_remove(conn->data_received_callback_list, cb, cb_data))
00792         return 0;
00793     else
00794         return EINVAL;
00795 }

int ipmi_sol_flush ipmi_sol_conn_t conn,
int  queue_selectors,
ipmi_sol_flush_complete_cb  cb,
void *  cb_data
 

Requests a flush of the transmit queue(s) identified by queue_selector.

If no error is returned, the callback will be called in a synchronous manner if the flush does not involve the BMC, asynchronous if it does.

Parameters:
[in] conn The IPMI SoL connection.
[in] queue_selectors Identifies the queues to flush. This is specified as a bitwise-OR of the following:
  • IPMI_SOL_BMC_TRANSMIT_QUEUE
  • IPMI_SOL_BMC_RECEIVE_QUEUE
  • IPMI_SOL_MANAGEMENT_CONSOLE_TRANSMIT_QUEUE
  • IPMI_SOL_MANAGEMENT_CONSOLE_RECEIVE_QUEUE

or use IPMI_SOL_ALL_QUEUES, IPMI_SOL_BMC_QUEUES or IPMI_SOL_MANAGEMENT_CONSOLE_QUEUES

Parameters:
[in] cb The callback to call when the operation is complete. This callback will only be called if this function call returns zero.
[in] cb_data User-defined data to pass to the callback.
Returns:
Zero on success, or a nonzero IPMI error code on failure. Callback is likely to receive IPMI_SOL_UNCONFIRMABLE_OPERATION because the BMC will not bother to acknowledge the receipt of this request unless it is sent at the same time as a block of data.

Definition at line 2261 of file ipmi_sol.c.

References add_op_control_callback(), flush_finalize(), ipmi_lock(), ipmi_mem_alloc(), IPMI_SOL_BMC_QUEUES, IPMI_SOL_BMC_RECEIVE_QUEUE, IPMI_SOL_BMC_TRANSMIT_QUEUE, IPMI_SOL_ERR_VAL, IPMI_SOL_FLUSHED, IPMI_SOL_MANAGEMENT_CONSOLE_QUEUES, IPMI_SOL_MANAGEMENT_CONSOLE_RECEIVE_QUEUE, IPMI_SOL_MANAGEMENT_CONSOLE_TRANSMIT_QUEUE, IPMI_SOL_OPERATION_FLUSH_BMC_TO_CONSOLE, IPMI_SOL_OPERATION_FLUSH_CONSOLE_TO_BMC, ipmi_sol_state_connected, ipmi_sol_state_connected_ctu, ipmi_unlock(), ipmi_sol_transmitter_context_s::oob_op_lock, ipmi_sol_transmitter_context_s::oob_transient_op, ipmi_sol_transmitter_context_s::packet_lock, ipmi_sol_conn_s::state, ipmi_sol_conn_s::transmitter, transmitter_flush_outbound(), and transmitter_prod().

Referenced by sol_do_flush().

02265 {
02266     int rv = 0;
02267     int need_callback = 0;
02268 
02269     ipmi_lock(conn->transmitter.packet_lock);
02270     if ((conn->state != ipmi_sol_state_connected)
02271         && (conn->state != ipmi_sol_state_connected_ctu))
02272     {
02273         ipmi_unlock(conn->transmitter.packet_lock);
02274         return EINVAL;
02275     }
02276 
02277     /*
02278      * Do we flush the local transmit queue?
02279      */
02280     if (!rv
02281         && (! (queue_selectors & IPMI_SOL_MANAGEMENT_CONSOLE_TRANSMIT_QUEUE)))
02282     {
02283         transmitter_flush_outbound(&conn->transmitter,
02284                                    IPMI_SOL_ERR_VAL(IPMI_SOL_FLUSHED));
02285     }
02286 
02287     /*
02288      * Do we flush the local receive queue?
02289      */
02290     if (!rv
02291         && (! (queue_selectors & IPMI_SOL_MANAGEMENT_CONSOLE_RECEIVE_QUEUE)))
02292     {
02293         /* We don't HAVE a local RX queue... */
02294         /*VOID*/
02295     }
02296 
02297     ipmi_lock(conn->transmitter.oob_op_lock);
02298     /*
02299      * Do we flush the remote transmit queue?
02300      */
02301     if (!rv && (! (queue_selectors & IPMI_SOL_BMC_TRANSMIT_QUEUE))) {
02302         conn->transmitter.oob_transient_op
02303             |= IPMI_SOL_OPERATION_FLUSH_BMC_TO_CONSOLE;
02304         need_callback = 1;
02305     }
02306 
02307     /*
02308      * Do we flush the remote receive queue?
02309      */
02310     if (!rv && (! (queue_selectors & IPMI_SOL_BMC_RECEIVE_QUEUE))) {
02311         conn->transmitter.oob_transient_op
02312             |= IPMI_SOL_OPERATION_FLUSH_CONSOLE_TO_BMC;
02313         need_callback = 1;
02314     }
02315 
02316     if (need_callback) {
02317         ipmi_sol_flush_data_t *flush_data;
02318 
02319         flush_data = ipmi_mem_alloc(sizeof(*flush_data));
02320 
02321         flush_data->cb = cb;
02322         flush_data->cb_data = cb_data;
02323 
02324         /* FIXME - the below two had &&, not &.  I assumed that was wrong. */
02325         flush_data->selectors_flushed
02326             = queue_selectors & IPMI_SOL_MANAGEMENT_CONSOLE_QUEUES;
02327         flush_data->selectors_pending = queue_selectors & IPMI_SOL_BMC_QUEUES;
02328 
02329         rv = add_op_control_callback(&conn->transmitter, flush_finalize,
02330                                      flush_data);
02331         ipmi_unlock(conn->transmitter.oob_op_lock);
02332 
02333         transmitter_prod(&conn->transmitter);
02334     } else {
02335         ipmi_unlock(conn->transmitter.oob_op_lock);
02336     }
02337 
02338     ipmi_unlock(conn->transmitter.packet_lock);
02339     return rv;
02340 }

int ipmi_sol_force_close ipmi_sol_conn_t conn  ) 
 

Forces the closure of the SoL session.

The BMC is notified that the connection will should close, but no attempt is made to wait for a response from the BMC. Otherwise, this function does purely local cleanup of outstanding transmit callbacks and connection- oriented memory allocations.

Parameters:
[in] conn The IPMI SoL connection to close.
Returns:
Zero on success. EINVAL if this handle was already closed. A nonzero IPMI error code on other failure.

Definition at line 3120 of file ipmi_sol.c.

References ipmi_lock(), IPMI_SOL_DISCONNECTED, IPMI_SOL_ERR_VAL, ipmi_sol_set_connection_state(), ipmi_sol_state_closed, ipmi_sol_state_closing, ipmi_unlock(), ipmi_sol_transmitter_context_s::packet_lock, send_close(), ipmi_sol_conn_s::state, ipmi_sol_conn_s::transmitter, and transmitter_shutdown().

Referenced by conn_changed(), main(), and sol_cleanup().

03121 {
03122     ipmi_lock(conn->transmitter.packet_lock);
03123     if (conn->state == ipmi_sol_state_closed) {
03124         ipmi_unlock(conn->transmitter.packet_lock);
03125         return EINVAL;
03126     }
03127 
03128     if (conn->state != ipmi_sol_state_closing)
03129         /*
03130          * Try to be polite to the BMC. Don't ask for a callback,
03131          * cos we'll be gone!
03132          */
03133         send_close(conn, NULL); 
03134 
03135     transmitter_shutdown(&conn->transmitter,
03136                          IPMI_SOL_ERR_VAL(IPMI_SOL_DISCONNECTED));
03137 
03138     ipmi_sol_set_connection_state(conn, ipmi_sol_state_closed,
03139                                   IPMI_SOL_ERR_VAL(IPMI_SOL_DISCONNECTED));
03140     ipmi_unlock(conn->transmitter.packet_lock);
03141 
03142     return 0;
03143 }

int ipmi_sol_free ipmi_sol_conn_t conn  ) 
 

Frees the memory used by the SoL connection structure. No callbacks will occur after this function is called. The connection will be forced closed if it was still open when the function was called.

Parameters:
[in] conn The IPMI SoL connection to release.
Returns:
Zero on success, or a nonzero IPMI error code on failure.

Definition at line 3147 of file ipmi_sol.c.

References sol_put_connection().

Referenced by main().

03148 {
03149     sol_put_connection(conn);
03150     return 0;
03151 }

int ipmi_sol_get_ACK_retries ipmi_sol_conn_t conn  ) 
 

Get the number of retries that we make before declaring a packet "lost".

Parameters:
[in] conn The IPMI SoL connection to configure.
Returns:
The number of retries

Definition at line 887 of file ipmi_sol.c.

References ipmi_sol_conn_s::ACK_retries.

00888 {
00889     return conn->ACK_retries;
00890 }

int ipmi_sol_get_ACK_timeout ipmi_sol_conn_t conn  ) 
 

Get the timeout to wait for an ACK from the BMC (for packets that expect an ACK).

Parameters:
[in] conn The IPMI SoL connection to configure.
Returns:
The timeout

Definition at line 875 of file ipmi_sol.c.

References ipmi_sol_conn_s::ACK_timeout_usec.

00876 {
00877     return conn->ACK_timeout_usec;
00878 }

unsigned char ipmi_sol_get_bit_rate ipmi_sol_conn_t conn  ) 
 

Query the bit rate to be used upon connection.

Parameters:
[in] conn The IPMI SoL connection to query.
Returns:
The bit rate that will be used (IPMI_SOL_BIT_RATE_xxxxx)

Definition at line 1044 of file ipmi_sol.c.

References ipmi_sol_conn_s::initial_bit_rate.

01045 {
01046     return conn->initial_bit_rate;
01047 }

int ipmi_sol_get_deassert_CTS_DCD_DSR_on_connect ipmi_sol_conn_t conn  ) 
 

Query the CTS, DCD and DSR deassert-on-connect configuration for the SoL connection.

Parameters:
[in] conn The IPMI SoL connection to query.
Returns:
Nonzero iff the connection will deassert CTS, DCD and DSR upon connection.

Definition at line 1019 of file ipmi_sol.c.

References ipmi_sol_conn_s::auxiliary_payload_data, and IPMI_SOL_AUX_DEASSERT_HANDSHAKE.

01020 {
01021     return ((conn->auxiliary_payload_data & IPMI_SOL_AUX_DEASSERT_HANDSHAKE)
01022             != 0);
01023 }

ipmi_sol_serial_alert_behavior ipmi_sol_get_shared_serial_alert_behavior ipmi_sol_conn_t conn  ) 
 

Query the shared serial alerts behavior configuration for the SoL connection.

Parameters:
[in] conn The IPMI SoL connection to query.
Returns:
A value identifying the shared serial alert behavior that will be in force during the connection.

Definition at line 987 of file ipmi_sol.c.

References ipmi_sol_conn_s::auxiliary_payload_data, IPMI_SOL_AUX_SHARED_SERIAL_BEHAVIOR_MASK, and IPMI_SOL_AUX_SHARED_SERIAL_BEHAVIOR_SHIFT.

int ipmi_sol_get_use_authentication ipmi_sol_conn_t conn  ) 
 

Query the authentication configuration for the SoL packets.

Parameters:
[in] conn The IPMI SoL connection to query.
Returns:
Nonzero iff the connection will attempt to use authentication for SoL packets.

Definition at line 927 of file ipmi_sol.c.

References ipmi_sol_conn_s::auxiliary_payload_data, and IPMI_SOL_AUX_USE_AUTHENTICATION.

Referenced by transmit_outstanding_packet().

00928 {
00929     return ((conn->auxiliary_payload_data & IPMI_SOL_AUX_USE_AUTHENTICATION)
00930             != 0);
00931 }

int ipmi_sol_get_use_encryption ipmi_sol_conn_t conn  ) 
 

Query the encryption configuration for the SoL packets.

Parameters:
[in] conn The IPMI SoL connection to query.
Returns:
Nonzero iff the connection will attempt to use encryption for SoL packets.

Definition at line 955 of file ipmi_sol.c.

References ipmi_sol_conn_s::auxiliary_payload_data, and IPMI_SOL_AUX_USE_ENCRYPTION.

Referenced by transmit_outstanding_packet().

00956 {
00957     return ((conn->auxiliary_payload_data & IPMI_SOL_AUX_USE_ENCRYPTION)
00958             != 0);
00959 }

int ipmi_sol_open ipmi_sol_conn_t conn  ) 
 

Opens the SoL connection using the previously set nonvolatile and volatile parameters.

This contacts the BMC and checks that we share a compatible revision of SoL, and that this connection has the privileges to activate SoL. If this function returns an ERROR, the callback will never be called. If it returns no error, the callback WILL be called, indicating whether the connection was successful or not.

Parameters:
[in] conn The IPMI SoL connection handle from ipmi_sol_create.
[in] cb The callback to use to indicate success or failure of the operation. This is only used if ipmi_sol_open returns zero.
[in] cb_data User-defined data to pass to the callback.
Returns:
Zero on success. EINVAL if this handle is already connected. A nonzero IPMI error code on other failure.

Definition at line 3028 of file ipmi_sol.c.

References ipmi_sol_conn_s::addr, ipmi_system_interface_addr::addr_type, ipmi_rmcpp_addr::addr_type, ipmi_system_interface_addr::channel, IPMI_BMC_CHANNEL, ipmi_lock(), ipmi_log(), IPMI_LOG_ERR_INFO, IPMI_RMCPP_ADDR_SOL, ipmi_sol_set_connection_state(), ipmi_sol_state_closed, ipmi_sol_state_connecting, IPMI_SYSTEM_INTERFACE_ADDR_TYPE, ipmi_unlock(), ipmi_system_interface_addr::lun, ipmi_sol_transmitter_context_s::packet_lock, send_get_channel_payload_support_command(), send_get_payload_activation_status_command(), ipmi_sol_conn_s::sol_payload_addr, ipmi_sol_conn_s::state, ipmi_sol_conn_s::transmitter, and ipmi_sol_conn_s::try_fast_connect.

Referenced by conn_changed().

03029 {
03030     int rv;
03031 
03032     ipmi_lock(conn->transmitter.packet_lock);
03033     if (conn->state != ipmi_sol_state_closed) {
03034         /* It's an error to try to connect when not in closed state. */
03035         ipmi_unlock(conn->transmitter.packet_lock);
03036         ipmi_log(IPMI_LOG_ERR_INFO,
03037                  "ipmi_sol.c(ipmi_sol_open): "
03038                  "An attempt was made to open an SoL connection"
03039                  " that's already open.");
03040         return EINVAL;
03041     }
03042 
03043     conn->addr.addr_type = IPMI_SYSTEM_INTERFACE_ADDR_TYPE;
03044     conn->addr.channel = IPMI_BMC_CHANNEL;
03045     conn->addr.lun = 0;
03046     
03047     /*
03048      * Note: For SoL over IPMI 1.5, the ipmi_lan code will translate this
03049      * RMCP+ address into the right packet format over RMCP (instead of
03050      * RMCP+).
03051      */
03052     conn->sol_payload_addr.addr_type = IPMI_RMCPP_ADDR_SOL;
03053 
03054     if (conn->try_fast_connect)
03055         rv = send_get_payload_activation_status_command(conn);
03056     else
03057         rv = send_get_channel_payload_support_command(conn);
03058 
03059     if (!rv)
03060         ipmi_sol_set_connection_state(conn, ipmi_sol_state_connecting, 0);
03061 
03062     conn->transmitter.nack_count = 0;
03063     conn->transmitter.packet_to_acknowledge = 0;
03064     conn->transmitter.accepted_character_count = 0;
03065     conn->transmitter.bytes_acked_at_head = 0;
03066 
03067     ipmi_unlock(conn->transmitter.packet_lock);
03068     return rv;
03069 }

int ipmi_sol_register_bmc_transmit_overrun_callback ipmi_sol_conn_t conn,
ipmi_sol_bmc_transmit_overrun_cb  cb,
void *  cb_data
 

Definition at line 822 of file ipmi_sol.c.

References ipmi_sol_conn_s::bmc_transmit_overrun_callback_list, and locked_list_add().

Referenced by configure_sol().

00825 {
00826