X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=MdeModulePkg%2FUniversal%2FDebugPortDxe%2FDebugPort.h;h=852cae94815ac7afe88b73983f5927c0eca27147;hb=49c8b87c66e8034d935ed11673dd8a230e43440a;hp=de2fd4e50bd0d4c3794a89fbdd302f930da751c8;hpb=19f97f7e860b65f638777845b65b458659c7eb66;p=mirror_edk2.git diff --git a/MdeModulePkg/Universal/DebugPortDxe/DebugPort.h b/MdeModulePkg/Universal/DebugPortDxe/DebugPort.h index de2fd4e50b..852cae9481 100644 --- a/MdeModulePkg/Universal/DebugPortDxe/DebugPort.h +++ b/MdeModulePkg/Universal/DebugPortDxe/DebugPort.h @@ -1,21 +1,16 @@ -/*++ +/** @file + Definitions and prototypes for DebugPort driver. -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 - 2008, 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 -Module Name: - DebugPort.h +THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, +WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Abstract: - Definitions and prototypes for DebugPort driver - ---*/ +**/ #ifndef __DEBUGPORT_H__ #define __DEBUGPORT_H__ @@ -88,41 +83,100 @@ typedef struct { #define DEBUGPORT_DRIVER_VERSION 1 -#define EfiIsUartDevicePath(dp) (DevicePathType (dp) == MESSAGING_DEVICE_PATH && DevicePathSubType (dp) == MSG_UART_DP) +#define IS_UART_DEVICEPATH(dp) (DevicePathType (dp) == MESSAGING_DEVICE_PATH && DevicePathSubType (dp) == MSG_UART_DP) // // globals // extern DEBUGPORT_DEVICE *gDebugPortDevice; -// -// Driver binding interface functions... -// +/** + Debug Port Driver entry pointo. + + Reads DebugPort variable to determine what device and settings to use as the + debug port. Binds exclusively to SerialIo. Reverts to defaults if no variable + is found. + + @param[in] ImageHandle The firmware allocated handle for the EFI image. + @param[in] SystemTable A pointer to the EFI System Table. + + @retval EFI_SUCCESS The entry point is executed successfully. + @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device. + @retval other Some error occurs when executing this entry point. + +**/ EFI_STATUS -DebugPortEntryPoint ( +EFIAPI +InitializeDebugPortDriver ( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable - ) -; + ); + +/** + Checks to see if there's not already a DebugPort interface somewhere. + + If there's a DEBUGPORT variable, the device path must match exactly. If there's + no DEBUGPORT variable, then device path is not checked and does not matter. + Checks to see that there's a serial io interface on the controller handle + that can be bound BY_DRIVER | EXCLUSIVE. + If all these tests succeed, then we return EFI_SUCCESS, else, EFI_UNSUPPORTED + or other error returned by OpenProtocol. + @param This Protocol instance pointer. + @param ControllerHandle Handle of device to test. + @param RemainingDevicePath Optional parameter use to pick a specific child + device to start. + + @retval EFI_SUCCESS This driver supports this device. + @retval EFI_UNSUPPORTED Debug Port device is not supported. + @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device. + @retval others Some error occurs. + +**/ EFI_STATUS EFIAPI DebugPortSupported ( IN EFI_DRIVER_BINDING_PROTOCOL *This, IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath - ) -; + ); + +/** + Binds exclusively to serial io on the controller handle, Produces DebugPort + protocol and DevicePath on new handle. + + @param This Protocol instance pointer. + @param ControllerHandle Handle of device to bind driver to. + @param RemainingDevicePath Optional parameter use to pick a specific child + device to start. + @retval EFI_SUCCESS This driver is added to ControllerHandle. + @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device. + @retval others Some error occurs. + +**/ EFI_STATUS EFIAPI DebugPortStart ( IN EFI_DRIVER_BINDING_PROTOCOL *This, IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath - ) -; + ); + +/** + Stop this driver on ControllerHandle by removing Serial IO protocol on + the ControllerHandle. + + @param This Protocol instance pointer. + @param ControllerHandle Handle of device to stop driver on + @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of + children is zero stop the entire bus driver. + @param ChildHandleBuffer List of Child Handles to Stop. + + @retval EFI_SUCCESS This driver is removed ControllerHandle. + @retval other This driver was not removed from this device. +**/ EFI_STATUS EFIAPI DebugPortStop ( @@ -130,8 +184,7 @@ DebugPortStop ( IN EFI_HANDLE Controller, IN UINTN NumberOfChildren, IN EFI_HANDLE *ChildHandleBuffer - ) -; + ); // // EFI Component Name Functions @@ -263,16 +316,39 @@ DebugPortComponentNameGetControllerName ( ); -// -// DebugPort member functions -// +/** + DebugPort protocol member function. Calls SerialIo:GetControl to flush buffer. + We cannot call SerialIo:SetAttributes because it uses pool services, which use + locks, which affect TPL, so it's not interrupt context safe or re-entrant. + SerialIo:Reset() calls SetAttributes, so it can't be used either. + + The port itself should be fine since it was set up during initialization. + + @param This Protocol instance pointer. + + @return EFI_SUCCESS Always. + +**/ EFI_STATUS EFIAPI DebugPortReset ( IN EFI_DEBUGPORT_PROTOCOL *This - ) -; + ); + +/** + DebugPort protocol member function. Calls SerialIo:Read() after setting + if it's different than the last SerialIo access. + + @param This Pointer to DebugPort protocol. + @param Timeout Timeout value. + @param BufferSize On input, the size of Buffer. + On output, the amount of data actually written. + @param Buffer Pointer to buffer to read. + @retval EFI_SUCCESS + @retval others + +**/ EFI_STATUS EFIAPI DebugPortRead ( @@ -280,9 +356,23 @@ DebugPortRead ( IN UINT32 Timeout, IN OUT UINTN *BufferSize, IN VOID *Buffer - ) -; + ); + +/** + DebugPort protocol member function. Calls SerialIo:Write() Writes 8 bytes at + a time and does a GetControl between 8 byte writes to help insure reads are + interspersed This is poor-man's flow control. + + @param This Pointer to DebugPort protocol. + @param Timeout Timeout value. + @param BufferSize On input, the size of Buffer. + On output, the amount of data actually written. + @param Buffer Pointer to buffer to read. + + @retval EFI_SUCCESS The data was written. + @retval others Fails when writting datas to debug port device. +**/ EFI_STATUS EFIAPI DebugPortWrite ( @@ -290,14 +380,25 @@ DebugPortWrite ( IN UINT32 Timeout, IN OUT UINTN *BufferSize, OUT VOID *Buffer - ) -; + ); + +/** + DebugPort protocol member function. Calls SerialIo:Write() after setting + if it's different than the last SerialIo access. + @param This Pointer to DebugPort protocol. + + @retval EFI_SUCCESS At least 1 character is ready to be read from + the DebugPort interface. + @retval EFI_NOT_READY There are no characters ready to read from the + DebugPort interface + @retval EFI_DEVICE_ERROR A hardware failure occured... (from SerialIo) + +**/ EFI_STATUS EFIAPI DebugPortPoll ( IN EFI_DEBUGPORT_PROTOCOL *This - ) -; + ); #endif