[linux,v5,18/18] Documenation: Add basic FSI text file

From: Chris Bostic <cbostic@us.ibm.com>

Add documentation explaining the basics of FSI and how to find
more information.

Signed-off-by: Chris Bostic <cbostic@us.ibm.com>
---
 Documentation/fsi.txt | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 Documentation/fsi.txt

Hi Chris,

> Add documentation explaining the basics of FSI and how to find
> more information.
> +The Flexible Support Interface (FSI) is a two wire bus consisting of
> +a serial data line and a clock capable of running at up to 166 MHz.
> +FSI features strong data integrity with CRC protection and is capable
> +of very high fan out.
> +
> +The complete hardware specification[1] for FSI is publicly available on
> +the OpenPower Foundation website:
> +
> +[1] http://openpowerfoundation.org/wp-content/uploads/resources/OpenFSI-spec/content/ch_preface.html
> +
> +Common FSI terminology:
> +
> +* Master
> +    Controller of the FSI bus.  Only the master is allowed to control the
> +    clock line and is the initiator of all transactions on a bus.
> +
> +* Slave
> +    The receiver or target of a master initiated transaction.  The slave
> +    cannot initiate communications on a bus and must respond to any
> +    master requests for data.
> +
> +* CFAM
> +    Stands for Common Field replaceable unit Access Macro.  A CFAM is an
> +    ASIC residing in any device requiring FSI communications. CFAMs
> +    consist of an array of hardware 'engines' used for various purposes.
> +    I2C masters, UARTs, General Purpose IO hardware are common types of
> +    these engines.
> +
> +* Configuration Space / Configuration Table
> +    A table contained at the beginning of each CFAM address space.
> +    This table lists information such as the CFAM's ID, which engine types
> +    and versions it contains, as well as its addressing range.
> +
> +* FSI Client driver
> +    A device driver that registers with the FSI core so that it can access
> +    devices it owns on an FSI bus.

Is "client" something new, or is this standard FSI terminology? I would
have thought "engine" is the term used elsewhere.

Anyway, here's a little more to tie it into the kernel implementation:

------------
In Linux, we have a core FSI "bus type", along with drivers for FSI
masters and clients.

The FSI master drivers expose a read/write interface to the bus address
space. The master drivers are under drivers/fsi/fsi-master-*.c.

The core handles probing and discovery of slaves and slave
engines, using those read/write interfaces. It is responsible for
creating the endpoint Linux devices corresponding to the discovered
engines on each slave.

Slave engines are identified by an 'engine' type, and an optional
version. Client drivers are matched and bound to these engines during
discovery.

------------

We may want to add some description of the APIs, but that should do for
now.

Cheers,


Jeremy

On Wed, Oct 19, 2016 at 9:17 PM, Jeremy Kerr <jk@ozlabs.org> wrote:
> Hi Chris,
>
>> Add documentation explaining the basics of FSI and how to find
>> more information.
>> +The Flexible Support Interface (FSI) is a two wire bus consisting of
>> +a serial data line and a clock capable of running at up to 166 MHz.
>> +FSI features strong data integrity with CRC protection and is capable
>> +of very high fan out.
>> +
>> +The complete hardware specification[1] for FSI is publicly available on
>> +the OpenPower Foundation website:
>> +
>> +[1] http://openpowerfoundation.org/wp-content/uploads/resources/OpenFSI-spec/content/ch_preface.html
>> +
>> +Common FSI terminology:
>> +
>> +* Master
>> +    Controller of the FSI bus.  Only the master is allowed to control the
>> +    clock line and is the initiator of all transactions on a bus.
>> +
>> +* Slave
>> +    The receiver or target of a master initiated transaction.  The slave
>> +    cannot initiate communications on a bus and must respond to any
>> +    master requests for data.
>> +
>> +* CFAM
>> +    Stands for Common Field replaceable unit Access Macro.  A CFAM is an
>> +    ASIC residing in any device requiring FSI communications. CFAMs
>> +    consist of an array of hardware 'engines' used for various purposes.
>> +    I2C masters, UARTs, General Purpose IO hardware are common types of
>> +    these engines.
>> +
>> +* Configuration Space / Configuration Table
>> +    A table contained at the beginning of each CFAM address space.
>> +    This table lists information such as the CFAM's ID, which engine types
>> +    and versions it contains, as well as its addressing range.
>> +
>> +* FSI Client driver
>> +    A device driver that registers with the FSI core so that it can access
>> +    devices it owns on an FSI bus.
>
> Is "client" something new, or is this standard FSI terminology? I would
> have thought "engine" is the term used elsewhere.
>
> Anyway, here's a little more to tie it into the kernel implementation:

Hi Jeremy,

OK will change client wording to engine and add your text.
If we can defer the description of API's I'd prefer to do that.

Thanks,
Chris

>
> ------------
> In Linux, we have a core FSI "bus type", along with drivers for FSI
> masters and clients.
>
> The FSI master drivers expose a read/write interface to the bus address
> space. The master drivers are under drivers/fsi/fsi-master-*.c.
>
> The core handles probing and discovery of slaves and slave
> engines, using those read/write interfaces. It is responsible for
> creating the endpoint Linux devices corresponding to the discovered
> engines on each slave.
>
> Slave engines are identified by an 'engine' type, and an optional
> version. Client drivers are matched and bound to these engines during
> discovery.
>
> ------------
>
> We may want to add some description of the APIs, but that should do for
> now.
>
> Cheers,
>
>
> Jeremy