rtserial.h
1 /** 2 * @file 3 * Real-Time Driver Model for RTAI, serial device profile header 4 * 5 * @note Copyright (C) 2005-2007 Jan Kiszka <jan.kiszka@web.de> 6 * 7 * with adaptions for RTAI by Paolo Mantegazza <mantegazza@aero.polimi.it> 8 * 9 * RTAI is free software; you can redistribute it and/or modify it 10 * under the terms of the GNU General Public License as published by 11 * the Free Software Foundation; either version 2 of the License, or 12 * (at your option) any later version. 13 * 14 * RTAI is distributed in the hope that it will be useful, but 15 * WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 * General Public License for more details. 18 * 19 * You should have received a copy of the GNU General Public License 20 * along with RTAI; if not, write to the Free Software Foundation, 21 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 22 * 23 * @ingroup rtserial 24 */ 25 26 /*! 27 * @ingroup profiles 28 * @defgroup rtserial Serial Devices 29 * 30 * This is the common interface a RTDM-compliant serial device has to provide. 31 * Feel free to comment on this profile via the RTAI mailing list 32 * (rtai@rtai.org) or directly to the author (jan.kiszka@web.de). 33 * 34 * @b Profile @b Revision: 3 35 * @n 36 * @n 37 * @par Device Characteristics 38 * @ref rtdm_device.device_flags "Device Flags": @c RTDM_NAMED_DEVICE, @c RTDM_EXCLUSIVE @n 39 * @n 40 * @ref rtdm_device.device_name "Device Name": @c "rtser<N>", N >= 0 @n 41 * @n 42 * @ref rtdm_device.device_class "Device Class": @c RTDM_CLASS_SERIAL @n 43 * @n 44 * 45 * @par Supported Operations 46 * @b Open @n 47 * Environments: non-RT (RT optional, deprecated)@n 48 * Specific return values: none @n 49 * @n 50 * @b Close @n 51 * Environments: non-RT (RT optional, deprecated)@n 52 * Specific return values: none @n 53 * @n 54 * @b IOCTL @n 55 * Mandatory Environments: see @ref SERIOCTLs "below" @n 56 * Specific return values: see @ref SERIOCTLs "below" @n 57 * @n 58 * @b Read @n 59 * Environments: RT (non-RT optional)@n 60 * Specific return values: 61 * - -ETIMEDOUT 62 * - -EINTR (interrupted explicitly or by signal) 63 * - -EAGAIN (no data available in non-blocking mode) 64 * - -EBADF (device has been closed while reading) 65 * - -EIO (hardware error or broken bit stream) 66 * . 67 * @n 68 * @b Write @n 69 * Environments: RT (non-RT optional)@n 70 * Specific return values: 71 * - -ETIMEDOUT 72 * - -EINTR (interrupted explicitly or by signal) 73 * - -EAGAIN (no data written in non-blocking mode) 74 * - -EBADF (device has been closed while writing) 75 * 76 * @{ 77 */ 78 79 #ifndef _RTSERIAL_H 80 #define _RTSERIAL_H 81 82 #include <rtdm/rtdm.h> 83 84 #define RTSER_PROFILE_VER 3 85 86 /*! 87 * @anchor RTSER_DEF_BAUD @name RTSER_DEF_BAUD 88 * Default baud rate 89 * @{ */ 90 #define RTSER_DEF_BAUD 9600 91 /** @} */ 92 93 /*! 94 * @anchor RTSER_xxx_PARITY @name RTSER_xxx_PARITY 95 * Number of parity bits 96 * @{ */ 97 #define RTSER_NO_PARITY 0x00 98 #define RTSER_ODD_PARITY 0x01 99 #define RTSER_EVEN_PARITY 0x03 100 #define RTSER_DEF_PARITY RTSER_NO_PARITY 101 /** @} */ 102 103 /*! 104 * @anchor RTSER_xxx_BITS @name RTSER_xxx_BITS 105 * Number of data bits 106 * @{ */ 107 #define RTSER_5_BITS 0x00 108 #define RTSER_6_BITS 0x01 109 #define RTSER_7_BITS 0x02 110 #define RTSER_8_BITS 0x03 111 #define RTSER_DEF_BITS RTSER_8_BITS 112 /** @} */ 113 114 /*! 115 * @anchor RTSER_xxx_STOPB @name RTSER_xxx_STOPB 116 * Number of stop bits 117 * @{ */ 118 #define RTSER_1_STOPB 0x00 119 /** valid only in combination with 5 data bits */ 120 #define RTSER_1_5_STOPB 0x01 121 #define RTSER_2_STOPB 0x01 122 #define RTSER_DEF_STOPB RTSER_1_STOPB 123 /** @} */ 124 125 /*! 126 * @anchor RTSER_xxx_HAND @name RTSER_xxx_HAND 127 * Handshake mechanisms 128 * @{ */ 129 #define RTSER_NO_HAND 0x00 130 #define RTSER_RTSCTS_HAND 0x01 131 #define RTSER_DEF_HAND RTSER_NO_HAND 132 /** @} */ 133 134 /*! 135 * @anchor RTSER_RS485_xxx @name RTSER_RS485_xxx 136 * RS485 mode with automatic RTS handling 137 * @{ */ 138 #define RTSER_RS485_DISABLE 0x00 139 #define RTSER_RS485_ENABLE 0x01 140 #define RTSER_DEF_RS485 RTSER_RS485_DISABLE 141 /** @} */ 142 143 /*! 144 * @anchor RTSER_FIFO_xxx @name RTSER_FIFO_xxx 145 * Reception FIFO interrupt threshold 146 * @{ */ 147 #define RTSER_FIFO_DEPTH_1 0x00 148 #define RTSER_FIFO_DEPTH_4 0x40 149 #define RTSER_FIFO_DEPTH_8 0x80 150 #define RTSER_FIFO_DEPTH_14 0xC0 151 #define RTSER_DEF_FIFO_DEPTH RTSER_FIFO_DEPTH_1 152 /** @} */ 153 154 /*! 155 * @anchor RTSER_TIMEOUT_xxx @name RTSER_TIMEOUT_xxx 156 * Special timeout values, see also @ref RTDM_TIMEOUT_xxx 157 * @{ */ 158 #define RTSER_TIMEOUT_INFINITE RTDM_TIMEOUT_INFINITE 159 #define RTSER_TIMEOUT_NONE RTDM_TIMEOUT_NONE 160 #define RTSER_DEF_TIMEOUT RTDM_TIMEOUT_INFINITE 161 /** @} */ 162 163 /*! 164 * @anchor RTSER_xxx_TIMESTAMP_HISTORY @name RTSER_xxx_TIMESTAMP_HISTORY 165 * Timestamp history control 166 * @{ */ 167 #define RTSER_RX_TIMESTAMP_HISTORY 0x01 168 #define RTSER_DEF_TIMESTAMP_HISTORY 0x00 169 /** @} */ 170 171 /*! 172 * @anchor RTSER_EVENT_xxx @name RTSER_EVENT_xxx 173 * Events bits 174 * @{ */ 175 #define RTSER_EVENT_RXPEND 0x01 176 #define RTSER_EVENT_ERRPEND 0x02 177 #define RTSER_EVENT_MODEMHI 0x04 178 #define RTSER_EVENT_MODEMLO 0x08 179 #define RTSER_EVENT_TXEMPTY 0x10 180 #define RTSER_DEF_EVENT_MASK 0x00 181 /** @} */ 182 183 184 /*! 185 * @anchor RTSER_SET_xxx @name RTSER_SET_xxx 186 * Configuration mask bits 187 * @{ */ 188 #define RTSER_SET_BAUD 0x0001 189 #define RTSER_SET_PARITY 0x0002 190 #define RTSER_SET_DATA_BITS 0x0004 191 #define RTSER_SET_STOP_BITS 0x0008 192 #define RTSER_SET_HANDSHAKE 0x0010 193 #define RTSER_SET_FIFO_DEPTH 0x0020 194 #define RTSER_SET_TIMEOUT_RX 0x0100 195 #define RTSER_SET_TIMEOUT_TX 0x0200 196 #define RTSER_SET_TIMEOUT_EVENT 0x0400 197 #define RTSER_SET_TIMESTAMP_HISTORY 0x0800 198 #define RTSER_SET_EVENT_MASK 0x1000 199 #define RTSER_SET_RS485 0x2000 200 /** @} */ 201 202 203 /*! 204 * @anchor RTSER_LSR_xxx @name RTSER_LSR_xxx 205 * Line status bits 206 * @{ */ 207 #define RTSER_LSR_DATA 0x01 208 #define RTSER_LSR_OVERRUN_ERR 0x02 209 #define RTSER_LSR_PARITY_ERR 0x04 210 #define RTSER_LSR_FRAMING_ERR 0x08 211 #define RTSER_LSR_BREAK_IND 0x10 212 #define RTSER_LSR_THR_EMTPY 0x20 213 #define RTSER_LSR_TRANSM_EMPTY 0x40 214 #define RTSER_LSR_FIFO_ERR 0x80 215 #define RTSER_SOFT_OVERRUN_ERR 0x0100 216 /** @} */ 217 218 219 /*! 220 * @anchor RTSER_MSR_xxx @name RTSER_MSR_xxx 221 * Modem status bits 222 * @{ */ 223 #define RTSER_MSR_DCTS 0x01 224 #define RTSER_MSR_DDSR 0x02 225 #define RTSER_MSR_TERI 0x04 226 #define RTSER_MSR_DDCD 0x08 227 #define RTSER_MSR_CTS 0x10 228 #define RTSER_MSR_DSR 0x20 229 #define RTSER_MSR_RI 0x40 230 #define RTSER_MSR_DCD 0x80 231 /** @} */ 232 233 234 /*! 235 * @anchor RTSER_MCR_xxx @name RTSER_MCR_xxx 236 * Modem control bits 237 * @{ */ 238 #define RTSER_MCR_DTR 0x01 239 #define RTSER_MCR_RTS 0x02 240 #define RTSER_MCR_OUT1 0x04 241 #define RTSER_MCR_OUT2 0x08 242 #define RTSER_MCR_LOOP 0x10 243 /** @} */ 244 245 246 /*! 247 * @anchor RTSER_BREAK_xxx @name RTSER_BREAK_xxx 248 * Break control 249 * @{ */ 250 #define RTSER_BREAK_CLR 0x00 251 #define RTSER_BREAK_SET 0x01 252 253 254 /** 255 * Serial device configuration 256 */ 257 typedef struct rtser_config { 258 /** mask specifying valid fields, see @ref RTSER_SET_xxx */ 259 int config_mask; 260 261 /** baud rate, default @ref RTSER_DEF_BAUD */ 262 int baud_rate; 263 264 /** number of parity bits, see @ref RTSER_xxx_PARITY */ 265 int parity; 266 267 /** number of data bits, see @ref RTSER_xxx_BITS */ 268 int data_bits; 269 270 /** number of stop bits, see @ref RTSER_xxx_STOPB */ 271 int stop_bits; 272 273 /** handshake mechanisms, see @ref RTSER_xxx_HAND */ 274 int handshake; 275 276 /** reception FIFO interrupt threshold, see @ref RTSER_FIFO_xxx */ 277 int fifo_depth; 278 279 int reserved; 280 281 /** reception timeout, see @ref RTSER_TIMEOUT_xxx for special 282 * values */ 283 nanosecs_rel_t rx_timeout; 284 285 /** transmission timeout, see @ref RTSER_TIMEOUT_xxx for special 286 * values */ 287 nanosecs_rel_t tx_timeout; 288 289 /** event timeout, see @ref RTSER_TIMEOUT_xxx for special values */ 290 nanosecs_rel_t event_timeout; 291 292 /** enable timestamp history, see @ref RTSER_xxx_TIMESTAMP_HISTORY */ 293 int timestamp_history; 294 295 /** event mask to be used with @ref RTSER_RTIOC_WAIT_EVENT, see 296 * @ref RTSER_EVENT_xxx */ 297 int event_mask; 298 299 /** enable RS485 mode, see @ref RTSER_RS485_xxx */ 300 int rs485; 301 } rtser_config_t; 302 303 /** 304 * Serial device status 305 */ 306 typedef struct rtser_status { 307 /** line status register, see @ref RTSER_LSR_xxx */ 308 int line_status; 309 310 /** modem status register, see @ref RTSER_MSR_xxx */ 311 int modem_status; 312 } rtser_status_t; 313 314 /** 315 * Additional information about serial device events 316 */ 317 typedef struct rtser_event { 318 /** signalled events, see @ref RTSER_EVENT_xxx */ 319 int events; 320 321 /** number of pending input characters */ 322 int rx_pending; 323 324 /** last interrupt timestamp */ 325 nanosecs_abs_t last_timestamp; 326 327 /** reception timestamp of oldest character in input queue */ 328 nanosecs_abs_t rxpend_timestamp; 329 } rtser_event_t; 330 331 332 #define RTIOC_TYPE_SERIAL RTDM_CLASS_SERIAL 333 334 335 /*! 336 * @name Sub-Classes of RTDM_CLASS_SERIAL 337 * @{ */ 338 #define RTDM_SUBCLASS_16550A 0 339 /** @} */ 340 341 342 /*! 343 * @anchor SERIOCTLs @name IOCTLs 344 * Serial device IOCTLs 345 * @{ */ 346 347 /** 348 * Get serial device configuration 349 * 350 * @param[out] arg Pointer to configuration buffer (struct rtser_config) 351 * 352 * @return 0 on success, otherwise negative error code 353 * 354 * Environments: 355 * 356 * This service can be called from: 357 * 358 * - Kernel module initialization/cleanup code 359 * - Kernel-based task 360 * - User-space task (RT, non-RT) 361 * 362 * Rescheduling: never. 363 */ 364 #define RTSER_RTIOC_GET_CONFIG \ 365 _IOR(RTIOC_TYPE_SERIAL, 0x00, struct rtser_config) 366 367 /** 368 * Set serial device configuration 369 * 370 * @param[in] arg Pointer to configuration buffer (struct rtser_config) 371 * 372 * @return 0 on success, otherwise: 373 * 374 * - -EPERM is returned if the caller's context is invalid, see note below. 375 * 376 * - -ENOMEM is returned if a new history buffer for timestamps cannot be 377 * allocated. 378 * 379 * Environments: 380 * 381 * This service can be called from: 382 * 383 * - Kernel module initialization/cleanup code 384 * - Kernel-based task 385 * - User-space task (RT, non-RT) 386 * 387 * @note If rtser_config contains a valid timestamp_history and the 388 * addressed device has been opened in non-real-time context, this IOCTL must 389 * be issued in non-real-time context as well. Otherwise, this command will 390 * fail. 391 * 392 * Rescheduling: never. 393 */ 394 #define RTSER_RTIOC_SET_CONFIG \ 395 _IOW(RTIOC_TYPE_SERIAL, 0x01, struct rtser_config) 396 397 /** 398 * Get serial device status 399 * 400 * @param[out] arg Pointer to status buffer (struct rtser_status) 401 * 402 * @return 0 on success, otherwise negative error code 403 * 404 * Environments: 405 * 406 * This service can be called from: 407 * 408 * - Kernel module initialization/cleanup code 409 * - Kernel-based task 410 * - User-space task (RT, non-RT) 411 * 412 * @note The error states @c RTSER_LSR_OVERRUN_ERR, @c RTSER_LSR_PARITY_ERR, 413 * @c RTSER_LSR_FRAMING_ERR, and @c RTSER_SOFT_OVERRUN_ERR that may have 414 * occured during previous read accesses to the device will be saved for being 415 * reported via this IOCTL. Upon return from @c RTSER_RTIOC_GET_STATUS, the 416 * saved state will be cleared. 417 * 418 * Rescheduling: never. 419 */ 420 #define RTSER_RTIOC_GET_STATUS \ 421 _IOR(RTIOC_TYPE_SERIAL, 0x02, struct rtser_status) 422 423 /** 424 * Get serial device's modem contol register 425 * 426 * @param[out] arg Pointer to variable receiving the content (int, see 427 * @ref RTSER_MCR_xxx) 428 * 429 * @return 0 on success, otherwise negative error code 430 * 431 * Environments: 432 * 433 * This service can be called from: 434 * 435 * - Kernel module initialization/cleanup code 436 * - Kernel-based task 437 * - User-space task (RT, non-RT) 438 * 439 * Rescheduling: never. 440 */ 441 #define RTSER_RTIOC_GET_CONTROL \ 442 _IOR(RTIOC_TYPE_SERIAL, 0x03, int) 443 444 /** 445 * Set serial device's modem contol register 446 * 447 * @param[in] arg New control register content (int, see @ref RTSER_MCR_xxx) 448 * 449 * @return 0 on success, otherwise negative error code 450 * 451 * Environments: 452 * 453 * This service can be called from: 454 * 455 * - Kernel module initialization/cleanup code 456 * - Kernel-based task 457 * - User-space task (RT, non-RT) 458 * 459 * Rescheduling: never. 460 */ 461 #define RTSER_RTIOC_SET_CONTROL \ 462 _IOW(RTIOC_TYPE_SERIAL, 0x04, int) 463 464 /** 465 * Wait on serial device events according to previously set mask 466 * 467 * @param[out] arg Pointer to event information buffer (struct rtser_event) 468 * 469 * @return 0 on success, otherwise: 470 * 471 * - -EBUSY is returned if another task is already waiting on events of this 472 * device. 473 * 474 * - -EBADF is returned if the file descriptor is invalid or the device has 475 * just been closed. 476 * 477 * Environments: 478 * 479 * This service can be called from: 480 * 481 * - Kernel-based task 482 * - User-space task (RT) 483 * 484 * Rescheduling: possible. 485 */ 486 #define RTSER_RTIOC_WAIT_EVENT \ 487 _IOR(RTIOC_TYPE_SERIAL, 0x05, struct rtser_event) 488 /** @} */ 489 490 /** 491 * Set or clear break on UART output line 492 * 493 * @param[in] arg @c RTSER_BREAK_SET or @c RTSER_BREAK_CLR (int) 494 * 495 * @return 0 on success, otherwise negative error code 496 * 497 * Environments: 498 * 499 * This service can be called from: 500 * 501 * - Kernel module initialization/cleanup code 502 * - Kernel-based task 503 * - User-space task (RT, non-RT) 504 * 505 * @note A set break condition may also be cleared on UART line 506 * reconfiguration. 507 * 508 * Rescheduling: never. 509 */ 510 #define RTSER_RTIOC_BREAK_CTL \ 511 _IOR(RTIOC_TYPE_SERIAL, 0x06, int) 512 /** @} */ 513 514 /*! 515 * @anchor SERutils @name RT Serial example and utility programs 516 * @{ */ 517 /** @example cross-link.c */ 518 /** @} */ 519 520 /** @} */ 521 522 #endif /* _RTSERIAL_H */