요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
FSI bus & engine generic device tree bindings
=============================================
The FSI bus is probe-able, so the OS is able to enumerate FSI slaves, and
engines within those slaves. However, we have a facility to match devicetree
nodes to probed engines. This allows for fsi engines to expose non-probeable
busses, which are then exposed by the device tree. For example, an FSI engine
that is an I2C master - the I2C bus can be described by the device tree under
the engine's device tree node.
FSI masters may require their own DT nodes (to describe the master HW itself);
that requirement is defined by the master's implementation, and is described by
the fsi-master-* binding specifications.
Under the masters' nodes, we can describe the bus topology using nodes to
represent the FSI slaves and their slave engines. As a basic outline:
fsi-master {
/* top-level of FSI bus topology, bound to an FSI master driver and
* exposes an FSI bus */
fsi-slave@<link,id> {
/* this node defines the FSI slave device, and is handled
* entirely with FSI core code */
fsi-slave-engine@<addr> {
/* this node defines the engine endpoint & address range, which
* is bound to the relevant fsi device driver */
...
};
fsi-slave-engine@<addr> {
...
};
};
};
Note that since the bus is probe-able, some (or all) of the topology may
not be described; this binding only provides an optional facility for
adding subordinate device tree nodes as children of FSI engines.
FSI masters
-----------
FSI master nodes declare themselves as such with the "fsi-master" compatible
value. It's likely that an implementation-specific compatible value will
be needed as well, for example:
compatible = "fsi-master-gpio", "fsi-master";
Since the master nodes describe the top-level of the FSI topology, they also
need to declare the FSI-standard addressing scheme. This requires two cells for
addresses (link index and slave ID), and no size:
#address-cells = <2>;
#size-cells = <0>;
An optional boolean property can be added to indicate that a particular master
should not scan for connected devices at initialization time. This is
necessary in cases where a scan could cause arbitration issues with other
masters that may be present on the bus.
no-scan-on-init;
FSI slaves
----------
Slaves are identified by a (link-index, slave-id) pair, so require two cells
for an address identifier. Since these are not a range, no size cells are
required. For an example, a slave on link 1, with ID 2, could be represented
as:
cfam@1,2 {
reg = <1 2>;
[...];
}
Each slave provides an address-space, under which the engines are accessible.
That address space has a maximum of 23 bits, so we use one cell to represent
addresses and sizes in the slave address space:
#address-cells = <1>;
#size-cells = <1>;
Optionally, a slave can provide a global unique chip ID which is used to
identify the physical location of the chip in a system specific way
chip-id = <0>;
FSI engines (devices)
---------------------
Engines are identified by their address under the slaves' address spaces. We
use a single cell for address and size. Engine nodes represent the endpoint
FSI device, and are passed to those FSI device drivers' ->probe() functions.
For example, for a slave using a single 0x400-byte page starting at address
0xc00:
engine@c00 {
reg = <0xc00 0x400>;
};
Full example
------------
Here's an example that illustrates:
- an FSI master
- connected to an FSI slave
- that contains an engine that is an I2C master
- connected to an I2C EEPROM
The FSI master may be connected to additional slaves, and slaves may have
additional engines, but they don't necessarily need to be describe in the
device tree if no extra platform information is required.
/* The GPIO-based FSI master node, describing the top level of the
* FSI bus
*/
gpio-fsi {
compatible = "fsi-master-gpio", "fsi-master";
#address-cells = <2>;
#size-cells = <0>;
/* A FSI slave (aka. CFAM) at link 0, ID 0. */
cfam@0,0 {
reg = <0 0>;
#address-cells = <1>;
#size-cells = <1>;
chip-id = <0>;
/* FSI engine at 0xc00, using a single page. In this example,
* it's an I2C master controller, so subnodes describe the
* I2C bus.
*/
i2c-controller@c00 {
reg = <0xc00 0x400>;
/* Engine-specific data. In this case, we're describing an
* I2C bus, so we're conforming to the generic I2C binding
*/
compatible = "some-vendor,fsi-i2c-controller";
#address-cells = <1>;
#size-cells = <1>;
/* I2C endpoint device: an Atmel EEPROM */
eeprom@50 {
compatible = "atmel,24c256";
reg = <0x50>;
pagesize = <64>;
};
};
};
};
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
FSI bus와 engine topology
1-42FSI bus는 probe할 수 있으므로 OS가 FSI slave와 그 slave 안의 engine을 열거할 수 있습니다. 또한 probe된 engine과 devicetree node를 연결하는 기능을 제공합니다. 이를 통해 FSI engine이 probe할 수 없는 subordinate bus를 노출하고 device tree가 그 bus를 기술할 수 있습니다. 예를 들어 FSI engine이 I2C master라면 그 engine의 device tree node 아래에 I2C bus를 기술할 수 있습니다.
FSI master hardware 자체를 기술하기 위해 master별 DT node가 필요할 수 있습니다. 이 요구 사항은 master 구현이 정하며 `fsi-master-*` binding specification에서 설명합니다. Master node 아래에는 FSI slave와 slave engine을 나타내는 node로 bus topology를 기술합니다.
FSI bus는 probe할 수 있으므로 topology 일부 또는 전부를 생략할 수 있습니다. 이 binding은 FSI engine의 child로 subordinate device tree node를 추가하는 선택 기능만 제공합니다.
원문의 중첩 ASCII outline을 master, slave, engine과 subordinate bus 계층으로 구조화했습니다.
FSI master
43-65FSI master node는 `fsi-master` compatible 값으로 자신을 선언합니다. 일반적으로 `fsi-master-gpio` 같은 구현별 compatible 값도 함께 필요합니다.
Master node는 FSI topology의 최상위이므로 FSI 표준 addressing scheme도 선언해야 합니다. Address는 link index와 slave ID의 두 cell을 사용하고 size는 사용하지 않으므로 `#address-cells = <2>`, `#size-cells = <0>`입니다.
선택 boolean `no-scan-on-init`은 initialization 때 연결된 device를 scan하지 않도록 합니다. Bus에 다른 master가 있을 때 scan이 arbitration 문제를 일으킬 수 있는 경우 필요합니다.
compatible = "fsi-master-gpio", "fsi-master";#address-cells = <2>;
#size-cells = <0>;no-scan-on-init;FSI slave
66-90Slave는 `(link-index, slave-id)` pair로 식별하므로 address identifier에 두 cell이 필요합니다. 이 값은 range가 아니므로 size cell은 필요하지 않습니다. 예를 들어 link 1의 ID 2 slave는 `cfam@1,2`와 `reg = <1 2>`로 나타냅니다.
각 slave는 engine이 접근할 address space를 제공합니다. 이 address space는 최대 23 bit이므로 slave address space의 address와 size에 각각 한 cell을 사용합니다.
선택 `chip-id`는 system별 방식으로 chip의 물리적 위치를 식별하는 global unique chip ID입니다.
cfam@1,2 {
reg = <1 2>;
[...];
}#address-cells = <1>;
#size-cells = <1>;chip-id = <0>;FSI engine device
91-105Engine은 slave address space 안의 address로 식별하며 address와 size에 각각 한 cell을 사용합니다. Engine node는 endpoint FSI device를 나타내고 해당 FSI device driver의 `->probe()` 함수에 전달됩니다.
예제는 address `0xc00`에서 시작하는 단일 0x400-byte page를 사용하는 engine입니다.
engine@c00 {
reg = <0xc00 0x400>;
};FSI 전체 topology 예제
106-156전체 예제는 GPIO 기반 FSI master가 link 0, ID 0의 FSI slave(CFAM)에 연결되고, 그 slave의 address `0xc00`에 있는 한 page 크기 engine이 I2C master이며, I2C bus에 Atmel EEPROM이 연결된 계층을 보여 줍니다.
FSI master에는 추가 slave가, slave에는 추가 engine이 있을 수 있습니다. 추가 platform 정보가 필요하지 않다면 device tree에 반드시 기술할 필요는 없습니다.
원문의 bullet hierarchy를 실제 node와 address를 포함한 연결 흐름으로 다시 그렸습니다.
/* The GPIO-based FSI master node, describing the top level of the
* FSI bus
*/
gpio-fsi {
compatible = "fsi-master-gpio", "fsi-master";
#address-cells = <2>;
#size-cells = <0>;
/* A FSI slave (aka. CFAM) at link 0, ID 0. */
cfam@0,0 {
reg = <0 0>;
#address-cells = <1>;
#size-cells = <1>;
chip-id = <0>;
/* FSI engine at 0xc00, using a single page. In this example,
* it's an I2C master controller, so subnodes describe the
* I2C bus.
*/
i2c-controller@c00 {
reg = <0xc00 0x400>;
/* Engine-specific data. In this case, we're describing an
* I2C bus, so we're conforming to the generic I2C binding
*/
compatible = "some-vendor,fsi-i2c-controller";
#address-cells = <1>;
#size-cells = <1>;
/* I2C endpoint device: an Atmel EEPROM */
eeprom@50 {
compatible = "atmel,24c256";
reg = <0x50>;
pagesize = <64>;
};
};
};
};
요약과 해설
fsi.txt:1-156Probe 가능한 FSI topology와 주소 cell, I2C engine 예제를 설명합니다.