VirtualBox

source: vbox/trunk/src/VBox/Devices/Serial/UartCore.h@ 73381

Last change on this file since 73381 was 73259, checked in by vboxsync, 6 years ago

Devices/Serial: Saved state handling for the UART core and the legacy serial device (no saved states for the OXPCIe958 device yet)
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 12.1 KB
Line 
1/* $Id: UartCore.h 73259 2018-07-20 10:14:05Z vboxsync $ */
2/** @file
3 * UartCore - UART (16550A up to 16950) emulation.
4 *
5 * The documentation for this device was taken from the PC16550D spec from TI.
6 */
7
8/*
9 * Copyright (C) 2018 Oracle Corporation
10 *
11 * This file is part of VirtualBox Open Source Edition (OSE), as
12 * available from http://www.virtualbox.org. This file is free software;
13 * you can redistribute it and/or modify it under the terms of the GNU
14 * General Public License (GPL) as published by the Free Software
15 * Foundation, in version 2 as it comes in the "COPYING" file of the
16 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
17 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
18 */
19#ifndef ___UartCore_h
20#define ___UartCore_h
21
22#include <VBox/types.h>
23#include <VBox/vmm/pdmdev.h>
24#include <VBox/vmm/pdmserialifs.h>
25#include <VBox/vmm/ssm.h>
26#include <iprt/assert.h>
27
28RT_C_DECLS_BEGIN
29
30/*********************************************************************************************************************************
31* Defined Constants And Macros *
32*********************************************************************************************************************************/
33
34/** The current serial code saved state version. */
35#define UART_SAVED_STATE_VERSION 6
36/** Saved state version of the legacy code which got replaced after 5.2. */
37#define UART_SAVED_STATE_VERSION_LEGACY_CODE 5
38/** Includes some missing bits from the previous saved state. */
39#define UART_SAVED_STATE_VERSION_MISSING_BITS 4
40/** Saved state version when only the 16450 variant was implemented. */
41#define UART_SAVED_STATE_VERSION_16450 3
42
43/** Maximum size of a FIFO. */
44#define UART_FIFO_LENGTH_MAX 128
45
46
47/*********************************************************************************************************************************
48* Structures and Typedefs *
49*********************************************************************************************************************************/
50
51/** Pointer to the UART core state. */
52typedef struct UARTCORE *PUARTCORE;
53
54
55/**
56 * UART core IRQ request callback to let the core instance raise/clear interrupt requests.
57 *
58 * @returns nothing.
59 * @param pDevIns The owning device instance.
60 * @param pThis The UART core instance.
61 * @param iLUN The LUN associated with the UART core.
62 * @param iLvl The interrupt level.
63 */
64typedef DECLCALLBACK(void) FNUARTCOREIRQREQ(PPDMDEVINS pDevIns, PUARTCORE pThis, unsigned iLUN, int iLvl);
65/** Pointer to a UART core IRQ request callback. */
66typedef FNUARTCOREIRQREQ *PFNUARTCOREIRQREQ;
67
68
69/**
70 * UART type.
71 */
72typedef enum UARTTYPE
73{
74 /** Invalid UART type. */
75 UARTTYPE_INVALID = 0,
76 /** 16450 UART type. */
77 UARTTYPE_16450,
78 /** 16550A UART type. */
79 UARTTYPE_16550A,
80 /** 16750 UART type. */
81 UARTTYPE_16750,
82 /** 32bit hack. */
83 UARTTYPE_32BIT_HACK = 0x7fffffff
84} UARTTYPE;
85
86
87/**
88 * UART FIFO.
89 */
90typedef struct UARTFIFO
91{
92 /** Fifo size configured. */
93 uint8_t cbMax;
94 /** Current amount of bytes used. */
95 uint8_t cbUsed;
96 /** Next index to write to. */
97 uint8_t offWrite;
98 /** Next index to read from. */
99 uint8_t offRead;
100 /** The interrupt trigger level (only used for the receive FIFO). */
101 uint8_t cbItl;
102 /** The data in the FIFO. */
103 uint8_t abBuf[UART_FIFO_LENGTH_MAX];
104 /** Alignment to a 4 byte boundary. */
105 uint8_t au8Alignment0[3];
106} UARTFIFO;
107/** Pointer to a FIFO. */
108typedef UARTFIFO *PUARTFIFO;
109
110
111/**
112 * UART core device.
113 *
114 * @implements PDMIBASE
115 * @implements PDMISERIALPORT
116 */
117typedef struct UARTCORE
118{
119 /** Access critical section. */
120 PDMCRITSECT CritSect;
121 /** Pointer to the device instance - R3 Ptr. */
122 PPDMDEVINSR3 pDevInsR3;
123 /** Pointer to the device instance - R0 Ptr. */
124 PPDMDEVINSR0 pDevInsR0;
125 /** Pointer to the device instance - RC Ptr. */
126 PPDMDEVINSRC pDevInsRC;
127 /** The LUN on the owning device instance for this core. */
128 uint32_t iLUN;
129 /** LUN\#0: The base interface. */
130 PDMIBASE IBase;
131 /** LUN\#0: The serial port interface. */
132 PDMISERIALPORT ISerialPort;
133 /** Pointer to the attached base driver. */
134 R3PTRTYPE(PPDMIBASE) pDrvBase;
135 /** Pointer to the attached serial driver. */
136 R3PTRTYPE(PPDMISERIALCONNECTOR) pDrvSerial;
137 /** Configuration flags. */
138 uint32_t fFlags;
139 /** The selected UART type. */
140 UARTTYPE enmType;
141
142 /** R3 timer pointer fo the character timeout indication. */
143 PTMTIMERR3 pTimerRcvFifoTimeoutR3;
144 /** R3 interrupt request callback of the owning device. */
145 R3PTRTYPE(PFNUARTCOREIRQREQ) pfnUartIrqReqR3;
146 /** R0 timer pointer fo the character timeout indication. */
147 PTMTIMERR0 pTimerRcvFifoTimeoutR0;
148 /** R0 interrupt request callback of the owning device. */
149 R0PTRTYPE(PFNUARTCOREIRQREQ) pfnUartIrqReqR0;
150 /** RC timer pointer fo the character timeout indication. */
151 PTMTIMERRC pTimerRcvFifoTimeoutRC;
152 /** RC interrupt request callback of the owning device. */
153 RCPTRTYPE(PFNUARTCOREIRQREQ) pfnUartIrqReqRC;
154
155 /** The divisor register (DLAB = 1). */
156 uint16_t uRegDivisor;
157 /** The Receiver Buffer Register (RBR, DLAB = 0). */
158 uint8_t uRegRbr;
159 /** The Transmitter Holding Register (THR, DLAB = 0). */
160 uint8_t uRegThr;
161 /** The Interrupt Enable Register (IER, DLAB = 0). */
162 uint8_t uRegIer;
163 /** The Interrupt Identification Register (IIR). */
164 uint8_t uRegIir;
165 /** The FIFO Control Register (FCR). */
166 uint8_t uRegFcr;
167 /** The Line Control Register (LCR). */
168 uint8_t uRegLcr;
169 /** The Modem Control Register (MCR). */
170 uint8_t uRegMcr;
171 /** The Line Status Register (LSR). */
172 uint8_t uRegLsr;
173 /** The Modem Status Register (MSR). */
174 uint8_t uRegMsr;
175 /** The Scratch Register (SCR). */
176 uint8_t uRegScr;
177
178 /** Flag whether a character timeout interrupt is pending
179 * (no symbols were inserted or removed from the receive FIFO
180 * during an 4 times the character transmit/receive period and the FIFO
181 * is not empty). */
182 bool fIrqCtiPending;
183 /** Alignment. */
184 bool afAlignment[3];
185 /** The transmit FIFO. */
186 UARTFIFO FifoXmit;
187 /** The receive FIFO. */
188 UARTFIFO FifoRecv;
189
190 /** Time it takes to transmit/receive a single symbol in timer ticks. */
191 uint64_t cSymbolXferTicks;
192 /** Number of bytes available for reading from the layer below. */
193 volatile uint32_t cbAvailRdr;
194
195#if defined(IN_RC) || HC_ARCH_BITS == 32
196 uint32_t uAlignment;
197#endif
198} UARTCORE;
199
200AssertCompileSizeAlignment(UARTCORE, 8);
201
202
203#ifndef VBOX_DEVICE_STRUCT_TESTCASE
204
205/** Flag whether to yield the CPU on an LSR read. */
206#define UART_CORE_YIELD_ON_LSR_READ RT_BIT_32(0)
207
208/**
209 * Performs a register write to the given register offset.
210 *
211 * @returns VBox status code.
212 * @param pThis The UART core instance.
213 * @param uReg The register offset (byte offset) to start writing to.
214 * @param u32 The value to write.
215 * @param cb Number of bytes to write.
216 */
217DECLHIDDEN(int) uartRegWrite(PUARTCORE pThis, uint32_t uReg, uint32_t u32, size_t cb);
218
219/**
220 * Performs a register read from the given register offset.
221 *
222 * @returns VBox status code.
223 * @param pThis The UART core instance.
224 * @param uReg The register offset (byte offset) to start reading from.
225 * @param pu32 Where to store the read value.
226 * @param cb Number of bytes to read.
227 */
228DECLHIDDEN(int) uartRegRead(PUARTCORE pThis, uint32_t uReg, uint32_t *pu32, size_t cb);
229
230# ifdef IN_RING3
231/**
232 * Initializes the given UART core instance using the provided configuration.
233 *
234 * @returns VBox status code.
235 * @param pThis The UART core instance to initialize.
236 * @param pDevInsR3 The R3 device instance pointer.
237 * @param enmType The type of UART emulated.
238 * @param iLUN The LUN the UART should look for attached drivers.
239 * @param fFlags Additional flags controlling device behavior.
240 * @param pfnUartIrqReqR3 Pointer to the R3 interrupt request callback.
241 * @param pfnUartIrqReqR0 Pointer to the R0 interrupt request callback.
242 * @param pfnUartIrqReqRC Pointer to the RC interrupt request callback.
243 */
244DECLHIDDEN(int) uartR3Init(PUARTCORE pThis, PPDMDEVINS pDevInsR3, UARTTYPE enmType, unsigned iLUN, uint32_t fFlags,
245 R3PTRTYPE(PFNUARTCOREIRQREQ) pfnUartIrqReqR3, R0PTRTYPE(PFNUARTCOREIRQREQ) pfnUartIrqReqR0,
246 RCPTRTYPE(PFNUARTCOREIRQREQ) pfnUartIrqReqRC);
247
248/**
249 * Destroys the given UART core instance freeing all allocated resources.
250 *
251 * @returns nothing.
252 * @param pThis The UART core instance.
253 */
254DECLHIDDEN(void) uartR3Destruct(PUARTCORE pThis);
255
256/**
257 * Detaches any attached driver from the given UART core instance.
258 *
259 * @returns nothing.
260 * @param pThis The UART core instance.
261 */
262DECLHIDDEN(void) uartR3Detach(PUARTCORE pThis);
263
264/**
265 * Attaches the given UART core instance to the drivers at the given LUN.
266 *
267 * @returns VBox status code.
268 * @param pThis The UART core instance.
269 * @param iLUN The LUN being attached.
270 */
271DECLHIDDEN(int) uartR3Attach(PUARTCORE pThis, unsigned iLUN);
272
273/**
274 * Resets the given UART core instance.
275 *
276 * @returns nothing.
277 * @param pThis The UART core instance.
278 */
279DECLHIDDEN(void) uartR3Reset(PUARTCORE pThis);
280
281/**
282 * Relocates an RC pointers of the given UART core instance
283 *
284 * @returns nothing.
285 * @param pThis The UART core instance.
286 * @param offDelta The delta to relocate RC pointers with.
287 */
288DECLHIDDEN(void) uartR3Relocate(PUARTCORE pThis, RTGCINTPTR offDelta);
289
290/**
291 * Saves the UART state to the given SSM handle.
292 *
293 * @returns VBox status code.
294 * @param pThis The UART core instance.
295 * @param pSSM The SSM handle to save to.
296 */
297DECLHIDDEN(int) uartR3SaveExec(PUARTCORE pThis, PSSMHANDLE pSSM);
298
299/**
300 * Loads the UART state from the given SSM handle.
301 *
302 * @returns VBox status code.
303 * @param pThis The UART core instance.
304 * @param pSSM The SSM handle to load from.
305 * @param uVersion Saved state version.
306 * @param uPass The SSM pass the call is done in.
307 * @param puIrq Where to store the IRQ value for legacy
308 * saved states - optional.
309 * @param pPortBase Where to store the I/O port base for legacy
310 * saved states - optional.
311 */
312DECLHIDDEN(int) uartR3LoadExec(PUARTCORE pThis, PSSMHANDLE pSSM, uint32_t uVersion, uint32_t uPass,
313 uint8_t *puIrq, RTIOPORT *pPortBase);
314
315/**
316 * Called when loading the state completed, updates the parameters of any driver underneath.
317 *
318 * @returns VBox status code.
319 * @param pThis The UART core instance.
320 * @param pSSM The SSM handle.
321 */
322DECLHIDDEN(int) uartR3LoadDone(PUARTCORE pThis, PSSMHANDLE pSSM);
323
324# endif
325
326#endif
327
328RT_C_DECLS_END
329
330#endif
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette