VirtualBox

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

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

doxygen
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 9.2 KB
Line 
1/* $Id: UartCore.h 73136 2018-07-15 16:56:28Z 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/vmm/pdmdev.h>
23#include <VBox/vmm/pdmserialifs.h>
24#include <iprt/assert.h>
25
26RT_C_DECLS_BEGIN
27
28/*********************************************************************************************************************************
29* Defined Constants And Macros *
30*********************************************************************************************************************************/
31
32/** Size of a FIFO. */
33#define UART_FIFO_LENGTH 16
34
35
36/*********************************************************************************************************************************
37* Structures and Typedefs *
38*********************************************************************************************************************************/
39
40/** Pointer to the UART core state. */
41typedef struct UARTCORE *PUARTCORE;
42
43
44/**
45 * UART core IRQ request callback to let the core instance raise/clear interrupt requests.
46 *
47 * @returns nothing.
48 * @param pDevIns The owning device instance.
49 * @param pThis The UART core instance.
50 * @param iLUN The LUN associated with the UART core.
51 * @param iLvl The interrupt level.
52 */
53typedef DECLCALLBACK(void) FNUARTCOREIRQREQ(PPDMDEVINS pDevIns, PUARTCORE pThis, unsigned iLUN, int iLvl);
54/** Pointer to a UART core IRQ request callback. */
55typedef FNUARTCOREIRQREQ *PFNUARTCOREIRQREQ;
56
57
58/**
59 * UART type.
60 */
61typedef enum UARTTYPE
62{
63 /** Invalid UART type. */
64 UARTTYPE_INVALID = 0,
65 /** 16450 UART type. */
66 UARTTYPE_16450,
67 /** 16550A UART type. */
68 UARTTYPE_16550A,
69 /** 32bit hack. */
70 UARTTYPE_32BIT_HACK = 0x7fffffff
71} UARTTYPE;
72
73
74/**
75 * UART FIFO.
76 */
77typedef struct UARTFIFO
78{
79 /** Current amount of bytes used. */
80 uint8_t cbUsed;
81 /** Next index to write to. */
82 uint8_t offWrite;
83 /** Next index to read from. */
84 uint8_t offRead;
85 /** The interrupt trigger level (only used for the receive FIFO). */
86 uint8_t cbItl;
87 /** The data in the FIFO. */
88 uint8_t abBuf[UART_FIFO_LENGTH];
89} UARTFIFO;
90/** Pointer to a FIFO. */
91typedef UARTFIFO *PUARTFIFO;
92
93
94/**
95 * UART core device.
96 *
97 * @implements PDMIBASE
98 * @implements PDMISERIALPORT
99 */
100typedef struct UARTCORE
101{
102 /** Access critical section. */
103 PDMCRITSECT CritSect;
104 /** Pointer to the device instance - R3 Ptr. */
105 PPDMDEVINSR3 pDevInsR3;
106 /** Pointer to the device instance - R0 Ptr. */
107 PPDMDEVINSR0 pDevInsR0;
108 /** Pointer to the device instance - RC Ptr. */
109 PPDMDEVINSRC pDevInsRC;
110 /** The LUN on the owning device instance for this core. */
111 uint32_t iLUN;
112 /** LUN\#0: The base interface. */
113 PDMIBASE IBase;
114 /** LUN\#0: The serial port interface. */
115 PDMISERIALPORT ISerialPort;
116 /** Pointer to the attached base driver. */
117 R3PTRTYPE(PPDMIBASE) pDrvBase;
118 /** Pointer to the attached serial driver. */
119 R3PTRTYPE(PPDMISERIALCONNECTOR) pDrvSerial;
120 /** Configuration flags. */
121 uint32_t fFlags;
122 /** The selected UART type. */
123 UARTTYPE enmType;
124
125 /** R3 interrupt request callback of the owning device. */
126 R3PTRTYPE(PFNUARTCOREIRQREQ) pfnUartIrqReqR3;
127 /** R0 interrupt request callback of the owning device. */
128 R0PTRTYPE(PFNUARTCOREIRQREQ) pfnUartIrqReqR0;
129 /** RC interrupt request callback of the owning device. */
130 RCPTRTYPE(PFNUARTCOREIRQREQ) pfnUartIrqReqRC;
131
132 /** The divisor register (DLAB = 1). */
133 uint16_t uRegDivisor;
134 /** The Receiver Buffer Register (RBR, DLAB = 0). */
135 uint8_t uRegRbr;
136 /** The Transmitter Holding Register (THR, DLAB = 0). */
137 uint8_t uRegThr;
138 /** The Interrupt Enable Register (IER, DLAB = 0). */
139 uint8_t uRegIer;
140 /** The Interrupt Identification Register (IIR). */
141 uint8_t uRegIir;
142 /** The FIFO Control Register (FCR). */
143 uint8_t uRegFcr;
144 /** The Line Control Register (LCR). */
145 uint8_t uRegLcr;
146 /** The Modem Control Register (MCR). */
147 uint8_t uRegMcr;
148 /** The Line Status Register (LSR). */
149 uint8_t uRegLsr;
150 /** The Modem Status Register (MSR). */
151 uint8_t uRegMsr;
152 /** The Scratch Register (SCR). */
153 uint8_t uRegScr;
154
155 /** The transmit FIFO. */
156 UARTFIFO FifoXmit;
157 /** The receive FIFO. */
158 UARTFIFO FifoRecv;
159
160 /** Number of bytes available for reading from the layer below. */
161 volatile uint32_t cbAvailRdr;
162
163#if defined(IN_RC) || HC_ARCH_BITS == 32
164 uint32_t uAlignment;
165#endif
166} UARTCORE;
167
168AssertCompileSizeAlignment(UARTCORE, 8);
169
170
171#ifndef VBOX_DEVICE_STRUCT_TESTCASE
172
173/** Flag whether to yield the CPU on an LSR read. */
174#define UART_CORE_YIELD_ON_LSR_READ RT_BIT_32(0)
175
176/**
177 * Performs a register write to the given register offset.
178 *
179 * @returns VBox status code.
180 * @param pThis The UART core instance.
181 * @param uReg The register offset (byte offset) to start writing to.
182 * @param u32 The value to write.
183 * @param cb Number of bytes to write.
184 */
185DECLHIDDEN(int) uartRegWrite(PUARTCORE pThis, uint32_t uReg, uint32_t u32, size_t cb);
186
187/**
188 * Performs a register read from the given register offset.
189 *
190 * @returns VBox status code.
191 * @param pThis The UART core instance.
192 * @param uReg The register offset (byte offset) to start reading from.
193 * @param pu32 Where to store the read value.
194 * @param cb Number of bytes to read.
195 */
196DECLHIDDEN(int) uartRegRead(PUARTCORE pThis, uint32_t uReg, uint32_t *pu32, size_t cb);
197
198# ifdef IN_RING3
199/**
200 * Initializes the given UART core instance using the provided configuration.
201 *
202 * @returns VBox status code.
203 * @param pThis The UART core instance to initialize.
204 * @param pDevInsR3 The R3 device instance pointer.
205 * @param enmType The type of UART emulated.
206 * @param iLUN The LUN the UART should look for attached drivers.
207 * @param fFlags Additional flags controlling device behavior.
208 * @param pfnUartIrqReqR3 Pointer to the R3 interrupt request callback.
209 * @param pfnUartIrqReqR0 Pointer to the R0 interrupt request callback.
210 * @param pfnUartIrqReqRC Pointer to the RC interrupt request callback.
211 */
212DECLHIDDEN(int) uartR3Init(PUARTCORE pThis, PPDMDEVINS pDevInsR3, UARTTYPE enmType, unsigned iLUN, uint32_t fFlags,
213 R3PTRTYPE(PFNUARTCOREIRQREQ) pfnUartIrqReqR3, R0PTRTYPE(PFNUARTCOREIRQREQ) pfnUartIrqReqR0,
214 RCPTRTYPE(PFNUARTCOREIRQREQ) pfnUartIrqReqRC);
215
216/**
217 * Destroys the given UART core instance freeing all allocated resources.
218 *
219 * @returns nothing.
220 * @param pThis The UART core instance.
221 */
222DECLHIDDEN(void) uartR3Destruct(PUARTCORE pThis);
223
224/**
225 * Detaches any attached driver from the given UART core instance.
226 *
227 * @returns nothing.
228 * @param pThis The UART core instance.
229 */
230DECLHIDDEN(void) uartR3Detach(PUARTCORE pThis);
231
232/**
233 * Attaches the given UART core instance to the drivers at the given LUN.
234 *
235 * @returns VBox status code.
236 * @param pThis The UART core instance.
237 * @param iLUN The LUN being attached.
238 */
239DECLHIDDEN(int) uartR3Attach(PUARTCORE pThis, unsigned iLUN);
240
241/**
242 * Resets the given UART core instance.
243 *
244 * @returns nothing.
245 * @param pThis The UART core instance.
246 */
247DECLHIDDEN(void) uartR3Reset(PUARTCORE pThis);
248
249/**
250 * Relocates an RC pointers of the given UART core instance
251 *
252 * @returns nothing.
253 * @param pThis The UART core instance.
254 * @param offDelta The delta to relocate RC pointers with.
255 */
256DECLHIDDEN(void) uartR3Relocate(PUARTCORE pThis, RTGCINTPTR offDelta);
257
258# endif
259
260#endif
261
262RT_C_DECLS_END
263
264#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