From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752435AbdBBSHq (ORCPT ); Thu, 2 Feb 2017 13:07:46 -0500 Received: from ale.deltatee.com ([207.54.116.67]:36473 "EHLO ale.deltatee.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752142AbdBBSHo (ORCPT ); Thu, 2 Feb 2017 13:07:44 -0500 From: Logan Gunthorpe To: Keith Busch , Myron Stowe , Greg Kroah-Hartman , Bjorn Helgaas , Geert Uytterhoeven , Jonathan Corbet , "David S. Miller" , Andrew Morton , Emil Velikov , Mauro Carvalho Chehab , Guenter Roeck , Jarkko Sakkinen , Linus Walleij , Ryusuke Konishi , Stefan Berger , Wei Zhang Cc: Kurt Schwemmer , Stephen Bates , linux-pci@vger.kernel.org, linux-doc@vger.kernel.org, linux-nvme@lists.infradead.org, linux-kernel@vger.kernel.org, Logan Gunthorpe Date: Thu, 2 Feb 2017 11:06:01 -0700 Message-Id: <1486058763-7730-3-git-send-email-logang@deltatee.com> X-Mailer: git-send-email 2.1.4 In-Reply-To: <1486058763-7730-1-git-send-email-logang@deltatee.com> References: <1486058763-7730-1-git-send-email-logang@deltatee.com> X-SA-Exim-Connect-IP: 172.16.1.31 X-SA-Exim-Rcpt-To: keith.busch@intel.com, gregkh@linuxfoundation.org, bhelgaas@google.com, geert+renesas@glider.be, corbet@lwn.net, davem@davemloft.net, akpm@linux-foundation.org, myron.stowe@gmail.com, emil.l.velikov@gmail.com, mchehab@kernel.org, linux@roeck-us.net, jarkko.sakkinen@linux.intel.com, linus.walleij@linaro.org, konishi.ryusuke@lab.ntt.co.jp, stefanb@linux.vnet.ibm.com, wzhang@fb.com, kurt.schwemmer@microsemi.com, stephen.bates@microsemi.com, linux-nvme@lists.infradead.org, linux-pci@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, logang@deltatee.com X-SA-Exim-Mail-From: gunthorp@deltatee.com Subject: [PATCH v2 2/4] switchtec: Add user interface documentation X-SA-Exim-Version: 4.2.1 (built Mon, 26 Dec 2011 16:24:06 +0000) X-SA-Exim-Scanned: Yes (on ale.deltatee.com) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org This adds standard documentation for the sysfs switchtec attributes and a RST formatted text file which documents the char device interface. Jonathan Corbet has indicated he will move this to a new user-space developer documentation book once it's created. Signed-off-by: Logan Gunthorpe Signed-off-by: Stephen Bates --- Documentation/switchtec.txt | 53 +++++++++++++++++++++++++++++++++++++++++++++ MAINTAINERS | 1 + 2 files changed, 54 insertions(+) create mode 100644 Documentation/switchtec.txt diff --git a/Documentation/switchtec.txt b/Documentation/switchtec.txt new file mode 100644 index 0000000..4bced4c --- /dev/null +++ b/Documentation/switchtec.txt @@ -0,0 +1,53 @@ +======================== +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. diff --git a/MAINTAINERS b/MAINTAINERS index 9c35198..0ab858d 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -9513,6 +9513,7 @@ M: Stephen Bates M: Logan Gunthorpe L: linux-pci@vger.kernel.org S: Maintained +F: Documentation/switchtec.txt F: drivers/pci/switch/switchtec* PCI DRIVER FOR NVIDIA TEGRA -- 2.1.4