%% rt_com documentation%%%% Copyright (C) 1997-2000 Jochen K黳per%%%% Available under GNU General Public License V2.\documentclass[12pt,twoside]{article}\usepackage{rtldoc}\usepackage[nofancy]{rcsinfo}\usepackage{textcomp}\begin{document}\rcsInfo $Id: rt_com.tex,v 1.5 2000/01/28 17:27:19 jochen Exp $\rtldraft\hypersetup{   pdfauthor = {Jochen K{\"u}pper},   pdfsubject = {The Serial Port Driver of Real-Time Linux},   pdftitle = {The Serial Port Driver of Real-Time Linux},   pdfkeywords = {rt\_com serial port driver Real-Time Linux}   }\title{The Serial Port Driver of Real-Time Linux}\fancyhead[CE]{Jochen K黳per}\fancyhead[CO]{The Serial Port Driver of Real-Time Linux}\author{J.\ K黳per}\affil{Heinrich Heine Universit鋞, Institut f黵 Physikalische Chemie~I,   Universit鋞sstra遝 1, D--40225 D黶seldorf, Deutschland}\email{jochen@pc1.uni-duesseldorf.de}\begin{abstract}   This documentation describes the rt\_com serial port driver for RT-Linux.   The driver works with \href{http://www.rtlinux.org}{NMT RT-Linux} v1 and v2,   as well as \href{http://www.rtai.org}{RTAI}. \\   This manual is intended to describe \texttt{rt\_com} version 0.5.\end{abstract}\section{License}This document is free. You can redistribute it and/or modify it under theterms of the GNU General Public License as published by the Free SoftwareFoundation either version 2 of the License, or (at your option) any laterversion. This document is distributed in the hope that it will be useful, but\emph{without any warranty}. Without even the implied warranty of\emph{merchantability} or \emph{fitness for a particular purpose}. See theGNU General Public License for more details. You should have received a copy ofthe GNU General Public License along with this document.  If not, write to theFree Software Foundation, Inc., 675 Mass Ave, Cambridge MA 02139, USA.\section{Copyright(s)}\noindent\copyright 1997-2000, Jochen K黳per. All rights reserved.\section{Typographic Conventions}The conventions used in this document are described in Table~\ref{tab:habits}.\begin{table}   \centering   \caption{Typographical Conventions for this Document}   \label{tab:habits}   \begin{tabular}{lcr}      \hline \hline                                       %% two ruled lines      & & \\                                              %% blank line      Markup & Usage & Effect \\                          %% column header(s)      & & \\                                              %% blank line      \hline                                              %% one ruled line      & & \\                                              %% blank line      \verb"\rtlin{"\arg{blue type-face}\verb"}" &        %% row 1 data      \rtlnormal{user input} &       \rtlin{blue type-face} \\      \verb"\rtlout{"\arg{magenta sans-serif}\verb"}" &   %% row 2 data      \rtlnormal{machine output} &       \rtlout{magenta sans-serif} \\      \verb"\rtlnormal{"\arg{black times-roman}\verb"}" & %% row 3 data      \rtlnormal{normal text (reset)} &       \rtlnormal{black times-roman} \\      \verb"\rtlmargin{"\arg{teal italic}\verb"}" &       %% row 4 data      \rtlnormal{margin notes} &       \rtlti{teal italic} \\      & & \\                                              %% blank line      \hline \hline                                       %% two ruled lines   \end{tabular}\end{table}For reasons of clarity, the \verb"\rtlmargin" is not shown as a margin notewithin the table.  Verbatim-like output can be set using the \verb"\begin{rtlcode}" \ldots \verb"\end{rtlcode}" environment (Daly et al.\ 2000).\section{Introduction}This manual describes the \texttt{rt\_com} kernel module.  The module providesa reasonable easy software interface to the standard serial ports of the PCsfor NMT RT-Linux v1 and v2 and RTAI.There are a small number of user functions that provide an interface to theport, as well as several functions internally used to communicate with thehardware.\section{Availability}The primary site of this package is\href{http://www-public.rz.uni-duesseldorf.de/~jochen/computer/software/rt_com/}{rt\_com   homepage}. It is also distributed with RT-Linux systems from\href{http://www.rtlinux.org}{NMT} and \href{http://ww.rtai.org}{RTAI}.\section{Installation}The rt\_com package you obtained should contain the source code(\texttt{rt\_com.h}, \texttt{rt\_com.c}, \texttt{rt\_comP.h}), the makefile(\texttt{Makefile}), some informational files (\texttt{COPYING},\texttt{License}, \texttt{README}) and this documentation --- the documetationmaster file is \texttt{rt\_com.tex}, it is also available in Portable DocumentFormat (PDF) \texttt{rt\_com.pdf}. Moreover there are a few examples to testthe module and to show you how to program it in the directory \texttt{test/}.In order to run the module on a NMT-RT-Linux v1 system (Linux kernel 2.0.x) oron RTAI you need to define \texttt{RTLINUX\_V1 or RTAI}, respectivly, atcompile time.  For this edit the \texttt{Makefile} and add the define to the\texttt{CFLAGS} variable.To compile the module \rtlin{cd} to the rt\_com directory and do \\\rtlin{make \&\& make install}. \\When you obtained this module with a RT-Linuxdistribution, see the distribution for installation instructions.\section{Interface functions}\subsection{Setting up a serial port}This is to set up the port for use by your module by providing someinitialization data. The function is declared as\begin{rtlcode}void rt_com_setup( unsigned int com, unsigned baud, unsigned parity,                   unsigned stopbits, unsigned wordlength )\end{rtlcode} where com is the entry number from the \texttt{rt\_com\_table} (seesection~\ref{sec:rt_com_table}), baud is the Baud rate the port shall beoperated at, parity determines the parity policy to use (possible values are\texttt{RT\_COM\_PARITY\_EVEN}, \texttt{RT\_COM\_PARITY\_NONE},\texttt{RT\_COM\_PARITY\_ODD} - these are defined in \texttt{rt\_com.h}),stopbits and wordlength are self explanatory and take the immediate valuethese flags shall be set at.\subsection{Writing data to a port  }To write data to a port you need to call the function \texttt{rt\_com\_write},which is declared as\begin{rtlcode}void rt_com_write( unsigned int com, char *buf, int cnt )\end{rtlcode} where com is the entry number from the \texttt{rt\_com\_table} (seesection~\ref{sec:rt_com_table}), buf is the memory address ofthe data to write to the port, cnt is the number of bytes that shall bewritten.\subsection{Reading data from a port}To read data from a port you need to call the function rt\_com\_read, which isdeclared as\begin{rtlcode}int rt_com_read( unsigned int com, char *buf, int cnt )\end{rtlcode} where com is the entry number from the \texttt{rt\_com\_table} (seesection~\ref{sec:rt_com_table}), buf is the memory address the data read shallbe put in, cnt is the maximum number of bytes that shall be read. The functionreturns the number of bytes that really have been read.\section{Internals}\subsection{Loading the module into memory}\label{sec:init_module}When the module gets loaded it requests the port memory and registers theinterrupt service routine (ISR) for each member of the rt\_com\_table (seeparagraph \ref{sec:rt_com_table} {(rt\_com\_table)}). Moreover it initializesall ports.On success it reports the loading of the module, otherwise it releases allresources, reports the failure and exits without the module beeing loaded.\subsection{Removing the module}Before the module is removed from memory, the function cleanup\_module freesall allocated resources.\section{Data Structures}\subsection{rt\_buf\_struct}\label{sec:rt_buf_struct}Structure to implement software FIFOs. Used for buffering of the data thatneeds to be written to the port and data read from hardware that needs to beread by the user. The FIFO size is given by the define\texttt{RT\_COM\_BUF\_SIZ}; it has to be a power of two.\subsection{rt\_com\_struct}Defines the hardware parameter of one serial port. The members of thisstructure are a magic number (not used yet), the base rate of the port (115200for standard ports), the port number, the interrupt number (IRQ) of the port,the flags set for this port, the ISR (see paragraph \ref{sec:init_module}{(init\_module)}) the type and a copy of the IER register. Moreover itcontains two FIFOs as defined by the {\ttfamily rt\_buf\_struc} (see paragraph\ref{sec:rt_buf_struct} {(rt\_buf\_struct)}), one for reading from the portand one for writing to it, respectively.\subsection{rt\_com\_table}\label{sec:rt_com_table}This array holds a rt\_com\_struct for each serial port to be handled by themodule.\section{Bugs}Please report bugs to \href{mailto:jochen@uni-duesseldorf.de}{Jochen K黳per}and the \href{mailto:rtl@rtlinux.cs.nmt.edu}{RT-Linux mailing list}.There are no known bugs right now. \section{Document Revision History}\noindent07. January 2000, JK: Changed from sgml to rtldoc.\noindent\textit{last changed}: \rcsInfoLongDate, \rcsInfoOwner\hfill\acknowledgements The rt\_com package is based on code sent to theReal-Time Linux mailing list by Jens Michaelsen in 1997.\href{mailto:finaz@tin.it}{Roberto Finazzi} contributed various extensions tort\_com, esp. hardware control, handshaking.  Linux is a registered trade markof Linus Torvalds.\begin{references}   \reference Daly, P.\ N.,\ Mahoney, T.\ J.,\ and K黳per, J.\    \rtlrefdp{RTLDOC \LaTeXe{} Template and Style File}{1}\end{references}\end{document}\endinput%% Local Variables:%% buffer-tag-table: TAGS%% mode: LaTeX%% mode: auto-fill%% fill-column: 78%% End: