Re: [PATCH v6 01/23] PCI: endpoint: Add EP core layer to enable EP controller and EP functions

[Kishon Vijay Abraham I]

Hi Bjorn,

On Wednesday 05 April 2017 10:22 PM, Bjorn Helgaas wrote:
> On Wed, Apr 05, 2017 at 02:22:21PM +0530, Kishon Vijay Abraham I wrote:
>> Introduce a new EP core layer in order to support endpoint functions in
>> linux kernel. This comprises the EPC library (Endpoint Controller Library)
>> and EPF library (Endpoint Function Library). EPC library implements
>> functions specific to an endpoint controller and EPF library implements
>> functions specific to an endpoint function.
>> ...
> 
>> +/**
>> + * pci_epf_linkup() - Notify the function driver that EPC device has
>> + *established a connection with the Root Complex.
>> + * @epf: the EPF device bound to the EPC device which has established
>> + *   the connection with the host
>> + *
>> + * Invoke to notify the function driver that EPC device has established
>> + * a connection with the Root Complex.
>> + */
>> +void pci_epf_linkup(struct pci_epf *epf)
>> +{
>> +if (!epf->driver)
>> +dev_WARN(&epf->dev, "epf device not bound to driver\n");
>> +
>> +epf->driver->ops->linkup(epf);
> 
> I don't understand what's going on here.  We warn if epf->driver is
> NULL, but the next thing we do is dereference it.
> 
> For NULL pointers that are symptoms of Linux defects, I usually prefer
> not to check at all so that a dereference generates an oops and we can
> debug the problem.  For NULL pointers caused by user error, we would
> generally return an error that percolates up to the user.
> 
> I haven't competely wrapped my head around this endpoint support, but
> I assume a NULL pointer here would be caused by user error, not
> necessarily a Linux defect.  So why would we dereference a NULL
> pointer?  And what happens when we do?  Is this just going to oops an
> embedded Linux running inside the endpoint?  Is that the correct
> behavior?

With the new configfs directory structure, this should be a kernel error.
However the EPF layer should be independent of how it's API's are used i.e
someone can create a new sysfs/configfs structure and the value of epf->driver
might be dependent on user actions.

I think I'd prefer not to dereference NULL pointers since we anyways have a
dev_WARN for debug. I'll resend this patch with return if epf->driver is NULL.

Thanks
Kishon
--
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] docs/vm/transhuge: Fix few trivial typos

[SeongJae Park]

Signed-off-by: SeongJae Park 
---
 Documentation/vm/transhuge.txt | 10 +-
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/vm/transhuge.txt b/Documentation/vm/transhuge.txt
index cd28d5ee5273..4e22578e50d3 100644
--- a/Documentation/vm/transhuge.txt
+++ b/Documentation/vm/transhuge.txt
@@ -266,7 +266,7 @@ for each mapping.
 
 The number of file transparent huge pages mapped to userspace is available
 by reading ShmemPmdMapped and ShmemHugePages fields in /proc/meminfo.
-To identify what applications are mapping file  transparent huge pages, it
+To identify what applications are mapping file transparent huge pages, it
 is necessary to read /proc/PID/smaps and count the FileHugeMapped fields
 for each mapping.
 
@@ -292,7 +292,7 @@ thp_collapse_alloc_failed is incremented if khugepaged 
found a range
the allocation.
 
 thp_file_alloc is incremented every time a file huge page is successfully
-i  allocated.
+   allocated.
 
 thp_file_mapped is incremented every time a file huge page is mapped into
user address space.
@@ -501,7 +501,7 @@ scanner can get reference to a page is 
get_page_unless_zero().
 
 All tail pages have zero ->_refcount until atomic_add(). This prevents the
 scanner from getting a reference to the tail page up to that point. After the
-atomic_add() we don't care about the ->_refcount value.  We already known how
+atomic_add() we don't care about the ->_refcount value. We already known how
 many references should be uncharged from the head page.
 
 For head page get_page_unless_zero() will succeed and we don't mind. It's
@@ -519,8 +519,8 @@ comes. Splitting will free up unused subpages.
 
 Splitting the page right away is not an option due to locking context in
 the place where we can detect partial unmap. It's also might be
-counterproductive since in many cases partial unmap unmap happens during
-exit(2) if an THP crosses VMA boundary.
+counterproductive since in many cases partial unmap happens during exit(2) if
+an THP crosses VMA boundary.
 
 Function deferred_split_huge_page() is used to queue page for splitting.
 The splitting itself will happen when we get memory pressure via shrinker
-- 
2.12.0

--
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 v6 01/23] PCI: endpoint: Add EP core layer to enable EP controller and EP functions

[Bjorn Helgaas]

On Wed, Apr 05, 2017 at 02:22:21PM +0530, Kishon Vijay Abraham I wrote:
> Introduce a new EP core layer in order to support endpoint functions in
> linux kernel. This comprises the EPC library (Endpoint Controller Library)
> and EPF library (Endpoint Function Library). EPC library implements
> functions specific to an endpoint controller and EPF library implements
> functions specific to an endpoint function.
> ...

> +/**
> + * pci_epf_linkup() - Notify the function driver that EPC device has
> + * established a connection with the Root Complex.
> + * @epf: the EPF device bound to the EPC device which has established
> + *the connection with the host
> + *
> + * Invoke to notify the function driver that EPC device has established
> + * a connection with the Root Complex.
> + */
> +void pci_epf_linkup(struct pci_epf *epf)
> +{
> + if (!epf->driver)
> + dev_WARN(&epf->dev, "epf device not bound to driver\n");
> +
> + epf->driver->ops->linkup(epf);

I don't understand what's going on here.  We warn if epf->driver is
NULL, but the next thing we do is dereference it.

For NULL pointers that are symptoms of Linux defects, I usually prefer
not to check at all so that a dereference generates an oops and we can
debug the problem.  For NULL pointers caused by user error, we would
generally return an error that percolates up to the user.

I haven't competely wrapped my head around this endpoint support, but
I assume a NULL pointer here would be caused by user error, not
necessarily a Linux defect.  So why would we dereference a NULL
pointer?  And what happens when we do?  Is this just going to oops an
embedded Linux running inside the endpoint?  Is that the correct
behavior?

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

Re: [GIT PULL] PCI: Support for configurable PCI endpoint

[Kishon Vijay Abraham I]

Hi Bjorn,

On Wednesday 05 April 2017 02:06 AM, Bjorn Helgaas wrote:
> On Mon, Mar 27, 2017 at 03:14:56PM +0530, Kishon Vijay Abraham I wrote:
>> Hi Bjorn,
>>
>> Please find the pull request for PCI endpoint support below. I've
>> also included all the history here.
> 
> I tentatively applied this to pci/host-designware with the mostly trival
> textual changes below.  If you post the series again, please include them.

Sure, I've used pci/host-designware as the base for the next revision.
> 
> I saw some acks to prior revisions, but few of them were included in this
> series.   Can you collect them up?  If there are no other substantial
> changes, I can insert them into my branch manually.

Yeah, looks like I've missed including Joao Pinto's Acked-by in some of the
patches. I'll include them in the next revision.

Thanks
Kishon
--
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

[GIT PULL] PCI: Support for configurable PCI endpoint

[Kishon Vijay Abraham I]

Hi Bjorn,

Please find the pull request for PCI endpoint support below. I've
also included all the history here.

Changes from v5:
*) remove #syscon-cells property added in v5 and used 
   of_parse_phandle_with_fixed_args
*) fix compilation error in make.cross ARCH=blackfin that was because
   pci_endpoint_test.c driver depends on COMPILE_TEST.

Changes from v4:
*) add #syscon-cells property and used of_parse_phandle_with_args
   to perform a configuration in syscon module (as suggested by
   Rob Herring)
*) Remove unnecessary white space.

Changes from v3:
*) fixed a typo and adapted to https://lkml.org/lkml/2017/3/13/562.

Changes from v2:
*) changed the configfs structure as suggested by Christoph Hellwig. With
   this change the framework creates configfs entry for EP function driver
   and EP controller. Previously these entries have to be created by the
   the user. (Haven't changed the epc core or epf core except for invoking
   configfs APIs to create entries for EP function driver and EP controller.
   That's mostly because the EP function device can still be created by
   directly invoking the epf core API without using configfs).
*) Now the user has to use configfs entry 'start' to start the link.
   This was previously done by the function driver. However in the case of
   multi function EP, the function driver shouldn't start the link.

Changes from v1:
*) The preparation patches for adding EP support is removed and is sent
   separately
*) Added device ID for DRA74x/DRA72x and used it instead of
   using "PCI_ANY_ID"
*) Added userguide for PCI endpoint test function

Major Improvements from RFC:
 *) support multi-function devices (hw supported not virtual)
 *) Access host side buffers
 *) Raise MSI interrupts
 *) Add user space program to use the host side PCI driver
 *) Adapt all other users of designware to use the new design (only
compile tested. Since I have only dra7xx boards, the new design
has only been tested in dra7xx. I'd require the help of others
to test the platforms they have access to).

This is based on
git://git.kernel.org/pub/scm/linux/kernel/git/helgaas/pci.git
pci/host-designware

Thanks
Kishon

The following changes since commit 7ea64dcf602c21b3e5062ca90111ca4459fab403:

  __end__ (2017-04-04 15:29:37 -0500)

are available in the git repository at:

  git://git.kernel.org/pub/scm/linux/kernel/git/kishon/pci-endpoint.git 
tags/pci-endpoint-for-4.12

for you to fetch changes up to a5c85ba45c9682456077d7277196e91f8ea5fd5c:

  ARM: DRA7: clockdomain: Change the CLKTRCTRL of CM_PCIE_CLKSTCTRL to SW_WKUP 
(2017-04-05 14:05:28 +0530)


pci: endpoint: for 4.12

 *) Add PCI endpoint core layer
 *) Modify designware and dra7xx driver to be configured in EP mode
 *) Add a PCI endpoint *test* function driver and corresponding host
driver

Signed-off-by: Kishon Vijay Abraham I 


Kishon Vijay Abraham I (23):
  PCI: endpoint: Add EP core layer to enable EP controller and EP functions
  Documentation: PCI: Guide to use PCI Endpoint Core Layer
  PCI: endpoint: Introduce configfs entry for configuring EP functions
  Documentation: PCI: Guide to use PCI endpoint configfs
  PCI: endpoint: Create configfs entry for EPC device and EPF driver
  Documentation: PCI: Add specification for the *PCI test* function device
  PCI: endpoint: functions: Add an EP function to test PCI
  Documentation: PCI: Add binding documentation for pci-test endpoint 
function
  PCI: dwc: designware: Add EP mode support
  dt-bindings: PCI: Add DT bindings for PCI designware EP mode
  PCI: dwc: dra7xx: Facilitate wrapper and MSI interrupts to be enabled 
independently
  PCI: dwc: dra7xx: Add EP mode support
  dt-bindings: PCI: dra7xx: Add DT bindings for PCI dra7xx EP mode
  PCI: dwc: dra7xx: Workaround for errata id i870
  dt-bindings: PCI: dra7xx: Add DT bindings to enable unaligned access
  PCI: Add device IDs for DRA74x and DRA72x
  misc: Add host side PCI driver for PCI test function device
  Documentation: misc-devices: Add Documentation for pci-endpoint-test 
driver
  tools: PCI: Add a userspace tool to test PCI endpoint
  tools: PCI: Add sample test script to invoke pcitest
  Documentation: PCI: Add userguide for PCI endpoint test function
  MAINTAINERS: Add PCI Endpoint maintainer
  ARM: DRA7: clockdomain: Change the CLKTRCTRL of CM_PCIE_CLKSTCTRL to 
SW_WKUP

 Documentation/PCI/00-INDEX|  10 +++
 Documentation/PCI/endpoint/function/binding/pci-test.txt  |  17 +
 Documentation/PCI/endpoint/pci-endpoint-cfs.txt   | 105 
++
 Documentation/PCI/endpoint/pci-endpoint.txt   | 215 

 Documentation/PCI/endpoint/pci-test-function.txt  |  66 

[PATCH v6 01/23] PCI: endpoint: Add EP core layer to enable EP controller and EP functions

[Kishon Vijay Abraham I]

Introduce a new EP core layer in order to support endpoint functions in
linux kernel. This comprises the EPC library (Endpoint Controller Library)
and EPF library (Endpoint Function Library). EPC library implements
functions specific to an endpoint controller and EPF library implements
functions specific to an endpoint function.

Signed-off-by: Kishon Vijay Abraham I 
Acked-By: Joao Pinto 
Signed-off-by: Bjorn Helgaas 
---
 drivers/Makefile|   2 +
 drivers/pci/Kconfig |   1 +
 drivers/pci/endpoint/Kconfig|  20 ++
 drivers/pci/endpoint/Makefile   |   6 +
 drivers/pci/endpoint/pci-epc-core.c | 575 
 drivers/pci/endpoint/pci-epc-mem.c  | 143 +
 drivers/pci/endpoint/pci-epf-core.c | 347 ++
 include/linux/mod_devicetable.h |  10 +
 include/linux/pci-epc.h | 142 +
 include/linux/pci-epf.h | 160 ++
 10 files changed, 1406 insertions(+)
 create mode 100644 drivers/pci/endpoint/Kconfig
 create mode 100644 drivers/pci/endpoint/Makefile
 create mode 100644 drivers/pci/endpoint/pci-epc-core.c
 create mode 100644 drivers/pci/endpoint/pci-epc-mem.c
 create mode 100644 drivers/pci/endpoint/pci-epf-core.c
 create mode 100644 include/linux/pci-epc.h
 create mode 100644 include/linux/pci-epf.h

diff --git a/drivers/Makefile b/drivers/Makefile
index 2eced9afba53..a5f8e43b2c4d 100644
--- a/drivers/Makefile
+++ b/drivers/Makefile
@@ -14,7 +14,9 @@ obj-$(CONFIG_GENERIC_PHY) += phy/
 obj-$(CONFIG_PINCTRL)  += pinctrl/
 obj-$(CONFIG_GPIOLIB)  += gpio/
 obj-y  += pwm/
+
 obj-$(CONFIG_PCI)  += pci/
+obj-$(CONFIG_PCI_ENDPOINT) += pci/endpoint/
 # PCI dwc controller drivers
 obj-y  += pci/dwc/
 
diff --git a/drivers/pci/Kconfig b/drivers/pci/Kconfig
index df141420c902..9747c1ec8c74 100644
--- a/drivers/pci/Kconfig
+++ b/drivers/pci/Kconfig
@@ -134,3 +134,4 @@ config PCI_HYPERV
 source "drivers/pci/hotplug/Kconfig"
 source "drivers/pci/dwc/Kconfig"
 source "drivers/pci/host/Kconfig"
+source "drivers/pci/endpoint/Kconfig"
diff --git a/drivers/pci/endpoint/Kconfig b/drivers/pci/endpoint/Kconfig
new file mode 100644
index ..a5442ace7077
--- /dev/null
+++ b/drivers/pci/endpoint/Kconfig
@@ -0,0 +1,20 @@
+#
+# PCI Endpoint Support
+#
+
+menu "PCI Endpoint"
+
+config PCI_ENDPOINT
+   bool "PCI Endpoint Support"
+   help
+  Enable this configuration option to support configurable PCI
+  endpoint. This should be enabled if the platform has a PCI
+  controller that can operate in endpoint mode.
+
+  Enabling this option will build the endpoint library, which
+  includes endpoint controller library and endpoint function
+  library.
+
+  If in doubt, say "N" to disable Endpoint support.
+
+endmenu
diff --git a/drivers/pci/endpoint/Makefile b/drivers/pci/endpoint/Makefile
new file mode 100644
index ..dc1bc16491e6
--- /dev/null
+++ b/drivers/pci/endpoint/Makefile
@@ -0,0 +1,6 @@
+#
+# Makefile for PCI Endpoint Support
+#
+
+obj-$(CONFIG_PCI_ENDPOINT) += pci-epc-core.o pci-epf-core.o\
+  pci-epc-mem.o
diff --git a/drivers/pci/endpoint/pci-epc-core.c 
b/drivers/pci/endpoint/pci-epc-core.c
new file mode 100644
index ..54b366ece844
--- /dev/null
+++ b/drivers/pci/endpoint/pci-epc-core.c
@@ -0,0 +1,575 @@
+/**
+ * PCI Endpoint *Controller* (EPC) library
+ *
+ * Copyright (C) 2017 Texas Instruments
+ * Author: Kishon Vijay Abraham I 
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 of
+ * the License 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, see .
+ */
+
+#include 
+#include 
+#include 
+#include 
+
+#include 
+#include 
+
+static struct class *pci_epc_class;
+
+static void devm_pci_epc_release(struct device *dev, void *res)
+{
+   struct pci_epc *epc = *(struct pci_epc **)res;
+
+   pci_epc_destroy(epc);
+}
+
+static int devm_pci_epc_match(struct device *dev, void *res, void *match_data)
+{
+   struct pci_epc **epc = res;
+
+   return *epc == match_data;
+}
+
+/**
+ * pci_epc_put() - release the PCI endpoint controller
+ * @epc: epc returned by pci_epc_get()
+ *
+ * release the refcount the caller obtained by invoking pci_epc_get()
+ */
+void pci_epc_put(struct pci_epc *epc)
+{
+   if (!epc || IS_ERR(epc))
+   return;
+
+   module_put(epc->ops->own

[PATCH v6 07/23] PCI: endpoint: functions: Add an EP function to test PCI

[Kishon Vijay Abraham I]

Adds a new endpoint function driver (to program the virtual test device)
making use of the EP-core library.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 drivers/pci/endpoint/Kconfig  |   2 +
 drivers/pci/endpoint/Makefile |   2 +-
 drivers/pci/endpoint/functions/Kconfig|  12 +
 drivers/pci/endpoint/functions/Makefile   |   5 +
 drivers/pci/endpoint/functions/pci-epf-test.c | 510 ++
 5 files changed, 530 insertions(+), 1 deletion(-)
 create mode 100644 drivers/pci/endpoint/functions/Kconfig
 create mode 100644 drivers/pci/endpoint/functions/Makefile
 create mode 100644 drivers/pci/endpoint/functions/pci-epf-test.c

diff --git a/drivers/pci/endpoint/Kconfig b/drivers/pci/endpoint/Kconfig
index c86bca9b7de3..c23f146fb5a6 100644
--- a/drivers/pci/endpoint/Kconfig
+++ b/drivers/pci/endpoint/Kconfig
@@ -26,4 +26,6 @@ config PCI_ENDPOINT_CONFIGFS
   configure the endpoint function and used to bind the
   function with a endpoint controller.
 
+source "drivers/pci/endpoint/functions/Kconfig"
+
 endmenu
diff --git a/drivers/pci/endpoint/Makefile b/drivers/pci/endpoint/Makefile
index 7219d51bb401..1041f80a4645 100644
--- a/drivers/pci/endpoint/Makefile
+++ b/drivers/pci/endpoint/Makefile
@@ -4,4 +4,4 @@
 
 obj-$(CONFIG_PCI_ENDPOINT_CONFIGFS)+= pci-ep-cfs.o
 obj-$(CONFIG_PCI_ENDPOINT) += pci-epc-core.o pci-epf-core.o\
-  pci-epc-mem.o
+  pci-epc-mem.o functions/
diff --git a/drivers/pci/endpoint/functions/Kconfig 
b/drivers/pci/endpoint/functions/Kconfig
new file mode 100644
index ..175edad42d2f
--- /dev/null
+++ b/drivers/pci/endpoint/functions/Kconfig
@@ -0,0 +1,12 @@
+#
+# PCI Endpoint Functions
+#
+
+config PCI_EPF_TEST
+   tristate "PCI Endpoint Test driver"
+   depends on PCI_ENDPOINT
+   help
+  Enable this configuration option to enable the test driver
+  for PCI Endpoint.
+
+  If in doubt, say "N" to disable Endpoint test driver.
diff --git a/drivers/pci/endpoint/functions/Makefile 
b/drivers/pci/endpoint/functions/Makefile
new file mode 100644
index ..6d94a4801838
--- /dev/null
+++ b/drivers/pci/endpoint/functions/Makefile
@@ -0,0 +1,5 @@
+#
+# Makefile for PCI Endpoint Functions
+#
+
+obj-$(CONFIG_PCI_EPF_TEST) += pci-epf-test.o
diff --git a/drivers/pci/endpoint/functions/pci-epf-test.c 
b/drivers/pci/endpoint/functions/pci-epf-test.c
new file mode 100644
index ..d6a7a12a99f7
--- /dev/null
+++ b/drivers/pci/endpoint/functions/pci-epf-test.c
@@ -0,0 +1,510 @@
+/**
+ * Test driver to test endpoint functionality
+ *
+ * Copyright (C) 2017 Texas Instruments
+ * Author: Kishon Vijay Abraham I 
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 of
+ * the License 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, see .
+ */
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include 
+#include 
+#include 
+
+#define COMMAND_RAISE_LEGACY_IRQ   BIT(0)
+#define COMMAND_RAISE_MSI_IRQ  BIT(1)
+#define MSI_NUMBER_SHIFT   2
+#define MSI_NUMBER_MASK(0x3f << MSI_NUMBER_SHIFT)
+#define COMMAND_READ   BIT(8)
+#define COMMAND_WRITE  BIT(9)
+#define COMMAND_COPY   BIT(10)
+
+#define STATUS_READ_SUCCESSBIT(0)
+#define STATUS_READ_FAIL   BIT(1)
+#define STATUS_WRITE_SUCCESS   BIT(2)
+#define STATUS_WRITE_FAIL  BIT(3)
+#define STATUS_COPY_SUCCESSBIT(4)
+#define STATUS_COPY_FAIL   BIT(5)
+#define STATUS_IRQ_RAISED  BIT(6)
+#define STATUS_SRC_ADDR_INVALIDBIT(7)
+#define STATUS_DST_ADDR_INVALIDBIT(8)
+
+#define TIMER_RESOLUTION   1
+
+static struct workqueue_struct *kpcitest_workqueue;
+
+struct pci_epf_test {
+   void*reg[6];
+   struct pci_epf  *epf;
+   struct delayed_work cmd_handler;
+};
+
+struct pci_epf_test_reg {
+   u32 magic;
+   u32 command;
+   u32 status;
+   u64 src_addr;
+   u64 dst_addr;
+   u32 size;
+   u32 checksum;
+} __packed;
+
+static struct pci_epf_header test_header = {
+   .vendorid   = PCI_ANY_ID,
+   .deviceid   = PCI_ANY_ID,
+   .baseclass_code = PCI_CLASS_OTHERS,
+   .in

[PATCH v6 06/23] Documentation: PCI: Add specification for the *PCI test* function device

[Kishon Vijay Abraham I]

Add specification for the *PCI test* virtual function device. The endpoint
function driver and the host PCI driver should be created based on this
specification.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 Documentation/PCI/00-INDEX   |  2 +
 Documentation/PCI/endpoint/pci-test-function.txt | 66 
 2 files changed, 68 insertions(+)
 create mode 100644 Documentation/PCI/endpoint/pci-test-function.txt

diff --git a/Documentation/PCI/00-INDEX b/Documentation/PCI/00-INDEX
index bf8223a1bf08..ab35e4bbdb1c 100644
--- a/Documentation/PCI/00-INDEX
+++ b/Documentation/PCI/00-INDEX
@@ -16,3 +16,5 @@ endpoint/pci-endpoint.txt
- guide to add endpoint controller driver and endpoint function driver.
 endpoint/pci-endpoint-cfs.txt
- guide to use configfs to configure the PCI endpoint function.
+endpoint/pci-test-function.txt
+   - specification of *PCI test* function device.
diff --git a/Documentation/PCI/endpoint/pci-test-function.txt 
b/Documentation/PCI/endpoint/pci-test-function.txt
new file mode 100644
index ..0c519c9bf94a
--- /dev/null
+++ b/Documentation/PCI/endpoint/pci-test-function.txt
@@ -0,0 +1,66 @@
+   PCI TEST
+   Kishon Vijay Abraham I 
+
+Traditionally PCI RC has always been validated by using standard
+PCI cards like ethernet PCI cards or USB PCI cards or SATA PCI cards.
+However with the addition of EP-core in linux kernel, it is possible
+to configure a PCI controller that can operate in EP mode to work as
+a test device.
+
+The PCI endpoint test device is a virtual device (defined in software)
+used to test the endpoint functionality and serve as a sample driver
+for other PCI endpoint devices (to use the EP framework).
+
+The PCI endpoint test device has the following registers:
+
+   1) PCI_ENDPOINT_TEST_MAGIC
+   2) PCI_ENDPOINT_TEST_COMMAND
+   3) PCI_ENDPOINT_TEST_STATUS
+   4) PCI_ENDPOINT_TEST_SRC_ADDR
+   5) PCI_ENDPOINT_TEST_DST_ADDR
+   6) PCI_ENDPOINT_TEST_SIZE
+   7) PCI_ENDPOINT_TEST_CHECKSUM
+
+*) PCI_ENDPOINT_TEST_MAGIC
+
+This register will be used to test BAR0. A known pattern will be written
+and read back from MAGIC register to verify BAR0.
+
+*) PCI_ENDPOINT_TEST_COMMAND:
+
+This register will be used by the host driver to indicate the function
+that the endpoint device must perform.
+
+Bitfield Description:
+  Bit 0: raise legacy IRQ
+  Bit 1: raise MSI IRQ
+  Bit 2 - 7: MSI interrupt number
+  Bit 8: read command (read data from RC buffer)
+  Bit 9: write command (write data to RC buffer)
+  Bit 10   : copy command (copy data from one RC buffer to another
+ RC buffer)
+
+*) PCI_ENDPOINT_TEST_STATUS
+
+This register reflects the status of the PCI endpoint device.
+
+Bitfield Description:
+  Bit 0: read success
+  Bit 1: read fail
+  Bit 2: write success
+  Bit 3: write fail
+  Bit 4: copy success
+  Bit 5: copy fail
+  Bit 6: IRQ raised
+  Bit 7: source address is invalid
+  Bit 8: destination address is invalid
+
+*) PCI_ENDPOINT_TEST_SRC_ADDR
+
+This register contains the source address (RC buffer address) for the
+COPY/READ command.
+
+*) PCI_ENDPOINT_TEST_DST_ADDR
+
+This register contains the destination address (RC buffer address) for
+the COPY/WRITE command.
-- 
2.11.0

--
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 v6 05/23] PCI: endpoint: Create configfs entry for EPC device and EPF driver

[Kishon Vijay Abraham I]

Invoke APIs provided by pci-ep-cfs to create configfs entry for every EPC
device and EPF driver to help users in creating EPF device and binding the
EPF device to the EPC device.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 drivers/pci/endpoint/pci-epc-core.c | 4 
 drivers/pci/endpoint/pci-epf-core.c | 4 
 include/linux/pci-epc.h | 2 ++
 include/linux/pci-epf.h | 2 ++
 4 files changed, 12 insertions(+)

diff --git a/drivers/pci/endpoint/pci-epc-core.c 
b/drivers/pci/endpoint/pci-epc-core.c
index 54b366ece844..9ae9e59b2a74 100644
--- a/drivers/pci/endpoint/pci-epc-core.c
+++ b/drivers/pci/endpoint/pci-epc-core.c
@@ -24,6 +24,7 @@
 
 #include 
 #include 
+#include 
 
 static struct class *pci_epc_class;
 
@@ -441,6 +442,7 @@ EXPORT_SYMBOL_GPL(pci_epc_linkup);
  */
 void pci_epc_destroy(struct pci_epc *epc)
 {
+   pci_ep_cfs_remove_epc_group(epc->group);
device_unregister(&epc->dev);
kfree(epc);
 }
@@ -507,6 +509,8 @@ __pci_epc_create(struct device *dev, const struct 
pci_epc_ops *ops,
if (ret)
goto put_dev;
 
+   epc->group = pci_ep_cfs_add_epc_group(dev_name(dev));
+
return epc;
 
 put_dev:
diff --git a/drivers/pci/endpoint/pci-epf-core.c 
b/drivers/pci/endpoint/pci-epf-core.c
index 7564a29f435c..92db7dcd911c 100644
--- a/drivers/pci/endpoint/pci-epf-core.c
+++ b/drivers/pci/endpoint/pci-epf-core.c
@@ -24,6 +24,7 @@
 
 #include 
 #include 
+#include 
 
 static struct bus_type pci_epf_bus_type;
 static struct device_type pci_epf_type;
@@ -143,6 +144,7 @@ EXPORT_SYMBOL_GPL(pci_epf_alloc_space);
  */
 void pci_epf_unregister_driver(struct pci_epf_driver *driver)
 {
+   pci_ep_cfs_remove_epf_group(driver->group);
driver_unregister(&driver->driver);
 }
 EXPORT_SYMBOL_GPL(pci_epf_unregister_driver);
@@ -172,6 +174,8 @@ int __pci_epf_register_driver(struct pci_epf_driver *driver,
if (ret)
return ret;
 
+   driver->group = pci_ep_cfs_add_epf_group(driver->driver.name);
+
return 0;
 }
 EXPORT_SYMBOL_GPL(__pci_epf_register_driver);
diff --git a/include/linux/pci-epc.h b/include/linux/pci-epc.h
index 8c63d3c37f76..af5edbf3eea3 100644
--- a/include/linux/pci-epc.h
+++ b/include/linux/pci-epc.h
@@ -77,6 +77,7 @@ struct pci_epc_mem {
  * @ops: function pointers for performing endpoint operations
  * @mem: address space of the endpoint controller
  * @max_functions: max number of functions that can be configured in this EPC
+ * @group: configfs group representing the PCI EPC device
  * @lock: spinlock to protect pci_epc ops
  */
 struct pci_epc {
@@ -85,6 +86,7 @@ struct pci_epc {
const struct pci_epc_ops*ops;
struct pci_epc_mem  *mem;
u8  max_functions;
+   struct config_group *group;
/* spinlock to protect against concurrent access of EP controller */
spinlock_t  lock;
 };
diff --git a/include/linux/pci-epf.h b/include/linux/pci-epf.h
index 5628714f7bcf..0d529cb90143 100644
--- a/include/linux/pci-epf.h
+++ b/include/linux/pci-epf.h
@@ -82,6 +82,7 @@ struct pci_epf_ops {
  * @driver: PCI EPF driver
  * @ops: set of function pointers for performing EPF operations
  * @owner: the owner of the module that registers the PCI EPF driver
+ * @group: configfs group corresponding to the PCI EPF driver
  * @id_table: identifies EPF devices for probing
  */
 struct pci_epf_driver {
@@ -91,6 +92,7 @@ struct pci_epf_driver {
struct device_driverdriver;
struct pci_epf_ops  *ops;
struct module   *owner;
+   struct config_group *group;
const struct pci_epf_device_id  *id_table;
 };
 
-- 
2.11.0

--
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 v6 02/23] Documentation: PCI: Guide to use PCI Endpoint Core Layer

[Kishon Vijay Abraham I]

Add Documentation to help users use endpoint library to enable endpoint
mode in the PCI controller and add new PCI endpoint functions.

Signed-off-by: Kishon Vijay Abraham I 
Acked-By: Joao Pinto 
Signed-off-by: Bjorn Helgaas 
---
 Documentation/PCI/00-INDEX  |   2 +
 Documentation/PCI/endpoint/pci-endpoint.txt | 215 
 2 files changed, 217 insertions(+)
 create mode 100644 Documentation/PCI/endpoint/pci-endpoint.txt

diff --git a/Documentation/PCI/00-INDEX b/Documentation/PCI/00-INDEX
index 147231f1613e..ba950b296bd8 100644
--- a/Documentation/PCI/00-INDEX
+++ b/Documentation/PCI/00-INDEX
@@ -12,3 +12,5 @@ pci.txt
- info on the PCI subsystem for device driver authors
 pcieaer-howto.txt
- the PCI Express Advanced Error Reporting Driver Guide HOWTO
+endpoint/pci-endpoint.txt
+   - guide to add endpoint controller driver and endpoint function driver.
diff --git a/Documentation/PCI/endpoint/pci-endpoint.txt 
b/Documentation/PCI/endpoint/pci-endpoint.txt
new file mode 100644
index ..9b1d66829290
--- /dev/null
+++ b/Documentation/PCI/endpoint/pci-endpoint.txt
@@ -0,0 +1,215 @@
+   PCI ENDPOINT FRAMEWORK
+   Kishon Vijay Abraham I 
+
+This document is a guide to use the PCI Endpoint Framework in order to create
+endpoint controller driver, endpoint function driver, and using configfs
+interface to bind the function driver to the controller driver.
+
+1. Introduction
+
+Linux has a comprehensive PCI subsystem to support PCI controllers that
+operates in Root Complex mode. The subsystem has capability to scan PCI bus,
+assign memory resources and IRQ resources, load PCI driver (based on
+vendor ID, device ID), support other services like hot-plug, power management,
+advanced error reporting and virtual channels.
+
+However the PCI controller IP integrated in some SoCs is capable of operating
+either in Root Complex mode or Endpoint mode. PCI Endpoint Framework will
+add endpoint mode support in Linux. This will help to run Linux in an
+EP system which can have a wide variety of use cases from testing or
+validation, co-processor accelerator, etc.
+
+2. PCI Endpoint Core
+
+The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller
+library, the Endpoint Function library, and the configfs layer to bind the
+endpoint function with the endpoint controller.
+
+2.1 PCI Endpoint Controller(EPC) Library
+
+The EPC library provides APIs to be used by the controller that can operate
+in endpoint mode. It also provides APIs to be used by function driver/library
+in order to implement a particular endpoint function.
+
+2.1.1 APIs for the PCI controller Driver
+
+This section lists the APIs that the PCI Endpoint core provides to be used
+by the PCI controller driver.
+
+*) devm_pci_epc_create()/pci_epc_create()
+
+   The PCI controller driver should implement the following ops:
+* write_header: ops to populate configuration space header
+* set_bar: ops to configure the BAR
+* clear_bar: ops to reset the BAR
+* alloc_addr_space: ops to allocate in PCI controller address space
+* free_addr_space: ops to free the allocated address space
+* raise_irq: ops to raise a legacy or MSI interrupt
+* start: ops to start the PCI link
+* stop: ops to stop the PCI link
+
+   The PCI controller driver can then create a new EPC device by invoking
+   devm_pci_epc_create()/pci_epc_create().
+
+*) devm_pci_epc_destroy()/pci_epc_destroy()
+
+   The PCI controller driver can destroy the EPC device created by either
+   devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or
+   pci_epc_destroy().
+
+*) pci_epc_linkup()
+
+   In order to notify all the function devices that the EPC device to which
+   they are linked has established a link with the host, the PCI controller
+   driver should invoke pci_epc_linkup().
+
+*) pci_epc_mem_init()
+
+   Initialize the pci_epc_mem structure used for allocating EPC addr space.
+
+*) pci_epc_mem_exit()
+
+   Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init().
+
+2.1.2 APIs for the PCI Endpoint Function Driver
+
+This section lists the APIs that the PCI Endpoint core provides to be used
+by the PCI endpoint function driver.
+
+*) pci_epc_write_header()
+
+   The PCI endpoint function driver should use pci_epc_write_header() to
+   write the standard configuration header to the endpoint controller.
+
+*) pci_epc_set_bar()
+
+   The PCI endpoint function driver should use pci_epc_set_bar() to configure
+   the Base Address Register in order for the host to assign PCI addr space.
+   Register space of the function driver is usually configured
+   using this API.
+
+*) pci_epc_clear_bar()
+
+   The PCI endpoint function driver should use pci_epc_clear_bar() to reset
+   the BAR.
+
+*) pci_epc_raise_irq()
+
+   The PCI endpoint function driver should use pci_epc_raise_irq() to raise
+ 

[PATCH v6 04/23] Documentation: PCI: Guide to use PCI endpoint configfs

[Kishon Vijay Abraham I]

Add Documentation to help users use PCI endpoint to configure PCI endpoint
function and to bind the endpoint function with endpoint controller.

Signed-off-by: Kishon Vijay Abraham I 
Acked-By: Joao Pinto 
Signed-off-by: Bjorn Helgaas 
---
 Documentation/PCI/00-INDEX  |   2 +
 Documentation/PCI/endpoint/pci-endpoint-cfs.txt | 105 
 2 files changed, 107 insertions(+)
 create mode 100644 Documentation/PCI/endpoint/pci-endpoint-cfs.txt

diff --git a/Documentation/PCI/00-INDEX b/Documentation/PCI/00-INDEX
index ba950b296bd8..bf8223a1bf08 100644
--- a/Documentation/PCI/00-INDEX
+++ b/Documentation/PCI/00-INDEX
@@ -14,3 +14,5 @@ pcieaer-howto.txt
- the PCI Express Advanced Error Reporting Driver Guide HOWTO
 endpoint/pci-endpoint.txt
- guide to add endpoint controller driver and endpoint function driver.
+endpoint/pci-endpoint-cfs.txt
+   - guide to use configfs to configure the PCI endpoint function.
diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.txt 
b/Documentation/PCI/endpoint/pci-endpoint-cfs.txt
new file mode 100644
index ..d740f29960a4
--- /dev/null
+++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.txt
@@ -0,0 +1,105 @@
+   CONFIGURING PCI ENDPOINT USING CONFIGFS
+Kishon Vijay Abraham I 
+
+The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the
+PCI endpoint function and to bind the endpoint function
+with the endpoint controller. (For introducing other mechanisms to
+configure the PCI Endpoint Function refer to [1]).
+
+*) Mounting configfs
+
+The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs
+directory. configfs can be mounted using the following command.
+
+   mount -t configfs none /sys/kernel/config
+
+*) Directory Structure
+
+The pci_ep configfs has two directories at its root: controllers and
+functions. Every EPC device present in the system will have an entry in
+the *controllers* directory and and every EPF driver present in the system
+will have an entry in the *functions* directory.
+
+/sys/kernel/config/pci_ep/
+   .. controllers/
+   .. functions/
+
+*) Creating EPF Device
+
+Every registered EPF driver will be listed in controllers directory. The
+entries corresponding to EPF driver will be created by the EPF core.
+
+/sys/kernel/config/pci_ep/functions/
+   .. /
+   ... /
+   ... /
+   .. /
+   ... /
+   ... /
+
+In order to create a  of the type probed by , the
+user has to create a directory inside .
+
+Every  directory consists of the following entries that can be
+used to configure the standard configuration header of the endpoint function.
+(These entries are created by the framework when any new  is
+created)
+
+   .. /
+   ... /
+   ... vendorid
+   ... deviceid
+   ... revid
+   ... progif_code
+   ... subclass_code
+   ... baseclass_code
+   ... cache_line_size
+   ... subsys_vendor_id
+   ... subsys_id
+   ... interrupt_pin
+
+*) EPC Device
+
+Every registered EPC device will be listed in controllers directory. The
+entries corresponding to EPC device will be created by the EPC core.
+
+/sys/kernel/config/pci_ep/controllers/
+   .. /
+   ... /
+   ... /
+   ... start
+   .. /
+   ... /
+   ... /
+   ... start
+
+The  directory will have a list of symbolic links to
+. These symbolic links should be created by the user to
+represent the functions present in the endpoint device.
+
+The  directory will also have a *start* field. Once
+"1" is written to this field, the endpoint device will be ready to
+establish the link with the host. This is usually done after
+all the EPF devices are created and linked with the EPC device.
+
+
+| controllers/
+   | /
+   | 
+   | start
+| functions/
+   | /
+   | /
+   | vendorid
+   | deviceid
+   | revid
+   | progif_code
+   | subclass_code
+   | baseclass_code
+   | cache_line_size
+   | subsys_vendor_id
+   | subsys_id
+   | interrupt_pin
+ 

[PATCH v6 11/23] PCI: dwc: dra7xx: Facilitate wrapper and MSI interrupts to be enabled independently

[Kishon Vijay Abraham I]

No functional change. Split dra7xx_pcie_enable_interrupts() into
dra7xx_pcie_enable_wrapper_interrupts() and
dra7xx_pcie_enable_msi_interrupts() so that wrapper interrupts and MSI
interrupts can be enabled independently.  This is in preparation for adding
EP mode support to dra7xx driver since EP mode doesn't have to enable
msi_interrupts.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 drivers/pci/dwc/pci-dra7xx.c | 24 ++--
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/drivers/pci/dwc/pci-dra7xx.c b/drivers/pci/dwc/pci-dra7xx.c
index 7c9ed6a6675c..d78974d20360 100644
--- a/drivers/pci/dwc/pci-dra7xx.c
+++ b/drivers/pci/dwc/pci-dra7xx.c
@@ -140,18 +140,30 @@ static int dra7xx_pcie_establish_link(struct dra7xx_pcie 
*dra7xx)
return dw_pcie_wait_for_link(pci);
 }
 
-static void dra7xx_pcie_enable_interrupts(struct dra7xx_pcie *dra7xx)
+static void dra7xx_pcie_enable_msi_interrupts(struct dra7xx_pcie *dra7xx)
 {
-   dra7xx_pcie_writel(dra7xx, PCIECTRL_DRA7XX_CONF_IRQSTATUS_MAIN,
-  ~INTERRUPTS);
-   dra7xx_pcie_writel(dra7xx,
-  PCIECTRL_DRA7XX_CONF_IRQENABLE_SET_MAIN, INTERRUPTS);
dra7xx_pcie_writel(dra7xx, PCIECTRL_DRA7XX_CONF_IRQSTATUS_MSI,
   ~LEG_EP_INTERRUPTS & ~MSI);
-   dra7xx_pcie_writel(dra7xx, PCIECTRL_DRA7XX_CONF_IRQENABLE_SET_MSI,
+
+   dra7xx_pcie_writel(dra7xx,
+  PCIECTRL_DRA7XX_CONF_IRQENABLE_SET_MSI,
   MSI | LEG_EP_INTERRUPTS);
 }
 
+static void dra7xx_pcie_enable_wrapper_interrupts(struct dra7xx_pcie *dra7xx)
+{
+   dra7xx_pcie_writel(dra7xx, PCIECTRL_DRA7XX_CONF_IRQSTATUS_MAIN,
+  ~INTERRUPTS);
+   dra7xx_pcie_writel(dra7xx, PCIECTRL_DRA7XX_CONF_IRQENABLE_SET_MAIN,
+  INTERRUPTS);
+}
+
+static void dra7xx_pcie_enable_interrupts(struct dra7xx_pcie *dra7xx)
+{
+   dra7xx_pcie_enable_wrapper_interrupts(dra7xx);
+   dra7xx_pcie_enable_msi_interrupts(dra7xx);
+}
+
 static void dra7xx_pcie_host_init(struct pcie_port *pp)
 {
struct dw_pcie *pci = to_dw_pcie_from_pp(pp);
-- 
2.11.0

--
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 v6 14/23] PCI: dwc: dra7xx: Workaround for errata id i870

[Kishon Vijay Abraham I]

According to errata i870, access to the PCIe slave port that are not 32-bit
aligned will result in incorrect mapping to TLP Address and Byte enable
fields.

Accessing non 32-bit aligned data causes incorrect data in the target
buffer if memcpy is used. Implement the workaround for this errata here.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 drivers/pci/dwc/pci-dra7xx.c | 49 
 1 file changed, 49 insertions(+)

diff --git a/drivers/pci/dwc/pci-dra7xx.c b/drivers/pci/dwc/pci-dra7xx.c
index 35c18534469c..8decf46cf525 100644
--- a/drivers/pci/dwc/pci-dra7xx.c
+++ b/drivers/pci/dwc/pci-dra7xx.c
@@ -26,6 +26,8 @@
 #include 
 #include 
 #include 
+#include 
+#include 
 
 #include "pcie-designware.h"
 
@@ -528,6 +530,48 @@ static const struct of_device_id of_dra7xx_pcie_match[] = {
{},
 };
 
+/*
+ * dra7xx_pcie_ep_unaligned_memaccess: workaround for AM572x/AM571x Errata i870
+ * @dra7xx: the dra7xx device where the workaround should be applied
+ *
+ * Access to the PCIe slave port that are not 32-bit aligned will result
+ * in incorrect mapping to TLP Address and Byte enable fields. Therefore,
+ * byte and half-word accesses are not possible to byte offset 0x1, 0x2, or
+ * 0x3.
+ *
+ * To avoid this issue set PCIE_SS1_AXI2OCP_LEGACY_MODE_ENABLE to 1.
+ */
+static int dra7xx_pcie_ep_unaligned_memaccess(struct device *dev)
+{
+   int ret;
+   struct device_node *np = dev->of_node;
+   struct of_phandle_args args;
+   struct regmap *regmap;
+
+   regmap = syscon_regmap_lookup_by_phandle(np,
+"ti,syscon-unaligned-access");
+   if (IS_ERR(regmap)) {
+   dev_dbg(dev, "can't get ti,syscon-unaligned-access\n");
+   return -EINVAL;
+   }
+
+   ret = of_parse_phandle_with_fixed_args(np, "ti,syscon-unaligned-access",
+  2, 0, &args);
+   if (ret) {
+   dev_err(dev, "failed to parse ti,syscon-unaligned-access\n");
+   return ret;
+   }
+
+   ret = regmap_update_bits(regmap, args.args[0], args.args[1],
+args.args[1]);
+   if (ret)
+   dev_err(dev, "failed to enable unaligned access\n");
+
+   of_node_put(args.np);
+
+   return ret;
+}
+
 static int __init dra7xx_pcie_probe(struct platform_device *pdev)
 {
u32 reg;
@@ -644,6 +688,11 @@ static int __init dra7xx_pcie_probe(struct platform_device 
*pdev)
case DW_PCIE_EP_TYPE:
dra7xx_pcie_writel(dra7xx, PCIECTRL_TI_CONF_DEVICE_TYPE,
   DEVICE_TYPE_EP);
+
+   ret = dra7xx_pcie_ep_unaligned_memaccess(dev);
+   if (ret)
+   goto err_gpio;
+
ret = dra7xx_add_pcie_ep(dra7xx, pdev);
if (ret < 0)
goto err_gpio;
-- 
2.11.0

--
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 v6 10/23] dt-bindings: PCI: Add DT bindings for PCI designware EP mode

[Kishon Vijay Abraham I]

Add device tree binding documentation for PCI designware EP mode.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
Acked-by: Rob Herring 
---
 .../devicetree/bindings/pci/designware-pcie.txt| 26 +++---
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/Documentation/devicetree/bindings/pci/designware-pcie.txt 
b/Documentation/devicetree/bindings/pci/designware-pcie.txt
index 1392c705ceca..b2480dd38c11 100644
--- a/Documentation/devicetree/bindings/pci/designware-pcie.txt
+++ b/Documentation/devicetree/bindings/pci/designware-pcie.txt
@@ -6,30 +6,40 @@ Required properties:
 - reg-names: Must be "config" for the PCIe configuration space.
 (The old way of getting the configuration address space from "ranges"
 is deprecated and should be avoided.)
+- num-lanes: number of lanes to use
+RC mode:
 - #address-cells: set to <3>
 - #size-cells: set to <2>
 - device_type: set to "pci"
 - ranges: ranges for the PCI memory and I/O regions
 - #interrupt-cells: set to <1>
-- interrupt-map-mask and interrupt-map: standard PCI properties
-   to define the mapping of the PCIe interface to interrupt
+- interrupt-map-mask and interrupt-map: standard PCI
+   properties to define the mapping of the PCIe interface to interrupt
numbers.
-- num-lanes: number of lanes to use
+EP mode:
+- num-ib-windows: number of inbound address translation
+windows
+- num-ob-windows: number of outbound address translation
+windows
 
 Optional properties:
-- num-viewport: number of view ports configured in hardware.  If a platform
-  does not specify it, the driver assumes 2.
 - num-lanes: number of lanes to use (this property should be specified unless
   the link is brought already up in BIOS)
 - reset-gpio: gpio pin number of power good signal
-- bus-range: PCI bus numbers covered (it is recommended for new devicetrees to
-  specify this property, to keep backwards compatibility a range of 0x00-0xff
-  is assumed if not present)
 - clocks: Must contain an entry for each entry in clock-names.
See ../clocks/clock-bindings.txt for details.
 - clock-names: Must include the following entries:
- "pcie"
- "pcie_bus"
+RC mode:
+- num-viewport: number of view ports configured in
+  hardware. If a platform does not specify it, the driver assumes 2.
+- bus-range: PCI bus numbers covered (it is recommended
+  for new devicetrees to specify this property, to keep backwards
+  compatibility a range of 0x00-0xff is assumed if not present)
+EP mode:
+- max-functions: maximum number of functions that can be
+  configured
 
 Example configuration:
 
-- 
2.11.0

--
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 v6 21/23] Documentation: PCI: Add userguide for PCI endpoint test function

[Kishon Vijay Abraham I]

Add documentation to help users use pci-epf-test function driver and
pci_endpoint_test host driver for testing PCI.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 Documentation/PCI/00-INDEX|   2 +
 Documentation/PCI/endpoint/pci-test-howto.txt | 179 ++
 2 files changed, 181 insertions(+)
 create mode 100644 Documentation/PCI/endpoint/pci-test-howto.txt

diff --git a/Documentation/PCI/00-INDEX b/Documentation/PCI/00-INDEX
index 2fc901a1c32e..00c9a90b6f38 100644
--- a/Documentation/PCI/00-INDEX
+++ b/Documentation/PCI/00-INDEX
@@ -18,5 +18,7 @@ endpoint/pci-endpoint-cfs.txt
- guide to use configfs to configure the PCI endpoint function.
 endpoint/pci-test-function.txt
- specification of *PCI test* function device.
+endpoint/pci-test-howto.txt
+   - userguide for PCI endpoint test function.
 endpoint/function/binding/
- binding documentation for PCI endpoint function
diff --git a/Documentation/PCI/endpoint/pci-test-howto.txt 
b/Documentation/PCI/endpoint/pci-test-howto.txt
new file mode 100644
index ..75f48c3bb191
--- /dev/null
+++ b/Documentation/PCI/endpoint/pci-test-howto.txt
@@ -0,0 +1,179 @@
+   PCI TEST USERGUIDE
+   Kishon Vijay Abraham I 
+
+This document is a guide to help users use pci-epf-test function driver
+and pci_endpoint_test host driver for testing PCI. The list of steps to
+be followed in the host side and EP side is given below.
+
+1. Endpoint Device
+
+1.1 Endpoint Controller Devices
+
+To find the list of endpoint controller devices in the system:
+
+   # ls /sys/class/pci_epc/
+ 5100.pcie_ep
+
+If PCI_ENDPOINT_CONFIGFS is enabled
+   # ls /sys/kernel/config/pci_ep/controllers
+ 5100.pcie_ep
+
+1.2 Endpoint Function Drivers
+
+To find the list of endpoint function drivers in the system:
+
+   # ls /sys/bus/pci-epf/drivers
+ pci_epf_test
+
+If PCI_ENDPOINT_CONFIGFS is enabled
+   # ls /sys/kernel/config/pci_ep/functions
+ pci_epf_test
+
+1.3 Creating pci-epf-test Device
+
+PCI endpoint function device can be created using the configfs. To create
+pci-epf-test device, the following commands can be used
+
+   # mount -t configfs none /sys/kernel/config
+   # cd /sys/kernel/config/pci_ep/
+   # mkdir functions/pci_epf_test/func1
+
+The "mkdir func1" above creates the pci-epf-test function device that will
+be probed by pci_epf_test driver.
+
+The PCI endpoint framework populates the directory with the following
+configurable fields.
+
+   # ls functions/pci_epf_test/func1
+ baseclass_codeinterrupt_pin   revid   subsys_vendor_id
+ cache_line_size   msi_interrupts  subclass_code   vendorid
+ deviceid  progif_code subsys_id
+
+The PCI endpoint function driver populates these entries with default values
+when the device is bound to the driver. The pci-epf-test driver populates
+vendorid with 0x and interrupt_pin with 0x0001
+
+   # cat functions/pci_epf_test/func1/vendorid
+ 0x
+   # cat functions/pci_epf_test/func1/interrupt_pin
+ 0x0001
+
+1.4 Configuring pci-epf-test Device
+
+The user can configure the pci-epf-test device using configfs entry. In order
+to change the vendorid and the number of MSI interrupts used by the function
+device, the following commands can be used.
+
+   # echo 0x104c > functions/pci_epf_test/func1/vendorid
+   # echo 0xb500 > functions/pci_epf_test/func1/deviceid
+   # echo 16 > functions/pci_epf_test/func1/msi_interrupts
+
+1.5 Binding pci-epf-test Device to EP Controller
+
+In order for the endpoint function device to be useful, it has to be bound to
+a PCI endpoint controller driver. Use the configfs to bind the function
+device to one of the controller driver present in the system.
+
+   # ln -s functions/pci_epf_test/func1 controllers/5100.pcie_ep/
+
+Once the above step is completed, the PCI endpoint is ready to establish a link
+with the host.
+
+1.6 Start the Link
+
+In order for the endpoint device to establish a link with the host, the _start_
+field should be populated with '1'.
+
+   # echo 1 > controllers/5100.pcie_ep/start
+
+2. RootComplex Device
+
+2.1 lspci Output
+
+Note that the devices listed here correspond to the value populated in 1.4 
above
+
+   00:00.0 PCI bridge: Texas Instruments Device  (rev 01)
+   01:00.0 Unassigned class [ff00]: Texas Instruments Device b500
+
+2.2 Using Endpoint Test function Device
+
+pcitest.sh added in tools/pci/ can be used to run all the default PCI endpoint
+tests. Before pcitest.sh can be used pcitest.c should be compiled using the
+following commands.
+
+   cd 
+   make headers_install ARCH=arm
+   arm-linux-gnueabihf-gcc -Iusr/include tools/pci/pcitest.c -o pcitest
+   cp pcitest  /usr/sbin/
+   cp tools/pci/pcitest.sh 
+
+2.2.1 pcitest.sh

[PATCH v6 17/23] misc: Add host side PCI driver for PCI test function device

[Kishon Vijay Abraham I]

Add PCI endpoint test driver that can verify base address register, legacy
interrupt/MSI interrupt and read/write/copy buffers between host and
device. The corresponding pci-epf-test function driver should be used on
the EP side.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 drivers/misc/Kconfig |   7 +
 drivers/misc/Makefile|   1 +
 drivers/misc/pci_endpoint_test.c | 534 +++
 include/uapi/linux/Kbuild|   1 +
 include/uapi/linux/pcitest.h |  19 ++
 5 files changed, 562 insertions(+)
 create mode 100644 drivers/misc/pci_endpoint_test.c
 create mode 100644 include/uapi/linux/pcitest.h

diff --git a/drivers/misc/Kconfig b/drivers/misc/Kconfig
index c290990d73ed..527b115c4e23 100644
--- a/drivers/misc/Kconfig
+++ b/drivers/misc/Kconfig
@@ -771,6 +771,13 @@ config PANEL_BOOT_MESSAGE
 
 endif # PANEL
 
+config PCI_ENDPOINT_TEST
+   depends on PCI
+   tristate "PCI Endpoint Test driver"
+   ---help---
+   Enable this configuration option to enable the host side test driver
+   for PCI Endpoint.
+
 source "drivers/misc/c2port/Kconfig"
 source "drivers/misc/eeprom/Kconfig"
 source "drivers/misc/cb710/Kconfig"
diff --git a/drivers/misc/Makefile b/drivers/misc/Makefile
index 7a3ea89339b4..6e139cd70421 100644
--- a/drivers/misc/Makefile
+++ b/drivers/misc/Makefile
@@ -54,6 +54,7 @@ obj-$(CONFIG_ECHO)+= echo/
 obj-$(CONFIG_VEXPRESS_SYSCFG)  += vexpress-syscfg.o
 obj-$(CONFIG_CXL_BASE) += cxl/
 obj-$(CONFIG_PANEL) += panel.o
+obj-$(CONFIG_PCI_ENDPOINT_TEST)+= pci_endpoint_test.o
 
 lkdtm-$(CONFIG_LKDTM)  += lkdtm_core.o
 lkdtm-$(CONFIG_LKDTM)  += lkdtm_bugs.o
diff --git a/drivers/misc/pci_endpoint_test.c b/drivers/misc/pci_endpoint_test.c
new file mode 100644
index ..09c10f426b64
--- /dev/null
+++ b/drivers/misc/pci_endpoint_test.c
@@ -0,0 +1,534 @@
+/**
+ * Host side test driver to test endpoint functionality
+ *
+ * Copyright (C) 2017 Texas Instruments
+ * Author: Kishon Vijay Abraham I 
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 of
+ * the License 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, see .
+ */
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include 
+
+#include 
+
+#define DRV_MODULE_NAME"pci-endpoint-test"
+
+#define PCI_ENDPOINT_TEST_MAGIC0x0
+
+#define PCI_ENDPOINT_TEST_COMMAND  0x4
+#define COMMAND_RAISE_LEGACY_IRQ   BIT(0)
+#define COMMAND_RAISE_MSI_IRQ  BIT(1)
+#define MSI_NUMBER_SHIFT   2
+/* 6 bits for MSI number */
+#define COMMAND_READBIT(8)
+#define COMMAND_WRITE   BIT(9)
+#define COMMAND_COPYBIT(10)
+
+#define PCI_ENDPOINT_TEST_STATUS   0x8
+#define STATUS_READ_SUCCESS BIT(0)
+#define STATUS_READ_FAILBIT(1)
+#define STATUS_WRITE_SUCCESSBIT(2)
+#define STATUS_WRITE_FAIL   BIT(3)
+#define STATUS_COPY_SUCCESS BIT(4)
+#define STATUS_COPY_FAILBIT(5)
+#define STATUS_IRQ_RAISED   BIT(6)
+#define STATUS_SRC_ADDR_INVALID BIT(7)
+#define STATUS_DST_ADDR_INVALID BIT(8)
+
+#define PCI_ENDPOINT_TEST_LOWER_SRC_ADDR   0xc
+#define PCI_ENDPOINT_TEST_UPPER_SRC_ADDR   0x10
+
+#define PCI_ENDPOINT_TEST_LOWER_DST_ADDR   0x14
+#define PCI_ENDPOINT_TEST_UPPER_DST_ADDR   0x18
+
+#define PCI_ENDPOINT_TEST_SIZE 0x1c
+#define PCI_ENDPOINT_TEST_CHECKSUM 0x20
+
+static DEFINE_IDA(pci_endpoint_test_ida);
+
+#define to_endpoint_test(priv) container_of((priv), struct pci_endpoint_test, \
+   miscdev)
+enum pci_barno {
+   BAR_0,
+   BAR_1,
+   BAR_2,
+   BAR_3,
+   BAR_4,
+   BAR_5,
+};
+
+struct pci_endpoint_test {
+   struct pci_dev  *pdev;
+   void __iomem*base;
+   void __iomem*bar[6];
+   struct completion irq_raised;
+   int last_irq;
+   /* mutex to protect the ioctls */
+   struct mutexmutex;
+   struct miscdevice miscdev;
+};
+
+static int bar_size[] = { 4, 512, 1024, 16384, 131072, 1048576 };
+
+static inline u32 pci_endpoint_test_readl(struct pci_endpoint_test *test,
+ u32 offset)
+{
+   return readl(test->base + of

[PATCH v6 16/23] PCI: Add device IDs for DRA74x and DRA72x

[Kishon Vijay Abraham I]

Add device IDs for DRA74x and DRA72x devices. These devices have
configurable PCI endpoint.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 include/linux/pci_ids.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/linux/pci_ids.h b/include/linux/pci_ids.h
index a4f77feecbb0..5f6b71d15393 100644
--- a/include/linux/pci_ids.h
+++ b/include/linux/pci_ids.h
@@ -862,6 +862,8 @@
 #define PCI_DEVICE_ID_TI_X620  0xac8d
 #define PCI_DEVICE_ID_TI_X420  0xac8e
 #define PCI_DEVICE_ID_TI_XX20_FM   0xac8f
+#define PCI_DEVICE_ID_TI_DRA74x0xb500
+#define PCI_DEVICE_ID_TI_DRA72x0xb501
 
 #define PCI_VENDOR_ID_SONY 0x104d
 
-- 
2.11.0

--
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

[RFC PATCH 2/2] drivers: pwm: pwm-atmel: implement pwm dead-time

[Claudiu Beznea]

Implement PWM dead-times for atmel PWM controllers.
Since this driver is used by PWM controllers which
supports dead-times and PWM controllers which doesn't,
add specific input for dead-time register in atmel
register private data structure.

Signed-off-by: Claudiu Beznea 
---
 drivers/pwm/pwm-atmel.c | 56 +
 1 file changed, 52 insertions(+), 4 deletions(-)

diff --git a/drivers/pwm/pwm-atmel.c b/drivers/pwm/pwm-atmel.c
index 530d7dc..0e69319 100644
--- a/drivers/pwm/pwm-atmel.c
+++ b/drivers/pwm/pwm-atmel.c
@@ -33,8 +33,9 @@
 
 #define PWM_CMR0x0
 /* Bit field in CMR */
-#define PWM_CMR_CPOL   (1 << 9)
-#define PWM_CMR_UPD_CDTY   (1 << 10)
+#define PWM_CMR_CPOL   BIT(9)
+#define PWM_CMR_UPD_CDTY   BIT(10)
+#define PWM_CMR_DTEBIT(16)
 #define PWM_CMR_CPRE_MSK   0xF
 
 /* The following registers for PWM v1 */
@@ -47,6 +48,7 @@
 #define PWMV2_CDTYUPD  0x08
 #define PWMV2_CPRD 0x0C
 #define PWMV2_CPRDUPD  0x10
+#define PWMV2_DT   0x18
 
 /*
  * Max value for duty and period
@@ -63,6 +65,7 @@ struct atmel_pwm_registers {
u8 period_upd;
u8 duty;
u8 duty_upd;
+   u8 dt;
 };
 
 struct atmel_pwm_chip {
@@ -161,6 +164,32 @@ static void atmel_pwm_update_cdty(struct pwm_chip *chip, 
struct pwm_device *pwm,
atmel_pwm->regs->duty_upd, cdty);
 }
 
+static int atmel_pwm_calculate_deadtime(struct pwm_chip *chip,
+   struct pwm_state *state,
+   unsigned long cprd, unsigned long *dt)
+{
+   unsigned long long cycles;
+
+   if (state->deadtime_fe > state->duty_cycle ||
+   state->deadtime_re > state->period - state->duty_cycle)
+   return -EINVAL;
+
+   *dt = 0;
+   if (state->deadtime_fe) {
+   cycles = (unsigned long long)state->deadtime_fe * cprd;
+   do_div(cycles, state->period);
+   *dt = (cycles << 16);
+   }
+
+   if (state->deadtime_re) {
+   cycles = (unsigned long long)state->deadtime_re * cprd;
+   do_div(cycles, state->period);
+   *dt |= cycles;
+   }
+
+   return 0;
+}
+
 static void atmel_pwm_set_cprd_cdty(struct pwm_chip *chip,
struct pwm_device *pwm,
unsigned long cprd, unsigned long cdty)
@@ -214,7 +243,7 @@ static int atmel_pwm_apply(struct pwm_chip *chip, struct 
pwm_device *pwm,
 {
struct atmel_pwm_chip *atmel_pwm = to_atmel_pwm_chip(chip);
struct pwm_state cstate;
-   unsigned long cprd, cdty;
+   unsigned long cprd, cdty, dt;
u32 pres, val;
int ret;
 
@@ -223,7 +252,9 @@ static int atmel_pwm_apply(struct pwm_chip *chip, struct 
pwm_device *pwm,
if (state->enabled) {
if (cstate.enabled &&
cstate.polarity == state->polarity &&
-   cstate.period == state->period) {
+   cstate.period == state->period &&
+   cstate.deadtime_re == state->deadtime_re &&
+   cstate.deadtime_fe == state->deadtime_fe) {
cprd = atmel_pwm_ch_readl(atmel_pwm, pwm->hwpwm,
  atmel_pwm->regs->period);
atmel_pwm_calculate_cdty(state, cprd, &cdty);
@@ -239,6 +270,12 @@ static int atmel_pwm_apply(struct pwm_chip *chip, struct 
pwm_device *pwm,
return ret;
}
 
+   ret = atmel_pwm_calculate_deadtime(chip, state, cprd, &dt);
+   if (ret) {
+   dev_err(chip->dev, "failed to calculate dead-time\n");
+   return ret;
+   }
+
atmel_pwm_calculate_cdty(state, cprd, &cdty);
 
if (cstate.enabled) {
@@ -258,8 +295,17 @@ static int atmel_pwm_apply(struct pwm_chip *chip, struct 
pwm_device *pwm,
val &= ~PWM_CMR_CPOL;
else
val |= PWM_CMR_CPOL;
+
+   if (dt)
+   val |= PWM_CMR_DTE;
+   else
+   val &= ~PWM_CMR_DTE;
+
atmel_pwm_ch_writel(atmel_pwm, pwm->hwpwm, PWM_CMR, val);
atmel_pwm_set_cprd_cdty(chip, pwm, cprd, cdty);
+   if (atmel_pwm->regs->dt)
+   atmel_pwm_ch_writel(atmel_pwm, pwm->hwpwm,
+   atmel_pwm->regs->dt, dt);
mutex_lock(&atmel_pwm->isr_lock);
atmel_pwm->updated_pwms |= atmel_pwm_readl(atmel_pwm, PWM_ISR);
atmel_pwm->updated_pwms &= ~(1 << pwm->hwpwm);
@@ -282,6 +328,7 @@ static const struct atmel_pwm_registers atmel_pwm_regs_v1 = 
{
.period_upd = PWMV1_CUPD,
.duty   = PWMV1_CDTY,
   

[RFC PATCH 0/2] extend PWM framework to support PWM modes

[Claudiu Beznea]

Hi all,

Please give feedback on these patches which extends the PWM
framework in order to support multiple PWM signal types.
The current patch series recognize the following PWM
signal types:
- PWM complementary signals
- PWM push-pull signal
These output signals could be configured by setting PWM mode
(a new input in sysfs has been added in order to support this
operation).

root@sama5d2-xplained:/sys/devices/platform/ahb/ahb:apb/f802c000.pwm/pwm/pwmchip0/pwm2#
 ls -l
-r--r--r--1 root root  4096 Feb  9 10:54 capture
-rw-r--r--1 root root  4096 Feb  9 10:54 duty_cycle
-rw-r--r--1 root root  4096 Feb  9 10:54 enable
-rw-r--r--1 root root  4096 Feb  9 10:54 mode
-rw-r--r--1 root root  4096 Feb  9 10:54 period
-rw-r--r--1 root root  4096 Feb  9 10:55 polarity
drwxr-xr-x2 root root 0 Feb  9 10:54 power
-rw-r--r--1 root root  4096 Feb  9 10:54 uevent

Definition of PWM complementary mode:
For a PWM controllers with more than one outputs per PWM channel,
e.g. with 2 outputs per PWM channels, the PWM complementary signals
have opposite levels, same duration and same starting times,
as in the following diagram:

________
PWMH __|  |__|  |__|  |__|  |__
 __________
PWML   |__|  |__|  |__|  |__|
   <--T-->
Where T is the signal period.

Definition of PWM push-pull mode:
For PWM controllers with more than one outputs per PWM channel,
e.g. with 2 outputs per PWM channel, the PWM push-pull signals
have same levels, same duration and are delayed until the begining
of the next period, as in the following diagram:

__  __
PWMH __|  ||  |
  __  __
PWML |  ||  |__
   <--T-->

Where T is the signal period.

The PWM push-pull mode could be usefull in applications like
half bridge converters.

This series add support for PWM modes on atmel SAMA5D2 SoC.

Please consider that this series was build on top following
patch series:
[PATCH v3 0/2] switch to atomic PWM
[PATCH v3 1/2] drivers: pwm: pwm-atmel: switch to atomic PWM
[PATCH v3 2/2] drivers: pwm: pwm-atmel: enable PWM on sama5d2

This patch series is not dependent on the other patch series
I've made for extending PWM framework with PWM dead-times:
[RFC PATCH 0/2] extends PWM framework to support PWM dead-times
[RFC PATCH 1/2] drivers: pwm: core: implement pwm dead-times
[RFC PATCH 2/2] drivers: pwm: pwm-atmel: implement pwm dead-time
but, if you consider relevant, and both patch changes are considered
relevant for PWM subsistem, I can combine both of them, if any.

Thanks you,
Claudiu Beznea

Claudiu Beznea (2):
  drivers: pwm: core: implement pwm mode
  drivers: pwm: pwm-atmel: add support for pwm modes

 drivers/pwm/core.c| 13 +-
 drivers/pwm/pwm-atmel.c   | 94 +--
 drivers/pwm/sysfs.c   | 52 
 include/dt-bindings/pwm/pwm.h |  1 +
 include/linux/pwm.h   | 37 -
 5 files changed, 162 insertions(+), 35 deletions(-)

-- 
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

[RFC PATCH 0/2] extends PWM framework to support PWM dead-times

[Claudiu Beznea]

Hi all,

Please give feedback on these patches which extends PWM framework
in order to support PWM dead-times.

For a PWM controller with more than one output signals per PWM channel
dead-times are the delays introduced between the edges of the output
signals and the original signal introduced in dead-time generator
engine.
E.g. consider a PWM controller with with the following diagram:

-
   | |---> PWMH
PWM signal --->| Dead-time engine|
   | |---> PWML
-

With no dead-time configured, the PWMH and PWML signals will be
complementary signals (rising and falling edges of PWMH and PWML
have opposite leves, same duration and same starting time) as
follows:

  0DP     
PWM signal __||||||||||___
          
  PWMH __||||||||||___
   __          ___
  PWML   ||||||||||

Where - 0 is the starting point of the signal
  - D is the starting point of the duty-cycle
  - P is the signal period

Based on the above diagram:
- rising edge dead-time - is the delay introduced in one of the
dead-time engine output signal; the delay is introduced after
rising edge of PWM signal
- falling edge dead-time - is the delay introduced in one of the
dead-time engine output signal; the delay is introduced after
the end of falling edge of the PWM signal
The following diagram explain how PWM dead-times falls on some signals:

  0DP     
PWM signal __||||||||||___
__________
  PWMH |  |re|  |__|  |__|  |__|  |___
   ____________
  PWML   |__|  |fe|  |__|  |__|  |__|

In the upper diagram:
- re = rising edge = the delay between D point of PWM signal
(rising edge) and the starting point of the next edge
- fe = falling edge = the delay between P point of PWM signal
(falling edge) and the starting point of the next edge

To configure the PWM dead-times new inputs were added to sysfs,
in PWM subsystem, one for rising edge dead-time, one for falling
edge deadtime.

root@sama5d2-xplained:/sys/devices/platform/ahb/ahb:apb/f802c000.pwm/pwm/pwmchip0/pwm2#
 ls -l
-r--r--r--1 root root  4096 Feb 10 10:00 capture
-rw-r--r--1 root root  4096 Feb 10 10:01 deadtime_fe
-rw-r--r--1 root root  4096 Feb 10 10:02 deadtime_re
-rw-r--r--1 root root  4096 Feb 10 10:00 duty_cycle
-rw-r--r--1 root root  4096 Feb 10 10:00 enable
-rw-r--r--1 root root  4096 Feb 10 10:00 period
-rw-r--r--1 root root  4096 Feb 10 10:00 polarity
drwxr-xr-x2 root root 0 Feb 10 10:00 power
-rw-r--r--1 root root  4096 Feb 10 10:00 uevent

The PWM dead-times are used in half bridge converters applications.

Please consider that this series was build on top of following
patch series:
[PATCH v3 0/2] switch to atomic PWM
[PATCH v3 1/2] drivers: pwm: pwm-atmel: switch to atomic PWM
[PATCH v3 2/2] drivers: pwm: pwm-atmel: enable PWM on sama5d2

This patch series is not dependent on the other patch series
I've made for extending PWM framework with PWM mode:
[RFC PATCH 0/2] extend PWM framework to support PWM modes
[RFC PATCH 1/2] drivers: pwm: core: implement pwm mode
[RFC PATCH 2/2] drivers: pwm: pwm-atmel: add support for pwm modes
but, if you consider relevant, and both patch changes are considered
relevant for PWM subsistem, I can combine both of them, if any.

Thanks you,
Claudiu Beznea

Claudiu Beznea (2):
  drivers: pwm: core: implement pwm dead-times
  drivers: pwm: pwm-atmel: implement pwm dead-time

 Documentation/pwm.txt   | 52 ++
 drivers/pwm/core.c  | 10 ++-
 drivers/pwm/pwm-atmel.c | 56 ++---
 drivers/pwm/sysfs.c | 74 +
 include/linux/pwm.h | 36 
 5 files changed, 223 insertions(+), 5 deletions(-)

-- 
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

[RFC PATCH 2/2] drivers: pwm: pwm-atmel: add support for pwm modes

[Claudiu Beznea]

Implement pwm modes by adding PWM controller specific
configuration. Since this driver is used by controllers
which supports PWM push-pull mode and controllers which
doesn't, a new field was added in driver private data
structure. Also, the driver private data structure was
changed to adapt the new feature.

Signed-off-by: Claudiu Beznea 
---
 drivers/pwm/pwm-atmel.c | 94 +
 1 file changed, 63 insertions(+), 31 deletions(-)

diff --git a/drivers/pwm/pwm-atmel.c b/drivers/pwm/pwm-atmel.c
index 530d7dc..9e812ce 100644
--- a/drivers/pwm/pwm-atmel.c
+++ b/drivers/pwm/pwm-atmel.c
@@ -33,8 +33,11 @@
 
 #define PWM_CMR0x0
 /* Bit field in CMR */
-#define PWM_CMR_CPOL   (1 << 9)
-#define PWM_CMR_UPD_CDTY   (1 << 10)
+#define PWM_CMR_CPOL   BIT(9)
+#define PWM_CMR_UPD_CDTY   BIT(10)
+#define PWM_CMR_DTHI   BIT(17)
+#define PWM_CMR_DTLI   BIT(18)
+#define PWM_CMR_PPMBIT(19)
 #define PWM_CMR_CPRE_MSK   0xF
 
 /* The following registers for PWM v1 */
@@ -65,11 +68,16 @@ struct atmel_pwm_registers {
u8 duty_upd;
 };
 
+struct atmel_pwm_data {
+   struct atmel_pwm_registers regs;
+   bool ppm_supported;
+};
+
 struct atmel_pwm_chip {
struct pwm_chip chip;
struct clk *clk;
void __iomem *base;
-   const struct atmel_pwm_registers *regs;
+   const struct atmel_pwm_data *data;
 
unsigned int updated_pwms;
/* ISR is cleared when read, ensure only one thread does that */
@@ -150,15 +158,15 @@ static void atmel_pwm_update_cdty(struct pwm_chip *chip, 
struct pwm_device *pwm,
struct atmel_pwm_chip *atmel_pwm = to_atmel_pwm_chip(chip);
u32 val;
 
-   if (atmel_pwm->regs->duty_upd ==
-   atmel_pwm->regs->period_upd) {
+   if (atmel_pwm->data->regs.duty_upd ==
+   atmel_pwm->data->regs.period_upd) {
val = atmel_pwm_ch_readl(atmel_pwm, pwm->hwpwm, PWM_CMR);
val &= ~PWM_CMR_UPD_CDTY;
atmel_pwm_ch_writel(atmel_pwm, pwm->hwpwm, PWM_CMR, val);
}
 
atmel_pwm_ch_writel(atmel_pwm, pwm->hwpwm,
-   atmel_pwm->regs->duty_upd, cdty);
+   atmel_pwm->data->regs.duty_upd, cdty);
 }
 
 static void atmel_pwm_set_cprd_cdty(struct pwm_chip *chip,
@@ -168,9 +176,9 @@ static void atmel_pwm_set_cprd_cdty(struct pwm_chip *chip,
struct atmel_pwm_chip *atmel_pwm = to_atmel_pwm_chip(chip);
 
atmel_pwm_ch_writel(atmel_pwm, pwm->hwpwm,
-   atmel_pwm->regs->duty, cdty);
+   atmel_pwm->data->regs.duty, cdty);
atmel_pwm_ch_writel(atmel_pwm, pwm->hwpwm,
-   atmel_pwm->regs->period, cprd);
+   atmel_pwm->data->regs.period, cprd);
 }
 
 static void atmel_pwm_disable(struct pwm_chip *chip, struct pwm_device *pwm,
@@ -223,9 +231,10 @@ static int atmel_pwm_apply(struct pwm_chip *chip, struct 
pwm_device *pwm,
if (state->enabled) {
if (cstate.enabled &&
cstate.polarity == state->polarity &&
-   cstate.period == state->period) {
+   cstate.period == state->period &&
+   cstate.mode == state->mode) {
cprd = atmel_pwm_ch_readl(atmel_pwm, pwm->hwpwm,
- atmel_pwm->regs->period);
+ atmel_pwm->data->regs.period);
atmel_pwm_calculate_cdty(state, cprd, &cdty);
atmel_pwm_update_cdty(chip, pwm, cdty);
return 0;
@@ -258,6 +267,23 @@ static int atmel_pwm_apply(struct pwm_chip *chip, struct 
pwm_device *pwm,
val &= ~PWM_CMR_CPOL;
else
val |= PWM_CMR_CPOL;
+
+   /* PWM mode. */
+   if (atmel_pwm->data->ppm_supported) {
+   if (state->mode == PWM_MODE_PUSH_PULL) {
+   val |= PWM_CMR_PPM;
+   if (state->polarity == PWM_POLARITY_NORMAL)
+   val = (val & ~PWM_CMR_DTHI) |
+ PWM_CMR_DTLI;
+   else
+   val = (val & ~PWM_CMR_DTLI) |
+ PWM_CMR_DTHI;
+   } else {
+   val &= ~(PWM_CMR_PPM | PWM_CMR_DTLI |
+PWM_CMR_DTHI);
+   }
+   }
+
atmel_pwm_ch_writel(atmel_pwm, pwm->hwpwm, PWM_CMR, val);
atmel_pwm_set_cprd_cdty(chip, pwm, cprd, cdty);
mutex_lock(&atmel_pwm->isr_lock);
@@ -277,27 +303,33 @@ static const struct pwm_ops atmel_pwm_ops = {
.own

[RFC PATCH 1/2] drivers: pwm: core: implement pwm dead-times

[Claudiu Beznea]

Extends PWM framework to support PWM dead-times.
The notions introduced are rising edge dead-time
and falling edge dead-time. These are useful for
PWM controllers with cannels that have more than
one outputs.
The implementation add sysfs interface for
configuration. It extends the pwm_state structure
with two new members which keeps the values for
dead-times.
There was no additions in device tree for PWM channels
with inputs there.

Signed-off-by: Claudiu Beznea 
---
 Documentation/pwm.txt | 52 
 drivers/pwm/core.c| 10 ++-
 drivers/pwm/sysfs.c   | 74 +++
 include/linux/pwm.h   | 36 +
 4 files changed, 171 insertions(+), 1 deletion(-)

diff --git a/Documentation/pwm.txt b/Documentation/pwm.txt
index 789b27c..1dc530b 100644
--- a/Documentation/pwm.txt
+++ b/Documentation/pwm.txt
@@ -100,6 +100,58 @@ enable - Enable/disable the PWM signal (read/write).
0 - disabled
1 - enabled
 
+deadtime_re -The rising edge dead-time
+deadtime_fe - the falling edge dead-time
+   For a PWM controller with more than one output signals per PWM channel
+   dead-times are the delays introduced between the edges of the output
+   signals and the original signal introduced in dead-time generator
+   engine.
+   E.g. consider a PWM controller with with the following diagram:
+
+-
+   | |---> PWMH
+PWM signal --->| Dead-time engine|
+   | |---> PWML
+-
+
+   With no dead-time configured, the PWMH and PWML signals will be
+   complementary signals (rising and falling edges of PWMH and PWML
+   have opposite leves, same duration and same starting time) as
+   follows:
+
+  0DP     
+PWM signal __||||||||||___
+          
+  PWMH __||||||||||___
+   __          ___
+  PWML   ||||||||||
+   
+   Where - 0 is the starting point of the signal
+ - D is the starting point of the duty-cycle
+ - P is the signal period
+
+   Based on the above diagram:
+   - rising edge dead-time - is the delay introduced in one of the
+   dead-time engine output signal; the delay is introduced after
+   rising edge of PWM signal
+   - falling edge dead-time - is the delay introduced in one of the
+   dead-time engine output signal; the delay is introduced after
+   the end of falling edge of the PWM signal
+   See the following diagram:
+
+  0DP     
+PWM signal __||||||||||___
+__________
+  PWMH |  |re|  |__|  |__|  |__|  |___
+   ____________
+  PWML   |__|  |fe|  |__|  |__|  |__|
+
+   In the upper diagram:
+   - re = rising edge = the delay between D point of PWM signal
+   (rising edge) and the starting point of the next edge
+   - fe = falling edge = the delay between P point of PWM signal
+   (falling edge) and the starting point of the next edge
+
 Implementing a PWM driver
 -
 
diff --git a/drivers/pwm/core.c b/drivers/pwm/core.c
index a0860b3..c1a9828 100644
--- a/drivers/pwm/core.c
+++ b/drivers/pwm/core.c
@@ -469,7 +469,8 @@ int pwm_apply_state(struct pwm_device *pwm, struct 
pwm_state *state)
int err;
 
if (!pwm || !state || !state->period ||
-   state->duty_cycle > state->period)
+   state->duty_cycle > state->period ||
+   state->deadtime_re + state->deadtime_fe > state->period)
return -EINVAL;
 
if (!memcmp(state, &pwm->state, sizeof(*state)))
@@ -579,6 +580,9 @@ int pwm_adjust_config(struct pwm_device *pwm)
pwm_get_args(pwm, &pargs);
pwm_get_state(pwm, &state);
 
+   state.deadtime_re = 0;
+   state.deadtime_fe = 0;
+
/*
 * If the current period is zero it means that either the PWM driver
 * does not support initial state retrieval or the PWM has not yet
@@ -997,6 +1001,10 @@ static void pwm_dbg_show(struct pwm_chip *chip, struct 
seq_file *s)
seq_printf(s, " duty: %u ns", state.duty_cycle);
seq_printf(s, " polarity: %s",
   state.polarity ? "inverse" : "normal");
+   seq_printf(s, " dead-time rising edge: %u ns",
+  state.deadtime_re);
+

[RFC PATCH 1/2] drivers: pwm: core: implement pwm mode

[Claudiu Beznea]

Extends PWM framework to support PWM modes. The currently
implemented PWM modes were called PWM complementary mode
and PWM push-pull mode. For devices that have more than one
output per PWM channel:
- PWM complementary mode is standard working mode; in PWM
complementary mode the rising and falling edges of the
channels outputs have opposite levels, same duration and
same starting time.
- in PWM push-pull mode the channles outputs has same levels,
same duration and the rising edges are delayed until the
beginning of the next period.
A new member was added in pwm_state structure in order to
keep the new PWM argument.
For PWM channels with inputs in DT, the mode could also be
passed via DT. No new extra field need to be added in device
tree; since the signal polarity is passed as a flag via DT,
the filed used to pass information for PWM channel polarity
via DT is also used by PWM mode. Since, for the moment, only
the complementary and push-pull modes are implemented, only
one bit in flags used to pass polarity could also be used for
PWM mode. The other drivers are not affected by this change.

Signed-off-by: Claudiu Beznea 
---
 Documentation/pwm.txt | 24 +---
 drivers/pwm/core.c| 13 +--
 drivers/pwm/sysfs.c   | 52 +++
 include/dt-bindings/pwm/pwm.h |  1 +
 include/linux/pwm.h   | 37 --
 5 files changed, 120 insertions(+), 7 deletions(-)

diff --git a/Documentation/pwm.txt b/Documentation/pwm.txt
index 789b27c..1b6fc59 100644
--- a/Documentation/pwm.txt
+++ b/Documentation/pwm.txt
@@ -59,9 +59,9 @@ In addition to the PWM state, the PWM API also exposes PWM 
arguments, which
 are the reference PWM config one should use on this PWM.
 PWM arguments are usually platform-specific and allows the PWM user to only
 care about dutycycle relatively to the full period (like, duty = 50% of the
-period). struct pwm_args contains 2 fields (period and polarity) and should
-be used to set the initial PWM config (usually done in the probe function
-of the PWM user). PWM arguments are retrieved with pwm_get_args().
+period). struct pwm_args contains 3 fields (period, polarity and mode) and
+should be used to set the initial PWM config (usually done in the probe
+function of the PWM user). PWM arguments are retrieved with pwm_get_args().
 
 Using PWMs with the sysfs interface
 ---
@@ -100,6 +100,24 @@ enable - Enable/disable the PWM signal (read/write).
0 - disabled
1 - enabled
 
+mode - Set PWM signal type (for channels with more than one output
+   per channel)
+   complementary - for an output signal as follow:
+________
+PWMH __|  |__|  |__|  |__|  |__
+ __________
+PWML   |__|  |__|  |__|  |__|
+   <--T-->
+   Where T is the signal period.
+
+   push-pull - for an output signal as follows:
+__  __
+PWMH __|  ||  |
+  __  __
+PWML |  ||  |__
+   <--T-->
+   Where T is the signal period.
+
 Implementing a PWM driver
 -
 
diff --git a/drivers/pwm/core.c b/drivers/pwm/core.c
index a0860b3..4efc92d 100644
--- a/drivers/pwm/core.c
+++ b/drivers/pwm/core.c
@@ -154,9 +154,14 @@ of_pwm_xlate_with_flags(struct pwm_chip *pc, const struct 
of_phandle_args *args)
 
pwm->args.period = args->args[1];
pwm->args.polarity = PWM_POLARITY_NORMAL;
+   pwm->args.mode = PWM_MODE_COMPLEMENTARY;
 
-   if (args->args_count > 2 && args->args[2] & PWM_POLARITY_INVERTED)
-   pwm->args.polarity = PWM_POLARITY_INVERSED;
+   if (args->args_count > 2) {
+   if (args->args[2] & PWM_POLARITY_INVERTED)
+   pwm->args.polarity = PWM_POLARITY_INVERSED;
+   if (args->args[2] & PWM_MODE_PUSHPULL)
+   pwm->args.mode = PWM_MODE_PUSH_PULL;
+   }
 
return pwm;
 }
@@ -579,6 +584,8 @@ int pwm_adjust_config(struct pwm_device *pwm)
pwm_get_args(pwm, &pargs);
pwm_get_state(pwm, &state);
 
+   state.mode = pargs.mode;
+
/*
 * If the current period is zero it means that either the PWM driver
 * does not support initial state retrieval or the PWM has not yet
@@ -997,6 +1004,8 @@ static void pwm_dbg_show(struct pwm_chip *chip, struct 
seq_file *s)
seq_printf(s, " duty: %u ns", state.duty_cycle);
seq_printf(s, " polarity: %s",
   state.polarity ? "inverse" : "normal");
+   seq_printf(s, " mode: %s",
+  state.mode ? "push-pull" : "complementary");
 
seq_puts(s, "\n");
}
diff --git a/drivers/pwm/sysfs.c b/

[PATCH v3] usb: document that URB transfer_buffer should be aligned

[Mauro Carvalho Chehab]

Several host controllers, commonly found on ARM, like dwc2,
require buffers that are CPU-word aligned for they to work.

Failing to do that will cause buffer overflows at the caller
drivers, with could cause data corruption.

Such data corruption was found, in practice, with the uvcdriver.

Document it.

Signed-off-by: Mauro Carvalho Chehab 
---

Note: this patch is based on my previous patch series with
converts URB.txt to ReST:

Subject: [PATCH v2 00/21] Convert USB documentation to ReST format
Date: Wed,  5 Apr 2017 10:22:54 -0300
https://marc.info/?l=linux-doc&m=149139868231095&w=2

This patch, together with the ones above can be found on this tree:
 
   https://git.linuxtv.org/mchehab/experimental.git/log/?h=usb-docs-v2

 Documentation/driver-api/usb/URB.rst | 12 
 drivers/usb/core/message.c   | 15 +++
 include/linux/usb.h  | 12 
 3 files changed, 39 insertions(+)

diff --git a/Documentation/driver-api/usb/URB.rst 
b/Documentation/driver-api/usb/URB.rst
index 61a54da9fce9..8d3f362fbe82 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -271,6 +271,18 @@ If you specify your own start frame, make sure it's 
several frames in advance
 of the current frame.  You might want this model if you're synchronizing
 ISO data with some other event stream.
 
+ .. warning::
+
+   Several host drivers have a 32-bits or 64-bits DMA transfer word size,
+   with usually matches the CPU word. Due to such restriction, you should
+   warrant that the @transfer_buffer is DWORD aligned, on 32 bits system, or
+   QDWORD aligned, on 64 bits system. You should also ensure that the
+   buffer has enough space for PAD bits.
+
+   This condition is satisfied if you pass a buffer directly allocated by
+   kmalloc(), but this may not be the case if the driver allocates a bigger
+   buffer and point to a random place inside it.
+
 
 How to start interrupt (INT) transfers?
 ===
diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
index 4c38ea41ae96..1662a4446475 100644
--- a/drivers/usb/core/message.c
+++ b/drivers/usb/core/message.c
@@ -128,6 +128,21 @@ static int usb_internal_control_msg(struct usb_device 
*usb_dev,
  * make sure your disconnect() method can wait for it to complete. Since you
  * don't have a handle on the URB used, you can't cancel the request.
  *
+ * .. note::
+ *
+ *   Several host drivers require that the @data buffer to be aligned
+ *   with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
+ *   It is up to USB drivers should ensure that they'll only pass buffers
+ *   with such alignments.
+ *
+ *   Please also notice that, due to such restriction, the host driver
+ *   may also override PAD bytes at the end of the @data buffer, up to the
+ *   size of the CPU word.
+ *
+ *   Such word alignment condition is normally ensured if the buffer is
+ *   allocated with kmalloc(), but this may not be the case if the driver
+ *   allocates a bigger buffer and point to a random place inside it.
+ *
  * Return: If successful, the number of bytes transferred. Otherwise, a 
negative
  * error number.
  */
diff --git a/include/linux/usb.h b/include/linux/usb.h
index 7e68259360de..5739d4422343 100644
--- a/include/linux/usb.h
+++ b/include/linux/usb.h
@@ -1373,6 +1373,18 @@ typedef void (*usb_complete_t)(struct urb *);
  * capable, assign NULL to it, so that usbmon knows not to use the value.
  * The setup_packet must always be set, so it cannot be located in highmem.
  *
+ * .. warning::
+ *
+ *   Several host drivers have a 32-bits or 64-bits DMA transfer word size,
+ *   with usually matches the CPU word. Due to such restriction, you should
+ *   warrant that the @transfer_buffer is DWORD aligned, on 32 bits system, or
+ *   QDWORD aligned, on 64 bits system. You should also ensure that the
+ *   buffer has enough space for PAD bits.
+ *
+ *   This condition is satisfied if you pass a buffer directly allocated by
+ *   kmalloc(), but this may not be the case if the driver allocates a bigger
+ *   buffer and point to a random place inside it.
+ *
  * Initialization:
  *
  * All URBs submitted must initialize the dev, pipe, transfer_flags (may be
-- 
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

[PATCH v2 05/21] gadget.rst: Enrich its ReST representation and add kernel-doc tag

[Mauro Carvalho Chehab]

The pandoc conversion is not perfect. Do handwork in order to:

- add a title to this chapter;
- use the proper warning and note markups;
- use kernel-doc to include Kernel header and c files;
- remove legacy notes with regards to DocBook;
- some other minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/gadget.rst | 127 +---
 1 file changed, 52 insertions(+), 75 deletions(-)

diff --git a/Documentation/driver-api/usb/gadget.rst 
b/Documentation/driver-api/usb/gadget.rst
index 52b299b1ca6d..3e8a3809c0b8 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -38,7 +38,7 @@ address a number of important problems, including:
resources.
 
 Most Linux developers will not be able to use this API, since they have
-USB "host" hardware in a PC, workstation, or server. Linux users with
+USB ``host`` hardware in a PC, workstation, or server. Linux users with
 embedded systems are more likely to have USB peripheral hardware. To
 distinguish drivers running inside such hardware from the more familiar
 Linux "USB device drivers", which are host side proxies for the real USB
@@ -64,7 +64,7 @@ Structure of Gadget Drivers
 
 A system running inside a USB peripheral normally has at least three
 layers inside the kernel to handle USB protocol processing, and may have
-additional layers in user space code. The "gadget" API is used by the
+additional layers in user space code. The ``gadget`` API is used by the
 middle layer to interact with the lowest level (which directly handles
 hardware).
 
@@ -143,13 +143,13 @@ In Linux, from the bottom up, these layers are:
 *Additional Layers*
 Other layers may exist. These could include kernel layers, such as
 network protocol stacks, as well as user mode applications building
-on standard POSIX system call APIs such as *open()*, *close()*,
-*read()* and *write()*. On newer systems, POSIX Async I/O calls may
+on standard POSIX system call APIs such as ``open()``, ``close()``,
+``read()`` and ``write()``. On newer systems, POSIX Async I/O calls may
 be an option. Such user mode code will not necessarily be subject to
 the GNU General Public License (GPL).
 
 OTG-capable systems will also need to include a standard Linux-USB host
-side stack, with *usbcore*, one or more *Host Controller Drivers*
+side stack, with ``usbcore``, one or more *Host Controller Drivers*
 (HCDs), *USB Device Drivers* to support the OTG "Targeted Peripheral
 List", and so forth. There will also be an *OTG Controller Driver*,
 which is visible to gadget and device driver developers only indirectly.
@@ -174,24 +174,20 @@ combined, to implement composite devices.
 Kernel Mode Gadget API
 ==
 
-Gadget drivers declare themselves through a *struct
-usb_gadget_driver*, which is responsible for most parts of enumeration
-for a *struct usb_gadget*. The response to a set_configuration usually
-involves enabling one or more of the *struct usb_ep* objects exposed by
-the gadget, and submitting one or more *struct usb_request* buffers to
+Gadget drivers declare themselves through a struct
+:c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration
+for a struct :c:type:`usb_gadget`. The response to a set_configuration usually
+involves enabling one or more of the struct :c:type:`usb_ep` objects exposed by
+the gadget, and submitting one or more struct :c:type:`usb_request` buffers to
 transfer data. Understand those four data types, and their operations,
 and you will understand how this API works.
 
-**Note**
+.. Note::
 
-This documentation was prepared using the standard Linux kernel
-``docproc`` tool, which turns text and in-code comments into SGML
-DocBook and then into usable formats such as HTML or PDF. Other than
-the "Chapter 9" data types, most of the significant data types and
-functions are described here.
+Other than the "Chapter 9" data types, most of the significant data
+types and functions are described here.
 
-However, docproc does not understand all the C constructs that are
-used, so some relevant information is likely omitted from what you
+However, some relevant information is likely omitted from what you
 are reading. One example of such information is endpoint
 autoconfiguration. You'll have to read the header file, and use
 example source code (such as that for "Gadget Zero"), to fully
@@ -199,10 +195,10 @@ and you will understand how this API works.
 
 The part of the API implementing some basic driver capabilities is
 specific to the version of the Linux kernel that's in use. The 2.6
-kernel includes a *driver model* framework that has no analogue on
-earlier kernels; so those parts of the gadget API are not fully
-portable. (They are implemented on 2.4 kernels, but in a different
-  

[PATCH v2 21/21] docs-rst: fix usb cross-references

[Mauro Carvalho Chehab]

As some USB documentation files got moved, adjust their
cross-references to their new place.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/ABI/stable/sysfs-bus-usb| 2 +-
 Documentation/driver-api/usb/URB.rst  | 2 ++
 Documentation/driver-api/usb/callbacks.rst| 4 ++--
 Documentation/driver-api/usb/error-codes.rst  | 2 ++
 Documentation/driver-api/usb/persist.rst  | 2 ++
 Documentation/driver-api/usb/power-management.rst | 2 +-
 Documentation/driver-api/usb/usb.rst  | 4 ++--
 Documentation/power/swsusp.txt| 2 +-
 drivers/staging/most/hdm-usb/hdm_usb.c| 2 +-
 drivers/usb/core/Kconfig  | 2 +-
 10 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/Documentation/ABI/stable/sysfs-bus-usb 
b/Documentation/ABI/stable/sysfs-bus-usb
index 831f15d9672f..b832eeff 100644
--- a/Documentation/ABI/stable/sysfs-bus-usb
+++ b/Documentation/ABI/stable/sysfs-bus-usb
@@ -9,7 +9,7 @@ Description:
hubs this facility is always enabled and their device
directories will not contain this file.
 
-   For more information, see Documentation/usb/persist.txt.
+   For more information, see 
Documentation/driver-api/usb/persist.rst.
 
 What:  /sys/bus/usb/devices/.../power/autosuspend
 Date:  March 2007
diff --git a/Documentation/driver-api/usb/URB.rst 
b/Documentation/driver-api/usb/URB.rst
index c4a141f29477..61a54da9fce9 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -1,3 +1,5 @@
+.. _usb-urb:
+
 USB Request Block (URB)
 ~~~
 
diff --git a/Documentation/driver-api/usb/callbacks.rst 
b/Documentation/driver-api/usb/callbacks.rst
index 93a8d53e27e7..2b80cf54bcc3 100644
--- a/Documentation/driver-api/usb/callbacks.rst
+++ b/Documentation/driver-api/usb/callbacks.rst
@@ -8,7 +8,7 @@ Usbcore will call into a driver through callbacks defined in 
the driver
 structure and through the completion handler of URBs a driver submits.
 Only the former are in the scope of this document. These two kinds of
 callbacks are completely independent of each other. Information on the
-completion callback can be found in Documentation/usb/URB.txt.
+completion callback can be found in :ref:`usb-urb`.
 
 The callbacks defined in the driver structure are:
 
@@ -53,7 +53,7 @@ The callbacks defined in the driver structure are:
 
 The ioctl interface (2) should be used only if you have a very good
 reason. Sysfs is preferred these days. The PM callbacks are covered
-separately in Documentation/usb/power-management.txt.
+separately in :ref:`usb-power-management`.
 
 Calling conventions
 ===
diff --git a/Documentation/driver-api/usb/error-codes.rst 
b/Documentation/driver-api/usb/error-codes.rst
index 9c11a0fd16cb..a3e84bfac776 100644
--- a/Documentation/driver-api/usb/error-codes.rst
+++ b/Documentation/driver-api/usb/error-codes.rst
@@ -1,3 +1,5 @@
+.. _usb-error-codes:
+
 USB Error codes
 ~~~
 
diff --git a/Documentation/driver-api/usb/persist.rst 
b/Documentation/driver-api/usb/persist.rst
index ea1b43f0559e..08cafc6292c1 100644
--- a/Documentation/driver-api/usb/persist.rst
+++ b/Documentation/driver-api/usb/persist.rst
@@ -1,3 +1,5 @@
+.. _usb-persist:
+
 USB device persistence during system suspend
 
 
diff --git a/Documentation/driver-api/usb/power-management.rst 
b/Documentation/driver-api/usb/power-management.rst
index c068257f6d27..79beb807996b 100644
--- a/Documentation/driver-api/usb/power-management.rst
+++ b/Documentation/driver-api/usb/power-management.rst
@@ -328,7 +328,7 @@ possible to work around the hibernation-forces-disconnect 
problem by
 using the USB Persist facility.)
 
 The ``reset_resume`` method is used by the USB Persist facility (see
-``Documentation/usb/persist.txt``) and it can also be used under certain
+:ref:`usb-persist`) and it can also be used under certain
 circumstances when ``CONFIG_USB_PERSIST`` is not enabled.  Currently, if a
 device is reset during a resume and the driver does not have a
 ``reset_resume`` method, the driver won't receive any notification about
diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index 5ebaf669704c..6824089ef4c8 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -424,8 +424,8 @@ header.
 Unless noted otherwise, the ioctl requests described here will update
 the modification time on the usbfs file to which they are applied
 (unless they fail). A return of zero indicates success; otherwise, a
-standard USB error code is returned. (These are documented in
-``Documentation/usb/error-codes.txt`` in your kernel sources.)
+standard USB error code is returned (These are documented in
+:ref:`usb-error-codes`).
 
 Each of these files multiplexes access to several I/O streams, 

[PATCH v2 02/21] driver-api/basics.rst: add device table header

[Mauro Carvalho Chehab]

The structs there at device table are used by other documentation
at the Kernel. So, add it to the driver API.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/basics.rst | 6 ++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/driver-api/basics.rst 
b/Documentation/driver-api/basics.rst
index 935b9b8d456c..472e7a664d13 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -7,6 +7,12 @@ Driver Entry and Exit points
 .. kernel-doc:: include/linux/init.h
:internal:
 
+Driver device table
+---
+
+.. kernel-doc:: include/linux/mod_devicetable.h
+   :internal:
+
 Atomic and pointer manipulation
 ---
 
-- 
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

[PATCH v2 07/21] writing_musb_glue_layer.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

This file is actually quite complex, and required several
manual handwork:

- add a title for the document;
- use the right tags for monospaced fonts;
- use c references where needed;
- adjust cross-reference to writing_usb_driver.rst
- hightlight cross-referenced lines.

With regards to C code snippet line highlights, the better would be
to use :linenos: for the C code snippets that are referenced by
the line number. However, at least with Sphinx 1.4.9, enabling
it cause the line number to be misaligned with the code,
making it even more confusing. So, instead, let's use
:emphasize-lines: tag to mark the lines that are referenced
at the text.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../driver-api/usb/writing_musb_glue_layer.rst | 598 ++---
 1 file changed, 292 insertions(+), 306 deletions(-)

diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst 
b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
index 52700c7031f9..e90e8fa95600 100644
--- a/Documentation/driver-api/usb/writing_musb_glue_layer.rst
+++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
@@ -1,6 +1,6 @@
-==
-Writing an MUSB Glue Layer
-==
+=
+Writing a MUSB Glue Layer
+=
 
 :Author: Apelete Seketeli
 
@@ -21,10 +21,12 @@ design.
 As a self-taught exercise I have written an MUSB glue layer for the
 Ingenic JZ4740 SoC, modelled after the many MUSB glue layers in the
 kernel source tree. This layer can be found at
-drivers/usb/musb/jz4740.c. In this documentation I will walk through the
-basics of the jz4740.c glue layer, explaining the different pieces and
+``drivers/usb/musb/jz4740.c``. In this documentation I will walk through the
+basics of the ``jz4740.c`` glue layer, explaining the different pieces and
 what needs to be done in order to write your own device glue layer.
 
+.. _musb-basics:
+
 Linux MUSB Basics
 =
 
@@ -39,33 +41,30 @@ USB Device Drivers documentation (again, see Resources).
 
 Linux USB stack is a layered architecture in which the MUSB controller
 hardware sits at the lowest. The MUSB controller driver abstract the
-MUSB controller hardware to the Linux USB stack.
+MUSB controller hardware to the Linux USB stack::
 
-::
-
-  
-  |  | <--- drivers/usb/gadget
-  | Linux USB Core Stack | <--- drivers/usb/host
-  |  | <--- drivers/usb/core
-  
- ⬍
- --
- || <-- drivers/usb/musb/musb_gadget.c
- | MUSB Controller driver | <-- drivers/usb/musb/musb_host.c
- || <-- drivers/usb/musb/musb_core.c
- --
- ⬍
+ 
+ |  | <--- drivers/usb/gadget
+ | Linux USB Core Stack | <--- drivers/usb/host
+ |  | <--- drivers/usb/core
+ 
+⬍
+--
+|| <-- drivers/usb/musb/musb_gadget.c
+| MUSB Controller driver | <-- drivers/usb/musb/musb_host.c
+|| <-- drivers/usb/musb/musb_core.c
+--
+⬍
   -
   | MUSB Platform Specific Driver |
   |   | <-- drivers/usb/musb/jz4740.c
   |   aka "Glue Layer"|
   -
- ⬍
+⬍
   -
   |   MUSB Controller Hardware|
   -
 
-
 As outlined above, the glue layer is actually the platform specific code
 sitting in between the controller driver and the controller hardware.
 
@@ -78,37 +77,32 @@ about an embedded controller chip here, so no insertion or 
removal at
 run-time.
 
 All of this information is passed to the MUSB controller driver through
-a platform_driver structure defined in the glue layer as:
-
-::
+a :c:type:`platform_driver` structure defined in the glue layer as::
 
 static struct platform_driver jz4740_driver = {
-.probe  = jz4740_probe,
-.remove = jz4740_remove,
-.driver = {
-.name   = "musb-jz4740",
-},
+   .probe  = jz4740_probe,
+   .remove = jz4740_remove,
+   .driver = {
+   .name   = "musb-jz4740",
+   },
 };
 
-
 The probe and remove function pointers are called when a matching device
 is detected and, respectively, released. The name string describes the
 device supported by this glue layer. In the current case it matches a
-platform_device structure declared in a

[PATCH v2 11/21] usb/power-management.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/index.rst |   1 +
 .../usb/power-management.rst}  | 404 +++--
 2 files changed, 214 insertions(+), 191 deletions(-)
 rename Documentation/{usb/power-management.txt => 
driver-api/usb/power-management.rst} (69%)

diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 441c5dacdf27..23c76c17fc19 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -9,6 +9,7 @@ Linux USB API
anchors
bulk-streams
callbacks
+   power-management
writing_usb_driver
writing_musb_glue_layer
 
diff --git a/Documentation/usb/power-management.txt 
b/Documentation/driver-api/usb/power-management.rst
similarity index 69%
rename from Documentation/usb/power-management.txt
rename to Documentation/driver-api/usb/power-management.rst
index 00e706997130..c068257f6d27 100644
--- a/Documentation/usb/power-management.txt
+++ b/Documentation/driver-api/usb/power-management.rst
@@ -1,10 +1,12 @@
-   Power Management for USB
+.. _usb-power-management:
 
-Alan Stern 
-
-  Last-updated: February 2014
+Power Management for USB
+
 
+:Author: Alan Stern 
+:Date: Last-updated: February 2014
 
+..
Contents:
-
* What is Power Management?
@@ -25,14 +27,14 @@
* Suggested Userspace Port Power Policy
 
 
-   What is Power Management?
-   -
+What is Power Management?
+-
 
 Power Management (PM) is the practice of saving energy by suspending
 parts of a computer system when they aren't being used.  While a
-component is "suspended" it is in a nonfunctional low-power state; it
+component is ``suspended`` it is in a nonfunctional low-power state; it
 might even be turned off completely.  A suspended component can be
-"resumed" (returned to a functional full-power state) when the kernel
+``resumed`` (returned to a functional full-power state) when the kernel
 needs to use it.  (There also are forms of PM in which components are
 placed in a less functional but still usable state instead of being
 suspended; an example would be reducing the CPU's clock rate.  This
@@ -44,22 +46,25 @@ device is turned off while the system as a whole remains 
running, we
 call it a "dynamic suspend" (also known as a "runtime suspend" or
 "selective suspend").  This document concentrates mostly on how
 dynamic PM is implemented in the USB subsystem, although system PM is
-covered to some extent (see Documentation/power/*.txt for more
+covered to some extent (see ``Documentation/power/*.txt`` for more
 information about system PM).
 
-System PM support is present only if the kernel was built with CONFIG_SUSPEND
-or CONFIG_HIBERNATION enabled.  Dynamic PM support for USB is present whenever
-the kernel was built with CONFIG_PM enabled.
+System PM support is present only if the kernel was built with
+``CONFIG_SUSPEND`` or ``CONFIG_HIBERNATION`` enabled.  Dynamic PM support
+
+for USB is present whenever
+the kernel was built with ``CONFIG_PM`` enabled.
 
 [Historically, dynamic PM support for USB was present only if the
-kernel had been built with CONFIG_USB_SUSPEND enabled (which depended on
-CONFIG_PM_RUNTIME).  Starting with the 3.10 kernel release, dynamic PM support
-for USB was present whenever the kernel was built with CONFIG_PM_RUNTIME
-enabled.  The CONFIG_USB_SUSPEND option had been eliminated.]
+kernel had been built with ``CONFIG_USB_SUSPEND`` enabled (which depended on
+``CONFIG_PM_RUNTIME``).  Starting with the 3.10 kernel release, dynamic PM
+support for USB was present whenever the kernel was built with
+``CONFIG_PM_RUNTIME`` enabled.  The ``CONFIG_USB_SUSPEND`` option had been
+eliminated.]
 
 
-   What is Remote Wakeup?
-   --
+What is Remote Wakeup?
+--
 
 When a device has been suspended, it generally doesn't resume until
 the computer tells it to.  Likewise, if the entire computer has been
@@ -76,8 +81,8 @@ event.  Examples include a suspended keyboard resuming when a 
key is
 pressed, or a suspended USB hub resuming when a device is plugged in.
 
 
-   When is a USB device idle?
-   --
+When is a USB device idle?
+--
 
 A device is idle whenever the kernel thinks it's not busy doing
 anything important and thus is a candidate for being suspended.  The
@@ -92,11 +97,11 @@ If a USB device has no driver, its usbfs file isn't open, 
and it isn't
 being accessed through sysfs, then it definitely is idle.
 
 
-   Forms of dynamic PM
-   ---
+Forms of dynamic PM
+---
 
 Dynamic suspends occur when the kernel decides to suspend an idle
-device.  This is c

[PATCH v2 16/21] usb/URB.txt: convert to ReST and update it

[Mauro Carvalho Chehab]

The URB doc describes the Kernel mechanism that do USB transfers.
While the functions are already described at urb.h, there are a
number of concepts and theory that are important for USB driver
developers.

Convert it to ReST and use C ref links to point to the places
at usb.h where each function and struct is located.

A few of those descriptions were incomplete. While here, update
to reflect the current API status.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../{usb/URB.txt => driver-api/usb/URB.rst}| 221 -
 Documentation/driver-api/usb/index.rst |   1 +
 Documentation/driver-api/usb/usb.rst   |   2 +
 3 files changed, 127 insertions(+), 97 deletions(-)
 rename Documentation/{usb/URB.txt => driver-api/usb/URB.rst} (50%)

diff --git a/Documentation/usb/URB.txt b/Documentation/driver-api/usb/URB.rst
similarity index 50%
rename from Documentation/usb/URB.txt
rename to Documentation/driver-api/usb/URB.rst
index 50da0d455444..c4a141f29477 100644
--- a/Documentation/usb/URB.txt
+++ b/Documentation/driver-api/usb/URB.rst
@@ -1,28 +1,35 @@
-Revised: 2000-Dec-05.
-Again:   2002-Jul-06
-Again:   2005-Sep-19
+USB Request Block (URB)
+~~~
 
-NOTE:
+:Revised: 2000-Dec-05
+:Again:   2002-Jul-06
+:Again:   2005-Sep-19
+:Again:   2017-Mar-29
 
-The USB subsystem now has a substantial section in "The Linux Kernel API"
-guide (in Documentation/DocBook), generated from the current source
-code.  This particular documentation file isn't particularly current or
-complete; don't rely on it except for a quick overview.
 
+.. note::
 
-1.1. Basic concept or 'What is an URB?'
+The USB subsystem now has a substantial section at :ref:`usb-hostside-api`
+section, generated from the current source code.
+This particular documentation file isn't complete and may not be
+updated to the last version; don't rely on it except for a quick
+overview.
 
-The basic idea of the new driver is message passing, the message itself is 
-called USB Request Block, or URB for short. 
+Basic concept or 'What is an URB?'
+==
 
-- An URB consists of all relevant information to execute any USB transaction 
-  and deliver the data and status back. 
+The basic idea of the new driver is message passing, the message itself is
+called USB Request Block, or URB for short.
 
-- Execution of an URB is inherently an asynchronous operation, i.e. the 
-  usb_submit_urb(urb) call returns immediately after it has successfully
+- An URB consists of all relevant information to execute any USB transaction
+  and deliver the data and status back.
+
+- Execution of an URB is inherently an asynchronous operation, i.e. the
+  :c:func:`usb_submit_urb` call returns immediately after it has successfully
   queued the requested action.
 
-- Transfers for one URB can be canceled with usb_unlink_urb(urb) at any time. 
+- Transfers for one URB can be canceled with :c:func:`usb_unlink_urb`
+  at any time.
 
 - Each URB has a completion handler, which is called after the action
   has been successfully completed or canceled. The URB also contains a
@@ -35,53 +42,55 @@ called USB Request Block, or URB for short.
   of data to (or from) devices when using periodic transfer modes.
 
 
-1.2. The URB structure
+The URB structure
+=
 
-Some of the fields in an URB are:
+Some of the fields in struct :c:type:`urb` are::
 
-struct urb
-{
-// (IN) device and pipe specify the endpoint queue
+  struct urb
+  {
+  // (IN) device and pipe specify the endpoint queue
struct usb_device *dev; // pointer to associated USB device
unsigned int pipe;  // endpoint information
 
-   unsigned int transfer_flags;// ISO_ASAP, SHORT_NOT_OK, etc.
+   unsigned int transfer_flags;// URB_ISO_ASAP, URB_SHORT_NOT_OK, etc.
 
-// (IN) all urbs need completion routines
+  // (IN) all urbs need completion routines
void *context;  // context for completion routine
-   void (*complete)(struct urb *); // pointer to completion routine
+   usb_complete_t complete;// pointer to completion routine
 
-// (OUT) status after each completion
+  // (OUT) status after each completion
int status; // returned status
 
-// (IN) buffer used for data transfers
+  // (IN) buffer used for data transfers
void *transfer_buffer;  // associated data buffer
-   int transfer_buffer_length; // data buffer length
+   u32 transfer_buffer_length; // data buffer length
int number_of_packets;  // size of iso_frame_desc
 
-// (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
-   int actual_length;  // actual data buffer length
+  // (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
+   u32 actual_length;  // actual data buffer length
 
-// (IN) setup stage for CT

[PATCH v2 15/21] usb/persist.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/index.rst |  1 +
 .../persist.txt => driver-api/usb/persist.rst} | 22 +-
 2 files changed, 14 insertions(+), 9 deletions(-)
 rename Documentation/{usb/persist.txt => driver-api/usb/persist.rst} (94%)

diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 43f0a8b72b11..3f08cb5d5feb 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -12,6 +12,7 @@ Linux USB API
dma
power-management
hotplug
+   persist
error-codes
writing_usb_driver
writing_musb_glue_layer
diff --git a/Documentation/usb/persist.txt 
b/Documentation/driver-api/usb/persist.rst
similarity index 94%
rename from Documentation/usb/persist.txt
rename to Documentation/driver-api/usb/persist.rst
index 35d70eda9ad6..ea1b43f0559e 100644
--- a/Documentation/usb/persist.txt
+++ b/Documentation/driver-api/usb/persist.rst
@@ -1,11 +1,12 @@
-   USB device persistence during system suspend
+USB device persistence during system suspend
+
 
-  Alan Stern 
+:Author: Alan Stern 
+:Date: September 2, 2006 (Updated February 25, 2008)
 
-   September 2, 2006 (Updated February 25, 2008)
 
-
-   What is the problem?
+What is the problem?
+
 
 According to the USB specification, when a USB bus is suspended the
 bus must continue to supply suspend current (around 1-5 mA).  This
@@ -63,7 +64,8 @@ suspended -- but it will crash as soon as it wakes up, which 
isn't
 much better.)
 
 
-   What is the solution?
+What is the solution?
+=
 
 The kernel includes a feature called USB-persist.  It tries to work
 around these issues by allowing the core USB device data structures to
@@ -99,7 +101,7 @@ now a good and happy place.
 
 Note that the "USB-persist" feature will be applied only to those
 devices for which it is enabled.  You can enable the feature by doing
-(as root):
+(as root)::
 
echo 1 >/sys/bus/usb/devices/.../power/persist
 
@@ -110,7 +112,8 @@ doesn't even exist, so you only have to worry about setting 
it for
 devices where it really matters.
 
 
-   Is this the best solution?
+Is this the best solution?
+==
 
 Perhaps not.  Arguably, keeping track of mounted filesystems and
 memory mappings across device disconnects should be handled by a
@@ -130,7 +133,8 @@ just mass-storage devices.  It might turn out to be equally 
useful for
 other device types, such as network interfaces.
 
 
-   WARNING: USB-persist can be dangerous!!
+WARNING: USB-persist can be dangerous!!
+===
 
 When recovering an interrupted power session the kernel does its best
 to make sure the USB device hasn't been changed; that is, the same
-- 
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

[PATCH v2 10/21] usb/callbacks.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../callbacks.txt => driver-api/usb/callbacks.rst} | 61 +++---
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 43 insertions(+), 19 deletions(-)
 rename Documentation/{usb/callbacks.txt => driver-api/usb/callbacks.rst} (78%)

diff --git a/Documentation/usb/callbacks.txt 
b/Documentation/driver-api/usb/callbacks.rst
similarity index 78%
rename from Documentation/usb/callbacks.txt
rename to Documentation/driver-api/usb/callbacks.rst
index 9e85846bdb98..93a8d53e27e7 100644
--- a/Documentation/usb/callbacks.txt
+++ b/Documentation/driver-api/usb/callbacks.rst
@@ -1,3 +1,6 @@
+USB core callbacks
+~~
+
 What callbacks will usbcore do?
 ===
 
@@ -11,30 +14,42 @@ The callbacks defined in the driver structure are:
 
 1. Hotplugging callbacks:
 
- * @probe: Called to see if the driver is willing to manage a particular
- * interface on a device.
- * @disconnect: Called when the interface is no longer accessible, usually
- * because its device has been (or is being) disconnected or the
- * driver module is being unloaded.
+ - @probe:
+   Called to see if the driver is willing to manage a particular
+   interface on a device.
+
+ - @disconnect:
+   Called when the interface is no longer accessible, usually
+   because its device has been (or is being) disconnected or the
+   driver module is being unloaded.
 
 2. Odd backdoor through usbfs:
 
- * @ioctl: Used for drivers that want to talk to userspace through
- * the "usbfs" filesystem.  This lets devices provide ways to
- * expose information to user space regardless of where they
- * do (or don't) show up otherwise in the filesystem.
+ - @ioctl:
+   Used for drivers that want to talk to userspace through
+   the "usbfs" filesystem.  This lets devices provide ways to
+   expose information to user space regardless of where they
+   do (or don't) show up otherwise in the filesystem.
 
 3. Power management (PM) callbacks:
 
- * @suspend: Called when the device is going to be suspended.
- * @resume: Called when the device is being resumed.
- * @reset_resume: Called when the suspended device has been reset instead
- * of being resumed.
+ - @suspend:
+   Called when the device is going to be suspended.
+
+ - @resume:
+   Called when the device is being resumed.
+
+ - @reset_resume:
+   Called when the suspended device has been reset instead
+   of being resumed.
 
 4. Device level operations:
 
- * @pre_reset: Called when the device is about to be reset.
- * @post_reset: Called after the device has been reset
+ - @pre_reset:
+   Called when the device is about to be reset.
+
+ - @post_reset:
+   Called after the device has been reset
 
 The ioctl interface (2) should be used only if you have a very good
 reason. Sysfs is preferred these days. The PM callbacks are covered
@@ -58,7 +73,9 @@ an interface. A driver's bond to an interface is exclusive.
 The probe() callback
 
 
-int (*probe) (struct usb_interface *intf,
+::
+
+  int (*probe) (struct usb_interface *intf,
const struct usb_device_id *id);
 
 Accept or decline an interface. If you accept the device return 0,
@@ -75,7 +92,9 @@ initialisation that doesn't take too long is a good idea here.
 The disconnect() callback
 -
 
-void (*disconnect) (struct usb_interface *intf);
+::
+
+  void (*disconnect) (struct usb_interface *intf);
 
 This callback is a signal to break any connection with an interface.
 You are not allowed any IO to a device after returning from this
@@ -93,7 +112,9 @@ Device level callbacks
 pre_reset
 -
 
-int (*pre_reset)(struct usb_interface *intf);
+::
+
+  int (*pre_reset)(struct usb_interface *intf);
 
 A driver or user space is triggering a reset on the device which
 contains the interface passed as an argument. Cease IO, wait for all
@@ -107,7 +128,9 @@ are in atomic context.
 post_reset
 --
 
-int (*post_reset)(struct usb_interface *intf);
+::
+
+  int (*post_reset)(struct usb_interface *intf);
 
 The reset has completed.  Restore any saved device state and begin
 using the device again.
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 6fe7611f7332..441c5dacdf27 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -8,6 +8,7 @@ Linux USB API
gadget
anchors
bulk-streams
+   callbacks
writing_usb_driver
writing_musb_glue_layer
 
-- 
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

[PATCH v2 14/21] usb/hotplug.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../hotplug.txt => driver-api/usb/hotplug.rst} | 66 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 37 insertions(+), 30 deletions(-)
 rename Documentation/{usb/hotplug.txt => driver-api/usb/hotplug.rst} (76%)

diff --git a/Documentation/usb/hotplug.txt 
b/Documentation/driver-api/usb/hotplug.rst
similarity index 76%
rename from Documentation/usb/hotplug.txt
rename to Documentation/driver-api/usb/hotplug.rst
index 5b243f315b2c..79663e653ca1 100644
--- a/Documentation/usb/hotplug.txt
+++ b/Documentation/driver-api/usb/hotplug.rst
@@ -1,4 +1,9 @@
-LINUX HOTPLUGGING
+USB hotplugging
+~~~
+
+Linux Hotplugging
+=
+
 
 In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices
 into the bus with power on.  In most cases, users expect the devices to become
@@ -30,11 +35,11 @@ Because some of those actions rely on information about 
drivers (metadata)
 that is currently available only when the drivers are dynamically linked,
 you get the best hotplugging when you configure a highly modular system.
 
+Kernel Hotplug Helper (``/sbin/hotplug``)
+=
 
-KERNEL HOTPLUG HELPER (/sbin/hotplug)
-
-There is a kernel parameter: /proc/sys/kernel/hotplug, which normally
-holds the pathname "/sbin/hotplug".  That parameter names a program
+There is a kernel parameter: ``/proc/sys/kernel/hotplug``, which normally
+holds the pathname ``/sbin/hotplug``.  That parameter names a program
 which the kernel may invoke at various times.
 
 The /sbin/hotplug program can be invoked by any subsystem as part of its
@@ -51,26 +56,26 @@ Hotplug software and other resources is available at:
 Mailing list information is also available at that site.
 
 
---
+USB Policy Agent
+
 
-
-USB POLICY AGENT
-
-The USB subsystem currently invokes /sbin/hotplug when USB devices
+The USB subsystem currently invokes ``/sbin/hotplug`` when USB devices
 are added or removed from system.  The invocation is done by the kernel
 hub workqueue [hub_wq], or else as part of root hub initialization
 (done by init, modprobe, kapmd, etc).  Its single command line parameter
 is the string "usb", and it passes these environment variables:
 
-ACTION ... "add", "remove"
-PRODUCT ... USB vendor, product, and version codes (hex)
-TYPE ... device class codes (decimal)
-INTERFACE ... interface 0 class codes (decimal)
+== 
+ACTION ``add``, ``remove``
+PRODUCTUSB vendor, product, and version codes (hex)
+TYPE   device class codes (decimal)
+INTERFACE  interface 0 class codes (decimal)
+== 
 
 If "usbdevfs" is configured, DEVICE and DEVFS are also passed.  DEVICE is
 the pathname of the device, and is useful for devices with multiple and/or
 alternate interfaces that complicate driver selection.  By design, USB
-hotplugging is independent of "usbdevfs":  you can do most essential parts
+hotplugging is independent of ``usbdevfs``:  you can do most essential parts
 of USB device setup without using that filesystem, and without running a
 user mode daemon to detect changes in system configuration.
 
@@ -79,19 +84,20 @@ modules, and can invoke driver-specific setup scripts.  The 
newest ones
 leverage USB module-init-tools support.  Later agents might unload drivers.
 
 
-USB MODUTILS SUPPORT
+USB Modutils Support
+
 
-Current versions of module-init-tools will create a "modules.usbmap" file
-which contains the entries from each driver's MODULE_DEVICE_TABLE.  Such
+Current versions of module-init-tools will create a ``modules.usbmap`` file
+which contains the entries from each driver's ``MODULE_DEVICE_TABLE``.  Such
 files can be used by various user mode policy agents to make sure all the
 right driver modules get loaded, either at boot time or later.
 
-See  for full information about such table entries; or look
+See ``linux/usb.h`` for full information about such table entries; or look
 at existing drivers.  Each table entry describes one or more criteria to
 be used when matching a driver to a device or class of devices.  The
 specific criteria are identified by bits set in "match_flags", paired
 with field values.  You can construct the criteria directly, or with
-macros such as these, and use driver_info to store more information.
+macros such as these, and use driver_info to store more information::
 
 USB_DEVICE (vendorId, productId)
... matching devices with specified vendor and product ids
@@ -103,7 +109,7 @@ macros such as these, and use driver_info to store more 
information.
... matching specified device class info
 
 A short example, for a driver that supports 

[PATCH v2 12/21] usb/dma.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../{usb/dma.txt => driver-api/usb/dma.rst}| 51 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 28 insertions(+), 24 deletions(-)
 rename Documentation/{usb/dma.txt => driver-api/usb/dma.rst} (79%)

diff --git a/Documentation/usb/dma.txt b/Documentation/driver-api/usb/dma.rst
similarity index 79%
rename from Documentation/usb/dma.txt
rename to Documentation/driver-api/usb/dma.rst
index 444651e70d95..59d5aee89e37 100644
--- a/Documentation/usb/dma.txt
+++ b/Documentation/driver-api/usb/dma.rst
@@ -1,16 +1,19 @@
+USB DMA
+~~~
+
 In Linux 2.5 kernels (and later), USB device drivers have additional control
 over how DMA may be used to perform I/O operations.  The APIs are detailed
 in the kernel usb programming guide (kerneldoc, from the source code).
 
-
-API OVERVIEW
+API overview
+
 
 The big picture is that USB drivers can continue to ignore most DMA issues,
 though they still must provide DMA-ready buffers (see
-Documentation/DMA-API-HOWTO.txt).  That's how they've worked through
-the 2.4 (and earlier) kernels.
+``Documentation/DMA-API-HOWTO.txt``).  That's how they've worked through
+the 2.4 (and earlier) kernels, or they can now be DMA-aware.
 
-OR:  they can now be DMA-aware.
+DMA-aware usb drivers:
 
 - New calls enable DMA-aware drivers, letting them allocate dma buffers and
   manage dma mappings for existing dma-ready buffers (see below).
@@ -20,15 +23,15 @@ OR:  they can now be DMA-aware.
   drivers must not use it.)
 
 - "usbcore" will map this DMA address, if a DMA-aware driver didn't do
-  it first and set URB_NO_TRANSFER_DMA_MAP.  HCDs
+  it first and set ``URB_NO_TRANSFER_DMA_MAP``.  HCDs
   don't manage dma mappings for URBs.
 
 - There's a new "generic DMA API", parts of which are usable by USB device
   drivers.  Never use dma_set_mask() on any USB interface or device; that
   would potentially break all devices sharing that bus.
 
-
-ELIMINATING COPIES
+Eliminating copies
+==
 
 It's good to avoid making CPUs copy data needlessly.  The costs can add up,
 and effects like cache-trashing can impose subtle penalties.
@@ -41,7 +44,7 @@ and effects like cache-trashing can impose subtle penalties.
   For those specific cases, USB has primitives to allocate less expensive
   memory.  They work like kmalloc and kfree versions that give you the right
   kind of addresses to store in urb->transfer_buffer and urb->transfer_dma.
-  You'd also set URB_NO_TRANSFER_DMA_MAP in urb->transfer_flags:
+  You'd also set ``URB_NO_TRANSFER_DMA_MAP`` in urb->transfer_flags::
 
void *usb_alloc_coherent (struct usb_device *dev, size_t size,
int mem_flags, dma_addr_t *dma);
@@ -49,15 +52,15 @@ and effects like cache-trashing can impose subtle penalties.
void usb_free_coherent (struct usb_device *dev, size_t size,
void *addr, dma_addr_t dma);
 
-  Most drivers should *NOT* be using these primitives; they don't need
+  Most drivers should **NOT** be using these primitives; they don't need
   to use this type of memory ("dma-coherent"), and memory returned from
-  kmalloc() will work just fine.
+  :c:func:`kmalloc` will work just fine.
 
   The memory buffer returned is "dma-coherent"; sometimes you might need to
   force a consistent memory access ordering by using memory barriers.  It's
   not using a streaming DMA mapping, so it's good for small transfers on
   systems where the I/O would otherwise thrash an IOMMU mapping.  (See
-  Documentation/DMA-API-HOWTO.txt for definitions of "coherent" and
+  ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and
   "streaming" DMA mappings.)
 
   Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
@@ -75,15 +78,15 @@ and effects like cache-trashing can impose subtle penalties.
   way to expose these capabilities ... and in any case, HIGHMEM is mostly a
   design wart specific to x86_32.  So your best bet is to ensure you never
   pass a highmem buffer into a USB driver.  That's easy; it's the default
-  behavior.  Just don't override it; e.g. with NETIF_F_HIGHDMA.
+  behavior.  Just don't override it; e.g. with ``NETIF_F_HIGHDMA``.
 
   This may force your callers to do some bounce buffering, copying from
   high memory to "normal" DMA memory.  If you can come up with a good way
   to fix this issue (for x86_32 machines with over 1 GByte of memory),
   feel free to submit patches.
 
-
-WORKING WITH EXISTING BUFFERS
+Working with existing buffers
+=
 
 Existing buffers aren't usable for DMA without first being mapped into the
 DMA address space of the device.  However, most buffers passed to your
@@ -92,7 +95,7 @@ of Documentation/DMA-API-HOWTO.txt, titled "What memory is 
DMA-able?")
 
 - When you're using scatterlists, you can map everything at once.  O

[PATCH v2 01/21] tmplcvt: make the tool more robust

[Mauro Carvalho Chehab]

Currently, the script just assumes to be called at
Documentation/sphinx/. Change it to work on any directory,
and make it abort if something gets wrong.

Also, be sure that both parameters are specified.

That should avoid troubles like this:

$ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
sed: couldn't open file convert_template.sed: No such file or directory

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/sphinx/tmplcvt | 13 +++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt
index 909a73065e0a..6848f0a26fa5 100755
--- a/Documentation/sphinx/tmplcvt
+++ b/Documentation/sphinx/tmplcvt
@@ -7,13 +7,22 @@
 # fix \_
 # title line?
 #
+set -eu
+
+if [ "$#" != "2" ]; then
+   echo "$0  "
+   exit
+fi
+
+DIR=$(dirname $0)
 
 in=$1
 rst=$2
 tmp=$rst.tmp
 
 cp $in $tmp
-sed --in-place -f convert_template.sed $tmp
+sed --in-place -f $DIR/convert_template.sed $tmp
 pandoc -s -S -f docbook -t rst -o $rst $tmp
-sed --in-place -f post_convert.sed $rst
+sed --in-place -f $DIR/post_convert.sed $rst
 rm $tmp
+echo "book writen to $rst"
-- 
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

[PATCH v2 20/21] usb: gadget.h: be consistent at kernel doc macros

[Mauro Carvalho Chehab]

There's one value that use spaces instead of tabs to ident.
That causes the following warning:

./include/linux/usb/gadget.h:193: ERROR: Unexpected indentation.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/linux/usb/gadget.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/usb/gadget.h b/include/linux/usb/gadget.h
index e4516e9ded0f..fbc22a39e7bc 100644
--- a/include/linux/usb/gadget.h
+++ b/include/linux/usb/gadget.h
@@ -188,7 +188,7 @@ struct usb_ep_caps {
  * @caps:The structure describing types and directions supported by endoint.
  * @maxpacket:The maximum packet size used on this endpoint.  The initial
  * value can sometimes be reduced (hardware allowing), according to
- *  the endpoint descriptor used to configure the endpoint.
+ * the endpoint descriptor used to configure the endpoint.
  * @maxpacket_limit:The maximum packet size value which can be handled by this
  * endpoint. It's set once by UDC driver when endpoint is initialized, and
  * should not be changed. Should not be confused with maxpacket.
-- 
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

[PATCH v2 18/21] usb: get rid of some ReST doc build errors

[Mauro Carvalho Chehab]

We need an space before a numbered list to avoid those warnings:

./drivers/usb/core/message.c:478: ERROR: Unexpected indentation.
./drivers/usb/core/message.c:479: WARNING: Block quote ends without a blank 
line; unexpected unindent.
./include/linux/usb/composite.h:455: ERROR: Unexpected indentation.
./include/linux/usb/composite.h:456: WARNING: Block quote ends without a blank 
line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/usb/core/message.c| 1 +
 include/linux/usb/composite.h | 1 +
 2 files changed, 2 insertions(+)

diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
index 2184ef40a82a..4c38ea41ae96 100644
--- a/drivers/usb/core/message.c
+++ b/drivers/usb/core/message.c
@@ -474,6 +474,7 @@ EXPORT_SYMBOL_GPL(usb_sg_init);
  * significantly improve USB throughput.
  *
  * There are three kinds of completion for this function.
+ *
  * (1) success, where io->status is zero.  The number of io->bytes
  * transferred is as requested.
  * (2) error, where io->status is a negative errno value.  The number
diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h
index 4616a49a1c2e..30a063e98c19 100644
--- a/include/linux/usb/composite.h
+++ b/include/linux/usb/composite.h
@@ -451,6 +451,7 @@ static inline struct usb_composite_driver *to_cdriver(
  * sure doing that won't hurt too much.
  *
  * One notion for how to handle Wireless USB devices involves:
+ *
  * (a) a second gadget here, discovery mechanism TBD, but likely
  * needing separate "register/unregister WUSB gadget" calls;
  * (b) updates to usb_gadget to include flags "is it wireless",
-- 
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

[PATCH v2 17/21] usb.rst: get rid of some Sphinx errors

[Mauro Carvalho Chehab]

Get rid of those warnings:

Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_type".
Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_dir".
Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_recip".
Documentation/driver-api/usb/usb.rst:679: ERROR: Unknown target name: 
"usbdevfs_urb_type".

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/usb.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index d15ab8ae5239..5ebaf669704c 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -615,8 +615,8 @@ USBDEVFS_CONTROL
 The first eight bytes of this structure are the contents of the
 SETUP packet to be sent to the device; see the USB 2.0 specification
 for details. The bRequestType value is composed by combining a
-USB_TYPE_\* value, a USB_DIR_\* value, and a USB_RECIP_\*
-value (from **). If wLength is nonzero, it describes
+``USB_TYPE_*`` value, a ``USB_DIR_*`` value, and a ``USB_RECIP_*``
+value (from ``linux/usb.h``). If wLength is nonzero, it describes
 the length of the data buffer, which is either written to the device
 (USB_DIR_OUT) or read from the device (USB_DIR_IN).
 
@@ -678,7 +678,7 @@ the blocking is separate.
 
 These requests are packaged into a structure that resembles the URB used
 by kernel device drivers. (No POSIX Async I/O support here, sorry.) It
-identifies the endpoint type (USBDEVFS_URB_TYPE_\*), endpoint
+identifies the endpoint type (``USBDEVFS_URB_TYPE_*``), endpoint
 (number, masked with USB_DIR_IN as appropriate), buffer and length,
 and a user "context" value serving to uniquely identify each request.
 (It's usually a pointer to per-request data.) Flags can modify requests
-- 
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

[PATCH v2 04/21] usb.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

- use the proper warning and note markups;
- add references for parts of the document that will be
  cross-referenced on other USB docs;
- some minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/usb.rst | 48 +---
 1 file changed, 17 insertions(+), 31 deletions(-)

diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index b856abb3200e..7e820768ee4f 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -102,6 +102,8 @@ disconnect testing (while the device is active) with each 
different host
 controller driver, to make sure drivers don't have bugs of their own as
 well as to make sure they aren't relying on some HCD-specific behavior.
 
+.. _usb_chapter9:
+
 USB-Standard Types
 ==
 
@@ -112,6 +114,8 @@ USB, and in APIs including this host side API, gadget APIs, 
and usbfs.
 .. kernel-doc:: include/linux/usb/ch9.h
:internal:
 
+.. _usb_header:
+
 Host-Side Data Types and Macros
 ===
 
@@ -209,7 +213,7 @@ library that wraps it. Such libraries include
 `libusb `__ for C/C++, and
 `jUSB `__ for Java.
 
-**Note**
+.. note::
 
 This particular documentation is incomplete, especially with respect
 to the asynchronous mode. As of kernel 2.5.66 the code and this
@@ -319,9 +323,7 @@ files. For information about the current format of this 
file, see the
 sources.
 
 This file, in combination with the poll() system call, can also be used
-to detect when devices are added or removed:
-
-::
+to detect when devices are added or removed::
 
 int fd;
 struct pollfd pfd;
@@ -407,9 +409,7 @@ The ioctl() Requests
 
 
 To use these ioctls, you need to include the following headers in your
-userspace program:
-
-::
+userspace program::
 
 #include 
 #include 
@@ -458,9 +458,7 @@ USBDEVFS_CLAIMINTERFACE
 
 USBDEVFS_CONNECTINFO
 Says whether the device is lowspeed. The ioctl parameter points to a
-structure like this:
-
-::
+structure like this::
 
struct usbdevfs_connectinfo {
unsigned int   devnum;
@@ -477,9 +475,7 @@ USBDEVFS_CONNECTINFO
 USBDEVFS_GETDRIVER
 Returns the name of the kernel driver bound to a given interface (a
 string). Parameter is a pointer to this structure, which is
-modified:
-
-::
+modified::
 
struct usbdevfs_getdriver {
unsigned int  interface;
@@ -490,9 +486,7 @@ USBDEVFS_GETDRIVER
 
 USBDEVFS_IOCTL
 Passes a request from userspace through to a kernel driver that has
-an ioctl entry in the *struct usb_driver* it registered.
-
-::
+an ioctl entry in the *struct usb_driver* it registered::
 
struct usbdevfs_ioctl {
int ifno;
@@ -534,7 +528,7 @@ USBDEVFS_RELEASEINTERFACE
 the number of the interface (bInterfaceNumber from descriptor); File
 modification time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*No security check is made to ensure that the task which made
the claim is the one which is releasing it. This means that user
@@ -574,9 +568,7 @@ a time.
 
 USBDEVFS_BULK
 Issues a bulk read or write request to the device. The ioctl
-parameter is a pointer to this structure:
-
-::
+parameter is a pointer to this structure::
 
struct usbdevfs_bulktransfer {
unsigned int  ep;
@@ -606,9 +598,7 @@ USBDEVFS_CLEAR_HALT
 
 USBDEVFS_CONTROL
 Issues a control request to the device. The ioctl parameter points
-to a structure like this:
-
-::
+to a structure like this::
 
struct usbdevfs_ctrltransfer {
__u8   bRequestType;
@@ -638,7 +628,7 @@ USBDEVFS_RESET
 the reset, this rebinds all device interfaces. File modification
 time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*Avoid using this call* until some usbcore bugs get fixed, since
it does not fully synchronize device, interface, and driver (not
@@ -646,9 +636,7 @@ USBDEVFS_RESET
 
 USBDEVFS_SETINTERFACE
 Sets the alternate setting for an interface. The ioctl parameter is
-a pointer to a structure like this:
-
-::
+a pointer to a structure like this::
 
struct usbdevfs_setinterface {
unsigned int  interface;
@@ -669,7 +657,7 @@ USBDEVFS_SETCONFIGURATION
 configuration (bConfigurationValue from descriptor). File
 modification time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*Avoid using this call* until some usbcore bugs get fixed, since
it does not fully synchronize device, interface, and driver (not
@@ -702,9 +690,7 @@ When usbfs returns these urbs, the status value is updated, 
and the
 buffer may have been modified. Exc

[PATCH v2 19/21] usb: composite.h: fix two warnings when building docs

[Mauro Carvalho Chehab]

By definition, we use /* private: */ tag when we won't be documenting
a parameter. However, those two parameters are documented:

./include/linux/usb/composite.h:510: warning: Excess struct/union/enum/typedef 
member 'setup_pending' description in 'usb_composite_dev'
./include/linux/usb/composite.h:510: warning: Excess struct/union/enum/typedef 
member 'os_desc_pending' description in 'usb_composite_dev'

So, we need to use /* public: */ to avoid a warning.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/linux/usb/composite.h | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h
index 30a063e98c19..f665d2ceac20 100644
--- a/include/linux/usb/composite.h
+++ b/include/linux/usb/composite.h
@@ -504,8 +504,9 @@ struct usb_composite_dev {
/* protects deactivations and delayed_status counts*/
spinlock_t  lock;
 
-   unsignedsetup_pending:1;
-   unsignedos_desc_pending:1;
+   /* public: */
+   unsigned intsetup_pending:1;
+   unsigned intos_desc_pending:1;
 };
 
 extern int usb_string_id(struct usb_composite_dev *c);
-- 
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

[PATCH v2 00/21] Convert USB documentation to ReST format

[Mauro Carvalho Chehab]

Currently, there are several USB core documents that are at either
written in plain text or in DocBook format. Convert them to ReST
and add to the driver-api book.

Mauro Carvalho Chehab (21):
  tmplcvt: make the tool more robust
  driver-api/basics.rst: add device table header
  docs-rst: convert usb docbooks to ReST
  usb.rst: Enrich its ReST representation
  gadget.rst: Enrich its ReST representation and add kernel-doc tag
  writing_usb_driver.rst: Enrich its ReST representation
  writing_musb_glue_layer.rst: Enrich its ReST representation
  usb/anchors.txt: convert to ReST and add to driver-api book
  usb/bulk-streams.txt: convert to ReST and add to driver-api book
  usb/callbacks.txt: convert to ReST and add to driver-api book
  usb/power-management.txt: convert to ReST and add to driver-api book
  usb/dma.txt: convert to ReST and add to driver-api book
  error-codes.rst: convert to ReST and add to driver-api book
  usb/hotplug.txt: convert to ReST and add to driver-api book
  usb/persist.txt: convert to ReST and add to driver-api book
  usb/URB.txt: convert to ReST and update it
  usb.rst: get rid of some Sphinx errors
  usb: get rid of some ReST doc build errors
  usb: composite.h: fix two warnings when building docs
  usb: gadget.h: be consistent at kernel doc macros
  docs-rst: fix usb cross-references

 Documentation/ABI/stable/sysfs-bus-usb |   2 +-
 Documentation/DocBook/Makefile |   7 +-
 Documentation/DocBook/gadget.tmpl  | 793 ---
 Documentation/DocBook/writing_musb_glue_layer.tmpl | 873 -
 Documentation/DocBook/writing_usb_driver.tmpl  | 412 --
 Documentation/driver-api/basics.rst|   6 +
 Documentation/driver-api/index.rst |   2 +-
 .../{usb/URB.txt => driver-api/usb/URB.rst}| 223 +++---
 .../anchors.txt => driver-api/usb/anchors.rst} |  36 +-
 .../usb/bulk-streams.rst}  |  13 +-
 .../callbacks.txt => driver-api/usb/callbacks.rst} |  65 +-
 .../{usb/dma.txt => driver-api/usb/dma.rst}|  51 +-
 Documentation/driver-api/usb/error-codes.rst   | 207 +
 Documentation/driver-api/usb/gadget.rst| 510 
 .../hotplug.txt => driver-api/usb/hotplug.rst} |  66 +-
 Documentation/driver-api/usb/index.rst |  26 +
 .../persist.txt => driver-api/usb/persist.rst} |  22 +-
 .../usb/power-management.rst}  | 404 +-
 Documentation/driver-api/{ => usb}/usb.rst | 222 +++---
 .../driver-api/usb/writing_musb_glue_layer.rst | 723 +
 .../driver-api/usb/writing_usb_driver.rst  | 326 
 Documentation/power/swsusp.txt |   2 +-
 Documentation/sphinx/tmplcvt   |  13 +-
 Documentation/usb/error-codes.txt  | 175 -
 drivers/staging/most/hdm-usb/hdm_usb.c |   2 +-
 drivers/usb/core/Kconfig   |   2 +-
 drivers/usb/core/message.c |   1 +
 include/linux/usb/composite.h  |   6 +-
 include/linux/usb/gadget.h |   2 +-
 29 files changed, 2417 insertions(+), 2775 deletions(-)
 delete mode 100644 Documentation/DocBook/gadget.tmpl
 delete mode 100644 Documentation/DocBook/writing_musb_glue_layer.tmpl
 delete mode 100644 Documentation/DocBook/writing_usb_driver.tmpl
 rename Documentation/{usb/URB.txt => driver-api/usb/URB.rst} (50%)
 rename Documentation/{usb/anchors.txt => driver-api/usb/anchors.rst} (75%)
 rename Documentation/{usb/bulk-streams.txt => driver-api/usb/bulk-streams.rst} 
(94%)
 rename Documentation/{usb/callbacks.txt => driver-api/usb/callbacks.rst} (76%)
 rename Documentation/{usb/dma.txt => driver-api/usb/dma.rst} (79%)
 create mode 100644 Documentation/driver-api/usb/error-codes.rst
 create mode 100644 Documentation/driver-api/usb/gadget.rst
 rename Documentation/{usb/hotplug.txt => driver-api/usb/hotplug.rst} (76%)
 create mode 100644 Documentation/driver-api/usb/index.rst
 rename Documentation/{usb/persist.txt => driver-api/usb/persist.rst} (94%)
 rename Documentation/{usb/power-management.txt => 
driver-api/usb/power-management.rst} (69%)
 rename Documentation/driver-api/{ => usb}/usb.rst (85%)
 create mode 100644 Documentation/driver-api/usb/writing_musb_glue_layer.rst
 create mode 100644 Documentation/driver-api/usb/writing_usb_driver.rst
 delete mode 100644 Documentation/usb/error-codes.txt

-- 
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

[PATCH v2 08/21] usb/anchors.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../anchors.txt => driver-api/usb/anchors.rst} | 36 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 21 insertions(+), 16 deletions(-)
 rename Documentation/{usb/anchors.txt => driver-api/usb/anchors.rst} (75%)

diff --git a/Documentation/usb/anchors.txt 
b/Documentation/driver-api/usb/anchors.rst
similarity index 75%
rename from Documentation/usb/anchors.txt
rename to Documentation/driver-api/usb/anchors.rst
index fe6a99a32bbd..4b248e691bd6 100644
--- a/Documentation/usb/anchors.txt
+++ b/Documentation/driver-api/usb/anchors.rst
@@ -1,3 +1,6 @@
+USB Anchors
+~~~
+
 What is anchor?
 ===
 
@@ -13,7 +16,7 @@ Allocation and Initialisation
 =
 
 There's no API to allocate an anchor. It is simply declared
-as struct usb_anchor. init_usb_anchor() must be called to
+as struct usb_anchor. :c:func:`init_usb_anchor` must be called to
 initialise the data structure.
 
 Deallocation
@@ -26,52 +29,53 @@ Association and disassociation of URBs with anchors
 ===
 
 An association of URBs to an anchor is made by an explicit
-call to usb_anchor_urb(). The association is maintained until
+call to :c:func:`usb_anchor_urb`. The association is maintained until
 an URB is finished by (successful) completion. Thus disassociation
 is automatic. A function is provided to forcibly finish (kill)
 all URBs associated with an anchor.
-Furthermore, disassociation can be made with usb_unanchor_urb()
+Furthermore, disassociation can be made with :c:func:`usb_unanchor_urb`
 
 Operations on multitudes of URBs
 
 
-usb_kill_anchored_urbs()
-
+:c:func:`usb_kill_anchored_urbs`
+
 
 This function kills all URBs associated with an anchor. The URBs
 are called in the reverse temporal order they were submitted.
 This way no data can be reordered.
 
-usb_unlink_anchored_urbs()
---
+:c:func:`usb_unlink_anchored_urbs`
+--
+
 
 This function unlinks all URBs associated with an anchor. The URBs
 are processed in the reverse temporal order they were submitted.
-This is similar to usb_kill_anchored_urbs(), but it will not sleep.
+This is similar to :c:func:`usb_kill_anchored_urbs`, but it will not sleep.
 Therefore no guarantee is made that the URBs have been unlinked when
 the call returns. They may be unlinked later but will be unlinked in
 finite time.
 
-usb_scuttle_anchored_urbs()

+:c:func:`usb_scuttle_anchored_urbs`
+---
 
 All URBs of an anchor are unanchored en masse.
 
-usb_wait_anchor_empty_timeout()

+:c:func:`usb_wait_anchor_empty_timeout`
+---
 
 This function waits for all URBs associated with an anchor to finish
 or a timeout, whichever comes first. Its return value will tell you
 whether the timeout was reached.
 
-usb_anchor_empty()
---
+:c:func:`usb_anchor_empty`
+--
 
 Returns true if no URBs are associated with an anchor. Locking
 is the caller's responsibility.
 
-usb_get_from_anchor()
--
+:c:func:`usb_get_from_anchor`
+-
 
 Returns the oldest anchored URB of an anchor. The URB is unanchored
 and returned with a reference. As you may mix URBs to several
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index cf2fa2e8d236..5dfb04b2d730 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -6,6 +6,7 @@ Linux USB API
 
usb
gadget
+   anchors
writing_usb_driver
writing_musb_glue_layer
 
-- 
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

[PATCH v2 09/21] usb/bulk-streams.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../bulk-streams.txt => driver-api/usb/bulk-streams.rst}| 13 +
 Documentation/driver-api/usb/index.rst  |  1 +
 2 files changed, 10 insertions(+), 4 deletions(-)
 rename Documentation/{usb/bulk-streams.txt => driver-api/usb/bulk-streams.rst} 
(94%)

diff --git a/Documentation/usb/bulk-streams.txt 
b/Documentation/driver-api/usb/bulk-streams.rst
similarity index 94%
rename from Documentation/usb/bulk-streams.txt
rename to Documentation/driver-api/usb/bulk-streams.rst
index ffc02021863e..99b515babdeb 100644
--- a/Documentation/usb/bulk-streams.txt
+++ b/Documentation/driver-api/usb/bulk-streams.rst
@@ -1,3 +1,6 @@
+USB bulk streams
+
+
 Background
 ==
 
@@ -25,7 +28,9 @@ time.
 Driver implications
 ===
 
-int usb_alloc_streams(struct usb_interface *interface,
+::
+
+  int usb_alloc_streams(struct usb_interface *interface,
struct usb_host_endpoint **eps, unsigned int num_eps,
unsigned int num_streams, gfp_t mem_flags);
 
@@ -53,7 +58,7 @@ controller driver, and may change in the future.
 
 
 Picking new Stream IDs to use
-
+=
 
 Stream ID 0 is reserved, and should not be used to communicate with devices.  
If
 usb_alloc_streams() returns with a value of N, you may use streams 1 though N.
@@ -68,9 +73,9 @@ Clean up
 
 
 If a driver wishes to stop using streams to communicate with the device, it
-should call
+should call::
 
-void usb_free_streams(struct usb_interface *interface,
+  void usb_free_streams(struct usb_interface *interface,
struct usb_host_endpoint **eps, unsigned int num_eps,
gfp_t mem_flags);
 
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 5dfb04b2d730..6fe7611f7332 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -7,6 +7,7 @@ Linux USB API
usb
gadget
anchors
+   bulk-streams
writing_usb_driver
writing_musb_glue_layer
 
-- 
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

[PATCH v2 13/21] error-codes.rst: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/error-codes.rst | 205 +++
 Documentation/driver-api/usb/index.rst   |   1 +
 Documentation/usb/error-codes.txt| 175 ---
 3 files changed, 206 insertions(+), 175 deletions(-)
 create mode 100644 Documentation/driver-api/usb/error-codes.rst
 delete mode 100644 Documentation/usb/error-codes.txt

diff --git a/Documentation/driver-api/usb/error-codes.rst 
b/Documentation/driver-api/usb/error-codes.rst
new file mode 100644
index ..9c11a0fd16cb
--- /dev/null
+++ b/Documentation/driver-api/usb/error-codes.rst
@@ -0,0 +1,205 @@
+USB Error codes
+~~~
+
+:Revised: 2004-Oct-21
+
+This is the documentation of (hopefully) all possible error codes (and
+their interpretation) that can be returned from usbcore.
+
+Some of them are returned by the Host Controller Drivers (HCDs), which
+device drivers only see through usbcore.  As a rule, all the HCDs should
+behave the same except for transfer speed dependent behaviors and the
+way certain faults are reported.
+
+
+Error codes returned by :c:func:`usb_submit_urb`
+
+
+Non-USB-specific:
+
+
+=== ===
+0  URB submission went fine
+
+``-ENOMEM``no memory for allocation of internal structures
+=== ===
+
+USB-specific:
+
+===
===
+``-EBUSY`` The URB is already active.
+
+``-ENODEV``specified USB-device or bus doesn't exist
+
+``-ENOENT``specified interface or endpoint does not exist or
+   is not enabled
+
+``-ENXIO`` host controller driver does not support queuing of
+   this type of urb.  (treat as a host controller bug.)
+
+``-EINVAL``a) Invalid transfer type specified (or not supported)
+   b) Invalid or unsupported periodic transfer interval
+   c) ISO: attempted to change transfer interval
+   d) ISO: ``number_of_packets`` is < 0
+   e) various other cases
+
+``-EXDEV`` ISO: ``URB_ISO_ASAP`` wasn't specified and all the
+   frames the URB would be scheduled in have already
+   expired.
+
+``-EFBIG`` Host controller driver can't schedule that many ISO
+   frames.
+
+``-EPIPE`` The pipe type specified in the URB doesn't match the
+   endpoint's actual type.
+
+``-EMSGSIZE``  (a) endpoint maxpacket size is zero; it is not usable
+   in the current interface altsetting.
+   (b) ISO packet is larger than the endpoint maxpacket.
+   (c) requested data transfer length is invalid: negative
+   or too large for the host controller.
+
+``-ENOSPC``This request would overcommit the usb bandwidth reserved
+   for periodic transfers (interrupt, isochronous).
+
+``-ESHUTDOWN`` The device or host controller has been disabled due to
+   some problem that could not be worked around.
+
+``-EPERM`` Submission failed because ``urb->reject`` was set.
+
+``-EHOSTUNREACH``  URB was rejected because the device is suspended.
+
+``-ENOEXEC``   A control URB doesn't contain a Setup packet.
+===
===
+
+Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` 
(for ISO)
+===
+
+USB device drivers may only test urb status values in completion handlers.
+This is because otherwise there would be a race between HCDs updating
+these values on one CPU, and device drivers testing them on another CPU.
+
+A transfer's actual_length may be positive even when an error has been
+reported.  That's because transfers often involve several packets, so that
+one or more packets could finish before an error stops further endpoint I/O.
+
+For isochronous URBs, the urb status value is non-zero only if the URB is
+unlinked, the device is removed, the host controller is disabled, or the total
+transferred length is less than the requested length and the
+``URB_SHORT_NOT_OK`` flag is set.  Completion handlers for isochronous URBs
+should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``,
+``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame descriptor status fields
+may report more status codes.
+
+
+===
=

[PATCH v2 06/21] writing_usb_driver.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

The pandoc conversion is not perfect. Do handwork in order to:

- add a title to this chapter;
- adjust function and struct references;
- use monospaced fonts for C code names;
- some other minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../driver-api/usb/writing_usb_driver.rst  | 182 ++---
 1 file changed, 82 insertions(+), 100 deletions(-)

diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst 
b/Documentation/driver-api/usb/writing_usb_driver.rst
index c18dbd74152b..69f077dcdb78 100644
--- a/Documentation/driver-api/usb/writing_usb_driver.rst
+++ b/Documentation/driver-api/usb/writing_usb_driver.rst
@@ -1,3 +1,5 @@
+.. _writing-usb-driver:
+
 ==
 Writing USB Device Drivers
 ==
@@ -48,25 +50,23 @@ The first thing a Linux USB driver needs to do is register 
itself with
 the Linux USB subsystem, giving it some information about which devices
 the driver supports and which functions to call when a device supported
 by the driver is inserted or removed from the system. All of this
-information is passed to the USB subsystem in the usb_driver structure.
-The skeleton driver declares a usb_driver as:
-
-::
+information is passed to the USB subsystem in the :c:type:`usb_driver`
+structure. The skeleton driver declares a :c:type:`usb_driver` as::
 
 static struct usb_driver skel_driver = {
-.name= "skeleton",
-.probe   = skel_probe,
-.disconnect  = skel_disconnect,
-.fops= &skel_fops,
-.minor   = USB_SKEL_MINOR_BASE,
-.id_table= skel_table,
+   .name= "skeleton",
+   .probe   = skel_probe,
+   .disconnect  = skel_disconnect,
+   .fops= &skel_fops,
+   .minor   = USB_SKEL_MINOR_BASE,
+   .id_table= skel_table,
 };
 
 
 The variable name is a string that describes the driver. It is used in
 informational messages printed to the system log. The probe and
 disconnect function pointers are called when a device that matches the
-information provided in the id_table variable is either seen or
+information provided in the ``id_table`` variable is either seen or
 removed.
 
 The fops and minor variables are optional. Most USB drivers hook into
@@ -76,78 +76,70 @@ subsystem, and any user-space interactions are provided 
through that
 interface. But for drivers that do not have a matching kernel subsystem,
 such as MP3 players or scanners, a method of interacting with user space
 is needed. The USB subsystem provides a way to register a minor device
-number and a set of file_operations function pointers that enable this
-user-space interaction. The skeleton driver needs this kind of
+number and a set of :c:type:`file_operations` function pointers that enable
+this user-space interaction. The skeleton driver needs this kind of
 interface, so it provides a minor starting number and a pointer to its
-file_operations functions.
+:c:type:`file_operations` functions.
 
-The USB driver is then registered with a call to usb_register, usually
-in the driver's init function, as shown here:
-
-::
+The USB driver is then registered with a call to :c:func:`usb_register`,
+usually in the driver's init function, as shown here::
 
 static int __init usb_skel_init(void)
 {
-int result;
+   int result;
 
-/* register this driver with the USB subsystem */
-result = usb_register(&skel_driver);
-if (result < 0) {
-err("usb_register failed for the "__FILE__ "driver."
-"Error number %d", result);
-return -1;
-}
+   /* register this driver with the USB subsystem */
+   result = usb_register(&skel_driver);
+   if (result < 0) {
+   err("usb_register failed for the "__FILE__ "driver."
+   "Error number %d", result);
+   return -1;
+   }
 
-return 0;
+   return 0;
 }
 module_init(usb_skel_init);
 
 
 When the driver is unloaded from the system, it needs to deregister
-itself with the USB subsystem. This is done with the usb_deregister
-function:
-
-::
+itself with the USB subsystem. This is done with the :c:func:`usb_deregister`
+function::
 
 static void __exit usb_skel_exit(void)
 {
-/* deregister this driver with the USB subsystem */
-usb_deregister(&skel_driver);
+   /* deregister this driver with the USB subsystem */
+   usb_deregister(&skel_driver);
 }
 module_exit(usb_skel_exit);
 
 
 To enable the linux-hotplug system to load the driver automatically when
-the device is plugged in, you need to create a MODULE_DEVICE_TABLE.
+the device is plugged in, you need to create a ``MODULE_DEVICE_TABLE``.
 The following 

Re: [PATCH v2 01/22] tmplcvt: make the tool more robust

[Mauro Carvalho Chehab]

Em Sun, 2 Apr 2017 15:32:31 -0600
Jonathan Corbet  escreveu:

> On Thu, 30 Mar 2017 07:45:35 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > Currently, the script just assumes to be called at
> > Documentation/sphinx/. Change it to work on any directory,
> > and make it abort if something gets wrong.
> > 
> > Also, be sure that both parameters are specified.
> > 
> > That should avoid troubles like this:
> > 
> > $ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
> > sed: couldn't open file convert_template.sed: No such file or directory  
> 
> What's the status of this patch set?  I saw that Jani had one comment
> that, I think, hasn't been addressed?

I'm resending it today, rebased on the top of docs-next.

I'll send the last patch in separate, as it is unrelated to the
doc conversion.

Regards,
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

Re: [PATCH v2 35/37] input: add a EV_SW event for ratchet switch

[Peter Hutterer]

On Tue, Apr 04, 2017 at 09:22:35AM -0300, Mauro Carvalho Chehab wrote:
> Some mouses have a switch on their wheel, allowing to switch

isnt' the plural of mouse mice? (non-native english speaker myself)

> between ratchet or free wheel mode. Add support for it.

s/or/and/

> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/input/event-codes.rst| 16 
>  include/linux/mod_devicetable.h|  2 +-
>  include/uapi/linux/input-event-codes.h |  4 +++-
>  3 files changed, 20 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/input/event-codes.rst 
> b/Documentation/input/event-codes.rst
> index 0c8591d39bc6..93f14f0ddb3d 100644
> --- a/Documentation/input/event-codes.rst
> +++ b/Documentation/input/event-codes.rst
> @@ -239,6 +239,22 @@ Upon resume, if the switch state is the same as before 
> suspend, then the input
>  subsystem will filter out the duplicate switch state reports. The driver does
>  not need to keep the state of the switch at any time.
>  
> +A few EV_SW codes have special meanings:
> +
> +* SW_RATCHET:
> +
> +  - Some mouses have a special switch at their wheel that allows to change
> +from free wheel mode to ratchet mode.

"between free wheel mode and ratchet mode"

> +
> +When such switch is ratchet mode (ON state), the wheel will offer some

s/such/the/

> +resistance for movements movement. It will also provide a tactile
> +feedback when scrolled.

this is too specific, you cannot guarantee that all devices in the future
have exactly that behaviour. I would just skip the second sentence.

> +
> +When pressed while in ratchet mode, the wheel will switch to free wheel
> +mode (OFF state). In this mode, it will offer no resistance to wheel
> +movements nor any tactile feedback. Pressing again returns to ratchet
> +mode.

nack to this, this is your device but not all future devices will have this
behaviour. e.g. some devices have the ratchet switch below (i.e. south of)
the weel. Just describe the effect the switch has, not the physical
behaviour.

Cheers,
   Peter

> +
>  EV_MSC
>  --
>  
> diff --git a/include/linux/mod_devicetable.h b/include/linux/mod_devicetable.h
> index 8850fcaf50db..038cddf1436a 100644
> --- a/include/linux/mod_devicetable.h
> +++ b/include/linux/mod_devicetable.h
> @@ -292,7 +292,7 @@ struct pcmcia_device_id {
>  #define INPUT_DEVICE_ID_LED_MAX  0x0f
>  #define INPUT_DEVICE_ID_SND_MAX  0x07
>  #define INPUT_DEVICE_ID_FF_MAX   0x7f
> -#define INPUT_DEVICE_ID_SW_MAX   0x0f
> +#define INPUT_DEVICE_ID_SW_MAX   0x1f
>  
>  #define INPUT_DEVICE_ID_MATCH_BUS1
>  #define INPUT_DEVICE_ID_MATCH_VENDOR 2
> diff --git a/include/uapi/linux/input-event-codes.h 
> b/include/uapi/linux/input-event-codes.h
> index 23b2d377af59..a3eafd0527f1 100644
> --- a/include/uapi/linux/input-event-codes.h
> +++ b/include/uapi/linux/input-event-codes.h
> @@ -782,7 +782,9 @@
>  #define SW_LINEIN_INSERT 0x0d  /* set = inserted */
>  #define SW_MUTE_DEVICE   0x0e  /* set = device disabled */
>  #define SW_PEN_INSERTED  0x0f  /* set = pen inserted */
> -#define SW_MAX   0x0f
> +#define SW_RATCHET   0x10  /* set = ratchet mode,
> +  unset: free wheel */
> +#define SW_MAX   0x1f
>  #define SW_CNT   (SW_MAX+1)
>  
>  /*
> -- 
> 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

[PATCH v6 20/23] tools: PCI: Add sample test script to invoke pcitest

[Kishon Vijay Abraham I]

Add a simple test script that invokes the pcitest userspace tool to perform
all the PCI endpoint tests (BAR tests, interrupt tests, read tests, write
tests and copy tests).

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 tools/pci/pcitest.sh | 56 
 1 file changed, 56 insertions(+)
 create mode 100644 tools/pci/pcitest.sh

diff --git a/tools/pci/pcitest.sh b/tools/pci/pcitest.sh
new file mode 100644
index ..5442bbea4c22
--- /dev/null
+++ b/tools/pci/pcitest.sh
@@ -0,0 +1,56 @@
+#!/bin/sh
+
+echo "BAR tests"
+echo
+
+bar=0
+
+while [ $bar -lt 6 ]
+do
+   pcitest -b $bar
+   bar=`expr $bar + 1`
+done
+echo
+
+echo "Interrupt tests"
+echo
+
+pcitest -l
+msi=1
+
+while [ $msi -lt 33 ]
+do
+pcitest -m $msi
+msi=`expr $msi + 1`
+done
+echo
+
+echo "Read Tests"
+echo
+
+pcitest -r -s 1
+pcitest -r -s 1024
+pcitest -r -s 1025
+pcitest -r -s 1024000
+pcitest -r -s 1024001
+echo
+
+echo "Write Tests"
+echo
+
+pcitest -w -s 1
+pcitest -w -s 1024
+pcitest -w -s 1025
+pcitest -w -s 1024000
+pcitest -w -s 1024001
+echo
+
+echo "Copy Tests"
+echo
+
+pcitest -c -s 1
+pcitest -c -s 1024
+pcitest -c -s 1025
+pcitest -c -s 1024000
+pcitest -c -s 1024001
+echo
-- 
2.11.0

--
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 v6 19/23] tools: PCI: Add a userspace tool to test PCI endpoint

[Kishon Vijay Abraham I]

Add a userspace tool to invoke the ioctls exposed by the PCI endpoint test
driver to perform various PCI tests.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 tools/pci/pcitest.c | 186 
 1 file changed, 186 insertions(+)
 create mode 100644 tools/pci/pcitest.c

diff --git a/tools/pci/pcitest.c b/tools/pci/pcitest.c
new file mode 100644
index ..ad54a58d7dda
--- /dev/null
+++ b/tools/pci/pcitest.c
@@ -0,0 +1,186 @@
+/**
+ * Userspace PCI Endpoint Test Module
+ *
+ * Copyright (C) 2017 Texas Instruments
+ * Author: Kishon Vijay Abraham I 
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 of
+ * the License 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, see .
+ */
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include 
+
+#define BILLION 1E9
+
+static char *result[] = { "NOT OKAY", "OKAY" };
+
+struct pci_test {
+   char*device;
+   charbarnum;
+   boollegacyirq;
+   unsigned intmsinum;
+   boolread;
+   boolwrite;
+   boolcopy;
+   unsigned long   size;
+};
+
+static int run_test(struct pci_test *test)
+{
+   long ret;
+   int fd;
+   struct timespec start, end;
+   double time;
+
+   fd = open(test->device, O_RDWR);
+   if (fd < 0) {
+   perror("can't open PCI Endpoint Test device");
+   return fd;
+   }
+
+   if (test->barnum >= 0 && test->barnum <= 5) {
+   ret = ioctl(fd, PCITEST_BAR, test->barnum);
+   fprintf(stdout, "BAR%d:\t\t", test->barnum);
+   if (ret < 0)
+   fprintf(stdout, "TEST FAILED\n");
+   else
+   fprintf(stdout, "%s\n", result[ret]);
+   }
+
+   if (test->legacyirq) {
+   ret = ioctl(fd, PCITEST_LEGACY_IRQ, 0);
+   fprintf(stdout, "LEGACY IRQ:\t");
+   if (ret < 0)
+   fprintf(stdout, "TEST FAILED\n");
+   else
+   fprintf(stdout, "%s\n", result[ret]);
+   }
+
+   if (test->msinum > 0 && test->msinum <= 32) {
+   ret = ioctl(fd, PCITEST_MSI, test->msinum);
+   fprintf(stdout, "MSI%d:\t\t", test->msinum);
+   if (ret < 0)
+   fprintf(stdout, "TEST FAILED\n");
+   else
+   fprintf(stdout, "%s\n", result[ret]);
+   }
+
+   if (test->write) {
+   ret = ioctl(fd, PCITEST_WRITE, test->size);
+   fprintf(stdout, "WRITE (%7ld bytes):\t\t", test->size);
+   if (ret < 0)
+   fprintf(stdout, "TEST FAILED\n");
+   else
+   fprintf(stdout, "%s\n", result[ret]);
+   }
+
+   if (test->read) {
+   ret = ioctl(fd, PCITEST_READ, test->size);
+   fprintf(stdout, "READ (%7ld bytes):\t\t", test->size);
+   if (ret < 0)
+   fprintf(stdout, "TEST FAILED\n");
+   else
+   fprintf(stdout, "%s\n", result[ret]);
+   }
+
+   if (test->copy) {
+   ret = ioctl(fd, PCITEST_COPY, test->size);
+   fprintf(stdout, "COPY (%7ld bytes):\t\t", test->size);
+   if (ret < 0)
+   fprintf(stdout, "TEST FAILED\n");
+   else
+   fprintf(stdout, "%s\n", result[ret]);
+   }
+
+   fflush(stdout);
+}
+
+int main(int argc, char **argv)
+{
+   int c;
+   struct pci_test *test;
+
+   test = calloc(1, sizeof(*test));
+   if (!test) {
+   perror("Fail to allocate memory for pci_test\n");
+   return -ENOMEM;
+   }
+
+   /* since '0' is a valid BAR number, initialize it to -1 */
+   test->barnum = -1;
+
+   /* set default size as 100KB */
+   test->size = 0x19000;
+
+   /* set default endpoint device */
+   test->device = "/dev/pci-endpoint-test.0";
+
+   while ((c = getopt(argc, argv, "D:b:m:lrwcs:")) != EOF)
+   switch (c) {
+   case 'D':
+   test->device = optarg;
+   continue;
+   case 'b':
+   test->barnum = atoi(optarg);
+   if (test->barnum < 0 || test->barnum > 5)
+   goto usage;
+   continue;
+   case 'l':
+   test

[PATCH v6 09/23] PCI: dwc: designware: Add EP mode support

[Kishon Vijay Abraham I]

Add endpoint mode support to designware driver. This uses the EP Core layer
introduced recently to add endpoint mode support.  *Any* function driver
can now use this designware device in order to achieve the EP
functionality.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 drivers/pci/dwc/Kconfig  |   5 +
 drivers/pci/dwc/Makefile |   1 +
 drivers/pci/dwc/pcie-designware-ep.c | 342 +++
 drivers/pci/dwc/pcie-designware.c| 125 +
 drivers/pci/dwc/pcie-designware.h| 105 +++
 5 files changed, 578 insertions(+)
 create mode 100644 drivers/pci/dwc/pcie-designware-ep.c

diff --git a/drivers/pci/dwc/Kconfig b/drivers/pci/dwc/Kconfig
index d2d2ba5b8a68..d37ea72a846a 100644
--- a/drivers/pci/dwc/Kconfig
+++ b/drivers/pci/dwc/Kconfig
@@ -9,6 +9,11 @@ config PCIE_DW_HOST
depends on PCI_MSI_IRQ_DOMAIN
 select PCIE_DW
 
+config PCIE_DW_EP
+   bool
+   depends on PCI_ENDPOINT
+   select PCIE_DW
+
 config PCI_DRA7XX
bool "TI DRA7xx PCIe controller"
depends on PCI
diff --git a/drivers/pci/dwc/Makefile b/drivers/pci/dwc/Makefile
index a2df13c28798..b38425d36200 100644
--- a/drivers/pci/dwc/Makefile
+++ b/drivers/pci/dwc/Makefile
@@ -1,5 +1,6 @@
 obj-$(CONFIG_PCIE_DW) += pcie-designware.o
 obj-$(CONFIG_PCIE_DW_HOST) += pcie-designware-host.o
+obj-$(CONFIG_PCIE_DW_EP) += pcie-designware-ep.o
 obj-$(CONFIG_PCIE_DW_PLAT) += pcie-designware-plat.o
 obj-$(CONFIG_PCI_DRA7XX) += pci-dra7xx.o
 obj-$(CONFIG_PCI_EXYNOS) += pci-exynos.o
diff --git a/drivers/pci/dwc/pcie-designware-ep.c 
b/drivers/pci/dwc/pcie-designware-ep.c
new file mode 100644
index ..398406393f37
--- /dev/null
+++ b/drivers/pci/dwc/pcie-designware-ep.c
@@ -0,0 +1,342 @@
+/**
+ * Synopsys Designware PCIe Endpoint controller driver
+ *
+ * Copyright (C) 2017 Texas Instruments
+ * Author: Kishon Vijay Abraham I 
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 of
+ * the License 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, see .
+ */
+
+#include 
+
+#include "pcie-designware.h"
+#include 
+#include 
+
+void dw_pcie_ep_linkup(struct dw_pcie_ep *ep)
+{
+   struct pci_epc *epc = ep->epc;
+
+   pci_epc_linkup(epc);
+}
+
+static void dw_pcie_ep_reset_bar(struct dw_pcie *pci, enum pci_barno bar)
+{
+   u32 reg;
+
+   reg = PCI_BASE_ADDRESS_0 + (4 * bar);
+   dw_pcie_writel_dbi2(pci, reg, 0x0);
+   dw_pcie_writel_dbi(pci, reg, 0x0);
+}
+
+static int dw_pcie_ep_write_header(struct pci_epc *epc,
+  struct pci_epf_header *hdr)
+{
+   struct dw_pcie_ep *ep = epc_get_drvdata(epc);
+   struct dw_pcie *pci = to_dw_pcie_from_ep(ep);
+
+   dw_pcie_writew_dbi(pci, PCI_VENDOR_ID, hdr->vendorid);
+   dw_pcie_writew_dbi(pci, PCI_DEVICE_ID, hdr->deviceid);
+   dw_pcie_writeb_dbi(pci, PCI_REVISION_ID, hdr->revid);
+   dw_pcie_writeb_dbi(pci, PCI_CLASS_PROG, hdr->progif_code);
+   dw_pcie_writew_dbi(pci, PCI_CLASS_DEVICE,
+  hdr->subclass_code | hdr->baseclass_code << 8);
+   dw_pcie_writeb_dbi(pci, PCI_CACHE_LINE_SIZE,
+  hdr->cache_line_size);
+   dw_pcie_writew_dbi(pci, PCI_SUBSYSTEM_VENDOR_ID,
+  hdr->subsys_vendor_id);
+   dw_pcie_writew_dbi(pci, PCI_SUBSYSTEM_ID, hdr->subsys_id);
+   dw_pcie_writeb_dbi(pci, PCI_INTERRUPT_PIN,
+  hdr->interrupt_pin);
+
+   return 0;
+}
+
+static int dw_pcie_ep_inbound_atu(struct dw_pcie_ep *ep, enum pci_barno bar,
+ dma_addr_t cpu_addr,
+ enum dw_pcie_as_type as_type)
+{
+   int ret;
+   u32 free_win;
+   struct dw_pcie *pci = to_dw_pcie_from_ep(ep);
+
+   free_win = find_first_zero_bit(&ep->ib_window_map,
+  sizeof(ep->ib_window_map));
+   if (free_win >= ep->num_ib_windows) {
+   dev_err(pci->dev, "no free inbound window\n");
+   return -EINVAL;
+   }
+
+   ret = dw_pcie_prog_inbound_atu(pci, free_win, bar, cpu_addr,
+  as_type);
+   if (ret < 0) {
+   dev_err(pci->dev, "Failed to program IB window\n");
+   return ret;
+   }
+
+   ep->bar_to_atu[bar] = free_win;
+   set_bit(free_win, &ep->ib_window_map);
+
+   return 0;
+}
+
+static int dw_pcie_ep_outbound_atu(struct dw_pcie_ep *ep,

[PATCH v6 08/23] Documentation: PCI: Add binding documentation for pci-test endpoint function

[Kishon Vijay Abraham I]

Add binding documentation for pci-test endpoint function that helps in
adding and configuring pci-test endpoint function.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 Documentation/PCI/00-INDEX  |  2 ++
 .../PCI/endpoint/function/binding/pci-test.txt  | 17 +
 2 files changed, 19 insertions(+)
 create mode 100644 Documentation/PCI/endpoint/function/binding/pci-test.txt

diff --git a/Documentation/PCI/00-INDEX b/Documentation/PCI/00-INDEX
index ab35e4bbdb1c..2fc901a1c32e 100644
--- a/Documentation/PCI/00-INDEX
+++ b/Documentation/PCI/00-INDEX
@@ -18,3 +18,5 @@ endpoint/pci-endpoint-cfs.txt
- guide to use configfs to configure the PCI endpoint function.
 endpoint/pci-test-function.txt
- specification of *PCI test* function device.
+endpoint/function/binding/
+   - binding documentation for PCI endpoint function
diff --git a/Documentation/PCI/endpoint/function/binding/pci-test.txt 
b/Documentation/PCI/endpoint/function/binding/pci-test.txt
new file mode 100644
index ..3b68b955fb50
--- /dev/null
+++ b/Documentation/PCI/endpoint/function/binding/pci-test.txt
@@ -0,0 +1,17 @@
+PCI TEST ENDPOINT FUNCTION
+
+name: Should be "pci_epf_test" to bind to the pci_epf_test driver.
+
+Configurable Fields:
+vendorid: should be 0x104c
+deviceid: should be 0xb500 for DRA74x and 0xb501 for DRA72x
+revid   : don't care
+progif_code : don't care
+subclass_code   : don't care
+baseclass_code  : should be 0xff
+cache_line_size : don't care
+subsys_vendor_id : don't care
+subsys_id   : don't care
+interrupt_pin   : Should be 1 - INTA, 2 - INTB, 3 - INTC, 4 -INTD
+msi_interrupts  : Should be 1 to 32 depending on the number of MSI interrupts
+  to test
-- 
2.11.0

--
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 v6 23/23] ARM: DRA7: clockdomain: Change the CLKTRCTRL of CM_PCIE_CLKSTCTRL to SW_WKUP

[Kishon Vijay Abraham I]

The PCIe programming sequence in TRM suggests CLKSTCTRL of PCIe should be
set to SW_WKUP. There are no issues when CLKSTCTRL is set to HW_AUTO in RC
mode. However in EP mode, the host system is not able to access the
MEMSPACE and setting the CLKSTCTRL to SW_WKUP fixes it.

Acked-by: Tony Lindgren 
Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 arch/arm/mach-omap2/clockdomains7xx_data.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/arch/arm/mach-omap2/clockdomains7xx_data.c 
b/arch/arm/mach-omap2/clockdomains7xx_data.c
index 6c679659cda5..67ebff829cf2 100644
--- a/arch/arm/mach-omap2/clockdomains7xx_data.c
+++ b/arch/arm/mach-omap2/clockdomains7xx_data.c
@@ -524,7 +524,7 @@ static struct clockdomain pcie_7xx_clkdm = {
.dep_bit  = DRA7XX_PCIE_STATDEP_SHIFT,
.wkdep_srcs   = pcie_wkup_sleep_deps,
.sleepdep_srcs= pcie_wkup_sleep_deps,
-   .flags= CLKDM_CAN_HWSUP_SWSUP,
+   .flags= CLKDM_CAN_SWSUP,
 };
 
 static struct clockdomain atl_7xx_clkdm = {
-- 
2.11.0

--
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 v6 22/23] MAINTAINERS: Add PCI Endpoint maintainer

[Kishon Vijay Abraham I]

Add maintainer for the newly introduced PCI Endpoint framework.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 MAINTAINERS | 9 +
 1 file changed, 9 insertions(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index c265a5fe4848..15ed84389092 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9581,6 +9581,15 @@ F:   include/linux/pci*
 F: arch/x86/pci/
 F: arch/x86/kernel/quirks.c
 
+PCI ENDPOINT SUBSYSTEM
+M: Kishon Vijay Abraham I 
+L: linux-...@vger.kernel.org
+T: git 
git://git.kernel.org/pub/scm/linux/kernel/git/kishon/pci-endpoint.git
+S: Supported
+F: drivers/pci/endpoint/
+F: drivers/misc/pci_endpoint_test.c
+F: tools/pci/
+
 PCI DRIVER FOR ALTERA PCIE IP
 M: Ley Foon Tan 
 L: r...@lists.rocketboards.org (moderated for non-subscribers)
-- 
2.11.0

--
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 v6 03/23] PCI: endpoint: Introduce configfs entry for configuring EP functions

[Kishon Vijay Abraham I]

Introduce a new configfs entry to configure the EP function (like
configuring the standard configuration header entries) and to bind the EP
function with EP controller.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 drivers/pci/endpoint/Kconfig  |   9 +
 drivers/pci/endpoint/Makefile |   1 +
 drivers/pci/endpoint/pci-ep-cfs.c | 509 ++
 include/linux/pci-ep-cfs.h|  41 +++
 4 files changed, 560 insertions(+)
 create mode 100644 drivers/pci/endpoint/pci-ep-cfs.c
 create mode 100644 include/linux/pci-ep-cfs.h

diff --git a/drivers/pci/endpoint/Kconfig b/drivers/pci/endpoint/Kconfig
index a5442ace7077..c86bca9b7de3 100644
--- a/drivers/pci/endpoint/Kconfig
+++ b/drivers/pci/endpoint/Kconfig
@@ -17,4 +17,13 @@ config PCI_ENDPOINT
 
   If in doubt, say "N" to disable Endpoint support.
 
+config PCI_ENDPOINT_CONFIGFS
+   bool "PCI Endpoint Configfs Support"
+   depends on PCI_ENDPOINT
+   select CONFIGFS_FS
+   help
+  This will enable the configfs entry that can be used to
+  configure the endpoint function and used to bind the
+  function with a endpoint controller.
+
 endmenu
diff --git a/drivers/pci/endpoint/Makefile b/drivers/pci/endpoint/Makefile
index dc1bc16491e6..7219d51bb401 100644
--- a/drivers/pci/endpoint/Makefile
+++ b/drivers/pci/endpoint/Makefile
@@ -2,5 +2,6 @@
 # Makefile for PCI Endpoint Support
 #
 
+obj-$(CONFIG_PCI_ENDPOINT_CONFIGFS)+= pci-ep-cfs.o
 obj-$(CONFIG_PCI_ENDPOINT) += pci-epc-core.o pci-epf-core.o\
   pci-epc-mem.o
diff --git a/drivers/pci/endpoint/pci-ep-cfs.c 
b/drivers/pci/endpoint/pci-ep-cfs.c
new file mode 100644
index ..424fdd6ed1ca
--- /dev/null
+++ b/drivers/pci/endpoint/pci-ep-cfs.c
@@ -0,0 +1,509 @@
+/**
+ * configfs to configure the PCI endpoint
+ *
+ * Copyright (C) 2017 Texas Instruments
+ * Author: Kishon Vijay Abraham I 
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 of
+ * the License 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, see .
+ */
+
+#include 
+#include 
+
+#include 
+#include 
+#include 
+
+static struct config_group *functions_group;
+static struct config_group *controllers_group;
+
+struct pci_epf_group {
+   struct config_group group;
+   struct pci_epf *epf;
+};
+
+struct pci_epc_group {
+   struct config_group group;
+   struct pci_epc *epc;
+   bool start;
+   unsigned long function_num_map;
+};
+
+static inline struct pci_epf_group *to_pci_epf_group(struct config_item *item)
+{
+   return container_of(to_config_group(item), struct pci_epf_group, group);
+}
+
+static inline struct pci_epc_group *to_pci_epc_group(struct config_item *item)
+{
+   return container_of(to_config_group(item), struct pci_epc_group, group);
+}
+
+static ssize_t pci_epc_start_store(struct config_item *item, const char *page,
+  size_t len)
+{
+   int ret;
+   bool start;
+   struct pci_epc *epc;
+   struct pci_epc_group *epc_group = to_pci_epc_group(item);
+
+   epc = epc_group->epc;
+
+   ret = kstrtobool(page, &start);
+   if (ret)
+   return ret;
+
+   if (!start) {
+   pci_epc_stop(epc);
+   return len;
+   }
+
+   ret = pci_epc_start(epc);
+   if (ret) {
+   dev_err(&epc->dev, "failed to start endpoint controller\n");
+   return -EINVAL;
+   }
+
+   epc_group->start = start;
+
+   return len;
+}
+
+static ssize_t pci_epc_start_show(struct config_item *item, char *page)
+{
+   return sprintf(page, "%d\n",
+  to_pci_epc_group(item)->start);
+}
+
+CONFIGFS_ATTR(pci_epc_, start);
+
+static struct configfs_attribute *pci_epc_attrs[] = {
+   &pci_epc_attr_start,
+   NULL,
+};
+
+static int pci_epc_epf_link(struct config_item *epc_item,
+   struct config_item *epf_item)
+{
+   int ret;
+   u32 func_no = 0;
+   struct pci_epc *epc;
+   struct pci_epf *epf;
+   struct pci_epf_group *epf_group = to_pci_epf_group(epf_item);
+   struct pci_epc_group *epc_group = to_pci_epc_group(epc_item);
+
+   epc = epc_group->epc;
+   epf = epf_group->epf;
+   ret = pci_epc_add_epf(epc, epf);
+   if (ret)
+   goto err_add_epf;
+
+   func_no = find_first_zero_bit(&epc_group->function_num_map,
+ size

[PATCH v6 13/23] dt-bindings: PCI: dra7xx: Add DT bindings for PCI dra7xx EP mode

[Kishon Vijay Abraham I]

Add device tree binding documentation for PCI dra7xx EP mode.

Acked-by: Rob Herring 
Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 Documentation/devicetree/bindings/pci/ti-pci.txt | 37 +++-
 1 file changed, 30 insertions(+), 7 deletions(-)

diff --git a/Documentation/devicetree/bindings/pci/ti-pci.txt 
b/Documentation/devicetree/bindings/pci/ti-pci.txt
index 60e25161f351..60c3cccefabc 100644
--- a/Documentation/devicetree/bindings/pci/ti-pci.txt
+++ b/Documentation/devicetree/bindings/pci/ti-pci.txt
@@ -1,17 +1,22 @@
 TI PCI Controllers
 
 PCIe Designware Controller
- - compatible: Should be "ti,dra7-pcie""
- - reg : Two register ranges as listed in the reg-names property
- - reg-names : The first entry must be "ti-conf" for the TI specific registers
-  The second entry must be "rc-dbics" for the designware pcie
-  registers
-  The third entry must be "config" for the PCIe configuration space
+ - compatible: Should be "ti,dra7-pcie" for RC
+  Should be "ti,dra7-pcie-ep" for EP
  - phys : list of PHY specifiers (used by generic PHY framework)
  - phy-names : must be "pcie-phy0", "pcie-phy1", "pcie-phyN".. based on the
   number of PHYs as specified in *phys* property.
  - ti,hwmods : Name of the hwmod associated to the pcie, "pcie",
   where  is the instance number of the pcie from the HW spec.
+ - num-lanes as specified in ../designware-pcie.txt
+
+HOST MODE
+=
+ - reg : Two register ranges as listed in the reg-names property
+ - reg-names : The first entry must be "ti-conf" for the TI specific registers
+  The second entry must be "rc-dbics" for the DesignWare PCIe
+  registers
+  The third entry must be "config" for the PCIe configuration space
  - interrupts : Two interrupt entries must be specified. The first one is for
main interrupt line and the second for MSI interrupt line.
  - #address-cells,
@@ -19,13 +24,31 @@ PCIe Designware Controller
#interrupt-cells,
device_type,
ranges,
-   num-lanes,
interrupt-map-mask,
interrupt-map : as specified in ../designware-pcie.txt
 
+DEVICE MODE
+===
+ - reg : Four register ranges as listed in the reg-names property
+ - reg-names : "ti-conf" for the TI specific registers
+  "ep_dbics" for the standard configuration registers as
+   they are locally accessed within the DIF CS space
+  "ep_dbics2" for the standard configuration registers as
+   they are locally accessed within the DIF CS2 space
+  "addr_space" used to map remote RC address space
+ - interrupts : one interrupt entries must be specified for main interrupt.
+ - num-ib-windows : number of inbound address translation windows
+ - num-ob-windows : number of outbound address translation windows
+
 Optional Property:
  - gpios : Should be added if a gpio line is required to drive PERST# line
 
+NOTE: Two DT nodes may be added for each PCI controller; one for host
+mode and another for device mode. So in order for PCI to
+work in host mode, EP mode DT node should be disabled and in order to PCI to
+work in EP mode, host mode DT node should be disabled. Host mode and EP
+mode are mutually exclusive.
+
 Example:
 axi {
compatible = "simple-bus";
-- 
2.11.0

--
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 v6 12/23] PCI: dwc: dra7xx: Add EP mode support

[Kishon Vijay Abraham I]

The PCIe controller integrated in dra7xx SoCs is capable of operating in
endpoint mode. Add endpoint mode support to dra7xx driver.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 drivers/pci/dwc/Kconfig   |  31 +-
 drivers/pci/dwc/Makefile  |   4 +-
 drivers/pci/dwc/pci-dra7xx.c  | 197 +++---
 drivers/pci/dwc/pcie-designware.h |   7 ++
 4 files changed, 221 insertions(+), 18 deletions(-)

diff --git a/drivers/pci/dwc/Kconfig b/drivers/pci/dwc/Kconfig
index d37ea72a846a..b7e15526d676 100644
--- a/drivers/pci/dwc/Kconfig
+++ b/drivers/pci/dwc/Kconfig
@@ -16,14 +16,37 @@ config PCIE_DW_EP
 
 config PCI_DRA7XX
bool "TI DRA7xx PCIe controller"
-   depends on PCI
+   depends on (PCI && PCI_MSI_IRQ_DOMAIN) || PCI_ENDPOINT
depends on OF && HAS_IOMEM && TI_PIPE3
+   help
+Enables support for the PCIe controller in the DRA7xx SoC. There
+are two instances of PCIe controller in DRA7xx. This controller can
+work either as EP or RC. In order to enable host-specific features
+PCI_DRA7XX_HOST must be selected and in order to enable device-
+specific features PCI_DRA7XX_EP must be selected. This uses
+the Designware core.
+
+if PCI_DRA7XX
+
+config PCI_DRA7XX_HOST
+   bool "PCI DRA7xx Host Mode"
+   depends on PCI
depends on PCI_MSI_IRQ_DOMAIN
select PCIE_DW_HOST
+   default y
help
-Enables support for the PCIe controller in the DRA7xx SoC.  There
-are two instances of PCIe controller in DRA7xx.  This controller can
-act both as EP and RC.  This reuses the Designware core.
+Enables support for the PCIe controller in the DRA7xx SoC to work in
+host mode.
+
+config PCI_DRA7XX_EP
+   bool "PCI DRA7xx Endpoint Mode"
+   depends on PCI_ENDPOINT
+   select PCIE_DW_EP
+   help
+Enables support for the PCIe controller in the DRA7xx SoC to work in
+endpoint mode.
+
+endif
 
 config PCIE_DW_PLAT
bool "Platform bus based DesignWare PCIe Controller"
diff --git a/drivers/pci/dwc/Makefile b/drivers/pci/dwc/Makefile
index b38425d36200..f31a8596442a 100644
--- a/drivers/pci/dwc/Makefile
+++ b/drivers/pci/dwc/Makefile
@@ -2,7 +2,9 @@ obj-$(CONFIG_PCIE_DW) += pcie-designware.o
 obj-$(CONFIG_PCIE_DW_HOST) += pcie-designware-host.o
 obj-$(CONFIG_PCIE_DW_EP) += pcie-designware-ep.o
 obj-$(CONFIG_PCIE_DW_PLAT) += pcie-designware-plat.o
-obj-$(CONFIG_PCI_DRA7XX) += pci-dra7xx.o
+ifneq ($(filter y,$(CONFIG_PCI_DRA7XX_HOST) $(CONFIG_PCI_DRA7XX_EP)),)
+obj-$(CONFIG_PCI_DRA7XX) += pci-dra7xx.o
+endif
 obj-$(CONFIG_PCI_EXYNOS) += pci-exynos.o
 obj-$(CONFIG_PCI_IMX6) += pci-imx6.o
 obj-$(CONFIG_PCIE_SPEAR13XX) += pcie-spear13xx.o
diff --git a/drivers/pci/dwc/pci-dra7xx.c b/drivers/pci/dwc/pci-dra7xx.c
index d78974d20360..35c18534469c 100644
--- a/drivers/pci/dwc/pci-dra7xx.c
+++ b/drivers/pci/dwc/pci-dra7xx.c
@@ -10,12 +10,14 @@
  * published by the Free Software Foundation.
  */
 
+#include 
 #include 
 #include 
 #include 
 #include 
 #include 
 #include 
+#include 
 #include 
 #include 
 #include 
@@ -57,6 +59,11 @@
 #defineMSI BIT(4)
 #defineLEG_EP_INTERRUPTS (INTA | INTB | INTC | INTD)
 
+#definePCIECTRL_TI_CONF_DEVICE_TYPE0x0100
+#defineDEVICE_TYPE_EP  0x0
+#defineDEVICE_TYPE_LEG_EP  0x1
+#defineDEVICE_TYPE_RC  0x4
+
 #definePCIECTRL_DRA7XX_CONF_DEVICE_CMD 0x0104
 #defineLTSSM_EN0x1
 
@@ -66,6 +73,13 @@
 
 #define EXP_CAP_ID_OFFSET  0x70
 
+#definePCIECTRL_TI_CONF_INTX_ASSERT0x0124
+#definePCIECTRL_TI_CONF_INTX_DEASSERT  0x0128
+
+#definePCIECTRL_TI_CONF_MSI_XMT0x012c
+#define MSI_REQ_GRANT  BIT(0)
+#define MSI_VECTOR_SHIFT   7
+
 struct dra7xx_pcie {
struct dw_pcie  *pci;
void __iomem*base;  /* DT ti_conf */
@@ -73,6 +87,11 @@ struct dra7xx_pcie {
struct phy  **phy;
int link_gen;
struct irq_domain   *irq_domain;
+   enum dw_pcie_device_mode mode;
+};
+
+struct dra7xx_pcie_of_data {
+   enum dw_pcie_device_mode mode;
 };
 
 #define to_dra7xx_pcie(x)  dev_get_drvdata((x)->dev)
@@ -101,9 +120,19 @@ static int dra7xx_pcie_link_up(struct dw_pcie *pci)
return !!(reg & LINK_UP);
 }
 
-static int dra7xx_pcie_establish_link(struct dra7xx_pcie *dra7xx)
+static void dra7xx_pcie_stop_link(struct dw_pcie *pci)
 {
-   struct dw_pcie *pci = dra7xx->pci;
+   struct dra7xx_pcie *dra7xx = to_dra7xx_pcie(pci);
+   

[PATCH v6 15/23] dt-bindings: PCI: dra7xx: Add DT bindings to enable unaligned access

[Kishon Vijay Abraham I]

Update device tree binding documentation of TI's dra7xx PCI controller to
include property for enabling unaligned mem access.

Signed-off-by: Kishon Vijay Abraham I 
Acked-by: Rob Herring 
Signed-off-by: Bjorn Helgaas 
---
 Documentation/devicetree/bindings/pci/ti-pci.txt | 5 +
 1 file changed, 5 insertions(+)

diff --git a/Documentation/devicetree/bindings/pci/ti-pci.txt 
b/Documentation/devicetree/bindings/pci/ti-pci.txt
index 60c3cccefabc..6a07c96227e0 100644
--- a/Documentation/devicetree/bindings/pci/ti-pci.txt
+++ b/Documentation/devicetree/bindings/pci/ti-pci.txt
@@ -39,6 +39,11 @@ DEVICE MODE
  - interrupts : one interrupt entries must be specified for main interrupt.
  - num-ib-windows : number of inbound address translation windows
  - num-ob-windows : number of outbound address translation windows
+ - ti,syscon-unaligned-access: phandle to the syscon DT node. The 1st argument
+  should contain the register offset within syscon
+  and the 2nd argument should contain the bit field
+  for setting the bit to enable unaligned
+  access.
 
 Optional Property:
  - gpios : Should be added if a gpio line is required to drive PERST# line
-- 
2.11.0

--
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 v6 18/23] Documentation: misc-devices: Add Documentation for pci-endpoint-test driver

[Kishon Vijay Abraham I]

Add Documentation for pci-endpoint-test driver.

Signed-off-by: Kishon Vijay Abraham I 
Signed-off-by: Bjorn Helgaas 
---
 Documentation/misc-devices/pci-endpoint-test.txt | 35 
 1 file changed, 35 insertions(+)
 create mode 100644 Documentation/misc-devices/pci-endpoint-test.txt

diff --git a/Documentation/misc-devices/pci-endpoint-test.txt 
b/Documentation/misc-devices/pci-endpoint-test.txt
new file mode 100644
index ..4ebc3594b32c
--- /dev/null
+++ b/Documentation/misc-devices/pci-endpoint-test.txt
@@ -0,0 +1,35 @@
+Driver for PCI Endpoint Test Function
+
+This driver should be used as a host side driver if the root complex is
+connected to a configurable PCI endpoint running *pci_epf_test* function
+driver configured according to [1].
+
+The "pci_endpoint_test" driver can be used to perform the following tests.
+
+The PCI driver for the test device performs the following tests
+   *) verifying addresses programmed in BAR
+   *) raise legacy IRQ
+   *) raise MSI IRQ
+   *) read data
+   *) write data
+   *) copy data
+
+This misc driver creates /dev/pci-endpoint-test. for every
+*pci_epf_test* function connected to the root complex and "ioctls"
+should be used to perform the above tests.
+
+ioctl
+-
+ PCITEST_BAR: Tests the BAR. The number of the BAR to be tested
+ should be passed as argument.
+ PCITEST_LEGACY_IRQ: Tests legacy IRQ
+ PCITEST_MSI: Tests message signalled interrupts. The MSI number
+ to be tested should be passed as argument.
+ PCITEST_WRITE: Perform write tests. The size of the buffer should be passed
+   as argument.
+ PCITEST_READ: Perform read tests. The size of the buffer should be passed
+  as argument.
+ PCITEST_COPY: Perform read tests. The size of the buffer should be passed
+  as argument.
+
+[1] -> Documentation/PCI/endpoint/function/binding/pci-test.txt
-- 
2.11.0

--
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 v5 14/24] dt-bindings: mfd: syscon: Add documentation for #syscon-cells property

[Kishon Vijay Abraham I]

Hi Rob,

On Saturday 01 April 2017 12:36 AM, Rob Herring wrote:
> On Fri, Mar 31, 2017 at 01:58:52PM -0500, Rob Herring wrote:
>> On Mon, Mar 27, 2017 at 03:15:10PM +0530, Kishon Vijay Abraham I wrote:
>>> Add documentation for the optional #syscon-cells property to determine
>>> the number of cells that should be given in the phandle while
>>> referencing the syscon-node.
>>>
>>> Suggested-by: Rob Herring 
>>
>> I did? When?
>>
>> I'm not remembering why we need this. Generally, phandles to a syscon 
>> are for a single defined purpose. When do we need a list of them?
> 
> Ah, I remember now the context. I suggested using standard parsing 
> function rather than open coding. I wasn't suggesting changing the 
> binding. Instead of of_parse_phandle_with_args, can't 
> of_parse_phandle_with_fixed_args work?

yes, it can be used. Will change it my next revision.

Thanks
Kishon
--
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