2 Definitions and prototypes for DebugPort driver.
4 Copyright (c) 2006 - 2008, Intel Corporation. <BR>
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15 #ifndef __DEBUGPORT_H__
16 #define __DEBUGPORT_H__
21 #include <Protocol/DevicePath.h>
22 #include <Protocol/ComponentName.h>
23 #include <Protocol/DriverBinding.h>
24 #include <Protocol/SerialIo.h>
25 #include <Protocol/DebugPort.h>
27 #include <Library/DebugLib.h>
28 #include <Library/UefiDriverEntryPoint.h>
29 #include <Library/UefiLib.h>
30 #include <Library/BaseMemoryLib.h>
31 #include <Library/MemoryAllocationLib.h>
32 #include <Library/UefiBootServicesTableLib.h>
33 #include <Library/UefiRuntimeServicesTableLib.h>
34 #include <Library/DevicePathLib.h>
37 // Driver Binding Externs
39 extern EFI_DRIVER_BINDING_PROTOCOL gDebugPortDriverBinding
;
40 extern EFI_COMPONENT_NAME_PROTOCOL gDebugPortComponentName
;
41 extern EFI_COMPONENT_NAME2_PROTOCOL gDebugPortComponentName2
;
44 // local type definitions
46 #define DEBUGPORT_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('D', 'B', 'G', 'P')
49 // Device structure used by driver
53 EFI_HANDLE DriverBindingHandle
;
54 EFI_HANDLE DebugPortDeviceHandle
;
55 VOID
*DebugPortVariable
;
57 EFI_DRIVER_BINDING_PROTOCOL DriverBindingInterface
;
58 EFI_COMPONENT_NAME_PROTOCOL ComponentNameInterface
;
59 EFI_DEVICE_PATH_PROTOCOL
*DebugPortDevicePath
;
60 EFI_DEBUGPORT_PROTOCOL DebugPortInterface
;
62 EFI_HANDLE SerialIoDeviceHandle
;
63 EFI_SERIAL_IO_PROTOCOL
*SerialIoBinding
;
65 UINT32 ReceiveFifoDepth
;
67 EFI_PARITY_TYPE Parity
;
69 EFI_STOP_BITS_TYPE StopBits
;
72 #define DEBUGPORT_DEVICE_FROM_THIS(a) CR (a, DEBUGPORT_DEVICE, DebugPortInterface, DEBUGPORT_DEVICE_SIGNATURE)
74 #define EFI_ACPI_PC_COMPORT_HID EISA_PNP_ID (0x0500)
75 #define EFI_ACPI_16550UART_HID EISA_PNP_ID (0x0501)
77 #define DEBUGPORT_UART_DEFAULT_BAUDRATE 115200
78 #define DEBUGPORT_UART_DEFAULT_PARITY 0
79 #define DEBUGPORT_UART_DEFAULT_FIFO_DEPTH 16
80 #define DEBUGPORT_UART_DEFAULT_TIMEOUT 50000 // 5 ms
81 #define DEBUGPORT_UART_DEFAULT_DATA_BITS 8
82 #define DEBUGPORT_UART_DEFAULT_STOP_BITS 1
84 #define DEBUGPORT_DRIVER_VERSION 1
86 #define IS_UART_DEVICEPATH(dp) (DevicePathType (dp) == MESSAGING_DEVICE_PATH && DevicePathSubType (dp) == MSG_UART_DP)
91 extern DEBUGPORT_DEVICE
*gDebugPortDevice
;
94 Debug Port Driver entry pointo.
96 Reads DebugPort variable to determine what device and settings to use as the
97 debug port. Binds exclusively to SerialIo. Reverts to defaults if no variable
100 @param[in] ImageHandle The firmware allocated handle for the EFI image.
101 @param[in] SystemTable A pointer to the EFI System Table.
103 @retval EFI_SUCCESS The entry point is executed successfully.
104 @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.
105 @retval other Some error occurs when executing this entry point.
110 InitializeDebugPortDriver (
111 IN EFI_HANDLE ImageHandle
,
112 IN EFI_SYSTEM_TABLE
*SystemTable
116 Checks to see if there's not already a DebugPort interface somewhere.
118 If there's a DEBUGPORT variable, the device path must match exactly. If there's
119 no DEBUGPORT variable, then device path is not checked and does not matter.
120 Checks to see that there's a serial io interface on the controller handle
121 that can be bound BY_DRIVER | EXCLUSIVE.
122 If all these tests succeed, then we return EFI_SUCCESS, else, EFI_UNSUPPORTED
123 or other error returned by OpenProtocol.
125 @param This Protocol instance pointer.
126 @param ControllerHandle Handle of device to test.
127 @param RemainingDevicePath Optional parameter use to pick a specific child
130 @retval EFI_SUCCESS This driver supports this device.
131 @retval EFI_UNSUPPORTED Debug Port device is not supported.
132 @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.
133 @retval others Some error occurs.
139 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
140 IN EFI_HANDLE Controller
,
141 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
145 Binds exclusively to serial io on the controller handle, Produces DebugPort
146 protocol and DevicePath on new handle.
148 @param This Protocol instance pointer.
149 @param ControllerHandle Handle of device to bind driver to.
150 @param RemainingDevicePath Optional parameter use to pick a specific child
153 @retval EFI_SUCCESS This driver is added to ControllerHandle.
154 @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.
155 @retval others Some error occurs.
161 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
162 IN EFI_HANDLE Controller
,
163 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
167 Stop this driver on ControllerHandle by removing Serial IO protocol on
168 the ControllerHandle.
170 @param This Protocol instance pointer.
171 @param ControllerHandle Handle of device to stop driver on
172 @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of
173 children is zero stop the entire bus driver.
174 @param ChildHandleBuffer List of Child Handles to Stop.
176 @retval EFI_SUCCESS This driver is removed ControllerHandle.
177 @retval other This driver was not removed from this device.
183 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
184 IN EFI_HANDLE Controller
,
185 IN UINTN NumberOfChildren
,
186 IN EFI_HANDLE
*ChildHandleBuffer
190 // EFI Component Name Functions
193 Retrieves a Unicode string that is the user readable name of the driver.
195 This function retrieves the user readable name of a driver in the form of a
196 Unicode string. If the driver specified by This has a user readable name in
197 the language specified by Language, then a pointer to the driver name is
198 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
199 by This does not support the language specified by Language,
200 then EFI_UNSUPPORTED is returned.
202 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
203 EFI_COMPONENT_NAME_PROTOCOL instance.
205 @param Language[in] A pointer to a Null-terminated ASCII string
206 array indicating the language. This is the
207 language of the driver name that the caller is
208 requesting, and it must match one of the
209 languages specified in SupportedLanguages. The
210 number of languages supported by a driver is up
211 to the driver writer. Language is specified
212 in RFC 3066 or ISO 639-2 language code format.
214 @param DriverName[out] A pointer to the Unicode string to return.
215 This Unicode string is the name of the
216 driver specified by This in the language
217 specified by Language.
219 @retval EFI_SUCCESS The Unicode string for the Driver specified by
220 This and the language specified by Language was
221 returned in DriverName.
223 @retval EFI_INVALID_PARAMETER Language is NULL.
225 @retval EFI_INVALID_PARAMETER DriverName is NULL.
227 @retval EFI_UNSUPPORTED The driver specified by This does not support
228 the language specified by Language.
233 DebugPortComponentNameGetDriverName (
234 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
236 OUT CHAR16
**DriverName
241 Retrieves a Unicode string that is the user readable name of the controller
242 that is being managed by a driver.
244 This function retrieves the user readable name of the controller specified by
245 ControllerHandle and ChildHandle in the form of a Unicode string. If the
246 driver specified by This has a user readable name in the language specified by
247 Language, then a pointer to the controller name is returned in ControllerName,
248 and EFI_SUCCESS is returned. If the driver specified by This is not currently
249 managing the controller specified by ControllerHandle and ChildHandle,
250 then EFI_UNSUPPORTED is returned. If the driver specified by This does not
251 support the language specified by Language, then EFI_UNSUPPORTED is returned.
253 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
254 EFI_COMPONENT_NAME_PROTOCOL instance.
256 @param ControllerHandle[in] The handle of a controller that the driver
257 specified by This is managing. This handle
258 specifies the controller whose name is to be
261 @param ChildHandle[in] The handle of the child controller to retrieve
262 the name of. This is an optional parameter that
263 may be NULL. It will be NULL for device
264 drivers. It will also be NULL for a bus drivers
265 that wish to retrieve the name of the bus
266 controller. It will not be NULL for a bus
267 driver that wishes to retrieve the name of a
270 @param Language[in] A pointer to a Null-terminated ASCII string
271 array indicating the language. This is the
272 language of the driver name that the caller is
273 requesting, and it must match one of the
274 languages specified in SupportedLanguages. The
275 number of languages supported by a driver is up
276 to the driver writer. Language is specified in
277 RFC 3066 or ISO 639-2 language code format.
279 @param ControllerName[out] A pointer to the Unicode string to return.
280 This Unicode string is the name of the
281 controller specified by ControllerHandle and
282 ChildHandle in the language specified by
283 Language from the point of view of the driver
286 @retval EFI_SUCCESS The Unicode string for the user readable name in
287 the language specified by Language for the
288 driver specified by This was returned in
291 @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
293 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
296 @retval EFI_INVALID_PARAMETER Language is NULL.
298 @retval EFI_INVALID_PARAMETER ControllerName is NULL.
300 @retval EFI_UNSUPPORTED The driver specified by This is not currently
301 managing the controller specified by
302 ControllerHandle and ChildHandle.
304 @retval EFI_UNSUPPORTED The driver specified by This does not support
305 the language specified by Language.
310 DebugPortComponentNameGetControllerName (
311 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
312 IN EFI_HANDLE ControllerHandle
,
313 IN EFI_HANDLE ChildHandle OPTIONAL
,
315 OUT CHAR16
**ControllerName
320 DebugPort protocol member function. Calls SerialIo:GetControl to flush buffer.
321 We cannot call SerialIo:SetAttributes because it uses pool services, which use
322 locks, which affect TPL, so it's not interrupt context safe or re-entrant.
323 SerialIo:Reset() calls SetAttributes, so it can't be used either.
325 The port itself should be fine since it was set up during initialization.
327 @param This Protocol instance pointer.
329 @return EFI_SUCCESS Always.
335 IN EFI_DEBUGPORT_PROTOCOL
*This
339 DebugPort protocol member function. Calls SerialIo:Read() after setting
340 if it's different than the last SerialIo access.
342 @param This Pointer to DebugPort protocol.
343 @param Timeout Timeout value.
344 @param BufferSize On input, the size of Buffer.
345 On output, the amount of data actually written.
346 @param Buffer Pointer to buffer to read.
355 IN EFI_DEBUGPORT_PROTOCOL
*This
,
357 IN OUT UINTN
*BufferSize
,
362 DebugPort protocol member function. Calls SerialIo:Write() Writes 8 bytes at
363 a time and does a GetControl between 8 byte writes to help insure reads are
364 interspersed This is poor-man's flow control.
366 @param This Pointer to DebugPort protocol.
367 @param Timeout Timeout value.
368 @param BufferSize On input, the size of Buffer.
369 On output, the amount of data actually written.
370 @param Buffer Pointer to buffer to read.
372 @retval EFI_SUCCESS The data was written.
373 @retval others Fails when writting datas to debug port device.
379 IN EFI_DEBUGPORT_PROTOCOL
*This
,
381 IN OUT UINTN
*BufferSize
,
386 DebugPort protocol member function. Calls SerialIo:Write() after setting
387 if it's different than the last SerialIo access.
389 @param This Pointer to DebugPort protocol.
391 @retval EFI_SUCCESS At least 1 character is ready to be read from
392 the DebugPort interface.
393 @retval EFI_NOT_READY There are no characters ready to read from the
395 @retval EFI_DEVICE_ERROR A hardware failure occured... (from SerialIo)
401 IN EFI_DEBUGPORT_PROTOCOL
*This