Documentation/devicetree/bindings/fsi/fsi.txt

   1 FSI bus & engine generic device tree bindings
   2 =============================================
   3
   4 The FSI bus is probe-able, so the OS is able to enumerate FSI slaves, and
   5 engines within those slaves. However, we have a facility to match devicetree
   6 nodes to probed engines. This allows for fsi engines to expose non-probeable
   7 busses, which are then exposed by the device tree. For example, an FSI engine
   8 that is an I2C master - the I2C bus can be described by the device tree under
   9 the engine's device tree node.
  10
  11 FSI masters may require their own DT nodes (to describe the master HW itself);
  12 that requirement is defined by the master's implementation, and is described by
  13 the fsi-master-* binding specifications.
  14
  15 Under the masters' nodes, we can describe the bus topology using nodes to
  16 represent the FSI slaves and their slave engines. As a basic outline:
  17
  18   fsi-master {
  19       /* top-level of FSI bus topology, bound to an FSI master driver and
  20        * exposes an FSI bus */
  21
  22       fsi-slave@<link,id> {
  23           /* this node defines the FSI slave device, and is handled
  24            * entirely with FSI core code */
  25
  26           fsi-slave-engine@<addr> {
  27               /* this node defines the engine endpoint & address range, which
  28                * is bound to the relevant fsi device driver */
  29                ...
  30           };
  31
  32           fsi-slave-engine@<addr> {
  33               ...
  34           };
  35
  36       };
  37   };
  38
  39 Note that since the bus is probe-able, some (or all) of the topology may
  40 not be described; this binding only provides an optional facility for
  41 adding subordinate device tree nodes as children of FSI engines.
  42
  43 FSI masters
  44 -----------
  45
  46 FSI master nodes declare themselves as such with the "fsi-master" compatible
  47 value. It's likely that an implementation-specific compatible value will
  48 be needed as well, for example:
  49
  50     compatible = "fsi-master-gpio", "fsi-master";
  51
  52 Since the master nodes describe the top-level of the FSI topology, they also
  53 need to declare the FSI-standard addressing scheme. This requires two cells for
  54 addresses (link index and slave ID), and no size:
  55
  56     #address-cells = <2>;
  57     #size-cells = <0>;
  58
  59 An optional boolean property can be added to indicate that a particular master
  60 should not scan for connected devices at initialization time.  This is
  61 necessary in cases where a scan could cause arbitration issues with other
  62 masters that may be present on the bus.
  63
  64     no-scan-on-init;
  65
  66 FSI slaves
  67 ----------
  68
  69 Slaves are identified by a (link-index, slave-id) pair, so require two cells
  70 for an address identifier. Since these are not a range, no size cells are
  71 required. For an example, a slave on link 1, with ID 2, could be represented
  72 as:
  73
  74     cfam@1,2 {
  75         reg = <1 2>;
  76         [...];
  77     }
  78
  79 Each slave provides an address-space, under which the engines are accessible.
  80 That address space has a maximum of 23 bits, so we use one cell to represent
  81 addresses and sizes in the slave address space:
  82
  83     #address-cells = <1>;
  84     #size-cells = <1>;
  85
  86
  87 FSI engines (devices)
  88 ---------------------
  89
  90 Engines are identified by their address under the slaves' address spaces. We
  91 use a single cell for address and size. Engine nodes represent the endpoint
  92 FSI device, and are passed to those FSI device drivers' ->probe() functions.
  93
  94 For example, for a slave using a single 0x400-byte page starting at address
  95 0xc00:
  96
  97     engine@c00 {
  98         reg = <0xc00 0x400>;
  99     };
 100
 101
 102 Full example
 103 ------------
 104
 105 Here's an example that illustrates:
 106  - an FSI master
 107    - connected to an FSI slave
 108      - that contains an engine that is an I2C master
 109        - connected to an I2C EEPROM
 110
 111 The FSI master may be connected to additional slaves, and slaves may have
 112 additional engines, but they don't necessarily need to be describe in the
 113 device tree if no extra platform information is required.
 114
 115     /* The GPIO-based FSI master node, describing the top level of the
 116      * FSI bus
 117      */
 118     gpio-fsi {
 119         compatible = "fsi-master-gpio", "fsi-master";
 120         #address-cells = <2>;
 121         #size-cells = <0>;
 122
 123         /* A FSI slave (aka. CFAM) at link 0, ID 0. */
 124         cfam@0,0 {
 125             reg = <0 0>;
 126             #address-cells = <1>;
 127             #size-cells = <1>;
 128
 129             /* FSI engine at 0xc00, using a single page. In this example,
 130              * it's an I2C master controller, so subnodes describe the
 131              * I2C bus.
 132              */
 133             i2c-controller@c00 {
 134                 reg = <0xc00 0x400>;
 135
 136                 /* Engine-specific data. In this case, we're describing an
 137                  * I2C bus, so we're conforming to the generic I2C binding
 138                  */
 139                 compatible = "some-vendor,fsi-i2c-controller";
 140                 #address-cells = <1>;
 141                 #size-cells = <1>;
 142
 143                 /* I2C endpoint device: an Atmel EEPROM */
 144                 eeprom@50 {
 145                     compatible = "atmel,24c256";
 146                     reg = <0x50>;
 147                     pagesize = <64>;
 148                 };
 149             };
 150         };
 151     };