From b41203897a7bfc7ab4a446808494e6216eff7c56 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Mon, 11 Apr 2016 13:53:58 +1000 Subject: Clean up and review of Networking User Guide. --- networking/dec_21140.rst | 176 ++++++++++++++++++++++------------------------- 1 file changed, 81 insertions(+), 95 deletions(-) (limited to 'networking/dec_21140.rst') diff --git a/networking/dec_21140.rst b/networking/dec_21140.rst index 9064508..03133d8 100644 --- a/networking/dec_21140.rst +++ b/networking/dec_21140.rst @@ -6,20 +6,19 @@ DEC 21240 Driver Introduction .. COMMENT: 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 +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. +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 . +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 . Document Revision History ========================= @@ -47,15 +46,15 @@ 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, ... +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. +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. .. COMMENT: PCI Device's Configuration Header Space Format @@ -65,17 +64,16 @@ on a PowerPC target. .. COMMENT: 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 ``pci_initialize()`` 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``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 *DIGITAL -Semiconductor 21140A PCI Fast Ethernet LAN Controller +On RTEMS, a PCI API exists. We have used it to configure the board. After +initializing this PCI module via the ``pci_initialize()`` 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``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 *DIGITAL Semiconductor 21140A PCI Fast Ethernet LAN Controller - Hardware Reference Manual*. .. COMMENT: fix citation @@ -89,16 +87,17 @@ host memory and the 2 threads launched at the initialization time. 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 ``rtems_dec21140_driver_attach````(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 +The DEC21140 Ethernet driver keeps the same software architecture than the +other RTEMS ethernet drivers. The only API the programmer can use is the +``rtems_dec21140_driver_attach(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. @@ -108,19 +107,18 @@ Memory Buffer .. COMMENT: 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 +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 *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. +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]. +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. .. COMMENT: Buffer Descriptor @@ -132,12 +130,12 @@ 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). +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). Transmitter Thread ------------------ @@ -151,47 +149,37 @@ 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 *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. - -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. +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 *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. 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. +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. +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. List of Ethernet cards using the DEC chip ========================================= @@ -238,9 +226,7 @@ of adapters which support this driver : Our DEC driver has not been tested with all these cards, only with the D-Link DFE500-TX. -- *[DEC21140 Hardware Manual] DIGITAL, *DIGITAL - Semiconductor 21140A PCI Fast Ethernet LAN Controller - Hardware - Reference Manual**. +- DEC21140 Hardware Manual DIGITAL, DIGITAL Semiconductor 21140A PCI Fast + Ethernet LAN Controller - Hardware Reference Manual**. - *[99.TA.0021.M.ER]Emmanuel Raguet,*RTEMS Cache Management For Intel**. - -- cgit v1.2.3