/** @file\r
Definitions and prototypes for DebugPort driver.\r
\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
-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 - 2018, Intel Corporation. All rights reserved.<BR>\r
+SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\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
UINT32 Signature;\r
EFI_HANDLE DriverBindingHandle;\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
+ 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_DEVICE_PATH_PROTOCOL *RemainingDevicePath\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_DEVICE_PATH_PROTOCOL *RemainingDevicePath\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
languages specified in SupportedLanguages. The\r
number of languages supported by a driver is up\r
to the driver writer. Language is specified\r
- in RFC 3066 or ISO 639-2 language code format.\r
+ in RFC 4646 or ISO 639-2 language code format.\r
\r
@param DriverName[out] A pointer to the Unicode string to return.\r
This Unicode string is the name of the\r
languages specified in SupportedLanguages. The\r
number of languages supported by a driver is up\r
to the driver writer. Language is specified in\r
- RFC 3066 or ISO 639-2 language code format.\r
+ RFC 4646 or ISO 639-2 language code format.\r
\r
@param ControllerName[out] A pointer to the Unicode string to return.\r
This Unicode string is the name of the\r
driver specified by This was returned in\r
DriverName.\r
\r
- @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.\r
+ @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.\r
\r
@retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid\r
EFI_HANDLE.\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
+ 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 VOID *Buffer\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
OUT VOID *Buffer\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
projects / mirror_edk2.git / blobdiff