\r
**/\r
\r
-\r
#include "DebugPort.h"\r
\r
//\r
-// Misc. functions local to this module..\r
+// Globals\r
//\r
-VOID\r
-GetDebugPortVariable (\r
- DEBUGPORT_DEVICE *DebugPortDevice\r
- )\r
-/*++\r
-\r
-Routine Description:\r
- Local worker function to obtain device path information from DebugPort variable.\r
- Records requested settings in DebugPort device structure.\r
+EFI_DRIVER_BINDING_PROTOCOL gDebugPortDriverBinding = {\r
+ DebugPortSupported,\r
+ DebugPortStart,\r
+ DebugPortStop,\r
+ DEBUGPORT_DRIVER_VERSION,\r
+ NULL,\r
+ NULL\r
+};\r
\r
-Arguments:\r
- DEBUGPORT_DEVICE *DebugPortDevice,\r
+DEBUGPORT_DEVICE *gDebugPortDevice;\r
\r
-Returns:\r
+/**\r
+ Local worker function to obtain device path information from DebugPort variable.\r
\r
- Nothing\r
+ Records requested settings in DebugPort device structure.\r
+ \r
+ @param DebugPortDevice Pointer to instance of dubug port device.\r
\r
---*/\r
+**/\r
+VOID\r
+GetDebugPortVariable (\r
+ DEBUGPORT_DEVICE *DebugPortDevice\r
+ )\r
{\r
UINTN DataSize;\r
EFI_DEVICE_PATH_PROTOCOL *DevicePath;\r
DebugPortDevice->DebugPortVariable\r
);\r
DevicePath = (EFI_DEVICE_PATH_PROTOCOL *) DebugPortDevice->DebugPortVariable;\r
- while (!EfiIsDevicePathEnd (DevicePath) && !EfiIsUartDevicePath (DevicePath)) {\r
+ while (!EfiIsDevicePathEnd (DevicePath) && !IS_UART_DEVICEPATH (DevicePath)) {\r
DevicePath = EfiNextDevicePathNode (DevicePath);\r
}\r
\r
}\r
}\r
\r
+\r
//\r
-// Globals\r
+// implementation code\r
//\r
\r
-EFI_DRIVER_BINDING_PROTOCOL gDebugPortDriverBinding = {\r
- DebugPortSupported,\r
- DebugPortStart,\r
- DebugPortStop,\r
- DEBUGPORT_DRIVER_VERSION,\r
- NULL,\r
- NULL\r
-};\r
+/**\r
+ Debug Port Driver entry pointo. \r
\r
-DEBUGPORT_DEVICE *gDebugPortDevice;\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
-//\r
-// implementation code\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
EFIAPI\r
InitializeDebugPortDriver (\r
IN EFI_HANDLE ImageHandle,\r
IN EFI_SYSTEM_TABLE *SystemTable\r
)\r
-/*++\r
-\r
-Routine Description:\r
- Driver entry point. Reads DebugPort variable to determine what device and settings\r
- to use as the debug port. Binds exclusively to SerialIo. Reverts to defaults \\r
- if no variable is found.\r
-\r
- Creates debugport and devicepath protocols on new handle.\r
-\r
-Arguments:\r
- ImageHandle,\r
- SystemTable\r
-\r
-Returns:\r
-\r
- EFI_UNSUPPORTED\r
- EFI_OUT_OF_RESOURCES\r
-\r
---*/\r
{\r
EFI_STATUS Status;\r
\r
\r
return EFI_SUCCESS;\r
}\r
-//\r
-// DebugPort driver binding member functions...\r
-//\r
-EFI_STATUS\r
-EFIAPI\r
-DebugPortSupported (\r
- IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
- IN EFI_HANDLE ControllerHandle,\r
- IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
- )\r
-/*++\r
\r
-Routine Description:\r
- Checks to see that there's not already a DebugPort interface somewhere. If so,\r
- fail.\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
-\r
Checks to see that there's a serial io interface on the controller handle\r
that can be bound BY_DRIVER | EXCLUSIVE.\r
-\r
If all these tests succeed, then we return EFI_SUCCESS, else, EFI_UNSUPPORTED\r
or other error returned by OpenProtocol.\r
\r
-Arguments:\r
- This\r
- ControllerHandle\r
- RemainingDevicePath\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
-Returns:\r
- EFI_UNSUPPORTED\r
- EFI_OUT_OF_RESOURCES\r
- EFI_SUCCESS\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
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+DebugPortSupported (\r
+ IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
+ IN EFI_HANDLE ControllerHandle,\r
+ IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
+ )\r
{\r
EFI_STATUS Status;\r
EFI_DEVICE_PATH_PROTOCOL *Dp1;\r
return EFI_SUCCESS;\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_HANDLE ControllerHandle,\r
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
)\r
-/*++\r
-\r
-Routine Description:\r
- Binds exclusively to serial io on the controller handle. Produces DebugPort\r
- protocol and DevicePath on new handle.\r
-\r
-Arguments:\r
- This\r
- ControllerHandle\r
- RemainingDevicePath\r
-\r
-Returns:\r
- EFI_OUT_OF_RESOURCES\r
- EFI_SUCCESS\r
---*/\r
{\r
EFI_STATUS Status;\r
DEBUGPORT_DEVICE_PATH DebugPortDP;\r
return EFI_SUCCESS;\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 UINTN NumberOfChildren,\r
IN EFI_HANDLE *ChildHandleBuffer\r
)\r
-/*++\r
-\r
-Routine Description:\r
- We're never intending to be stopped via the driver model so this just returns\r
- EFI_UNSUPPORTED\r
-\r
-Arguments:\r
- Per UEFI 2.0 driver model\r
-\r
-Returns:\r
- EFI_UNSUPPORTED\r
- EFI_SUCCESS\r
-\r
---*/\r
{\r
EFI_STATUS Status;\r
\r
\r
return Status;\r
}\r
-//\r
-// Debugport protocol member functions\r
-//\r
-EFI_STATUS\r
-EFIAPI\r
-DebugPortReset (\r
- IN EFI_DEBUGPORT_PROTOCOL *This\r
- )\r
-/*++\r
\r
-Routine Description:\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
\r
The port itself should be fine since it was set up during initialization.\r
\r
-Arguments:\r
- This\r
-\r
-Returns:\r
+ @param This Protocol instance pointer. \r
\r
- EFI_SUCCESS\r
+ @return EFI_SUCCESS Always.\r
\r
---*/\r
+**/ \r
+EFI_STATUS\r
+EFIAPI\r
+DebugPortReset (\r
+ IN EFI_DEBUGPORT_PROTOCOL *This\r
+ )\r
{\r
UINTN BufferSize;\r
UINTN BitBucket;\r
return EFI_SUCCESS;\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 OUT UINTN *BufferSize,\r
IN VOID *Buffer\r
)\r
-/*++\r
-\r
-Routine Description:\r
- DebugPort protocol member function. Calls SerialIo:Read() after setting\r
- if it's different than the last SerialIo access.\r
-\r
-Arguments:\r
- IN EFI_DEBUGPORT_PROTOCOL *This\r
- IN UINT32 Timeout,\r
- IN OUT UINTN *BufferSize,\r
- IN VOID *Buffer\r
-\r
-Returns:\r
-\r
- EFI_STATUS\r
-\r
---*/\r
{\r
DEBUGPORT_DEVICE *DebugPortDevice;\r
UINTN LocalBufferSize;\r
return Status;\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 OUT UINTN *BufferSize,\r
OUT VOID *Buffer\r
)\r
-/*++\r
-\r
-Routine Description:\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
-Arguments:\r
- This - Pointer to DebugPort protocol\r
- Timeout - Timeout value\r
- BufferSize - On input, the size of Buffer.\r
- On output, the amount of data actually written.\r
- Buffer - Pointer to buffer to write\r
-\r
-Returns:\r
- EFI_SUCCESS - The data was written.\r
- EFI_DEVICE_ERROR - The device reported an error.\r
- EFI_TIMEOUT - The data write was stopped due to a timeout.\r
-\r
---*/\r
{\r
DEBUGPORT_DEVICE *DebugPortDevice;\r
UINTN Position;\r
return Status;\r
}\r
\r
-EFI_STATUS\r
-EFIAPI\r
-DebugPortPoll (\r
- IN EFI_DEBUGPORT_PROTOCOL *This\r
- )\r
-/*++\r
-\r
-Routine Description:\r
+/**\r
DebugPort protocol member function. Calls SerialIo:Write() after setting\r
if it's different than the last SerialIo access.\r
\r
-Arguments:\r
- IN EFI_DEBUGPORT_PROTOCOL *This\r
+ @param This Pointer to DebugPort protocol.\r
\r
-Returns:\r
- EFI_SUCCESS - At least 1 character is ready to be read from the DebugPort interface\r
- EFI_NOT_READY - There are no characters ready to read from the DebugPort interface\r
- EFI_DEVICE_ERROR - A hardware failure occured... (from SerialIo)\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
+**/ \r
+EFI_STATUS\r
+EFIAPI\r
+DebugPortPoll (\r
+ IN EFI_DEBUGPORT_PROTOCOL *This\r
+ )\r
{\r
EFI_STATUS Status;\r
UINT32 SerialControl;\r
);\r
\r
if (!EFI_ERROR (Status)) {\r
- if (SerialControl & EFI_SERIAL_INPUT_BUFFER_EMPTY) {\r
+ if ((SerialControl & EFI_SERIAL_INPUT_BUFFER_EMPTY) != 0) {\r
Status = EFI_NOT_READY;\r
} else {\r
Status = EFI_SUCCESS;\r
return Status;\r
}\r
\r
-EFI_STATUS\r
-EFIAPI\r
-ImageUnloadHandler (\r
- EFI_HANDLE ImageHandle\r
- )\r
-/*++\r
-\r
-Routine Description:\r
+/**\r
Unload function that is registered in the LoadImage protocol. It un-installs\r
protocols produced and deallocates pool used by the driver. Called by the core\r
when unloading the driver.\r
\r
-Arguments:\r
- EFI_HANDLE ImageHandle\r
-\r
-Returns:\r
+ @param ImageHandle\r
\r
- EFI_SUCCESS\r
+ @retval EFI_SUCCESS Unload Debug Port driver successfully.\r
+ @retval EFI_ABORTED Serial IO is still binding.\r
+ @retval others Fails to unload Debug Port driver.\r
\r
---*/\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+ImageUnloadHandler (\r
+ EFI_HANDLE ImageHandle\r
+ )\r
{\r
EFI_STATUS Status;\r
\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
-//\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
projects / mirror_edk2.git / commitdiff