cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

vortex.rst (15368B)


      1.. SPDX-License-Identifier: GPL-2.0
      2
      3=========================
      43Com Vortex device driver
      5=========================
      6
      7Andrew Morton
      8
      930 April 2000
     10
     11
     12This document describes the usage and errata of the 3Com "Vortex" device
     13driver for Linux, 3c59x.c.
     14
     15The driver was written by Donald Becker <becker@scyld.com>
     16
     17Don is no longer the prime maintainer of this version of the driver.
     18Please report problems to one or more of:
     19
     20- Andrew Morton
     21- Netdev mailing list <netdev@vger.kernel.org>
     22- Linux kernel mailing list <linux-kernel@vger.kernel.org>
     23
     24Please note the 'Reporting and Diagnosing Problems' section at the end
     25of this file.
     26
     27
     28Since kernel 2.3.99-pre6, this driver incorporates the support for the
     293c575-series Cardbus cards which used to be handled by 3c575_cb.c.
     30
     31This driver supports the following hardware:
     32
     33	- 3c590 Vortex 10Mbps
     34	- 3c592 EISA 10Mbps Demon/Vortex
     35	- 3c597 EISA Fast Demon/Vortex
     36	- 3c595 Vortex 100baseTx
     37	- 3c595 Vortex 100baseT4
     38	- 3c595 Vortex 100base-MII
     39	- 3c900 Boomerang 10baseT
     40	- 3c900 Boomerang 10Mbps Combo
     41	- 3c900 Cyclone 10Mbps TPO
     42	- 3c900 Cyclone 10Mbps Combo
     43	- 3c900 Cyclone 10Mbps TPC
     44	- 3c900B-FL Cyclone 10base-FL
     45	- 3c905 Boomerang 100baseTx
     46	- 3c905 Boomerang 100baseT4
     47	- 3c905B Cyclone 100baseTx
     48	- 3c905B Cyclone 10/100/BNC
     49	- 3c905B-FX Cyclone 100baseFx
     50	- 3c905C Tornado
     51	- 3c920B-EMB-WNM (ATI Radeon 9100 IGP)
     52	- 3c980 Cyclone
     53	- 3c980C Python-T
     54	- 3cSOHO100-TX Hurricane
     55	- 3c555 Laptop Hurricane
     56	- 3c556 Laptop Tornado
     57	- 3c556B Laptop Hurricane
     58	- 3c575 [Megahertz] 10/100 LAN  CardBus
     59	- 3c575 Boomerang CardBus
     60	- 3CCFE575BT Cyclone CardBus
     61	- 3CCFE575CT Tornado CardBus
     62	- 3CCFE656 Cyclone CardBus
     63	- 3CCFEM656B Cyclone+Winmodem CardBus
     64	- 3CXFEM656C Tornado+Winmodem CardBus
     65	- 3c450 HomePNA Tornado
     66	- 3c920 Tornado
     67	- 3c982 Hydra Dual Port A
     68	- 3c982 Hydra Dual Port B
     69	- 3c905B-T4
     70	- 3c920B-EMB-WNM Tornado
     71
     72Module parameters
     73=================
     74
     75There are several parameters which may be provided to the driver when
     76its module is loaded.  These are usually placed in ``/etc/modprobe.d/*.conf``
     77configuration files.  Example::
     78
     79    options 3c59x debug=3 rx_copybreak=300
     80
     81If you are using the PCMCIA tools (cardmgr) then the options may be
     82placed in /etc/pcmcia/config.opts::
     83
     84    module "3c59x" opts "debug=3 rx_copybreak=300"
     85
     86
     87The supported parameters are:
     88
     89debug=N
     90
     91  Where N is a number from 0 to 7.  Anything above 3 produces a lot
     92  of output in your system logs.  debug=1 is default.
     93
     94options=N1,N2,N3,...
     95
     96  Each number in the list provides an option to the corresponding
     97  network card.  So if you have two 3c905's and you wish to provide
     98  them with option 0x204 you would use::
     99
    100    options=0x204,0x204
    101
    102  The individual options are composed of a number of bitfields which
    103  have the following meanings:
    104
    105  Possible media type settings
    106
    107	==	=================================
    108	0	10baseT
    109	1	10Mbs AUI
    110	2	undefined
    111	3	10base2 (BNC)
    112	4	100base-TX
    113	5	100base-FX
    114	6	MII (Media Independent Interface)
    115	7	Use default setting from EEPROM
    116	8       Autonegotiate
    117	9       External MII
    118	10      Use default setting from EEPROM
    119	==	=================================
    120
    121  When generating a value for the 'options' setting, the above media
    122  selection values may be OR'ed (or added to) the following:
    123
    124  ======  =============================================
    125  0x8000  Set driver debugging level to 7
    126  0x4000  Set driver debugging level to 2
    127  0x0400  Enable Wake-on-LAN
    128  0x0200  Force full duplex mode.
    129  0x0010  Bus-master enable bit (Old Vortex cards only)
    130  ======  =============================================
    131
    132  For example::
    133
    134    insmod 3c59x options=0x204
    135
    136  will force full-duplex 100base-TX, rather than allowing the usual
    137  autonegotiation.
    138
    139global_options=N
    140
    141  Sets the ``options`` parameter for all 3c59x NICs in the machine.
    142  Entries in the ``options`` array above will override any setting of
    143  this.
    144
    145full_duplex=N1,N2,N3...
    146
    147  Similar to bit 9 of 'options'.  Forces the corresponding card into
    148  full-duplex mode.  Please use this in preference to the ``options``
    149  parameter.
    150
    151  In fact, please don't use this at all! You're better off getting
    152  autonegotiation working properly.
    153
    154global_full_duplex=N1
    155
    156  Sets full duplex mode for all 3c59x NICs in the machine.  Entries
    157  in the ``full_duplex`` array above will override any setting of this.
    158
    159flow_ctrl=N1,N2,N3...
    160
    161  Use 802.3x MAC-layer flow control.  The 3com cards only support the
    162  PAUSE command, which means that they will stop sending packets for a
    163  short period if they receive a PAUSE frame from the link partner.
    164
    165  The driver only allows flow control on a link which is operating in
    166  full duplex mode.
    167
    168  This feature does not appear to work on the 3c905 - only 3c905B and
    169  3c905C have been tested.
    170
    171  The 3com cards appear to only respond to PAUSE frames which are
    172  sent to the reserved destination address of 01:80:c2:00:00:01.  They
    173  do not honour PAUSE frames which are sent to the station MAC address.
    174
    175rx_copybreak=M
    176
    177  The driver preallocates 32 full-sized (1536 byte) network buffers
    178  for receiving.  When a packet arrives, the driver has to decide
    179  whether to leave the packet in its full-sized buffer, or to allocate
    180  a smaller buffer and copy the packet across into it.
    181
    182  This is a speed/space tradeoff.
    183
    184  The value of rx_copybreak is used to decide when to make the copy.
    185  If the packet size is less than rx_copybreak, the packet is copied.
    186  The default value for rx_copybreak is 200 bytes.
    187
    188max_interrupt_work=N
    189
    190  The driver's interrupt service routine can handle many receive and
    191  transmit packets in a single invocation.  It does this in a loop.
    192  The value of max_interrupt_work governs how many times the interrupt
    193  service routine will loop.  The default value is 32 loops.  If this
    194  is exceeded the interrupt service routine gives up and generates a
    195  warning message "eth0: Too much work in interrupt".
    196
    197hw_checksums=N1,N2,N3,...
    198
    199  Recent 3com NICs are able to generate IPv4, TCP and UDP checksums
    200  in hardware.  Linux has used the Rx checksumming for a long time.
    201  The "zero copy" patch which is planned for the 2.4 kernel series
    202  allows you to make use of the NIC's DMA scatter/gather and transmit
    203  checksumming as well.
    204
    205  The driver is set up so that, when the zerocopy patch is applied,
    206  all Tornado and Cyclone devices will use S/G and Tx checksums.
    207
    208  This module parameter has been provided so you can override this
    209  decision.  If you think that Tx checksums are causing a problem, you
    210  may disable the feature with ``hw_checksums=0``.
    211
    212  If you think your NIC should be performing Tx checksumming and the
    213  driver isn't enabling it, you can force the use of hardware Tx
    214  checksumming with ``hw_checksums=1``.
    215
    216  The driver drops a message in the logfiles to indicate whether or
    217  not it is using hardware scatter/gather and hardware Tx checksums.
    218
    219  Scatter/gather and hardware checksums provide considerable
    220  performance improvement for the sendfile() system call, but a small
    221  decrease in throughput for send().  There is no effect upon receive
    222  efficiency.
    223
    224compaq_ioaddr=N,
    225compaq_irq=N,
    226compaq_device_id=N
    227
    228  "Variables to work-around the Compaq PCI BIOS32 problem"....
    229
    230watchdog=N
    231
    232  Sets the time duration (in milliseconds) after which the kernel
    233  decides that the transmitter has become stuck and needs to be reset.
    234  This is mainly for debugging purposes, although it may be advantageous
    235  to increase this value on LANs which have very high collision rates.
    236  The default value is 5000 (5.0 seconds).
    237
    238enable_wol=N1,N2,N3,...
    239
    240  Enable Wake-on-LAN support for the relevant interface.  Donald
    241  Becker's ``ether-wake`` application may be used to wake suspended
    242  machines.
    243
    244  Also enables the NIC's power management support.
    245
    246global_enable_wol=N
    247
    248  Sets enable_wol mode for all 3c59x NICs in the machine.  Entries in
    249  the ``enable_wol`` array above will override any setting of this.
    250
    251Media selection
    252---------------
    253
    254A number of the older NICs such as the 3c590 and 3c900 series have
    25510base2 and AUI interfaces.
    256
    257Prior to January, 2001 this driver would autoeselect the 10base2 or AUI
    258port if it didn't detect activity on the 10baseT port.  It would then
    259get stuck on the 10base2 port and a driver reload was necessary to
    260switch back to 10baseT.  This behaviour could not be prevented with a
    261module option override.
    262
    263Later (current) versions of the driver _do_ support locking of the
    264media type.  So if you load the driver module with
    265
    266	modprobe 3c59x options=0
    267
    268it will permanently select the 10baseT port.  Automatic selection of
    269other media types does not occur.
    270
    271
    272Transmit error, Tx status register 82
    273-------------------------------------
    274
    275This is a common error which is almost always caused by another host on
    276the same network being in full-duplex mode, while this host is in
    277half-duplex mode.  You need to find that other host and make it run in
    278half-duplex mode or fix this host to run in full-duplex mode.
    279
    280As a last resort, you can force the 3c59x driver into full-duplex mode
    281with
    282
    283	options 3c59x full_duplex=1
    284
    285but this has to be viewed as a workaround for broken network gear and
    286should only really be used for equipment which cannot autonegotiate.
    287
    288
    289Additional resources
    290--------------------
    291
    292Details of the device driver implementation are at the top of the source file.
    293
    294Additional documentation is available at Don Becker's Linux Drivers site:
    295
    296     http://www.scyld.com/vortex.html
    297
    298Donald Becker's driver development site:
    299
    300     http://www.scyld.com/network.html
    301
    302Donald's vortex-diag program is useful for inspecting the NIC's state:
    303
    304     http://www.scyld.com/ethercard_diag.html
    305
    306Donald's mii-diag program may be used for inspecting and manipulating
    307the NIC's Media Independent Interface subsystem:
    308
    309     http://www.scyld.com/ethercard_diag.html#mii-diag
    310
    311Donald's wake-on-LAN page:
    312
    313     http://www.scyld.com/wakeonlan.html
    314
    3153Com's DOS-based application for setting up the NICs EEPROMs:
    316
    317	ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe
    318
    319
    320Autonegotiation notes
    321---------------------
    322
    323  The driver uses a one-minute heartbeat for adapting to changes in
    324  the external LAN environment if link is up and 5 seconds if link is down.
    325  This means that when, for example, a machine is unplugged from a hubbed
    326  10baseT LAN plugged into a  switched 100baseT LAN, the throughput
    327  will be quite dreadful for up to sixty seconds.  Be patient.
    328
    329  Cisco interoperability note from Walter Wong <wcw+@CMU.EDU>:
    330
    331  On a side note, adding HAS_NWAY seems to share a problem with the
    332  Cisco 6509 switch.  Specifically, you need to change the spanning
    333  tree parameter for the port the machine is plugged into to 'portfast'
    334  mode.  Otherwise, the negotiation fails.  This has been an issue
    335  we've noticed for a while but haven't had the time to track down.
    336
    337  Cisco switches    (Jeff Busch <jbusch@deja.com>)
    338
    339    My "standard config" for ports to which PC's/servers connect directly::
    340
    341	interface FastEthernet0/N
    342	description machinename
    343	load-interval 30
    344	spanning-tree portfast
    345
    346    If autonegotiation is a problem, you may need to specify "speed
    347    100" and "duplex full" as well (or "speed 10" and "duplex half").
    348
    349    WARNING: DO NOT hook up hubs/switches/bridges to these
    350    specially-configured ports! The switch will become very confused.
    351
    352
    353Reporting and diagnosing problems
    354---------------------------------
    355
    356Maintainers find that accurate and complete problem reports are
    357invaluable in resolving driver problems.  We are frequently not able to
    358reproduce problems and must rely on your patience and efforts to get to
    359the bottom of the problem.
    360
    361If you believe you have a driver problem here are some of the
    362steps you should take:
    363
    364- Is it really a driver problem?
    365
    366   Eliminate some variables: try different cards, different
    367   computers, different cables, different ports on the switch/hub,
    368   different versions of the kernel or of the driver, etc.
    369
    370- OK, it's a driver problem.
    371
    372   You need to generate a report.  Typically this is an email to the
    373   maintainer and/or netdev@vger.kernel.org.  The maintainer's
    374   email address will be in the driver source or in the MAINTAINERS file.
    375
    376- The contents of your report will vary a lot depending upon the
    377  problem.  If it's a kernel crash then you should refer to
    378  'Documentation/admin-guide/reporting-issues.rst'.
    379
    380  But for most problems it is useful to provide the following:
    381
    382   - Kernel version, driver version
    383
    384   - A copy of the banner message which the driver generates when
    385     it is initialised.  For example:
    386
    387     eth0: 3Com PCI 3c905C Tornado at 0xa400,  00:50:da:6a:88:f0, IRQ 19
    388     8K byte-wide RAM 5:3 Rx:Tx split, autoselect/Autonegotiate interface.
    389     MII transceiver found at address 24, status 782d.
    390     Enabling bus-master transmits and whole-frame receives.
    391
    392     NOTE: You must provide the ``debug=2`` modprobe option to generate
    393     a full detection message.  Please do this::
    394
    395	modprobe 3c59x debug=2
    396
    397   - If it is a PCI device, the relevant output from 'lspci -vx', eg::
    398
    399       00:09.0 Ethernet controller: 3Com Corporation 3c905C-TX [Fast Etherlink] (rev 74)
    400	       Subsystem: 3Com Corporation: Unknown device 9200
    401	       Flags: bus master, medium devsel, latency 32, IRQ 19
    402	       I/O ports at a400 [size=128]
    403	       Memory at db000000 (32-bit, non-prefetchable) [size=128]
    404	       Expansion ROM at <unassigned> [disabled] [size=128K]
    405	       Capabilities: [dc] Power Management version 2
    406       00: b7 10 00 92 07 00 10 02 74 00 00 02 08 20 00 00
    407       10: 01 a4 00 00 00 00 00 db 00 00 00 00 00 00 00 00
    408       20: 00 00 00 00 00 00 00 00 00 00 00 00 b7 10 00 10
    409       30: 00 00 00 00 dc 00 00 00 00 00 00 00 05 01 0a 0a
    410
    411   - A description of the environment: 10baseT? 100baseT?
    412     full/half duplex? switched or hubbed?
    413
    414   - Any additional module parameters which you may be providing to the driver.
    415
    416   - Any kernel logs which are produced.  The more the merrier.
    417     If this is a large file and you are sending your report to a
    418     mailing list, mention that you have the logfile, but don't send
    419     it.  If you're reporting direct to the maintainer then just send
    420     it.
    421
    422     To ensure that all kernel logs are available, add the
    423     following line to /etc/syslog.conf::
    424
    425	 kern.* /var/log/messages
    426
    427     Then restart syslogd with::
    428
    429	 /etc/rc.d/init.d/syslog restart
    430
    431     (The above may vary, depending upon which Linux distribution you use).
    432
    433    - If your problem is reproducible then that's great.  Try the
    434      following:
    435
    436      1) Increase the debug level.  Usually this is done via:
    437
    438	 a) modprobe driver debug=7
    439	 b) In /etc/modprobe.d/driver.conf:
    440	    options driver debug=7
    441
    442      2) Recreate the problem with the higher debug level,
    443	 send all logs to the maintainer.
    444
    445      3) Download you card's diagnostic tool from Donald
    446	 Becker's website <http://www.scyld.com/ethercard_diag.html>.
    447	 Download mii-diag.c as well.  Build these.
    448
    449	 a) Run 'vortex-diag -aaee' and 'mii-diag -v' when the card is
    450	    working correctly.  Save the output.
    451
    452	 b) Run the above commands when the card is malfunctioning.  Send
    453	    both sets of output.
    454
    455Finally, please be patient and be prepared to do some work.  You may
    456end up working on this problem for a week or more as the maintainer
    457asks more questions, asks for more tests, asks for patches to be
    458applied, etc.  At the end of it all, the problem may even remain
    459unresolved.