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