doc/html/ref/io-tty-driver.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 > TTY driver</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="Serial driver details"
  23 HREF="io-serial-driver-details.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Serial driver details"
  26 HREF="io-serial-driver-details.html"><LINK
  27 REL="NEXT"
  28 TITLE="How to Write a Driver"
  29 HREF="io-how-to-write-a-driver.html"></HEAD
  30 ><BODY
  31 CLASS="SECTION"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="io-serial-driver-details.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 16. Serial driver details</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="io-how-to-write-a-driver.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECTION"
  82 ><H1
  83 CLASS="SECTION"
  84 ><A
  85 NAME="IO-TTY-DRIVER">TTY driver</H1
  86 ><P
  87 >Use the include file <TT
  88 CLASS="FILENAME"
  89 >&lt;cyg/io/ttyio.h&gt;</TT
  90 > for
  91 this driver.</P
  92 ><P
  93 >This driver is built on top of the simple
  94 serial driver and is typically used for a device that interfaces with
  95 humans such as a terminal. It provides some minimal formatting of data
  96 on output and allows for line-oriented editing on input.</P
  97 ><DIV
  98 CLASS="SECTION"
  99 ><H2
 100 CLASS="SECTION"
 101 ><A
 102 NAME="AEN10715">Runtime configuration</H2
 103 ><P
 104 >Runtime configuration is achieved by exchanging data structures with
 105 the driver via the <TT
 106 CLASS="FUNCTION"
 107 >cyg_io_set_config()</TT
 108 > and
 109 <TT
 110 CLASS="FUNCTION"
 111 >cyg_io_get_config()</TT
 112 > functions.</P
 113 ><TABLE
 114 BORDER="5"
 115 BGCOLOR="#E0E0F0"
 116 WIDTH="70%"
 117 ><TR
 118 ><TD
 119 ><PRE
 120 CLASS="PROGRAMLISTING"
 121 >typedef struct {
 122  cyg_uint32 tty_out_flags;
 123  cyg_uint32 tty_in_flags;
 124 } cyg_tty_info_t;</PRE
 125 ></TD
 126 ></TR
 127 ></TABLE
 128 ><P
 129 >The field <TT
 130 CLASS="STRUCTFIELD"
 131 ><I
 132 >tty_out_flags</I
 133 ></TT
 134 >
 135 is used to control what happens to data as it is send to the serial
 136 port. It contains a bitmap comprised of the bits as defined by the
 137 <TT
 138 CLASS="LITERAL"
 139 >CYG_TTY_OUT_FLAGS_xxx</TT
 140 > values below. </P
 141 ><TABLE
 142 BORDER="5"
 143 BGCOLOR="#E0E0F0"
 144 WIDTH="70%"
 145 ><TR
 146 ><TD
 147 ><PRE
 148 CLASS="PROGRAMLISTING"
 149 >#define CYG_TTY_OUT_FLAGS_CRLF 0x0001 // Map '\n' =&gt; '\n\r' on output</PRE
 150 ></TD
 151 ></TR
 152 ></TABLE
 153 ><P
 154 >If this bit is set in <TT
 155 CLASS="STRUCTFIELD"
 156 ><I
 157 >tty_out_flags</I
 158 ></TT
 159 >,
 160 any occurrence of the character &quot;\n&quot; will
 161 be replaced by the sequence &quot;\n\r&quot; before
 162 being sent to the device.</P
 163 ><P
 164 >The field <TT
 165 CLASS="STRUCTFIELD"
 166 ><I
 167 >tty_in_flags</I
 168 ></TT
 169 >
 170 is used to control how data is handled as it comes from the serial
 171 port. It contains a bitmap comprised of the bits as defined by the
 172 <TT
 173 CLASS="LITERAL"
 174 >CYG_TTY_IN_FLAGS_xxx</TT
 175 > values below. </P
 176 ><TABLE
 177 BORDER="5"
 178 BGCOLOR="#E0E0F0"
 179 WIDTH="70%"
 180 ><TR
 181 ><TD
 182 ><PRE
 183 CLASS="PROGRAMLISTING"
 184 >#define CYG_TTY_IN_FLAGS_CR 0x0001 // Map '\r' =&gt; '\n' on input</PRE
 185 ></TD
 186 ></TR
 187 ></TABLE
 188 ><P
 189 >If this bit is set in <TT
 190 CLASS="STRUCTFIELD"
 191 ><I
 192 >tty_in_flags</I
 193 ></TT
 194 >, the
 195 character &quot;\r&quot; (&#8220;return&#8221; or &#8220;enter&#8221; on
 196 most keyboards) will be mapped to &quot;\n&quot;.</P
 197 ><TABLE
 198 BORDER="5"
 199 BGCOLOR="#E0E0F0"
 200 WIDTH="70%"
 201 ><TR
 202 ><TD
 203 ><PRE
 204 CLASS="PROGRAMLISTING"
 205 >#define CYG_TTY_IN_FLAGS_CRLF 0x0002 // Map '\n\r' =&gt; '\n' on input</PRE
 206 ></TD
 207 ></TR
 208 ></TABLE
 209 ><P
 210 >If this bit is set in <TT
 211 CLASS="STRUCTFIELD"
 212 ><I
 213 >tty_in_flags</I
 214 ></TT
 215 >, the
 216 character sequence &quot;\n\r&quot; (often sent by DOS/Windows
 217 based terminals) will be mapped to &quot;\n&quot;. </P
 218 ><TABLE
 219 BORDER="5"
 220 BGCOLOR="#E0E0F0"
 221 WIDTH="70%"
 222 ><TR
 223 ><TD
 224 ><PRE
 225 CLASS="PROGRAMLISTING"
 226 >#define CYG_TTY_IN_FLAGS_BINARY 0x0004 // No input processing</PRE
 227 ></TD
 228 ></TR
 229 ></TABLE
 230 ><P
 231 >If this bit is set in <TT
 232 CLASS="STRUCTFIELD"
 233 ><I
 234 >tty_in_flags</I
 235 ></TT
 236 >, the
 237 input will not be manipulated in any way before being placed in
 238 the user&#8217;s buffer. </P
 239 ><TABLE
 240 BORDER="5"
 241 BGCOLOR="#E0E0F0"
 242 WIDTH="70%"
 243 ><TR
 244 ><TD
 245 ><PRE
 246 CLASS="PROGRAMLISTING"
 247 >#define CYG_TTY_IN_FLAGS_ECHO 0x0008 // Echo characters as processed</PRE
 248 ></TD
 249 ></TR
 250 ></TABLE
 251 ><P
 252 >If this bit is set in <TT
 253 CLASS="STRUCTFIELD"
 254 ><I
 255 >tty_in_flags</I
 256 ></TT
 257 >, characters
 258 will be echoed back to the serial port as they are processed. </P
 259 ></DIV
 260 ><DIV
 261 CLASS="SECTION"
 262 ><H2
 263 CLASS="SECTION"
 264 ><A
 265 NAME="AEN10742">API details</H2
 266 ><TABLE
 267 BORDER="5"
 268 BGCOLOR="#E0E0F0"
 269 WIDTH="70%"
 270 ><TR
 271 ><TD
 272 ><PRE
 273 CLASS="PROGRAMLISTING"
 274 >cyg_io_read(handle, buf, len)</PRE
 275 ></TD
 276 ></TR
 277 ></TABLE
 278 ><P
 279 >This function is used to read data from the device. In the
 280 default case, data is read until an end-of-line character ("\n"
 281 or "\r") is read. Additionally, the characters are echoed
 282 back to the [terminal] device. Minimal editing
 283 of the input is also supported. </P
 284 ><DIV
 285 CLASS="NOTE"
 286 ><BLOCKQUOTE
 287 CLASS="NOTE"
 288 ><P
 289 ><B
 290 >Note: </B
 291 >When connecting to a remote target via GDB it is not possible
 292 to provide console input while GDB is connected. The GDB remote
 293 protocol does not support input. Users must disconnect from GDB
 294 if this functionality is required.</P
 295 ></BLOCKQUOTE
 296 ></DIV
 297 ><TABLE
 298 BORDER="5"
 299 BGCOLOR="#E0E0F0"
 300 WIDTH="70%"
 301 ><TR
 302 ><TD
 303 ><PRE
 304 CLASS="PROGRAMLISTING"
 305 >
 306 cyg_io_write(handle, buf, len)</PRE
 307 ></TD
 308 ></TR
 309 ></TABLE
 310 ><P
 311 >This function is used to send data to the device. In the default
 312 case, the end-of-line character "\n" is replaced by the
 313 sequence "\n\r". </P
 314 ><TABLE
 315 BORDER="5"
 316 BGCOLOR="#E0E0F0"
 317 WIDTH="70%"
 318 ><TR
 319 ><TD
 320 ><PRE
 321 CLASS="PROGRAMLISTING"
 322 >cyg_io_get_config(handle, key, buf, len)</PRE
 323 ></TD
 324 ></TR
 325 ></TABLE
 326 ><P
 327 >This function is used to get information about the channel&#8217;s
 328 configuration at runtime. </P
 329 ><P
 330 ></P
 331 ><DIV
 332 CLASS="VARIABLELIST"
 333 ><DL
 334 ><DT
 335 ><TT
 336 CLASS="LITERAL"
 337 >CYG_IO_GET_CONFIG_TTY_INFO</TT
 338 ></DT
 339 ><DD
 340 ><P
 341 ></P
 342 ><DIV
 343 CLASS="VARIABLELIST"
 344 ><DL
 345 ><DT
 346 >Buf type:</DT
 347 ><DD
 348 ><P
 349 >cyg_tty_info_t</P
 350 ></DD
 351 ><DT
 352 >Function:</DT
 353 ><DD
 354 ><P
 355 >This function retrieves the current state of the
 356             driver.
 357             </P
 358 ></DD
 359 ></DL
 360 ></DIV
 361 ></DD
 362 ></DL
 363 ></DIV
 364 ><P
 365 >Serial driver keys (see above) may also be specified
 366 in which case the call is passed directly to the serial
 367 driver. </P
 368 ><TABLE
 369 BORDER="5"
 370 BGCOLOR="#E0E0F0"
 371 WIDTH="70%"
 372 ><TR
 373 ><TD
 374 ><PRE
 375 CLASS="PROGRAMLISTING"
 376 >cyg_io_set_config(handle, key, buf, len)</PRE
 377 ></TD
 378 ></TR
 379 ></TABLE
 380 ><P
 381 >This function is used to modify the channel&#8217;s configuration
 382 at runtime. </P
 383 ><P
 384 ></P
 385 ><DIV
 386 CLASS="VARIABLELIST"
 387 ><DL
 388 ><DT
 389 ><TT
 390 CLASS="LITERAL"
 391 >CYG_IO_SET_CONFIG_TTY_INFO</TT
 392 ></DT
 393 ><DD
 394 ><P
 395 ></P
 396 ><DIV
 397 CLASS="VARIABLELIST"
 398 ><DL
 399 ><DT
 400 >Buf type:</DT
 401 ><DD
 402 ><P
 403 >cyg_tty_info_t</P
 404 ></DD
 405 ><DT
 406 >Function:</DT
 407 ><DD
 408 ><P
 409 >This function changes the current state of the
 410             driver.</P
 411 ></DD
 412 ></DL
 413 ></DIV
 414 ></DD
 415 ></DL
 416 ></DIV
 417 ><P
 418 >Serial driver
 419 keys (see above) may also be specified in which case the
 420 call is passed directly to the serial driver. </P
 421 ></DIV
 422 ></DIV
 423 ><DIV
 424 CLASS="NAVFOOTER"
 425 ><HR
 426 ALIGN="LEFT"
 427 WIDTH="100%"><TABLE
 428 SUMMARY="Footer navigation table"
 429 WIDTH="100%"
 430 BORDER="0"
 431 CELLPADDING="0"
 432 CELLSPACING="0"
 433 ><TR
 434 ><TD
 435 WIDTH="33%"
 436 ALIGN="left"
 437 VALIGN="top"
 438 ><A
 439 HREF="io-serial-driver-details.html"
 440 ACCESSKEY="P"
 441 >Prev</A
 442 ></TD
 443 ><TD
 444 WIDTH="34%"
 445 ALIGN="center"
 446 VALIGN="top"
 447 ><A
 448 HREF="ecos-ref.html"
 449 ACCESSKEY="H"
 450 >Home</A
 451 ></TD
 452 ><TD
 453 WIDTH="33%"
 454 ALIGN="right"
 455 VALIGN="top"
 456 ><A
 457 HREF="io-how-to-write-a-driver.html"
 458 ACCESSKEY="N"
 459 >Next</A
 460 ></TD
 461 ></TR
 462 ><TR
 463 ><TD
 464 WIDTH="33%"
 465 ALIGN="left"
 466 VALIGN="top"
 467 >Serial driver details</TD
 468 ><TD
 469 WIDTH="34%"
 470 ALIGN="center"
 471 VALIGN="top"
 472 ><A
 473 HREF="io-serial-driver-details.html"
 474 ACCESSKEY="U"
 475 >Up</A
 476 ></TD
 477 ><TD
 478 WIDTH="33%"
 479 ALIGN="right"
 480 VALIGN="top"
 481 >How to Write a Driver</TD
 482 ></TR
 483 ></TABLE
 484 ></DIV
 485 ></BODY
 486 ></HTML
 487 >