| 1 | ========================
|
| 2 | Linux Switchtec Support
|
| 3 | ========================
|
| 4 |
|
| 5 | Microsemi's "Switchtec" line of PCI switch devices is already
|
| 6 | supported by the kernel with standard PCI switch drivers. However, the
|
| 7 | Switchtec device advertises a special management endpoint which
|
| 8 | enables 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 |
|
| 16 | The switchtec kernel module implements this functionality.
|
| 17 |
|
| 18 |
|
| 19 | Interface
|
| 20 | =========
|
| 21 |
|
| 22 | The primary means of communicating with the Switchtec management firmware is
|
| 23 | through the Memory-mapped Remote Procedure Call (MRPC) interface.
|
| 24 | Commands are submitted to the interface with a 4-byte command
|
| 25 | identifier and up to 1KB of command specific data. The firmware will
|
| 26 | respond with a 4-byte return code and up to 1KB of command-specific
|
| 27 | data. The interface only processes a single command at a time.
|
| 28 |
|
| 29 |
|
| 30 | Userspace Interface
|
| 31 | ===================
|
| 32 |
|
| 33 | The MRPC interface will be exposed to userspace through a simple char
|
| 34 | device: /dev/switchtec#, one for each management endpoint in the system.
|
| 35 |
|
| 36 | The char device has the following semantics:
|
| 37 |
|
| 38 | * A write must consist of at least 4 bytes and no more than 1028 bytes.
|
| 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
|
| 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
|
| 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.)
|
| 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.
|
| 54 |
|
| 55 | The 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).
|
| 81 |
|
| 82 |
|
| 83 | Non-Transparent Bridge (NTB) Driver
|
| 84 | ===================================
|
| 85 |
|
| 86 | An NTB hardware driver is provided for the Switchtec hardware in
|
| 87 | ntb_hw_switchtec. Currently, it only supports switches configured with
|
| 88 | exactly 2 NT partitions and zero or more non-NT partitions. It also requires
|
| 89 | the following configuration settings:
|
| 90 |
|
| 91 | * Both NT partitions must be able to access each other's GAS spaces.
|
| 92 | Thus, the bits in the GAS Access Vector under Management Settings
|
| 93 | must be set to support this.
|
| 94 | * Kernel configuration MUST include support for NTB (CONFIG_NTB needs
|
| 95 | to be set)
|
| 96 |
|
| 97 | NT EP BAR 2 will be dynamically configured as a Direct Window, and
|
| 98 | the configuration file does not need to configure it explicitly.
|
| 99 |
|
| 100 | Please refer to Documentation/driver-api/ntb.rst in Linux source tree for an overall
|
| 101 | understanding of the Linux NTB stack. ntb_hw_switchtec works as an NTB
|
| 102 | Hardware Driver in this stack.
|