EFI SERIAL IO PROTOCOL

From PhoenixWiki

Jump to: navigation, search

This protocol is used to communicate with any type of character-based I/O device.

Contents

GUID

#define EFI_SERIAL_IO_PROTOCOL_GUID \
  {0xBB25CF6F,0xF1D4,0x11D2,0x9A,0x0C,0x00,0x90,0x27,0x3F,0xC1,0xFD}


Protocol Interface Structure

#include EFI_PROTOCOL_CONSUMER(SerialIo)

extern EFI_GUID gEfiSerialIoProtocolGuid;
typedef struct {
  UINT32                      Revision;
  EFI_SERIAL_RESET            Reset;
  EFI_SERIAL_SET_ATTRIBUTES   SetAttributes;
  EFI_SERIAL_SET_CONTROL_BITS SetControl;
  EFI_SERIAL_GET_CONTROL_BITS GetControl;
  EFI_SERIAL_WRITE            Write;
  EFI_SERIAL_READ             Read;
  SERIAL_IO_MODE              *Mode;
} EFI_SERIAL_IO_PROTOCOL;
#define EFI_SERIAL_IO_PROTOCOL_REVISION 0x00010000

Members

Member Description
Revision The revision to which the EFI_SERIAL_IO_PROTOCOL adheres. All future revisions must be backwards compatible. If a future version is not back wards compatible, it is not the same GUID.
Reset Resets the hardware device.
SetAttributes Sets communication parameters for a serial device. These include the baud rate, receive FIFO depth, transmit/receive time out, parity, data bits, and stop bit attributes.
SetControl Sets the control bits on a serial device. These include Request to Send and Data Terminal Ready.
GetControl Reads the status of the control bits on a serial device. These include Clear to Send, Data Set Ready, Ring Indicator, and Carrier Detect.
Write Sends a buffer of characters to a serial device.
Read Receives a buffer of characters from a serial device.
Mode Pointer to SERIAL_IO_MODE data.

Description

The Serial I/O protocol is used to communicate with UART-style serial devices. These can be standard UART serial ports in PC-AT systems, serial ports attached to a USB interface, or potentially any character-based I/O device.

The Serial I/O protocol can control byte I/O style devices from a generic device, to a device with features such as a UART. As such many of the serial I/O features are optional to allow for the case of devices that do not have UART controls. Each of these options is called out in the specific serial I/O functions.

The default attributes for all UART-style serial device interfaces are: 115,200 baud, a 1 byte receive FIFO, a 1,000,000 microsecond timeout per character, no parity, 8 data bits, and 1 stop bit. Flow control is the responsibility of the software that uses the protocol. Hardware flow control can be implemented through the use of the GetControl() and SetControl() functions (described below) to monitor and assert the flow control signals. The XON/XOFF flow control algorithm can be implemented in software by inserting XON and XOFF characters into the serial data stream as required.

Special care must be taken if a significant amount of data is going to be read from a serial device. Since UEFI drivers are polled mode drivers, characters received on a serial device might be missed. It is the responsibility of the software that uses the protocol to check for new data often enough to guarantee that no characters will be missed. The required polling frequency depends on the baud rate of the connection and the depth of the receive FIFO.

Reset()

Resets the serial device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SERIAL_RESET) (
  IN EFI_SERIAL_IO_PROTOCOL *This
  );

Parameters

Parameter Description
This A pointer to the EFI_SERIAL_IO_PROTOCOL instance.

Description
The Reset() function resets the hardware of a serial device.

Status Codes Returned

Status Code Description
EFI_SUCCESS The serial device was reset.
EFI_DEVICE_ERROR The serial device could not be reset.

SetAttributes()

Sets the baud rate, receive FIFO depth, transmit/receive time out, parity, data bits, and stop bits on a serial device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SERIAL_SET_ATTRIBUTES) (
  IN EFI_SERIAL_IO_PROTOCOL *This,
  IN UINT64                 BaudRate,
  IN UINT32                 ReceiveFifoDepth,
  IN UINT32                 Timeout
  IN EFI_PARITY_TYPE        Parity,
  IN UINT8                  DataBits,
  IN EFI_STOP_BITS_TYPE     StopBits
  );

Parameters

Parameter Description
This A pointer to the EFI_SERIAL_IO_PROTOCOL instance.
BaudRate The requested baud rate. A BaudRate value of 0 will use the device’s default interface speed.
ReceiveFifoDepth The requested depth of the FIFO on the receive side of the serial interface. A ReceiveFifoDepth value of 0 will use the device’s default FIFO depth.
Timeout The requested time out for a single character in microseconds. This timeout applies to both the transmit and receive side of the interface. A Timeout value of 0 will use the device’s default time out value.
Parity The type of parity to use on this serial device. A Parity value of DefaultParity will use the device’s default parity value.
DataBits The number of data bits to use on this serial device. A DataBits value of 0 will use the device’s default data bit setting.
StopBits The number of stop bits to use on this serial device. A StopBits value of DefaultStopBits will use the device’s default number of stop bits.

Description
The SetAttributes() function sets the baud rate, receive-FIFO depth, transmit/receive time out, parity, data bits, and stop bits on a serial device.

The controller for a serial device is programmed with the specified attributes. If the Parity, DataBits, or StopBits values are not valid, then an error will be returned. If the specified BaudRate is below the minimum baud rate supported by the serial device, an error will be returned. The nearest baud rate supported by the serial device will be selected without exceeding the BaudRate parameter. If the specified ReceiveFifoDepth is below the smallest FIFO size supported by the serial device, an error will be returned. The nearest FIFO size supported by the serial device will be selected without exceeding the ReceiveFifoDepth parameter.

Status Codes Returned

Status Code Description
EFI_SUCCESS The new attributes were set on the serial device.
EFI_INVALID_PARAMETER One or more of the attributes has an unsupported value.
EFI_DEVICE_ERROR The serial device is not functioning correctly.

SetControl()

Sets the control bits on a serial device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SERIAL_SET_CONTROL_BITS) (
  IN EFI_SERIAL_IO_PROTOCOL *This,
  IN UINT32                 Control
  );

Parameters

Parameter Description
This A pointer to the EFI_SERIAL_IO_PROTOCOL instance.
Control Sets the bits of Control that are settable.
#define EFI_SERIAL_CLEAR_TO_SEND                0x0010
#define EFI_SERIAL_DATA_SET_READY               0x0020
#define EFI_SERIAL_RING_INDICATE                0x0040
#define EFI_SERIAL_CARRIER_DETECT               0x0080
#define EFI_SERIAL_REQUEST_TO_SEND              0x0002
#define EFI_SERIAL_DATA_TERMINAL_READY          0x0001
#define EFI_SERIAL_INPUT_BUFFER_EMPTY           0x0100
#define EFI_SERIAL_OUTPUT_BUFFER_EMPTY          0x0200
#define EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE     0x1000
#define EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE     0x2000
#define EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE 0x4000

Description
The SetControl() function is used to assert or deassert the control signals on a serial device. The following signals are set according their bit settings:

  • Request to Send
  • Data Terminal Ready

Only the EFI_REQUEST_TO_SEND, EFI_DATA_TERMINAL_READY, EFI_HARDWARE_LOOPBACK_ENABLE, EFI_SOFTWARE_LOOPBACK_ENABLE, and EFI_HARDWARE_FLOW_CONTROL_ENABLE bits can be set with SetControl(). All the bits can be read with GetControl().

Status Codes Returned

Status Code Description
EFI_SUCCESS The new control bits were set on the serial device.
EFI_UNSUPPORTED The serial device does not support this operation.
EFI_DEVICE_ERROR The serial device is not functioning correctly.

GetControl()

Retrieves the status of the control bits on a serial device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SERIAL_GET_CONTROL_BITS) (
  IN  EFI_SERIAL_IO_PROTOCOL *This,
  OUT UINT32                 *Control
  );

Parameters

Parameter Description
This A pointer to the EFI_SERIAL_IO_PROTOCOL instance.
Control A pointer to return the current control signals from the serial device. See SetContro().

Description
The GetControl() function retrieves the status of the control bits on a serial device.

Status Codes Returned

Status Code Description
EFI_SUCCESS The control bits were read from the serial device.
EFI_DEVICE_ERROR The serial device is not functioning correctly.

Write()

Writes data to a serial device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SERIAL_WRITE) (
  IN     EFI_SERIAL_IO_PROTOCOL *This,
  IN OUT UINTN                  *BufferSize,
  IN     VOID                   *Buffer
  );

Parameters

Parameter Description
This A pointer to the EFI_SERIAL_IO_PROTOCOL instance.
BufferSize On input, the size of the Buffer. On output, the amount of data actually written.
Buffer The buffer of data to write.

Description
The Write() function writes the specified number of bytes to a serial device. If a time out error occurs while data is being sent to the serial port, transmission of this buffer will terminate, and EFI_TIMEOUT will be returned. In all cases the number of bytes actually written to the serial device is returned in BufferSize.

Status Codes Returned

Status Code Description
EFI_SUCCESS The data was written.
EFI_DEVICE_ERROR The device reported an error.
EFI_TIMEOUT The data write was stopped due to a timeout.

Read()

Reads data from a serial device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SERIAL_READ) (
  IN     EFI_SERIAL_IO_PROTOCOL *This,
  IN OUT UINTN *BufferSize,
  OUT    VOID *Buffer
  );

Parameters

Parameter Description
This A pointer to the EFI_SERIAL_IO_PROTOCOL instance.
BufferSize On input, the size of the Buffer. On output, the amount of data returned in Buffer.
Buffer The buffer to return the data into.

Description
The Read() function reads a specified number of bytes from a serial device. If a time out error or an overrun error is detected while data is being read from the serial device, then no more characters will be read, and an error will be returned. In all cases the number of bytes actually read is returned in BufferSize.

Status Codes Returned

Status Code Description
EFI_SUCCESS The data was read.
EFI_DEVICE_ERROR The serial device reported an error.
EFI_TIMEOUT The operation was stopped due to a timeout or overrun.

Copyright (C) 2008 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2008 UEFI Forum, Inc. Used with permission.

Personal tools