OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [io-how-to-write-a-driver.html] - Blame information for rev 174

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback 
<!-- 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 
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.