All of lore.kernel.org
 help / color / mirror / Atom feed
From: "Cédric Le Goater" <clg@kaod.org>
To: qemu-arm@nongnu.org, qemu-devel@nongnu.org
Cc: "Ninad Palsule" <ninad@linux.ibm.com>, "Cédric Le Goater" <clg@kaod.org>
Subject: [PULL 16/17] hw/fsi: Added FSI documentation
Date: Thu,  1 Feb 2024 15:12:52 +0100	[thread overview]
Message-ID: <20240201141253.806055-17-clg@kaod.org> (raw)
In-Reply-To: <20240201141253.806055-1-clg@kaod.org>

From: Ninad Palsule <ninad@linux.ibm.com>

Documentation for IBM FSI model.

Signed-off-by: Ninad Palsule <ninad@linux.ibm.com>
Reviewed-by: Cédric Le Goater <clg@kaod.org>
[ clg : - Removed source file list
        - Fixed aspeed machine reference ]
Signed-off-by: Cédric Le Goater <clg@kaod.org>
---
 docs/specs/fsi.rst   | 122 +++++++++++++++++++++++++++++++++++++++++++
 docs/specs/index.rst |   1 +
 2 files changed, 123 insertions(+)
 create mode 100644 docs/specs/fsi.rst

diff --git a/docs/specs/fsi.rst b/docs/specs/fsi.rst
new file mode 100644
index 000000000000..af8782253152
--- /dev/null
+++ b/docs/specs/fsi.rst
@@ -0,0 +1,122 @@
+======================================
+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
diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index b3f482b0aa58..1484e3e76077 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -24,6 +24,7 @@ guest hardware that is specific to QEMU.
    acpi_erst
    sev-guest-firmware
    fw_cfg
+   fsi
    vmw_pvscsi-spec
    edu
    ivshmem-spec
-- 
2.43.0



  parent reply	other threads:[~2024-02-01 14:16 UTC|newest]

Thread overview: 20+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2024-02-01 14:12 [PULL v2 00/17] aspeed queue Cédric Le Goater
2024-02-01 14:12 ` [PULL 01/17] tests/avocado/machine_aspeed.py: Update buildroot images to 2023.11 Cédric Le Goater
2024-02-01 14:12 ` [PULL 02/17] hw/arm/aspeed: Remove dead code Cédric Le Goater
2024-02-01 14:12 ` [PULL 03/17] hw/arm/aspeed: Set default CPU count using aspeed_soc_num_cpus() Cédric Le Goater
2024-02-01 14:12 ` [PULL 04/17] hw/arm/aspeed: Init CPU defaults in a common helper Cédric Le Goater
2024-02-01 14:12 ` [PULL 05/17] hw/arm/aspeed: Introduce aspeed_soc_cpu_type() helper Cédric Le Goater
2024-02-01 14:12 ` [PULL 06/17] hw/arm/aspeed: Check for CPU types in machine_run_board_init() Cédric Le Goater
2024-02-01 14:12 ` [PULL 07/17] hw/fsi: Introduce IBM's Local bus Cédric Le Goater
2024-02-01 14:12 ` [PULL 08/17] hw/fsi: Introduce IBM's scratchpad device Cédric Le Goater
2024-02-01 14:12 ` [PULL 09/17] hw/fsi: Introduce IBM's FSI Bus Cédric Le Goater
2024-02-01 14:12 ` [PULL 10/17] hw/fsi: Introduce IBM's fsi-slave model Cédric Le Goater
2024-02-01 14:12 ` [PULL 11/17] hw/fsi: Introduce IBM's cfam Cédric Le Goater
2024-02-01 14:12 ` [PULL 12/17] hw/fsi: Introduce IBM's FSI master Cédric Le Goater
2024-02-01 14:12 ` [PULL 13/17] hw/fsi: Aspeed APB2OPB & On-chip peripheral bus Cédric Le Goater
2024-02-01 14:12 ` [PULL 14/17] hw/arm: Hook up FSI module in AST2600 Cédric Le Goater
2024-02-01 14:12 ` [PULL 15/17] hw/fsi: Added qtest Cédric Le Goater
2024-02-01 14:12 ` Cédric Le Goater [this message]
2024-02-01 14:12 ` [PULL 17/17] hw/fsi: Update MAINTAINER list Cédric Le Goater
2024-02-02 13:50 ` [PULL v2 00/17] aspeed queue Peter Maydell
  -- strict thread matches above, loose matches on Subject: below --
2024-01-26 13:31 [PULL " Cédric Le Goater
2024-01-26 13:32 ` [PULL 16/17] hw/fsi: Added FSI documentation Cédric Le Goater

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20240201141253.806055-17-clg@kaod.org \
    --to=clg@kaod.org \
    --cc=ninad@linux.ibm.com \
    --cc=qemu-arm@nongnu.org \
    --cc=qemu-devel@nongnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.