dt-bindings: net: dsa: qca8k: support internal mdio-bus
[linux-2.6-block.git] / Documentation / switchtec.txt
CommitLineData
44fc691b
LG
1========================
2Linux Switchtec Support
3========================
4
5Microsemi's "Switchtec" line of PCI switch devices is already
6supported by the kernel with standard PCI switch drivers. However, the
7Switchtec device advertises a special management endpoint which
8enables some additional functionality. This includes:
9
10* Packet and Byte Counters
11* Firmware Upgrades
12* Event and Error logs
13* Querying port link status
14* Custom user firmware commands
15
16The switchtec kernel module implements this functionality.
17
18
19Interface
20=========
21
22The primary means of communicating with the Switchtec management firmware is
23through the Memory-mapped Remote Procedure Call (MRPC) interface.
24Commands are submitted to the interface with a 4-byte command
25identifier and up to 1KB of command specific data. The firmware will
fb513f60 26respond with a 4-byte return code and up to 1KB of command-specific
44fc691b
LG
27data. The interface only processes a single command at a time.
28
29
30Userspace Interface
31===================
32
33The MRPC interface will be exposed to userspace through a simple char
34device: /dev/switchtec#, one for each management endpoint in the system.
35
36The char device has the following semantics:
37
38* A write must consist of at least 4 bytes and no more than 1028 bytes.
fb513f60
WY
39 The first 4 bytes will be interpreted as the Command ID and the
40 remainder will be used as the input data. A write will send the
44fc691b
LG
41 command to the firmware to begin processing.
42
43* Each write must be followed by exactly one read. Any double write will
44 produce an error and any read that doesn't follow a write will
45 produce an error.
46
47* A read will block until the firmware completes the command and return
fb513f60
WY
48 the 4-byte Command Return Value plus up to 1024 bytes of output
49 data. (The length will be specified by the size parameter of the read
50 call -- reading less than 4 bytes will produce an error.)
44fc691b
LG
51
52* The poll call will also be supported for userspace applications that
53 need to do other things while waiting for the command to complete.
52eabba5
LG
54
55The following IOCTLs are also supported by the device:
56
57* SWITCHTEC_IOCTL_FLASH_INFO - Retrieve firmware length and number
58 of partitions in the device.
59
60* SWITCHTEC_IOCTL_FLASH_PART_INFO - Retrieve address and lengeth for
61 any specified partition in flash.
62
63* SWITCHTEC_IOCTL_EVENT_SUMMARY - Read a structure of bitmaps
64 indicating all uncleared events.
65
66* SWITCHTEC_IOCTL_EVENT_CTL - Get the current count, clear and set flags
67 for any event. This ioctl takes in a switchtec_ioctl_event_ctl struct
68 with the event_id, index and flags set (index being the partition or PFF
69 number for non-global events). It returns whether the event has
70 occurred, the number of times and any event specific data. The flags
71 can be used to clear the count or enable and disable actions to
72 happen when the event occurs.
73 By using the SWITCHTEC_IOCTL_EVENT_FLAG_EN_POLL flag,
74 you can set an event to trigger a poll command to return with
75 POLLPRI. In this way, userspace can wait for events to occur.
76
77* SWITCHTEC_IOCTL_PFF_TO_PORT and SWITCHTEC_IOCTL_PORT_TO_PFF convert
78 between PCI Function Framework number (used by the event system)
79 and Switchtec Logic Port ID and Partition number (which is more
80 user friendly).
d0450244
LG
81
82
83Non-Transparent Bridge (NTB) Driver
84===================================
85
fb513f60
WY
86An NTB hardware driver is provided for the Switchtec hardware in
87ntb_hw_switchtec. Currently, it only supports switches configured with
88exactly 2 NT partitions and zero or more non-NT partitions. It also requires
89the following configuration settings:
d0450244 90
fb513f60 91* Both NT partitions must be able to access each other's GAS spaces.
d0450244
LG
92 Thus, the bits in the GAS Access Vector under Management Settings
93 must be set to support this.
fb513f60
WY
94* Kernel configuration MUST include support for NTB (CONFIG_NTB needs
95 to be set)
96
97NT EP BAR 2 will be dynamically configured as a Direct Window, and
98the configuration file does not need to configure it explicitly.
99
100Please refer to Documentation/ntb.txt in Linux source tree for an overall
101understanding of the Linux NTB stack. ntb_hw_switchtec works as an NTB
102Hardware Driver in this stack.