← Back to branch summary

~ubuntu-branches/ubuntu/trusty/virtualbox-lts-xenial/trusty-proposed

« back to all changes in this revision

Viewing changes to src/VBox/Devices/EFI/Firmware/MdePkg/Include/Protocol/SerialIo.h

  • Committer: Package Import Robot
  • Author(s): Gianfranco Costamagna
  • Date: 2016-02-23 14:28:26 UTC
  • Revision ID: package-import@ubuntu.com-20160223142826-bdu69el2z6wa2a44
Tags: upstream-4.3.36-dfsg
Import upstream version 4.3.36-dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/VBox/Devices/EFI/Firmware/MdePkg/Include/Protocol/SerialIo.h
 
1
/** @file
 
2
  Serial IO protocol as defined in the UEFI 2.0 specification.
 
3
 
 
4
  Abstraction of a basic serial device. Targeted at 16550 UART, but
 
5
  could be much more generic.
 
6
 
 
7
  Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR>
 
8
  This program and the accompanying materials                          
 
9
  are licensed and made available under the terms and conditions of the BSD License         
 
10
  which accompanies this distribution.  The full text of the license may be found at        
 
11
  http://opensource.org/licenses/bsd-license.php                                            
 
12
 
 
13
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     
 
14
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             
 
15
 
 
16
**/
 
17
 
 
18
#ifndef __SERIAL_IO_PROTOCOL_H__
 
19
#define __SERIAL_IO_PROTOCOL_H__
 
20
 
 
21
#define EFI_SERIAL_IO_PROTOCOL_GUID \
 
22
  { \
 
23
    0xBB25CF6F, 0xF1D4, 0x11D2, {0x9A, 0x0C, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0xFD } \
 
24
  }
 
25
 
 
26
///
 
27
/// Protocol GUID defined in EFI1.1.
 
28
/// 
 
29
#define SERIAL_IO_PROTOCOL  EFI_SERIAL_IO_PROTOCOL_GUID
 
30
 
 
31
typedef struct _EFI_SERIAL_IO_PROTOCOL EFI_SERIAL_IO_PROTOCOL;
 
32
 
 
33
 
 
34
///
 
35
/// Backward-compatible with EFI1.1.
 
36
/// 
 
37
typedef EFI_SERIAL_IO_PROTOCOL  SERIAL_IO_INTERFACE;
 
38
 
 
39
///
 
40
/// Parity type that is computed or checked as each character is transmitted or received. If the
 
41
/// device does not support parity, the value is the default parity value.
 
42
///
 
43
typedef enum {
 
44
  DefaultParity,
 
45
  NoParity,
 
46
  EvenParity,
 
47
  OddParity,
 
48
  MarkParity,
 
49
  SpaceParity
 
50
} EFI_PARITY_TYPE;
 
51
 
 
52
///
 
53
/// Stop bits type
 
54
///
 
55
typedef enum {
 
56
  DefaultStopBits,
 
57
  OneStopBit,
 
58
  OneFiveStopBits,
 
59
  TwoStopBits
 
60
} EFI_STOP_BITS_TYPE;
 
61
 
 
62
//
 
63
// define for Control bits, grouped by read only, write only, and read write
 
64
//
 
65
//
 
66
// Read Only
 
67
//
 
68
#define EFI_SERIAL_CLEAR_TO_SEND        0x00000010
 
69
#define EFI_SERIAL_DATA_SET_READY       0x00000020
 
70
#define EFI_SERIAL_RING_INDICATE        0x00000040
 
71
#define EFI_SERIAL_CARRIER_DETECT       0x00000080
 
72
#define EFI_SERIAL_INPUT_BUFFER_EMPTY   0x00000100
 
73
#define EFI_SERIAL_OUTPUT_BUFFER_EMPTY  0x00000200
 
74
 
 
75
//
 
76
// Write Only
 
77
//
 
78
#define EFI_SERIAL_REQUEST_TO_SEND      0x00000002
 
79
#define EFI_SERIAL_DATA_TERMINAL_READY  0x00000001
 
80
 
 
81
//
 
82
// Read Write
 
83
//
 
84
#define EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE     0x00001000
 
85
#define EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE     0x00002000
 
86
#define EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE 0x00004000
 
87
 
 
88
//
 
89
// Serial IO Member Functions
 
90
//
 
91
/**
 
92
  Reset the serial device.
 
93
 
 
94
  @param  This              Protocol instance pointer.
 
95
                            
 
96
  @retval EFI_SUCCESS       The device was reset.
 
97
  @retval EFI_DEVICE_ERROR  The serial device could not be reset.
 
98
 
 
99
**/
 
100
typedef
 
101
EFI_STATUS
 
102
(EFIAPI *EFI_SERIAL_RESET)(
 
103
  IN EFI_SERIAL_IO_PROTOCOL *This
 
104
  );
 
105
 
 
106
/**
 
107
  Sets the baud rate, receive FIFO depth, transmit/receice time out, parity, 
 
108
  data buts, and stop bits on a serial device.
 
109
 
 
110
  @param  This             Protocol instance pointer.
 
111
  @param  BaudRate         The requested baud rate. A BaudRate value of 0 will use the
 
112
                           device's default interface speed.
 
113
  @param  ReveiveFifoDepth The requested depth of the FIFO on the receive side of the
 
114
                           serial interface. A ReceiveFifoDepth value of 0 will use
 
115
                           the device's default FIFO depth.
 
116
  @param  Timeout          The requested time out for a single character in microseconds.
 
117
                           This timeout applies to both the transmit and receive side of the
 
118
                           interface. A Timeout value of 0 will use the device's default time
 
119
                           out value.
 
120
  @param  Parity           The type of parity to use on this serial device. A Parity value of
 
121
                           DefaultParity will use the device's default parity value.
 
122
  @param  DataBits         The number of data bits to use on the serial device. A DataBits
 
123
                           vaule of 0 will use the device's default data bit setting.
 
124
  @param  StopBits         The number of stop bits to use on this serial device. A StopBits
 
125
                           value of DefaultStopBits will use the device's default number of
 
126
                           stop bits.
 
127
 
 
128
  @retval EFI_SUCCESS      The device was reset.
 
129
  @retval EFI_DEVICE_ERROR The serial device could not be reset.
 
130
 
 
131
**/
 
132
typedef
 
133
EFI_STATUS
 
134
(EFIAPI *EFI_SERIAL_SET_ATTRIBUTES)(
 
135
  IN EFI_SERIAL_IO_PROTOCOL         *This,
 
136
  IN UINT64                         BaudRate,
 
137
  IN UINT32                         ReceiveFifoDepth,
 
138
  IN UINT32                         Timeout,
 
139
  IN EFI_PARITY_TYPE                Parity,
 
140
  IN UINT8                          DataBits,
 
141
  IN EFI_STOP_BITS_TYPE             StopBits
 
142
  );
 
143
 
 
144
/**
 
145
  Set the control bits on a serial device
 
146
 
 
147
  @param  This             Protocol instance pointer.
 
148
  @param  Control          Set the bits of Control that are settable.
 
149
 
 
150
  @retval EFI_SUCCESS      The new control bits were set on the serial device.
 
151
  @retval EFI_UNSUPPORTED  The serial device does not support this operation.
 
152
  @retval EFI_DEVICE_ERROR The serial device is not functioning correctly.
 
153
 
 
154
**/
 
155
typedef
 
156
EFI_STATUS
 
157
(EFIAPI *EFI_SERIAL_SET_CONTROL_BITS)(
 
158
  IN EFI_SERIAL_IO_PROTOCOL         *This,
 
159
  IN UINT32                         Control
 
160
  );
 
161
 
 
162
/**
 
163
  Retrieves the status of thecontrol bits on a serial device
 
164
 
 
165
  @param  This              Protocol instance pointer.
 
166
  @param  Control           A pointer to return the current Control signals from the serial device.
 
167
                            
 
168
  @retval EFI_SUCCESS       The control bits were read from the serial device.
 
169
  @retval EFI_DEVICE_ERROR  The serial device is not functioning correctly.
 
170
 
 
171
**/
 
172
typedef
 
173
EFI_STATUS
 
174
(EFIAPI *EFI_SERIAL_GET_CONTROL_BITS)(
 
175
  IN EFI_SERIAL_IO_PROTOCOL         *This,
 
176
  OUT UINT32                        *Control
 
177
  );
 
178
 
 
179
/**
 
180
  Writes data to a serial device.
 
181
 
 
182
  @param  This              Protocol instance pointer.
 
183
  @param  BufferSize        On input, the size of the Buffer. On output, the amount of
 
184
                            data actually written.
 
185
  @param  Buffer            The buffer of data to write
 
186
 
 
187
  @retval EFI_SUCCESS       The data was written.
 
188
  @retval EFI_DEVICE_ERROR  The device reported an error.
 
189
  @retval EFI_TIMEOUT       The data write was stopped due to a timeout.
 
190
 
 
191
**/
 
192
typedef
 
193
EFI_STATUS
 
194
(EFIAPI *EFI_SERIAL_WRITE)(
 
195
  IN EFI_SERIAL_IO_PROTOCOL         *This,
 
196
  IN OUT UINTN                      *BufferSize,
 
197
  IN VOID                           *Buffer
 
198
  );
 
199
 
 
200
/**
 
201
  Writes data to a serial device.
 
202
 
 
203
  @param  This              Protocol instance pointer.
 
204
  @param  BufferSize        On input, the size of the Buffer. On output, the amount of
 
205
                            data returned in Buffer.
 
206
  @param  Buffer            The buffer to return the data into.
 
207
 
 
208
  @retval EFI_SUCCESS       The data was read.
 
209
  @retval EFI_DEVICE_ERROR  The device reported an error.
 
210
  @retval EFI_TIMEOUT       The data write was stopped due to a timeout.
 
211
 
 
212
**/
 
213
typedef
 
214
EFI_STATUS
 
215
(EFIAPI *EFI_SERIAL_READ)(
 
216
  IN EFI_SERIAL_IO_PROTOCOL         *This,
 
217
  IN OUT UINTN                      *BufferSize,
 
218
  OUT VOID                          *Buffer
 
219
  );
 
220
 
 
221
/**
 
222
  @par Data Structure Description:
 
223
  The data values in SERIAL_IO_MODE are read-only and are updated by the code 
 
224
  that produces the SERIAL_IO_PROTOCOL member functions.
 
225
 
 
226
  @param ControlMask
 
227
  A mask for the Control bits that the device supports. The device
 
228
  must always support the Input Buffer Empty control bit.
 
229
  
 
230
  @param TimeOut
 
231
  If applicable, the number of microseconds to wait before timing out
 
232
  a Read or Write operation.
 
233
  
 
234
  @param BaudRate
 
235
  If applicable, the current baud rate setting of the device; otherwise,
 
236
  baud rate has the value of zero to indicate that device runs at the
 
237
  device's designed speed.
 
238
  
 
239
  @param ReceiveFifoDepth
 
240
  The number of characters the device will buffer on input
 
241
  
 
242
  @param DataBits
 
243
  The number of characters the device will buffer on input
 
244
  
 
245
  @param Parity
 
246
  If applicable, this is the EFI_PARITY_TYPE that is computed or 
 
247
  checked as each character is transmitted or reveived. If the device
 
248
  does not support parity the value is the default parity value.
 
249
  
 
250
  @param StopBits
 
251
  If applicable, the EFI_STOP_BITS_TYPE number of stop bits per
 
252
  character. If the device does not support stop bits the value is
 
253
  the default stop bit values.
 
254
 
 
255
**/
 
256
typedef struct {
 
257
  UINT32  ControlMask;
 
258
 
 
259
  //
 
260
  // current Attributes
 
261
  //
 
262
  UINT32  Timeout;
 
263
  UINT64  BaudRate;
 
264
  UINT32  ReceiveFifoDepth;
 
265
  UINT32  DataBits;
 
266
  UINT32  Parity;
 
267
  UINT32  StopBits;
 
268
} EFI_SERIAL_IO_MODE;
 
269
 
 
270
#define EFI_SERIAL_IO_PROTOCOL_REVISION    0x00010000
 
271
#define SERIAL_IO_INTERFACE_REVISION  EFI_SERIAL_IO_PROTOCOL_REVISION
 
272
 
 
273
///
 
274
/// The Serial I/O protocol is used to communicate with UART-style serial devices. 
 
275
/// These can be standard UART serial ports in PC-AT systems, serial ports attached 
 
276
/// to a USB interface, or potentially any character-based I/O device.
 
277
///
 
278
struct _EFI_SERIAL_IO_PROTOCOL {
 
279
  ///
 
280
  /// The revision to which the EFI_SERIAL_IO_PROTOCOL adheres. All future revisions 
 
281
  /// must be backwards compatible. If a future version is not backwards compatible, 
 
282
  /// it is not the same GUID.
 
283
  ///
 
284
  UINT32                      Revision;
 
285
  EFI_SERIAL_RESET            Reset;
 
286
  EFI_SERIAL_SET_ATTRIBUTES   SetAttributes;
 
287
  EFI_SERIAL_SET_CONTROL_BITS SetControl;
 
288
  EFI_SERIAL_GET_CONTROL_BITS GetControl;
 
289
  EFI_SERIAL_WRITE            Write;
 
290
  EFI_SERIAL_READ             Read;
 
291
  ///
 
292
  /// Pointer to SERIAL_IO_MODE data.
 
293
  ///
 
294
  EFI_SERIAL_IO_MODE          *Mode;
 
295
};
 
296
 
 
297
extern EFI_GUID gEfiSerialIoProtocolGuid;
 
298
 
 
299
#endif