1*f334afcfSToomas Soome /** @file 2*f334afcfSToomas Soome Serial IO protocol as defined in the UEFI 2.0 specification. 3*f334afcfSToomas Soome 4*f334afcfSToomas Soome Abstraction of a basic serial device. Targeted at 16550 UART, but 5*f334afcfSToomas Soome could be much more generic. 6*f334afcfSToomas Soome 7*f334afcfSToomas Soome Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 8*f334afcfSToomas Soome SPDX-License-Identifier: BSD-2-Clause-Patent 9*f334afcfSToomas Soome 10*f334afcfSToomas Soome **/ 11*f334afcfSToomas Soome 12*f334afcfSToomas Soome #ifndef __SERIAL_IO_PROTOCOL_H__ 13*f334afcfSToomas Soome #define __SERIAL_IO_PROTOCOL_H__ 14*f334afcfSToomas Soome 15*f334afcfSToomas Soome #define EFI_SERIAL_IO_PROTOCOL_GUID \ 16*f334afcfSToomas Soome { \ 17*f334afcfSToomas Soome 0xBB25CF6F, 0xF1D4, 0x11D2, {0x9A, 0x0C, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0xFD } \ 18*f334afcfSToomas Soome } 19*f334afcfSToomas Soome 20*f334afcfSToomas Soome #define EFI_SERIAL_TERMINAL_DEVICE_TYPE_GUID \ 21*f334afcfSToomas Soome { \ 22*f334afcfSToomas Soome 0X6AD9A60F, 0X5815, 0X4C7C, { 0X8A, 0X10, 0X50, 0X53, 0XD2, 0XBF, 0X7A, 0X1B } \ 23*f334afcfSToomas Soome } 24*f334afcfSToomas Soome 25*f334afcfSToomas Soome /// 26*f334afcfSToomas Soome /// Protocol GUID defined in EFI1.1. 27*f334afcfSToomas Soome /// 28*f334afcfSToomas Soome #define SERIAL_IO_PROTOCOL EFI_SERIAL_IO_PROTOCOL_GUID 29*f334afcfSToomas Soome 30*f334afcfSToomas Soome typedef struct _EFI_SERIAL_IO_PROTOCOL EFI_SERIAL_IO_PROTOCOL; 31*f334afcfSToomas Soome 32*f334afcfSToomas Soome /// 33*f334afcfSToomas Soome /// Backward-compatible with EFI1.1. 34*f334afcfSToomas Soome /// 35*f334afcfSToomas Soome typedef EFI_SERIAL_IO_PROTOCOL SERIAL_IO_INTERFACE; 36*f334afcfSToomas Soome 37*f334afcfSToomas Soome /// 38*f334afcfSToomas Soome /// Parity type that is computed or checked as each character is transmitted or received. If the 39*f334afcfSToomas Soome /// device does not support parity, the value is the default parity value. 40*f334afcfSToomas Soome /// 41*f334afcfSToomas Soome typedef enum { 42*f334afcfSToomas Soome DefaultParity, 43*f334afcfSToomas Soome NoParity, 44*f334afcfSToomas Soome EvenParity, 45*f334afcfSToomas Soome OddParity, 46*f334afcfSToomas Soome MarkParity, 47*f334afcfSToomas Soome SpaceParity 48*f334afcfSToomas Soome } EFI_PARITY_TYPE; 49*f334afcfSToomas Soome 50*f334afcfSToomas Soome /// 51*f334afcfSToomas Soome /// Stop bits type 52*f334afcfSToomas Soome /// 53*f334afcfSToomas Soome typedef enum { 54*f334afcfSToomas Soome DefaultStopBits, 55*f334afcfSToomas Soome OneStopBit, 56*f334afcfSToomas Soome OneFiveStopBits, 57*f334afcfSToomas Soome TwoStopBits 58*f334afcfSToomas Soome } EFI_STOP_BITS_TYPE; 59*f334afcfSToomas Soome 60*f334afcfSToomas Soome // 61*f334afcfSToomas Soome // define for Control bits, grouped by read only, write only, and read write 62*f334afcfSToomas Soome // 63*f334afcfSToomas Soome // 64*f334afcfSToomas Soome // Read Only 65*f334afcfSToomas Soome // 66*f334afcfSToomas Soome #define EFI_SERIAL_CLEAR_TO_SEND 0x00000010 67*f334afcfSToomas Soome #define EFI_SERIAL_DATA_SET_READY 0x00000020 68*f334afcfSToomas Soome #define EFI_SERIAL_RING_INDICATE 0x00000040 69*f334afcfSToomas Soome #define EFI_SERIAL_CARRIER_DETECT 0x00000080 70*f334afcfSToomas Soome #define EFI_SERIAL_INPUT_BUFFER_EMPTY 0x00000100 71*f334afcfSToomas Soome #define EFI_SERIAL_OUTPUT_BUFFER_EMPTY 0x00000200 72*f334afcfSToomas Soome 73*f334afcfSToomas Soome // 74*f334afcfSToomas Soome // Write Only 75*f334afcfSToomas Soome // 76*f334afcfSToomas Soome #define EFI_SERIAL_REQUEST_TO_SEND 0x00000002 77*f334afcfSToomas Soome #define EFI_SERIAL_DATA_TERMINAL_READY 0x00000001 78*f334afcfSToomas Soome 79*f334afcfSToomas Soome // 80*f334afcfSToomas Soome // Read Write 81*f334afcfSToomas Soome // 82*f334afcfSToomas Soome #define EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE 0x00001000 83*f334afcfSToomas Soome #define EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE 0x00002000 84*f334afcfSToomas Soome #define EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE 0x00004000 85*f334afcfSToomas Soome 86*f334afcfSToomas Soome // 87*f334afcfSToomas Soome // Serial IO Member Functions 88*f334afcfSToomas Soome // 89*f334afcfSToomas Soome 90*f334afcfSToomas Soome /** 91*f334afcfSToomas Soome Reset the serial device. 92*f334afcfSToomas Soome 93*f334afcfSToomas Soome @param This Protocol instance pointer. 94*f334afcfSToomas Soome 95*f334afcfSToomas Soome @retval EFI_SUCCESS The device was reset. 96*f334afcfSToomas Soome @retval EFI_DEVICE_ERROR The serial device could not be reset. 97*f334afcfSToomas Soome 98*f334afcfSToomas Soome **/ 99*f334afcfSToomas Soome typedef 100*f334afcfSToomas Soome EFI_STATUS 101*f334afcfSToomas Soome (EFIAPI *EFI_SERIAL_RESET)( 102*f334afcfSToomas Soome IN EFI_SERIAL_IO_PROTOCOL *This 103*f334afcfSToomas Soome ); 104*f334afcfSToomas Soome 105*f334afcfSToomas Soome /** 106*f334afcfSToomas Soome Sets the baud rate, receive FIFO depth, transmit/receice time out, parity, 107*f334afcfSToomas Soome data bits, and stop bits on a serial device. 108*f334afcfSToomas Soome 109*f334afcfSToomas Soome @param This Protocol instance pointer. 110*f334afcfSToomas Soome @param BaudRate The requested baud rate. A BaudRate value of 0 will use the 111*f334afcfSToomas Soome device's default interface speed. 112*f334afcfSToomas Soome @param ReveiveFifoDepth The requested depth of the FIFO on the receive side of the 113*f334afcfSToomas Soome serial interface. A ReceiveFifoDepth value of 0 will use 114*f334afcfSToomas Soome the device's default FIFO depth. 115*f334afcfSToomas Soome @param Timeout The requested time out for a single character in microseconds. 116*f334afcfSToomas Soome This timeout applies to both the transmit and receive side of the 117*f334afcfSToomas Soome interface. A Timeout value of 0 will use the device's default time 118*f334afcfSToomas Soome out value. 119*f334afcfSToomas Soome @param Parity The type of parity to use on this serial device. A Parity value of 120*f334afcfSToomas Soome DefaultParity will use the device's default parity value. 121*f334afcfSToomas Soome @param DataBits The number of data bits to use on the serial device. A DataBits 122*f334afcfSToomas Soome vaule of 0 will use the device's default data bit setting. 123*f334afcfSToomas Soome @param StopBits The number of stop bits to use on this serial device. A StopBits 124*f334afcfSToomas Soome value of DefaultStopBits will use the device's default number of 125*f334afcfSToomas Soome stop bits. 126*f334afcfSToomas Soome 127*f334afcfSToomas Soome @retval EFI_SUCCESS The device was reset. 128*f334afcfSToomas Soome @retval EFI_INVALID_PARAMETER One or more attributes has an unsupported value. 129*f334afcfSToomas Soome @retval EFI_DEVICE_ERROR The serial device is not functioning correctly. 130*f334afcfSToomas Soome 131*f334afcfSToomas Soome **/ 132*f334afcfSToomas Soome typedef 133*f334afcfSToomas Soome EFI_STATUS 134*f334afcfSToomas Soome (EFIAPI *EFI_SERIAL_SET_ATTRIBUTES)( 135*f334afcfSToomas Soome IN EFI_SERIAL_IO_PROTOCOL *This, 136*f334afcfSToomas Soome IN UINT64 BaudRate, 137*f334afcfSToomas Soome IN UINT32 ReceiveFifoDepth, 138*f334afcfSToomas Soome IN UINT32 Timeout, 139*f334afcfSToomas Soome IN EFI_PARITY_TYPE Parity, 140*f334afcfSToomas Soome IN UINT8 DataBits, 141*f334afcfSToomas Soome IN EFI_STOP_BITS_TYPE StopBits 142*f334afcfSToomas Soome ); 143*f334afcfSToomas Soome 144*f334afcfSToomas Soome /** 145*f334afcfSToomas Soome Set the control bits on a serial device 146*f334afcfSToomas Soome 147*f334afcfSToomas Soome @param This Protocol instance pointer. 148*f334afcfSToomas Soome @param Control Set the bits of Control that are settable. 149*f334afcfSToomas Soome 150*f334afcfSToomas Soome @retval EFI_SUCCESS The new control bits were set on the serial device. 151*f334afcfSToomas Soome @retval EFI_UNSUPPORTED The serial device does not support this operation. 152*f334afcfSToomas Soome @retval EFI_DEVICE_ERROR The serial device is not functioning correctly. 153*f334afcfSToomas Soome 154*f334afcfSToomas Soome **/ 155*f334afcfSToomas Soome typedef 156*f334afcfSToomas Soome EFI_STATUS 157*f334afcfSToomas Soome (EFIAPI *EFI_SERIAL_SET_CONTROL_BITS)( 158*f334afcfSToomas Soome IN EFI_SERIAL_IO_PROTOCOL *This, 159*f334afcfSToomas Soome IN UINT32 Control 160*f334afcfSToomas Soome ); 161*f334afcfSToomas Soome 162*f334afcfSToomas Soome /** 163*f334afcfSToomas Soome Retrieves the status of thecontrol bits on a serial device 164*f334afcfSToomas Soome 165*f334afcfSToomas Soome @param This Protocol instance pointer. 166*f334afcfSToomas Soome @param Control A pointer to return the current Control signals from the serial device. 167*f334afcfSToomas Soome 168*f334afcfSToomas Soome @retval EFI_SUCCESS The control bits were read from the serial device. 169*f334afcfSToomas Soome @retval EFI_DEVICE_ERROR The serial device is not functioning correctly. 170*f334afcfSToomas Soome 171*f334afcfSToomas Soome **/ 172*f334afcfSToomas Soome typedef 173*f334afcfSToomas Soome EFI_STATUS 174*f334afcfSToomas Soome (EFIAPI *EFI_SERIAL_GET_CONTROL_BITS)( 175*f334afcfSToomas Soome IN EFI_SERIAL_IO_PROTOCOL *This, 176*f334afcfSToomas Soome OUT UINT32 *Control 177*f334afcfSToomas Soome ); 178*f334afcfSToomas Soome 179*f334afcfSToomas Soome /** 180*f334afcfSToomas Soome Writes data to a serial device. 181*f334afcfSToomas Soome 182*f334afcfSToomas Soome @param This Protocol instance pointer. 183*f334afcfSToomas Soome @param BufferSize On input, the size of the Buffer. On output, the amount of 184*f334afcfSToomas Soome data actually written. 185*f334afcfSToomas Soome @param Buffer The buffer of data to write 186*f334afcfSToomas Soome 187*f334afcfSToomas Soome @retval EFI_SUCCESS The data was written. 188*f334afcfSToomas Soome @retval EFI_DEVICE_ERROR The device reported an error. 189*f334afcfSToomas Soome @retval EFI_TIMEOUT The data write was stopped due to a timeout. 190*f334afcfSToomas Soome 191*f334afcfSToomas Soome **/ 192*f334afcfSToomas Soome typedef 193*f334afcfSToomas Soome EFI_STATUS 194*f334afcfSToomas Soome (EFIAPI *EFI_SERIAL_WRITE)( 195*f334afcfSToomas Soome IN EFI_SERIAL_IO_PROTOCOL *This, 196*f334afcfSToomas Soome IN OUT UINTN *BufferSize, 197*f334afcfSToomas Soome IN VOID *Buffer 198*f334afcfSToomas Soome ); 199*f334afcfSToomas Soome 200*f334afcfSToomas Soome /** 201*f334afcfSToomas Soome Writes data to a serial device. 202*f334afcfSToomas Soome 203*f334afcfSToomas Soome @param This Protocol instance pointer. 204*f334afcfSToomas Soome @param BufferSize On input, the size of the Buffer. On output, the amount of 205*f334afcfSToomas Soome data returned in Buffer. 206*f334afcfSToomas Soome @param Buffer The buffer to return the data into. 207*f334afcfSToomas Soome 208*f334afcfSToomas Soome @retval EFI_SUCCESS The data was read. 209*f334afcfSToomas Soome @retval EFI_DEVICE_ERROR The device reported an error. 210*f334afcfSToomas Soome @retval EFI_TIMEOUT The data write was stopped due to a timeout. 211*f334afcfSToomas Soome 212*f334afcfSToomas Soome **/ 213*f334afcfSToomas Soome typedef 214*f334afcfSToomas Soome EFI_STATUS 215*f334afcfSToomas Soome (EFIAPI *EFI_SERIAL_READ)( 216*f334afcfSToomas Soome IN EFI_SERIAL_IO_PROTOCOL *This, 217*f334afcfSToomas Soome IN OUT UINTN *BufferSize, 218*f334afcfSToomas Soome OUT VOID *Buffer 219*f334afcfSToomas Soome ); 220*f334afcfSToomas Soome 221*f334afcfSToomas Soome /** 222*f334afcfSToomas Soome @par Data Structure Description: 223*f334afcfSToomas Soome The data values in SERIAL_IO_MODE are read-only and are updated by the code 224*f334afcfSToomas Soome that produces the SERIAL_IO_PROTOCOL member functions. 225*f334afcfSToomas Soome 226*f334afcfSToomas Soome @param ControlMask 227*f334afcfSToomas Soome A mask for the Control bits that the device supports. The device 228*f334afcfSToomas Soome must always support the Input Buffer Empty control bit. 229*f334afcfSToomas Soome 230*f334afcfSToomas Soome @param TimeOut 231*f334afcfSToomas Soome If applicable, the number of microseconds to wait before timing out 232*f334afcfSToomas Soome a Read or Write operation. 233*f334afcfSToomas Soome 234*f334afcfSToomas Soome @param BaudRate 235*f334afcfSToomas Soome If applicable, the current baud rate setting of the device; otherwise, 236*f334afcfSToomas Soome baud rate has the value of zero to indicate that device runs at the 237*f334afcfSToomas Soome device's designed speed. 238*f334afcfSToomas Soome 239*f334afcfSToomas Soome @param ReceiveFifoDepth 240*f334afcfSToomas Soome The number of characters the device will buffer on input 241*f334afcfSToomas Soome 242*f334afcfSToomas Soome @param DataBits 243*f334afcfSToomas Soome The number of characters the device will buffer on input 244*f334afcfSToomas Soome 245*f334afcfSToomas Soome @param Parity 246*f334afcfSToomas Soome If applicable, this is the EFI_PARITY_TYPE that is computed or 247*f334afcfSToomas Soome checked as each character is transmitted or reveived. If the device 248*f334afcfSToomas Soome does not support parity the value is the default parity value. 249*f334afcfSToomas Soome 250*f334afcfSToomas Soome @param StopBits 251*f334afcfSToomas Soome If applicable, the EFI_STOP_BITS_TYPE number of stop bits per 252*f334afcfSToomas Soome character. If the device does not support stop bits the value is 253*f334afcfSToomas Soome the default stop bit values. 254*f334afcfSToomas Soome 255*f334afcfSToomas Soome **/ 256*f334afcfSToomas Soome typedef struct { 257*f334afcfSToomas Soome UINT32 ControlMask; 258*f334afcfSToomas Soome 259*f334afcfSToomas Soome // 260*f334afcfSToomas Soome // current Attributes 261*f334afcfSToomas Soome // 262*f334afcfSToomas Soome UINT32 Timeout; 263*f334afcfSToomas Soome UINT64 BaudRate; 264*f334afcfSToomas Soome UINT32 ReceiveFifoDepth; 265*f334afcfSToomas Soome UINT32 DataBits; 266*f334afcfSToomas Soome UINT32 Parity; 267*f334afcfSToomas Soome UINT32 StopBits; 268*f334afcfSToomas Soome } EFI_SERIAL_IO_MODE; 269*f334afcfSToomas Soome 270*f334afcfSToomas Soome #define EFI_SERIAL_IO_PROTOCOL_REVISION 0x00010000 271*f334afcfSToomas Soome #define EFI_SERIAL_IO_PROTOCOL_REVISION1p1 0x00010001 272*f334afcfSToomas Soome #define SERIAL_IO_INTERFACE_REVISION EFI_SERIAL_IO_PROTOCOL_REVISION 273*f334afcfSToomas Soome 274*f334afcfSToomas Soome /// 275*f334afcfSToomas Soome /// The Serial I/O protocol is used to communicate with UART-style serial devices. 276*f334afcfSToomas Soome /// These can be standard UART serial ports in PC-AT systems, serial ports attached 277*f334afcfSToomas Soome /// to a USB interface, or potentially any character-based I/O device. 278*f334afcfSToomas Soome /// 279*f334afcfSToomas Soome struct _EFI_SERIAL_IO_PROTOCOL { 280*f334afcfSToomas Soome /// 281*f334afcfSToomas Soome /// The revision to which the EFI_SERIAL_IO_PROTOCOL adheres. All future revisions 282*f334afcfSToomas Soome /// must be backwards compatible. If a future version is not backwards compatible, 283*f334afcfSToomas Soome /// it is not the same GUID. 284*f334afcfSToomas Soome /// 285*f334afcfSToomas Soome UINT32 Revision; 286*f334afcfSToomas Soome EFI_SERIAL_RESET Reset; 287*f334afcfSToomas Soome EFI_SERIAL_SET_ATTRIBUTES SetAttributes; 288*f334afcfSToomas Soome EFI_SERIAL_SET_CONTROL_BITS SetControl; 289*f334afcfSToomas Soome EFI_SERIAL_GET_CONTROL_BITS GetControl; 290*f334afcfSToomas Soome EFI_SERIAL_WRITE Write; 291*f334afcfSToomas Soome EFI_SERIAL_READ Read; 292*f334afcfSToomas Soome /// 293*f334afcfSToomas Soome /// Pointer to SERIAL_IO_MODE data. 294*f334afcfSToomas Soome /// 295*f334afcfSToomas Soome EFI_SERIAL_IO_MODE *Mode; 296*f334afcfSToomas Soome /// 297*f334afcfSToomas Soome /// Pointer to a GUID identifying the device connected to the serial port. 298*f334afcfSToomas Soome /// This field is NULL when the protocol is installed by the serial port 299*f334afcfSToomas Soome /// driver and may be populated by a platform driver for a serial port 300*f334afcfSToomas Soome /// with a known device attached. The field will remain NULL if there is 301*f334afcfSToomas Soome /// no platform serial device identification information available. 302*f334afcfSToomas Soome /// 303*f334afcfSToomas Soome CONST EFI_GUID *DeviceTypeGuid; // Revision 1.1 304*f334afcfSToomas Soome }; 305*f334afcfSToomas Soome 306*f334afcfSToomas Soome extern EFI_GUID gEfiSerialIoProtocolGuid; 307*f334afcfSToomas Soome extern EFI_GUID gEfiSerialTerminalDeviceTypeGuid; 308*f334afcfSToomas Soome 309*f334afcfSToomas Soome #endif 310