Check comments, format and fix some typo.
[mirror_edk2.git] / MdeModulePkg / Universal / DebugPortDxe / DebugPort.h
1 /** @file
2 Definitions and prototypes for DebugPort driver.
3
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
9
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.
12
13 **/
14
15 #ifndef __DEBUGPORT_H__
16 #define __DEBUGPORT_H__
17
18
19 #include <Uefi.h>
20
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>
26
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>
35
36 //
37 // Driver Binding Externs
38 //
39 extern EFI_DRIVER_BINDING_PROTOCOL gDebugPortDriverBinding;
40 extern EFI_COMPONENT_NAME_PROTOCOL gDebugPortComponentName;
41 extern EFI_COMPONENT_NAME2_PROTOCOL gDebugPortComponentName2;
42
43 //
44 // local type definitions
45 //
46 #define DEBUGPORT_DEVICE_SIGNATURE SIGNATURE_32 ('D', 'B', 'G', 'P')
47
48 //
49 // Device structure used by driver
50 //
51 typedef struct {
52 UINT32 Signature;
53 EFI_HANDLE DriverBindingHandle;
54 EFI_HANDLE DebugPortDeviceHandle;
55 VOID *DebugPortVariable;
56
57 EFI_DEVICE_PATH_PROTOCOL *DebugPortDevicePath;
58 EFI_DEBUGPORT_PROTOCOL DebugPortInterface;
59
60 EFI_HANDLE SerialIoDeviceHandle;
61 EFI_SERIAL_IO_PROTOCOL *SerialIoBinding;
62 UINT64 BaudRate;
63 UINT32 ReceiveFifoDepth;
64 UINT32 Timeout;
65 EFI_PARITY_TYPE Parity;
66 UINT8 DataBits;
67 EFI_STOP_BITS_TYPE StopBits;
68 } DEBUGPORT_DEVICE;
69
70 #define DEBUGPORT_DEVICE_FROM_THIS(a) CR (a, DEBUGPORT_DEVICE, DebugPortInterface, DEBUGPORT_DEVICE_SIGNATURE)
71
72 #define EFI_ACPI_PC_COMPORT_HID EISA_PNP_ID (0x0500)
73 #define EFI_ACPI_16550UART_HID EISA_PNP_ID (0x0501)
74
75 #define DEBUGPORT_UART_DEFAULT_BAUDRATE 115200
76 #define DEBUGPORT_UART_DEFAULT_PARITY 0
77 #define DEBUGPORT_UART_DEFAULT_FIFO_DEPTH 16
78 #define DEBUGPORT_UART_DEFAULT_TIMEOUT 50000 ///< 5 ms
79 #define DEBUGPORT_UART_DEFAULT_DATA_BITS 8
80 #define DEBUGPORT_UART_DEFAULT_STOP_BITS 1
81
82 #define DEBUGPORT_DRIVER_VERSION 1
83
84 #define IS_UART_DEVICEPATH(dp) (DevicePathType (dp) == MESSAGING_DEVICE_PATH && DevicePathSubType (dp) == MSG_UART_DP)
85
86 /**
87 Debug Port Driver entry point.
88
89 Reads DebugPort variable to determine what device and settings to use as the
90 debug port. Binds exclusively to SerialIo. Reverts to defaults if no variable
91 is found.
92
93 @param[in] ImageHandle The firmware allocated handle for the EFI image.
94 @param[in] SystemTable A pointer to the EFI System Table.
95
96 @retval EFI_SUCCESS The entry point is executed successfully.
97 @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.
98 @retval other Some error occurs when executing this entry point.
99
100 **/
101 EFI_STATUS
102 EFIAPI
103 InitializeDebugPortDriver (
104 IN EFI_HANDLE ImageHandle,
105 IN EFI_SYSTEM_TABLE *SystemTable
106 );
107
108 /**
109 Checks to see if there's not already a DebugPort interface somewhere.
110
111 If there's a DEBUGPORT variable, the device path must match exactly. If there's
112 no DEBUGPORT variable, then device path is not checked and does not matter.
113 Checks to see that there's a serial io interface on the controller handle
114 that can be bound BY_DRIVER | EXCLUSIVE.
115 If all these tests succeed, then we return EFI_SUCCESS, else, EFI_UNSUPPORTED
116 or other error returned by OpenProtocol.
117
118 @param This Protocol instance pointer.
119 @param ControllerHandle Handle of device to test.
120 @param RemainingDevicePath Optional parameter use to pick a specific child
121 device to start.
122
123 @retval EFI_SUCCESS This driver supports this device.
124 @retval EFI_UNSUPPORTED Debug Port device is not supported.
125 @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.
126 @retval others Some error occurs.
127
128 **/
129 EFI_STATUS
130 EFIAPI
131 DebugPortSupported (
132 IN EFI_DRIVER_BINDING_PROTOCOL *This,
133 IN EFI_HANDLE Controller,
134 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
135 );
136
137 /**
138 Binds exclusively to serial io on the controller handle, Produces DebugPort
139 protocol and DevicePath on new handle.
140
141 @param This Protocol instance pointer.
142 @param ControllerHandle Handle of device to bind driver to.
143 @param RemainingDevicePath Optional parameter use to pick a specific child
144 device to start.
145
146 @retval EFI_SUCCESS This driver is added to ControllerHandle.
147 @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.
148 @retval others Some error occurs.
149
150 **/
151 EFI_STATUS
152 EFIAPI
153 DebugPortStart (
154 IN EFI_DRIVER_BINDING_PROTOCOL *This,
155 IN EFI_HANDLE Controller,
156 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
157 );
158
159 /**
160 Stop this driver on ControllerHandle by removing Serial IO protocol on
161 the ControllerHandle.
162
163 @param This Protocol instance pointer.
164 @param ControllerHandle Handle of device to stop driver on
165 @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of
166 children is zero stop the entire bus driver.
167 @param ChildHandleBuffer List of Child Handles to Stop.
168
169 @retval EFI_SUCCESS This driver is removed ControllerHandle.
170 @retval other This driver was not removed from this device.
171
172 **/
173 EFI_STATUS
174 EFIAPI
175 DebugPortStop (
176 IN EFI_DRIVER_BINDING_PROTOCOL *This,
177 IN EFI_HANDLE Controller,
178 IN UINTN NumberOfChildren,
179 IN EFI_HANDLE *ChildHandleBuffer
180 );
181
182 //
183 // EFI Component Name Functions
184 //
185 /**
186 Retrieves a Unicode string that is the user readable name of the driver.
187
188 This function retrieves the user readable name of a driver in the form of a
189 Unicode string. If the driver specified by This has a user readable name in
190 the language specified by Language, then a pointer to the driver name is
191 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
192 by This does not support the language specified by Language,
193 then EFI_UNSUPPORTED is returned.
194
195 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
196 EFI_COMPONENT_NAME_PROTOCOL instance.
197
198 @param Language[in] A pointer to a Null-terminated ASCII string
199 array indicating the language. This is the
200 language of the driver name that the caller is
201 requesting, and it must match one of the
202 languages specified in SupportedLanguages. The
203 number of languages supported by a driver is up
204 to the driver writer. Language is specified
205 in RFC 3066 or ISO 639-2 language code format.
206
207 @param DriverName[out] A pointer to the Unicode string to return.
208 This Unicode string is the name of the
209 driver specified by This in the language
210 specified by Language.
211
212 @retval EFI_SUCCESS The Unicode string for the Driver specified by
213 This and the language specified by Language was
214 returned in DriverName.
215
216 @retval EFI_INVALID_PARAMETER Language is NULL.
217
218 @retval EFI_INVALID_PARAMETER DriverName is NULL.
219
220 @retval EFI_UNSUPPORTED The driver specified by This does not support
221 the language specified by Language.
222
223 **/
224 EFI_STATUS
225 EFIAPI
226 DebugPortComponentNameGetDriverName (
227 IN EFI_COMPONENT_NAME_PROTOCOL *This,
228 IN CHAR8 *Language,
229 OUT CHAR16 **DriverName
230 );
231
232
233 /**
234 Retrieves a Unicode string that is the user readable name of the controller
235 that is being managed by a driver.
236
237 This function retrieves the user readable name of the controller specified by
238 ControllerHandle and ChildHandle in the form of a Unicode string. If the
239 driver specified by This has a user readable name in the language specified by
240 Language, then a pointer to the controller name is returned in ControllerName,
241 and EFI_SUCCESS is returned. If the driver specified by This is not currently
242 managing the controller specified by ControllerHandle and ChildHandle,
243 then EFI_UNSUPPORTED is returned. If the driver specified by This does not
244 support the language specified by Language, then EFI_UNSUPPORTED is returned.
245
246 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
247 EFI_COMPONENT_NAME_PROTOCOL instance.
248
249 @param ControllerHandle[in] The handle of a controller that the driver
250 specified by This is managing. This handle
251 specifies the controller whose name is to be
252 returned.
253
254 @param ChildHandle[in] The handle of the child controller to retrieve
255 the name of. This is an optional parameter that
256 may be NULL. It will be NULL for device
257 drivers. It will also be NULL for a bus drivers
258 that wish to retrieve the name of the bus
259 controller. It will not be NULL for a bus
260 driver that wishes to retrieve the name of a
261 child controller.
262
263 @param Language[in] A pointer to a Null-terminated ASCII string
264 array indicating the language. This is the
265 language of the driver name that the caller is
266 requesting, and it must match one of the
267 languages specified in SupportedLanguages. The
268 number of languages supported by a driver is up
269 to the driver writer. Language is specified in
270 RFC 3066 or ISO 639-2 language code format.
271
272 @param ControllerName[out] A pointer to the Unicode string to return.
273 This Unicode string is the name of the
274 controller specified by ControllerHandle and
275 ChildHandle in the language specified by
276 Language from the point of view of the driver
277 specified by This.
278
279 @retval EFI_SUCCESS The Unicode string for the user readable name in
280 the language specified by Language for the
281 driver specified by This was returned in
282 DriverName.
283
284 @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
285
286 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
287 EFI_HANDLE.
288
289 @retval EFI_INVALID_PARAMETER Language is NULL.
290
291 @retval EFI_INVALID_PARAMETER ControllerName is NULL.
292
293 @retval EFI_UNSUPPORTED The driver specified by This is not currently
294 managing the controller specified by
295 ControllerHandle and ChildHandle.
296
297 @retval EFI_UNSUPPORTED The driver specified by This does not support
298 the language specified by Language.
299
300 **/
301 EFI_STATUS
302 EFIAPI
303 DebugPortComponentNameGetControllerName (
304 IN EFI_COMPONENT_NAME_PROTOCOL *This,
305 IN EFI_HANDLE ControllerHandle,
306 IN EFI_HANDLE ChildHandle OPTIONAL,
307 IN CHAR8 *Language,
308 OUT CHAR16 **ControllerName
309 );
310
311
312 /**
313 DebugPort protocol member function. Calls SerialIo:GetControl to flush buffer.
314 We cannot call SerialIo:SetAttributes because it uses pool services, which use
315 locks, which affect TPL, so it's not interrupt context safe or re-entrant.
316 SerialIo:Reset() calls SetAttributes, so it can't be used either.
317
318 The port itself should be fine since it was set up during initialization.
319
320 @param This Protocol instance pointer.
321
322 @return EFI_SUCCESS Always.
323
324 **/
325 EFI_STATUS
326 EFIAPI
327 DebugPortReset (
328 IN EFI_DEBUGPORT_PROTOCOL *This
329 );
330
331 /**
332 DebugPort protocol member function. Calls SerialIo:Read() after setting
333 if it's different than the last SerialIo access.
334
335 @param This Pointer to DebugPort protocol.
336 @param Timeout Timeout value.
337 @param BufferSize On input, the size of Buffer.
338 On output, the amount of data actually written.
339 @param Buffer Pointer to buffer to read.
340
341 @retval EFI_SUCCESS
342 @retval others
343
344 **/
345 EFI_STATUS
346 EFIAPI
347 DebugPortRead (
348 IN EFI_DEBUGPORT_PROTOCOL *This,
349 IN UINT32 Timeout,
350 IN OUT UINTN *BufferSize,
351 IN VOID *Buffer
352 );
353
354 /**
355 DebugPort protocol member function. Calls SerialIo:Write() Writes 8 bytes at
356 a time and does a GetControl between 8 byte writes to help insure reads are
357 interspersed This is poor-man's flow control.
358
359 @param This Pointer to DebugPort protocol.
360 @param Timeout Timeout value.
361 @param BufferSize On input, the size of Buffer.
362 On output, the amount of data actually written.
363 @param Buffer Pointer to buffer to read.
364
365 @retval EFI_SUCCESS The data was written.
366 @retval others Fails when writting datas to debug port device.
367
368 **/
369 EFI_STATUS
370 EFIAPI
371 DebugPortWrite (
372 IN EFI_DEBUGPORT_PROTOCOL *This,
373 IN UINT32 Timeout,
374 IN OUT UINTN *BufferSize,
375 OUT VOID *Buffer
376 );
377
378 /**
379 DebugPort protocol member function. Calls SerialIo:Write() after setting
380 if it's different than the last SerialIo access.
381
382 @param This Pointer to DebugPort protocol.
383
384 @retval EFI_SUCCESS At least 1 character is ready to be read from
385 the DebugPort interface.
386 @retval EFI_NOT_READY There are no characters ready to read from the
387 DebugPort interface
388 @retval EFI_DEVICE_ERROR A hardware failure occured... (from SerialIo)
389
390 **/
391 EFI_STATUS
392 EFIAPI
393 DebugPortPoll (
394 IN EFI_DEBUGPORT_PROTOCOL *This
395 );
396
397 #endif