%% rt_com documentation
%%
%% Copyright (C) 1997-2000 Jochen Küpper
%%
%% 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.1 2001/10/18 13:00:13 paolom 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üpper}
\fancyhead[CO]{The Serial Port Driver of Real-Time Linux}
\author{J.\ Küpper}
\affil{Heinrich Heine Universität, Institut für Physikalische Chemie~I,
   Universitätsstraße 1, D--40225 Düsseldorf, 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 the
terms of the GNU General Public License as published by the Free Software
Foundation either version 2 of the License, or (at your option) any later
version. 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 the
GNU General Public License for more details. You should have received a copy of
the GNU General Public License along with this document.  If not, write to the
Free Software Foundation, Inc., 675 Mass Ave, Cambridge MA 02139, USA.

\section{Copyright(s)}
\noindent
\copyright 1997-2000, Jochen Küpper. 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 note
within 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 provides
a reasonable easy software interface to the standard serial ports of the PCs
for NMT RT-Linux v1 and v2 and RTAI.

There are a small number of user functions that provide an interface to the
port, as well as several functions internally used to communicate with the
hardware.


\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 documetation
master file is \texttt{rt\_com.tex}, it is also available in Portable Document
Format (PDF) \texttt{rt\_com.pdf}. Moreover there are a few examples to test
the 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) or
on RTAI you need to define \texttt{RTLINUX\_V1 or RTAI}, respectivly, at
compile 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-Linux
distribution, 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 some
initialization 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} (see
section~\ref{sec:rt_com_table}), baud is the Baud rate the port shall be
operated 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 value
these 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} (see
section~\ref{sec:rt_com_table}), buf is the memory address of
the data to write to the port, cnt is the number of bytes that shall be
written.


\subsection{Reading data from a port}

To read data from a port you need to call the function rt\_com\_read, which is
declared 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} (see
section~\ref{sec:rt_com_table}), buf is the memory address the data read shall
be put in, cnt is the maximum number of bytes that shall be read. The function
returns 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 the
interrupt service routine (ISR) for each member of the rt\_com\_table (see
paragraph \ref{sec:rt_com_table} {(rt\_com\_table)}). Moreover it initializes
all ports.

On success it reports the loading of the module, otherwise it releases all
resources, 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 frees
all 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 that
needs to be written to the port and data read from hardware that needs to be
read 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 this
structure are a magic number (not used yet), the base rate of the port (115200
for 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 it
contains 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 port
and 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 the
module.


\section{Bugs}

Please report bugs to \href{mailto:jochen@uni-duesseldorf.de}{Jochen Küpper}
and the \href{mailto:rtl@rtlinux.cs.nmt.edu}{RT-Linux mailing list}.

There are no known bugs right now. 


\section{Document Revision History}

\noindent
07. 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 the
Real-Time Linux mailing list by Jens Michaelsen in 1997.
\href{mailto:finaz@tin.it}{Roberto Finazzi} contributed various extensions to
rt\_com, esp. hardware control, handshaking.  Linux is a registered trade mark
of Linus Torvalds.


\begin{references}
   \reference Daly, P.\ N.,\ Mahoney, T.\ J.,\ and Küpper, 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:
