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 59FSI slaves 60---------- 61 62Slaves are identified by a (link-index, slave-id) pair, so require two cells 63for an address identifier. Since these are not a range, no size cells are 64required. For an example, a slave on link 1, with ID 2, could be represented 65as: 66 67 cfam@1,2 { 68 reg = <1 2>; 69 [...]; 70 } 71 72Each slave provides an address-space, under which the engines are accessible. 73That address space has a maximum of 23 bits, so we use one cell to represent 74addresses and sizes in the slave address space: 75 76 #address-cells = <1>; 77 #size-cells = <1>; 78 79 80FSI engines (devices) 81--------------------- 82 83Engines are identified by their address under the slaves' address spaces. We 84use a single cell for address and size. Engine nodes represent the endpoint 85FSI device, and are passed to those FSI device drivers' ->probe() functions. 86 87For example, for a slave using a single 0x400-byte page starting at address 880xc00: 89 90 engine@c00 { 91 reg = <0xc00 0x400>; 92 }; 93 94 95Full example 96------------ 97 98Here's an example that illustrates: 99 - an FSI master 100 - connected to an FSI slave 101 - that contains an engine that is an I2C master 102 - connected to an I2C EEPROM 103 104The FSI master may be connected to additional slaves, and slaves may have 105additional engines, but they don't necessarily need to be describe in the 106device tree if no extra platform information is required. 107 108 /* The GPIO-based FSI master node, describing the top level of the 109 * FSI bus 110 */ 111 gpio-fsi { 112 compatible = "fsi-master-gpio", "fsi-master"; 113 #address-cells = <2>; 114 #size-cells = <0>; 115 116 /* A FSI slave (aka. CFAM) at link 0, ID 0. */ 117 cfam@0,0 { 118 reg = <0 0>; 119 #address-cells = <1>; 120 #size-cells = <1>; 121 122 /* FSI engine at 0xc00, using a single page. In this example, 123 * it's an I2C master controller, so subnodes describe the 124 * I2C bus. 125 */ 126 i2c-controller@c00 { 127 reg = <0xc00 0x400>; 128 129 /* Engine-specific data. In this case, we're describing an 130 * I2C bus, so we're conforming to the generic I2C binding 131 */ 132 compatible = "some-vendor,fsi-i2c-controller"; 133 #address-cells = <1>; 134 #size-cells = <1>; 135 136 /* I2C endpoint device: an Atmel EEPROM */ 137 eeprom@50 { 138 compatible = "atmel,24c256"; 139 reg = <0x50>; 140 pagesize = <64>; 141 }; 142 }; 143 }; 144 }; 145