docs/specs/fsi.rst

   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