include/rtdm/rtserial.h

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