-/*++\r
+/** @file\r
+ Definitions and prototypes for DebugPort driver.\r
\r
-Copyright (c) 2006, Intel Corporation \r
-All rights reserved. This program and the accompanying materials \r
-are licensed and made available under the terms and conditions of the BSD License \r
-which accompanies this distribution. The full text of the license may be found at \r
-http://opensource.org/licenses/bsd-license.php \r
- \r
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
+Copyright (c) 2006 - 2008, Intel Corporation. <BR>\r
+All rights reserved. This program and the accompanying materials\r
+are licensed and made available under the terms and conditions of the BSD License\r
+which accompanies this distribution. The full text of the license may be found at\r
+http://opensource.org/licenses/bsd-license.php\r
\r
-Module Name:\r
- DebugPort.h\r
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
-Abstract:\r
- Definitions and prototypes for DebugPort driver\r
-\r
---*/\r
+**/\r
\r
#ifndef __DEBUGPORT_H__\r
#define __DEBUGPORT_H__\r
//\r
// local type definitions\r
//\r
-#define DEBUGPORT_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('D', 'B', 'G', 'P')\r
+#define DEBUGPORT_DEVICE_SIGNATURE SIGNATURE_32 ('D', 'B', 'G', 'P')\r
\r
//\r
// Device structure used by driver\r
EFI_HANDLE DebugPortDeviceHandle;\r
VOID *DebugPortVariable;\r
\r
- EFI_DRIVER_BINDING_PROTOCOL DriverBindingInterface;\r
- EFI_COMPONENT_NAME_PROTOCOL ComponentNameInterface;\r
EFI_DEVICE_PATH_PROTOCOL *DebugPortDevicePath;\r
EFI_DEBUGPORT_PROTOCOL DebugPortInterface;\r
\r
#define DEBUGPORT_UART_DEFAULT_BAUDRATE 115200\r
#define DEBUGPORT_UART_DEFAULT_PARITY 0\r
#define DEBUGPORT_UART_DEFAULT_FIFO_DEPTH 16\r
-#define DEBUGPORT_UART_DEFAULT_TIMEOUT 50000 // 5 ms\r
+#define DEBUGPORT_UART_DEFAULT_TIMEOUT 50000 ///< 5 ms\r
#define DEBUGPORT_UART_DEFAULT_DATA_BITS 8\r
#define DEBUGPORT_UART_DEFAULT_STOP_BITS 1\r
\r
#define DEBUGPORT_DRIVER_VERSION 1\r
\r
-#define EfiIsUartDevicePath(dp) (DevicePathType (dp) == MESSAGING_DEVICE_PATH && DevicePathSubType (dp) == MSG_UART_DP)\r
+#define IS_UART_DEVICEPATH(dp) (DevicePathType (dp) == MESSAGING_DEVICE_PATH && DevicePathSubType (dp) == MSG_UART_DP)\r
\r
-//\r
-// globals\r
-//\r
-extern DEBUGPORT_DEVICE *gDebugPortDevice;\r
+/**\r
+ Debug Port Driver entry point. \r
\r
-//\r
-// Driver binding interface functions...\r
-//\r
+ Reads DebugPort variable to determine what device and settings to use as the\r
+ debug port. Binds exclusively to SerialIo. Reverts to defaults if no variable\r
+ is found.\r
+\r
+ @param[in] ImageHandle The firmware allocated handle for the EFI image. \r
+ @param[in] SystemTable A pointer to the EFI System Table.\r
+ \r
+ @retval EFI_SUCCESS The entry point is executed successfully.\r
+ @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.\r
+ @retval other Some error occurs when executing this entry point.\r
+\r
+**/\r
EFI_STATUS\r
-DebugPortEntryPoint (\r
+EFIAPI\r
+InitializeDebugPortDriver (\r
IN EFI_HANDLE ImageHandle,\r
IN EFI_SYSTEM_TABLE *SystemTable\r
- )\r
-;\r
+ );\r
+\r
+/**\r
+ Checks to see if there's not already a DebugPort interface somewhere. \r
+\r
+ If there's a DEBUGPORT variable, the device path must match exactly. If there's\r
+ no DEBUGPORT variable, then device path is not checked and does not matter.\r
+ Checks to see that there's a serial io interface on the controller handle\r
+ that can be bound BY_DRIVER | EXCLUSIVE.\r
+ If all these tests succeed, then we return EFI_SUCCESS, else, EFI_UNSUPPORTED\r
+ or other error returned by OpenProtocol.\r
\r
+ @param This Protocol instance pointer.\r
+ @param ControllerHandle Handle of device to test.\r
+ @param RemainingDevicePath Optional parameter use to pick a specific child\r
+ device to start.\r
+\r
+ @retval EFI_SUCCESS This driver supports this device.\r
+ @retval EFI_UNSUPPORTED Debug Port device is not supported.\r
+ @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.\r
+ @retval others Some error occurs.\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
DebugPortSupported (\r
IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
IN EFI_HANDLE Controller,\r
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
- )\r
-;\r
+ );\r
+\r
+/**\r
+ Binds exclusively to serial io on the controller handle, Produces DebugPort\r
+ protocol and DevicePath on new handle.\r
+\r
+ @param This Protocol instance pointer.\r
+ @param ControllerHandle Handle of device to bind driver to.\r
+ @param RemainingDevicePath Optional parameter use to pick a specific child\r
+ device to start.\r
\r
+ @retval EFI_SUCCESS This driver is added to ControllerHandle.\r
+ @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.\r
+ @retval others Some error occurs. \r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
DebugPortStart (\r
IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
IN EFI_HANDLE Controller,\r
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
- )\r
-;\r
+ );\r
+\r
+/**\r
+ Stop this driver on ControllerHandle by removing Serial IO protocol on\r
+ the ControllerHandle.\r
+\r
+ @param This Protocol instance pointer.\r
+ @param ControllerHandle Handle of device to stop driver on\r
+ @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of\r
+ children is zero stop the entire bus driver.\r
+ @param ChildHandleBuffer List of Child Handles to Stop.\r
+\r
+ @retval EFI_SUCCESS This driver is removed ControllerHandle.\r
+ @retval other This driver was not removed from this device.\r
\r
+**/\r
EFI_STATUS\r
EFIAPI\r
DebugPortStop (\r
IN EFI_HANDLE Controller,\r
IN UINTN NumberOfChildren,\r
IN EFI_HANDLE *ChildHandleBuffer\r
- )\r
-;\r
+ );\r
\r
//\r
// EFI Component Name Functions\r
);\r
\r
\r
-//\r
-// DebugPort member functions\r
-//\r
+/**\r
+ DebugPort protocol member function. Calls SerialIo:GetControl to flush buffer.\r
+ We cannot call SerialIo:SetAttributes because it uses pool services, which use\r
+ locks, which affect TPL, so it's not interrupt context safe or re-entrant.\r
+ SerialIo:Reset() calls SetAttributes, so it can't be used either.\r
+\r
+ The port itself should be fine since it was set up during initialization.\r
+\r
+ @param This Protocol instance pointer. \r
+\r
+ @return EFI_SUCCESS Always.\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
DebugPortReset (\r
IN EFI_DEBUGPORT_PROTOCOL *This\r
- )\r
-;\r
+ );\r
+\r
+/**\r
+ DebugPort protocol member function. Calls SerialIo:Read() after setting\r
+ if it's different than the last SerialIo access.\r
+\r
+ @param This Pointer to DebugPort protocol.\r
+ @param Timeout Timeout value.\r
+ @param BufferSize On input, the size of Buffer.\r
+ On output, the amount of data actually written.\r
+ @param Buffer Pointer to buffer to read.\r
\r
+ @retval EFI_SUCCESS \r
+ @retval others \r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
DebugPortRead (\r
IN UINT32 Timeout,\r
IN OUT UINTN *BufferSize,\r
IN VOID *Buffer\r
- )\r
-;\r
+ );\r
+\r
+/**\r
+ DebugPort protocol member function. Calls SerialIo:Write() Writes 8 bytes at\r
+ a time and does a GetControl between 8 byte writes to help insure reads are\r
+ interspersed This is poor-man's flow control.\r
+\r
+ @param This Pointer to DebugPort protocol.\r
+ @param Timeout Timeout value.\r
+ @param BufferSize On input, the size of Buffer.\r
+ On output, the amount of data actually written.\r
+ @param Buffer Pointer to buffer to read.\r
+\r
+ @retval EFI_SUCCESS The data was written.\r
+ @retval others Fails when writting datas to debug port device.\r
\r
+**/\r
EFI_STATUS\r
EFIAPI\r
DebugPortWrite (\r
IN UINT32 Timeout,\r
IN OUT UINTN *BufferSize,\r
OUT VOID *Buffer\r
- )\r
-;\r
+ );\r
+\r
+/**\r
+ DebugPort protocol member function. Calls SerialIo:Write() after setting\r
+ if it's different than the last SerialIo access.\r
\r
+ @param This Pointer to DebugPort protocol.\r
+\r
+ @retval EFI_SUCCESS At least 1 character is ready to be read from\r
+ the DebugPort interface.\r
+ @retval EFI_NOT_READY There are no characters ready to read from the\r
+ DebugPort interface\r
+ @retval EFI_DEVICE_ERROR A hardware failure occured... (from SerialIo)\r
+\r
+**/ \r
EFI_STATUS\r
EFIAPI\r
DebugPortPoll (\r
IN EFI_DEBUGPORT_PROTOCOL *This\r
- )\r
-;\r
+ );\r
\r
#endif\r
projects / mirror_edk2.git / blobdiff