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