XScale builds
[barrelfish] / doc / 016-serial-ports / Serial.tex
1 \documentclass[a4paper,twoside]{report} % for a report (default)
2
3 \usepackage{amsmath}
4 \usepackage{bftn} % You need this
5 \usepackage{cite}
6 \usepackage{color}
7 \usepackage{listings}
8 \usepackage{xspace}
9
10 \title{Serial ports in Barrelfish}   % title of report
11 \author{Timothy Roscoe} % author
12 \tnnumber{016}  % give the number of the tech report
13 \tnkey{Serial ports} % Short title, will appear in footer
14
15 % \date{Month Year} % Not needed - will be taken from version history
16
17 \begin{document}
18 \maketitle
19
20 %
21 % Include version history first
22 %
23 \begin{versionhistory}
24 \vhEntry{0.0}{08.07.2012}{TR}{Initial version}
25 \end{versionhistory}
26
27 % \intro{Abstract}              % Insert abstract here
28 % \intro{Acknowledgements}      % Uncomment (if needed) for acknowledgements
29 % \tableofcontents              % Uncomment (if needed) for final draft
30 % \listoffigures                % Uncomment (if needed) for final draft
31 % \listoftables                 % Uncomment (if needed) for final draft
32
33 \lstset{
34   language=C,
35   basicstyle=\ttfamily \small,
36   flexiblecolumns=false,
37   basewidth={0.5em,0.45em},
38   boxpos=t,
39 }
40
41 \newcommand{\note}[1]{[\textcolor{red}{\emph{#1}}]}
42 \newcommand{\Intf}{\texttt{/kernel/include/serial.h}\xspace}
43
44 \tableofcontents
45
46 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
47 \chapter{Introduction}
48
49 This technical note describes the use of serial ports (UARTS) in
50 Barrelfish.  
51
52 At present, it only describes the kernel-space interface
53 to serial ports, used internally by CPU drivers for debugging and
54 console output.  
55
56 In the future, it will also describe the interface to user-space UART
57 drivers and other console subsystems. 
58
59 \chapter{CPU driver interface}\label{cha:cpudriver}
60
61 CPU drivers use serial port access for printing debug information,
62 status messages during startup, and connecting a debugger such as GDB
63 to a processor. 
64
65 Each CPU driver implements a serial port subsystem which provides a
66 small number serial ports to the rest of the CPU driver.  
67
68 The interface to this subsystem is specified in the file
69 \Intf, and is described in this chapter.
70 Check the header file for a (possibly) more-up-to-date description. 
71
72 The interface is intentionally very basic.  It assumes each UART runs
73 at a fixed, default speed with basic settings (typically 115000 baud,
74 8-bit words, no parity, no flow control).   Serious applications
75 should use a full user-space UART driver instead. 
76
77 \section{Physical ports}
78
79 Serial ports available inside a CPU driver are numbered starting at
80 zero. 
81
82 The number of available serial ports is given by:
83 \begin{alltt}
84   extern const unsigned serial\_num\_physical\_ports;
85 \end{alltt}
86
87 \subsection{Initialization}
88
89 Each port must be initialized before it can be used:
90 \begin{alltt}
91   extern errval\_t serial\_init(unsigned port);
92 \end{alltt}
93 This call should fail with \texttt{SYS\_ERR\_SERIAL\_PORT\_INVALID} if
94 the port cannot be initialized, or the port number is out of range.
95
96 Initializing a serial port more than once, however, is permissible:
97 subsequent attempts to initialize an initialized port are silently
98 ignored.  The motivation for this is to handle the case where the
99 console and debug logical ports share the same physical port. 
100
101 In some cases it is necessary to do an ``early'' initializaton, for
102 example while running in physical address space before the MMU is
103 enabled.  In such cases the CPU driver should call, and the code
104 implement, the following:
105 \begin{alltt}
106   extern errval\_t serial\_early\_init(unsigned port);
107 \end{alltt}
108
109 This returns the same errors as \texttt{serial\_init()}, but it is a
110 bug to call this function more than once with the same port number,
111 and doing so will cause an assertion failure. 
112
113 \subsection{Input/output}
114
115 Each serial port provides polled, blocking, single-character
116 programmed I/O:
117 \begin{alltt}
118   extern void serial\_putchar(unsigned port, char c);
119   extern char serial\_getchar(unsigned port);
120 \end{alltt}
121 It is a bug to call these with a port number that is out of range
122 (i.e. one that is greater than or equal to
123 \texttt{serial\_num\_physical\_ports}), and doing so will cause an
124 assertion failure.  It may also cause an assertion failure to call
125 these functions on a serial port which has not yet been initialized
126 with a call to \texttt{serial\_init()} or
127 \texttt{serial\_early\_init()}. 
128
129 Note that implementations of these functions should not attempt to use
130 DMA or interrupts.  They should also not buffer any data in software
131 (though they may use a hardware FIFO in the UART if appropriate). 
132
133 \section{Logical ports}
134
135 Barrelfish CPU drivers have access to two logical serial ports: 
136 \begin{itemize}
137 \item The \emph{console} port is used for general logging and debug
138   information.  It is principally called by \texttt{kputchar()}, which
139   implements line-buffering and is in turn called by the kernel
140   \texttt{printf()} function.
141 \item The \emph{debug} port can be used to attach an external debugger
142   like \texttt{gdb}. 
143 \end{itemize}
144
145 Both logical ports are assigned to sensible default physical ports by
146 the serial port implementation, but they can be changed by writing
147 these variables:
148 \begin{alltt}
149   extern unsigned serial\_console\_port;
150   extern unsigned serial\_debug\_port;
151 \end{alltt}
152
153 Note that it is not unusual for both logical ports to be assigned to
154 the same physical port. 
155
156 The file \Intf also includes inline functions to initialize whichever
157 physical port is currently assigned to a logical port:
158 \begin{alltt}
159   static inline errval\_t serial\_console\_init(void);
160   static inline errval\_t serial\_debug\_init(void);
161 \end{alltt}
162
163 There are also input functions, which simply call
164 \texttt{serial\_getchar()} with the appropriate port number:
165 \begin{alltt}
166   static inline char serial\_console\_getchar(void);
167   static inline char serial\_debug\_getchar(void);
168 \end{alltt}
169
170 Output functions are similar, but in addition replace any LF character
171 with the sequence CR/LF:
172 \begin{alltt}
173   static inline void serial\_console\_putchar(char c);
174   static inline void serial\_debug\_putchar(char c);
175 \end{alltt}
176
177 \section{Implementing a serial port subsystem}
178
179 Typically, a rudimentary console driver is the first thing to be
180 implemented when writing a CPU driver for a new architecture.   
181
182 The serial port subsystem for a CPU driver must implement all the
183 functionality in \Intf that deals with physical serial ports, in other
184 words:
185 \begin{verbatim}
186   const unsigned serial_num_physical_ports;
187   errval_t serial_init(unsigned port);
188   errval_t serial_early_init(unsigned port);
189   void serial_putchar(unsigned port, char c);
190   char serial_getchar(unsigned port);
191   unsigned serial_console_port;  
192   unsigned serial_debug_port;
193 \end{verbatim}
194
195 Functions for logical ports are provided by inline functions in the
196 header file. 
197
198 Initializing a serial port typically consists of configuring the UART
199 hardware, and then mapping the registers appropriately into the
200 kernel's virtual address space. 
201
202 Examples of serial port implementations at time of writing include:
203 \begin{itemize}
204 \item \texttt{/kernel/arch/omap44xx/omap\_uart.c}
205 \item \texttt{/kernel/arch/x86/serial.c}
206 \end{itemize}
207
208 \subsection{Multiprocessor considerations}
209
210 This document does not address accessing a single UART from more than
211 CPU driver.  If this happens at all, it is typically hidden by the
212 implementation (for example, some x86 CPU drivers use a global
213 spinlock, since performance is not an issue anyway).  Care should be
214 taken not to initialize the UARTs multiple times in such
215 circumstances. 
216
217
218
219 \end{document}