diff options
Diffstat (limited to '')
-rw-r--r-- | doc/networking/decdriver.t | 569 |
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}}. |