doc/html/ref/io-how-to-write-a-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 >How to Write a 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="I/O Package (Device Drivers)"
  23 HREF="io.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE=" TTY driver"
  26 HREF="io-tty-driver.html"><LINK
  27 REL="NEXT"
  28 TITLE="Serial testing with ser_filter"
  29 HREF="io-serial-testing-with-serfilter.html"></HEAD
  30 ><BODY
  31 CLASS="CHAPTER"
  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-tty-driver.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="io-serial-testing-with-serfilter.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="CHAPTER"
  82 ><H1
  83 ><A
  84 NAME="IO-HOW-TO-WRITE-A-DRIVER">Chapter 17. How to Write a Driver</H1
  85 ><DIV
  86 CLASS="TOC"
  87 ><DL
  88 ><DT
  89 ><B
  90 >Table of Contents</B
  91 ></DT
  92 ><DT
  93 ><A
  94 HREF="io-how-to-write-a-driver.html#IO-HOW-TO-WRITE-SERIAL-INTERFACE-DRIVER"
  95 >How to Write a Serial Hardware Interface Driver</A
  96 ></DT
  97 ><DT
  98 ><A
  99 HREF="io-serial-testing-with-serfilter.html"
 100 >Serial testing with ser_filter</A
 101 ></DT
 102 ></DL
 103 ></DIV
 104 ><P
 105 >A device driver is nothing more than a
 106 named entity that supports the basic I/O functions - read, write, get
 107 config, and set config. Typically a device driver also uses and
 108 manages interrupts from the device. While the interface is generic and
 109 device driver independent, the actual driver implementation is
 110 completely up to the device driver designer. </P
 111 ><P
 112 >That said, the reason for using a device driver is to provide
 113 access to a device from application code in as general purpose a
 114 fashion as reasonable. Most driver writers are also concerned with
 115 making this access as simple as possible while being as efficient
 116 as possible. </P
 117 ><P
 118 >Most device drivers are concerned with the movement of information,
 119 for example data bytes along a serial interface, or packets in a
 120 network. In order to make the most efficient use of system resources,
 121 interrupts are used. This will allow other application processing
 122 to take place while the data transfers are under way, with interrupts
 123 used to indicate when various events have occurred. For example,
 124 a serial port typically generates an interrupt after a character
 125 has been sent &#8220;down the wire&#8221; and the interface
 126 is ready for another. It makes sense to allow further application
 127 processing while the data is being sent since this can take quite
 128 a long time. The interrupt can be used to allow the driver to send
 129 a character as soon as the current one is complete, without any
 130 active participation by the application code. </P
 131 ><P
 132 >The main building blocks for device drivers are found in the
 133 include file: <TT
 134 CLASS="FILENAME"
 135 >&lt;cyg/io/devtab.h&gt;</TT
 136 ></P
 137 ><P
 138 >All device drivers in <SPAN
 139 CLASS="emphasis"
 140 ><I
 141 CLASS="EMPHASIS"
 142 >eCos</I
 143 ></SPAN
 144 > are described
 145 by a device table entry, using the <SPAN
 146 CLASS="TYPE"
 147 >cyg_devtab_entry_t</SPAN
 148 > type.
 149 The entry should be created using the <TT
 150 CLASS="FUNCTION"
 151 >DEVTAB_ENTRY()</TT
 152 > macro,
 153 like this:</P
 154 ><TABLE
 155 BORDER="5"
 156 BGCOLOR="#E0E0F0"
 157 WIDTH="70%"
 158 ><TR
 159 ><TD
 160 ><PRE
 161 CLASS="PROGRAMLISTING"
 162 ><TT
 163 CLASS="FUNCTION"
 164 >DEVTAB_ENTRY</TT
 165 >(l, name, dep_name, handlers, init, lookup, priv)</PRE
 166 ></TD
 167 ></TR
 168 ></TABLE
 169 ><P
 170 ></P
 171 ><DIV
 172 CLASS="VARIABLELIST"
 173 ><P
 174 ><B
 175 >Arguments</B
 176 ></P
 177 ><DL
 178 ><DT
 179 ><TT
 180 CLASS="PARAMETER"
 181 ><I
 182 >l</I
 183 ></TT
 184 ></DT
 185 ><DD
 186 ><P
 187 >The "C" label for this device table entry.</P
 188 ></DD
 189 ><DT
 190 ><TT
 191 CLASS="PARAMETER"
 192 ><I
 193 >name</I
 194 ></TT
 195 ></DT
 196 ><DD
 197 ><P
 198 >The "C" string name for the device.</P
 199 ></DD
 200 ><DT
 201 ><TT
 202 CLASS="PARAMETER"
 203 ><I
 204 >dep_name</I
 205 ></TT
 206 ></DT
 207 ><DD
 208 ><P
 209 >For a layered device, the "C" string name of the
 210     device this device is built upon.</P
 211 ></DD
 212 ><DT
 213 ><TT
 214 CLASS="PARAMETER"
 215 ><I
 216 >handlers</I
 217 ></TT
 218 ></DT
 219 ><DD
 220 ><P
 221 >A pointer to the I/O function "handlers" (see below).</P
 222 ></DD
 223 ><DT
 224 ><TT
 225 CLASS="PARAMETER"
 226 ><I
 227 >init</I
 228 ></TT
 229 ></DT
 230 ><DD
 231 ><P
 232 >A function called when eCos is initialized. This
 233     function can query the device, setup hardware, etc.</P
 234 ></DD
 235 ><DT
 236 ><TT
 237 CLASS="PARAMETER"
 238 ><I
 239 >lookup</I
 240 ></TT
 241 ></DT
 242 ><DD
 243 ><P
 244 >A function called when <TT
 245 CLASS="FUNCTION"
 246 >cyg_io_lookup()</TT
 247 > is called
 248     for this device. </P
 249 ></DD
 250 ><DT
 251 ><TT
 252 CLASS="PARAMETER"
 253 ><I
 254 >priv</I
 255 ></TT
 256 ></DT
 257 ><DD
 258 ><P
 259 >A placeholder for any device specific data
 260     required by the driver.</P
 261 ></DD
 262 ></DL
 263 ></DIV
 264 ><P
 265 >The interface to the driver is through the <TT
 266 CLASS="STRUCTFIELD"
 267 ><I
 268 >handlers</I
 269 ></TT
 270 > field.  This is a pointer to
 271 a set of functions which implement the various <TT
 272 CLASS="FUNCTION"
 273 >cyg_io_XXX()</TT
 274 >
 275 routines. This table is defined by the macro:</P
 276 ><TABLE
 277 BORDER="5"
 278 BGCOLOR="#E0E0F0"
 279 WIDTH="70%"
 280 ><TR
 281 ><TD
 282 ><PRE
 283 CLASS="PROGRAMLISTING"
 284 >DEVIO_TABLE(l, write, read, get_config, set_config)</PRE
 285 ></TD
 286 ></TR
 287 ></TABLE
 288 ><P
 289 ></P
 290 ><DIV
 291 CLASS="VARIABLELIST"
 292 ><P
 293 ><B
 294 >Arguments</B
 295 ></P
 296 ><DL
 297 ><DT
 298 ><TT
 299 CLASS="PARAMETER"
 300 ><I
 301 >l</I
 302 ></TT
 303 ></DT
 304 ><DD
 305 ><P
 306 >The "C" label for this table of handlers.</P
 307 ></DD
 308 ><DT
 309 >write</DT
 310 ><DD
 311 ><P
 312 >The function called as a result of
 313     <TT
 314 CLASS="FUNCTION"
 315 >cyg_io_write()</TT
 316 >.</P
 317 ></DD
 318 ><DT
 319 >read</DT
 320 ><DD
 321 ><P
 322 >The function called as a result of
 323     <TT
 324 CLASS="FUNCTION"
 325 >cyg_io_read()</TT
 326 >. </P
 327 ></DD
 328 ><DT
 329 >get_config</DT
 330 ><DD
 331 ><P
 332 >The function called as a result of
 333     <TT
 334 CLASS="FUNCTION"
 335 >cyg_io_get_config()</TT
 336 >.</P
 337 ></DD
 338 ><DT
 339 >set_config</DT
 340 ><DD
 341 ><P
 342 >The function called as a result of
 343     <TT
 344 CLASS="FUNCTION"
 345 >cyg_io_set_config()</TT
 346 >. </P
 347 ></DD
 348 ></DL
 349 ></DIV
 350 ><P
 351 >When <SPAN
 352 CLASS="emphasis"
 353 ><I
 354 CLASS="EMPHASIS"
 355 >eCos</I
 356 ></SPAN
 357 > is initialized (sometimes called
 358 &#8220;boot&#8221; time), the <TT
 359 CLASS="FUNCTION"
 360 >init()</TT
 361 > function is called
 362 for all devices in the system. The <TT
 363 CLASS="FUNCTION"
 364 >init()</TT
 365 > function is
 366 allowed to return an error in which case the device will be placed
 367 &#8220;off line&#8221; and all I/O requests to that device will be
 368 considered in error.</P
 369 ><P
 370 >The <TT
 371 CLASS="FUNCTION"
 372 >lookup()</TT
 373 > function is called whenever
 374 the <TT
 375 CLASS="FUNCTION"
 376 >cyg_io_lookup()</TT
 377 > function
 378 is called with this device name. The lookup function may cause the device
 379 to come &#8220;on line&#8221; which would then allow I/O
 380 operations to proceed. Future versions of the I/O system
 381 will allow for other states, including power saving modes,
 382 etc.</P
 383 ><DIV
 384 CLASS="SECTION"
 385 ><H1
 386 CLASS="SECTION"
 387 ><A
 388 NAME="IO-HOW-TO-WRITE-SERIAL-INTERFACE-DRIVER">How to Write a Serial Hardware Interface Driver</H1
 389 ><P
 390 >The standard serial driver supplied with
 391 <SPAN
 392 CLASS="emphasis"
 393 ><I
 394 CLASS="EMPHASIS"
 395 >eCos</I
 396 ></SPAN
 397 > is structured as a hardware independent
 398 portion and a hardware dependent interface module. To add support for
 399 a new serial port, the user should be able to use the existing
 400 hardware independent portion and just add their own interface driver which handles the details of the
 401 actual device. The user should have no need to change the hardware
 402 independent portion. </P
 403 ><P
 404 >The interfaces used by the serial driver and serial implementation
 405 modules are contained in the file <TT
 406 CLASS="FILENAME"
 407 >&lt;cyg/io/serial.h&gt;</TT
 408 ></P
 409 ><DIV
 410 CLASS="NOTE"
 411 ><BLOCKQUOTE
 412 CLASS="NOTE"
 413 ><P
 414 ><B
 415 >Note: </B
 416 >In the sections below we use the notation &lt;&lt;xx&gt;&gt; to
 417 mean a module specific value, referred to as &#8220;xx&#8221; below.</P
 418 ></BLOCKQUOTE
 419 ></DIV
 420 ><DIV
 421 CLASS="SECTION"
 422 ><H2
 423 CLASS="SECTION"
 424 ><A
 425 NAME="AEN10881">DevTab Entry</H2
 426 ><P
 427 >The interface module contains the devtab entry (or entries
 428 if a single module supports more than one interface). This entry
 429 should have the form: </P
 430 ><TABLE
 431 BORDER="5"
 432 BGCOLOR="#E0E0F0"
 433 WIDTH="70%"
 434 ><TR
 435 ><TD
 436 ><PRE
 437 CLASS="PROGRAMLISTING"
 438 >DEVTAB_ENTRY(&lt;&lt;module_name&gt;&gt;,
 439              &lt;&lt;device_name&gt;&gt;,
 440              0,
 441              &amp;serial_devio,
 442              &lt;&lt;module_init&gt;&gt;,
 443              &lt;&lt;module_lookup&gt;&gt;,
 444              &amp;&lt;&lt;serial_channel&gt;&gt;
 445             );</PRE
 446 ></TD
 447 ></TR
 448 ></TABLE
 449 ><P
 450 ></P
 451 ><DIV
 452 CLASS="VARIABLELIST"
 453 ><P
 454 ><B
 455 >Arguments</B
 456 ></P
 457 ><DL
 458 ><DT
 459 ><TT
 460 CLASS="PARAMETER"
 461 ><I
 462 >module_name</I
 463 ></TT
 464 ></DT
 465 ><DD
 466 ><P
 467 >The "C" label for this devtab entry</P
 468 ></DD
 469 ><DT
 470 ><TT
 471 CLASS="PARAMETER"
 472 ><I
 473 >device_name</I
 474 ></TT
 475 ></DT
 476 ><DD
 477 ><P
 478 >The "C" string for the
 479     device. E.g. <TT
 480 CLASS="FILENAME"
 481 >/dev/serial0</TT
 482 >.</P
 483 ></DD
 484 ><DT
 485 ><TT
 486 CLASS="PARAMETER"
 487 ><I
 488 >serial_devio</I
 489 ></TT
 490 ></DT
 491 ><DD
 492 ><P
 493 >The table of I/O functions. This set is defined in
 494     the hardware independent serial driver and should be used.</P
 495 ></DD
 496 ><DT
 497 ><TT
 498 CLASS="PARAMETER"
 499 ><I
 500 >module_init</I
 501 ></TT
 502 ></DT
 503 ><DD
 504 ><P
 505 >The module initialization function.</P
 506 ></DD
 507 ><DT
 508 ><TT
 509 CLASS="PARAMETER"
 510 ><I
 511 >module_lookup</I
 512 ></TT
 513 ></DT
 514 ><DD
 515 ><P
 516 >The device lookup function. This function
 517     typically sets up the device for actual use, turning on
 518     interrupts, configuring the port, etc.</P
 519 ></DD
 520 ><DT
 521 ><TT
 522 CLASS="PARAMETER"
 523 ><I
 524 >serial_channel</I
 525 ></TT
 526 ></DT
 527 ><DD
 528 ><P
 529 >This table (defined below) contains the interface
 530     between the interface module and the serial driver proper.</P
 531 ></DD
 532 ></DL
 533 ></DIV
 534 ></DIV
 535 ><DIV
 536 CLASS="SECTION"
 537 ><H2
 538 CLASS="SECTION"
 539 ><A
 540 NAME="AEN10918">Serial Channel Structure</H2
 541 ><P
 542 >Each serial device must have a &#8220;serial channel&#8221;.
 543 This is a set of data which describes all operations on the device.
 544 It also contains buffers, etc., if the device is to be buffered.
 545 The serial channel is created by the macro: </P
 546 ><TABLE
 547 BORDER="5"
 548 BGCOLOR="#E0E0F0"
 549 WIDTH="70%"
 550 ><TR
 551 ><TD
 552 ><PRE
 553 CLASS="PROGRAMLISTING"
 554 >SERIAL_CHANNEL_USING_INTERRUPTS(l, funs, dev_priv, baud,stop, parity, word_length,
 555                                 flags, out_buf, out_buflen, in_buf, in_buflen)</PRE
 556 ></TD
 557 ></TR
 558 ></TABLE
 559 ><P
 560 ></P
 561 ><DIV
 562 CLASS="VARIABLELIST"
 563 ><P
 564 ><B
 565 >Arguments</B
 566 ></P
 567 ><DL
 568 ><DT
 569 ><TT
 570 CLASS="PARAMETER"
 571 ><I
 572 >l</I
 573 ></TT
 574 ></DT
 575 ><DD
 576 ><P
 577 >The "C" label for this structure.</P
 578 ></DD
 579 ><DT
 580 ><TT
 581 CLASS="PARAMETER"
 582 ><I
 583 >funs</I
 584 ></TT
 585 ></DT
 586 ><DD
 587 ><P
 588 >The set of interface functions (see below).</P
 589 ></DD
 590 ><DT
 591 ><TT
 592 CLASS="STRUCTFIELD"
 593 ><I
 594 >dev_priv</I
 595 ></TT
 596 ></DT
 597 ><DD
 598 ><P
 599 >A placeholder for any device specific data for
 600     this channel.</P
 601 ></DD
 602 ><DT
 603 ><TT
 604 CLASS="STRUCTFIELD"
 605 ><I
 606 >baud</I
 607 ></TT
 608 ></DT
 609 ><DD
 610 ><P
 611 >The initial baud rate value
 612     (<SPAN
 613 CLASS="TYPE"
 614 >cyg_serial_baud_t</SPAN
 615 >).</P
 616 ></DD
 617 ><DT
 618 ><TT
 619 CLASS="STRUCTFIELD"
 620 ><I
 621 >stop</I
 622 ></TT
 623 ></DT
 624 ><DD
 625 ><P
 626 >The initial stop bits value
 627     (<SPAN
 628 CLASS="TYPE"
 629 >cyg_serial_stop_bits_t</SPAN
 630 >).</P
 631 ></DD
 632 ><DT
 633 ><TT
 634 CLASS="STRUCTFIELD"
 635 ><I
 636 >parity</I
 637 ></TT
 638 ></DT
 639 ><DD
 640 ><P
 641 >The initial parity mode value
 642     (<SPAN
 643 CLASS="TYPE"
 644 >cyg_serial_parity_t</SPAN
 645 >).</P
 646 ></DD
 647 ><DT
 648 ><TT
 649 CLASS="STRUCTFIELD"
 650 ><I
 651 >word_length</I
 652 ></TT
 653 ></DT
 654 ><DD
 655 ><P
 656 >The initial word length value
 657     (<SPAN
 658 CLASS="TYPE"
 659 >cyg_serial_word_length_t</SPAN
 660 >).</P
 661 ></DD
 662 ><DT
 663 ><TT
 664 CLASS="STRUCTFIELD"
 665 ><I
 666 >flags</I
 667 ></TT
 668 ></DT
 669 ><DD
 670 ><P
 671 >The initial driver flags value.</P
 672 ></DD
 673 ><DT
 674 ><TT
 675 CLASS="STRUCTFIELD"
 676 ><I
 677 >out_buf</I
 678 ></TT
 679 ></DT
 680 ><DD
 681 ><P
 682 >Pointer to the output
 683     buffer. <TT
 684 CLASS="LITERAL"
 685 >NULL</TT
 686 > if none required.</P
 687 ></DD
 688 ><DT
 689 ><TT
 690 CLASS="STRUCTFIELD"
 691 ><I
 692 >out_buflen</I
 693 ></TT
 694 ></DT
 695 ><DD
 696 ><P
 697 >The length of the output buffer.</P
 698 ></DD
 699 ><DT
 700 ><TT
 701 CLASS="STRUCTFIELD"
 702 ><I
 703 >in_buf</I
 704 ></TT
 705 ></DT
 706 ><DD
 707 ><P
 708 >pointer to the input
 709     buffer. <TT
 710 CLASS="LITERAL"
 711 >NULL</TT
 712 > if none required.</P
 713 ></DD
 714 ><DT
 715 ><TT
 716 CLASS="STRUCTFIELD"
 717 ><I
 718 >in_buflen</I
 719 ></TT
 720 ></DT
 721 ><DD
 722 ><P
 723 >The length of the input buffer. </P
 724 ></DD
 725 ></DL
 726 ></DIV
 727 ><P
 728 >If either buffer length is zero, no buffering will take place
 729 in that direction and only polled mode functions will be used.</P
 730 ><P
 731 >The interface from the hardware independent driver into the
 732 hardware interface module is contained in the <TT
 733 CLASS="STRUCTFIELD"
 734 ><I
 735 >funs</I
 736 ></TT
 737 > table.
 738 This is defined by the macro:</P
 739 ></DIV
 740 ><DIV
 741 CLASS="SECTION"
 742 ><H2
 743 CLASS="SECTION"
 744 ><A
 745 NAME="AEN10993">Serial Functions Structure</H2
 746 ><TABLE
 747 BORDER="5"
 748 BGCOLOR="#E0E0F0"
 749 WIDTH="70%"
 750 ><TR
 751 ><TD
 752 ><PRE
 753 CLASS="PROGRAMLISTING"
 754 >SERIAL_FUNS(l, putc, getc, set_config, start_xmit, stop_xmit)</PRE
 755 ></TD
 756 ></TR
 757 ></TABLE
 758 ><P
 759 ></P
 760 ><DIV
 761 CLASS="VARIABLELIST"
 762 ><P
 763 ><B
 764 >Arguments</B
 765 ></P
 766 ><DL
 767 ><DT
 768 ><TT
 769 CLASS="STRUCTFIELD"
 770 ><I
 771 >l</I
 772 ></TT
 773 ></DT
 774 ><DD
 775 ><P
 776 >The "C" label for this structure.</P
 777 ></DD
 778 ><DT
 779 ><TT
 780 CLASS="STRUCTFIELD"
 781 ><I
 782 >putc</I
 783 ></TT
 784 ></DT
 785 ><DD
 786 ><P
 787 ><TT
 788 CLASS="LITERAL"
 789 >bool (*putc)(serial_channel *priv, unsigned char
 790       c)</TT
 791 ></P
 792 ><P
 793 >      This function sends one character to the interface. It should
 794       return <TT
 795 CLASS="LITERAL"
 796 >true</TT
 797 > if the character is actually consumed. It should
 798       return <TT
 799 CLASS="LITERAL"
 800 >false</TT
 801 > if there is no space in the interface
 802       </P
 803 ></DD
 804 ><DT
 805 ><TT
 806 CLASS="STRUCTFIELD"
 807 ><I
 808 >getc</I
 809 ></TT
 810 ></DT
 811 ><DD
 812 ><P
 813 ><TT
 814 CLASS="LITERAL"
 815 >unsigned char (*getc)(serial_channel *priv)</TT
 816 ></P
 817 ><P
 818 >      This function fetches one character from the interface. It will
 819       be only called in a non-interrupt driven mode, thus it should
 820       wait for a character by polling the device until ready.
 821       </P
 822 ></DD
 823 ><DT
 824 ><TT
 825 CLASS="STRUCTFIELD"
 826 ><I
 827 >set_config</I
 828 ></TT
 829 ></DT
 830 ><DD
 831 ><P
 832 ><TT
 833 CLASS="LITERAL"
 834 >bool (*set_config)(serial_channel
 835       *priv,cyg_serial_info_t *config)</TT
 836 ></P
 837 ><P
 838 >        This function is used to configure the port. It should return
 839         <TT
 840 CLASS="LITERAL"
 841 >true</TT
 842 > if the hardware is updated to match the desired
 843         configuration. It should return <TT
 844 CLASS="LITERAL"
 845 >false</TT
 846 > if the port cannot
 847         support some parameter specified by the given
 848         configuration. E.g. selecting 1.5 stop bits and 8 data bits is
 849         invalid for most serial devices and should not be allowed.
 850       </P
 851 ></DD
 852 ><DT
 853 ><TT
 854 CLASS="PARAMETER"
 855 ><I
 856 >start_xmit</I
 857 ></TT
 858 ></DT
 859 ><DD
 860 ><P
 861 ><TT
 862 CLASS="LITERAL"
 863 >void (*start_xmit)(serial_channel *priv)</TT
 864 ></P
 865 ><P
 866 >        In interrupt mode, turn on the transmitter and allow for
 867         transmit interrupts.
 868       </P
 869 ></DD
 870 ><DT
 871 ><TT
 872 CLASS="PARAMETER"
 873 ><I
 874 >stop_xmit</I
 875 ></TT
 876 ></DT
 877 ><DD
 878 ><P
 879 ><TT
 880 CLASS="LITERAL"
 881 >void (*stop_xmit)(serial_channel *priv)</TT
 882 ></P
 883 ><P
 884 >In interrupt mode, turn off the transmitter.</P
 885 ></DD
 886 ></DL
 887 ></DIV
 888 ></DIV
 889 ><DIV
 890 CLASS="SECTION"
 891 ><H2
 892 CLASS="SECTION"
 893 ><A
 894 NAME="AEN11042">Callbacks</H2
 895 ><P
 896 >The device interface module can execute functions in the
 897 hardware independent driver via <TT
 898 CLASS="LITERAL"
 899 >chan-&gt;callbacks</TT
 900 >.
 901 These functions are available:</P
 902 ><TABLE
 903 BORDER="5"
 904 BGCOLOR="#E0E0F0"
 905 WIDTH="70%"
 906 ><TR
 907 ><TD
 908 ><PRE
 909 CLASS="PROGRAMLISTING"
 910 >void (*serial_init)( serial_channel *chan )</PRE
 911 ></TD
 912 ></TR
 913 ></TABLE
 914 ><P
 915 >This function is used to initialize the serial channel. It
 916 is only required if the channel is being used in interrupt
 917 mode.</P
 918 ><TABLE
 919 BORDER="5"
 920 BGCOLOR="#E0E0F0"
 921 WIDTH="70%"
 922 ><TR
 923 ><TD
 924 ><PRE
 925 CLASS="PROGRAMLISTING"
 926 >void (*xmt_char)( serial_channel *chan )</PRE
 927 ></TD
 928 ></TR
 929 ></TABLE
 930 ><P
 931 >This function would be called from an interrupt handler after a
 932 transmit interrupt indicating that additional characters may be
 933 sent. The upper driver will call the <TT
 934 CLASS="FUNCTION"
 935 >putc</TT
 936 >
 937 function as appropriate to send more data to the device.</P
 938 ><TABLE
 939 BORDER="5"
 940 BGCOLOR="#E0E0F0"
 941 WIDTH="70%"
 942 ><TR
 943 ><TD
 944 ><PRE
 945 CLASS="PROGRAMLISTING"
 946 >void (*rcv_char)( serial_channel *chan, unsigned char c )</PRE
 947 ></TD
 948 ></TR
 949 ></TABLE
 950 ><P
 951 >This function is used to tell the driver that a character has arrived
 952 at the interface. This function is typically called from the interrupt
 953 handler. </P
 954 ><P
 955 >Furthermore, if the device has a FIFO it should require the hardware
 956 independent driver to provide block transfer functionality (driver CDL
 957 should include &quot;implements
 958 CYGINT_IO_SERIAL_BLOCK_TRANSFER&quot;).  In that case, the following
 959 functions are available as well:</P
 960 ><TABLE
 961 BORDER="5"
 962 BGCOLOR="#E0E0F0"
 963 WIDTH="70%"
 964 ><TR
 965 ><TD
 966 ><PRE
 967 CLASS="PROGRAMLISTING"
 968 >bool (*data_xmt_req)(serial_channel *chan,
 969                      int space,
 970                      int* chars_avail,
 971                      unsigned char** chars)
 972 void (*data_xmt_done)(serial_channel *chan)</PRE
 973 ></TD
 974 ></TR
 975 ></TABLE
 976 ><P
 977 >Instead of calling <TT
 978 CLASS="FUNCTION"
 979 >xmt_char()</TT
 980 > to get a single
 981 character for transmission at a time, the driver should call
 982 <TT
 983 CLASS="FUNCTION"
 984 >data_xmt_req()</TT
 985 > in a loop, requesting character
 986 blocks for transfer. Call with a <TT
 987 CLASS="PARAMETER"
 988 ><I
 989 >space</I
 990 ></TT
 991 > argument of how much space
 992 there is available in the FIFO.</P
 993 ><P
 994 >If the call returns <TT
 995 CLASS="LITERAL"
 996 >true</TT
 997 >, the driver can read
 998 <TT
 999 CLASS="PARAMETER"
1000 ><I
1001 >chars_avail</I
1002 ></TT
1003 > characters from
1004 <TT
1005 CLASS="PARAMETER"
1006 ><I
1007 >chars</I
1008 ></TT
1009 > and copy them into the FIFO.</P
1010 ><P
1011 >If the call returns <TT
1012 CLASS="LITERAL"
1013 >false</TT
1014 >, there are
1015 no more buffered characters and the driver should continue without
1016 filling up the FIFO.</P
1017 ><P
1018 >When all data has been unloaded, the
1019 driver must call <TT
1020 CLASS="FUNCTION"
1021 >data_xmt_done()</TT
1022 >.</P
1023 ><TABLE
1024 BORDER="5"
1025 BGCOLOR="#E0E0F0"
1026 WIDTH="70%"
1027 ><TR
1028 ><TD
1029 ><PRE
1030 CLASS="PROGRAMLISTING"
1031 >bool (*data_rcv_req)(serial_channel *chan,
1032                      int avail,
1033                      int* space_avail,
1034                      unsigned char** space)
1035 void (*data_rcv_done)(serial_channel *chan)</PRE
1036 ></TD
1037 ></TR
1038 ></TABLE
1039 ><P
1040 >Instead of calling <TT
1041 CLASS="FUNCTION"
1042 >rcv_char()</TT
1043 > with a single
1044 character at a time, the driver should call
1045 <TT
1046 CLASS="FUNCTION"
1047 >data_rcv_req()</TT
1048 > in a loop, requesting space to
1049 unload the FIFO to. <TT
1050 CLASS="PARAMETER"
1051 ><I
1052 >avail</I
1053 ></TT
1054 > is the number of
1055 characters the driver wishes to unload.</P
1056 ><P
1057 >If the call returns <TT
1058 CLASS="LITERAL"
1059 >true</TT
1060 >, the driver can copy
1061 <TT
1062 CLASS="PARAMETER"
1063 ><I
1064 >space_avail</I
1065 ></TT
1066 > characters to
1067 <TT
1068 CLASS="PARAMETER"
1069 ><I
1070 >space</I
1071 ></TT
1072 >. </P
1073 ><P
1074 >If the call returns <TT
1075 CLASS="LITERAL"
1076 >false</TT
1077 >, the input buffer is
1078 full. It is up to the driver to decide what to do in that case
1079 (callback functions for registering overflow are being planned for
1080 later versions of the serial driver).</P
1081 ><P
1082 >When all data has been unloaded, the driver must call
1083 <TT
1084 CLASS="FUNCTION"
1085 >data_rcv_done()</TT
1086 >.</P
1087 ></DIV
1088 ></DIV
1089 ></DIV
1090 ><DIV
1091 CLASS="NAVFOOTER"
1092 ><HR
1093 ALIGN="LEFT"
1094 WIDTH="100%"><TABLE
1095 SUMMARY="Footer navigation table"
1096 WIDTH="100%"
1097 BORDER="0"
1098 CELLPADDING="0"
1099 CELLSPACING="0"
1100 ><TR
1101 ><TD
1102 WIDTH="33%"
1103 ALIGN="left"
1104 VALIGN="top"
1105 ><A
1106 HREF="io-tty-driver.html"
1107 ACCESSKEY="P"
1108 >Prev</A
1109 ></TD
1110 ><TD
1111 WIDTH="34%"
1112 ALIGN="center"
1113 VALIGN="top"
1114 ><A
1115 HREF="ecos-ref.html"
1116 ACCESSKEY="H"
1117 >Home</A
1118 ></TD
1119 ><TD
1120 WIDTH="33%"
1121 ALIGN="right"
1122 VALIGN="top"
1123 ><A
1124 HREF="io-serial-testing-with-serfilter.html"
1125 ACCESSKEY="N"
1126 >Next</A
1127 ></TD
1128 ></TR
1129 ><TR
1130 ><TD
1131 WIDTH="33%"
1132 ALIGN="left"
1133 VALIGN="top"
1134 >TTY driver</TD
1135 ><TD
1136 WIDTH="34%"
1137 ALIGN="center"
1138 VALIGN="top"
1139 ><A
1140 HREF="io.html"
1141 ACCESSKEY="U"
1142 >Up</A
1143 ></TD
1144 ><TD
1145 WIDTH="33%"
1146 ALIGN="right"
1147 VALIGN="top"
1148 >Serial testing with ser_filter</TD
1149 ></TR
1150 ></TABLE
1151 ></DIV
1152 ></BODY
1153 ></HTML
1154 >