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