2 Definitions and prototypes for DebugPort driver.
4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
9 #ifndef __DEBUGPORT_H__
10 #define __DEBUGPORT_H__
15 #include <Protocol/DevicePath.h>
16 #include <Protocol/ComponentName.h>
17 #include <Protocol/DriverBinding.h>
18 #include <Protocol/SerialIo.h>
19 #include <Protocol/DebugPort.h>
21 #include <Library/DebugLib.h>
22 #include <Library/UefiDriverEntryPoint.h>
23 #include <Library/UefiLib.h>
24 #include <Library/BaseMemoryLib.h>
25 #include <Library/MemoryAllocationLib.h>
26 #include <Library/UefiBootServicesTableLib.h>
27 #include <Library/UefiRuntimeServicesTableLib.h>
28 #include <Library/DevicePathLib.h>
31 // Driver Binding Externs
33 extern EFI_DRIVER_BINDING_PROTOCOL gDebugPortDriverBinding
;
34 extern EFI_COMPONENT_NAME_PROTOCOL gDebugPortComponentName
;
35 extern EFI_COMPONENT_NAME2_PROTOCOL gDebugPortComponentName2
;
38 // local type definitions
40 #define DEBUGPORT_DEVICE_SIGNATURE SIGNATURE_32 ('D', 'B', 'G', 'P')
43 // Device structure used by driver
47 EFI_HANDLE DriverBindingHandle
;
48 EFI_HANDLE DebugPortDeviceHandle
;
50 EFI_DEVICE_PATH_PROTOCOL
*DebugPortDevicePath
;
51 EFI_DEBUGPORT_PROTOCOL DebugPortInterface
;
53 EFI_HANDLE SerialIoDeviceHandle
;
54 EFI_SERIAL_IO_PROTOCOL
*SerialIoBinding
;
56 UINT32 ReceiveFifoDepth
;
58 EFI_PARITY_TYPE Parity
;
60 EFI_STOP_BITS_TYPE StopBits
;
63 #define DEBUGPORT_DEVICE_FROM_THIS(a) CR (a, DEBUGPORT_DEVICE, DebugPortInterface, DEBUGPORT_DEVICE_SIGNATURE)
65 #define EFI_ACPI_PC_COMPORT_HID EISA_PNP_ID (0x0500)
66 #define EFI_ACPI_16550UART_HID EISA_PNP_ID (0x0501)
68 #define DEBUGPORT_UART_DEFAULT_BAUDRATE 115200
69 #define DEBUGPORT_UART_DEFAULT_PARITY 0
70 #define DEBUGPORT_UART_DEFAULT_FIFO_DEPTH 16
71 #define DEBUGPORT_UART_DEFAULT_TIMEOUT 50000 ///< 5 ms
72 #define DEBUGPORT_UART_DEFAULT_DATA_BITS 8
73 #define DEBUGPORT_UART_DEFAULT_STOP_BITS 1
75 #define DEBUGPORT_DRIVER_VERSION 1
77 #define IS_UART_DEVICEPATH(dp) (DevicePathType (dp) == MESSAGING_DEVICE_PATH && DevicePathSubType (dp) == MSG_UART_DP)
80 Debug Port Driver entry point.
82 Reads DebugPort variable to determine what device and settings to use as the
83 debug port. Binds exclusively to SerialIo. Reverts to defaults if no variable
86 @param[in] ImageHandle The firmware allocated handle for the EFI image.
87 @param[in] SystemTable A pointer to the EFI System Table.
89 @retval EFI_SUCCESS The entry point is executed successfully.
90 @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.
91 @retval other Some error occurs when executing this entry point.
96 InitializeDebugPortDriver (
97 IN EFI_HANDLE ImageHandle
,
98 IN EFI_SYSTEM_TABLE
*SystemTable
102 Checks to see if there's not already a DebugPort interface somewhere.
104 If there's a DEBUGPORT variable, the device path must match exactly. If there's
105 no DEBUGPORT variable, then device path is not checked and does not matter.
106 Checks to see that there's a serial io interface on the controller handle
107 that can be bound BY_DRIVER | EXCLUSIVE.
108 If all these tests succeed, then we return EFI_SUCCESS, else, EFI_UNSUPPORTED
109 or other error returned by OpenProtocol.
111 @param This Protocol instance pointer.
112 @param ControllerHandle Handle of device to test.
113 @param RemainingDevicePath Optional parameter use to pick a specific child
116 @retval EFI_SUCCESS This driver supports this device.
117 @retval EFI_UNSUPPORTED Debug Port device is not supported.
118 @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.
119 @retval others Some error occurs.
125 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
126 IN EFI_HANDLE Controller
,
127 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
131 Binds exclusively to serial io on the controller handle, Produces DebugPort
132 protocol and DevicePath on new handle.
134 @param This Protocol instance pointer.
135 @param ControllerHandle Handle of device to bind driver to.
136 @param RemainingDevicePath Optional parameter use to pick a specific child
139 @retval EFI_SUCCESS This driver is added to ControllerHandle.
140 @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.
141 @retval others Some error occurs.
147 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
148 IN EFI_HANDLE Controller
,
149 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
153 Stop this driver on ControllerHandle by removing Serial IO protocol on
154 the ControllerHandle.
156 @param This Protocol instance pointer.
157 @param ControllerHandle Handle of device to stop driver on
158 @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of
159 children is zero stop the entire bus driver.
160 @param ChildHandleBuffer List of Child Handles to Stop.
162 @retval EFI_SUCCESS This driver is removed ControllerHandle.
163 @retval other This driver was not removed from this device.
169 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
170 IN EFI_HANDLE Controller
,
171 IN UINTN NumberOfChildren
,
172 IN EFI_HANDLE
*ChildHandleBuffer
176 // EFI Component Name Functions
179 Retrieves a Unicode string that is the user readable name of the driver.
181 This function retrieves the user readable name of a driver in the form of a
182 Unicode string. If the driver specified by This has a user readable name in
183 the language specified by Language, then a pointer to the driver name is
184 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
185 by This does not support the language specified by Language,
186 then EFI_UNSUPPORTED is returned.
188 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
189 EFI_COMPONENT_NAME_PROTOCOL instance.
191 @param Language[in] A pointer to a Null-terminated ASCII string
192 array indicating the language. This is the
193 language of the driver name that the caller is
194 requesting, and it must match one of the
195 languages specified in SupportedLanguages. The
196 number of languages supported by a driver is up
197 to the driver writer. Language is specified
198 in RFC 4646 or ISO 639-2 language code format.
200 @param DriverName[out] A pointer to the Unicode string to return.
201 This Unicode string is the name of the
202 driver specified by This in the language
203 specified by Language.
205 @retval EFI_SUCCESS The Unicode string for the Driver specified by
206 This and the language specified by Language was
207 returned in DriverName.
209 @retval EFI_INVALID_PARAMETER Language is NULL.
211 @retval EFI_INVALID_PARAMETER DriverName is NULL.
213 @retval EFI_UNSUPPORTED The driver specified by This does not support
214 the language specified by Language.
219 DebugPortComponentNameGetDriverName (
220 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
222 OUT CHAR16
**DriverName
227 Retrieves a Unicode string that is the user readable name of the controller
228 that is being managed by a driver.
230 This function retrieves the user readable name of the controller specified by
231 ControllerHandle and ChildHandle in the form of a Unicode string. If the
232 driver specified by This has a user readable name in the language specified by
233 Language, then a pointer to the controller name is returned in ControllerName,
234 and EFI_SUCCESS is returned. If the driver specified by This is not currently
235 managing the controller specified by ControllerHandle and ChildHandle,
236 then EFI_UNSUPPORTED is returned. If the driver specified by This does not
237 support the language specified by Language, then EFI_UNSUPPORTED is returned.
239 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
240 EFI_COMPONENT_NAME_PROTOCOL instance.
242 @param ControllerHandle[in] The handle of a controller that the driver
243 specified by This is managing. This handle
244 specifies the controller whose name is to be
247 @param ChildHandle[in] The handle of the child controller to retrieve
248 the name of. This is an optional parameter that
249 may be NULL. It will be NULL for device
250 drivers. It will also be NULL for a bus drivers
251 that wish to retrieve the name of the bus
252 controller. It will not be NULL for a bus
253 driver that wishes to retrieve the name of a
256 @param Language[in] A pointer to a Null-terminated ASCII string
257 array indicating the language. This is the
258 language of the driver name that the caller is
259 requesting, and it must match one of the
260 languages specified in SupportedLanguages. The
261 number of languages supported by a driver is up
262 to the driver writer. Language is specified in
263 RFC 4646 or ISO 639-2 language code format.
265 @param ControllerName[out] A pointer to the Unicode string to return.
266 This Unicode string is the name of the
267 controller specified by ControllerHandle and
268 ChildHandle in the language specified by
269 Language from the point of view of the driver
272 @retval EFI_SUCCESS The Unicode string for the user readable name in
273 the language specified by Language for the
274 driver specified by This was returned in
277 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
279 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
282 @retval EFI_INVALID_PARAMETER Language is NULL.
284 @retval EFI_INVALID_PARAMETER ControllerName is NULL.
286 @retval EFI_UNSUPPORTED The driver specified by This is not currently
287 managing the controller specified by
288 ControllerHandle and ChildHandle.
290 @retval EFI_UNSUPPORTED The driver specified by This does not support
291 the language specified by Language.
296 DebugPortComponentNameGetControllerName (
297 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
298 IN EFI_HANDLE ControllerHandle
,
299 IN EFI_HANDLE ChildHandle OPTIONAL
,
301 OUT CHAR16
**ControllerName
306 DebugPort protocol member function. Calls SerialIo:GetControl to flush buffer.
307 We cannot call SerialIo:SetAttributes because it uses pool services, which use
308 locks, which affect TPL, so it's not interrupt context safe or re-entrant.
309 SerialIo:Reset() calls SetAttributes, so it can't be used either.
311 The port itself should be fine since it was set up during initialization.
313 @param This Protocol instance pointer.
315 @return EFI_SUCCESS Always.
321 IN EFI_DEBUGPORT_PROTOCOL
*This
325 DebugPort protocol member function. Calls SerialIo:Read() after setting
326 if it's different than the last SerialIo access.
328 @param This Pointer to DebugPort protocol.
329 @param Timeout Timeout value.
330 @param BufferSize On input, the size of Buffer.
331 On output, the amount of data actually written.
332 @param Buffer Pointer to buffer to read.
341 IN EFI_DEBUGPORT_PROTOCOL
*This
,
343 IN OUT UINTN
*BufferSize
,
348 DebugPort protocol member function. Calls SerialIo:Write() Writes 8 bytes at
349 a time and does a GetControl between 8 byte writes to help insure reads are
350 interspersed This is poor-man's flow control.
352 @param This Pointer to DebugPort protocol.
353 @param Timeout Timeout value.
354 @param BufferSize On input, the size of Buffer.
355 On output, the amount of data actually written.
356 @param Buffer Pointer to buffer to read.
358 @retval EFI_SUCCESS The data was written.
359 @retval others Fails when writting datas to debug port device.
365 IN EFI_DEBUGPORT_PROTOCOL
*This
,
367 IN OUT UINTN
*BufferSize
,
372 DebugPort protocol member function. Calls SerialIo:Write() after setting
373 if it's different than the last SerialIo access.
375 @param This Pointer to DebugPort protocol.
377 @retval EFI_SUCCESS At least 1 character is ready to be read from
378 the DebugPort interface.
379 @retval EFI_NOT_READY There are no characters ready to read from the
381 @retval EFI_DEVICE_ERROR A hardware failure occurred... (from SerialIo)
387 IN EFI_DEBUGPORT_PROTOCOL
*This