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__
14 #include <Protocol/DevicePath.h>
15 #include <Protocol/ComponentName.h>
16 #include <Protocol/DriverBinding.h>
17 #include <Protocol/SerialIo.h>
18 #include <Protocol/DebugPort.h>
20 #include <Library/DebugLib.h>
21 #include <Library/UefiDriverEntryPoint.h>
22 #include <Library/UefiLib.h>
23 #include <Library/BaseMemoryLib.h>
24 #include <Library/MemoryAllocationLib.h>
25 #include <Library/UefiBootServicesTableLib.h>
26 #include <Library/UefiRuntimeServicesTableLib.h>
27 #include <Library/DevicePathLib.h>
30 // Driver Binding Externs
32 extern EFI_DRIVER_BINDING_PROTOCOL gDebugPortDriverBinding
;
33 extern EFI_COMPONENT_NAME_PROTOCOL gDebugPortComponentName
;
34 extern EFI_COMPONENT_NAME2_PROTOCOL gDebugPortComponentName2
;
37 // local type definitions
39 #define DEBUGPORT_DEVICE_SIGNATURE SIGNATURE_32 ('D', 'B', 'G', 'P')
42 // Device structure used by driver
46 EFI_HANDLE DriverBindingHandle
;
47 EFI_HANDLE DebugPortDeviceHandle
;
49 EFI_DEVICE_PATH_PROTOCOL
*DebugPortDevicePath
;
50 EFI_DEBUGPORT_PROTOCOL DebugPortInterface
;
52 EFI_HANDLE SerialIoDeviceHandle
;
53 EFI_SERIAL_IO_PROTOCOL
*SerialIoBinding
;
55 UINT32 ReceiveFifoDepth
;
57 EFI_PARITY_TYPE Parity
;
59 EFI_STOP_BITS_TYPE StopBits
;
62 #define DEBUGPORT_DEVICE_FROM_THIS(a) CR (a, DEBUGPORT_DEVICE, DebugPortInterface, DEBUGPORT_DEVICE_SIGNATURE)
64 #define EFI_ACPI_PC_COMPORT_HID EISA_PNP_ID (0x0500)
65 #define EFI_ACPI_16550UART_HID EISA_PNP_ID (0x0501)
67 #define DEBUGPORT_UART_DEFAULT_BAUDRATE 115200
68 #define DEBUGPORT_UART_DEFAULT_PARITY 0
69 #define DEBUGPORT_UART_DEFAULT_FIFO_DEPTH 16
70 #define DEBUGPORT_UART_DEFAULT_TIMEOUT 50000///< 5 ms
71 #define DEBUGPORT_UART_DEFAULT_DATA_BITS 8
72 #define DEBUGPORT_UART_DEFAULT_STOP_BITS 1
74 #define DEBUGPORT_DRIVER_VERSION 1
76 #define IS_UART_DEVICEPATH(dp) (DevicePathType (dp) == MESSAGING_DEVICE_PATH && DevicePathSubType (dp) == MSG_UART_DP)
79 Debug Port Driver entry point.
81 Reads DebugPort variable to determine what device and settings to use as the
82 debug port. Binds exclusively to SerialIo. Reverts to defaults if no variable
85 @param[in] ImageHandle The firmware allocated handle for the EFI image.
86 @param[in] SystemTable A pointer to the EFI System Table.
88 @retval EFI_SUCCESS The entry point is executed successfully.
89 @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.
90 @retval other Some error occurs when executing this entry point.
95 InitializeDebugPortDriver (
96 IN EFI_HANDLE ImageHandle
,
97 IN EFI_SYSTEM_TABLE
*SystemTable
101 Checks to see if there's not already a DebugPort interface somewhere.
103 If there's a DEBUGPORT variable, the device path must match exactly. If there's
104 no DEBUGPORT variable, then device path is not checked and does not matter.
105 Checks to see that there's a serial io interface on the controller handle
106 that can be bound BY_DRIVER | EXCLUSIVE.
107 If all these tests succeed, then we return EFI_SUCCESS, else, EFI_UNSUPPORTED
108 or other error returned by OpenProtocol.
110 @param This Protocol instance pointer.
111 @param ControllerHandle Handle of device to test.
112 @param RemainingDevicePath Optional parameter use to pick a specific child
115 @retval EFI_SUCCESS This driver supports this device.
116 @retval EFI_UNSUPPORTED Debug Port device is not supported.
117 @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.
118 @retval others Some error occurs.
124 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
125 IN EFI_HANDLE Controller
,
126 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
130 Binds exclusively to serial io on the controller handle, Produces DebugPort
131 protocol and DevicePath on new handle.
133 @param This Protocol instance pointer.
134 @param ControllerHandle Handle of device to bind driver to.
135 @param RemainingDevicePath Optional parameter use to pick a specific child
138 @retval EFI_SUCCESS This driver is added to ControllerHandle.
139 @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.
140 @retval others Some error occurs.
146 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
147 IN EFI_HANDLE Controller
,
148 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
152 Stop this driver on ControllerHandle by removing Serial IO protocol on
153 the ControllerHandle.
155 @param This Protocol instance pointer.
156 @param ControllerHandle Handle of device to stop driver on
157 @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of
158 children is zero stop the entire bus driver.
159 @param ChildHandleBuffer List of Child Handles to Stop.
161 @retval EFI_SUCCESS This driver is removed ControllerHandle.
162 @retval other This driver was not removed from this device.
168 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
169 IN EFI_HANDLE Controller
,
170 IN UINTN NumberOfChildren
,
171 IN EFI_HANDLE
*ChildHandleBuffer
175 // 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
226 Retrieves a Unicode string that is the user readable name of the controller
227 that is being managed by a driver.
229 This function retrieves the user readable name of the controller specified by
230 ControllerHandle and ChildHandle in the form of a Unicode string. If the
231 driver specified by This has a user readable name in the language specified by
232 Language, then a pointer to the controller name is returned in ControllerName,
233 and EFI_SUCCESS is returned. If the driver specified by This is not currently
234 managing the controller specified by ControllerHandle and ChildHandle,
235 then EFI_UNSUPPORTED is returned. If the driver specified by This does not
236 support the language specified by Language, then EFI_UNSUPPORTED is returned.
238 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
239 EFI_COMPONENT_NAME_PROTOCOL instance.
241 @param ControllerHandle[in] The handle of a controller that the driver
242 specified by This is managing. This handle
243 specifies the controller whose name is to be
246 @param ChildHandle[in] The handle of the child controller to retrieve
247 the name of. This is an optional parameter that
248 may be NULL. It will be NULL for device
249 drivers. It will also be NULL for a bus drivers
250 that wish to retrieve the name of the bus
251 controller. It will not be NULL for a bus
252 driver that wishes to retrieve the name of a
255 @param Language[in] A pointer to a Null-terminated ASCII string
256 array indicating the language. This is the
257 language of the driver name that the caller is
258 requesting, and it must match one of the
259 languages specified in SupportedLanguages. The
260 number of languages supported by a driver is up
261 to the driver writer. Language is specified in
262 RFC 4646 or ISO 639-2 language code format.
264 @param ControllerName[out] A pointer to the Unicode string to return.
265 This Unicode string is the name of the
266 controller specified by ControllerHandle and
267 ChildHandle in the language specified by
268 Language from the point of view of the driver
271 @retval EFI_SUCCESS The Unicode string for the user readable name in
272 the language specified by Language for the
273 driver specified by This was returned in
276 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
278 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
281 @retval EFI_INVALID_PARAMETER Language is NULL.
283 @retval EFI_INVALID_PARAMETER ControllerName is NULL.
285 @retval EFI_UNSUPPORTED The driver specified by This is not currently
286 managing the controller specified by
287 ControllerHandle and ChildHandle.
289 @retval EFI_UNSUPPORTED The driver specified by This does not support
290 the language specified by Language.
295 DebugPortComponentNameGetControllerName (
296 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
297 IN EFI_HANDLE ControllerHandle
,
298 IN EFI_HANDLE ChildHandle OPTIONAL
,
300 OUT CHAR16
**ControllerName
304 DebugPort protocol member function. Calls SerialIo:GetControl to flush buffer.
305 We cannot call SerialIo:SetAttributes because it uses pool services, which use
306 locks, which affect TPL, so it's not interrupt context safe or re-entrant.
307 SerialIo:Reset() calls SetAttributes, so it can't be used either.
309 The port itself should be fine since it was set up during initialization.
311 @param This Protocol instance pointer.
313 @return EFI_SUCCESS Always.
319 IN EFI_DEBUGPORT_PROTOCOL
*This
323 DebugPort protocol member function. Calls SerialIo:Read() after setting
324 if it's different than the last SerialIo access.
326 @param This Pointer to DebugPort protocol.
327 @param Timeout Timeout value.
328 @param BufferSize On input, the size of Buffer.
329 On output, the amount of data actually written.
330 @param Buffer Pointer to buffer to read.
339 IN EFI_DEBUGPORT_PROTOCOL
*This
,
341 IN OUT UINTN
*BufferSize
,
346 DebugPort protocol member function. Calls SerialIo:Write() Writes 8 bytes at
347 a time and does a GetControl between 8 byte writes to help insure reads are
348 interspersed This is poor-man's flow control.
350 @param This Pointer to DebugPort protocol.
351 @param Timeout Timeout value.
352 @param BufferSize On input, the size of Buffer.
353 On output, the amount of data actually written.
354 @param Buffer Pointer to buffer to read.
356 @retval EFI_SUCCESS The data was written.
357 @retval others Fails when writting datas to debug port device.
363 IN EFI_DEBUGPORT_PROTOCOL
*This
,
365 IN OUT UINTN
*BufferSize
,
370 DebugPort protocol member function. Calls SerialIo:Write() after setting
371 if it's different than the last SerialIo access.
373 @param This Pointer to DebugPort protocol.
375 @retval EFI_SUCCESS At least 1 character is ready to be read from
376 the DebugPort interface.
377 @retval EFI_NOT_READY There are no characters ready to read from the
379 @retval EFI_DEVICE_ERROR A hardware failure occurred... (from SerialIo)
385 IN EFI_DEBUGPORT_PROTOCOL
*This