\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
-//\r
-// Driver binding interface functions...\r
-//\r
+/**\r
+ Debug Port Driver entry pointo. \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
);\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