[01/14] Documentation: Add SoundWire summary

Commit Message

Vinod Koul Oct. 19, 2017, 3:03 a.m. UTC

From: Sanyog Kale <[e-mail]>

SoundWire is a new Linux bus which implements a new MIPI bus protocol
'SoundWire'. The summary of SoundWire bus and registration APIs is
documented in the 'summary' file.

Signed-off-by: Sanyog Kale <[e-mail]>
Signed-off-by: Hardik T Shah <[e-mail]>
Signed-off-by: Pierre-Louis Bossart <[e-mail]>
Signed-off-by: Vinod Koul <[e-mail]>
---
 Documentation/soundwire/summary.txt | 192 ++++++++++++++++++++++++++++++++++++
 1 file changed, 192 insertions(+)
 create mode 100644 Documentation/soundwire/summary.txt

Comments

Randy Dunlap Oct. 19, 2017, 3:33 a.m. UTC | #1

On 10/18/17 20:03, Vinod Koul wrote:
> From: Sanyog Kale <[e-mail]>
> 
> SoundWire is a new Linux bus which implements a new MIPI bus protocol
> 'SoundWire'. The summary of SoundWire bus and registration APIs is
> documented in the 'summary' file.
> 
> Signed-off-by: Sanyog Kale <[e-mail]>
> Signed-off-by: Hardik T Shah <[e-mail]>
> Signed-off-by: Pierre-Louis Bossart <[e-mail]>
> Signed-off-by: Vinod Koul <[e-mail]>
> ---
>  Documentation/soundwire/summary.txt | 192 ++++++++++++++++++++++++++++++++++++
>  1 file changed, 192 insertions(+)
>  create mode 100644 Documentation/soundwire/summary.txt
> 
> diff --git a/Documentation/soundwire/summary.txt b/Documentation/soundwire/summary.txt
> new file mode 100644
> index 000000000000..15b78e6e3347
> --- /dev/null
> +++ b/Documentation/soundwire/summary.txt
> @@ -0,0 +1,192 @@
> +SoundWire
> +===========
> +
> +SoundWire is a new interface ratified in 2015 by the MIPI Alliance.
> +SoundWire is used for transporting data typically related to audio
> +functions. SoundWire interface is optimized to integrate audio devices in
> +mobile or mobile inspired systems.
> +
> +SoundWire is a 2-Pin multi-drop interface with data and clock line. It

                  2-pin

> +facilitates development of low cost, efficient, high performance systems.
> +Broad level key features of SoundWire interface include:
> +  1. Transporting all of payload data channels, control information, and setup
> +  commands over a single two-pin interface.
> +  2. Lower clock frequency, and hence lower power consumption, by use of DDR
> +  (Dual Data Rate) data transmission.
> +  3. Clock scaling and optional multiple data lanes to give wide flexibility
> +  in data rate to match system requirements.
> +  4. Device status monitoring, including interrupt-style alerts to the Master.
> +
> +The SoundWire protocol supports up to eleven Slave interfaces. All the
> +interfaces share the common Bus containing data and clock line. Each of the
> +Slaves can support up to 14 Data Ports. 13 Data Ports are dedicated to audio
> +transport. Data Port0 is dedicated to transport of Bulk control information,
> +each of the audio Data Ports (1..14) can support up to 8 Channels in

                                (1..13) ??

> +transmit or receiving mode (typically fixed direction but configurable
> +direction is enabled by the specification).  Bandwidth restrictions to
> +~19.2..24.576Mbits/s don't however allow for 11*13*8 channels to be
> +transmitted simultaneously.
> +
> +Below figure shows an example of connectivity between a SoundWire Master and
> +two Slave devices.
> +
> ++---------------+                                       +---------------+
> +|               |                       Clock Signal    |               |
> +|    Master     |-------+-------------------------------|    Slave      |
> +|   Interface   |       |               Data Signal     |  Interface 1  |
> +|               |-------|-------+-----------------------|               |
> ++---------------+       |       |                       +---------------+
> +                        |       |
> +                        |       |
> +                        |       |
> +                     +--+-------+--+
> +                     |             |
> +                     |   Slave     |
> +                     | Interface 2 |
> +                     |             |
> +                     +-------------+
> +
> +Terminology
> +=============
> +
> +The MIPI SoundWire specification uses the term 'device' to refer to a Master
> +or Slave interface, which of course can be confusing. In this summary and
> +code we use the term interface only to refer to the hardware. We follow the
> +Linux device model by mapping each Slave interface connected on the bus as a
> +device managed by a specific driver. The Linux SoundWire subsystem provides
> +a framework to implement a SoundWire Slave driver with an API allowing
> +3rd-party vendors to enable implementation-defined functionality while
> +common setup/configuration tasks are handled by the bus.
> +
> +Bus:
> +Implements SoundWire Linux Bus which handles the SoundWire protocol.
> +It programs all the MIPI defined Slave registers. It represents a SoundWire

                       MIPI-defined

> +Master. There can be multiple instances of Bus maybe present in a system.

eh?
           Multiple instances of Bus may be present in a system.

> +
> +Slave:
> +Registers as SoundWire Slave device (Linux Device). Multiple Slave devices
> +can register to a Bus instance.
> +
> +Slave driver:
> +Driver controlling the Slave device. MIPI-specified registers are controlled
> +directly by the Bus (and transmitted through the Master driver/interface).
> +Any implementation-defined Slave register is controlled by Slave driver. In
> +practice, it is expected that the Slave driver relies on regmap and does not
> +request direct register access.
> +
> +Programming interfaces (SoundWire Master interface Driver)
> +==========================================================
> +
> +SoundWire Bus supports programming interfaces for the SoundWire Master
> +implementation and SoundWire Slave devices. All the code uses the "sdw"
> +prefix commonly used by SoC designers and 3rd party vendors.
> +
> +Each of the SoundWire Master interfaces needs to be registered to the Bus.
> +Bus implements API to read standard Master MIPI properties and also provides
> +callback in Master ops for Master driver to implement own functions that
> +provides capabilities information. DT support is not implemented at this
> +time but should be trivial to add since capabilities are enabled with the
> +device_property_ API.
> +
> +The Master interface along with the Master interface capabilities are
> +registered based on board file, DT or ACPI.
> +
> +Following is the Bus API to register the SoundWire Bus.
> +
> +int sdw_add_bus_master(struct sdw_bus *bus)
> +{
> +        if (!bus->dev)
> +                return -ENODEV;
> +
> +        mutex_init(&bus->lock);
> +        INIT_LIST_HEAD(&bus->slaves);
> +
> +	/* Check ACPI for Slave devices */
> +        sdw_acpi_find_slaves(bus);
> +
> +	/* Check DT for Slave devices */
> +	sdw_of_find_slaves(bus);

Please use same indentation as sdw_acpi_find_slaves().

> +
> +        return 0;
> +}
> +
> +This will initialize sdw_bus object for Master device. "sdw_master_ops" and
> +"sdw_master_port_ops" callback functions are provided to the Bus.
> +
> +"sdw_master_ops" is used by Bus to control the Bus in the hardware specific
> +way. It includes Bus control functions such as sending the SoundWire
> +read/write messages on Bus, setting up clock frequency & Stream
> +Synchronization Point (SSP). The "sdw_master_ops" structure abstracts the
> +hardware details of the Master from the Bus.
> +
> +"sdw_master_port_ops" is used by Bus to setup the Port parameters of the
> +Master interface Port. Master interface Port register map is not defined by
> +MIPI specification, so Bus calls the "sdw_master_port_ops" callback
> +function to do Port operations like "Port Prepare", "Port Transport params
> +set", "Port enable and disable". The implementation of the Master driver can
> +then perform hardware-specific configurations.
> +
> +Programming interfaces (SoundWire Slave Driver)
> +===============================================
> +
> +The MIPI specification requires each Slave interface to expose a unique
> +48-bit identifier, stored in 6 read only dev_id registers. This dev_id

                                  read-only

> +identifier contains vendor and part information, as well as a field enabling
> +to differentiate between identical components. An additional class field is
> +currently unused. Slave driver is written for the specific 48-bit
> +identifier, Bus enumerates the Slave device based on the 48-bit identifier.
> +Slave device and driver match is done based on this 48-bit identifier. Probe
> +of the Slave driver is called by Bus on successful match between device and
> +driver id. A parent/child relationship is enforced between Slave and Master

maybe reverse this order.............                         Master and Slave

to be in the "parent/child" order?  Unless I have them backwards?

> +devices (the logical representation is aligned with the physical
> +connectivity).
> +
> +The information on Master/Slave dependencies is stored in platform data,
> +board-file, ACPI or DT. The MIPI Software specification defines an

                                                      drop:        an

> +additional link_id parameters for controllers that have multiple Master
> +interfaces. The dev_id registers are only unique in the scope of a link, and
> +the link_id unique in the scope of a controller. Both dev_id and link_id are
> +not necessarily unique at the system level but the parent/child information
> +is used to avoid ambiguity.
> +
> +static const struct sdw_device_id slave_id[] = {
> +        SDW_SLAVE_ENTRY(0x025d, 0x700, 0),
> +        {},
> +};
> +MODULE_DEVICE_TABLE(sdw, slave_id);
> +
> +static struct sdw_driver slave_sdw_driver = {
> +        .driver = {
> +                   .name = "slave_xxx",
> +                   .pm = &slave_runtime_pm,
> +                   },
> +	.probe = slave_sdw_probe,
> +	.remove = slave_sdw_remove,
> +	.ops = &slave_slave_ops,
> +	.id_table = slave_id,
> +};
> +
> +
> +For capabilities, Bus implements API to read standard Slave MIPI properties
> +and also provides callback in Slave ops for Slave driver to implement own
> +function that provides capabilities information. Bus needs to know a set of
> +Slave capabilities to program Slave registers and to control the Bus
> +reconfigurations.
> +
> +Future enhancements to be done:
> +===============================
> +1. Bulk Register Access (BRA) transfers.
> +2. Multiple data lane support.
> +
> +Links:
> +=====
> +
> +SoundWire MIPI specification 1.1 is available at:
> +https://members.mipi.org/wg/All-Members/document/70290
> +
> +SoundWire MIPI DisCo (Discovery and Configuration) specification is
> +available at:
> +https://www.mipi.org/specifications/mipi-disco-soundwire
> +
> +(publicly accessible with registration or directly accessible to MIPI
> +members)
>

Vinod Koul Oct. 19, 2017, 4:44 a.m. UTC | #2

Thanks for the quick review Randy,

On Wed, Oct 18, 2017 at 08:33:08PM -0700, Randy Dunlap wrote:
> On 10/18/17 20:03, Vinod Koul wrote:

> > +SoundWire is a new interface ratified in 2015 by the MIPI Alliance.
> > +SoundWire is used for transporting data typically related to audio
> > +functions. SoundWire interface is optimized to integrate audio devices in
> > +mobile or mobile inspired systems.
> > +
> > +SoundWire is a 2-Pin multi-drop interface with data and clock line. It
> 
>                   2-pin

ok

> > +The SoundWire protocol supports up to eleven Slave interfaces. All the
> > +interfaces share the common Bus containing data and clock line. Each of the
> > +Slaves can support up to 14 Data Ports. 13 Data Ports are dedicated to audio
> > +transport. Data Port0 is dedicated to transport of Bulk control information,
> > +each of the audio Data Ports (1..14) can support up to 8 Channels in
> 
>                                 (1..13) ??

nope. 1 to 14, both inclusive, thats why 14 Data Ports

> > +Bus:
> > +Implements SoundWire Linux Bus which handles the SoundWire protocol.
> > +It programs all the MIPI defined Slave registers. It represents a SoundWire
> 
>                        MIPI-defined
> 
> > +Master. There can be multiple instances of Bus maybe present in a system.
> 
> eh?
>            Multiple instances of Bus may be present in a system.

sounds better

> > +int sdw_add_bus_master(struct sdw_bus *bus)
> > +{
> > +        if (!bus->dev)
> > +                return -ENODEV;
> > +
> > +        mutex_init(&bus->lock);
> > +        INIT_LIST_HEAD(&bus->slaves);
> > +
> > +	/* Check ACPI for Slave devices */
> > +        sdw_acpi_find_slaves(bus);
> > +
> > +	/* Check DT for Slave devices */
> > +	sdw_of_find_slaves(bus);
> 
> Please use same indentation as sdw_acpi_find_slaves().

ah not sure why it came like this, thanks for pointing out

> > +The MIPI specification requires each Slave interface to expose a unique
> > +48-bit identifier, stored in 6 read only dev_id registers. This dev_id
> 
>                                   read-only

right

> > +identifier, Bus enumerates the Slave device based on the 48-bit identifier.
> > +Slave device and driver match is done based on this 48-bit identifier. Probe
> > +of the Slave driver is called by Bus on successful match between device and
> > +driver id. A parent/child relationship is enforced between Slave and Master
> 
> maybe reverse this order.............                         Master and Slave
> 
> to be in the "parent/child" order?  Unless I have them backwards?

right, will update this

> > +devices (the logical representation is aligned with the physical
> > +connectivity).
> > +
> > +The information on Master/Slave dependencies is stored in platform data,
> > +board-file, ACPI or DT. The MIPI Software specification defines an
> 

ok

Greg KH Oct. 20, 2017, 10:39 a.m. UTC | #3

On Thu, Oct 19, 2017 at 08:33:17AM +0530, Vinod Koul wrote:
> From: Sanyog Kale <[e-mail]>
> 
> SoundWire is a new Linux bus which implements a new MIPI bus protocol
> 'SoundWire'. The summary of SoundWire bus and registration APIs is
> documented in the 'summary' file.
> 
> Signed-off-by: Sanyog Kale <[e-mail]>
> Signed-off-by: Hardik T Shah <[e-mail]>
> Signed-off-by: Pierre-Louis Bossart <[e-mail]>
> Signed-off-by: Vinod Koul <[e-mail]>
> ---
>  Documentation/soundwire/summary.txt | 192 ++++++++++++++++++++++++++++++++++++
>  1 file changed, 192 insertions(+)
>  create mode 100644 Documentation/soundwire/summary.txt

Any specific reason this is not in .rst format and tied to the rest of
the kernel Documentation so it gets built automatically?

thanks,

greg k-h

Vinod Koul Oct. 20, 2017, 3:49 p.m. UTC | #4

On Fri, Oct 20, 2017 at 12:39:34PM +0200, Greg Kroah-Hartman wrote:
> On Thu, Oct 19, 2017 at 08:33:17AM +0530, Vinod Koul wrote:
> > From: Sanyog Kale <[e-mail]>
> > 
> > SoundWire is a new Linux bus which implements a new MIPI bus protocol
> > 'SoundWire'. The summary of SoundWire bus and registration APIs is
> > documented in the 'summary' file.
> > 
> > Signed-off-by: Sanyog Kale <[e-mail]>
> > Signed-off-by: Hardik T Shah <[e-mail]>
> > Signed-off-by: Pierre-Louis Bossart <[e-mail]>
> > Signed-off-by: Vinod Koul <[e-mail]>
> > ---
> >  Documentation/soundwire/summary.txt | 192 ++++++++++++++++++++++++++++++++++++
> >  1 file changed, 192 insertions(+)
> >  create mode 100644 Documentation/soundwire/summary.txt
> 
> Any specific reason this is not in .rst format and tied to the rest of
> the kernel Documentation so it gets built automatically?

I was hoping to do rst conversion a bit later if that is not a deal
breaker :) That is certainly a todo in my list.

Greg KH Oct. 20, 2017, 4:22 p.m. UTC | #5

On Fri, Oct 20, 2017 at 09:19:18PM +0530, Vinod Koul wrote:
> On Fri, Oct 20, 2017 at 12:39:34PM +0200, Greg Kroah-Hartman wrote:
> > On Thu, Oct 19, 2017 at 08:33:17AM +0530, Vinod Koul wrote:
> > > From: Sanyog Kale <[e-mail]>
> > > 
> > > SoundWire is a new Linux bus which implements a new MIPI bus protocol
> > > 'SoundWire'. The summary of SoundWire bus and registration APIs is
> > > documented in the 'summary' file.
> > > 
> > > Signed-off-by: Sanyog Kale <[e-mail]>
> > > Signed-off-by: Hardik T Shah <[e-mail]>
> > > Signed-off-by: Pierre-Louis Bossart <[e-mail]>
> > > Signed-off-by: Vinod Koul <[e-mail]>
> > > ---
> > >  Documentation/soundwire/summary.txt | 192 ++++++++++++++++++++++++++++++++++++
> > >  1 file changed, 192 insertions(+)
> > >  create mode 100644 Documentation/soundwire/summary.txt
> > 
> > Any specific reason this is not in .rst format and tied to the rest of
> > the kernel Documentation so it gets built automatically?
> 
> I was hoping to do rst conversion a bit later if that is not a deal
> breaker :) That is certainly a todo in my list.

Should only take you a few minutes, don't add things to the tree that
you are going to fix up "some day", as that might never happen...

thanks,

greg k-h

Vinod Koul Oct. 20, 2017, 5:09 p.m. UTC | #6

On Fri, Oct 20, 2017 at 06:22:13PM +0200, Greg Kroah-Hartman wrote:
> On Fri, Oct 20, 2017 at 09:19:18PM +0530, Vinod Koul wrote:
> > On Fri, Oct 20, 2017 at 12:39:34PM +0200, Greg Kroah-Hartman wrote:
> > > On Thu, Oct 19, 2017 at 08:33:17AM +0530, Vinod Koul wrote:
> > > > From: Sanyog Kale <[e-mail]>
> > > > 
> > > > SoundWire is a new Linux bus which implements a new MIPI bus protocol
> > > > 'SoundWire'. The summary of SoundWire bus and registration APIs is
> > > > documented in the 'summary' file.
> > > > 
> > > > Signed-off-by: Sanyog Kale <[e-mail]>
> > > > Signed-off-by: Hardik T Shah <[e-mail]>
> > > > Signed-off-by: Pierre-Louis Bossart <[e-mail]>
> > > > Signed-off-by: Vinod Koul <[e-mail]>
> > > > ---
> > > >  Documentation/soundwire/summary.txt | 192 ++++++++++++++++++++++++++++++++++++
> > > >  1 file changed, 192 insertions(+)
> > > >  create mode 100644 Documentation/soundwire/summary.txt
> > > 
> > > Any specific reason this is not in .rst format and tied to the rest of
> > > the kernel Documentation so it gets built automatically?
> > 
> > I was hoping to do rst conversion a bit later if that is not a deal
> > breaker :) That is certainly a todo in my list.
> 
> Should only take you a few minutes, don't add things to the tree that
> you are going to fix up "some day", as that might never happen...

Yeah I need to do that anyway, so lets me get that done for this and some
other stuff I planned to do :)

Mark Brown Oct. 21, 2017, 8:57 a.m. UTC | #7

On Thu, Oct 19, 2017 at 08:33:17AM +0530, Vinod Koul wrote:

> +The SoundWire protocol supports up to eleven Slave interfaces. All the

There's lots of perfectly normal nouns in this document like Slave here
which are randomly capitalized.  Is there some great reason for this?
It makes the document pretty distracting to read.

> +Bus implements API to read standard Master MIPI properties and also provides
> +callback in Master ops for Master driver to implement own functions that

implement it's own functions.

> +provides capabilities information. DT support is not implemented at this
> +time but should be trivial to add since capabilities are enabled with the
> +device_property_ API.

Since we're making this up from whole cloth rather than following an
existing standard let's get a DT binding document together and review
the properties that are getting defined.

> +	/* Check ACPI for Slave devices */
> +        sdw_acpi_find_slaves(bus);

Tab/space issues here.

> +The MIPI specification requires each Slave interface to expose a unique
> +48-bit identifier, stored in 6 read only dev_id registers. This dev_id
> +identifier contains vendor and part information, as well as a field enabling
> +to differentiate between identical components. An additional class field is
> +currently unused. Slave driver is written for the specific 48-bit
> +identifier, Bus enumerates the Slave device based on the 48-bit identifier.

So this says that the instance identifer is part of the device
identifier but the driver should bind to the whole device identifer?
I'd expect the driver to bind to everything except the instance
identifer.

Vinod Koul Oct. 21, 2017, 11:28 a.m. UTC | #8

On Sat, Oct 21, 2017 at 09:57:44AM +0100, Mark Brown wrote:
> On Thu, Oct 19, 2017 at 08:33:17AM +0530, Vinod Koul wrote:
> 
> > +The SoundWire protocol supports up to eleven Slave interfaces. All the
> 
> There's lots of perfectly normal nouns in this document like Slave here
> which are randomly capitalized.  Is there some great reason for this?
> It makes the document pretty distracting to read.

Slave, SoundWire etc are MIPI definitions hence capitalized.

> > +Bus implements API to read standard Master MIPI properties and also provides
> > +callback in Master ops for Master driver to implement own functions that
> 
> implement it's own functions.

ok

> 
> > +provides capabilities information. DT support is not implemented at this
> > +time but should be trivial to add since capabilities are enabled with the
> > +device_property_ API.
> 
> Since we're making this up from whole cloth rather than following an
> existing standard let's get a DT binding document together and review
> the properties that are getting defined.

I don't have a DT to test, but looking at Slimbus code I guess assumptions
are fair and we seem to have similar concepts and implementation.

> 
> > +	/* Check ACPI for Slave devices */
> > +        sdw_acpi_find_slaves(bus);
> 
> Tab/space issues here.

fixed now

> 
> > +The MIPI specification requires each Slave interface to expose a unique
> > +48-bit identifier, stored in 6 read only dev_id registers. This dev_id
> > +identifier contains vendor and part information, as well as a field enabling
> > +to differentiate between identical components. An additional class field is
> > +currently unused. Slave driver is written for the specific 48-bit
> > +identifier, Bus enumerates the Slave device based on the 48-bit identifier.
> 
> So this says that the instance identifer is part of the device
> identifier but the driver should bind to the whole device identifer?
> I'd expect the driver to bind to everything except the instance
> identifer.

Other parts are still TBD and not really used, like Device Class, Spec
version. We are using only mfg id and part id for binding.

Pierre-Louis Bossart Oct. 22, 2017, 10:06 a.m. UTC | #9

On 10/21/17 4:58 PM, Vinod Koul wrote:
> On Sat, Oct 21, 2017 at 09:57:44AM +0100, Mark Brown wrote:
>> On Thu, Oct 19, 2017 at 08:33:17AM +0530, Vinod Koul wrote:
>>
>>> +The SoundWire protocol supports up to eleven Slave interfaces. All the
>>
>> There's lots of perfectly normal nouns in this document like Slave here
>> which are randomly capitalized.  Is there some great reason for this?
>> It makes the document pretty distracting to read.
> 
> Slave, SoundWire etc are MIPI definitions hence capitalized.

I insisted to follow the conventions in the specification, it's not 
random at all.

> 
>>> +Bus implements API to read standard Master MIPI properties and also provides
>>> +callback in Master ops for Master driver to implement own functions that
>>
>> implement it's own functions.
> 
> ok
> 
>>
>>> +provides capabilities information. DT support is not implemented at this
>>> +time but should be trivial to add since capabilities are enabled with the
>>> +device_property_ API.
>>
>> Since we're making this up from whole cloth rather than following an
>> existing standard let's get a DT binding document together and review
>> the properties that are getting defined.

The properties are already defined in the DisCo spec (publicly 
accessible) and were reviewed by MIPI contributors, they are not Intel 
specific and not invented by Intel.
We can put together a DT binding document that follows the Disco spec 
but it'd be a bad idea to change the definitions or come up with new ones...

> 
> I don't have a DT to test, but looking at Slimbus code I guess assumptions
> are fair and we seem to have similar concepts and implementation.
> 
>>
>>> +	/* Check ACPI for Slave devices */
>>> +        sdw_acpi_find_slaves(bus);
>>
>> Tab/space issues here.
> 
> fixed now
> 
>>
>>> +The MIPI specification requires each Slave interface to expose a unique
>>> +48-bit identifier, stored in 6 read only dev_id registers. This dev_id
>>> +identifier contains vendor and part information, as well as a field enabling
>>> +to differentiate between identical components. An additional class field is
>>> +currently unused. Slave driver is written for the specific 48-bit
>>> +identifier, Bus enumerates the Slave device based on the 48-bit identifier.
>>
>> So this says that the instance identifer is part of the device
>> identifier but the driver should bind to the whole device identifer?
>> I'd expect the driver to bind to everything except the instance
>> identifer.
> 
> Other parts are still TBD and not really used, like Device Class, Spec
> version. We are using only mfg id and part id for binding.

Yes, for now the only useful information is manufacturer ID/part ID, the 
spec version is not necessary since there is compatibility between 1.0 
and 1.1 and the changes are documented in properties.

Mark Brown Oct. 23, 2017, 7:50 a.m. UTC | #10

On Sat, Oct 21, 2017 at 04:58:40PM +0530, Vinod Koul wrote:
> On Sat, Oct 21, 2017 at 09:57:44AM +0100, Mark Brown wrote:

> > There's lots of perfectly normal nouns in this document like Slave here
> > which are randomly capitalized.  Is there some great reason for this?
> > It makes the document pretty distracting to read.

> Slave, SoundWire etc are MIPI definitions hence capitalized.

Slave?  Really?

> > > +provides capabilities information. DT support is not implemented at this
> > > +time but should be trivial to add since capabilities are enabled with the
> > > +device_property_ API.

> > Since we're making this up from whole cloth rather than following an
> > existing standard let's get a DT binding document together and review
> > the properties that are getting defined.

> I don't have a DT to test, but looking at Slimbus code I guess assumptions
> are fair and we seem to have similar concepts and implementation.

That's fine, we can still review binding documents.

> > > +The MIPI specification requires each Slave interface to expose a unique
> > > +48-bit identifier, stored in 6 read only dev_id registers. This dev_id
> > > +identifier contains vendor and part information, as well as a field enabling
> > > +to differentiate between identical components. An additional class field is
> > > +currently unused. Slave driver is written for the specific 48-bit
> > > +identifier, Bus enumerates the Slave device based on the 48-bit identifier.

> > So this says that the instance identifer is part of the device
> > identifier but the driver should bind to the whole device identifer?
> > I'd expect the driver to bind to everything except the instance
> > identifer.

> Other parts are still TBD and not really used, like Device Class, Spec
> version. We are using only mfg id and part id for binding.

That's not what the document claims.

Mark Brown Oct. 23, 2017, 8:21 a.m. UTC | #11

On Sun, Oct 22, 2017 at 03:36:32PM +0530, Pierre-Louis Bossart wrote:
> On 10/21/17 4:58 PM, Vinod Koul wrote:
> > On Sat, Oct 21, 2017 at 09:57:44AM +0100, Mark Brown wrote:

> > > There's lots of perfectly normal nouns in this document like Slave here
> > > which are randomly capitalized.  Is there some great reason for this?
> > > It makes the document pretty distracting to read.

> > Slave, SoundWire etc are MIPI definitions hence capitalized.

> I insisted to follow the conventions in the specification, it's not random
> at all.

It's making it pretty painful to read as kernel documentation.

> We can put together a DT binding document that follows the Disco spec but
> it'd be a bad idea to change the definitions or come up with new ones...

Given that there's a goal to do this via the device property stuff with
the apparent goal that we also use this stuff for DT it should at least
be run past some DT people. It may be that everything is totally fine as
is but we should at least check.

Vinod Koul Oct. 23, 2017, 11:18 a.m. UTC | #12

On Mon, Oct 23, 2017 at 08:50:50AM +0100, Mark Brown wrote:
> On Sat, Oct 21, 2017 at 04:58:40PM +0530, Vinod Koul wrote:
> > On Sat, Oct 21, 2017 at 09:57:44AM +0100, Mark Brown wrote:
> 
> > > There's lots of perfectly normal nouns in this document like Slave here
> > > which are randomly capitalized.  Is there some great reason for this?
> > > It makes the document pretty distracting to read.
> 
> > Slave, SoundWire etc are MIPI definitions hence capitalized.
> 
> Slave?  Really?
> 
> > > > +provides capabilities information. DT support is not implemented at this
> > > > +time but should be trivial to add since capabilities are enabled with the
> > > > +device_property_ API.
> 
> > > Since we're making this up from whole cloth rather than following an
> > > existing standard let's get a DT binding document together and review
> > > the properties that are getting defined.
> 
> > I don't have a DT to test, but looking at Slimbus code I guess assumptions
> > are fair and we seem to have similar concepts and implementation.
> 
> That's fine, we can still review binding documents.

I am not really sure about that part, let me see if I can come up or worst
case not talk about DT at all.

> > > > +The MIPI specification requires each Slave interface to expose a unique
> > > > +48-bit identifier, stored in 6 read only dev_id registers. This dev_id
> > > > +identifier contains vendor and part information, as well as a field enabling
> > > > +to differentiate between identical components. An additional class field is
> > > > +currently unused. Slave driver is written for the specific 48-bit
> > > > +identifier, Bus enumerates the Slave device based on the 48-bit identifier.
> 
> > > So this says that the instance identifer is part of the device
> > > identifier but the driver should bind to the whole device identifer?
> > > I'd expect the driver to bind to everything except the instance
> > > identifer.
> 
> > Other parts are still TBD and not really used, like Device Class, Spec
> > version. We are using only mfg id and part id for binding.
> 
> That's not what the document claims.

Sorry about that fixed now. Thanks for pointing

Patch

diff --git a/Documentation/soundwire/summary.txt b/Documentation/soundwire/summary.txt
new file mode 100644
index 000000000000..15b78e6e3347
--- /dev/null
+++ b/Documentation/soundwire/summary.txt
@@ -0,0 +1,192 @@ 
+SoundWire
+===========
+
+SoundWire is a new interface ratified in 2015 by the MIPI Alliance.
+SoundWire is used for transporting data typically related to audio
+functions. SoundWire interface is optimized to integrate audio devices in
+mobile or mobile inspired systems.
+
+SoundWire is a 2-Pin multi-drop interface with data and clock line. It
+facilitates development of low cost, efficient, high performance systems.
+Broad level key features of SoundWire interface include:
+  1. Transporting all of payload data channels, control information, and setup
+  commands over a single two-pin interface.
+  2. Lower clock frequency, and hence lower power consumption, by use of DDR
+  (Dual Data Rate) data transmission.
+  3. Clock scaling and optional multiple data lanes to give wide flexibility
+  in data rate to match system requirements.
+  4. Device status monitoring, including interrupt-style alerts to the Master.
+
+The SoundWire protocol supports up to eleven Slave interfaces. All the
+interfaces share the common Bus containing data and clock line. Each of the
+Slaves can support up to 14 Data Ports. 13 Data Ports are dedicated to audio
+transport. Data Port0 is dedicated to transport of Bulk control information,
+each of the audio Data Ports (1..14) can support up to 8 Channels in
+transmit or receiving mode (typically fixed direction but configurable
+direction is enabled by the specification).  Bandwidth restrictions to
+~19.2..24.576Mbits/s don't however allow for 11*13*8 channels to be
+transmitted simultaneously.
+
+Below figure shows an example of connectivity between a SoundWire Master and
+two Slave devices.
+
++---------------+                                       +---------------+
+|               |                       Clock Signal    |               |
+|    Master     |-------+-------------------------------|    Slave      |
+|   Interface   |       |               Data Signal     |  Interface 1  |
+|               |-------|-------+-----------------------|               |
++---------------+       |       |                       +---------------+
+                        |       |
+                        |       |
+                        |       |
+                     +--+-------+--+
+                     |             |
+                     |   Slave     |
+                     | Interface 2 |
+                     |             |
+                     +-------------+
+
+Terminology
+=============
+
+The MIPI SoundWire specification uses the term 'device' to refer to a Master
+or Slave interface, which of course can be confusing. In this summary and
+code we use the term interface only to refer to the hardware. We follow the
+Linux device model by mapping each Slave interface connected on the bus as a
+device managed by a specific driver. The Linux SoundWire subsystem provides
+a framework to implement a SoundWire Slave driver with an API allowing
+3rd-party vendors to enable implementation-defined functionality while
+common setup/configuration tasks are handled by the bus.
+
+Bus:
+Implements SoundWire Linux Bus which handles the SoundWire protocol.
+It programs all the MIPI defined Slave registers. It represents a SoundWire
+Master. There can be multiple instances of Bus maybe present in a system.
+
+Slave:
+Registers as SoundWire Slave device (Linux Device). Multiple Slave devices
+can register to a Bus instance.
+
+Slave driver:
+Driver controlling the Slave device. MIPI-specified registers are controlled
+directly by the Bus (and transmitted through the Master driver/interface).
+Any implementation-defined Slave register is controlled by Slave driver. In
+practice, it is expected that the Slave driver relies on regmap and does not
+request direct register access.
+
+Programming interfaces (SoundWire Master interface Driver)
+==========================================================
+
+SoundWire Bus supports programming interfaces for the SoundWire Master
+implementation and SoundWire Slave devices. All the code uses the "sdw"
+prefix commonly used by SoC designers and 3rd party vendors.
+
+Each of the SoundWire Master interfaces needs to be registered to the Bus.
+Bus implements API to read standard Master MIPI properties and also provides
+callback in Master ops for Master driver to implement own functions that
+provides capabilities information. DT support is not implemented at this
+time but should be trivial to add since capabilities are enabled with the
+device_property_ API.
+
+The Master interface along with the Master interface capabilities are
+registered based on board file, DT or ACPI.
+
+Following is the Bus API to register the SoundWire Bus.
+
+int sdw_add_bus_master(struct sdw_bus *bus)
+{
+        if (!bus->dev)
+                return -ENODEV;
+
+        mutex_init(&bus->lock);
+        INIT_LIST_HEAD(&bus->slaves);
+
+	/* Check ACPI for Slave devices */
+        sdw_acpi_find_slaves(bus);
+
+	/* Check DT for Slave devices */
+	sdw_of_find_slaves(bus);
+
+        return 0;
+}
+
+This will initialize sdw_bus object for Master device. "sdw_master_ops" and
+"sdw_master_port_ops" callback functions are provided to the Bus.
+
+"sdw_master_ops" is used by Bus to control the Bus in the hardware specific
+way. It includes Bus control functions such as sending the SoundWire
+read/write messages on Bus, setting up clock frequency & Stream
+Synchronization Point (SSP). The "sdw_master_ops" structure abstracts the
+hardware details of the Master from the Bus.
+
+"sdw_master_port_ops" is used by Bus to setup the Port parameters of the
+Master interface Port. Master interface Port register map is not defined by
+MIPI specification, so Bus calls the "sdw_master_port_ops" callback
+function to do Port operations like "Port Prepare", "Port Transport params
+set", "Port enable and disable". The implementation of the Master driver can
+then perform hardware-specific configurations.
+
+Programming interfaces (SoundWire Slave Driver)
+===============================================
+
+The MIPI specification requires each Slave interface to expose a unique
+48-bit identifier, stored in 6 read only dev_id registers. This dev_id
+identifier contains vendor and part information, as well as a field enabling
+to differentiate between identical components. An additional class field is
+currently unused. Slave driver is written for the specific 48-bit
+identifier, Bus enumerates the Slave device based on the 48-bit identifier.
+Slave device and driver match is done based on this 48-bit identifier. Probe
+of the Slave driver is called by Bus on successful match between device and
+driver id. A parent/child relationship is enforced between Slave and Master
+devices (the logical representation is aligned with the physical
+connectivity).
+
+The information on Master/Slave dependencies is stored in platform data,
+board-file, ACPI or DT. The MIPI Software specification defines an
+additional link_id parameters for controllers that have multiple Master
+interfaces. The dev_id registers are only unique in the scope of a link, and
+the link_id unique in the scope of a controller. Both dev_id and link_id are
+not necessarily unique at the system level but the parent/child information
+is used to avoid ambiguity.
+
+static const struct sdw_device_id slave_id[] = {
+        SDW_SLAVE_ENTRY(0x025d, 0x700, 0),
+        {},
+};
+MODULE_DEVICE_TABLE(sdw, slave_id);
+
+static struct sdw_driver slave_sdw_driver = {
+        .driver = {
+                   .name = "slave_xxx",
+                   .pm = &slave_runtime_pm,
+                   },
+	.probe = slave_sdw_probe,
+	.remove = slave_sdw_remove,
+	.ops = &slave_slave_ops,
+	.id_table = slave_id,
+};
+
+
+For capabilities, Bus implements API to read standard Slave MIPI properties
+and also provides callback in Slave ops for Slave driver to implement own
+function that provides capabilities information. Bus needs to know a set of
+Slave capabilities to program Slave registers and to control the Bus
+reconfigurations.
+
+Future enhancements to be done:
+===============================
+1. Bulk Register Access (BRA) transfers.
+2. Multiple data lane support.
+
+Links:
+=====
+
+SoundWire MIPI specification 1.1 is available at:
+https://members.mipi.org/wg/All-Members/document/70290
+
+SoundWire MIPI DisCo (Discovery and Configuration) specification is
+available at:
+https://www.mipi.org/specifications/mipi-disco-soundwire
+
+(publicly accessible with registration or directly accessible to MIPI
+members)