Re: [PATCH v9 01/13] Documentation: Add SLIMbus summary

[Jonathan Corbet]

On Thu, 7 Dec 2017 23:22:51 +
Srinivas Kandagatla  wrote:

> > It seems you have kerneldoc comments for your data structures and at least
> > some of your exported symbols.  If you really want to document this stuff
> > well, I'd suggest finishing out those comments, then pulling them into the
> > documentation in the appropriate places.  
> Am sure all the exported symbols have kernel doc, I will pull them into 
> relevant sub sections.
> 
> Do you think something like this http://paste.ubuntu.com/26135862/ makes 
> sense?

At a first glance it looks good to me.

Thanks,

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

Re: [alsa-devel] [PATCH v9 01/13] Documentation: Add SLIMbus summary

[Srinivas Kandagatla]

On 08/12/17 08:44, Vinod Koul wrote:

Do we really need a separate subdirectory for a single file?


May be not, TBH, I did take some inspiration from soundwire patches.

FWIW, SoundWire patches have more Documentation. We have 4 files atm, though
they are not part of current series, so a directory looks apt for that


Yes, it does makes sense for soundwire!!
--
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: [alsa-devel] [PATCH v9 01/13] Documentation: Add SLIMbus summary

[Vinod Koul]

On Thu, Dec 07, 2017 at 11:22:51PM +, Srinivas Kandagatla wrote:
> Thankyou for taking time to review the patch,
> 
> On 07/12/17 17:32, Jonathan Corbet wrote:
> >On Thu,  7 Dec 2017 10:27:08 +
> >srinivas.kandaga...@linaro.org wrote:
> >
> >A couple of overall comments...
> >
> >>  Documentation/driver-api/index.rst   |   1 +
> >>  Documentation/driver-api/slimbus/index.rst   |  15 
> >>  Documentation/driver-api/slimbus/summary.rst | 106 
> >> +++
> >>  3 files changed, 122 insertions(+)
> >>  create mode 100644 Documentation/driver-api/slimbus/index.rst
> >>  create mode 100644 Documentation/driver-api/slimbus/summary.rst
> >
> >Do we really need a separate subdirectory for a single file?
> >
> May be not, TBH, I did take some inspiration from soundwire patches.

FWIW, SoundWire patches have more Documentation. We have 4 files atm, though
they are not part of current series, so a directory looks apt for that

> I can drop that in next version. We can think of adding directory if we end
> up adding more apis for the new features in future.
> 
> >It seems you have kerneldoc comments for your data structures and at least
> >some of your exported symbols.  If you really want to document this stuff
> >well, I'd suggest finishing out those comments, then pulling them into the
> >documentation in the appropriate places.
> Am sure all the exported symbols have kernel doc, I will pull them into
> relevant sub sections.
> 
> Do you think something like this http://paste.ubuntu.com/26135862/ makes
> sense?
> 
> thanks,
> srini
> >
> >Thanks,
> >
> >jon
> >
> ___
> Alsa-devel mailing list
> alsa-de...@alsa-project.org
> http://mailman.alsa-project.org/mailman/listinfo/alsa-devel

-- 
~Vinod
--
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 v9 01/13] Documentation: Add SLIMbus summary

[Srinivas Kandagatla]

Thankyou for taking time to review the patch,

On 07/12/17 17:32, Jonathan Corbet wrote:

On Thu,  7 Dec 2017 10:27:08 +
srinivas.kandaga...@linaro.org wrote:

A couple of overall comments...


  Documentation/driver-api/index.rst   |   1 +
  Documentation/driver-api/slimbus/index.rst   |  15 
  Documentation/driver-api/slimbus/summary.rst | 106 +++
  3 files changed, 122 insertions(+)
  create mode 100644 Documentation/driver-api/slimbus/index.rst
  create mode 100644 Documentation/driver-api/slimbus/summary.rst


Do we really need a separate subdirectory for a single file?


May be not, TBH, I did take some inspiration from soundwire patches.
I can drop that in next version. We can think of adding directory if we 
end up adding more apis for the new features in future.



It seems you have kerneldoc comments for your data structures and at least
some of your exported symbols.  If you really want to document this stuff
well, I'd suggest finishing out those comments, then pulling them into the
documentation in the appropriate places.
Am sure all the exported symbols have kernel doc, I will pull them into 
relevant sub sections.


Do you think something like this http://paste.ubuntu.com/26135862/ makes 
sense?


thanks,
srini


Thanks,

jon


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

Re: [PATCH v9 01/13] Documentation: Add SLIMbus summary

[Jonathan Corbet]

On Thu,  7 Dec 2017 10:27:08 +
srinivas.kandaga...@linaro.org wrote:

A couple of overall comments...

>  Documentation/driver-api/index.rst   |   1 +
>  Documentation/driver-api/slimbus/index.rst   |  15 
>  Documentation/driver-api/slimbus/summary.rst | 106 
> +++
>  3 files changed, 122 insertions(+)
>  create mode 100644 Documentation/driver-api/slimbus/index.rst
>  create mode 100644 Documentation/driver-api/slimbus/summary.rst

Do we really need a separate subdirectory for a single file?

It seems you have kerneldoc comments for your data structures and at least
some of your exported symbols.  If you really want to document this stuff
well, I'd suggest finishing out those comments, then pulling them into the
documentation in the appropriate places.

Thanks,

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

[PATCH v9 01/13] Documentation: Add SLIMbus summary

[srinivas . kandagatla]

From: Sagar Dharia 

SLIMbus (Serial Low Power Interchip Media Bus) is a specification
developed by MIPI (Mobile Industry Processor Interface) alliance.
SLIMbus is a 2-wire implementation, which is used to communicate with
peripheral components like audio-codec.

The summary of SLIMbus and API is documented in the 'summary' file.

Signed-off-by: Sagar Dharia 
Signed-off-by: Srinivas Kandagatla 
---
 Documentation/driver-api/index.rst   |   1 +
 Documentation/driver-api/slimbus/index.rst   |  15 
 Documentation/driver-api/slimbus/summary.rst | 106 +++
 3 files changed, 122 insertions(+)
 create mode 100644 Documentation/driver-api/slimbus/index.rst
 create mode 100644 Documentation/driver-api/slimbus/summary.rst

diff --git a/Documentation/driver-api/index.rst 
b/Documentation/driver-api/index.rst
index d17a9876b473..3de6097525f4 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -47,6 +47,7 @@ available subsections can be seen below.
gpio
misc_devices
dmaengine/index
+   slimbus/index
 
 .. only::  subproject and html
 
diff --git a/Documentation/driver-api/slimbus/index.rst 
b/Documentation/driver-api/slimbus/index.rst
new file mode 100644
index ..586f979659e6
--- /dev/null
+++ b/Documentation/driver-api/slimbus/index.rst
@@ -0,0 +1,15 @@
+=
+SLIMbus Documentation
+=
+
+.. toctree::
+   :maxdepth: 1
+
+   summary
+
+.. only::  subproject
+
+   Indices
+   ===
+
+   * :ref:`genindex`
diff --git a/Documentation/driver-api/slimbus/summary.rst 
b/Documentation/driver-api/slimbus/summary.rst
new file mode 100644
index ..9a296766dc46
--- /dev/null
+++ b/Documentation/driver-api/slimbus/summary.rst
@@ -0,0 +1,106 @@
+
+Linux kernel SLIMbus support
+
+
+Overview
+
+
+What is SLIMbus?
+
+SLIMbus (Serial Low Power Interchip Media Bus) is a specification developed by
+MIPI (Mobile Industry Processor Interface) alliance. The bus uses master/slave
+configuration, and is a 2-wire multi-drop implementation (clock, and data).
+
+Currently, SLIMbus is used to interface between application processors of SoCs
+(System-on-Chip) and peripheral components (typically codec). SLIMbus uses
+Time-Division-Multiplexing to accommodate multiple data channels, and
+a control channel.
+
+The control channel is used for various control functions such as bus
+management, configuration and status updates. These messages can be unicast 
(e.g.
+reading/writing device specific values), or multicast (e.g. data channel
+reconfiguration sequence is a broadcast message announced to all devices)
+
+A data channel is used for data-transfer between 2 SLIMbus devices. Data
+channel uses dedicated ports on the device.
+
+Hardware description:
+-
+SLIMbus specification has different types of device classifications based on
+their capabilities.
+A manager device is responsible for enumeration, configuration, and dynamic
+channel allocation. Every bus has 1 active manager.
+
+A generic device is a device providing application functionality (e.g. codec).
+
+Framer device is responsible for clocking the bus, and transmitting frame-sync
+and framing information on the bus.
+
+Each SLIMbus component has an interface device for monitoring physical layer.
+
+Typically each SoC contains SLIMbus component having 1 manager, 1 framer 
device,
+1 generic device (for data channel support), and 1 interface device.
+External peripheral SLIMbus component usually has 1 generic device (for
+functionality/data channel support), and an associated interface device.
+The generic device's registers are mapped as 'value elements' so that they can
+be written/read using SLIMbus control channel exchanging control/status type of
+information.
+In case there are multiple framer devices on the same bus, manager device is
+responsible to select the active-framer for clocking the bus.
+
+Per specification, SLIMbus uses "clock gears" to do power management based on
+current frequency and bandwidth requirements. There are 10 clock gears and each
+gear changes the SLIMbus frequency to be twice its previous gear.
+
+Each device has a 6-byte enumeration-address and the manager assigns every
+device with a 1-byte logical address after the devices report presence on the
+bus.
+
+Software description:
+-
+There are 2 types of SLIMbus drivers:
+
+slim_controller represents a 'controller' for SLIMbus. This driver should
+implement duties needed by the SoC (manager device, associated
+interface device for monitoring the layers and reporting errors, default
+framer device).
+
+slim_device represents the 'generic device/component' for SLIMbus, and a
+slim_driver should implement driver for that slim_device.
+
+Device notifications to the