203 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3===========================4The Spidernet Device Driver5===========================6 7Written by Linas Vepstas <linas@austin.ibm.com>8 9Version of 7 June 200710 11Abstract12========13This document sketches the structure of portions of the spidernet14device driver in the Linux kernel tree. The spidernet is a gigabit15ethernet device built into the Toshiba southbridge commonly used16in the SONY Playstation 3 and the IBM QS20 Cell blade.17 18The Structure of the RX Ring.19=============================20The receive (RX) ring is a circular linked list of RX descriptors,21together with three pointers into the ring that are used to manage its22contents.23 24The elements of the ring are called "descriptors" or "descrs"; they25describe the received data. This includes a pointer to a buffer26containing the received data, the buffer size, and various status bits.27 28There are three primary states that a descriptor can be in: "empty",29"full" and "not-in-use". An "empty" or "ready" descriptor is ready30to receive data from the hardware. A "full" descriptor has data in it,31and is waiting to be emptied and processed by the OS. A "not-in-use"32descriptor is neither empty or full; it is simply not ready. It may33not even have a data buffer in it, or is otherwise unusable.34 35During normal operation, on device startup, the OS (specifically, the36spidernet device driver) allocates a set of RX descriptors and RX37buffers. These are all marked "empty", ready to receive data. This38ring is handed off to the hardware, which sequentially fills in the39buffers, and marks them "full". The OS follows up, taking the full40buffers, processing them, and re-marking them empty.41 42This filling and emptying is managed by three pointers, the "head"43and "tail" pointers, managed by the OS, and a hardware current44descriptor pointer (GDACTDPA). The GDACTDPA points at the descr45currently being filled. When this descr is filled, the hardware46marks it full, and advances the GDACTDPA by one. Thus, when there is47flowing RX traffic, every descr behind it should be marked "full",48and everything in front of it should be "empty". If the hardware49discovers that the current descr is not empty, it will signal an50interrupt, and halt processing.51 52The tail pointer tails or trails the hardware pointer. When the53hardware is ahead, the tail pointer will be pointing at a "full"54descr. The OS will process this descr, and then mark it "not-in-use",55and advance the tail pointer. Thus, when there is flowing RX traffic,56all of the descrs in front of the tail pointer should be "full", and57all of those behind it should be "not-in-use". When RX traffic is not58flowing, then the tail pointer can catch up to the hardware pointer.59The OS will then note that the current tail is "empty", and halt60processing.61 62The head pointer (somewhat mis-named) follows after the tail pointer.63When traffic is flowing, then the head pointer will be pointing at64a "not-in-use" descr. The OS will perform various housekeeping duties65on this descr. This includes allocating a new data buffer and66dma-mapping it so as to make it visible to the hardware. The OS will67then mark the descr as "empty", ready to receive data. Thus, when there68is flowing RX traffic, everything in front of the head pointer should69be "not-in-use", and everything behind it should be "empty". If no70RX traffic is flowing, then the head pointer can catch up to the tail71pointer, at which point the OS will notice that the head descr is72"empty", and it will halt processing.73 74Thus, in an idle system, the GDACTDPA, tail and head pointers will75all be pointing at the same descr, which should be "empty". All of the76other descrs in the ring should be "empty" as well.77 78The show_rx_chain() routine will print out the locations of the79GDACTDPA, tail and head pointers. It will also summarize the contents80of the ring, starting at the tail pointer, and listing the status81of the descrs that follow.82 83A typical example of the output, for a nearly idle system, might be::84 85 net eth1: Total number of descrs=25686 net eth1: Chain tail located at descr=2087 net eth1: Chain head is at 2088 net eth1: HW curr desc (GDACTDPA) is at 2189 net eth1: Have 1 descrs with stat=x4080010190 net eth1: HW next desc (GDACNEXTDA) is at 2291 net eth1: Last 255 descrs with stat=xa080000092 93In the above, the hardware has filled in one descr, number 20. Both94head and tail are pointing at 20, because it has not yet been emptied.95Meanwhile, hw is pointing at 21, which is free.96 97The "Have nnn decrs" refers to the descr starting at the tail: in this98case, nnn=1 descr, starting at descr 20. The "Last nnn descrs" refers99to all of the rest of the descrs, from the last status change. The "nnn"100is a count of how many descrs have exactly the same status.101 102The status x4... corresponds to "full" and status xa... corresponds103to "empty". The actual value printed is RXCOMST_A.104 105In the device driver source code, a different set of names are106used for these same concepts, so that::107 108 "empty" == SPIDER_NET_DESCR_CARDOWNED == 0xa109 "full" == SPIDER_NET_DESCR_FRAME_END == 0x4110 "not in use" == SPIDER_NET_DESCR_NOT_IN_USE == 0xf111 112 113The RX RAM full bug/feature114===========================115 116As long as the OS can empty out the RX buffers at a rate faster than117the hardware can fill them, there is no problem. If, for some reason,118the OS fails to empty the RX ring fast enough, the hardware GDACTDPA119pointer will catch up to the head, notice the not-empty condition,120ad stop. However, RX packets may still continue arriving on the wire.121The spidernet chip can save some limited number of these in local RAM.122When this local ram fills up, the spider chip will issue an interrupt123indicating this (GHIINT0STS will show ERRINT, and the GRMFLLINT bit124will be set in GHIINT1STS). When the RX ram full condition occurs,125a certain bug/feature is triggered that has to be specially handled.126This section describes the special handling for this condition.127 128When the OS finally has a chance to run, it will empty out the RX ring.129In particular, it will clear the descriptor on which the hardware had130stopped. However, once the hardware has decided that a certain131descriptor is invalid, it will not restart at that descriptor; instead132it will restart at the next descr. This potentially will lead to a133deadlock condition, as the tail pointer will be pointing at this descr,134which, from the OS point of view, is empty; the OS will be waiting for135this descr to be filled. However, the hardware has skipped this descr,136and is filling the next descrs. Since the OS doesn't see this, there137is a potential deadlock, with the OS waiting for one descr to fill,138while the hardware is waiting for a different set of descrs to become139empty.140 141A call to show_rx_chain() at this point indicates the nature of the142problem. A typical print when the network is hung shows the following::143 144 net eth1: Spider RX RAM full, incoming packets might be discarded!145 net eth1: Total number of descrs=256146 net eth1: Chain tail located at descr=255147 net eth1: Chain head is at 255148 net eth1: HW curr desc (GDACTDPA) is at 0149 net eth1: Have 1 descrs with stat=xa0800000150 net eth1: HW next desc (GDACNEXTDA) is at 1151 net eth1: Have 127 descrs with stat=x40800101152 net eth1: Have 1 descrs with stat=x40800001153 net eth1: Have 126 descrs with stat=x40800101154 net eth1: Last 1 descrs with stat=xa0800000155 156Both the tail and head pointers are pointing at descr 255, which is157marked xa... which is "empty". Thus, from the OS point of view, there158is nothing to be done. In particular, there is the implicit assumption159that everything in front of the "empty" descr must surely also be empty,160as explained in the last section. The OS is waiting for descr 255 to161become non-empty, which, in this case, will never happen.162 163The HW pointer is at descr 0. This descr is marked 0x4.. or "full".164Since its already full, the hardware can do nothing more, and thus has165halted processing. Notice that descrs 0 through 254 are all marked166"full", while descr 254 and 255 are empty. (The "Last 1 descrs" is167descr 254, since tail was at 255.) Thus, the system is deadlocked,168and there can be no forward progress; the OS thinks there's nothing169to do, and the hardware has nowhere to put incoming data.170 171This bug/feature is worked around with the spider_net_resync_head_ptr()172routine. When the driver receives RX interrupts, but an examination173of the RX chain seems to show it is empty, then it is probable that174the hardware has skipped a descr or two (sometimes dozens under heavy175network conditions). The spider_net_resync_head_ptr() subroutine will176search the ring for the next full descr, and the driver will resume177operations there. Since this will leave "holes" in the ring, there178is also a spider_net_resync_tail_ptr() that will skip over such holes.179 180As of this writing, the spider_net_resync() strategy seems to work very181well, even under heavy network loads.182 183 184The TX ring185===========186The TX ring uses a low-watermark interrupt scheme to make sure that187the TX queue is appropriately serviced for large packet sizes.188 189For packet sizes greater than about 1KBytes, the kernel can fill190the TX ring quicker than the device can drain it. Once the ring191is full, the netdev is stopped. When there is room in the ring,192the netdev needs to be reawakened, so that more TX packets are placed193in the ring. The hardware can empty the ring about four times per jiffy,194so its not appropriate to wait for the poll routine to refill, since195the poll routine runs only once per jiffy. The low-watermark mechanism196marks a descr about 1/4th of the way from the bottom of the queue, so197that an interrupt is generated when the descr is processed. This198interrupt wakes up the netdev, which can then refill the queue.199For large packets, this mechanism generates a relatively small number200of interrupts, about 1K/sec. For smaller packets, this will drop to zero201interrupts, as the hardware can empty the queue faster than the kernel202can fill it.203