[mirror_ubuntu-eoan-kernel.git] / Documentation / switchtec.txt

========================
Linux Switchtec Support
========================

Microsemi's "Switchtec" line of PCI switch devices is already
supported by the kernel with standard PCI switch drivers. However, the
Switchtec device advertises a special management endpoint which
enables some additional functionality. This includes:

* Packet and Byte Counters
* Firmware Upgrades
* Event and Error logs
* Querying port link status
* Custom user firmware commands

The switchtec kernel module implements this functionality.


Interface
=========

The primary means of communicating with the Switchtec management firmware is
through the Memory-mapped Remote Procedure Call (MRPC) interface.
Commands are submitted to the interface with a 4-byte command
identifier and up to 1KB of command specific data. The firmware will
respond with a 4 bytes return code and up to 1KB of command specific
data. The interface only processes a single command at a time.


Userspace Interface
===================

The MRPC interface will be exposed to userspace through a simple char
device: /dev/switchtec#, one for each management endpoint in the system.

The char device has the following semantics:

* A write must consist of at least 4 bytes and no more than 1028 bytes.
  The first four bytes will be interpreted as the command to run and
  the remainder will be used as the input data. A write will send the
  command to the firmware to begin processing.

* Each write must be followed by exactly one read. Any double write will
  produce an error and any read that doesn't follow a write will
  produce an error.

* A read will block until the firmware completes the command and return
  the four bytes of status plus up to 1024 bytes of output data. (The
  length will be specified by the size parameter of the read call --
  reading less than 4 bytes will produce an error.

* The poll call will also be supported for userspace applications that
  need to do other things while waiting for the command to complete.
Commit	Line	Data
44fc691b LG	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 bytes 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 four bytes will be interpreted as the command to run and
	40	the 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 four bytes of status plus up to 1024 bytes of output data. (The
	49	length will be specified by the size parameter of the read call --
	50	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.