First attempt to build.

1 files changed, 305 insertions, 264 deletions

diff --git a/doc/networking/decdriver.t b/doc/networking/decdriver.t
index b55b192f24..4b845900c5 100644
--- a/doc/networking/decdriver.t
+++ b/doc/networking/decdriver.t
@@ -1,264 +1,305 @@
-%% This LaTeX-file was created by <raguet> Wed Apr  7 17:10:33 1999

-%% LyX 1.0 (C) 1995-1999 by Matthias Ettrich and the LyX Team

-

-%% Do not edit this file unless you know what you are doing.

-\documentclass[10pt,american]{article}

-\usepackage[T1]{fontenc}

-\usepackage{a4wide}

-\pagestyle{plain}

-\usepackage{babel}

-\usepackage[dvips]{graphics}

-

-\makeatletter

-

-

-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.

-\providecommand{\LyX}{L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}

-

-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.

-\usepackage[dvips]{epsfig}

-

-\makeatother

-

-\begin{document}

-

-\resizebox*{1\textwidth}{!}{\includegraphics{garde.eps}} 

-

-{\par\centering \newpage\par}

-\vspace{0.3cm}

-

-\bigskip{}

-{\par\centering \textbf{\Huge Ethernet Driver for PCI DEC board}\Huge \par}

-\bigskip{}

-

-\tableofcontents{}

-

-\listoffigures{}

-

-\newpage

-

-

-\section{\noindent Introduction}

-

-One aim of our project is to port RTEMS on a standard PowerPC platform. To achieve

-it, we have chosen a Motorola MCP750 board. This board includes an Ethernet

-controller based on a DEC21140 chip. Because RTEMS has a TCP/IP stack, we will

-have to develop the DEC21140 related ethernet driver for the PowerPC port of

-RTEMS. As this controller is able to support 100Mbps network and as there is

-a lot of PCI card using this DEC chip (cf \ref{List}), we have decided to first

-implement this driver on an Intel PC386 target to provide a solution for using

-RTEMS on PC with the 100Mbps network and then to port this code on PowerPC in

-a second phase.\\

-

-

-\noindent The aim of this document is to give some PCI board generalities and

-to explain the software architecture of the RTEMS driver. Finally, we will see

-what will be done for ChorusOs and Netboot environment .

-

-

-\section{Document Revision History}

-

-\underbar{Current release} : 

-

-\begin{itemize}

-\item \noindent Current applicable release is 1.0.

-\end{itemize}

-\noindent \underbar{Existing releases} :

-

-\begin{itemize}

-\item \noindent 1.0 : Released the 10/02/98. First version of this document.

-\item 0.1 : First draft of this document

-\end{itemize}

-\noindent \underbar{Planned releases} :

-

-\begin{itemize}

-\item \noindent None planned today.

-\end{itemize}

-

-\section{DEC21140 PCI Board Generalities}

-

-This chapter describes rapidely the PCI interface of this Ethernet controller.

-The board we have chosen for our PC386 implementation is a D-Link DFE-500TX.

-This is a dual-speed 10/100Mbps Ethernet PCI adapter with a DEC21140AF chip.

-Like other PCI devices, this board has a PCI device's header containing some

-required configuration registers, as shown in figure \ref{PCI reg}. By reading

-or writing these registers, a driver can obtain information about the type of

-the board, the interrupt it uses, the mapping of the chip specific registers,~...

-\\

-

-

-\noindent On Intel target, the chip specific registers can be accessed via 2

-methods : I/O port access or PCI address mapped access. We have chosen to implement

-the PCI address access to obtain compatible source code to the port the driver

-on a PowerPC target.\\

-

-

-\begin{figure}

-{\par\centering \includegraphics{PCI_reg.eps} \par}

-

-

-\caption{\label{PCI reg}PCI device's configuration header space format}

-\end{figure}

-On RTEMS, a PCI API exists. We have used it to configure the board. After initializing

-this PCI module via the \textbf{\textit{pcib\_init()}} function, we try to detect

-the DEC21140 based ethernet board. This board is characterized by its Vendor

-ID (0x1011) and its Device ID (0x0009). We give these arguments to the \textbf{\textit{pcib\_find\_by\_deviceid}}

-function which returns , if the device is present, a pointer to the configuration

-header space (cf fig \ref{PCI reg}). Once this operation performed, the driver

-is able to extract the information it needs to configure the board internal

-registers, like the interrupt line, the base address,... The board internal

-registers will not be detailled here. You can find them in \cite{1}.\newpage

-

-

-\section{\noindent RTEMS Driver Software Architecture}

-

-In this chapter will see the initialization phase, how the controller uses the

-host memory and the 2 threads launched at the initialization time. 

-

-

-\subsection{Initialization phase}

-

-The DEC21140 Ethernet driver keeps the same software architecture than the other

-RTEMS ethernet drivers. The only API the programmer can use is the \textbf{\textit{``rtems\_dec21140\_driver\_attach}}\\

-\textbf{\textit{(struct rtems\_bsdnet\_ifconfig {*}config)''}} function which

-detects the board and initializes the associated data structure (with registers

-base address, entry points to low-level initialization function,...), if the

-board is found. 

-

-\noindent Once the attach function executed, the driver initializes the DEC

-chip. Then the driver connects an interrupt handler to the interrupt line driven

-by the Ethernet controller (the only interrupt which will be treated is the

-receive interrupt) and launches 2 threads : a receiver thread and a transmitter

-thread. Then the driver waits for incoming frame to give to the protocol stack

-or outcoming frame to send on the physical link.

-

-

-\subsection{Memory Buffer}

-

-This DEC chip uses the host memory to store the incoming Ethernet frames and

-the descriptor of these frames. We have chosen to use 7 receive buffers and

-1 transmit buffer to optimize memory allocation due to cache and paging problem

-that will be explained in paragraph \ref{Problem}).\\

-

-

-\noindent To reference these buffers to the DEC chip we use a buffer descriptors

-ring. The descriptor structure is defined in figure \ref{bdescr}. Each descriptor

-can reference one or two memory buffers. We choose to use only one buffer of

-1520 bytes per descriptor.\\

-

-

-\noindent The difference between a receive and a transmit buffer descriptor

-is located in the status and control bits fields. We do not give details here,

-please refer to \cite{1}.

-

-\begin{figure}

-{\par\centering \includegraphics{recv_bd.eps} \par}

-

-

-\caption{\label{bdescr}Buffer Descriptor}

-\end{figure}

-

-

-

-\subsection{Receiver Thread}

-

-This thread is event driven. Each time a DEC PCI board interrupt occurs, the

-handler checks if this is a receive interrupt and send an event ``reception''

-to the receiver thread which looks into the entire buffer descriptors ring the

-ones that contain a valid incoming frame (bit OWN=0 means descriptor belongs

-to host processor). Each valid incoming ethernet frame is sent to the protocol

-stack and the buffer descriptor is given back to the DEC board (the host processor

-reset bit OWN, which means descriptor belongs to 21140).

-

-

-\subsection{Transmitter Thread}

-

-This thread is also event driven. Each time an Ethernet frame is put in the

-transmit queue, an event is sent to the transmit thread, which empty the queue

-by sending each outcoming frame. Because we use only one transmit buffer, we

-are sure that the frame is well-sent before sending the next.

-

-

-\section{\label{Problem}Encountered Problems}

-

-On Intel PC386 target, we were faced with a problem of memory cache management.

-Because the DEC chip uses the host memory to store the incoming frame and because

-the DEC21140 configuration registers are mapped into the PCI address space,

-we must ensure that the data read (or written) by the host processor are the

-ones written (or read) by the DEC21140 device in the host memory and not old

-data stored in the cache memory. Therefore, we had to provide a way to manage

-the cache. This module is described in the document \cite{2}. On Intel, the

-memory region cache management is available only if the paging unit is enabled.

-We have used this paging mechanism, with 4Kb page. All the buffers allocated

-to store the incoming or outcoming frames, buffer descriptor and also the PCI

-address space of the DEC board are located in a memory space with cache disable.\\

-

-

-\noindent Concerning the buffers and their descriptors, we have tried to optimize

-the memory space in term of allocated page. One buffer has 1520 bytes, one descriptor

-has 16 bytes. We have 7 receive buffers and 1 transmit buffer, and for each,

-1 descriptor : (7+1){*}(1520+16) = 12288 bytes = 12Kb = 3 entire pages. This

-allows not to lose too much memory or not to disable cache memory for a page

-which contains other data than buffer, which could decrease performance.

-

-

-\section{ChorusOs DEC Driver}

-

-Because ChorusOs is used in several Canon CRF projects, we must provide such

-a driver on this OS to ensure compatibility between the RTEMS and ChorusOs developments.

-On ChorusOs, a DEC driver source code already exists but only for a PowerPC

-target. We plan to port this code (which uses ChorusOs API) on Intel target.

-This will allow us to have homogeneous developments. Moreover, the port of the

-development performed with ChorusOs environment to RTEMS environment will be

-easier for the developers.

-

-

-\section{Netboot DEC driver}

-

-We use Netboot tool to load our development from a server to the target via

-an ethernet network. Currently, this tool does not support the DEC board. We

-plan to port the DEC driver for the Netboot tool.\\

-

-

-\noindent But concerning the port of the DEC driver into Netboot, we are faced

-with a problem : in RTEMS environment, the DEC driver is interrupt or event

-driven, in Netboot environment, it must be used in polling mode. It means that

-we will have to re-write some mechanisms of this driver.

-

-

-\section{\label{List}List of Ethernet cards using the DEC chip}

-

-Many Ethernet adapter cards use the Tulip chip. Here is a non exhaustive list

-of adapters which support this driver :

-

-\begin{itemize}

-\item Accton EtherDuo PCI.

-\item Accton EN1207 All three media types supported.

-\item Adaptec ANA6911/TX 21140-AC.

-\item Cogent EM110 21140-A with DP83840 N-Way MII transceiver.

-\item Cogent EM400 EM100 with 4 21140 100mbps-only ports + PCI Bridge.

-\item Danpex EN-9400P3.

-\item D-Link DFE500-Tx 21140-A with DP83840 transceiver.

-\item Kingston EtherX KNE100TX 21140AE.

-\item Netgear FX310 TX 10/100 21140AE. 

-\item SMC EtherPower10/100 With DEC21140 and 68836 SYM transceiver. 

-\item SMC EtherPower10/100 With DEC21140-AC and DP83840 MII transceiver. \\

-Note: The EtherPower II uses the EPIC chip, which requires a different driver. 

-\item Surecom EP-320X DEC 21140. 

-\item Thomas Conrad TC5048. 

-\item Znyx ZX345 21140-A, usually with the DP83840 N-Way MII transciever. Some ZX345

-cards made in 1996 have an ICS 1890 transciver instead. 

-\item ZNYX ZX348 Two 21140-A chips using ICS 1890 transcievers and either a 21052

-or 21152 bridge. Early versions used National 83840 transcievers, but later

-versions are depopulated ZX346 boards. 

-\item ZNYX ZX351 21140 chip with a Broadcom 100BaseT4 transciever. 

-\end{itemize}

-Our DEC driver has not been tested with all these cards, only with the D-Link

-DFE500-TX.

-

-\begin{thebibliography}{DEC21140 Hardware Manual}

-\bibitem[DEC21140 Hardware Manual]{1}DIGITAL, \textit{DIGITAL Semiconductor 21140A PCI Fast Ethernet LAN Controller

-- Hardware Reference Manual.}

-\bibitem[99.TA.0021.M.ER]{2}Emmanuel Raguet, \textit{RTEMS Cache Management For Intel.}

-\end{thebibliography}

-\end{document}

+@c 
+@c  RTEMS Remote Debugger Server Specifications
+@c
+@c  Written by: Emmanuel Raguet <raguet@crf.canon.fr>
+@c
+@c
+@c  $Id$
+@c
+
+@chatper DEC 21140 Driver
+
+@section Introduction
+
+@c XXX add back in cross reference to list of boards.
+
+One aim of our project is to port RTEMS on a standard PowerPC platform. To achieve
+it, we have chosen a Motorola MCP750 board. This board includes an Ethernet
+controller based on a DEC21140 chip. Because RTEMS has a TCP/IP stack, we will
+have to develop the DEC21140 related ethernet driver for the PowerPC port of
+RTEMS. As this controller is able to support 100Mbps network and as there is
+a lot of PCI card using this DEC chip, we have decided to first
+implement this driver on an Intel PC386 target to provide a solution for using
+RTEMS on PC with the 100Mbps network and then to port this code on PowerPC in
+a second phase.
+
+
+The aim of this document is to give some PCI board generalities and
+to explain the software architecture of the RTEMS driver. Finally, we will see
+what will be done for ChorusOs and Netboot environment .
+
+
+@section Document Revision History
+
+@b{Current release}: 
+
+@itemize @bullet
+@item Current applicable release is 1.0.
+@end itemize
+@b{Existing releases}:
+
+@itemize @bullet
+@item 1.0 : Released the 10/02/98. First version of this document.
+@item 0.1 : First draft of this document
+@end itemize
+@b{Planned releases}:
+
+@itemize @bullet
+@item None planned today.
+@end itemize
+
+@section DEC21140 PCI Board Generalities
+
+@c XXX add crossreference to PCI Register Figure
+This chapter describes rapidely the PCI interface of this Ethernet controller.
+The board we have chosen for our PC386 implementation is a D-Link DFE-500TX.
+This is a dual-speed 10/100Mbps Ethernet PCI adapter with a DEC21140AF chip.
+Like other PCI devices, this board has a PCI device's header containing some
+required configuration registers, as shown in the PCI Register Figure.
+By reading
+or writing these registers, a driver can obtain information about the type of
+the board, the interrupt it uses, the mapping of the chip specific registers, ...
+
+
+
+On Intel target, the chip specific registers can be accessed via 2
+methods : I/O port access or PCI address mapped access. We have chosen to implement
+the PCI address access to obtain compatible source code to the port the driver
+on a PowerPC target.
+
+@c
+@c PCI Device's Configuration Header Space Format
+@c
+
+@ifset use-ascii
+@example
+@group
+XXXXX reference it in the previous paragraph
+XXXXX insert PCI_reg.eps
+XXXXX Caption PCI Device's Configuration Header Space Format
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@example
+@group
+XXXXX reference it in the previous paragraph
+XXXXX insert PCI_reg.eps
+XXXXX Caption PCI Device's Configuration Header Space Format
+@end group
+@end example
+@end ifset
+
+@c @image{PCI_reg}
+
+@ifset use-html
+@c <IMG SRC="PCI_reg.jpg" WIDTH=500 HEIGHT=600 ALT="PCI Device's Configuration Header Space Format">
+@html
+<IMG SRC="PCI_reg.jpg" ALT="PCI Device's Configuration Header Space Format">
+@end html
+@end ifset
+
+
+@c XXX add crossreference to PCI Register Figure
+
+On RTEMS, a PCI API exists. We have used it to configure the board. After initializing
+this PCI module via the @code{pcib_init()} function, we try to detect
+the DEC21140 based ethernet board. This board is characterized by its Vendor
+ID (0x1011) and its Device ID (0x0009). We give these arguments to the
+@code{pcib_find_by_deviceid}
+function which returns , if the device is present, a pointer to the configuration
+header space (see PCI Registers Fgure). Once this operation performed,
+the driver
+is able to extract the information it needs to configure the board internal
+registers, like the interrupt line, the base address,... The board internal
+registers will not be detailled here. You can find them in @title{DIGITAL
+Semiconductor 21140A PCI Fast Ethernet LAN Controller
+- Hardware Reference Manual}.
+
+@c fix citation
+
+
+@section RTEMS Driver Software Architecture
+
+In this chapter will see the initialization phase, how the controller uses the
+host memory and the 2 threads launched at the initialization time. 
+
+
+@subsection Initialization phase
+
+The DEC21140 Ethernet driver keeps the same software architecture than the other
+RTEMS ethernet drivers. The only API the programmer can use is the @code{rtems_dec21140_driver_attach}
+@code{(struct rtems_bsdnet_ifconfig *config)} function which
+detects the board and initializes the associated data structure (with registers
+base address, entry points to low-level initialization function,...), if the
+board is found. 
+
+Once the attach function executed, the driver initializes the DEC
+chip. Then the driver connects an interrupt handler to the interrupt line driven
+by the Ethernet controller (the only interrupt which will be treated is the
+receive interrupt) and launches 2 threads : a receiver thread and a transmitter
+thread. Then the driver waits for incoming frame to give to the protocol stack
+or outcoming frame to send on the physical link.
+
+
+@subsection Memory Buffer
+
+@c XXX add cross reference to Problem
+This DEC chip uses the host memory to store the incoming Ethernet frames and
+the descriptor of these frames. We have chosen to use 7 receive buffers and
+1 transmit buffer to optimize memory allocation due to cache and paging problem
+that will be explained in the section @b{Encountered Problems.
+
+
+To reference these buffers to the DEC chip we use a buffer descriptors
+ring. The descriptor structure is defined in the Buffer Descriptor Figure.
+Each descriptor
+can reference one or two memory buffers. We choose to use only one buffer of
+1520 bytes per descriptor.
+
+
+The difference between a receive and a transmit buffer descriptor
+is located in the status and control bits fields. We do not give details here,
+please refer to the [DEC21140 Hardware Manual].
+
+@c 
+@c Buffer Descriptor
+@c
+
+@ifset use-ascii
+@example
+@group
+XXXXX reference it in the previous paragraph
+XXXXX insert recv_bd.eps
+XXXXX Caption Buffer Descriptor
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@example
+@group
+XXXXX reference it in the previous paragraph
+XXXXX insert recv_bd.eps
+XXXXX Caption Buffer Descriptor
+@end group
+@end example
+@end ifset
+
+@c @image{recv_bd}
+
+@ifset use-html
+@c <IMG SRC="recv_bd.jpg" WIDTH=500 HEIGHT=600 ALT="Buffer Descriptor">
+@html
+<IMG SRC="recv_bd.jpg" ALT="Buffer Descriptor">
+@end html
+@end ifset
+
+
+
+@subsection Receiver Thread
+
+This thread is event driven. Each time a DEC PCI board interrupt occurs, the
+handler checks if this is a receive interrupt and send an event ``reception''
+to the receiver thread which looks into the entire buffer descriptors ring the
+ones that contain a valid incoming frame (bit OWN=0 means descriptor belongs
+to host processor). Each valid incoming ethernet frame is sent to the protocol
+stack and the buffer descriptor is given back to the DEC board (the host processor
+reset bit OWN, which means descriptor belongs to 21140).
+
+
+@subsection Transmitter Thread
+
+This thread is also event driven. Each time an Ethernet frame is put in the
+transmit queue, an event is sent to the transmit thread, which empty the queue
+by sending each outcoming frame. Because we use only one transmit buffer, we
+are sure that the frame is well-sent before sending the next.
+
+
+@section Encountered Problems
+
+On Intel PC386 target, we were faced with a problem of memory cache management.
+Because the DEC chip uses the host memory to store the incoming frame and because
+the DEC21140 configuration registers are mapped into the PCI address space,
+we must ensure that the data read (or written) by the host processor are the
+ones written (or read) by the DEC21140 device in the host memory and not old
+data stored in the cache memory. Therefore, we had to provide a way to manage
+the cache. This module is described in the document @b{RTEMS
+Cache Management For Intel}. On Intel, the
+memory region cache management is available only if the paging unit is enabled.
+We have used this paging mechanism, with 4Kb page. All the buffers allocated
+to store the incoming or outcoming frames, buffer descriptor and also the PCI
+address space of the DEC board are located in a memory space with cache disable.
+
+
+Concerning the buffers and their descriptors, we have tried to optimize
+the memory space in term of allocated page. One buffer has 1520 bytes, one descriptor
+has 16 bytes. We have 7 receive buffers and 1 transmit buffer, and for each,
+1 descriptor : (7+1)*(1520+16) = 12288 bytes = 12Kb = 3 entire pages. This
+allows not to lose too much memory or not to disable cache memory for a page
+which contains other data than buffer, which could decrease performance.
+
+
+@section ChorusOs DEC Driver
+
+Because ChorusOs is used in several Canon CRF projects, we must provide such
+a driver on this OS to ensure compatibility between the RTEMS and ChorusOs developments.
+On ChorusOs, a DEC driver source code already exists but only for a PowerPC
+target. We plan to port this code (which uses ChorusOs API) on Intel target.
+This will allow us to have homogeneous developments. Moreover, the port of the
+development performed with ChorusOs environment to RTEMS environment will be
+easier for the developers.
+
+
+@section Netboot DEC driver
+
+We use Netboot tool to load our development from a server to the target via
+an ethernet network. Currently, this tool does not support the DEC board. We
+plan to port the DEC driver for the Netboot tool.
+
+
+But concerning the port of the DEC driver into Netboot, we are faced
+with a problem : in RTEMS environment, the DEC driver is interrupt or event
+driven, in Netboot environment, it must be used in polling mode. It means that
+we will have to re-write some mechanisms of this driver.
+
+
+@section List of Ethernet cards using the DEC chip
+
+Many Ethernet adapter cards use the Tulip chip. Here is a non exhaustive list
+of adapters which support this driver :
+
+@itemize @bullet
+@item Accton EtherDuo PCI.
+@item Accton EN1207 All three media types supported.
+@item Adaptec ANA6911/TX 21140-AC.
+@item Cogent EM110 21140-A with DP83840 N-Way MII transceiver.
+@item Cogent EM400 EM100 with 4 21140 100mbps-only ports + PCI Bridge.
+@item Danpex EN-9400P3.
+@item D-Link DFE500-Tx 21140-A with DP83840 transceiver.
+@item Kingston EtherX KNE100TX 21140AE.
+@item Netgear FX310 TX 10/100 21140AE. 
+@item SMC EtherPower10/100 With DEC21140 and 68836 SYM transceiver. 
+@item SMC EtherPower10/100 With DEC21140-AC and DP83840 MII transceiver. 
+Note: The EtherPower II uses the EPIC chip, which requires a different driver. 
+@item Surecom EP-320X DEC 21140. 
+@item Thomas Conrad TC5048. 
+@item Znyx ZX345 21140-A, usually with the DP83840 N-Way MII transciever. Some ZX345
+cards made in 1996 have an ICS 1890 transciver instead. 
+@item ZNYX ZX348 Two 21140-A chips using ICS 1890 transcievers and either a 21052
+or 21152 bridge. Early versions used National 83840 transcievers, but later
+versions are depopulated ZX346 boards. 
+@item ZNYX ZX351 21140 chip with a Broadcom 100BaseT4 transciever. 
+@end itemize
+
+Our DEC driver has not been tested with all these cards, only with the D-Link
+DFE500-TX.
+
+@itemize @code{ }
+@item @cite{[DEC21140 Hardware Manual] DIGITAL, @b{DIGITAL
+Semiconductor 21140A PCI Fast Ethernet LAN Controller - Hardware
+Reference Manual}}.
+
+@item @cite{[99.TA.0021.M.ER]Emmanuel Raguet,
+@b{RTEMS Cache Management For Intel}}.