code:
.. SPDX-License-Identifier: GPL-2.0

======================================
Texas Instruments CPSW ethernet driver
======================================

Multiqueue & CBS & MQPRIO
=========================

The cpsw has 3 CBS shapers for each external ports. This document
describes MQPRIO and CBS Qdisc offload configuration for cpsw driver
based on examples. It potentially can be used in audio video bridging
(AVB) and time sensitive networking (TSN).

The following examples were tested on AM572x EVM and BBB boards.

Test setup
==========

Under consideration two examples with AM572x EVM running cpsw driver
in dual_emac mode.

Several prerequisites:

- TX queues must be rated starting from txq0 that has highest priority
- Traffic classes are used starting from 0, that has highest priority
- CBS shapers should be used with rated queues
- The bandwidth for CBS shapers has to be set a little bit more then
  potential incoming rate, thus, rate of all incoming tx queues has
  to be a little less
- Real rates can differ, due to discreetness
- Map skb-priority to txq is not enough, also skb-priority to l2 prio
  map has to be created with ip or vconfig tool
- Any l2/socket prio (0 - 7) for classes can be used, but for
  simplicity default values are used: 3 and 2
- only 2 classes tested: A and B, but checked and can work with more,
  maximum allowed 4, but only for 3 rate can be set.

Test setup for examples
=======================

::

					+-------------------------------+
					|--+                            |
					|  |      Workstation0          |
					|E |  MAC 18:03:73:66:87:42     |
    +-----------------------------+  +--|t |                            |
    |                    | 1  | E |  |  |h |./tsn_listener -d \         |
    |  Target board:     | 0  | t |--+  |0 | 18:03:73:66:87:42 -i eth0 \|
    |  AM572x EVM        | 0  | h |     |  | -s 1500                    |
    |                    | 0  | 0 |     |--+                            |
    |  Only 2 classes:   |Mb  +---|     +-------------------------------+
    |  class A, class B  |        |
    |                    |    +---|     +-------------------------------+
    |                    | 1  | E |     |--+                            |
    |                    | 0  | t |     |  |      Workstation1          |
    |                    | 0  | h |--+  |E |  MAC 20:cf:30:85:7d:fd     |
    |                    |Mb  | 1 |  +--|t |                            |
    +-----------------------------+     |h |./tsn_listener -d \         |
					|0 | 20:cf:30:85:7d:fd -i eth0 \|
					|  | -s 1500                    |
					|--+                            |
					+-------------------------------+

Example 1: One port tx AVB configuration scheme for target board
----------------------------------------------------------------

(prints and scheme for AM572x evm, applicable for single port boards)

- tc - traffic class
- txq - transmit queue
- p - priority
- f - fifo (cpsw fifo)
- S - shaper configured

::

    +------------------------------------------------------------------+ u
    | +---------------+  +---------------+  +------+ +------+          | s
    | |               |  |               |  |      | |      |          | e
    | | App 1         |  | App 2         |  | Apps | | Apps |          | r
    | | Class A       |  | Class B       |  | Rest | | Rest |          |
    | | Eth0          |  | Eth0          |  | Eth0 | | Eth1 |          | s
    | | VLAN100       |  | VLAN100       |  |   |  | |   |  |          | p
    | | 40 Mb/s       |  | 20 Mb/s       |  |   |  | |   |  |          | a
    | | SO_PRIORITY=3 |  | SO_PRIORITY=2 |  |   |  | |   |  |          | c
    | |   |           |  |   |           |  |   |  | |   |  |          | e
    | +---|-----------+  +---|-----------+  +---|--+ +---|--+          |
    +-----|------------------|------------------|--------|-------------+
	+-+     +------------+                  |        |
	|       |             +-----------------+     +--+
	|       |             |                       |
    +---|-------|-------------|-----------------------|----------------+
    | +----+ +----+ +----+ +----+                   +----+             |
    | | p3 | | p2 | | p1 | | p0 |                   | p0 |             | k
    | \    / \    / \    / \    /                   \    /             | e
    |  \  /   \  /   \  /   \  /                     \  /              | r
    |   \/     \/     \/     \/                       \/               | n
    |    |     |             |                        |                | e
    |    |     |       +-----+                        |                | l
    |    |     |       |                              |                |
    | +----+ +----+ +----+                          +----+             | s
    | |tc0 | |tc1 | |tc2 |                          |tc0 |             | p
    | \    / \    / \    /                          \    /             | a
    |  \  /   \  /   \  /                            \  /              | c
    |   \/     \/     \/                              \/               | e
    |   |      |       +-----+                        |                |
    |   |      |       |     |                        |                |
    |   |      |       |     |                        |                |
    |   |      |       |     |                        |                |
    | +----+ +----+ +----+ +----+                   +----+             |
    | |txq0| |txq1| |txq2| |txq3|                   |txq4|             |
    | \    / \    / \    / \    /                   \    /             |
    |  \  /   \  /   \  /   \  /                     \  /              |
    |   \/     \/     \/     \/                       \/               |
    | +-|------|------|------|--+                  +--|--------------+ |
    | | |      |      |      |  | Eth0.100         |  |     Eth1     | |
    +---|------|------|------|------------------------|----------------+
	|      |      |      |                        |
	p      p      p      p                        |
	3      2      0-1, 4-7  <- L2 priority        |
	|      |      |      |                        |
	|      |      |      |                        |
    +---|------|------|------|------------------------|----------------+
    |   |      |      |      |             |----------+                |
    | +----+ +----+ +----+ +----+       +----+                         |
    | |dma7| |dma6| |dma5| |dma4|       |dma3|                         |
    | \    / \    / \    / \    /       \    /                         | c
    |  \S /   \S /   \  /   \  /         \  /                          | p
    |   \/     \/     \/     \/           \/                           | s
    |   |      |      | +-----            |                            | w
    |   |      |      | |                 |                            |
    |   |      |      | |                 |                            | d
    | +----+ +----+ +----+p            p+----+                         | r
    | |    | |    | |    |o            o|    |                         | i
    | | f3 | | f2 | | f0 |r            r| f0 |                         | v
    | |tc0 | |tc1 | |tc2 |t            t|tc0 |                         | e
    | \CBS / \CBS / \CBS /1            2\CBS /                         | r
    |  \S /   \S /   \  /                \  /                          |
    |   \/     \/     \/                  \/                           |
    +------------------------------------------------------------------+

1) ::

	// Add 4 tx queues, for interface Eth0, and 1 tx queue for Eth1
	$ ethtool -L eth0 rx 1 tx 5
	rx unmodified, ignoring

2) ::

	// Check if num of queues is set correctly:
	$ ethtool -l eth0
	Channel parameters for eth0:
	Pre-set maximums:
	RX:             8
	TX:             8
	Other:          0
	Combined:       0
	Current hardware settings:
	RX:             1
	TX:             5
	Other:          0
	Combined:       0

3) ::

	// TX queues must be rated starting from 0, so set bws for tx0 and tx1
	// Set rates 40 and 20 Mb/s appropriately.
	// Pay attention, real speed can differ a bit due to discreetness.
	// Leave last 2 tx queues not rated.
	$ echo 40 > /sys/class/net/eth0/queues/tx-0/tx_maxrate
	$ echo 20 > /sys/class/net/eth0/queues/tx-1/tx_maxrate

4) ::

	// Check maximum rate of tx (cpdma) queues:
	$ cat /sys/class/net/eth0/queues/tx-*/tx_maxrate
	40
	20
	0
	0
	0

5) ::

	// Map skb->priority to traffic class:
	// 3pri -> tc0, 2pri -> tc1, (0,1,4-7)pri -> tc2
	// Map traffic class to transmit queue:
	// tc0 -> txq0, tc1 -> txq1, tc2 -> (txq2, txq3)
	$ tc qdisc replace dev eth0 handle 100: parent root mqprio num_tc 3 \
	map 2 2 1 0 2 2 2 2 2 2 2 2 2 2 2 2 queues 1@0 1@1 2@2 hw 1

5a) ::

	// As two interface sharing same set of tx queues, assign all traffic
	// coming to interface Eth1 to separate queue in order to not mix it
	// with traffic from interface Eth0, so use separate txq to send
	// packets to Eth1, so all prio -> tc0 and tc0 -> txq4
	// Here hw 0, so here still default configuration for eth1 in hw
	$ tc qdisc replace dev eth1 handle 100: parent root mqprio num_tc 1 \
	map 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 queues 1@4 hw 0

6) ::

	// Check classes settings
	$ tc -g class show dev eth0
	+---(100:ffe2) mqprio
	|    +---(100:3) mqprio
	|    +---(100:4) mqprio
	|
	+---(100:ffe1) mqprio
	|    +---(100:2) mqprio
	|
	+---(100:ffe0) mqprio
	    +---(100:1) mqprio

	$ tc -g class show dev eth1
	+---(100:ffe0) mqprio
	    +---(100:5) mqprio

7) ::

	// Set rate for class A - 41 Mbit (tc0, txq0) using CBS Qdisc
	// Set it +1 Mb for reserve (important!)
	// here only idle slope is important, others arg are ignored
	// Pay attention, real speed can differ a bit due to discreetness
	$ tc qdisc add dev eth0 parent 100:1 cbs locredit -1438 \
	hicredit 62 sendslope -959000 idleslope 41000 offload 1
	net eth0: set FIFO3 bw = 50

8) ::

	// Set rate for class B - 21 Mbit (tc1, txq1) using CBS Qdisc:
	// Set it +1 Mb for reserve (important!)
	$ tc qdisc add dev eth0 parent 100:2 cbs locredit -1468 \
	hicredit 65 sendslope -979000 idleslope 21000 offload 1
	net eth0: set FIFO2 bw = 30

9) ::

	// Create vlan 100 to map sk->priority to vlan qos
	$ ip link add link eth0 name eth0.100 type vlan id 100
	8021q: 802.1Q VLAN Support v1.8
	8021q: adding VLAN 0 to HW filter on device eth0
	8021q: adding VLAN 0 to HW filter on device eth1
	net eth0: Adding vlanid 100 to vlan filter

10) ::

	// Map skb->priority to L2 prio, 1 to 1
	$ ip link set eth0.100 type vlan \
	egress 0:0 1:1 2:2 3:3 4:4 5:5 6:6 7:7

11) ::

	// Check egress map for vlan 100
	$ cat /proc/net/vlan/eth0.100
	[...]
	INGRESS priority mappings: 0:0  1:0  2:0  3:0  4:0  5:0  6:0 7:0
	EGRESS priority mappings: 0:0 1:1 2:2 3:3 4:4 5:5 6:6 7:7

12) ::

	// Run your appropriate tools with socket option "SO_PRIORITY"
	// to 3 for class A and/or to 2 for class B
	// (I took at https://www.spinics.net/lists/netdev/msg460869.html)
	./tsn_talker -d 18:03:73:66:87:42 -i eth0.100 -p3 -s 1500&
	./tsn_talker -d 18:03:73:66:87:42 -i eth0.100 -p2 -s 1500&

13) ::

	// run your listener on workstation (should be in same vlan)
	// (I took at https://www.spinics.net/lists/netdev/msg460869.html)
	./tsn_listener -d 18:03:73:66:87:42 -i enp5s0 -s 1500
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39000 kbps

14) ::

	// Restore default configuration if needed
	$ ip link del eth0.100
	$ tc qdisc del dev eth1 root
	$ tc qdisc del dev eth0 root
	net eth0: Prev FIFO2 is shaped
	net eth0: set FIFO3 bw = 0
	net eth0: set FIFO2 bw = 0
	$ ethtool -L eth0 rx 1 tx 1

Example 2: Two port tx AVB configuration scheme for target board
----------------------------------------------------------------

(prints and scheme for AM572x evm, for dual emac boards only)

::

    +------------------------------------------------------------------+ u
    | +----------+  +----------+  +------+  +----------+  +----------+ | s
    | |          |  |          |  |      |  |          |  |          | | e
    | | App 1    |  | App 2    |  | Apps |  | App 3    |  | App 4    | | r
    | | Class A  |  | Class B  |  | Rest |  | Class B  |  | Class A  | |
    | | Eth0     |  | Eth0     |  |   |  |  | Eth1     |  | Eth1     | | s
    | | VLAN100  |  | VLAN100  |  |   |  |  | VLAN100  |  | VLAN100  | | p
    | | 40 Mb/s  |  | 20 Mb/s  |  |   |  |  | 10 Mb/s  |  | 30 Mb/s  | | a
    | | SO_PRI=3 |  | SO_PRI=2 |  |   |  |  | SO_PRI=3 |  | SO_PRI=2 | | c
    | |   |      |  |   |      |  |   |  |  |   |      |  |   |      | | e
    | +---|------+  +---|------+  +---|--+  +---|------+  +---|------+ |
    +-----|-------------|-------------|---------|-------------|--------+
	+-+     +-------+             |         +----------+  +----+
	|       |             +-------+------+             |       |
	|       |             |              |             |       |
    +---|-------|-------------|--------------|-------------|-------|---+
    | +----+ +----+ +----+ +----+          +----+ +----+ +----+ +----+ |
    | | p3 | | p2 | | p1 | | p0 |          | p0 | | p1 | | p2 | | p3 | | k
    | \    / \    / \    / \    /          \    / \    / \    / \    / | e
    |  \  /   \  /   \  /   \  /            \  /   \  /   \  /   \  /  | r
    |   \/     \/     \/     \/              \/     \/     \/     \/   | n
    |   |      |             |                |             |      |   | e
    |   |      |        +----+                +----+        |      |   | l
    |   |      |        |                          |        |      |   |
    | +----+ +----+ +----+                        +----+ +----+ +----+ | s
    | |tc0 | |tc1 | |tc2 |                        |tc2 | |tc1 | |tc0 | | p
    | \    / \    / \    /                        \    / \    / \    / | a
    |  \  /   \  /   \  /                          \  /   \  /   \  /  | c
    |   \/     \/     \/                            \/     \/     \/   | e
    |   |      |       +-----+                +-----+      |       |   |
    |   |      |       |     |                |     |      |       |   |
    |   |      |       |     |                |     |      |       |   |
    |   |      |       |     |    E      E    |     |      |       |   |
    | +----+ +----+ +----+ +----+ t      t +----+ +----+ +----+ +----+ |
    | |txq0| |txq1| |txq4| |txq5| h      h |txq6| |txq7| |txq3| |txq2| |
    | \    / \    / \    / \    / 0      1 \    / \    / \    / \    / |
    |  \  /   \  /   \  /   \  /  .      .  \  /   \  /   \  /   \  /  |
    |   \/     \/     \/     \/   1      1   \/     \/     \/     \/   |
    | +-|------|------|------|--+ 0      0 +-|------|------|------|--+ |
    | | |      |      |      |  | 0      0 | |      |      |      |  | |
    +---|------|------|------|---------------|------|------|------|----+
	|      |      |      |               |      |      |      |
	p      p      p      p               p      p      p      p
	3      2      0-1, 4-7   <-L2 pri->  0-1, 4-7      2      3
	|      |      |      |               |      |      |      |
	|      |      |      |               |      |      |      |
    +---|------|------|------|---------------|------|------|------|----+
    |   |      |      |      |               |      |      |      |    |
    | +----+ +----+ +----+ +----+          +----+ +----+ +----+ +----+ |
    | |dma7| |dma6| |dma3| |dma2|          |dma1| |dma0| |dma4| |dma5| |
    | \    / \    / \    / \    /          \    / \    / \    / \    / | c
    |  \S /   \S /   \  /   \  /            \  /   \  /   \S /   \S /  | p
    |   \/     \/     \/     \/              \/     \/     \/     \/   | s
    |   |      |      | +-----                |      |      |      |   | w
    |   |      |      | |                     +----+ |      |      |   |
    |   |      |      | |                          | |      |      |   | d
    | +----+ +----+ +----+p                      p+----+ +----+ +----+ | r
    | |    | |    | |    |o                      o|    | |    | |    | | i
    | | f3 | | f2 | | f0 |r        CPSW          r| f3 | | f2 | | f0 | | v
    | |tc0 | |tc1 | |tc2 |t                      t|tc0 | |tc1 | |tc2 | | e
    | \CBS / \CBS / \CBS /1                      2\CBS / \CBS / \CBS / | r
    |  \S /   \S /   \  /                          \S /   \S /   \  /  |
    |   \/     \/     \/                            \/     \/     \/   |
    +------------------------------------------------------------------+
    ========================================Eth==========================>

1) ::

	// Add 8 tx queues, for interface Eth0, but they are common, so are accessed
	// by two interfaces Eth0 and Eth1.
	$ ethtool -L eth1 rx 1 tx 8
	rx unmodified, ignoring

2) ::

	// Check if num of queues is set correctly:
	$ ethtool -l eth0
	Channel parameters for eth0:
	Pre-set maximums:
	RX:             8
	TX:             8
	Other:          0
	Combined:       0
	Current hardware settings:
	RX:             1
	TX:             8
	Other:          0
	Combined:       0

3) ::

	// TX queues must be rated starting from 0, so set bws for tx0 and tx1 for Eth0
	// and for tx2 and tx3 for Eth1. That is, rates 40 and 20 Mb/s appropriately
	// for Eth0 and 30 and 10 Mb/s for Eth1.
	// Real speed can differ a bit due to discreetness
	// Leave last 4 tx queues as not rated
	$ echo 40 > /sys/class/net/eth0/queues/tx-0/tx_maxrate
	$ echo 20 > /sys/class/net/eth0/queues/tx-1/tx_maxrate
	$ echo 30 > /sys/class/net/eth1/queues/tx-2/tx_maxrate
	$ echo 10 > /sys/class/net/eth1/queues/tx-3/tx_maxrate

4) ::

	// Check maximum rate of tx (cpdma) queues:
	$ cat /sys/class/net/eth0/queues/tx-*/tx_maxrate
	40
	20
	30
	10
	0
	0
	0
	0

5) ::

	// Map skb->priority to traffic class for Eth0:
	// 3pri -> tc0, 2pri -> tc1, (0,1,4-7)pri -> tc2
	// Map traffic class to transmit queue:
	// tc0 -> txq0, tc1 -> txq1, tc2 -> (txq4, txq5)
	$ tc qdisc replace dev eth0 handle 100: parent root mqprio num_tc 3 \
	map 2 2 1 0 2 2 2 2 2 2 2 2 2 2 2 2 queues 1@0 1@1 2@4 hw 1

6) ::

	// Check classes settings
	$ tc -g class show dev eth0
	+---(100:ffe2) mqprio
	|    +---(100:5) mqprio
	|    +---(100:6) mqprio
	|
	+---(100:ffe1) mqprio
	|    +---(100:2) mqprio
	|
	+---(100:ffe0) mqprio
	    +---(100:1) mqprio

7) ::

	// Set rate for class A - 41 Mbit (tc0, txq0) using CBS Qdisc for Eth0
	// here only idle slope is important, others ignored
	// Real speed can differ a bit due to discreetness
	$ tc qdisc add dev eth0 parent 100:1 cbs locredit -1470 \
	hicredit 62 sendslope -959000 idleslope 41000 offload 1
	net eth0: set FIFO3 bw = 50

8) ::

	// Set rate for class B - 21 Mbit (tc1, txq1) using CBS Qdisc for Eth0
	$ tc qdisc add dev eth0 parent 100:2 cbs locredit -1470 \
	hicredit 65 sendslope -979000 idleslope 21000 offload 1
	net eth0: set FIFO2 bw = 30

9) ::

	// Create vlan 100 to map sk->priority to vlan qos for Eth0
	$ ip link add link eth0 name eth0.100 type vlan id 100
	net eth0: Adding vlanid 100 to vlan filter

10) ::

	// Map skb->priority to L2 prio for Eth0.100, one to one
	$ ip link set eth0.100 type vlan \
	egress 0:0 1:1 2:2 3:3 4:4 5:5 6:6 7:7

11) ::

	// Check egress map for vlan 100
	$ cat /proc/net/vlan/eth0.100
	[...]
	INGRESS priority mappings: 0:0  1:0  2:0  3:0  4:0  5:0  6:0 7:0
	EGRESS priority mappings: 0:0 1:1 2:2 3:3 4:4 5:5 6:6 7:7

12) ::

	// Map skb->priority to traffic class for Eth1:
	// 3pri -> tc0, 2pri -> tc1, (0,1,4-7)pri -> tc2
	// Map traffic class to transmit queue:
	// tc0 -> txq2, tc1 -> txq3, tc2 -> (txq6, txq7)
	$ tc qdisc replace dev eth1 handle 100: parent root mqprio num_tc 3 \
	map 2 2 1 0 2 2 2 2 2 2 2 2 2 2 2 2 queues 1@2 1@3 2@6 hw 1

13) ::

	// Check classes settings
	$ tc -g class show dev eth1
	+---(100:ffe2) mqprio
	|    +---(100:7) mqprio
	|    +---(100:8) mqprio
	|
	+---(100:ffe1) mqprio
	|    +---(100:4) mqprio
	|
	+---(100:ffe0) mqprio
	    +---(100:3) mqprio

14) ::

	// Set rate for class A - 31 Mbit (tc0, txq2) using CBS Qdisc for Eth1
	// here only idle slope is important, others ignored, but calculated
	// for interface speed - 100Mb for eth1 port.
	// Set it +1 Mb for reserve (important!)
	$ tc qdisc add dev eth1 parent 100:3 cbs locredit -1035 \
	hicredit 465 sendslope -69000 idleslope 31000 offload 1
	net eth1: set FIFO3 bw = 31

15) ::

	// Set rate for class B - 11 Mbit (tc1, txq3) using CBS Qdisc for Eth1
	// Set it +1 Mb for reserve (important!)
	$ tc qdisc add dev eth1 parent 100:4 cbs locredit -1335 \
	hicredit 405 sendslope -89000 idleslope 11000 offload 1
	net eth1: set FIFO2 bw = 11

16) ::

	// Create vlan 100 to map sk->priority to vlan qos for Eth1
	$ ip link add link eth1 name eth1.100 type vlan id 100
	net eth1: Adding vlanid 100 to vlan filter

17) ::

	// Map skb->priority to L2 prio for Eth1.100, one to one
	$ ip link set eth1.100 type vlan \
	egress 0:0 1:1 2:2 3:3 4:4 5:5 6:6 7:7

18) ::

	// Check egress map for vlan 100
	$ cat /proc/net/vlan/eth1.100
	[...]
	INGRESS priority mappings: 0:0  1:0  2:0  3:0  4:0  5:0  6:0 7:0
	EGRESS priority mappings: 0:0 1:1 2:2 3:3 4:4 5:5 6:6 7:7

19) ::

	// Run appropriate tools with socket option "SO_PRIORITY" to 3
	// for class A and to 2 for class B. For both interfaces
	./tsn_talker -d 18:03:73:66:87:42 -i eth0.100 -p2 -s 1500&
	./tsn_talker -d 18:03:73:66:87:42 -i eth0.100 -p3 -s 1500&
	./tsn_talker -d 20:cf:30:85:7d:fd -i eth1.100 -p2 -s 1500&
	./tsn_talker -d 20:cf:30:85:7d:fd -i eth1.100 -p3 -s 1500&

20) ::

	// run your listener on workstation (should be in same vlan)
	// (I took at https://www.spinics.net/lists/netdev/msg460869.html)
	./tsn_listener -d 18:03:73:66:87:42 -i enp5s0 -s 1500
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39012 kbps
	Receiving data rate: 39000 kbps

21) ::

	// Restore default configuration if needed
	$ ip link del eth1.100
	$ ip link del eth0.100
	$ tc qdisc del dev eth1 root
	net eth1: Prev FIFO2 is shaped
	net eth1: set FIFO3 bw = 0
	net eth1: set FIFO2 bw = 0
	$ tc qdisc del dev eth0 root
	net eth0: Prev FIFO2 is shaped
	net eth0: set FIFO3 bw = 0
	net eth0: set FIFO2 bw = 0
	$ ethtool -L eth0 rx 1 tx 1


code:
.. SPDX-License-Identifier: GPL-2.0

======================================================
Texas Instruments CPSW switchdev based ethernet driver
======================================================

:Version: 2.0

Port renaming
=============

On older udev versions renaming of ethX to swXpY will not be automatically
supported

In order to rename via udev::

    ip -d link show dev sw0p1 | grep switchid

    SUBSYSTEM=="net", ACTION=="add", ATTR{phys_switch_id}==<switchid>, \
	    ATTR{phys_port_name}!="", NAME="sw0$attr{phys_port_name}"

Dual mac mode
=============

- The new (cpsw_new.c) driver is operating in dual-emac mode by default, thus
  working as 2 individual network interfaces. Main differences from legacy CPSW
  driver are:

 - optimized promiscuous mode: The P0_UNI_FLOOD (both ports) is enabled in
   addition to ALLMULTI (current port) instead of ALE_BYPASS.
   So, Ports in promiscuous mode will keep possibility of mcast and vlan
   filtering, which is provides significant benefits when ports are joined
   to the same bridge, but without enabling "switch" mode, or to different
   bridges.
 - learning disabled on ports as it make not too much sense for
   segregated ports - no forwarding in HW.
 - enabled basic support for devlink.

   ::

	devlink dev show
		platform/48484000.switch

	devlink dev param show
	platform/48484000.switch:
	name switch_mode type driver-specific
	values:
		cmode runtime value false
	name ale_bypass type driver-specific
	values:
		cmode runtime value false

Devlink configuration parameters
================================

See Documentation/networking/devlink/ti-cpsw-switch.rst

Bridging in dual mac mode
=========================

The dual_mac mode requires two vids to be reserved for internal purposes,
which, by default, equal CPSW Port numbers. As result, bridge has to be
configured in vlan unaware mode or default_pvid has to be adjusted::

	ip link add name br0 type bridge
	ip link set dev br0 type bridge vlan_filtering 0
	echo 0 > /sys/class/net/br0/bridge/default_pvid
	ip link set dev sw0p1 master br0
	ip link set dev sw0p2 master br0

or::

	ip link add name br0 type bridge
	ip link set dev br0 type bridge vlan_filtering 0
	echo 100 > /sys/class/net/br0/bridge/default_pvid
	ip link set dev br0 type bridge vlan_filtering 1
	ip link set dev sw0p1 master br0
	ip link set dev sw0p2 master br0

Enabling "switch"
=================

The Switch mode can be enabled by configuring devlink driver parameter
"switch_mode" to 1/true::

	devlink dev param set platform/48484000.switch \
	name switch_mode value 1 cmode runtime

This can be done regardless of the state of Port's netdev devices - UP/DOWN, but
Port's netdev devices have to be in UP before joining to the bridge to avoid
overwriting of bridge configuration as CPSW switch driver copletly reloads its
configuration when first Port changes its state to UP.

When the both interfaces joined the bridge - CPSW switch driver will enable
marking packets with offload_fwd_mark flag unless "ale_bypass=0"

All configuration is implemented via switchdev API.

Bridge setup
============

::

	devlink dev param set platform/48484000.switch \
	name switch_mode value 1 cmode runtime

	ip link add name br0 type bridge
	ip link set dev br0 type bridge ageing_time 1000
	ip link set dev sw0p1 up
	ip link set dev sw0p2 up
	ip link set dev sw0p1 master br0
	ip link set dev sw0p2 master br0

	[*] bridge vlan add dev br0 vid 1 pvid untagged self

	[*] if vlan_filtering=1. where default_pvid=1

	Note. Steps [*] are mandatory.

On/off STP
==========

::

	ip link set dev BRDEV type bridge stp_state 1/0

VLAN configuration
==================

::

  bridge vlan add dev br0 vid 1 pvid untagged self <---- add cpu port to VLAN 1

Note. This step is mandatory for bridge/default_pvid.

Add extra VLANs
===============

 1. untagged::

	bridge vlan add dev sw0p1 vid 100 pvid untagged master
	bridge vlan add dev sw0p2 vid 100 pvid untagged master
	bridge vlan add dev br0 vid 100 pvid untagged self <---- Add cpu port to VLAN100

 2. tagged::

	bridge vlan add dev sw0p1 vid 100 master
	bridge vlan add dev sw0p2 vid 100 master
	bridge vlan add dev br0 vid 100 pvid tagged self <---- Add cpu port to VLAN100

FDBs
----

FDBs are automatically added on the appropriate switch port upon detection

Manually adding FDBs::

    bridge fdb add aa:bb:cc:dd:ee:ff dev sw0p1 master vlan 100
    bridge fdb add aa:bb:cc:dd:ee:fe dev sw0p2 master <---- Add on all VLANs

MDBs
----

MDBs are automatically added on the appropriate switch port upon detection

Manually adding MDBs::

  bridge mdb add dev br0 port sw0p1 grp 239.1.1.1 permanent vid 100
  bridge mdb add dev br0 port sw0p1 grp 239.1.1.1 permanent <---- Add on all VLANs

Multicast flooding
==================
CPU port mcast_flooding is always on

Turning flooding on/off on swithch ports:
bridge link set dev sw0p1 mcast_flood on/off

Access and Trunk port
=====================

::

 bridge vlan add dev sw0p1 vid 100 pvid untagged master
 bridge vlan add dev sw0p2 vid 100 master

 bridge vlan add dev br0 vid 100 self
 ip link add link br0 name br0.100 type vlan id 100

Note. Setting PVID on Bridge device itself working only for
default VLAN (default_pvid).

NFS
===

The only way for NFS to work is by chrooting to a minimal environment when
switch configuration that will affect connectivity is needed.
Assuming you are booting NFS with eth1 interface(the script is hacky and
it's just there to prove NFS is doable).

setup.sh::

	#!/bin/sh
	mkdir proc
	mount -t proc none /proc
	ifconfig br0  > /dev/null
	if [ $? -ne 0 ]; then
		echo "Setting up bridge"
		ip link add name br0 type bridge
		ip link set dev br0 type bridge ageing_time 1000
		ip link set dev br0 type bridge vlan_filtering 1

		ip link set eth1 down
		ip link set eth1 name sw0p1
		ip link set dev sw0p1 up
		ip link set dev sw0p2 up
		ip link set dev sw0p2 master br0
		ip link set dev sw0p1 master br0
		bridge vlan add dev br0 vid 1 pvid untagged self
		ifconfig sw0p1 0.0.0.0
		udhchc -i br0
	fi
	umount /proc

run_nfs.sh:::

	#!/bin/sh
	mkdir /tmp/root/bin -p
	mkdir /tmp/root/lib -p

	cp -r /lib/ /tmp/root/
	cp -r /bin/ /tmp/root/
	cp /sbin/ip /tmp/root/bin
	cp /sbin/bridge /tmp/root/bin
	cp /sbin/ifconfig /tmp/root/bin
	cp /sbin/udhcpc /tmp/root/bin
	cp /path/to/setup.sh /tmp/root/bin
	chroot /tmp/root/ busybox sh /bin/setup.sh

	run ./run_nfs.sh

repo_name: angery/linux


code:
.. SPDX-License-Identifier: GPL-2.0

=====================
TLAN driver for Linux
=====================

:Version: 1.14a

(C) 1997-1998 Caldera, Inc.

(C) 1998 James Banks

(C) 1999-2001 Torben Mathiasen <tmm@image.dk, torben.mathiasen@compaq.com>

For driver information/updates visit http://www.compaq.com

I. Supported Devices
====================

    Only PCI devices will work with this driver.

    Supported:

    =========	=========	===========================================
    Vendor ID	Device ID	Name
    =========	=========	===========================================
    0e11	ae32		Compaq Netelligent 10/100 TX PCI UTP
    0e11	ae34		Compaq Netelligent 10 T PCI UTP
    0e11	ae35		Compaq Integrated NetFlex 3/P
    0e11	ae40		Compaq Netelligent Dual 10/100 TX PCI UTP
    0e11	ae43		Compaq Netelligent Integrated 10/100 TX UTP
    0e11	b011		Compaq Netelligent 10/100 TX Embedded UTP
    0e11	b012		Compaq Netelligent 10 T/2 PCI UTP/Coax
    0e11	b030		Compaq Netelligent 10/100 TX UTP
    0e11	f130		Compaq NetFlex 3/P
    0e11	f150		Compaq NetFlex 3/P
    108d	0012		Olicom OC-2325
    108d	0013		Olicom OC-2183
    108d	0014		Olicom OC-2326
    =========	=========	===========================================

    Caveats:

    I am not sure if 100BaseTX daughterboards (for those cards which
    support such things) will work.  I haven't had any solid evidence
    either way.

    However, if a card supports 100BaseTx without requiring an add
    on daughterboard, it should work with 100BaseTx.

    The "Netelligent 10 T/2 PCI UTP/Coax" (b012) device is untested,
    but I do not expect any problems.

II. Driver Options
==================

	1. You can append debug=x to the end of the insmod line to get
	   debug messages, where x is a bit field where the bits mean
	   the following:

	   ====		=====================================
	   0x01		Turn on general debugging messages.
	   0x02		Turn on receive debugging messages.
	   0x04		Turn on transmit debugging messages.
	   0x08		Turn on list debugging messages.
	   ====		=====================================

	2. You can append aui=1 to the end of the insmod line to cause
	   the adapter to use the AUI interface instead of the 10 Base T
	   interface.  This is also what to do if you want to use the BNC
	   connector on a TLAN based device.  (Setting this option on a
	   device that does not have an AUI/BNC connector will probably
	   cause it to not function correctly.)

	3. You can set duplex=1 to force half duplex, and duplex=2 to
	   force full duplex.

	4. You can set speed=10 to force 10Mbs operation, and speed=100
	   to force 100Mbs operation. (I'm not sure what will happen
	   if a card which only supports 10Mbs is forced into 100Mbs
	   mode.)

	5. You have to use speed=X duplex=Y together now. If you just
	   do "insmod tlan.o speed=100" the driver will do Auto-Neg.
	   To force a 10Mbps Half-Duplex link do "insmod tlan.o speed=10
	   duplex=1".

	6. If the driver is built into the kernel, you can use the 3rd
	   and 4th parameters to set aui and debug respectively.  For
	   example::

		ether=0,0,0x1,0x7,eth0

	   This sets aui to 0x1 and debug to 0x7, assuming eth0 is a
	   supported TLAN device.

	   The bits in the third byte are assigned as follows:

		====   ===============
		0x01   aui
		0x02   use half duplex
		0x04   use full duplex
		0x08   use 10BaseT
		0x10   use 100BaseTx
		====   ===============

	   You also need to set both speed and duplex settings when forcing
	   speeds with kernel-parameters.
	   ether=0,0,0x12,0,eth0 will force link to 100Mbps Half-Duplex.

	7. If you have more than one tlan adapter in your system, you can
	   use the above options on a per adapter basis. To force a 100Mbit/HD
	   link with your eth1 adapter use::

		insmod tlan speed=0,100 duplex=0,1

	   Now eth0 will use auto-neg and eth1 will be forced to 100Mbit/HD.
	   Note that the tlan driver supports a maximum of 8 adapters.

III. Things to try if you have problems
=======================================

	1. Make sure your card's PCI id is among those listed in
	   section I, above.
	2. Make sure routing is correct.
	3. Try forcing different speed/duplex settings

There is also a tlan mailing list which you can join by sending "subscribe tlan"
in the body of an email to majordomo@vuser.vu.union.edu.

There is also a tlan website at http://www.compaq.com


code:
.. SPDX-License-Identifier: GPL-2.0

===========================
The Spidernet Device Driver
===========================

Written by Linas Vepstas <linas@austin.ibm.com>

Version of 7 June 2007

Abstract
========
This document sketches the structure of portions of the spidernet
device driver in the Linux kernel tree. The spidernet is a gigabit
ethernet device built into the Toshiba southbridge commonly used
in the SONY Playstation 3 and the IBM QS20 Cell blade.

The Structure of the RX Ring.
=============================
The receive (RX) ring is a circular linked list of RX descriptors,
together with three pointers into the ring that are used to manage its
contents.

The elements of the ring are called "descriptors" or "descrs"; they
describe the received data. This includes a pointer to a buffer
containing the received data, the buffer size, and various status bits.

There are three primary states that a descriptor can be in: "empty",
"full" and "not-in-use".  An "empty" or "ready" descriptor is ready
to receive data from the hardware. A "full" descriptor has data in it,
and is waiting to be emptied and processed by the OS. A "not-in-use"
descriptor is neither empty or full; it is simply not ready. It may
not even have a data buffer in it, or is otherwise unusable.

During normal operation, on device startup, the OS (specifically, the
spidernet device driver) allocates a set of RX descriptors and RX
buffers. These are all marked "empty", ready to receive data. This
ring is handed off to the hardware, which sequentially fills in the
buffers, and marks them "full". The OS follows up, taking the full
buffers, processing them, and re-marking them empty.

This filling and emptying is managed by three pointers, the "head"
and "tail" pointers, managed by the OS, and a hardware current
descriptor pointer (GDACTDPA). The GDACTDPA points at the descr
currently being filled. When this descr is filled, the hardware
marks it full, and advances the GDACTDPA by one.  Thus, when there is
flowing RX traffic, every descr behind it should be marked "full",
and everything in front of it should be "empty".  If the hardware
discovers that the current descr is not empty, it will signal an
interrupt, and halt processing.

The tail pointer tails or trails the hardware pointer. When the
hardware is ahead, the tail pointer will be pointing at a "full"
descr. The OS will process this descr, and then mark it "not-in-use",
and advance the tail pointer.  Thus, when there is flowing RX traffic,
all of the descrs in front of the tail pointer should be "full", and
all of those behind it should be "not-in-use". When RX traffic is not
flowing, then the tail pointer can catch up to the hardware pointer.
The OS will then note that the current tail is "empty", and halt
processing.

The head pointer (somewhat mis-named) follows after the tail pointer.
When traffic is flowing, then the head pointer will be pointing at
a "not-in-use" descr. The OS will perform various housekeeping duties
on this descr. This includes allocating a new data buffer and
dma-mapping it so as to make it visible to the hardware. The OS will
then mark the descr as "empty", ready to receive data. Thus, when there
is flowing RX traffic, everything in front of the head pointer should
be "not-in-use", and everything behind it should be "empty". If no
RX traffic is flowing, then the head pointer can catch up to the tail
pointer, at which point the OS will notice that the head descr is
"empty", and it will halt processing.

Thus, in an idle system, the GDACTDPA, tail and head pointers will
all be pointing at the same descr, which should be "empty". All of the
other descrs in the ring should be "empty" as well.

The show_rx_chain() routine will print out the locations of the
GDACTDPA, tail and head pointers. It will also summarize the contents
of the ring, starting at the tail pointer, and listing the status
of the descrs that follow.

A typical example of the output, for a nearly idle system, might be::

    net eth1: Total number of descrs=256
    net eth1: Chain tail located at descr=20
    net eth1: Chain head is at 20
    net eth1: HW curr desc (GDACTDPA) is at 21
    net eth1: Have 1 descrs with stat=x40800101
    net eth1: HW next desc (GDACNEXTDA) is at 22
    net eth1: Last 255 descrs with stat=xa0800000

In the above, the hardware has filled in one descr, number 20. Both
head and tail are pointing at 20, because it has not yet been emptied.
Meanwhile, hw is pointing at 21, which is free.

The "Have nnn decrs" refers to the descr starting at the tail: in this
case, nnn=1 descr, starting at descr 20. The "Last nnn descrs" refers
to all of the rest of the descrs, from the last status change. The "nnn"
is a count of how many descrs have exactly the same status.

The status x4... corresponds to "full" and status xa... corresponds
to "empty". The actual value printed is RXCOMST_A.

In the device driver source code, a different set of names are
used for these same concepts, so that::

    "empty" == SPIDER_NET_DESCR_CARDOWNED == 0xa
    "full"  == SPIDER_NET_DESCR_FRAME_END == 0x4
    "not in use" == SPIDER_NET_DESCR_NOT_IN_USE == 0xf

The RX RAM full bug/feature
===========================

As long as the OS can empty out the RX buffers at a rate faster than
the hardware can fill them, there is no problem. If, for some reason,
the OS fails to empty the RX ring fast enough, the hardware GDACTDPA
pointer will catch up to the head, notice the not-empty condition,
ad stop. However, RX packets may still continue arriving on the wire.
The spidernet chip can save some limited number of these in local RAM.
When this local ram fills up, the spider chip will issue an interrupt
indicating this (GHIINT0STS will show ERRINT, and the GRMFLLINT bit
will be set in GHIINT1STS).  When the RX ram full condition occurs,
a certain bug/feature is triggered that has to be specially handled.
This section describes the special handling for this condition.

When the OS finally has a chance to run, it will empty out the RX ring.
In particular, it will clear the descriptor on which the hardware had
stopped. However, once the hardware has decided that a certain
descriptor is invalid, it will not restart at that descriptor; instead
it will restart at the next descr. This potentially will lead to a
deadlock condition, as the tail pointer will be pointing at this descr,
which, from the OS point of view, is empty; the OS will be waiting for
this descr to be filled. However, the hardware has skipped this descr,
and is filling the next descrs. Since the OS doesn't see this, there
is a potential deadlock, with the OS waiting for one descr to fill,
while the hardware is waiting for a different set of descrs to become
empty.

A call to show_rx_chain() at this point indicates the nature of the
problem. A typical print when the network is hung shows the following::

    net eth1: Spider RX RAM full, incoming packets might be discarded!
    net eth1: Total number of descrs=256
    net eth1: Chain tail located at descr=255
    net eth1: Chain head is at 255
    net eth1: HW curr desc (GDACTDPA) is at 0
    net eth1: Have 1 descrs with stat=xa0800000
    net eth1: HW next desc (GDACNEXTDA) is at 1
    net eth1: Have 127 descrs with stat=x40800101
    net eth1: Have 1 descrs with stat=x40800001
    net eth1: Have 126 descrs with stat=x40800101
    net eth1: Last 1 descrs with stat=xa0800000

Both the tail and head pointers are pointing at descr 255, which is
marked xa... which is "empty". Thus, from the OS point of view, there
is nothing to be done. In particular, there is the implicit assumption
that everything in front of the "empty" descr must surely also be empty,
as explained in the last section. The OS is waiting for descr 255 to
become non-empty, which, in this case, will never happen.

The HW pointer is at descr 0. This descr is marked 0x4.. or "full".
Since its already full, the hardware can do nothing more, and thus has
halted processing. Notice that descrs 0 through 254 are all marked
"full", while descr 254 and 255 are empty. (The "Last 1 descrs" is
descr 254, since tail was at 255.) Thus, the system is deadlocked,
and there can be no forward progress; the OS thinks there's nothing
to do, and the hardware has nowhere to put incoming data.

This bug/feature is worked around with the spider_net_resync_head_ptr()
routine. When the driver receives RX interrupts, but an examination
of the RX chain seems to show it is empty, then it is probable that
the hardware has skipped a descr or two (sometimes dozens under heavy
network conditions). The spider_net_resync_head_ptr() subroutine will
search the ring for the next full descr, and the driver will resume
operations there.  Since this will leave "holes" in the ring, there
is also a spider_net_resync_tail_ptr() that will skip over such holes.

As of this writing, the spider_net_resync() strategy seems to work very
well, even under heavy network loads.

The TX ring
===========
The TX ring uses a low-watermark interrupt scheme to make sure that
the TX queue is appropriately serviced for large packet sizes.

For packet sizes greater than about 1KBytes, the kernel can fill
the TX ring quicker than the device can drain it. Once the ring
is full, the netdev is stopped. When there is room in the ring,
the netdev needs to be reawakened, so that more TX packets are placed
in the ring. The hardware can empty the ring about four times per jiffy,
so its not appropriate to wait for the poll routine to refill, since
the poll routine runs only once per jiffy.  The low-watermark mechanism
marks a descr about 1/4th of the way from the bottom of the queue, so
that an interrupt is generated when the descr is processed. This
interrupt wakes up the netdev, which can then refill the queue.
For large packets, this mechanism generates a relatively small number
of interrupts, about 1K/sec. For smaller packets, this will drop to zero
interrupts, as the hardware can empty the queue faster than the kernel
can fill it.


code:
.. SPDX-License-Identifier: GPL-2.0

=============================================================
Linux Base Driver for WangXun(R) Gigabit PCI Express Adapters
=============================================================

WangXun Gigabit Linux driver.
Copyright (c) 2019 - 2022 Beijing WangXun Technology Co., Ltd.

Support
=======
 If you have problems with the software or hardware, please contact our
 customer support team via email at nic-support@net-swift.com or check our website
 at https://www.net-swift.com


code:
.. SPDX-License-Identifier: GPL-2.0

================================================================
Linux Base Driver for WangXun(R) 10 Gigabit PCI Express Adapters
================================================================

WangXun 10 Gigabit Linux driver.
Copyright (c) 2015 - 2022 Beijing WangXun Technology Co., Ltd.

Contents
========

- Support

Support
=======
If you got any problem, contact Wangxun support team via support@trustnetic.com
and Cc: netdev.


code:
.. SPDX-License-Identifier: GPL-2.0

=====================================================
Notes on the DEC FDDIcontroller 700 (DEFZA-xx) driver
=====================================================

:Version: v.1.1.4

DEC FDDIcontroller 700 is DEC's first-generation TURBOchannel FDDI
network card, designed in 1990 specifically for the DECstation 5000
model 200 workstation.  The board is a single attachment station and
it was manufactured in two variations, both of which are supported.

First is the SAS MMF DEFZA-AA option, the original design implementing
the standard MMF-PMD, however with a pair of ST connectors rather than
the usual MIC connector.  The other one is the SAS ThinWire/STP DEFZA-CA
option, denoted 700-C, with the network medium selectable by a switch
between the DEC proprietary ThinWire-PMD using a BNC connector and the
standard STP-PMD using a DE-9F connector.  This option can interface to
a DECconcentrator 500 device and, in the case of the STP-PMD, also other
FDDI equipment and was designed to make it easier to transition from
existing IEEE 802.3 10BASE2 Ethernet and IEEE 802.5 Token Ring networks
by providing means to reuse existing cabling.

This driver handles any number of cards installed in a single system.
They get fddi0, fddi1, etc. interface names assigned in the order of
increasing TURBOchannel slot numbers.

The board only supports DMA on the receive side.  Transmission involves
the use of PIO.  As a result under a heavy transmission load there will
be a significant impact on system performance.

The board supports a 64-entry CAM for matching destination addresses.
Two entries are preoccupied by the Directed Beacon and Ring Purger
multicast addresses and the rest is used as a multicast filter.  An
all-multi mode is also supported for LLC frames and it is used if
requested explicitly or if the CAM overflows.  The promiscuous mode
supports separate enables for LLC and SMT frames, but this driver
doesn't support changing them individually.

Known problems:

None.

To do:

5. MAC address change.  The card does not support changing the Media
   Access Controller's address registers but a similar effect can be
   achieved by adding an alias to the CAM.  There is no way to disable
   matching against the original address though.

7. Queueing incoming/outgoing SMT frames in the driver if the SMT
   receive/RMC transmit ring is full. (?)

8. Retrieving/reporting FDDI/SNMP stats.

Both success and failure reports are welcome.

Maciej W. Rozycki  <macro@orcam.me.uk>


code:
.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

Fiber Distributed Data Interface (FDDI) Device Drivers
======================================================

Contents:

.. toctree::
   :maxdepth: 2

   defza
   skfp

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`


code:
.. SPDX-License-Identifier: GPL-2.0

.. include:: <isonum.txt>

========================
SysKonnect driver - SKFP
========================

|copy| Copyright 1998-2000 SysKonnect,

skfp.txt created 11-May-2000

Readme File for skfp.o v2.06

.. This file contains

   (1) OVERVIEW
   (2) SUPPORTED ADAPTERS
   (3) GENERAL INFORMATION
   (4) INSTALLATION
   (5) INCLUSION OF THE ADAPTER IN SYSTEM START
   (6) TROUBLESHOOTING
   (7) FUNCTION OF THE ADAPTER LEDS
   (8) HISTORY

1. Overview
===========

This README explains how to use the driver 'skfp' for Linux with your
network adapter.

Chapter 2: Contains a list of all network adapters that are supported by
this driver.

Chapter 3:
	   Gives some general information.

Chapter 4: Describes common problems and solutions.

Chapter 5: Shows the changed functionality of the adapter LEDs.

Chapter 6: History of development.

2. Supported adapters
=====================

The network driver 'skfp' supports the following network adapters:
SysKonnect adapters:

  - SK-5521 (SK-NET FDDI-UP)
  - SK-5522 (SK-NET FDDI-UP DAS)
  - SK-5541 (SK-NET FDDI-FP)
  - SK-5543 (SK-NET FDDI-LP)
  - SK-5544 (SK-NET FDDI-LP DAS)
  - SK-5821 (SK-NET FDDI-UP64)
  - SK-5822 (SK-NET FDDI-UP64 DAS)
  - SK-5841 (SK-NET FDDI-FP64)
  - SK-5843 (SK-NET FDDI-LP64)
  - SK-5844 (SK-NET FDDI-LP64 DAS)

Compaq adapters (not tested):

  - Netelligent 100 FDDI DAS Fibre SC
  - Netelligent 100 FDDI SAS Fibre SC
  - Netelligent 100 FDDI DAS UTP
  - Netelligent 100 FDDI SAS UTP
  - Netelligent 100 FDDI SAS Fibre MIC

3. General Information
======================

From v2.01 on, the driver is integrated in the linux kernel sources.
Therefore, the installation is the same as for any other adapter
supported by the kernel.

Refer to the manual of your distribution about the installation
of network adapters.

Makes my life much easier :-)

4. Troubleshooting
==================

If you run into problems during installation, check those items:

Problem:
	  The FDDI adapter cannot be found by the driver.

Reason:
	  Look in /proc/pci for the following entry:

	     'FDDI network controller: SysKonnect SK-FDDI-PCI ...'

	  If this entry exists, then the FDDI adapter has been
	  found by the system and should be able to be used.

	  If this entry does not exist or if the file '/proc/pci'
	  is not there, then you may have a hardware problem or PCI
	  support may not be enabled in your kernel.

	  The adapter can be checked using the diagnostic program
	  which is available from the SysKonnect web site:

	      www.syskonnect.de

	  Some COMPAQ machines have a problem with PCI under
	  Linux. This is described in the 'PCI howto' document
	  (included in some distributions or available from the
	  www, e.g. at 'www.linux.org') and no workaround is available.

Problem:
	  You want to use your computer as a router between
	  multiple IP subnetworks (using multiple adapters), but
	  you cannot reach computers in other subnetworks.

Reason:
	  Either the router's kernel is not configured for IP
	  forwarding or there is a problem with the routing table
	  and gateway configuration in at least one of the
	  computers.

If your problem is not listed here, please contact our
technical support for help.

You can send email to: linux@syskonnect.de

When contacting our technical support,
please ensure that the following information is available:

- System Manufacturer and Model
- Boards in your system
- Distribution
- Kernel version

5. Function of the Adapter LEDs
===============================

	The functionality of the LED's on the FDDI network adapters was
	changed in SMT version v2.82. With this new SMT version, the yellow
	LED works as a ring operational indicator. An active yellow LED
	indicates that the ring is down. The green LED on the adapter now
	works as a link indicator where an active GREEN LED indicates that
	the respective port has a physical connection.

	With versions of SMT prior to v2.82 a ring up was indicated if the
	yellow LED was off while the green LED(s) showed the connection
	status of the adapter. During a ring down the green LED was off and
	the yellow LED was on.

	All implementations indicate that a driver is not loaded if
	all LEDs are off.

6. History
==========

v2.06 (20000511) (In-Kernel version)
    New features:

	- 64 bit support
	- new pci dma interface
	- in kernel 2.3.99

v2.05 (20000217) (In-Kernel version)
    New features:

	- Changes for 2.3.45 kernel

v2.04 (20000207) (Standalone version)
    New features:

	- Added rx/tx byte counter

v2.03 (20000111) (Standalone version)
    Problems fixed:

	- Fixed printk statements from v2.02

v2.02 (991215) (Standalone version)
    Problems fixed:

	- Removed unnecessary output
	- Fixed path for "printver.sh" in makefile

v2.01 (991122) (In-Kernel version)
    New features:

	- Integration in Linux kernel sources
	- Support for memory mapped I/O.

v2.00 (991112)
    New features:

	- Full source released under GPL

v1.05 (991023)
    Problems fixed:

	- Compilation with kernel version 2.2.13 failed

v1.04 (990427)
    Changes:

	- New SMT module included, changing LED functionality

    Problems fixed:

	- Synchronization on SMP machines was buggy

v1.03 (990325)
    Problems fixed:

	- Interrupt routing on SMP machines could be incorrect

v1.02 (990310)
    New features:

	- Support for kernel versions 2.2.x added
	- Kernel patch instead of private duplicate of kernel functions

v1.01 (980812)
    Problems fixed:

	Connection hangup with telnet
	Slow telnet connection

v1.00 beta 01 (980507)
    New features:

	None.

    Problems fixed:

	None.

    Known limitations:

	- tar archive instead of standard package format (rpm).
	- FDDI statistic is empty.
	- not tested with 2.1.xx kernels
	- integration in kernel not tested
	- not tested simultaneously with FDDI adapters from other vendors.
	- only X86 processors supported.
	- SBA (Synchronous Bandwidth Allocator) parameters can
	  not be configured.
	- does not work on some COMPAQ machines. See the PCI howto
	  document for details about this problem.
	- data corruption with kernel versions below 2.0.33.


code:
.. SPDX-License-Identifier: GPL-2.0

===============================
Linux Drivers for Baycom Modems
===============================

Thomas M. Sailer, HB9JNX/AE4WA, <sailer@ife.ee.ethz.ch>

The drivers for the baycom modems have been split into
separate drivers as they did not share any code, and the driver
and device names have changed.

This document describes the Linux Kernel Drivers for simple Baycom style
amateur radio modems.

The following drivers are available:
====================================

baycom_ser_fdx:
  This driver supports the SER12 modems either full or half duplex.
  Its baud rate may be changed via the ``baud`` module parameter,
  therefore it supports just about every bit bang modem on a
  serial port. Its devices are called bcsf0 through bcsf3.
  This is the recommended driver for SER12 type modems,
  however if you have a broken UART clone that does not have working
  delta status bits, you may try baycom_ser_hdx.

baycom_ser_hdx:
  This is an alternative driver for SER12 type modems.
  It only supports half duplex, and only 1200 baud. Its devices
  are called bcsh0 through bcsh3. Use this driver only if baycom_ser_fdx
  does not work with your UART.

baycom_par:
  This driver supports the par96 and picpar modems.
  Its devices are called bcp0 through bcp3.

baycom_epp:
  This driver supports the EPP modem.
  Its devices are called bce0 through bce3.
  This driver is work-in-progress.

The following modems are supported:

======= ========================================================================
ser12   This is a very simple 1200 baud AFSK modem. The modem consists only
	of a modulator/demodulator chip, usually a TI TCM3105. The computer
	is responsible for regenerating the receiver bit clock, as well as
	for handling the HDLC protocol. The modem connects to a serial port,
	hence the name. Since the serial port is not used as an async serial
	port, the kernel driver for serial ports cannot be used, and this
	driver only supports standard serial hardware (8250, 16450, 16550)

par96   This is a modem for 9600 baud FSK compatible to the G3RUH standard.
	The modem does all the filtering and regenerates the receiver clock.
	Data is transferred from and to the PC via a shift register.
	The shift register is filled with 16 bits and an interrupt is signalled.
	The PC then empties the shift register in a burst. This modem connects
	to the parallel port, hence the name. The modem leaves the
	implementation of the HDLC protocol and the scrambler polynomial to
	the PC.

picpar  This is a redesign of the par96 modem by Henning Rech, DF9IC. The modem
	is protocol compatible to par96, but uses only three low power ICs
	and can therefore be fed from the parallel port and does not require
	an additional power supply. Furthermore, it incorporates a carrier
	detect circuitry.

EPP     This is a high-speed modem adaptor that connects to an enhanced parallel
	port.

	Its target audience is users working over a high speed hub (76.8kbit/s).

eppfpga This is a redesign of the EPP adaptor.
======= ========================================================================

All of the above modems only support half duplex communications. However,
the driver supports the KISS (see below) fullduplex command. It then simply
starts to send as soon as there's a packet to transmit and does not care
about DCD, i.e. it starts to send even if there's someone else on the channel.
This command is required by some implementations of the DAMA channel
access protocol.

The Interface of the drivers
============================

Unlike previous drivers, these drivers are no longer character devices,
but they are now true kernel network interfaces. Installation is therefore
simple. Once installed, four interfaces named bc{sf,sh,p,e}[0-3] are available.
sethdlc from the ax25 utilities may be used to set driver states etc.
Users of userland AX.25 stacks may use the net2kiss utility (also available
in the ax25 utilities package) to convert packets of a network interface
to a KISS stream on a pseudo tty. There's also a patch available from
me for WAMPES which allows attaching a kernel network interface directly.

Configuring the driver
======================

Every time a driver is inserted into the kernel, it has to know which
modems it should access at which ports. This can be done with the setbaycom
utility. If you are only using one modem, you can also configure the
driver from the insmod command line (or by means of an option line in
``/etc/modprobe.d/*.conf``).

Examples::

  modprobe baycom_ser_fdx mode="ser12*" iobase=0x3f8 irq=4
  sethdlc -i bcsf0 -p mode "ser12*" io 0x3f8 irq 4

Both lines configure the first port to drive a ser12 modem at the first
serial port (COM1 under DOS). The * in the mode parameter instructs the driver
to use the software DCD algorithm (see below)::

  insmod baycom_par mode="picpar" iobase=0x378
  sethdlc -i bcp0 -p mode "picpar" io 0x378

Both lines configure the first port to drive a picpar modem at the
first parallel port (LPT1 under DOS). (Note: picpar implies
hardware DCD, par96 implies software DCD).

The channel access parameters can be set with sethdlc -a or kissparms.
Note that both utilities interpret the values slightly differently.

Hardware DCD versus Software DCD
================================

To avoid collisions on the air, the driver must know when the channel is
busy. This is the task of the DCD circuitry/software. The driver may either
utilise a software DCD algorithm (options=1) or use a DCD signal from
the hardware (options=0).

======= =================================================================
ser12   if software DCD is utilised, the radio's squelch should always be
	open. It is highly recommended to use the software DCD algorithm,
	as it is much faster than most hardware squelch circuitry. The
	disadvantage is a slightly higher load on the system.

par96   the software DCD algorithm for this type of modem is rather poor.
	The modem simply does not provide enough information to implement
	a reasonable DCD algorithm in software. Therefore, if your radio
	feeds the DCD input of the PAR96 modem, the use of the hardware
	DCD circuitry is recommended.

picpar  the picpar modem features a builtin DCD hardware, which is highly
	recommended.
======= =================================================================

Compatibility with the rest of the Linux kernel
===============================================

The serial driver and the baycom serial drivers compete
for the same hardware resources. Of course only one driver can access a given
interface at a time. The serial driver grabs all interfaces it can find at
startup time. Therefore the baycom drivers subsequently won't be able to
access a serial port. You might therefore find it necessary to release
a port owned by the serial driver with 'setserial /dev/ttyS# uart none', where
# is the number of the interface. The baycom drivers do not reserve any
ports at startup, unless one is specified on the 'insmod' command line. Another
method to solve the problem is to compile all drivers as modules and
leave it to kmod to load the correct driver depending on the application.

The parallel port drivers (baycom_par, baycom_epp) now use the parport subsystem
to arbitrate the ports between different client drivers.

vy 73s de

Tom Sailer, sailer@ife.ee.ethz.ch

hb9jnx @ hb9w.ampr.org


code:
.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

Amateur Radio Device Drivers
============================

Contents:

.. toctree::
   :maxdepth: 2

   baycom
   z8530drv

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`


code:
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

=========================================================
SCC.C - Linux driver for Z8530 based HDLC cards for AX.25
=========================================================

This is a subset of the documentation. To use this driver you MUST have the
full package from:

Internet:

    1. ftp://ftp.ccac.rwth-aachen.de/pub/jr/z8530drv-utils_3.0-3.tar.gz

    2. ftp://ftp.pspt.fi/pub/ham/linux/ax25/z8530drv-utils_3.0-3.tar.gz

Please note that the information in this document may be hopelessly outdated.
A new version of the documentation, along with links to other important
Linux Kernel AX.25 documentation and programs, is available on
http://yaina.de/jreuter

Copyright |copy| 1993,2000 by Joerg Reuter DL1BKE <jreuter@yaina.de>

portions Copyright |copy| 1993 Guido ten Dolle PE1NNZ

for the complete copyright notice see >> Copying.Z8530DRV <<

1. Initialization of the driver
===============================

To use the driver, 3 steps must be performed:

     1. if compiled as module: loading the module
     2. Setup of hardware, MODEM and KISS parameters with sccinit
     3. Attach each channel to the Linux kernel AX.25 with "ifconfig"

Unlike the versions below 2.4 this driver is a real network device
driver. If you want to run xNOS instead of our fine kernel AX.25
use a 2.x version (available from above sites) or read the
AX.25-HOWTO on how to emulate a KISS TNC on network device drivers.

1.1 Loading the module
======================

(If you're going to compile the driver as a part of the kernel image,
 skip this chapter and continue with 1.2)

Before you can use a module, you'll have to load it with::

	insmod scc.o

please read 'man insmod' that comes with module-init-tools.

You should include the insmod in one of the /etc/rc.d/rc.* files,
and don't forget to insert a call of sccinit after that. It
will read your /etc/z8530drv.conf.

1.2. /etc/z8530drv.conf
=======================

To setup all parameters you must run /sbin/sccinit from one
of your rc.*-files. This has to be done BEFORE you can
"ifconfig" an interface. Sccinit reads the file /etc/z8530drv.conf
and sets the hardware, MODEM and KISS parameters. A sample file is
delivered with this package. Change it to your needs.

The file itself consists of two main sections.

1.2.1 configuration of hardware parameters
==========================================

The hardware setup section defines the following parameters for each
Z8530::

    chip    1
    data_a  0x300                   # data port A
    ctrl_a  0x304                   # control port A
    data_b  0x301                   # data port B
    ctrl_b  0x305                   # control port B
    irq     5                       # IRQ No. 5
    pclock  4915200                 # clock
    board   BAYCOM                  # hardware type
    escc    no                      # enhanced SCC chip? (8580/85180/85280)
    vector  0                       # latch for interrupt vector
    special no                      # address of special function register
    option  0                       # option to set via sfr

chip
	- this is just a delimiter to make sccinit a bit simpler to
	  program. A parameter has no effect.

data_a
	- the address of the data port A of this Z8530 (needed)
ctrl_a
	- the address of the control port A (needed)
data_b
	- the address of the data port B (needed)
ctrl_b
	- the address of the control port B (needed)

irq
	- the used IRQ for this chip. Different chips can use different
	  IRQs or the same. If they share an interrupt, it needs to be
	  specified within one chip-definition only.

pclock  - the clock at the PCLK pin of the Z8530 (option, 4915200 is
	  default), measured in Hertz

board
	- the "type" of the board:

	   =======================  ========
	   SCC type                 value
	   =======================  ========
	   PA0HZP SCC card          PA0HZP
	   EAGLE card               EAGLE
	   PC100 card               PC100
	   PRIMUS-PC (DG9BL) card   PRIMUS
	   BayCom (U)SCC card       BAYCOM
	   =======================  ========

escc
	- if you want support for ESCC chips (8580, 85180, 85280), set
	  this to "yes" (option, defaults to "no")

vector
	- address of the vector latch (aka "intack port") for PA0HZP
	  cards. There can be only one vector latch for all chips!
	  (option, defaults to 0)

special
	- address of the special function register on several cards.
	  (option, defaults to 0)

option  - The value you write into that register (option, default is 0)

You can specify up to four chips (8 channels). If this is not enough,
just change::

	#define MAXSCC 4

to a higher value.

Example for the BAYCOM USCC:
----------------------------

::

	chip    1
	data_a  0x300                   # data port A
	ctrl_a  0x304                   # control port A
	data_b  0x301                   # data port B
	ctrl_b  0x305                   # control port B
	irq     5                       # IRQ No. 5 (#)
	board   BAYCOM                  # hardware type (*)
	#
	# SCC chip 2
	#
	chip    2
	data_a  0x302
	ctrl_a  0x306
	data_b  0x303
	ctrl_b  0x307
	board   BAYCOM

An example for a PA0HZP card:
-----------------------------

::

	chip 1
	data_a 0x153
	data_b 0x151
	ctrl_a 0x152
	ctrl_b 0x150
	irq 9
	pclock 4915200
	board PA0HZP
	vector 0x168
	escc no
	#
	#
	#
	chip 2
	data_a 0x157
	data_b 0x155
	ctrl_a 0x156
	ctrl_b 0x154
	irq 9
	pclock 4915200
	board PA0HZP
	vector 0x168
	escc no

A DRSI would should probably work with this:
--------------------------------------------
(actually: two DRSI cards...)

::

	chip 1
	data_a 0x303
	data_b 0x301
	ctrl_a 0x302
	ctrl_b 0x300
	irq 7
	pclock 4915200
	board DRSI
	escc no
	#
	#
	#
	chip 2
	data_a 0x313
	data_b 0x311
	ctrl_a 0x312
	ctrl_b 0x310
	irq 7
	pclock 4915200
	board DRSI
	escc no

Note that you cannot use the on-board baudrate generator off DRSI
cards. Use "mode dpll" for clock source (see below).

This is based on information provided by Mike Bilow (and verified
by Paul Helay)

The utility "gencfg"
--------------------

If you only know the parameters for the PE1CHL driver for DOS,
run gencfg. It will generate the correct port addresses (I hope).
Its parameters are exactly the same as the ones you use with
the "attach scc" command in net, except that the string "init" must
not appear. Example::

	gencfg 2 0x150 4 2 0 1 0x168 9 4915200

will print a skeleton z8530drv.conf for the OptoSCC to stdout.

::

	gencfg 2 0x300 2 4 5 -4 0 7 4915200 0x10

does the same for the BAYCOM USCC card. In my opinion it is much easier
to edit scc_config.h...

1.2.2 channel configuration
===========================

The channel definition is divided into three sub sections for each
channel:

An example for scc0::

	# DEVICE

	device scc0	# the device for the following params

	# MODEM / BUFFERS

	speed 1200		# the default baudrate
	clock dpll		# clock source:
				# 	dpll     = normal half duplex operation
				# 	external = MODEM provides own Rx/Tx clock
				#	divider  = use full duplex divider if
				#		   installed (1)
	mode nrzi		# HDLC encoding mode
				#	nrzi = 1k2 MODEM, G3RUH 9k6 MODEM
				#	nrz  = DF9IC 9k6 MODEM
				#
	bufsize	384		# size of buffers. Note that this must include
				# the AX.25 header, not only the data field!
				# (optional, defaults to 384)

	# KISS (Layer 1)

	txdelay 36              # (see chapter 1.4)
	persist 64
	slot    8
	tail    8
	fulldup 0
	wait    12
	min     3
	maxkey  7
	idle    3
	maxdef  120
	group   0
	txoff   off
	softdcd on
	slip    off

The order WITHIN these sections is unimportant. The order OF these
sections IS important. The MODEM parameters are set with the first
recognized KISS parameter...

Please note that you can initialize the board only once after boot
(or insmod). You can change all parameters but "mode" and "clock"
later with the Sccparam program or through KISS. Just to avoid
security holes...

(1) this divider is usually mounted on the SCC-PBC (PA0HZP) or not
    present at all (BayCom). It feeds back the output of the DPLL
    (digital pll) as transmit clock. Using this mode without a divider
    installed will normally result in keying the transceiver until
    maxkey expires --- of course without sending anything (useful).

2. Attachment of a channel by your AX.25 software
=================================================

2.1 Kernel AX.25
================

To set up an AX.25 device you can simply type::

	ifconfig scc0 44.128.1.1 hw ax25 dl0tha-7

This will create a network interface with the IP number 44.128.20.107
and the callsign "dl0tha". If you do not have any IP number (yet) you
can use any of the 44.128.0.0 network. Note that you do not need
axattach. The purpose of axattach (like slattach) is to create a KISS
network device linked to a TTY. Please read the documentation of the
ax25-utils and the AX.25-HOWTO to learn how to set the parameters of
the kernel AX.25.

2.2 NOS, NET and TFKISS
=======================

Since the TTY driver (aka KISS TNC emulation) is gone you need
to emulate the old behaviour. The cost of using these programs is
that you probably need to compile the kernel AX.25, regardless of whether
you actually use it or not. First setup your /etc/ax25/axports,
for example::

	9k6	dl0tha-9  9600  255 4 9600 baud port (scc3)
	axlink	dl0tha-15 38400 255 4 Link to NOS

Now "ifconfig" the scc device::

	ifconfig scc3 44.128.1.1 hw ax25 dl0tha-9

You can now axattach a pseudo-TTY::

	axattach /dev/ptys0 axlink

and start your NOS and attach /dev/ptys0 there. The problem is that
NOS is reachable only via digipeating through the kernel AX.25
(disastrous on a DAMA controlled channel). To solve this problem,
configure "rxecho" to echo the incoming frames from "9k6" to "axlink"
and outgoing frames from "axlink" to "9k6" and start::

	rxecho

Or simply use "kissbridge" coming with z8530drv-utils::

	ifconfig scc3 hw ax25 dl0tha-9
	kissbridge scc3 /dev/ptys0

3. Adjustment and Display of parameters
=======================================

3.1 Displaying SCC Parameters:
==============================

Once a SCC channel has been attached, the parameter settings and
some statistic information can be shown using the param program::

	dl1bke-u:~$ sccstat scc0

	Parameters:

	speed       : 1200 baud
	txdelay     : 36
	persist     : 255
	slottime    : 0
	txtail      : 8
	fulldup     : 1
	waittime    : 12
	mintime     : 3 sec
	maxkeyup    : 7 sec
	idletime    : 3 sec
	maxdefer    : 120 sec
	group       : 0x00
	txoff       : off
	softdcd     : on
	SLIP        : off

	Status:

	HDLC                  Z8530           Interrupts         Buffers
	-----------------------------------------------------------------------
	Sent       :     273  RxOver :     0  RxInts :   125074  Size    :  384
	Received   :    1095  TxUnder:     0  TxInts :     4684  NoSpace :    0
	RxErrors   :    1591                  ExInts :    11776
	TxErrors   :       0                  SpInts :     1503
	Tx State   :    idle

The status info shown is:

==============	==============================================================
Sent		number of frames transmitted
Received	number of frames received
RxErrors	number of receive errors (CRC, ABORT)
TxErrors	number of discarded Tx frames (due to various reasons)
Tx State	status of the Tx interrupt handler: idle/busy/active/tail (2)
RxOver		number of receiver overruns
TxUnder		number of transmitter underruns
RxInts		number of receiver interrupts
TxInts		number of transmitter interrupts
EpInts		number of receiver special condition interrupts
SpInts		number of external/status interrupts
Size		maximum size of an AX.25 frame (*with* AX.25 headers!)
NoSpace		number of times a buffer could not get allocated
==============	==============================================================

An overrun is abnormal. If lots of these occur, the product of
baudrate and number of interfaces is too high for the processing
power of your computer. NoSpace errors are unlikely to be caused by the
driver or the kernel AX.25.

3.2 Setting Parameters
======================

The setting of parameters of the emulated KISS TNC is done in the
same way in the SCC driver. You can change parameters by using
the kissparms program from the ax25-utils package or use the program
"sccparam"::

     sccparam <device> <paramname> <decimal-|hexadecimal value>

You can change the following parameters:

===========   =====
param	      value
===========   =====
speed         1200
txdelay       36
persist       255
slottime      0
txtail        8
fulldup       1
waittime      12
mintime       3
maxkeyup      7
idletime      3
maxdefer      120
group         0x00
txoff         off
softdcd       on
SLIP          off
===========   =====

The parameters have the following meaning:

speed:
     The baudrate on this channel in bits/sec

     Example: sccparam /dev/scc3 speed 9600

txdelay:
     The delay (in units of 10 ms) after keying of the
     transmitter, until the first byte is sent. This is usually
     called "TXDELAY" in a TNC.  When 0 is specified, the driver
     will just wait until the CTS signal is asserted. This
     assumes the presence of a timer or other circuitry in the
     MODEM and/or transmitter, that asserts CTS when the
     transmitter is ready for data.
     A normal value of this parameter is 30-36.

     Example: sccparam /dev/scc0 txd 20

persist:
     This is the probability that the transmitter will be keyed
     when the channel is found to be free.  It is a value from 0
     to 255, and the probability is (value+1)/256.  The value
     should be somewhere near 50-60, and should be lowered when
     the channel is used more heavily.

     Example: sccparam /dev/scc2 persist 20

slottime:
     This is the time between samples of the channel. It is
     expressed in units of 10 ms.  About 200-300 ms (value 20-30)
     seems to be a good value.

     Example: sccparam /dev/scc0 slot 20

tail:
     The time the transmitter will remain keyed after the last
     byte of a packet has been transferred to the SCC. This is
     necessary because the CRC and a flag still have to leave the
     SCC before the transmitter is keyed down. The value depends
     on the baudrate selected.  A few character times should be
     sufficient, e.g. 40ms at 1200 baud. (value 4)
     The value of this parameter is in 10 ms units.

     Example: sccparam /dev/scc2 4

full:
     The full-duplex mode switch. This can be one of the following
     values:

     0:   The interface will operate in CSMA mode (the normal
	  half-duplex packet radio operation)
     1:   Fullduplex mode, i.e. the transmitter will be keyed at
	  any time, without checking the received carrier.  It
	  will be unkeyed when there are no packets to be sent.
     2:   Like 1, but the transmitter will remain keyed, also
	  when there are no packets to be sent.  Flags will be
	  sent in that case, until a timeout (parameter 10)
	  occurs.

     Example: sccparam /dev/scc0 fulldup off

wait:
     The initial waittime before any transmit attempt, after the
     frame has been queue for transmit.  This is the length of
     the first slot in CSMA mode.  In full duplex modes it is
     set to 0 for maximum performance.
     The value of this parameter is in 10 ms units.

     Example: sccparam /dev/scc1 wait 4

maxkey:
     The maximal time the transmitter will be keyed to send
     packets, in seconds.  This can be useful on busy CSMA
     channels, to avoid "getting a bad reputation" when you are
     generating a lot of traffic.  After the specified time has
     elapsed, no new frame will be started. Instead, the trans-
     mitter will be switched off for a specified time (parameter
     min), and then the selected algorithm for keyup will be
     started again.
     The value 0 as well as "off" will disable this feature,
     and allow infinite transmission time.

     Example: sccparam /dev/scc0 maxk 20

min:
     This is the time the transmitter will be switched off when
     the maximum transmission time is exceeded.

     Example: sccparam /dev/scc3 min 10

idle:
     This parameter specifies the maximum idle time in full duplex
     2 mode, in seconds.  When no frames have been sent for this
     time, the transmitter will be keyed down.  A value of 0 is
     has same result as the fullduplex mode 1. This parameter
     can be disabled.

     Example: sccparam /dev/scc2 idle off	# transmit forever

maxdefer
     This is the maximum time (in seconds) to wait for a free channel
     to send. When this timer expires the transmitter will be keyed
     IMMEDIATELY. If you love to get trouble with other users you
     should set this to a very low value ;-)

     Example: sccparam /dev/scc0 maxdefer 240	# 2 minutes

txoff:
     When this parameter has the value 0, the transmission of packets
     is enable. Otherwise it is disabled.

     Example: sccparam /dev/scc2 txoff on

group:
     It is possible to build special radio equipment to use more than
     one frequency on the same band, e.g. using several receivers and
     only one transmitter that can be switched between frequencies.
     Also, you can connect several radios that are active on the same
     band.  In these cases, it is not possible, or not a good idea, to
     transmit on more than one frequency.  The SCC driver provides a
     method to lock transmitters on different interfaces, using the
     "param <interface> group <x>" command.  This will only work when
     you are using CSMA mode (parameter full = 0).

     The number <x> must be 0 if you want no group restrictions, and
     can be computed as follows to create restricted groups:
     <x> is the sum of some OCTAL numbers:

     ===  =======================================================
     200  This transmitter will only be keyed when all other
	  transmitters in the group are off.
     100  This transmitter will only be keyed when the carrier
	  detect of all other interfaces in the group is off.
     0xx  A byte that can be used to define different groups.
	  Interfaces are in the same group, when the logical AND
	  between their xx values is nonzero.
     ===  =======================================================

     Examples:

     When 2 interfaces use group 201, their transmitters will never be
     keyed at the same time.

     When 2 interfaces use group 101, the transmitters will only key
     when both channels are clear at the same time.  When group 301,
     the transmitters will not be keyed at the same time.

     Don't forget to convert the octal numbers into decimal before
     you set the parameter.

     Example: (to be written)

softdcd:
     use a software dcd instead of the real one... Useful for a very
     slow squelch.

     Example: sccparam /dev/scc0 soft on

4. Problems
===========

If you have tx-problems with your BayCom USCC card please check
the manufacturer of the 8530. SGS chips have a slightly
different timing. Try Zilog...  A solution is to write to register 8
instead to the data port, but this won't work with the ESCC chips.
*SIGH!*

A very common problem is that the PTT locks until the maxkeyup timer
expires, although interrupts and clock source are correct. In most
cases compiling the driver with CONFIG_SCC_DELAY (set with
make config) solves the problems. For more hints read the (pseudo) FAQ
and the documentation coming with z8530drv-utils.

I got reports that the driver has problems on some 386-based systems.
(i.e. Amstrad) Those systems have a bogus AT bus timing which will
lead to delayed answers on interrupts. You can recognize these
problems by looking at the output of Sccstat for the suspected
port. If it shows under- and overruns you own such a system.

Delayed processing of received data: This depends on

- the kernel version

- kernel profiling compiled or not

- a high interrupt load

- a high load of the machine --- running X, Xmorph, XV and Povray,
  while compiling the kernel... hmm ... even with 32 MB RAM ...  ;-)
  Or running a named for the whole .ampr.org domain on an 8 MB
  box...

- using information from rxecho or kissbridge.

Kernel panics: please read /linux/README and find out if it
really occurred within the scc driver.

If you cannot solve a problem, send me

- a description of the problem,
- information on your hardware (computer system, scc board, modem)
- your kernel version
- the output of cat /proc/net/z8530

4. Thor RLC100
==============

Mysteriously this board seems not to work with the driver. Anyone
got it up-and-running?

Many thanks to Linus Torvalds and Alan Cox for including the driver
in the Linux standard distribution and their support.

::

	Joerg Reuter	ampr-net: dl1bke@db0pra.ampr.org
			AX-25   : DL1BKE @ DB0ABH.#BAY.DEU.EU
			Internet: jreuter@yaina.de
			WWW     : http://yaina.de/jreuter


code:
.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

Hardware Device Drivers
=======================

Contents:

.. toctree::
   :maxdepth: 2

   appletalk/index
   atm/index
   cable/index
   can/index
   cellular/index
   ethernet/index
   fddi/index
   hamradio/index
   qlogic/index
   wifi/index
   wwan/index

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`


code:
.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

QLogic QLGE Device Drivers
===============================================

Contents:

.. toctree::
   :maxdepth: 2

   qlge

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`


code:
.. SPDX-License-Identifier: GPL-2.0

=======================================
QLogic QLGE 10Gb Ethernet device driver
=======================================

This driver use drgn and devlink for debugging.

Dump kernel data structures in drgn
-----------------------------------

To dump kernel data structures, the following Python script can be used
in drgn:

.. code-block:: python

	def align(x, a):
	    """the alignment a should be a power of 2
	    """
	    mask = a - 1
	    return (x+ mask) & ~mask

	def struct_size(struct_type):
	    struct_str = "struct {}".format(struct_type)
	    return sizeof(Object(prog, struct_str, address=0x0))

	def netdev_priv(netdevice):
	    NETDEV_ALIGN = 32
	    return netdevice.value_() + align(struct_size("net_device"), NETDEV_ALIGN)

	name = 'xxx'
	qlge_device = None
	netdevices = prog['init_net'].dev_base_head.address_of_()
	for netdevice in list_for_each_entry("struct net_device", netdevices, "dev_list"):
	    if netdevice.name.string_().decode('ascii') == name:
	        print(netdevice.name)

	ql_adapter = Object(prog, "struct ql_adapter", address=netdev_priv(qlge_device))

The struct ql_adapter will be printed in drgn as follows,

    >>> ql_adapter
    (struct ql_adapter){
            .ricb = (struct ricb){
                    .base_cq = (u8)0,
                    .flags = (u8)120,
                    .mask = (__le16)26637,
                    .hash_cq_id = (u8 [1024]){ 172, 142, 255, 255 },
                    .ipv6_hash_key = (__le32 [10]){},
                    .ipv4_hash_key = (__le32 [4]){},
            },
            .flags = (unsigned long)0,
            .wol = (u32)0,
            .nic_stats = (struct nic_stats){
                    .tx_pkts = (u64)0,
                    .tx_bytes = (u64)0,
                    .tx_mcast_pkts = (u64)0,
                    .tx_bcast_pkts = (u64)0,
                    .tx_ucast_pkts = (u64)0,
                    .tx_ctl_pkts = (u64)0,
                    .tx_pause_pkts = (u64)0,
                    ...
            },
            .active_vlans = (unsigned long [64]){
                    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 52780853100545, 18446744073709551615,
                    18446619461681283072, 0, 42949673024, 2147483647,
            },
            .rx_ring = (struct rx_ring [17]){
                    {
                            .cqicb = (struct cqicb){
                                    .msix_vect = (u8)0,
                                    .reserved1 = (u8)0,
                                    .reserved2 = (u8)0,
                                    .flags = (u8)0,
                                    .len = (__le16)0,
                                    .rid = (__le16)0,
                                    ...
                            },
                            .cq_base = (void *)0x0,
                            .cq_base_dma = (dma_addr_t)0,
                    }
                    ...
            }
    }

coredump via devlink
--------------------

And the coredump obtained via devlink in json format looks like,

.. code:: shell

	$ devlink health dump show DEVICE reporter coredump -p -j
	{
	    "Core Registers": {
	        "segment": 1,
	        "values": [ 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ]
	    },
	    "Test Logic Regs": {
	        "segment": 2,
	        "values": [ 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ]
	    },
	    "RMII Registers": {
	        "segment": 3,
	        "values": [ 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ]
	    },
	    ...
	    "Sem Registers": {
	        "segment": 50,
	        "values": [ 0,0,0,0 ]
	    }
	}

When the module parameter qlge_force_coredump is set to be true, the MPI
RISC reset before coredumping. So coredumping will much longer since
devlink tool has to wait for 5 secs for the resetting to be
finished.


code:
.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

Wi-Fi Device Drivers
====================

Contents:

.. toctree::
   :maxdepth: 2

   intel/ipw2100
   intel/ipw2200
   ray_cs

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`


code:
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

===========================================
Intel(R) PRO/Wireless 2100 Driver for Linux
===========================================

Support for:

- Intel(R) PRO/Wireless 2100 Network Connection

Copyright |copy| 2003-2006, Intel Corporation

README.ipw2100

:Version: git-1.1.5
:Date:    January 25, 2006

.. Index

    0. IMPORTANT INFORMATION BEFORE USING THIS DRIVER
    1. Introduction
    2. Release git-1.1.5 Current Features
    3. Command Line Parameters
    4. Sysfs Helper Files
    5. Radio Kill Switch
    6. Dynamic Firmware
    7. Power Management
    8. Support
    9. License

0. IMPORTANT INFORMATION BEFORE USING THIS DRIVER
=================================================

Important Notice FOR ALL USERS OR DISTRIBUTORS!!!!

Intel wireless LAN adapters are engineered, manufactured, tested, and
quality checked to ensure that they meet all necessary local and
governmental regulatory agency requirements for the regions that they
are designated and/or marked to ship into. Since wireless LANs are
generally unlicensed devices that share spectrum with radars,
satellites, and other licensed and unlicensed devices, it is sometimes
necessary to dynamically detect, avoid, and limit usage to avoid
interference with these devices. In many instances Intel is required to
provide test data to prove regional and local compliance to regional and
governmental regulations before certification or approval to use the
product is granted. Intel's wireless LAN's EEPROM, firmware, and
software driver are designed to carefully control parameters that affect
radio operation and to ensure electromagnetic compliance (EMC). These
parameters include, without limitation, RF power, spectrum usage,
channel scanning, and human exposure.

For these reasons Intel cannot permit any manipulation by third parties
of the software provided in binary format with the wireless WLAN
adapters (e.g., the EEPROM and firmware). Furthermore, if you use any
patches, utilities, or code with the Intel wireless LAN adapters that
have been manipulated by an unauthorized party (i.e., patches,
utilities, or code (including open source code modifications) which have
not been validated by Intel), (i) you will be solely responsible for
ensuring the regulatory compliance of the products, (ii) Intel will bear
no liability, under any theory of liability for any issues associated
with the modified products, including without limitation, claims under
the warranty and/or issues arising from regulatory non-compliance, and
(iii) Intel will not provide or be required to assist in providing
support to any third parties for such modified products.

Note: Many regulatory agencies consider Wireless LAN adapters to be
modules, and accordingly, condition system-level regulatory approval
upon receipt and review of test data documenting that the antennas and
system configuration do not cause the EMC and radio operation to be
non-compliant.

The drivers available for download from SourceForge are provided as a
part of a development project.  Conformance to local regulatory
requirements is the responsibility of the individual developer.  As
such, if you are interested in deploying or shipping a driver as part of
solution intended to be used for purposes other than development, please
obtain a tested driver from Intel Customer Support at:

https://www.intel.com/support/wireless/sb/CS-006408.htm

1. Introduction
===============

This document provides a brief overview of the features supported by the
IPW2100 driver project.  The main project website, where the latest
development version of the driver can be found, is:

	http://ipw2100.sourceforge.net

There you can find the not only the latest releases, but also information about
potential fixes and patches, as well as links to the development mailing list
for the driver project.

2. Release git-1.1.5 Current Supported Features
===============================================

- Managed (BSS) and Ad-Hoc (IBSS)
- WEP (shared key and open)
- Wireless Tools support
- 802.1x (tested with XSupplicant 1.0.1)

Enabled (but not supported) features:
- Monitor/RFMon mode
- WPA/WPA2

The distinction between officially supported and enabled is a reflection
on the amount of validation and interoperability testing that has been
performed on a given feature.

3. Command Line Parameters
==========================

If the driver is built as a module, the following optional parameters are used
by entering them on the command line with the modprobe command using this
syntax::

	modprobe ipw2100 [<option>=<VAL1><,VAL2>...]

For example, to disable the radio on driver loading, enter:

	modprobe ipw2100 disable=1

The ipw2100 driver supports the following module parameters:

=========	==============	============  ==============================
Name		Value		Example       Meaning
=========	==============	============  ==============================
debug		0x0-0xffffffff	debug=1024    Debug level set to 1024
mode		0,1,2		mode=1        AdHoc
channel		int		channel=3     Only valid in AdHoc or Monitor
associate	boolean		associate=0   Do NOT auto associate
disable		boolean		disable=1     Do not power the HW
=========	==============	============  ==============================

4. Sysfs Helper Files
=====================

There are several ways to control the behavior of the driver.  Many of the
general capabilities are exposed through the Wireless Tools (iwconfig).  There
are a few capabilities that are exposed through entries in the Linux Sysfs.

**Driver Level**

For the driver level files, look in /sys/bus/pci/drivers/ipw2100/

  debug_level
	This controls the same global as the 'debug' module parameter.  For
	information on the various debugging levels available, run the 'dvals'
	script found in the driver source directory.

	.. note::

	      'debug_level' is only enabled if CONFIG_IPW2100_DEBUG is turn on.

**Device Level**

For the device level files look in::

	/sys/bus/pci/drivers/ipw2100/{PCI-ID}/

For example::

	/sys/bus/pci/drivers/ipw2100/0000:02:01.0

For the device level files, see /sys/bus/pci/drivers/ipw2100:

  rf_kill
	read

	==  =========================================
	0   RF kill not enabled (radio on)
	1   SW based RF kill active (radio off)
	2   HW based RF kill active (radio off)
	3   Both HW and SW RF kill active (radio off)
	==  =========================================

	write

	==  ==================================================
	0   If SW based RF kill active, turn the radio back on
	1   If radio is on, activate SW based RF kill
	==  ==================================================

	.. note::

	   If you enable the SW based RF kill and then toggle the HW
	   based RF kill from ON -> OFF -> ON, the radio will NOT come back on

5. Radio Kill Switch
====================

Most laptops provide the ability for the user to physically disable the radio.
Some vendors have implemented this as a physical switch that requires no
software to turn the radio off and on.  On other laptops, however, the switch
is controlled through a button being pressed and a software driver then making
calls to turn the radio off and on.  This is referred to as a "software based
RF kill switch"

See the Sysfs helper file 'rf_kill' for determining the state of the RF switch
on your system.

6. Dynamic Firmware
===================

As the firmware is licensed under a restricted use license, it can not be
included within the kernel sources.  To enable the IPW2100 you will need a
firmware image to load into the wireless NIC's processors.

You can obtain these images from <http://ipw2100.sf.net/firmware.php>.

See INSTALL for instructions on installing the firmware.

7. Power Management
===================

The IPW2100 supports the configuration of the Power Save Protocol
through a private wireless extension interface.  The IPW2100 supports
the following different modes:

	===	===========================================================
	off	No power management.  Radio is always on.
	on	Automatic power management
	1-5	Different levels of power management.  The higher the
		number the greater the power savings, but with an impact to
		packet latencies.
	===	===========================================================

Power management works by powering down the radio after a certain
interval of time has passed where no packets are passed through the
radio.  Once powered down, the radio remains in that state for a given
period of time.  For higher power savings, the interval between last
packet processed to sleep is shorter and the sleep period is longer.

When the radio is asleep, the access point sending data to the station
must buffer packets at the AP until the station wakes up and requests
any buffered packets.  If you have an AP that does not correctly support
the PSP protocol you may experience packet loss or very poor performance
while power management is enabled.  If this is the case, you will need
to try and find a firmware update for your AP, or disable power
management (via ``iwconfig eth1 power off``)

To configure the power level on the IPW2100 you use a combination of
iwconfig and iwpriv.  iwconfig is used to turn power management on, off,
and set it to auto.

	=========================  ====================================
	iwconfig eth1 power off    Disables radio power down
	iwconfig eth1 power on     Enables radio power management to
				   last set level (defaults to AUTO)
	iwpriv eth1 set_power 0    Sets power level to AUTO and enables
				   power management if not previously
				   enabled.
	iwpriv eth1 set_power 1-5  Set the power level as specified,
				   enabling power management if not
				   previously enabled.
	=========================  ====================================

You can view the current power level setting via::

	iwpriv eth1 get_power

It will return the current period or timeout that is configured as a string
in the form of xxxx/yyyy (z) where xxxx is the timeout interval (amount of
time after packet processing), yyyy is the period to sleep (amount of time to
wait before powering the radio and querying the access point for buffered
packets), and z is the 'power level'.  If power management is turned off the
xxxx/yyyy will be replaced with 'off' -- the level reported will be the active
level if `iwconfig eth1 power on` is invoked.

8. Support
==========

For general development information and support,
go to:

    http://ipw2100.sf.net/

The ipw2100 1.1.0 driver and firmware can be downloaded from:

    http://support.intel.com

For installation support on the ipw2100 1.1.0 driver on Linux kernels
2.6.8 or greater, email support is available from:

    http://supportmail.intel.com

9. License
==========

  Copyright |copy| 2003 - 2006 Intel Corporation. All rights reserved.

  This program is free software; you can redistribute it and/or modify it
  under the terms of the GNU General Public License (version 2) as
  published by the Free Software Foundation.

  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  more details.

  You should have received a copy of the GNU General Public License along with
  this program; if not, write to the Free Software Foundation, Inc., 59
  Temple Place - Suite 330, Boston, MA  02111-1307, USA.

  The full GNU General Public License is included in this distribution in the
  file called LICENSE.

  License Contact Information:

  James P. Ketrenos <ipw2100-admin@linux.intel.com>

  Intel Corporation, 5200 N.E. Elam Young Parkway, Hillsboro, OR 97124-6497