source: rtems/doc/bsp_howto/console.t @ 3351d41

4.104.114.84.95
Last change on this file since 3351d41 was 3351d41, checked in by Joel Sherrill <joel.sherrill@…>, on 10/15/98 at 21:20:42

Redid sections to have right depth.

  • Property mode set to 100644
File size: 7.8 KB
RevLine 
[f96e8ee]1@c
2@c  COPYRIGHT (c) 1988-1998.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
[abfbfa7]9@chapter Console Driver
[07b3693f]10
[abfbfa7]11@section Introduction
[07b3693f]12
13This chapter describes how to do a console driver using RTEMS Termios
14support.
15
16The serial driver is called as soon as printf/scanf or read/write kind of
17input/output are needed. There are two main functioning modes:
18
19@itemize @bullet
20
21@item console: formatted input/output, with special characters (end of
22line, tabulations, etc...) recognition and processing,
23
24@item raw: permits raw data processing.
25
26@end itemize
27
28We may think that one need two serial drivers to deal with those two types
29of data, but Termios permits having only one driver.
30
[abfbfa7]31@section Termios
[07b3693f]32
33Termios is a standard for terminal management, included in several Unix
34versions. Termios is good because:
35
36@itemize @bullet
37
38@item from the user's side: primitives to access the terminal and change
39configuration settings are the same under Unix and Rtems.
40
41@item from the BSP developer's side: it frees you from dealing with buffer
42states and mutual exclusions on them.
43
44@end itemize
45
46Termios support includes:
47
48@itemize @bullet
49
50@item raw and console handling,
51
52@item blocking or non-blocking characters receive, with or without
53Timeout.
54
55@end itemize
56
57For more information on Termios, type man termios in your Unix box or go
58to http://www.freebsd.org/cgi/man.cgi.
59
[abfbfa7]60@section Driver Functioning Modes
[07b3693f]61
62There are generally two main functioning modes for an UART (Universal
63Asynchronous Receiver-Transmitter, i.e. the serial chip):
64
65@itemize @bullet
66
67@item polling mode: the processor blocks on sending/receiving characters.
68This mode is not powerful, but is necessary when one wants to print an
69error message when the board hung. This is also the most simple mode to
70program,
71
72@item interrupt mode: the processor doesn't block on sending/receiving
73characters. Two buffers (one for the in-going characters, the others for
74the characters to be sent) are used. An interrupt is raised as soon as a
75character is in the UART. Then the int errupt subroutine insert the
76character at the input buffer queue. When a character is asked for input,
77this at the head of the buffer is returned. When characters have to be
78sent, one have to put the first characters (the number depends on the
79UART) in th e UART. Then an interrupt is raised when all the characters
80have been emitted. The interrupt subroutine has to send the characters
81remaining in the output buffer the same way.
82
83@end itemize
84
[abfbfa7]85@section Serial Driver Functioning Overview
[07b3693f]86
87Figure 5 is an attempt of showing how a Termios driven serial driver works :
88
89@itemize @bullet
90
91@item the application programmer uses standard C library call (printf,
92scanf, read, write, etc.),
93
94@item C library (in fact that's Cygnus Newlib) calls RTEMS procedure: glue
95is made in newlib*.c files which can be found under
96$RTEMS_ROOT/c/src/lib/libc directory,
97
98@item Glue code calls your serial driver entry routines.
99
100@end itemize
101
[3351d41]102@subsection Termios and Polled I/O
[07b3693f]103
104You have to point Termios out which functions are used for simple
105character input/output:
106
107
108Function
109
110Description
111
112@example
113int pollWrite (int minor, const char *buf, int len)
114
[abfbfa7]115for (i=0; i<len; i++) @{
[07b3693f]116     put buf[i] into the UART channel minor
117     wait for the character to be transmitted
118     on the serial line
[abfbfa7]119@}
[07b3693f]120int pollread(int minor)
121@end example
122
123wait for a character to be available in the UART channel minor, then return it.
124
[3351d41]125@subsection Termios and Interrupt Driven I/O
[07b3693f]126
127The UART generally generates interrupts when it is ready to accept or to
128emit a number of characters. In this mode, the interrupt subroutine is the
129core of the driver:
130
131@example
132rtems_isr InterruptHandler (rtems_vector_number v)
133@end example
134
135check whether there was an error
136
137if some characters were received:
138   ask Termios to put them on his input buffer
139
140if some characters have been transmitted (i.e. the UART output buffer is empty)
141   tell TERMIOS that the characters have been
142   transmitted. The TERMIOS routine will call
143   the InterruptWrite function with the number
144   of characters not transmitted yet if it is
145   not zero.
146
147@example
148static int InterruptWrite(int minor, const char *buf, int len)
149@end example
150
151you have to put the n first buf characters in the UART channel minor
152buffer (n is the UART channel size, n=1 on the MC68640). Generally, an
153interrupt is raised after these n characters being transmitted. So you may
154have to enable the UART interrupts after having put the characters in the
155UART.
156
157
158Figure 5: general TERMIOS driven serial driver functioning
159
[3351d41]160@subsection Initialization
[07b3693f]161
162The driver initialization is called once during RTEMS initialization
163process.
164
165The console_initialize function has to :
166
167@itemize @bullet
168
169@item initialize Termios support: call rtems_termios_initialize(),
170
171@item initialize your integrated processor's UART: the operation is
172normally described in your user's manual and you must follow these
173instructions but it usually consists in:
174
175@item reinitialize the UART channels,
176
177@item set the channels configuration to Termios default one, i.e.: 9600
178bauds, no parity, 1 stop bit, 8 bits per character,
179
180@item register your console interrupt routine to RTEMS:
181
182@example
183        rtems_interrupt_catch (InterruptHandler,CONSOLE_VECTOR,&old_handler);
184@end example
185
186@item enable the UART channels,
187
188@item register your device name: in order to use the console (i.e. being
189able to do printf/scanf on stdin, stdout, and stderr), you have to
190register the "/dev/console" device:
191
192@example
193rtems_io_register_name ("dev/console", major, i);
194@end example
195
196@end itemize
197
[3351d41]198@subsection Opening a serial device
[07b3693f]199
200The console device is opened during RTEMS initialization but the
201console_open function is called when a new device is opened. For instance,
202if you register the "/dev/tty1" device for the UART channel 2, the
203console_open will be called with a fopen("/dev/t ty", mode) in your
204application.
205
206The console_open function has to inform Termios of your low-level function
207for serial line support; the "callbacks".
208
209The gen68340 BSP defines two kinds of callbacks:
210
211@itemize @bullet
212
213@item functions to use with polled input/output,
214
[abfbfa7]215@item functions to use with interrupt input/output.
[07b3693f]216
217@end itemize
218
[3351d41]219@subsubsection Polled I/O
[07b3693f]220
221You have to point Termios out which functions are used for simple
222character input/output, i.e. pointers to pollWrite and pollRead functions
223defined in 8.4.1.
224
[3351d41]225@subsubsection Interrupt Driven I/O
[07b3693f]226
227Driver functioning is quite different in this mode. You can see there's no
228read function passed to Termios. Indeed a console_read call returns the
229content of Termios input buffer. This buffer is filled in the driver
230interrupt subroutine (cf. 8.4.2).
231
232But you actually have to provide a pointer to the InterruptWrite function.
233
[3351d41]234@subsection Closing a serial device
[07b3693f]235
236The driver entry point is: console_close.
237
238You just have to notify Termios that the serial device was closed, with a
239call to rtems_termios_close.
240
[3351d41]241@subsection Reading characters from the serial device
[07b3693f]242
243The driver entry point is: console_read.
244
245You just have to return the content of the Termios input buffer.
246
247Call rtems_termios_read.
248
[3351d41]249@subsection Writing characters to the serial device
[07b3693f]250
251The driver entry point is: console_write.
252
253You just have to add the characters at the end of the Termios output
254buffer.
255
256Call rtems_termios_write.
257
[3351d41]258@subsection Changing serial line parameters
[07b3693f]259
260The driver entry point is: console_control.
261
262The application write is able to control the serial line configuration
263with Termios calls (such as the ioctl command, see Termios man page for
264more details). If you want to support dynamic configuration, you have to
265write the console_control piece of code . Look at the gen68340 BSP for an
266example of how it is done. Basically ioctl commands call console_control
267with the serial line configuration in a Termios structure. You just have
268to reinitialize the UART with the correct settings.
269
Note: See TracBrowser for help on using the repository browser.