drivers/net/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  * SPDX-License-Identifier:     BSD-3-Clause
  34  * @par
  35  * -- End of Copyright Notice --
  36 */
  37
  38 /**
  39  * @defgroup IxUARTAccAPI IXP400 UART Access (IxUARTAcc) API
  40  *
  41  * @brief IXP400 UARTAcc Driver Public API
  42  *
  43  * @{
  44  */
  45
  46
  47 /* Defaults */
  48
  49 /**
  50  * @defgroup DefaultDefines Defines for Default Values
  51  *
  52  * @brief Default values which can be used for UART configuration
  53  *
  54  * @sa ixUARTDev
  55  */
  56
  57 /**
  58  * @def IX_UART_DEF_OPTS
  59  *
  60  * @brief The default hardware options to set the UART to -
  61  * no flow control, 8 bit word, 1 stop bit, no parity
  62  *
  63  * @ingroup DefaultDefines
  64  */
  65 #define IX_UART_DEF_OPTS (CLOCAL | CS8)
  66
  67 /**
  68  * @def IX_UART_DEF_XMIT
  69  *
  70  * @brief The default UART FIFO size - must be no bigger than 64
  71  *
  72  * @ingroup DefaultDefines
  73  */
  74 #define IX_UART_DEF_XMIT 64
  75
  76 /**
  77  * @def IX_UART_DEF_BAUD
  78  *
  79  * @brief The default UART baud rate - 9600
  80  *
  81  * @ingroup DefaultDefines
  82  */
  83 #define IX_UART_DEF_BAUD 9600
  84
  85 /**
  86  * @def IX_UART_MIN_BAUD
  87  *
  88  * @brief The minimum UART baud rate - 9600
  89  *
  90  * @ingroup DefaultDefines
  91  */
  92 #define IX_UART_MIN_BAUD 9600
  93
  94 /**
  95  * @def IX_UART_MAX_BAUD
  96  *
  97  * @brief The maximum UART baud rate - 926100
  98  *
  99  * @ingroup DefaultDefines
 100  */
 101 #define IX_UART_MAX_BAUD 926100
 102
 103 /**
 104  * @def IX_UART_XTAL
 105  *
 106  * @brief The UART clock speed
 107  *
 108  * @ingroup DefaultDefines
 109  */
 110 #define IX_UART_XTAL 14745600
 111
 112
 113
 114 /* IOCTL commands (Request codes) */
 115
 116 /**
 117  * @defgroup IoctlCommandDefines Defines for IOCTL Commands
 118  *
 119  * @brief IOCTL Commands (Request codes) which can be used
 120  *        with @ref ixUARTIoctl
 121  */
 122
 123
 124 /**
 125  * @ingroup IoctlCommandDefines
 126  *
 127  * @def IX_BAUD_SET
 128  *
 129  * @brief Set the baud rate
 130  */
 131 #define IX_BAUD_SET     0
 132
 133 /**
 134  * @ingroup IoctlCommandDefines
 135  *
 136  * @def IX_BAUD_GET
 137  *
 138  * @brief Get the baud rate
 139  */
 140 #define IX_BAUD_GET     1
 141
 142 /**
 143  * @ingroup IoctlCommandDefines
 144  * @def IX_MODE_SET
 145  * @brief Set the UART mode of operation
 146  */
 147 #define IX_MODE_SET     2
 148
 149 /**
 150  * @ingroup IoctlCommandDefines
 151  *
 152  * @def IX_MODE_GET
 153  *
 154  * @brief Get the current UART mode of operation
 155  */
 156 #define IX_MODE_GET     3
 157
 158 /**
 159  * @ingroup IoctlCommandDefines
 160  *
 161  * @def IX_OPTS_SET
 162  *
 163  * @brief Set the UART device options
 164  */
 165 #define IX_OPTS_SET     4
 166
 167 /**
 168  * @ingroup IoctlCommandDefines
 169  *
 170  * @def IX_OPTS_GET
 171  *
 172  * @brief Get the UART device options
 173  */
 174 #define IX_OPTS_GET     5
 175
 176 /**
 177  * @ingroup IoctlCommandDefines
 178  *
 179  * @def IX_STATS_GET
 180  *
 181  * @brief Get the UART statistics
 182  */
 183 #define IX_STATS_GET    6
 184
 185
 186 /* POSIX style ioctl arguments */
 187
 188 /**
 189  * @defgroup IoctlArgDefines Defines for IOCTL Arguments
 190  *
 191  * @brief POSIX style IOCTL arguments which can be used
 192  *        with @ref ixUARTIoctl
 193  *
 194  * @sa ixUARTMode
 195  */
 196
 197
 198 /**
 199  * @ingroup IoctlArgDefines
 200  *
 201  * @def CLOCAL
 202  *
 203  * @brief Software flow control
 204  */
 205 #ifdef CLOCAL
 206 #undef CLOCAL
 207 #endif
 208 #define CLOCAL          0x1
 209
 210 /**
 211  * @ingroup IoctlArgDefines
 212  *
 213  * @def CREAD
 214  *
 215  * @brief Enable interrupt receiver
 216  */
 217 #ifdef CREAD
 218 #undef CREAD
 219 #endif
 220 #define CREAD           0x2
 221
 222 /**
 223  * @ingroup IoctlArgDefines
 224  *
 225  * @def CSIZE
 226  *
 227  * @brief Characters size
 228  */
 229 #ifdef CSIZE
 230 #undef CSIZE
 231 #endif
 232 #define CSIZE           0xc
 233
 234 /**
 235  * @ingroup IoctlArgDefines
 236  *
 237  * @def CS5
 238  *
 239  * @brief 5 bits
 240  */
 241 #ifdef CS5
 242 #undef CS5
 243 #endif
 244 #define CS5             0x0
 245
 246 /**
 247  * @ingroup IoctlArgDefines
 248  *
 249  * @def CS6
 250  *
 251  * @brief 6 bits
 252  */
 253 #ifdef CS6
 254 #undef CS6
 255 #endif
 256 #define CS6             0x4
 257
 258 /**
 259  * @ingroup IoctlArgDefines
 260  *
 261  * @def CS7
 262  *
 263  * @brief 7 bits
 264  */
 265 #ifdef CS7
 266 #undef CS7
 267 #endif
 268 #define CS7             0x8
 269
 270 /**
 271  * @ingroup IoctlArgDefines
 272  *
 273  * @def CS8
 274  *
 275  * @brief 8 bits
 276  */
 277 #ifdef CS8
 278 #undef CS8
 279 #endif
 280 #define CS8             0xc
 281
 282 /**
 283  * @ingroup IoctlArgDefines
 284  *
 285  * @def STOPB
 286  *
 287  * @brief Send two stop bits (else one)
 288  */
 289 #define STOPB           0x20
 290
 291 /**
 292  * @ingroup IoctlArgDefines
 293  *
 294  * @def PARENB
 295  *
 296  * @brief Parity detection enabled (else disabled)
 297  */
 298 #ifdef PARENB
 299 #undef PARENB
 300 #endif
 301 #define PARENB          0x40
 302
 303 /**
 304  * @ingroup IoctlArgDefines
 305  *
 306  * @def PARODD
 307  *
 308  * @brief Odd parity  (else even)
 309  */
 310 #ifdef PARODD
 311 #undef PARODD
 312 #endif
 313 #define PARODD          0x80
 314
 315 /**
 316  * @enum ixUARTMode
 317  * @brief The mode to set to UART to.
 318  */
 319 typedef enum
 320 {
 321     INTERRUPT=0,        /**< Interrupt mode */
 322     POLLED,             /**< Polled mode */
 323     LOOPBACK            /**< Loopback mode */
 324 } ixUARTMode;
 325
 326 /**
 327  * @struct ixUARTStats
 328  * @brief Statistics for the UART.
 329  */
 330 typedef struct
 331 {
 332     UINT32  rxCount;
 333     UINT32  txCount;
 334     UINT32  overrunErr;
 335     UINT32  parityErr;
 336     UINT32  framingErr;
 337     UINT32  breakErr;
 338 } ixUARTStats;
 339
 340 /**
 341  * @struct ixUARTDev
 342  * @brief Device descriptor for the UART.
 343  */
 344 typedef struct
 345 {
 346     UINT8 *addr;        /**< device base address */
 347     ixUARTMode mode;    /**< interrupt, polled or loopback */
 348     int baudRate;       /**< baud rate */
 349     int freq;           /**< UART clock frequency */
 350     int options;        /**< hardware options */
 351     int fifoSize;       /**< FIFO xmit size */
 352
 353     ixUARTStats   stats;        /**< device statistics */
 354 } ixUARTDev;
 355
 356 /**
 357  * @ingroup IxUARTAccAPI
 358  *
 359  * @fn IX_STATUS ixUARTInit(ixUARTDev* pUART)
 360  *
 361  * @param pUART @ref ixUARTDev [in] - pointer to UART structure describing our device.
 362  *
 363  * @brief Initialise the UART. This puts the chip in a quiescent state.
 364  *
 365  * @pre The base address for the UART must contain a valid value.
 366  *      Also the baud rate and hardware options must contain sensible values
 367  *      otherwise the defaults will be used as defined in ixUART.h
 368  *
 369  * @post UART is initialized and ready to send and receive data.
 370  *
 371  * @note This function should only be called once per device.
 372  *
 373  * @retval IX_SUCCESS - UART device successfully initialised.
 374  * @retval IX_FAIL - Critical error, device not initialised.
 375  ***************************************************************************/
 376 PUBLIC IX_STATUS ixUARTInit(ixUARTDev* pUART);
 377
 378 /**
 379  * @ingroup IxUARTAccAPI
 380  *
 381  * @fn IX_STATUS ixUARTPollOutput(ixUARTDev* pUART, int outChar)
 382  *
 383  * @param pUART @ref ixUARTDev [out] - pointer to UART structure describing our device.
 384  * @param outChar int [out] - character to transmit.
 385  *
 386  * @brief Transmit a character in polled mode.
 387  *
 388  * @pre UART device must be initialised.
 389  *
 390  * @retval IX_SUCCESS - character was successfully transmitted.
 391  * @retval IX_FAIL - output buffer is full (try again).
 392  ***************************************************************************/
 393 PUBLIC IX_STATUS ixUARTPollOutput(ixUARTDev* pUART, int outChar);
 394
 395 /**
 396  * @ingroup IxUARTAccAPI
 397  *
 398  * @fn IX_STATUS ixUARTPollInput(ixUARTDev* pUART, char *inChar)
 399  *
 400  * @param pUART @ref ixUARTDev [in] - pointer to UART structure describing our device.
 401  * @param *inChar char [in] - character read from the device.
 402  *
 403  * @brief Receive a character in polled mode.
 404  *
 405  * @pre UART device must be initialised.
 406  *
 407  * @retval IX_SUCCESS - character was successfully read.
 408  * @retval IX_FAIL - input buffer empty (try again).
 409  ***************************************************************************/
 410 PUBLIC IX_STATUS ixUARTPollInput(ixUARTDev* pUART, char *inChar);
 411
 412 /**
 413  * @ingroup IxUARTAccAPI
 414  *
 415  * @fn IX_STATUS ixUARTIoctl(ixUARTDev* pUART, int cmd, void* arg)
 416  *
 417  * @param pUART @ref ixUARTDev [in] - pointer to UART structure describing our device.
 418  * @param cmd int [in] - an ioctl request code.
 419  * @param arg void* [in] - optional argument used to set the device mode,
 420  *       baud rate, and hardware options.
 421  *
 422  * @brief Perform I/O control routines on the device.
 423  *
 424  * @retval IX_SUCCESS - requested feature was set/read successfully.
 425  * @retval IX_FAIL - error setting/reading the requested feature.
 426  *
 427  * @sa IoctlCommandDefines
 428  * @sa IoctlArgDefines
 429  ***************************************************************************/
 430 PUBLIC IX_STATUS ixUARTIoctl(ixUARTDev* pUART, int cmd, void* arg);
 431
 432 /**
 433  * @} defgroup IxUARTAcc
 434  */