Re: [PATCH v2 3/4] switchtec: Add sysfs attributes to the Switchtec driver

[Bjorn Helgaas]

On Thu, Feb 23, 2017 at 03:56:21PM -0700, Logan Gunthorpe wrote:
> 
> 
> On 23/02/17 03:43 PM, Bjorn Helgaas wrote:
> > This path seems a little generic.  I don't see other cases where a
> > product brand name ("Switchtec") appears at the top level of
> > /sys/class/...
> 
> Ok, well we are certainly open to suggestions, but there isn't really a
> generic version of this device available so I'm not sure how we would
> change that. Per device-type classes aren't that uncommon though, a
> quick grep shows things like:
> 
> platform/chrome/cros_ec_dev.c:40:static struct class cros_class
> s390/char/raw3270.h:94:extern struct class *class3270;
> net/ethernet/hisilicon/hns/hnae.c:19:static struct class *hnae_class;
> mfd/ucb1x00-core.c:490:static struct class ucb1x00_class
> 
> > My question is based on "ls Documentation/ABI/testing/sysfs-class*",
> > not on any great knowledge of sysfs, and I see Greg has already given
> > a Reviewed-by for this, so maybe this is the right approach.
> > 
> > It does seem like the path could include a clue that this is related
> > to PCI.
> 
> I mean, we could change it to pci-switchtec or something if you think
> that would be better..?? But I'm not sure how else to accommodate this.

I'm OK with it as-is.

> > Is there a link to the switch PCI device itself, e.g., to
> > /sys/devices/pci*?  Should these attributes simply be put in a
> > subdirectory there, e.g., in
> > 
> >   /sys/devices/pci:00/:00:00.0/stats/...
> 
> Well our device shows up here in the tree:
> 
> /sys/devices/pci:00/:00:03.0/:03:00.1/switchtec/switchtec0
> 
> (Which userspace can get to by following the link at
> /sys/class/switchtec/switchtec0) The switch is then always:
> 
> /sys/devices/pci:00/:00:03.0

That's exactly what I was looking for; I just didn't realize it was
connected like this.

Bjorn
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v4 3/4] switchtec: Add sysfs attributes to the Switchtec driver

[Logan Gunthorpe]

This patch adds a few read-only sysfs attributes which provide
some device information that is exposed from the devices. Primarily
component and device names and versions. These are documented in
Documentation/ABI/testing/sysfs-class-switchtec.

Signed-off-by: Logan Gunthorpe 
Signed-off-by: Stephen Bates 
Tested-by: Krishna Dhulipala 
Reviewed-by: Wei Zhang 
Reviewed-by: Jens Axboe 
Reviewed-by: Greg Kroah-Hartman 
---
 Documentation/ABI/testing/sysfs-class-switchtec |  96 
 MAINTAINERS |   1 +
 drivers/pci/switch/switchtec.c  | 113 
 3 files changed, 210 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-switchtec

diff --git a/Documentation/ABI/testing/sysfs-class-switchtec 
b/Documentation/ABI/testing/sysfs-class-switchtec
new file mode 100644
index 000..48cb4c1
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-switchtec
@@ -0,0 +1,96 @@
+switchtec - Microsemi Switchtec PCI Switch Management Endpoint
+
+For details on this subsystem look at Documentation/switchtec.txt.
+
+What:  /sys/class/switchtec
+Date:  05-Jan-2017
+KernelVersion: v4.11
+Contact:   Logan Gunthorpe 
+Description:   The switchtec class subsystem folder.
+   Each registered switchtec driver is represented by a switchtecX
+   subfolder (X being an integer >= 0).
+
+
+What:  /sys/class/switchtec/switchtec[0-9]+/component_id
+Date:  05-Jan-2017
+KernelVersion: v4.11
+Contact:   Logan Gunthorpe 
+Description:   Component identifier as stored in the hardware (eg. PM8543)
+   (read only)
+Values:arbitrary string.
+
+
+What:  /sys/class/switchtec/switchtec[0-9]+/component_revision
+Date:  05-Jan-2017
+KernelVersion: v4.11
+Contact:   Logan Gunthorpe 
+Description:   Component revision stored in the hardware (read only)
+Values:integer.
+
+
+What:  /sys/class/switchtec/switchtec[0-9]+/component_vendor
+Date:  05-Jan-2017
+KernelVersion: v4.11
+Contact:   Logan Gunthorpe 
+Description:   Component vendor as stored in the hardware (eg. MICROSEM)
+   (read only)
+Values:arbitrary string.
+
+
+What:  /sys/class/switchtec/switchtec[0-9]+/device_version
+Date:  05-Jan-2017
+KernelVersion: v4.11
+Contact:   Logan Gunthorpe 
+Description:   Device version as stored in the hardware (read only)
+Values:integer.
+
+
+What:  /sys/class/switchtec/switchtec[0-9]+/fw_version
+Date:  05-Jan-2017
+KernelVersion: v4.11
+Contact:   Logan Gunthorpe 
+Description:   Currently running firmware version (read only)
+Values:integer (in hexadecimal).
+
+
+What:  /sys/class/switchtec/switchtec[0-9]+/partition
+Date:  05-Jan-2017
+KernelVersion: v4.11
+Contact:   Logan Gunthorpe 
+Description:   Partition number for this device in the switch (read only)
+Values:integer.
+
+
+What:  /sys/class/switchtec/switchtec[0-9]+/partition_count
+Date:  05-Jan-2017
+KernelVersion: v4.11
+Contact:   Logan Gunthorpe 
+Description:   Total number of partitions in the switch (read only)
+Values:integer.
+
+
+What:  /sys/class/switchtec/switchtec[0-9]+/product_id
+Date:  05-Jan-2017
+KernelVersion: v4.11
+Contact:   Logan Gunthorpe 
+Description:   Product identifier as stored in the hardware (eg. PSX 48XG3)
+   (read only)
+Values:arbitrary string.
+
+
+What:  /sys/class/switchtec/switchtec[0-9]+/product_revision
+Date:  05-Jan-2017
+KernelVersion: v4.11
+Contact:   Logan Gunthorpe 
+Description:   Product revision stored in the hardware (eg. RevB)
+   (read only)
+Values:arbitrary string.
+
+
+What:  /sys/class/switchtec/switchtec[0-9]+/product_vendor
+Date:  05-Jan-2017
+KernelVersion: v4.11
+Contact:   Logan Gunthorpe 
+Description:   Product vendor as stored in the hardware (eg. MICROSEM)
+   (read only)
+Values:arbitrary string.
diff --git a/MAINTAINERS b/MAINTAINERS
index aa702b0..6fed938 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9513,6 +9513,7 @@ M:Logan Gunthorpe 
 L: linux-...@vger.kernel.org
 S: Maintained
 F: Documentation/switchtec.txt
+F: Documentation/ABI/testing/sysfs-class-switchtec
 F: drivers/pci/switch/switchtec*
 
 PCI DRIVER FOR NVIDIA TEGRA
diff --git a/drivers/pci/switch/switchtec.c b/drivers/pci/switch/switchtec.c
index f5813e0..2e3a45b 100644
--- 

[PATCH v4 4/4] switchtec: Add IOCTLs to the Switchtec driver

[Logan Gunthorpe]

This patch introduces a couple of special IOCTLs which are provided to:

* Inform userspace of firmware partition locations
* Pass event counts and allow userspace to wait on events
* Translate between PFF numbers used by the switch to
  port numbers.

Signed-off-by: Logan Gunthorpe 
Signed-off-by: Stephen Bates 
Tested-by: Krishna Dhulipala 
Reviewed-by: Wei Zhang 
Reviewed-by: Jens Axboe 
---
 Documentation/ioctl/ioctl-number.txt |   1 +
 Documentation/switchtec.txt  |  27 ++
 MAINTAINERS  |   1 +
 drivers/pci/switch/switchtec.c   | 467 +++
 include/uapi/linux/switchtec_ioctl.h | 132 ++
 5 files changed, 628 insertions(+)
 create mode 100644 include/uapi/linux/switchtec_ioctl.h

diff --git a/Documentation/ioctl/ioctl-number.txt 
b/Documentation/ioctl/ioctl-number.txt
index 81c7f2b..032b33c 100644
--- a/Documentation/ioctl/ioctl-number.txt
+++ b/Documentation/ioctl/ioctl-number.txt
@@ -191,6 +191,7 @@ Code  Seq#(hex) Include FileComments
 'W'00-1F   linux/watchdog.hconflict!
 'W'00-1F   linux/wanrouter.h   conflict!   (pre 3.9)
 'W'00-3F   sound/asound.h  conflict!
+'W'40-5F   drivers/pci/switch/switchtec.c
 'X'all fs/xfs/xfs_fs.h conflict!
and fs/xfs/linux-2.6/xfs_ioctl32.h
and include/linux/falloc.h
diff --git a/Documentation/switchtec.txt b/Documentation/switchtec.txt
index 4bced4c..a0a9c7b 100644
--- a/Documentation/switchtec.txt
+++ b/Documentation/switchtec.txt
@@ -51,3 +51,30 @@ The char device has the following semantics:
 
 * The poll call will also be supported for userspace applications that
   need to do other things while waiting for the command to complete.
+
+The following IOCTLs are also supported by the device:
+
+* SWITCHTEC_IOCTL_FLASH_INFO - Retrieve firmware length and number
+  of partitions in the device.
+
+* SWITCHTEC_IOCTL_FLASH_PART_INFO - Retrieve address and lengeth for
+  any specified partition in flash.
+
+* SWITCHTEC_IOCTL_EVENT_SUMMARY - Read a structure of bitmaps
+  indicating all uncleared events.
+
+* SWITCHTEC_IOCTL_EVENT_CTL - Get the current count, clear and set flags
+  for any event. This ioctl takes in a switchtec_ioctl_event_ctl struct
+  with the event_id, index and flags set (index being the partition or PFF
+  number for non-global events). It returns whether the event has
+  occurred, the number of times and any event specific data. The flags
+  can be used to clear the count or enable and disable actions to
+  happen when the event occurs.
+  By using the SWITCHTEC_IOCTL_EVENT_FLAG_EN_POLL flag,
+  you can set an event to trigger a poll command to return with
+  POLLPRI. In this way, userspace can wait for events to occur.
+
+* SWITCHTEC_IOCTL_PFF_TO_PORT and SWITCHTEC_IOCTL_PORT_TO_PFF convert
+  between PCI Function Framework number (used by the event system)
+  and Switchtec Logic Port ID and Partition number (which is more
+  user friendly).
diff --git a/MAINTAINERS b/MAINTAINERS
index 6fed938..c1a9a30 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9515,6 +9515,7 @@ S:Maintained
 F: Documentation/switchtec.txt
 F: Documentation/ABI/testing/sysfs-class-switchtec
 F: drivers/pci/switch/switchtec*
+F: include/uapi/linux/switchtec_ioctl.h
 
 PCI DRIVER FOR NVIDIA TEGRA
 M: Thierry Reding 
diff --git a/drivers/pci/switch/switchtec.c b/drivers/pci/switch/switchtec.c
index 2e3a45b..18286d3 100644
--- a/drivers/pci/switch/switchtec.c
+++ b/drivers/pci/switch/switchtec.c
@@ -13,6 +13,8 @@
  *
  */
 
+#include 
+
 #include 
 #include 
 #include 
@@ -717,6 +719,417 @@ static unsigned int switchtec_dev_poll(struct file *filp, 
poll_table *wait)
return ret;
 }
 
+static int ioctl_flash_info(struct switchtec_dev *stdev,
+   struct switchtec_ioctl_flash_info __user *uinfo)
+{
+   struct switchtec_ioctl_flash_info info = {0};
+   struct flash_info_regs __iomem *fi = stdev->mmio_flash_info;
+
+   info.flash_length = ioread32(>flash_length);
+   info.num_partitions = SWITCHTEC_IOCTL_NUM_PARTITIONS;
+
+   if (copy_to_user(uinfo, , sizeof(info)))
+   return -EFAULT;
+
+   return 0;
+}
+
+static void set_fw_info_part(struct switchtec_ioctl_flash_part_info *info,
+struct partition_info __iomem *pi)
+{
+   info->address = ioread32(>address);
+   info->length = ioread32(>length);
+}
+
+static int ioctl_flash_part_info(struct switchtec_dev *stdev,
+   struct switchtec_ioctl_flash_part_info __user *uinfo)
+{
+   struct switchtec_ioctl_flash_part_info info = {0};
+   struct flash_info_regs __iomem *fi = stdev->mmio_flash_info;
+   u32 active_addr = -1;
+
+   if (copy_from_user(, uinfo, sizeof(info)))
+   return 

[PATCH v4 0/4] New Microsemi PCI Switch Management Driver

[Logan Gunthorpe]

Changes since v3:

* Removed stdev_is_alive and moved pci deinit functions
  into the device release function which only occurs after all
  cdev instances are closed. (per Bjorn)
* Reduced locking in read/write functions (per Bjorn)
* Use pci_alloc_irq_vectors to vastly improve ISR initialization (Bjorn)
* A few other minor nits and cleanup as noticed by Bjorn

Changes since v2:

* Collected reviewed and tested tags
* Very minor fix to the error path in the create function

Changes since v1:

* Rebased onto 4.10-rc6 (cleanly)
* Split the patch into a few more easily digestible patches (as
  suggested by Greg Kroah-Hartman)
* Folded switchtec.c into switchtec.h (per Greg)
* Fixed a bunch of 32bit build warnings caught by the kbuild test robot
* Fixed some issues in the documentation so it has a proper
  reStructredText format (as noted by Jonathan Corbet)
* Fixed padding and sizes in the IOCTL structures as noticed by Emil
  Velikov and used pahole to verify their consistency across 32 and 64
  bit builds
* Reworked one of the IOCTL interfaces to be more future proof (per
  Emil).

Changes since RFC:

* Fixed incorrect use of the drive model as pointed out by Greg
  Kroah-Hartman
* Used devm functions as suggested by Keith Busch
* Added a handful of sysfs attributes to the switchtec class
* Added a handful of IOCTLs to the switchtec device
* A number of miscellaneous bug fixes

--

Hi,

This is a continuation of the RFC we posted lasted month [1] which
proposes a management driver for Microsemi's Switchtec line of PCI
switches. This hardware is still looking to be used in the Open
Compute Platform

To make this entirely clear: the Switchtec products are compliant
with the PCI specifications and are supported today with the standard
in-kernel driver. However, these devices also expose a management endpoint
on a separate PCI function address which can be used to perform some
advanced operations. This is a driver for that function. See the patch
for more information.

Since the RFC, we've made the changes requested by Greg Kroah-Hartman
and Keith Busch, and we've also fleshed out a number of features. We've
added a couple of IOCTLs and sysfs attributes which are documented in
the patch. Significant work has also been done on the userspace tool
which is available under a GPL license at [2]. We've also had testing
done by some of the interested parties.

We hope to see this work included in either 4.11 or 4.12 assuming a
smooth review process.

The patch is based off of the v4.10-rc6 release.

Thanks for your review,

Logan

[1] https://www.spinics.net/lists/linux-pci/msg56897.html
[2] https://github.com/sbates130272/switchtec-user

Logan Gunthorpe (4):
  MicroSemi Switchtec management interface driver
  switchtec: Add user interface documentation
  switchtec: Add sysfs attributes to the Switchtec driver
  switchtec: Add IOCTLs to the Switchtec driver

 Documentation/ABI/testing/sysfs-class-switchtec |   96 ++
 Documentation/ioctl/ioctl-number.txt|1 +
 Documentation/switchtec.txt |   80 ++
 MAINTAINERS |   11 +
 drivers/pci/Kconfig |1 +
 drivers/pci/Makefile|1 +
 drivers/pci/switch/Kconfig  |   13 +
 drivers/pci/switch/Makefile |1 +
 drivers/pci/switch/switchtec.c  | 1503 +++
 include/uapi/linux/switchtec_ioctl.h|  132 ++
 10 files changed, 1839 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-switchtec
 create mode 100644 Documentation/switchtec.txt
 create mode 100644 drivers/pci/switch/Kconfig
 create mode 100644 drivers/pci/switch/Makefile
 create mode 100644 drivers/pci/switch/switchtec.c
 create mode 100644 include/uapi/linux/switchtec_ioctl.h

--
2.1.4
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v4 1/4] MicroSemi Switchtec management interface driver

[Logan Gunthorpe]

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

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

This patch introduces the switchtec kernel module which provides
PCI driver that exposes a char device. The char device provides
userspace access to this interface through read, write and (optionally)
poll calls.

A userspace tool and library which utilizes this interface is available
at [1]. This tool takes inspiration (and borrows some code) from
nvme-cli [2]. The tool is largely complete at this time but additional
features may be added in the future.

[1] https://github.com/sbates130272/switchtec-user
[2] https://github.com/linux-nvme/nvme-cli

Signed-off-by: Logan Gunthorpe 
Signed-off-by: Stephen Bates 
Tested-by: Krishna Dhulipala 
Reviewed-by: Wei Zhang 
Reviewed-by: Jens Axboe 
Reviewed-by: Greg Kroah-Hartman 
---
 MAINTAINERS|   8 +
 drivers/pci/Kconfig|   1 +
 drivers/pci/Makefile   |   1 +
 drivers/pci/switch/Kconfig |  13 +
 drivers/pci/switch/Makefile|   1 +
 drivers/pci/switch/switchtec.c | 923 +
 6 files changed, 947 insertions(+)
 create mode 100644 drivers/pci/switch/Kconfig
 create mode 100644 drivers/pci/switch/Makefile
 create mode 100644 drivers/pci/switch/switchtec.c

diff --git a/MAINTAINERS b/MAINTAINERS
index 527d137..a57686f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9506,6 +9506,14 @@ S:   Maintained
 F: Documentation/devicetree/bindings/pci/aardvark-pci.txt
 F: drivers/pci/host/pci-aardvark.c
 
+PCI DRIVER FOR MICROSEMI SWITCHTEC
+M: Kurt Schwemmer 
+M: Stephen Bates 
+M: Logan Gunthorpe 
+L: linux-...@vger.kernel.org
+S: Maintained
+F: drivers/pci/switch/switchtec*
+
 PCI DRIVER FOR NVIDIA TEGRA
 M: Thierry Reding 
 L: linux-te...@vger.kernel.org
diff --git a/drivers/pci/Kconfig b/drivers/pci/Kconfig
index 6555eb7..f72e8c5 100644
--- a/drivers/pci/Kconfig
+++ b/drivers/pci/Kconfig
@@ -133,3 +133,4 @@ config PCI_HYPERV
 
 source "drivers/pci/hotplug/Kconfig"
 source "drivers/pci/host/Kconfig"
+source "drivers/pci/switch/Kconfig"
diff --git a/drivers/pci/Makefile b/drivers/pci/Makefile
index 8db5079..15b46dd 100644
--- a/drivers/pci/Makefile
+++ b/drivers/pci/Makefile
@@ -68,3 +68,4 @@ ccflags-$(CONFIG_PCI_DEBUG) := -DDEBUG
 
 # PCI host controller drivers
 obj-y += host/
+obj-y += switch/
diff --git a/drivers/pci/switch/Kconfig b/drivers/pci/switch/Kconfig
new file mode 100644
index 000..4c49648
--- /dev/null
+++ b/drivers/pci/switch/Kconfig
@@ -0,0 +1,13 @@
+menu "PCI switch controller drivers"
+   depends on PCI
+
+config PCI_SW_SWITCHTEC
+   tristate "MicroSemi Switchtec PCIe Switch Management Driver"
+   help
+Enables support for the management interface for the MicroSemi
+Switchtec series of PCIe switches. Supports userspace access
+to submit MRPC commands to the switch via /dev/switchtecX
+devices. See  for more
+information.
+
+endmenu
diff --git a/drivers/pci/switch/Makefile b/drivers/pci/switch/Makefile
new file mode 100644
index 000..37d8cfb
--- /dev/null
+++ b/drivers/pci/switch/Makefile
@@ -0,0 +1 @@
+obj-$(CONFIG_PCI_SW_SWITCHTEC) += switchtec.o
diff --git a/drivers/pci/switch/switchtec.c b/drivers/pci/switch/switchtec.c
new file mode 100644
index 000..f5813e0
--- /dev/null
+++ b/drivers/pci/switch/switchtec.c
@@ -0,0 +1,923 @@
+/*
+ * Microsemi Switchtec(tm) PCIe Management Driver
+ * Copyright (c) 2017, Microsemi Corporation
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms and conditions of the GNU General Public License,
+ * version 2, as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ */
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+MODULE_DESCRIPTION("Microsemi Switchtec(tm) PCIe Management Driver");
+MODULE_VERSION("0.1");
+MODULE_LICENSE("GPL");
+MODULE_AUTHOR("Microsemi Corporation");
+
+static int max_devices = 16;
+module_param(max_devices, int, 0644);
+MODULE_PARM_DESC(max_devices, "max number of switchtec device instances");
+
+static 

[PATCH v4 2/4] switchtec: Add user interface documentation

[Logan Gunthorpe]

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 000..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-...@vger.kernel.org
 S: Maintained
+F: Documentation/switchtec.txt
 F: drivers/pci/switch/switchtec*
 
 PCI DRIVER FOR NVIDIA TEGRA
-- 
2.1.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 1/4] MicroSemi Switchtec management interface driver

[Logan Gunthorpe]

Hey Bjorn,

Thanks for the thorough review. It definitely helped a lot to make the
code as good as it can be.

I've made all of the changes you suggested. I'm just going to do a bit
more testing and then post a v4. See my responses to all of your
feedback bellow.

Logan

On 23/02/17 05:35 PM, Bjorn Helgaas wrote:
> Would it make any sense to integrate this with the perf tool?  It
> looks like switchtec-user measures bandwidth and latency, which sounds
> sort of perf-ish.

That would be cool but lets file that under potential future work. This
driver also enables more than bandwidth and latency so it's still
required for us.

>> +MODULE_DESCRIPTION("Microsemi Switchtec(tm) PCI-E Management Driver");
> 
> Nit: s/PCI-E/PCIe/
> 

Fixed.

>> +MODULE_VERSION("0.1");
>> +MODULE_LICENSE("GPL");
>> +MODULE_AUTHOR("Microsemi Corporation");
>> +
>> +static int max_devices = 16;
> 
> This static initialization is slightly misleading because
> switchtec_init() immediately sets max_devices to at least 256.

Oops copied that from dax without thinking. I've just removed the max()
call in the init function.


>> +atomic_t event_cnt;
> 
> Why is this atomic_t?  You only do an atomic_set() (in stdev_create())
> and atomic_reads() -- no writes other than the initial one.  So I'm
> not sure what value atomic_t brings.

If you looked at a following patch in the series you'd see that there's
an atomic_inc in the ISR. The splitting of the series wasn't as precise
as it maybe should have been and thus this became a bit confusing.

>> +memcpy_fromio(stuser->data, >mmio_mrpc->output_data,
>> +  sizeof(stuser->data));
> 
> Apparently you always get 1K of data back, no matter what?

Yes, sort of unfortunately. Because these transactions can occur before
the user actually does the read, we don't know how much data the user
wants. This may be a performance improvement in the future (ie. if the
user reads before the MRPC transaction comes back, then only read the
requested amount). But we will leave it this way for now.


>> +if (!stdev_is_alive(stdev))
>> +return -ENXIO;
> 
> What exactly does this protect against?  Is it OK if stdev_is_alive()
> becomes false immediately after we check?

Yup, you're right: that's racy. Turns out cleanup is hard and I've
learned a lot even in the short time since I wrote this code. I've
gotten rid of stdev_is_alive and moved the pci cleanup code into the
device's release function so they won't occur until the last user closes
the cdev. I think that should work better but please let me know if you
see an issue with this.

>> +
>> +if (size < sizeof(stuser->cmd) ||
>> +size > sizeof(stuser->cmd) + SWITCHTEC_MRPC_PAYLOAD_SIZE)
> 
> I think I would use "sizeof(stuser->data)" instead of
> SWITCHTEC_MRPC_PAYLOAD_SIZE so it matches what mrpc_complete_cmd()
> does.  Same below in switchtec_dev_read().

Ok.

> mrpc_mutex doesn't protect the stuser things, does it?  If not, you
> could do this without the gotos.  And I think it's a little easier to
> be confident there are no buffer overruns:

I was using the mutex to protect stuser->state as well. But I've made
your changes and just adjusted stuser->state to be atomic and I think
this should be just as good.

>> +static int switchtec_init_msix_isr(struct switchtec_dev *stdev)
>> +{
>> +struct pci_dev *pdev = stdev->pdev;
>> +int rc, i, msix_count, node;
>> +
>> +node = dev_to_node(>dev);
> 
> Unused?

Yup, I've removed it.

>> +for (i = 0; i < ARRAY_SIZE(stdev->msix); ++i)
>> +stdev->msix[i].entry = i;
>> +
>> +msix_count = pci_enable_msix_range(pdev, stdev->msix, 1,
>> +   ARRAY_SIZE(stdev->msix));
>> +if (msix_count < 0)
>> +return msix_count;
> 
> Maybe this could be simplified by using pci_alloc_irq_vectors()?

Yup! I wasn't aware of that function. It's a _huge_ improvement. Thanks.
Still I'd really appreciate a quick re-review after I post v4 just to
make sure I got it correct.

>> +stdev->event_irq = ioread32(>mmio_part_cfg->vep_vector_number);
>> +if (stdev->event_irq < 0 || stdev->event_irq >= msix_count) {
>> +rc = -EFAULT;
>> +goto err_msix_request;
>> +}
> 
> Not sure what this is doing, but you immediately overwrite
> stdev->event_irq below.  If you're using it as just a temporary above
> for doing some validation, I would just use a local variable to avoid
> the connection with stdev->event_irq.

Yes, I made this temporary.

>> +stdev->event_irq = stdev->msix[stdev->event_irq].vector;
> 
> Oh, I guess you allocate several MSI-X vectors, but you only actually
> use one of them?  Why is that?  I was confused about why you allocate
> several vectors, but there's only one devm_request_irq() call below.

The event_irq is configurable in hardware and won't necessarily be the
first irq available. (It should always be in the first four.) As I
understand it, we need to allocate all of 

Re: [PATCH] lib/Kconfig.debug: correct documentation paths

[Krzysztof Kozlowski]

On Fri, Feb 24, 2017 at 10:21:35AM -0700, Jonathan Corbet wrote:
> On Fri, 24 Feb 2017 10:36:20 +0200
> Krzysztof Kozlowski <k...@kernel.org> wrote:
> 
> > What happened with this patch? I am asking because on top of
> > next-20170224 I found some more sysrq.txt obsolete paths... including
> > the ones fixed here. I am not sure whether I am fixing something
> > already fixed?
> 
> What happened, most likely, is that I saw /lib/Kconfig.debug and assumed
> it was one of the many patches sent my way that aren't really up to me to
> handle.  But nobody else really owns /lib either, I guess.  I've dug the
> patch out of my archive and will get it in.
>

Greatm thank you!

Best regards,
Krzysztof

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] lib/Kconfig.debug: correct documentation paths

[Jonathan Corbet]

On Fri, 24 Feb 2017 10:36:20 +0200
Krzysztof Kozlowski <k...@kernel.org> wrote:

> What happened with this patch? I am asking because on top of
> next-20170224 I found some more sysrq.txt obsolete paths... including
> the ones fixed here. I am not sure whether I am fixing something
> already fixed?

What happened, most likely, is that I saw /lib/Kconfig.debug and assumed
it was one of the many patches sent my way that aren't really up to me to
handle.  But nobody else really owns /lib either, I guess.  I've dug the
patch out of my archive and will get it in.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH v4 14/28] Add support to access boot related data in the clear

[Borislav Petkov]

On Fri, Feb 24, 2017 at 09:04:21AM -0600, Tom Lendacky wrote:
> I looked at doing that but you get into this cyclical situation unless
> you specifically map each setup data elemement as decrypted. This is ok
> for early_memremap since we have early_memremap_decrypted() but a new
> memremap_decrypted() would have to be added. But I was trying to avoid
> having to do multiple mapping calls inside the current mapping call.
> 
> I can always look at converting the setup_data_list from an array
> into a list to eliminate the 32 entry limit, too.
> 
> Let me look at adding the early_memremap_decrypted() type support to
> memremap() and see how that looks.

Yes, so this sounds better than the cyclic thing you explained
where you have to add and update since early_memremap() calls into
memremap_should_map_encrypted() which touches the list we're updating at
the same time.

So in the case where you absolutely know that those ranges should
be mapped decrypted, we should have special helpers which do that
explicitly and they are called when we access those special regions.
Well, special for SME. I'm thinking that should simplify the handling
but you'll know better once you write it. :)

Thanks.

-- 
Regards/Gruss,
Boris.

Good mailing practices for 400: avoid top-posting and trim the reply.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH v4 14/28] Add support to access boot related data in the clear

[Tom Lendacky]

On 2/24/2017 4:21 AM, Borislav Petkov wrote:

On Thu, Feb 23, 2017 at 03:34:30PM -0600, Tom Lendacky wrote:

Hmm... maybe I'm missing something here.  This doesn't have anything to
do with kexec or efi_reuse_config.  This has to do with the fact that


I said kexec because kexec uses the setup_data mechanism to pass config
tables to the second kernel, for example.


when a system boots the setup data and the EFI data are not encrypted.
Since it's not encrypted we need to be sure that any early_memremap()
and memremap() calls remove the encryption mask from the resulting
pagetable entry that is created so the data can be accessed properly.


Anyway, I'd prefer not to do this ad-hoc caching if it can be
helped. You're imposing an arbitrary limit of 32 there which the
setup_data linked list doesn't have. So if you really want to go
inspect those elements, you could iterate over them starting from
boot_params.hdr.setup_data, just like parse_setup_data() does. Most of
the time that list should be non-existent and if it is, it will be short
anyway.



I looked at doing that but you get into this cyclical situation unless
you specifically map each setup data elemement as decrypted. This is ok
for early_memremap since we have early_memremap_decrypted() but a new
memremap_decrypted() would have to be added. But I was trying to avoid
having to do multiple mapping calls inside the current mapping call.

I can always look at converting the setup_data_list from an array
into a list to eliminate the 32 entry limit, too.

Let me look at adding the early_memremap_decrypted() type support to
memremap() and see how that looks.


And if we really decide that we need to cache it for later inspection
due to speed considerations, as you do in memremap_is_setup_data(), you
could do that in the default: branch of parse_setup_data() and do it
just once: I don't see why you need to do add_to_setup_data_list() *and*
update_setup_data_list() when you could add both pointer and updated
size once.


I do the add followed by the update because we can't determine the true
size of the setup data until it is first mapped so that the data->len
field can be accessed. In order to map it properly the physical
address range needs to be added to the list before it is mapped. After
it's mapped, the true physical address range can be calculated and
updated.

Thanks,
Tom




--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH v4 13/28] efi: Update efi_mem_type() to return defined EFI mem types

[Matt Fleming]

On Thu, 23 Feb, at 11:27:55AM, Tom Lendacky wrote:
> 
> I can do that, I'll change the return type to an int. For the
> !efi_enabled I can return -ENOTSUPP and for when an entry isn't
> found I can return -EINVAL.  Sound good?
 
Sounds good to me!
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: Update path to sysrq.txt

[Mauro Carvalho Chehab]

Em Fri, 24 Feb 2017 10:42:14 +0200
Krzysztof Kozlowski  escreveu:

> Commit 9d85025b0418 ("docs-rst: create an user's manual book") moved the
> sysrq.txt leaving old paths in the kernel docs.
> 
> Signed-off-by: Krzysztof Kozlowski 
Reviewed-by: Mauro Carvalho Chehab 

> ---
>  Documentation/media/v4l-drivers/bttv.rst  | 2 +-
>  Documentation/s390/Debugging390.txt   | 2 +-
>  Documentation/sysctl/kernel.txt   | 2 +-
>  Documentation/virtual/uml/UserModeLinux-HOWTO.txt | 6 +++---
>  4 files changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/media/v4l-drivers/bttv.rst 
> b/Documentation/media/v4l-drivers/bttv.rst
> index bc63b12efafd..195ccaac2816 100644
> --- a/Documentation/media/v4l-drivers/bttv.rst
> +++ b/Documentation/media/v4l-drivers/bttv.rst
> @@ -312,7 +312,7 @@ information out of a register+stack dump printed by the 
> kernel on
>  protection faults (so-called "kernel oops").
>  
>  If you run into some kind of deadlock, you can try to dump a call trace
> -for each process using sysrq-t (see Documentation/sysrq.txt).
> +for each process using sysrq-t (see Documentation/admin-guide/sysrq.rst).
>  This way it is possible to figure where *exactly* some process in "D"
>  state is stuck.
>  
> diff --git a/Documentation/s390/Debugging390.txt 
> b/Documentation/s390/Debugging390.txt
> index 3df8babcdc41..5ae7f868a007 100644
> --- a/Documentation/s390/Debugging390.txt
> +++ b/Documentation/s390/Debugging390.txt
> @@ -2116,7 +2116,7 @@ The sysrq key reading is very picky ( I have to type 
> the keys in an
>  This is particularly useful for syncing disks unmounting & rebooting
>  if the machine gets partially hung.
>  
> -Read Documentation/sysrq.txt for more info
> +Read Documentation/admin-guide/sysrq.rst for more info
>  
>  References:
>  ===
> diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt
> index a32b4b748644..bac23c198360 100644
> --- a/Documentation/sysctl/kernel.txt
> +++ b/Documentation/sysctl/kernel.txt
> @@ -85,7 +85,7 @@ show up in /proc/sys/kernel:
>  - softlockup_all_cpu_backtrace
>  - soft_watchdog
>  - stop-a  [ SPARC only ]
> -- sysrq   ==> Documentation/sysrq.txt
> +- sysrq   ==> Documentation/admin-guide/sysrq.rst
>  - sysctl_writes_strict
>  - tainted
>  - threads-max
> diff --git a/Documentation/virtual/uml/UserModeLinux-HOWTO.txt 
> b/Documentation/virtual/uml/UserModeLinux-HOWTO.txt
> index f4099ca6b483..87b80f589e1c 100644
> --- a/Documentation/virtual/uml/UserModeLinux-HOWTO.txt
> +++ b/Documentation/virtual/uml/UserModeLinux-HOWTO.txt
> @@ -2401,9 +2401,9 @@
>  
>This takes one argument, which is a single letter.  It calls the
>generic kernel's SysRq driver, which does whatever is called for by
> -  that argument.  See the SysRq documentation in Documentation/sysrq.txt
> -  in your favorite kernel tree to see what letters are valid and what
> -  they do.
> +  that argument.  See the SysRq documentation in
> +  Documentation/admin-guide/sysrq.rst in your favorite kernel tree to
> +  see what letters are valid and what they do.
>  
>  
>  



Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] Documentation: Update path to sysrq.txt

[Krzysztof Kozlowski]

Commit 9d85025b0418 ("docs-rst: create an user's manual book") moved the
sysrq.txt leaving old paths in the kernel docs.

Signed-off-by: Krzysztof Kozlowski 
---
 Documentation/media/v4l-drivers/bttv.rst  | 2 +-
 Documentation/s390/Debugging390.txt   | 2 +-
 Documentation/sysctl/kernel.txt   | 2 +-
 Documentation/virtual/uml/UserModeLinux-HOWTO.txt | 6 +++---
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/media/v4l-drivers/bttv.rst 
b/Documentation/media/v4l-drivers/bttv.rst
index bc63b12efafd..195ccaac2816 100644
--- a/Documentation/media/v4l-drivers/bttv.rst
+++ b/Documentation/media/v4l-drivers/bttv.rst
@@ -312,7 +312,7 @@ information out of a register+stack dump printed by the 
kernel on
 protection faults (so-called "kernel oops").
 
 If you run into some kind of deadlock, you can try to dump a call trace
-for each process using sysrq-t (see Documentation/sysrq.txt).
+for each process using sysrq-t (see Documentation/admin-guide/sysrq.rst).
 This way it is possible to figure where *exactly* some process in "D"
 state is stuck.
 
diff --git a/Documentation/s390/Debugging390.txt 
b/Documentation/s390/Debugging390.txt
index 3df8babcdc41..5ae7f868a007 100644
--- a/Documentation/s390/Debugging390.txt
+++ b/Documentation/s390/Debugging390.txt
@@ -2116,7 +2116,7 @@ The sysrq key reading is very picky ( I have to type the 
keys in an
 This is particularly useful for syncing disks unmounting & rebooting
 if the machine gets partially hung.
 
-Read Documentation/sysrq.txt for more info
+Read Documentation/admin-guide/sysrq.rst for more info
 
 References:
 ===
diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt
index a32b4b748644..bac23c198360 100644
--- a/Documentation/sysctl/kernel.txt
+++ b/Documentation/sysctl/kernel.txt
@@ -85,7 +85,7 @@ show up in /proc/sys/kernel:
 - softlockup_all_cpu_backtrace
 - soft_watchdog
 - stop-a  [ SPARC only ]
-- sysrq   ==> Documentation/sysrq.txt
+- sysrq   ==> Documentation/admin-guide/sysrq.rst
 - sysctl_writes_strict
 - tainted
 - threads-max
diff --git a/Documentation/virtual/uml/UserModeLinux-HOWTO.txt 
b/Documentation/virtual/uml/UserModeLinux-HOWTO.txt
index f4099ca6b483..87b80f589e1c 100644
--- a/Documentation/virtual/uml/UserModeLinux-HOWTO.txt
+++ b/Documentation/virtual/uml/UserModeLinux-HOWTO.txt
@@ -2401,9 +2401,9 @@
 
   This takes one argument, which is a single letter.  It calls the
   generic kernel's SysRq driver, which does whatever is called for by
-  that argument.  See the SysRq documentation in Documentation/sysrq.txt
-  in your favorite kernel tree to see what letters are valid and what
-  they do.
+  that argument.  See the SysRq documentation in
+  Documentation/admin-guide/sysrq.rst in your favorite kernel tree to
+  see what letters are valid and what they do.
 
 
 
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] lib/Kconfig.debug: correct documentation paths

[Krzysztof Kozlowski]

On Tue, Dec 13, 2016 at 4:40 PM, Hans Holmberg <h...@pixelmunchies.com> wrote:
> A bunch of documentation files have moved, correct the paths.
>
> Signed-off-by: Hans Holmberg <h...@pixelmunchies.com>
> ---
>  lib/Kconfig.debug | 19 ++-
>  1 file changed, 10 insertions(+), 9 deletions(-)
>

Hi Jon,

What happened with this patch? I am asking because on top of
next-20170224 I found some more sysrq.txt obsolete paths... including
the ones fixed here. I am not sure whether I am fixing something
already fixed?

Best regards,
Krzysztof

> diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
> index e6327d1..18ffa80 100644
> --- a/lib/Kconfig.debug
> +++ b/lib/Kconfig.debug
> @@ -130,7 +130,8 @@ config DYNAMIC_DEBUG
> nullarbor:~ # echo -n 'func svc_process -p' >
> 
> /dynamic_debug/control
>
> - See Documentation/dynamic-debug-howto.txt for additional 
> information.
> + See Documentation/admin-guide/dynamic-debug-howto.rst for additional
> + information.
>
>  endmenu # "printk and dmesg options"
>
> @@ -194,8 +195,8 @@ config GDB_SCRIPTS
>   build directory. If you load vmlinux into gdb, the helper
>   scripts will be automatically imported by gdb as well, and
>   additional functions are available to analyze a Linux kernel
> - instance. See Documentation/gdb-kernel-debugging.txt for further
> - details.
> + instance. See Documentation/dev-tools/gdb-kernel-debugging.rst
> + for further details.
>
>  config ENABLE_WARN_DEPRECATED
> bool "Enable __deprecated logic"
> @@ -404,8 +405,8 @@ config MAGIC_SYSRQ
>   by pressing various keys while holding SysRq (Alt+PrintScreen). It
>   also works on a serial console (on PC hardware at least), if you
>   send a BREAK and then within 5 seconds a command keypress. The
> - keys are documented in . Don't say Y
> - unless you really know what this hack does.
> + keys are documented in .
> + Don't say Y unless you really know what this hack does.
>
>  config MAGIC_SYSRQ_DEFAULT_ENABLE
> hex "Enable magic SysRq key functions by default"
> @@ -414,7 +415,7 @@ config MAGIC_SYSRQ_DEFAULT_ENABLE
> help
>   Specifies which SysRq key functions are enabled by default.
>   This may be set to 1 or 0 to enable or disable them all, or
> - to a bitmask as described in Documentation/sysrq.txt.
> + to a bitmask as described in Documentation/admin-guide/sysrq.rst.
>
>  config DEBUG_KERNEL
> bool "Kernel debugging"
> @@ -542,8 +543,8 @@ config DEBUG_KMEMLEAK
>   difference being that the orphan objects are not freed but
>   only shown in /sys/kernel/debug/kmemleak. Enabling this
>   feature will introduce an overhead to memory
> - allocations. See Documentation/kmemleak.txt for more
> - details.
> + allocations. See Documentation/dev-tools/kmemleak.rst for
> + more details.
>
>   Enabling DEBUG_SLAB or SLUB_DEBUG may increase the chances
>   of finding leaks due to the slab objects poisoning.
> @@ -739,7 +740,7 @@ config KCOV
>   different machines and across reboots. If you need stable PC values,
>   disable RANDOMIZE_BASE.
>
> - For more details, see Documentation/kcov.txt.
> + For more details, see Documentation/dev-tools/kcov.rst.
>
>  config KCOV_INSTRUMENT_ALL
> bool "Instrument all code by default"
> --
> 1.9.1
>
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 2/2] Documentation: Add arch-guide documentation

[Steve Kowalik]

Add the new SuperH interfaces RST into the documentation tree by adding
a new arch-guide.

Signed-off-by: Steve Kowalik 
---
 Documentation/00-INDEX |  2 ++
 Documentation/arch-guide/conf.py   | 10 ++
 Documentation/arch-guide/index.rst | 14 ++
 Documentation/index.rst| 11 +++
 4 files changed, 37 insertions(+)
 create mode 100644 Documentation/arch-guide/conf.py
 create mode 100644 Documentation/arch-guide/index.rst

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index c8a8eb1..64625d0 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -60,6 +60,8 @@ admin-guide/
- info related to Linux users and system admins.
 aoe/
- description of AoE (ATA over Ethernet) along with config examples.
+arch-guide/
+   - info related to architecture-specific code.
 arm/
- directory with info about Linux on the ARM architecture.
 arm64/
diff --git a/Documentation/arch-guide/conf.py b/Documentation/arch-guide/conf.py
new file mode 100644
index 000..2ac424b
--- /dev/null
+++ b/Documentation/arch-guide/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = 'Linux Kernel architecture-specific Documentation'
+
+tags.add("subproject")
+
+latex_documents = [
+('index', 'Linux Kernel architecture-specific Documentation',
+ 'The kernel development community', 'manual'),
+]
diff --git a/Documentation/arch-guide/index.rst 
b/Documentation/arch-guide/index.rst
new file mode 100644
index 000..1db4658
--- /dev/null
+++ b/Documentation/arch-guide/index.rst
@@ -0,0 +1,14 @@
+The Linux kernel architecture-specific documentation
+
+
+The following is a collection of architecture-specific documentation for the
+different architectures that the kernel supports.
+
+SuperH
+--
+
+.. toctree::
+   :maxdepth: 1
+
+   ../sh/interfaces.rst
+
diff --git a/Documentation/index.rst b/Documentation/index.rst
index f6e641a..6b3f570 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -60,6 +60,17 @@ needed).
sound/index
crypto/index
 
+Architecture-specific documentation
+---
+
+These documents get into the details of architecture-specific code or
+interfaces.
+
+.. toctree::
+   :maxdepth: 2
+
+   arch-guide/index
+
 Korean translations
 ---
 
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 0/2] convert sh interfaces to RST

[Steve Kowalik]

Convert the SuperH interfaces guide to RST, and add a new arch-guide to
place it into. I'm not hugely happy with the wording, but I've been sitting
on this long enough, and should get more eyes on it.

Steve Kowalik (2):
  Documentation: convert sh interfaces to RST
  Documentation: Add arch-guide documentation

 Documentation/00-INDEX |   2 +
 Documentation/DocBook/Makefile |   2 +-
 Documentation/DocBook/sh.tmpl  | 105 -
 Documentation/arch-guide/conf.py   |  10 
 Documentation/arch-guide/index.rst |  14 +
 Documentation/index.rst|  11 
 Documentation/sh/interfaces.rst|  63 ++
 7 files changed, 101 insertions(+), 106 deletions(-)
 delete mode 100644 Documentation/DocBook/sh.tmpl
 create mode 100644 Documentation/arch-guide/conf.py
 create mode 100644 Documentation/arch-guide/index.rst
 create mode 100644 Documentation/sh/interfaces.rst

-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/2] Documentation: convert sh interfaces to RST

[Steve Kowalik]

Convert the SuperH interfaces DocBook to RST.

Signed-off-by: Steve Kowalik 
---
 Documentation/DocBook/Makefile  |   2 +-
 Documentation/DocBook/sh.tmpl   | 105 
 Documentation/sh/interfaces.rst |  63 
 3 files changed, 64 insertions(+), 106 deletions(-)
 delete mode 100644 Documentation/DocBook/sh.tmpl
 create mode 100644 Documentation/sh/interfaces.rst

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 60a17b7..a295eb2 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -12,7 +12,7 @@ DOCBOOKS := z8530book.xml  \
kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
genericirq.xml s390-drivers.xml scsi.xml \
-   sh.xml regulator.xml w1.xml \
+   regulator.xml w1.xml \
writing_musb_glue_layer.xml
 
 ifeq ($(DOCBOOKS),)
diff --git a/Documentation/DocBook/sh.tmpl b/Documentation/DocBook/sh.tmpl
deleted file mode 100644
index 4a38f60..000
--- a/Documentation/DocBook/sh.tmpl
+++ /dev/null
@@ -1,105 +0,0 @@
-
-http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd; []>
-
-
- 
-  SuperH Interfaces Guide
-  
-  
-   
-Paul
-Mundt
-
- 
-  let...@linux-sh.org
- 
-
-   
-  
-
-  
-   2008-2010
-   Paul Mundt
-  
-  
-   2008-2010
-   Renesas Technology Corp.
-  
-  
-   2010
-   Renesas Electronics Corp.
-  
-
-  
-   
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
-   
-  
-   
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
-   
-  
-   
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
-   
-  
-   
- For more details see the file COPYING in the source
- distribution of Linux.
-   
-  
- 
-
-
-
-  
-Memory Management
-
-SH-4
-  
-Store Queue API
-!Earch/sh/kernel/cpu/sh4/sq.c
-  
-
-
-  SH-5
-  
-   TLB Interfaces
-!Iarch/sh/mm/tlb-sh5.c
-!Iarch/sh/include/asm/tlb_64.h
-  
-
-  
-  
-Machine Specific Interfaces
-
-  mach-dreamcast
-!Iarch/sh/boards/mach-dreamcast/rtc.c
-
-
-  mach-x3proto
-!Earch/sh/boards/mach-x3proto/ilsel.c
-
-  
-  
-Busses
-
-  SuperHyway
-!Edrivers/sh/superhyway/superhyway.c
-
-
-
-  Maple
-!Edrivers/sh/maple/maple.c
-
-  
-
diff --git a/Documentation/sh/interfaces.rst b/Documentation/sh/interfaces.rst
new file mode 100644
index 000..85078d4
--- /dev/null
+++ b/Documentation/sh/interfaces.rst
@@ -0,0 +1,63 @@
+.. Copyright 2008-2010 Paul Mundt
+.. Copyright 2008-2010 Renasas Technology Corp.
+.. Copyright 2010 Renasas Electronics Corp.
+
+===
+SuperH Interfaces Guide
+===
+
+:Author: Paul Mundt
+
+Memory Management
+=
+
+SH-4
+
+
+Store Queue API
+~~~
+
+.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
+   :export:
+
+SH-5
+
+
+TLB Interfaces
+~~
+
+.. kernel-doc:: arch/sh/mm/tlb-sh5.c
+   :internal:
+
+.. kernel-doc:: arch/sh/include/asm/tlb_64.h
+   :internal:
+
+Machine Specific Interfaces
+===
+
+mach-dreamcast
+--
+
+.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
+   :internal:
+
+mach-x3proto
+
+
+.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
+   :export:
+
+Busses
+==
+
+SuperHyway
+--
+
+.. kernel-doc:: drivers/sh/superhyway/superhyway.c
+   :export:
+
+Maple
+-
+
+.. kernel-doc:: drivers/sh/maple/maple.c
+   :export:
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html