X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=MdePkg%2FInclude%2FProtocol%2FSerialIo.h;h=e2e0c61eeb0a9b4b7efc4dfbe4877d98f826756b;hb=7e9cef643d507e5ce40aa4b71fdb25d7fa051130;hp=59da19fbcfc51e411125efd6200bea4523f157ba;hpb=842f5579c7e2a313f56c576e4c5150f7f4793079;p=mirror_edk2.git diff --git a/MdePkg/Include/Protocol/SerialIo.h b/MdePkg/Include/Protocol/SerialIo.h index 59da19fbcf..e2e0c61eeb 100644 --- a/MdePkg/Include/Protocol/SerialIo.h +++ b/MdePkg/Include/Protocol/SerialIo.h @@ -1,17 +1,11 @@ /** @file - Serial IO protocol as defined in the EFI 1.0 specification. + Serial IO protocol as defined in the UEFI 2.0 specification. Abstraction of a basic serial device. Targeted at 16550 UART, but could be much more generic. - Copyright (c) 2006, Intel Corporation - All rights reserved. This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.
+ SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -23,22 +17,23 @@ 0xBB25CF6F, 0xF1D4, 0x11D2, {0x9A, 0x0C, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0xFD } \ } -// -// Protocol GUID defined in EFI1.1. -// +/// +/// Protocol GUID defined in EFI1.1. +/// #define SERIAL_IO_PROTOCOL EFI_SERIAL_IO_PROTOCOL_GUID typedef struct _EFI_SERIAL_IO_PROTOCOL EFI_SERIAL_IO_PROTOCOL; -// -// Backward-compatible with EFI1.1. -// +/// +/// Backward-compatible with EFI1.1. +/// typedef EFI_SERIAL_IO_PROTOCOL SERIAL_IO_INTERFACE; -// -// Serial IO Data structures -// +/// +/// Parity type that is computed or checked as each character is transmitted or received. If the +/// device does not support parity, the value is the default parity value. +/// typedef enum { DefaultParity, NoParity, @@ -48,6 +43,9 @@ typedef enum { SpaceParity } EFI_PARITY_TYPE; +/// +/// Stop bits type +/// typedef enum { DefaultStopBits, OneStopBit, @@ -88,28 +86,27 @@ typedef enum { Reset the serial device. @param This Protocol instance pointer. - + @retval EFI_SUCCESS The device was reset. @retval EFI_DEVICE_ERROR The serial device could not be reset. **/ typedef EFI_STATUS -(EFIAPI *EFI_SERIAL_RESET) ( +(EFIAPI *EFI_SERIAL_RESET)( IN EFI_SERIAL_IO_PROTOCOL *This - ) -; + ); /** - Sets the baud rate, receive FIFO depth, transmit/receice time out, parity, - data buts, and stop bits on a serial device. + Sets the baud rate, receive FIFO depth, transmit/receice time out, parity, + data bits, and stop bits on a serial device. @param This Protocol instance pointer. - @param BaudRate The requested baud rate. A BaudRate value of 0 will use the the + @param BaudRate The requested baud rate. A BaudRate value of 0 will use the device's default interface speed. @param ReveiveFifoDepth The requested depth of the FIFO on the receive side of the serial interface. A ReceiveFifoDepth value of 0 will use - the device's dfault FIFO depth. + the device's default FIFO depth. @param 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 @@ -122,13 +119,14 @@ EFI_STATUS value of DefaultStopBits will use the device's default number of stop bits. - @retval EFI_SUCCESS The device was reset. - @retval EFI_DEVICE_ERROR The serial device could not be reset. + @retval EFI_SUCCESS The device was reset. + @retval EFI_INVALID_PARAMETER One or more attributes has an unsupported value. + @retval EFI_DEVICE_ERROR The serial device is not functioning correctly. **/ typedef EFI_STATUS -(EFIAPI *EFI_SERIAL_SET_ATTRIBUTES) ( +(EFIAPI *EFI_SERIAL_SET_ATTRIBUTES)( IN EFI_SERIAL_IO_PROTOCOL *This, IN UINT64 BaudRate, IN UINT32 ReceiveFifoDepth, @@ -136,8 +134,7 @@ EFI_STATUS IN EFI_PARITY_TYPE Parity, IN UINT8 DataBits, IN EFI_STOP_BITS_TYPE StopBits - ) -; + ); /** Set the control bits on a serial device @@ -152,29 +149,27 @@ EFI_STATUS **/ typedef EFI_STATUS -(EFIAPI *EFI_SERIAL_SET_CONTROL_BITS) ( +(EFIAPI *EFI_SERIAL_SET_CONTROL_BITS)( IN EFI_SERIAL_IO_PROTOCOL *This, IN UINT32 Control - ) -; + ); /** Retrieves the status of thecontrol bits on a serial device @param This Protocol instance pointer. @param Control A pointer to return the current Control signals from the serial device. - + @retval EFI_SUCCESS The control bits were read from the serial device. @retval EFI_DEVICE_ERROR The serial device is not functioning correctly. **/ typedef EFI_STATUS -(EFIAPI *EFI_SERIAL_GET_CONTROL_BITS) ( +(EFIAPI *EFI_SERIAL_GET_CONTROL_BITS)( IN EFI_SERIAL_IO_PROTOCOL *This, OUT UINT32 *Control - ) -; + ); /** Writes data to a serial device. @@ -191,12 +186,11 @@ EFI_STATUS **/ typedef EFI_STATUS -(EFIAPI *EFI_SERIAL_WRITE) ( +(EFIAPI *EFI_SERIAL_WRITE)( IN EFI_SERIAL_IO_PROTOCOL *This, IN OUT UINTN *BufferSize, IN VOID *Buffer - ) -; + ); /** Writes data to a serial device. @@ -213,30 +207,43 @@ EFI_STATUS **/ typedef EFI_STATUS -(EFIAPI *EFI_SERIAL_READ) ( +(EFIAPI *EFI_SERIAL_READ)( IN EFI_SERIAL_IO_PROTOCOL *This, IN OUT UINTN *BufferSize, OUT VOID *Buffer - ) -; + ); /** - The data values in SERIAL_IO_MODE are read-only and are updated by the code + @par Data Structure Description: + The data values in SERIAL_IO_MODE are read-only and are updated by the code that produces the SERIAL_IO_PROTOCOL member functions. - ControlMask - A mask fo the Control bits that the device supports. The device + @param ControlMask + A mask for the Control bits that the device supports. The device must always support the Input Buffer Empty control bit. - TimeOut - If applicable, the number of microseconds to wait before timing out + + @param TimeOut + If applicable, the number of microseconds to wait before timing out a Read or Write operation. - BaudRate - If applicable, the current baud rate setting of the device; otherwise, + + @param BaudRate + If applicable, the current baud rate setting of the device; otherwise, baud rate has the value of zero to indicate that device runs at the device's designed speed. - ReceiveFifoDepth - The number of characters the device will buffer on input - DataBits - The number of characters the device will buffer on input - Parity - If applicable, this is the EFI_PARITY_TYPE that is computed or + + @param ReceiveFifoDepth + The number of characters the device will buffer on input + + @param DataBits + The number of characters the device will buffer on input + + @param Parity + If applicable, this is the EFI_PARITY_TYPE that is computed or checked as each character is transmitted or reveived. If the device does not support parity the value is the default parity value. - StopBits - If applicable, the EFI_STOP_BITS_TYPE number of stop bits per + + @param StopBits + If applicable, the EFI_STOP_BITS_TYPE number of stop bits per character. If the device does not support stop bits the value is the default stop bit values. @@ -256,9 +263,20 @@ typedef struct { } EFI_SERIAL_IO_MODE; #define EFI_SERIAL_IO_PROTOCOL_REVISION 0x00010000 +#define EFI_SERIAL_IO_PROTOCOL_REVISION1p1 0x00010001 #define SERIAL_IO_INTERFACE_REVISION EFI_SERIAL_IO_PROTOCOL_REVISION +/// +/// 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. +/// struct _EFI_SERIAL_IO_PROTOCOL { + /// + /// The revision to which the EFI_SERIAL_IO_PROTOCOL adheres. All future revisions + /// must be backwards compatible. If a future version is not backwards compatible, + /// it is not the same GUID. + /// UINT32 Revision; EFI_SERIAL_RESET Reset; EFI_SERIAL_SET_ATTRIBUTES SetAttributes; @@ -266,8 +284,18 @@ struct _EFI_SERIAL_IO_PROTOCOL { EFI_SERIAL_GET_CONTROL_BITS GetControl; EFI_SERIAL_WRITE Write; EFI_SERIAL_READ Read; - + /// + /// Pointer to SERIAL_IO_MODE data. + /// EFI_SERIAL_IO_MODE *Mode; + /// + /// Pointer to a GUID identifying the device connected to the serial port. + /// This field is NULL when the protocol is installed by the serial port + /// driver and may be populated by a platform driver for a serial port + /// with a known device attached. The field will remain NULL if there is + /// no platform serial device identification information available. + /// + CONST EFI_GUID *DeviceTypeGuid; // Revision 1.1 }; extern EFI_GUID gEfiSerialIoProtocolGuid;