VirtualBox

source: vbox/trunk/include/iprt/serialport.h

Last change on this file was 98103, checked in by vboxsync, 16 months ago

Copyright year updates by scm.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 13.7 KB
Line 
1/** @file
2 * IPRT Serial Port API.
3 */
4
5/*
6 * Copyright (C) 2017-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_serialport_h
37#define IPRT_INCLUDED_serialport_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/types.h>
43
44RT_C_DECLS_BEGIN
45
46/** @defgroup grp_rt_serial IPRT Serial Port API
47 * @ingroup grp_rt
48 *
49 * The IPRT serial port API provides a platform independent API to control a
50 * serial port of the host. It supports receiving/transmitting data as well as
51 * controlling and monitoring the status lines of a standard serial port.
52 *
53 * The user of the API is currently resposible for serializing calls to it.
54 * The only exception is RTSerialPortEvtPollInterrupt() which can be called on
55 * any thread to interrupt another thread waiting in RTSerialPortEvtPoll().
56 *
57 * @{
58 */
59
60/** Serial Port handle. */
61typedef struct RTSERIALPORTINTERNAL *RTSERIALPORT;
62/** Pointer to a Serial Port handle. */
63typedef RTSERIALPORT *PRTSERIALPORT;
64/** NIL Serial Port handle value. */
65#define NIL_RTSERIALPORT ((RTSERIALPORT)0)
66
67
68/**
69 * Supported parity settings.
70 */
71typedef enum RTSERIALPORTPARITY
72{
73 /** Invalid parity setting. */
74 RTSERIALPORTPARITY_INVALID = 0,
75 /** No parity used. */
76 RTSERIALPORTPARITY_NONE,
77 /** Even parity used. */
78 RTSERIALPORTPARITY_EVEN,
79 /** Odd parity used. */
80 RTSERIALPORTPARITY_ODD,
81 /** Mark parity (parity bit always 1) used. */
82 RTSERIALPORTPARITY_MARK,
83 /** Space parity (parity bit always 0) used. */
84 RTSERIALPORTPARITY_SPACE,
85 /** 32bit hack. */
86 RTSERIALPORTPARITY_32BIT_HACK = 0x7fffffff
87} RTSERIALPORTPARITY;
88
89
90/**
91 * Supported data bit count setting.
92 */
93typedef enum RTSERIALPORTDATABITS
94{
95 /** Invalid bitcount setting. */
96 RTSERIALPORTDATABITS_INVALID = 0,
97 /** 5 data bits. */
98 RTSERIALPORTDATABITS_5BITS,
99 /** 6 data bits. */
100 RTSERIALPORTDATABITS_6BITS,
101 /** 7 data bits. */
102 RTSERIALPORTDATABITS_7BITS,
103 /** 8 data bits. */
104 RTSERIALPORTDATABITS_8BITS,
105 /** 32bit hack. */
106 RTSERIALPORTDATABITS_32BIT_HACK = 0x7fffffff
107} RTSERIALPORTDATABITS;
108
109
110/**
111 * Supported stop bit setting.
112 */
113typedef enum RTSERIALPORTSTOPBITS
114{
115 /** Invalid stop bit setting. */
116 RTSERIALPORTSTOPBITS_INVALID = 0,
117 /** One stop bit is used. */
118 RTSERIALPORTSTOPBITS_ONE,
119 /** 1.5 stop bits are used. */
120 RTSERIALPORTSTOPBITS_ONEPOINTFIVE,
121 /** 2 stop bits are used. */
122 RTSERIALPORTSTOPBITS_TWO,
123 /** 32bit hack. */
124 RTSERIALPORTSTOPBITS_32BIT_HACK = 0x7fffffff
125} RTSERIALPORTSTOPBITS;
126
127
128/**
129 * Serial port config structure.
130 */
131typedef struct RTSERIALPORTCFG
132{
133 /** Baud rate. */
134 uint32_t uBaudRate;
135 /** Used parity. */
136 RTSERIALPORTPARITY enmParity;
137 /** Number of data bits. */
138 RTSERIALPORTDATABITS enmDataBitCount;
139 /** Number of stop bits. */
140 RTSERIALPORTSTOPBITS enmStopBitCount;
141} RTSERIALPORTCFG;
142/** Pointer to a serial port config. */
143typedef RTSERIALPORTCFG *PRTSERIALPORTCFG;
144/** Pointer to a const serial port config. */
145typedef const RTSERIALPORTCFG *PCRTSERIALPORTCFG;
146
147
148/** @name RTSerialPortOpen flags
149 * @{ */
150/** Open the serial port with the receiver enabled to receive data. */
151#define RTSERIALPORT_OPEN_F_READ RT_BIT(0)
152/** Open the serial port with the transmitter enabled to transmit data. */
153#define RTSERIALPORT_OPEN_F_WRITE RT_BIT(1)
154/** Open the serial port with status line monitoring enabled to get notified about status line changes. */
155#define RTSERIALPORT_OPEN_F_SUPPORT_STATUS_LINE_MONITORING RT_BIT(2)
156/** Open the serial port with BREAK condition detection enabled (Requires extra work on some hosts). */
157#define RTSERIALPORT_OPEN_F_DETECT_BREAK_CONDITION RT_BIT(3)
158/** Open the serial port with loopback mode enabled. */
159#define RTSERIALPORT_OPEN_F_ENABLE_LOOPBACK RT_BIT(4)
160/** Bitmask of valid flags. */
161#define RTSERIALPORT_OPEN_F_VALID_MASK UINT32_C(0x0000001f)
162/** @} */
163
164
165/** @name RTSerialPortChgModemLines flags
166 * @{ */
167/** Change the RTS (Ready To Send) line signal. */
168#define RTSERIALPORT_CHG_STS_LINES_F_RTS RT_BIT(0)
169/** Change the DTR (Data Terminal Ready) line signal. */
170#define RTSERIALPORT_CHG_STS_LINES_F_DTR RT_BIT(1)
171/** Bitmask of valid flags. */
172#define RTSERIALPORT_CHG_STS_LINES_F_VALID_MASK UINT32_C(0x00000003)
173/** @} */
174
175
176/** @name RTSerialPortQueryStatusLines flags
177 * @{ */
178/** The DCD (Data Carrier Detect) signal is active. */
179#define RTSERIALPORT_STS_LINE_DCD RT_BIT(0)
180/** The RI (Ring Indicator) signal is active. */
181#define RTSERIALPORT_STS_LINE_RI RT_BIT(1)
182/** The DSR (Data Set Ready) signal is active. */
183#define RTSERIALPORT_STS_LINE_DSR RT_BIT(2)
184/** The CTS (Clear To Send) signal is active. */
185#define RTSERIALPORT_STS_LINE_CTS RT_BIT(3)
186/** @} */
187
188
189/** @name RTSerialPortEvtPoll flags
190 * @{ */
191/** Data was received and can be read. */
192#define RTSERIALPORT_EVT_F_DATA_RX RT_BIT(0)
193/** All data was transmitted and there is room again in the transmit buffer. */
194#define RTSERIALPORT_EVT_F_DATA_TX RT_BIT(1)
195/** A BREAK condition was detected on the communication channel.
196 * Only available when BREAK condition detection was enabled when opening the serial port .*/
197#define RTSERIALPORT_EVT_F_BREAK_DETECTED RT_BIT(2)
198/** One of the monitored status lines changed, check with RTSerialPortQueryStatusLines().
199 * Only available if status line monitoring was enabled when opening the serial port. */
200#define RTSERIALPORT_EVT_F_STATUS_LINE_CHANGED RT_BIT(3)
201/** Status line monitor failed with an error and status line monitoring is disabled,
202 * this cannot be given in the event mask but will be set if status line
203 * monitoring is enabled and the monitor failed. */
204#define RTSERIALPORT_EVT_F_STATUS_LINE_MONITOR_FAILED RT_BIT(4)
205/** Bitmask of valid flags. */
206#define RTSERIALPORT_EVT_F_VALID_MASK UINT32_C(0x0000001f)
207/** @} */
208
209
210/**
211 * Opens a serial port with the specified flags.
212 *
213 * @returns IPRT status code.
214 * @param phSerialPort Where to store the IPRT serial port handle on success.
215 * @param pszPortAddress The address of the serial port (host dependent).
216 * @param fFlags Flags to open the serial port with, see RTSERIALPORT_OPEN_F_*.
217 */
218RTDECL(int) RTSerialPortOpen(PRTSERIALPORT phSerialPort, const char *pszPortAddress, uint32_t fFlags);
219
220
221/**
222 * Closes the given serial port handle.
223 *
224 * @returns IPRT status code.
225 * @param hSerialPort The IPRT serial port handle.
226 */
227RTDECL(int) RTSerialPortClose(RTSERIALPORT hSerialPort);
228
229
230/**
231 * Gets the native handle for an IPRT serial port handle.
232 *
233 * @returns The native handle. -1 on failure.
234 * @param hSerialPort The IPRT serial port handle.
235 */
236RTDECL(RTHCINTPTR) RTSerialPortToNative(RTSERIALPORT hSerialPort);
237
238
239/**
240 * Tries to read the given number of bytes from the serial port, blocking version.
241 *
242 * @returns IPRT status code.
243 * @retval VERR_SERIALPORT_BREAK_DETECTED if a break was detected before the requested number of bytes was received.
244 * @param hSerialPort The IPRT serial port handle.
245 * @param pvBuf Where to store the read data.
246 * @param cbToRead How much to read from the serial port.
247 * @param pcbRead Where to store the number of bytes received until an error condition occurred, optional.
248 */
249RTDECL(int) RTSerialPortRead(RTSERIALPORT hSerialPort, void *pvBuf, size_t cbToRead, size_t *pcbRead);
250
251
252/**
253 * Tries to read the given number of bytes from the serial port, non-blocking version.
254 *
255 * @returns IPRT status code.
256 * @retval VERR_SERIALPORT_BREAK_DETECTED if a break was detected before anything could be received.
257 * @retval VINF_TRY_AGAIN if nothing could be read.
258 * @param hSerialPort The IPRT serial port handle.
259 * @param pvBuf Where to store the read data.
260 * @param cbToRead How much to read from the serial port.
261 * @param pcbRead Where to store the number of bytes received.
262 */
263RTDECL(int) RTSerialPortReadNB(RTSERIALPORT hSerialPort, void *pvBuf, size_t cbToRead, size_t *pcbRead);
264
265
266/**
267 * Writes the given data to the serial port, blocking version.
268 *
269 * @returns IPRT status code.
270 * @param hSerialPort The IPRT serial port handle.
271 * @param pvBuf The data to write.
272 * @param cbToWrite How much to write.
273 * @param pcbWritten Where to store the number of bytes written until an error condition occurred, optional.
274 */
275RTDECL(int) RTSerialPortWrite(RTSERIALPORT hSerialPort, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
276
277
278/**
279 * Writes the given data to the serial port, non-blocking version.
280 *
281 * @returns IPRT status code.
282 * @retval VINF_TRY_AGAIN if nothing could be written.
283 * @param hSerialPort The IPRT serial port handle.
284 * @param pvBuf The data to write.
285 * @param cbToWrite How much to write.
286 * @param pcbWritten Where to store the number of bytes written.
287 */
288RTDECL(int) RTSerialPortWriteNB(RTSERIALPORT hSerialPort, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
289
290
291/**
292 * Queries the current active serial port config.
293 *
294 * @returns IPRT status code.
295 * @param hSerialPort The IPRT serial port handle.
296 * @param pCfg Where to store the current active config.
297 */
298RTDECL(int) RTSerialPortCfgQueryCurrent(RTSERIALPORT hSerialPort, PRTSERIALPORTCFG pCfg);
299
300
301/**
302 * Change the serial port to the given config.
303 *
304 * @returns IPRT status code.
305 * @retval VERR_SERIALPORT_INVALID_BAUDRATE if the baud rate is not supported on the serial port.
306 * @param hSerialPort The IPRT serial port handle.
307 * @param pCfg The config to write.
308 * @param pErrInfo Where to store additional information on error, optional.
309 */
310RTDECL(int) RTSerialPortCfgSet(RTSERIALPORT hSerialPort, PCRTSERIALPORTCFG pCfg, PRTERRINFO pErrInfo);
311
312
313/**
314 * Poll for an event on the given serial port.
315 *
316 * @returns IPRT status code.
317 * @retval VERR_TIMEOUT if the timeout was reached before an event happened.
318 * @retval VERR_INTERRUPTED if another thread interrupted the polling through RTSerialPortEvtPollInterrupt().
319 * @param hSerialPort The IPRT serial port handle.
320 * @param fEvtMask The mask of events to receive, see RTSERIALPORT_EVT_F_*
321 * @param pfEvtsRecv Where to store the bitmask of events received.
322 * @param msTimeout Number of milliseconds to wait for an event.
323 */
324RTDECL(int) RTSerialPortEvtPoll(RTSERIALPORT hSerialPort, uint32_t fEvtMask, uint32_t *pfEvtsRecv,
325 RTMSINTERVAL msTimeout);
326
327
328/**
329 * Interrupt another thread currently polling for an event.
330 *
331 * @returns IPRT status code.
332 * @param hSerialPort The IPRT serial port handle.
333 *
334 * @note Any thread.
335 */
336RTDECL(int) RTSerialPortEvtPollInterrupt(RTSERIALPORT hSerialPort);
337
338
339/**
340 * Sets or clears a BREAK condition on the given serial port.
341 *
342 * @returns IPRT status code.
343 * @param hSerialPort The IPRT serial port handle.
344 * @param fSet Flag whether to set the BREAK condition or clear it.
345 */
346RTDECL(int) RTSerialPortChgBreakCondition(RTSERIALPORT hSerialPort, bool fSet);
347
348
349/**
350 * Modify the status lines of the given serial port.
351 *
352 * @returns IPRT status code.
353 * @param hSerialPort The IPRT serial port handle.
354 * @param fClear Combination of status lines to clear, see RTSERIALPORT_CHG_STS_LINES_F_*.
355 * @param fSet Combination of status lines to set, see RTSERIALPORT_CHG_STS_LINES_F_*.
356 *
357 * @note fClear takes precedence over fSet in case the same status line bit is set in both arguments.
358 */
359RTDECL(int) RTSerialPortChgStatusLines(RTSERIALPORT hSerialPort, uint32_t fClear, uint32_t fSet);
360
361
362/**
363 * Query the status of the status lines on the given serial port.
364 *
365 * @returns IPRT status code.
366 * @param hSerialPort The IPRT serial port handle.
367 * @param pfStsLines Where to store the bitmask of active status lines on success,
368 * see RTSERIALPORT_STS_LINE_*.
369 */
370RTDECL(int) RTSerialPortQueryStatusLines(RTSERIALPORT hSerialPort, uint32_t *pfStsLines);
371
372/** @} */
373
374RT_C_DECLS_END
375
376#endif /* !IPRT_INCLUDED_serialport_h */
377
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use