0001 ========================
0002 Linux Switchtec Support
0003 ========================
0004
0005 Microsemi's "Switchtec" line of PCI switch devices is already
0006 supported by the kernel with standard PCI switch drivers. However, the
0007 Switchtec device advertises a special management endpoint which
0008 enables some additional functionality. This includes:
0009
0010 * Packet and Byte Counters
0011 * Firmware Upgrades
0012 * Event and Error logs
0013 * Querying port link status
0014 * Custom user firmware commands
0015
0016 The switchtec kernel module implements this functionality.
0017
0018
0019 Interface
0020 =========
0021
0022 The primary means of communicating with the Switchtec management firmware is
0023 through the Memory-mapped Remote Procedure Call (MRPC) interface.
0024 Commands are submitted to the interface with a 4-byte command
0025 identifier and up to 1KB of command specific data. The firmware will
0026 respond with a 4-byte return code and up to 1KB of command-specific
0027 data. The interface only processes a single command at a time.
0028
0029
0030 Userspace Interface
0031 ===================
0032
0033 The MRPC interface will be exposed to userspace through a simple char
0034 device: /dev/switchtec#, one for each management endpoint in the system.
0035
0036 The char device has the following semantics:
0037
0038 * A write must consist of at least 4 bytes and no more than 1028 bytes.
0039 The first 4 bytes will be interpreted as the Command ID and the
0040 remainder will be used as the input data. A write will send the
0041 command to the firmware to begin processing.
0042
0043 * Each write must be followed by exactly one read. Any double write will
0044 produce an error and any read that doesn't follow a write will
0045 produce an error.
0046
0047 * A read will block until the firmware completes the command and return
0048 the 4-byte Command Return Value plus up to 1024 bytes of output
0049 data. (The length will be specified by the size parameter of the read
0050 call -- reading less than 4 bytes will produce an error.)
0051
0052 * The poll call will also be supported for userspace applications that
0053 need to do other things while waiting for the command to complete.
0054
0055 The following IOCTLs are also supported by the device:
0056
0057 * SWITCHTEC_IOCTL_FLASH_INFO - Retrieve firmware length and number
0058 of partitions in the device.
0059
0060 * SWITCHTEC_IOCTL_FLASH_PART_INFO - Retrieve address and lengeth for
0061 any specified partition in flash.
0062
0063 * SWITCHTEC_IOCTL_EVENT_SUMMARY - Read a structure of bitmaps
0064 indicating all uncleared events.
0065
0066 * SWITCHTEC_IOCTL_EVENT_CTL - Get the current count, clear and set flags
0067 for any event. This ioctl takes in a switchtec_ioctl_event_ctl struct
0068 with the event_id, index and flags set (index being the partition or PFF
0069 number for non-global events). It returns whether the event has
0070 occurred, the number of times and any event specific data. The flags
0071 can be used to clear the count or enable and disable actions to
0072 happen when the event occurs.
0073 By using the SWITCHTEC_IOCTL_EVENT_FLAG_EN_POLL flag,
0074 you can set an event to trigger a poll command to return with
0075 POLLPRI. In this way, userspace can wait for events to occur.
0076
0077 * SWITCHTEC_IOCTL_PFF_TO_PORT and SWITCHTEC_IOCTL_PORT_TO_PFF convert
0078 between PCI Function Framework number (used by the event system)
0079 and Switchtec Logic Port ID and Partition number (which is more
0080 user friendly).
0081
0082
0083 Non-Transparent Bridge (NTB) Driver
0084 ===================================
0085
0086 An NTB hardware driver is provided for the Switchtec hardware in
0087 ntb_hw_switchtec. Currently, it only supports switches configured with
0088 exactly 2 NT partitions and zero or more non-NT partitions. It also requires
0089 the following configuration settings:
0090
0091 * Both NT partitions must be able to access each other's GAS spaces.
0092 Thus, the bits in the GAS Access Vector under Management Settings
0093 must be set to support this.
0094 * Kernel configuration MUST include support for NTB (CONFIG_NTB needs
0095 to be set)
0096
0097 NT EP BAR 2 will be dynamically configured as a Direct Window, and
0098 the configuration file does not need to configure it explicitly.
0099
0100 Please refer to Documentation/driver-api/ntb.rst in Linux source tree for an overall
0101 understanding of the Linux NTB stack. ntb_hw_switchtec works as an NTB
0102 Hardware Driver in this stack.
