[mirror_qemu.git] / docs / specs / fsi.rst

======================================
IBM's Flexible Service Interface (FSI)
======================================

The QEMU FSI emulation implements hardware interfaces between ASPEED SOC, FSI
master/slave and the end engine.

FSI is a point-to-point two wire interface which is capable of supporting
distances of up to 4 meters. FSI interfaces have been used successfully for
many years in IBM servers to attach IBM Flexible Support Processors(FSP) to
CPUs and IBM ASICs.

FSI allows a service processor access to the internal buses of a host POWER
processor to perform configuration or debugging. FSI has long existed in POWER
processes and so comes with some baggage, including how it has been integrated
into the ASPEED SoC.

Working backwards from the POWER processor, the fundamental pieces of interest
for the implementation are: (see the `FSI specification`_ for more details)

1. The Common FRU Access Macro (CFAM), an address space containing various
   "engines" that drive accesses on buses internal and external to the POWER
   chip. Examples include the SBEFIFO and I2C masters. The engines hang off of
   an internal Local Bus (LBUS) which is described by the CFAM configuration
   block.

2. The FSI slave: The slave is the terminal point of the FSI bus for FSI
   symbols addressed to it. Slaves can be cascaded off of one another. The
   slave's configuration registers appear in address space of the CFAM to
   which it is attached.

3. The FSI master: A controller in the platform service processor (e.g. BMC)
   driving CFAM engine accesses into the POWER chip. At the hardware level
   FSI is a bit-based protocol supporting synchronous and DMA-driven accesses
   of engines in a CFAM.

4. The On-Chip Peripheral Bus (OPB): A low-speed bus typically found in POWER
   processors. This now makes an appearance in the ASPEED SoC due to tight
   integration of the FSI master IP with the OPB, mainly the existence of an
   MMIO-mapping of the CFAM address straight onto a sub-region of the OPB
   address space.

5. An APB-to-OPB bridge enabling access to the OPB from the ARM core in the
   AST2600. Hardware limitations prevent the OPB from being directly mapped
   into APB, so all accesses are indirect through the bridge.

The LBUS is modelled to maintain the qdev bus hierarchy and to take advantages
of the object model to automatically generate the CFAM configuration block.
The configuration block presents engines in the order they are attached to the
CFAM's LBUS. Engine implementations should subclass the LBusDevice and set the
'config' member of LBusDeviceClass to match the engine's type.

CFAM designs offer a lot of flexibility, for instance it is possible for a
CFAM to be simultaneously driven from multiple FSI links. The modeling is not
so complete; it's assumed that each CFAM is attached to a single FSI slave (as
a consequence the CFAM subclasses the FSI slave).

As for FSI, its symbols and wire-protocol are not modelled at all. This is not
necessary to get FSI off the ground thanks to the mapping of the CFAM address
space onto the OPB address space - the models follow this directly and map the
CFAM memory region into the OPB's memory region.

The following commands start the ``rainier-bmc`` machine with built-in FSI
model. There are no model specific arguments. Please check this document to
learn more about Aspeed ``rainier-bmc`` machine: (:doc:`../../system/arm/aspeed`)

.. code-block:: console

  qemu-system-arm -M rainier-bmc -nographic \
  -kernel fitImage-linux.bin \
  -dtb aspeed-bmc-ibm-rainier.dtb \
  -initrd obmc-phosphor-initramfs.rootfs.cpio.xz \
  -drive file=obmc-phosphor-image.rootfs.wic.qcow2,if=sd,index=2 \
  -append "rootwait console=ttyS4,115200n8 root=PARTLABEL=rofs-a"

The implementation appears as following in the qemu device tree:

.. code-block:: console

  (qemu) info qtree
  bus: main-system-bus
    type System
    ...
    dev: aspeed.apb2opb, id ""
      gpio-out "sysbus-irq" 1
      mmio 000000001e79b000/0000000000001000
      bus: opb.1
        type opb
        dev: fsi.master, id ""
          bus: fsi.bus.1
            type fsi.bus
            dev: cfam.config, id ""
            dev: cfam, id ""
              bus: lbus.1
                type lbus
                dev: scratchpad, id ""
                  address = 0 (0x0)
      bus: opb.0
        type opb
        dev: fsi.master, id ""
          bus: fsi.bus.0
            type fsi.bus
            dev: cfam.config, id ""
            dev: cfam, id ""
              bus: lbus.0
                type lbus
                dev: scratchpad, id ""
                  address = 0 (0x0)

pdbg is a simple application to allow debugging of the host POWER processors
from the BMC. (see the `pdbg source repository`_ for more details)

.. code-block:: console

  root@p10bmc:~# pdbg -a getcfam 0x0
  p0: 0x0 = 0xc0022d15

.. _FSI specification:
   https://openpowerfoundation.org/specifications/fsi/

.. _pdbg source repository:
   https://github.com/open-power/pdbg
Commit	Line	Data
9f70e83a NP	1	======================================
	2	IBM's Flexible Service Interface (FSI)
	3	======================================
	4
	5	The QEMU FSI emulation implements hardware interfaces between ASPEED SOC, FSI
	6	master/slave and the end engine.
	7
	8	FSI is a point-to-point two wire interface which is capable of supporting
	9	distances of up to 4 meters. FSI interfaces have been used successfully for
	10	many years in IBM servers to attach IBM Flexible Support Processors(FSP) to
	11	CPUs and IBM ASICs.
	12
	13	FSI allows a service processor access to the internal buses of a host POWER
	14	processor to perform configuration or debugging. FSI has long existed in POWER
	15	processes and so comes with some baggage, including how it has been integrated
	16	into the ASPEED SoC.
	17
	18	Working backwards from the POWER processor, the fundamental pieces of interest
	19	for the implementation are: (see the `FSI specification`_ for more details)
	20
	21	1. The Common FRU Access Macro (CFAM), an address space containing various
	22	"engines" that drive accesses on buses internal and external to the POWER
	23	chip. Examples include the SBEFIFO and I2C masters. The engines hang off of
	24	an internal Local Bus (LBUS) which is described by the CFAM configuration
	25	block.
	26
	27	2. The FSI slave: The slave is the terminal point of the FSI bus for FSI
	28	symbols addressed to it. Slaves can be cascaded off of one another. The
	29	slave's configuration registers appear in address space of the CFAM to
	30	which it is attached.
	31
	32	3. The FSI master: A controller in the platform service processor (e.g. BMC)
	33	driving CFAM engine accesses into the POWER chip. At the hardware level
	34	FSI is a bit-based protocol supporting synchronous and DMA-driven accesses
	35	of engines in a CFAM.
	36
	37	4. The On-Chip Peripheral Bus (OPB): A low-speed bus typically found in POWER
	38	processors. This now makes an appearance in the ASPEED SoC due to tight
	39	integration of the FSI master IP with the OPB, mainly the existence of an
	40	MMIO-mapping of the CFAM address straight onto a sub-region of the OPB
	41	address space.
	42
	43	5. An APB-to-OPB bridge enabling access to the OPB from the ARM core in the
	44	AST2600. Hardware limitations prevent the OPB from being directly mapped
	45	into APB, so all accesses are indirect through the bridge.
	46
	47	The LBUS is modelled to maintain the qdev bus hierarchy and to take advantages
	48	of the object model to automatically generate the CFAM configuration block.
	49	The configuration block presents engines in the order they are attached to the
	50	CFAM's LBUS. Engine implementations should subclass the LBusDevice and set the
	51	'config' member of LBusDeviceClass to match the engine's type.
	52
	53	CFAM designs offer a lot of flexibility, for instance it is possible for a
	54	CFAM to be simultaneously driven from multiple FSI links. The modeling is not
	55	so complete; it's assumed that each CFAM is attached to a single FSI slave (as
	56	a consequence the CFAM subclasses the FSI slave).
	57
	58	As for FSI, its symbols and wire-protocol are not modelled at all. This is not
	59	necessary to get FSI off the ground thanks to the mapping of the CFAM address
	60	space onto the OPB address space - the models follow this directly and map the
	61	CFAM memory region into the OPB's memory region.
	62
	63	The following commands start the ``rainier-bmc`` machine with built-in FSI
	64	model. There are no model specific arguments. Please check this document to
65	learn more about Aspeed ``rainier-bmc`` machine: (:doc:`../../system/arm/aspeed`)
66
67	.. code-block:: console
68
69	qemu-system-arm -M rainier-bmc -nographic \
70	-kernel fitImage-linux.bin \
71	-dtb aspeed-bmc-ibm-rainier.dtb \
72	-initrd obmc-phosphor-initramfs.rootfs.cpio.xz \
73	-drive file=obmc-phosphor-image.rootfs.wic.qcow2,if=sd,index=2 \
74	-append "rootwait console=ttyS4,115200n8 root=PARTLABEL=rofs-a"
75
76	The implementation appears as following in the qemu device tree:
77
78	.. code-block:: console
79
80	(qemu) info qtree
81	bus: main-system-bus
82	type System
83	...
84	dev: aspeed.apb2opb, id ""
85	gpio-out "sysbus-irq" 1
86	mmio 000000001e79b000/0000000000001000
87	bus: opb.1
88	type opb
89	dev: fsi.master, id ""
90	bus: fsi.bus.1
91	type fsi.bus
92	dev: cfam.config, id ""
93	dev: cfam, id ""
94	bus: lbus.1
95	type lbus
96	dev: scratchpad, id ""
97	address = 0 (0x0)
98	bus: opb.0
99	type opb
100	dev: fsi.master, id ""
101	bus: fsi.bus.0
102	type fsi.bus
103	dev: cfam.config, id ""
104	dev: cfam, id ""
105	bus: lbus.0
106	type lbus
107	dev: scratchpad, id ""
108	address = 0 (0x0)
109
110	pdbg is a simple application to allow debugging of the host POWER processors
111	from the BMC. (see the `pdbg source repository`_ for more details)
112
113	.. code-block:: console
114
115	root@p10bmc:~# pdbg -a getcfam 0x0
116	p0: 0x0 = 0xc0022d15
117
118	.. _FSI specification:
119	https://openpowerfoundation.org/specifications/fsi/
120
121	.. _pdbg source repository:
122	https://github.com/open-power/pdbg