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

[Christopher Bostic]

On Wed, Oct 19, 2016 at 9:17 PM, Jeremy Kerr <jk at 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