From patchwork Fri Feb 24 00:07:22 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Logan Gunthorpe X-Patchwork-Id: 9589169 X-Patchwork-Delegate: bhelgaas@google.com Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 953B7601AE for ; Fri, 24 Feb 2017 00:18:14 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 997FD2875B for ; Fri, 24 Feb 2017 00:18:14 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 8DE242876A; Fri, 24 Feb 2017 00:18:14 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 2E3822875B for ; Fri, 24 Feb 2017 00:18:14 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752469AbdBXASM (ORCPT ); Thu, 23 Feb 2017 19:18:12 -0500 Received: from ale.deltatee.com ([207.54.116.67]:35792 "EHLO ale.deltatee.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751582AbdBXAJr (ORCPT ); Thu, 23 Feb 2017 19:09:47 -0500 Received: from cgy1-donard.priv.deltatee.com ([172.16.1.31] helo=cgy1-donard.pmc-sierra.internal) by ale.deltatee.com with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.84_2) (envelope-from ) id 1ch3Q5-0005PF-G8; Thu, 23 Feb 2017 17:07:35 -0700 Received: from gunthorp by cgy1-donard.pmc-sierra.internal with local (Exim 4.84_2) (envelope-from ) id 1ch3Q1-0000ij-CV; Thu, 23 Feb 2017 17:07:29 -0700 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, 23 Feb 2017 17:07:22 -0700 Message-Id: <1487894844-2721-3-git-send-email-logang@deltatee.com> X-Mailer: git-send-email 2.1.4 In-Reply-To: <1487894844-2721-1-git-send-email-logang@deltatee.com> References: <1487894844-2721-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 v3 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-pci-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-pci@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP 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 Tested-by: Krishna Dhulipala Reviewed-by: Wei Zhang Reviewed-by: Jens Axboe --- 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 a57686f..aa702b0 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -9512,6 +9512,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