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 */ 343typedef 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 */ 354typedef 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 */ 368typedef 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 ***************************************************************************/ 400PUBLIC 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 ***************************************************************************/ 417PUBLIC 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 ***************************************************************************/ 434PUBLIC 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 ***************************************************************************/ 454PUBLIC IX_STATUS ixUARTIoctl(ixUARTDev* pUART, int cmd, void* arg); 455 456/** 457 * @} defgroup IxUARTAcc 458 */ 459