arch/arm/cpu/ixp/npe/include/IxUART.h

   1 /**
   2  * @file IxUART.h
   3  *
   4  * @date 12-OCT-01
   5  *
   6  * @brief Public header for the Intel IXP400 internal UART, generic driver.
   7  *
   8  * Design Notes:
   9  * This driver allows you to perform the following functions:
  10  *      Device Initialization,
  11  *      send/receive characters.
  12  *
  13  * Perform Uart IOCTL for the following:
  14  *      Set/Get the current baud rate,
  15  *      set parity,
  16  *      set the number of Stop bits,
  17  *      set the character Length (5,6,7,8),
  18  *      enable/disable Hardware flow control.
  19  *
  20  * Only Polled mode is supported for now.
  21  *
  22  *
  23  * @par
  24  * IXP400 SW Release version 2.0
  25  *
  26  * -- Copyright Notice --
  27  *
  28  * @par
  29  * Copyright 2001-2005, Intel Corporation.
  30  * All rights reserved.
  31  *
  32  * @par
  33  * Redistribution and use in source and binary forms, with or without
  34  * modification, are permitted provided that the following conditions
  35  * are met:
  36  * 1. Redistributions of source code must retain the above copyright
  37  *    notice, this list of conditions and the following disclaimer.
  38  * 2. Redistributions in binary form must reproduce the above copyright
  39  *    notice, this list of conditions and the following disclaimer in the
  40  *    documentation and/or other materials provided with the distribution.
  41  * 3. Neither the name of the Intel Corporation nor the names of its contributors
  42  *    may be used to endorse or promote products derived from this software
  43  *    without specific prior written permission.
  44  *
  45  * @par
  46  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
  47  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  48  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  49  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
  50  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  51  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  52  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  53  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  54  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  55  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  56  * SUCH DAMAGE.
  57  *
  58  * @par
  59  * -- End of Copyright Notice --
  60 */
  61
  62 /**
  63  * @defgroup IxUARTAccAPI IXP400 UART Access (IxUARTAcc) API
  64  *
  65  * @brief IXP400 UARTAcc Driver Public API
  66  *
  67  * @{
  68  */
  69
  70
  71 /* Defaults */
  72
  73 /**
  74  * @defgroup DefaultDefines Defines for Default Values
  75  *
  76  * @brief Default values which can be used for UART configuration
  77  *
  78  * @sa ixUARTDev
  79  */
  80
  81 /**
  82  * @def IX_UART_DEF_OPTS
  83  *
  84  * @brief The default hardware options to set the UART to -
  85  * no flow control, 8 bit word, 1 stop bit, no parity
  86  *
  87  * @ingroup DefaultDefines
  88  */
  89 #define IX_UART_DEF_OPTS (CLOCAL | CS8)
  90
  91 /**
  92  * @def IX_UART_DEF_XMIT
  93  *
  94  * @brief The default UART FIFO size - must be no bigger than 64
  95  *
  96  * @ingroup DefaultDefines
  97  */
  98 #define IX_UART_DEF_XMIT 64
  99
 100 /**
 101  * @def IX_UART_DEF_BAUD
 102  *
 103  * @brief The default UART baud rate - 9600
 104  *
 105  * @ingroup DefaultDefines
 106  */
 107 #define IX_UART_DEF_BAUD 9600
 108
 109 /**
 110  * @def IX_UART_MIN_BAUD
 111  *
 112  * @brief The minimum UART baud rate - 9600
 113  *
 114  * @ingroup DefaultDefines
 115  */
 116 #define IX_UART_MIN_BAUD 9600
 117
 118 /**
 119  * @def IX_UART_MAX_BAUD
 120  *
 121  * @brief The maximum UART baud rate - 926100
 122  *
 123  * @ingroup DefaultDefines
 124  */
 125 #define IX_UART_MAX_BAUD 926100
 126
 127 /**
 128  * @def IX_UART_XTAL
 129  *
 130  * @brief The UART clock speed
 131  *
 132  * @ingroup DefaultDefines
 133  */
 134 #define IX_UART_XTAL 14745600
 135
 136
 137
 138 /* IOCTL commands (Request codes) */
 139
 140 /**
 141  * @defgroup IoctlCommandDefines Defines for IOCTL Commands
 142  *
 143  * @brief IOCTL Commands (Request codes) which can be used
 144  *        with @ref ixUARTIoctl
 145  */
 146
 147
 148 /**
 149  * @ingroup IoctlCommandDefines
 150  *
 151  * @def IX_BAUD_SET
 152  *
 153  * @brief Set the baud rate
 154  */
 155 #define IX_BAUD_SET     0
 156
 157 /**
 158  * @ingroup IoctlCommandDefines
 159  *
 160  * @def IX_BAUD_GET
 161  *
 162  * @brief Get the baud rate
 163  */
 164 #define IX_BAUD_GET     1
 165
 166 /**
 167  * @ingroup IoctlCommandDefines
 168  * @def IX_MODE_SET
 169  * @brief Set the UART mode of operation
 170  */
 171 #define IX_MODE_SET     2
 172
 173 /**
 174  * @ingroup IoctlCommandDefines
 175  *
 176  * @def IX_MODE_GET
 177  *
 178  * @brief Get the current UART mode of operation
 179  */
 180 #define IX_MODE_GET     3
 181
 182 /**
 183  * @ingroup IoctlCommandDefines
 184  *
 185  * @def IX_OPTS_SET
 186  *
 187  * @brief Set the UART device options
 188  */
 189 #define IX_OPTS_SET     4
 190
 191 /**
 192  * @ingroup IoctlCommandDefines
 193  *
 194  * @def IX_OPTS_GET
 195  *
 196  * @brief Get the UART device options
 197  */
 198 #define IX_OPTS_GET     5
 199
 200 /**
 201  * @ingroup IoctlCommandDefines
 202  *
 203  * @def IX_STATS_GET
 204  *
 205  * @brief Get the UART statistics
 206  */
 207 #define IX_STATS_GET    6
 208
 209
 210 /* POSIX style ioctl arguments */
 211
 212 /**
 213  * @defgroup IoctlArgDefines Defines for IOCTL Arguments
 214  *
 215  * @brief POSIX style IOCTL arguments which can be used
 216  *        with @ref ixUARTIoctl
 217  *
 218  * @sa ixUARTMode
 219  */
 220
 221
 222 /**
 223  * @ingroup IoctlArgDefines
 224  *
 225  * @def CLOCAL
 226  *
 227  * @brief Software flow control
 228  */
 229 #ifdef CLOCAL
 230 #undef CLOCAL
 231 #endif
 232 #define CLOCAL          0x1
 233
 234 /**
 235  * @ingroup IoctlArgDefines
 236  *
 237  * @def CREAD
 238  *
 239  * @brief Enable interrupt receiver
 240  */
 241 #ifdef CREAD
 242 #undef CREAD
 243 #endif
 244 #define CREAD           0x2
 245
 246 /**
 247  * @ingroup IoctlArgDefines
 248  *
 249  * @def CSIZE
 250  *
 251  * @brief Characters size
 252  */
 253 #ifdef CSIZE
 254 #undef CSIZE
 255 #endif
 256 #define CSIZE           0xc
 257
 258 /**
 259  * @ingroup IoctlArgDefines
 260  *
 261  * @def CS5
 262  *
 263  * @brief 5 bits
 264  */
 265 #ifdef CS5
 266 #undef CS5
 267 #endif
 268 #define CS5             0x0
 269
 270 /**
 271  * @ingroup IoctlArgDefines
 272  *
 273  * @def CS6
 274  *
 275  * @brief 6 bits
 276  */
 277 #ifdef CS6
 278 #undef CS6
 279 #endif
 280 #define CS6             0x4
 281
 282 /**
 283  * @ingroup IoctlArgDefines
 284  *
 285  * @def CS7
 286  *
 287  * @brief 7 bits
 288  */
 289 #ifdef CS7
 290 #undef CS7
 291 #endif
 292 #define CS7             0x8
 293
 294 /**
 295  * @ingroup IoctlArgDefines
 296  *
 297  * @def CS8
 298  *
 299  * @brief 8 bits
 300  */
 301 #ifdef CS8
 302 #undef CS8
 303 #endif
 304 #define CS8             0xc
 305
 306 /**
 307  * @ingroup IoctlArgDefines
 308  *
 309  * @def STOPB
 310  *
 311  * @brief Send two stop bits (else one)
 312  */
 313 #define STOPB           0x20
 314
 315 /**
 316  * @ingroup IoctlArgDefines
 317  *
 318  * @def PARENB
 319  *
 320  * @brief Parity detection enabled (else disabled)
 321  */
 322 #ifdef PARENB
 323 #undef PARENB
 324 #endif
 325 #define PARENB          0x40
 326
 327 /**
 328  * @ingroup IoctlArgDefines
 329  *
 330  * @def PARODD
 331  *
 332  * @brief Odd parity  (else even)
 333  */
 334 #ifdef PARODD
 335 #undef PARODD
 336 #endif
 337 #define PARODD          0x80
 338
 339 /**
 340  * @enum ixUARTMode
 341  * @brief The mode to set to UART to.
 342  */
 343 typedef enum
 344 {
 345     INTERRUPT=0,        /**< Interrupt mode */
 346     POLLED,             /**< Polled mode */
 347     LOOPBACK            /**< Loopback mode */
 348 } ixUARTMode;
 349
 350 /**
 351  * @struct ixUARTStats
 352  * @brief Statistics for the UART.
 353  */
 354 typedef struct
 355 {
 356     UINT32  rxCount;
 357     UINT32  txCount;
 358     UINT32  overrunErr;
 359     UINT32  parityErr;
 360     UINT32  framingErr;
 361     UINT32  breakErr;
 362 } ixUARTStats;
 363
 364 /**
 365  * @struct ixUARTDev
 366  * @brief Device descriptor for the UART.
 367  */
 368 typedef struct
 369 {
 370     UINT8 *addr;        /**< device base address */
 371     ixUARTMode mode;    /**< interrupt, polled or loopback */
 372     int baudRate;       /**< baud rate */
 373     int freq;           /**< UART clock frequency */
 374     int options;        /**< hardware options */
 375     int fifoSize;       /**< FIFO xmit size */
 376
 377     ixUARTStats   stats;        /**< device statistics */
 378 } ixUARTDev;
 379
 380 /**
 381  * @ingroup IxUARTAccAPI
 382  *
 383  * @fn IX_STATUS ixUARTInit(ixUARTDev* pUART)
 384  *
 385  * @param pUART @ref ixUARTDev [in] - pointer to UART structure describing our device.
 386  *
 387  * @brief Initialise the UART. This puts the chip in a quiescent state.
 388  *
 389  * @pre The base address for the UART must contain a valid value.
 390  *      Also the baud rate and hardware options must contain sensible values
 391  *      otherwise the defaults will be used as defined in ixUART.h
 392  *
 393  * @post UART is initialized and ready to send and receive data.
 394  *
 395  * @note This function should only be called once per device.
 396  *
 397  * @retval IX_SUCCESS - UART device successfully initialised.
 398  * @retval IX_FAIL - Critical error, device not initialised.
 399  ***************************************************************************/
 400 PUBLIC IX_STATUS ixUARTInit(ixUARTDev* pUART);
 401
 402 /**
 403  * @ingroup IxUARTAccAPI
 404  *
 405  * @fn IX_STATUS ixUARTPollOutput(ixUARTDev* pUART, int outChar)
 406  *
 407  * @param pUART @ref ixUARTDev [out] - pointer to UART structure describing our device.
 408  * @param outChar int [out] - character to transmit.
 409  *
 410  * @brief Transmit a character in polled mode.
 411  *
 412  * @pre UART device must be initialised.
 413  *
 414  * @retval IX_SUCCESS - character was successfully transmitted.
 415  * @retval IX_FAIL - output buffer is full (try again).
 416  ***************************************************************************/
 417 PUBLIC IX_STATUS ixUARTPollOutput(ixUARTDev* pUART, int outChar);
 418
 419 /**
 420  * @ingroup IxUARTAccAPI
 421  *
 422  * @fn IX_STATUS ixUARTPollInput(ixUARTDev* pUART, char *inChar)
 423  *
 424  * @param pUART @ref ixUARTDev [in] - pointer to UART structure describing our device.
 425  * @param *inChar char [in] - character read from the device.
 426  *
 427  * @brief Receive a character in polled mode.
 428  *
 429  * @pre UART device must be initialised.
 430  *
 431  * @retval IX_SUCCESS - character was successfully read.
 432  * @retval IX_FAIL - input buffer empty (try again).
 433  ***************************************************************************/
 434 PUBLIC IX_STATUS ixUARTPollInput(ixUARTDev* pUART, char *inChar);
 435
 436 /**
 437  * @ingroup IxUARTAccAPI
 438  *
 439  * @fn IX_STATUS ixUARTIoctl(ixUARTDev* pUART, int cmd, void* arg)
 440  *
 441  * @param pUART @ref ixUARTDev [in] - pointer to UART structure describing our device.
 442  * @param cmd int [in] - an ioctl request code.
 443  * @param arg void* [in] - optional argument used to set the device mode,
 444  *       baud rate, and hardware options.
 445  *
 446  * @brief Perform I/O control routines on the device.
 447  *
 448  * @retval IX_SUCCESS - requested feature was set/read successfully.
 449  * @retval IX_FAIL - error setting/reading the requested feature.
 450  *
 451  * @sa IoctlCommandDefines
 452  * @sa IoctlArgDefines
 453  ***************************************************************************/
 454 PUBLIC IX_STATUS ixUARTIoctl(ixUARTDev* pUART, int cmd, void* arg);
 455
 456 /**
 457  * @} defgroup IxUARTAcc
 458  */