[PATCH-for-5.2 7/7] hw/block/fdc: Add ASCII art schema of QOM relations

[Philippe Mathieu-Daudé]

Without knowing the QEMU history, it is hard to relate QEMU objects
with the hardware datasheet.

For example, one naively expects:

* a floppy disk is plugged / unplugged on the bus

  Wrong! QEMU floppy disks always sit on the bus. The block drives
  are plugged / unplugged on the disks, and the disks magically
  re-adapt their proprieties to match the block drive.

* a floppy controller has a fixed number of disks pluggable on the bus

  Wrong! QEMU floppy controllers have as much slots as the number of
  floppy drive provided when a machine is created. Then the ACPI table
  are generated and the number of slots can not be modified. So if you
  expect a dual slot controller being created with slot A and B, if
  the machine is created with a single drive attached, the controller
  will only have slot A created, and you will never be able to plug
  drive B without risking a mismatch in the ACPI tables.

* a floppy controller supporting 4 disks uses 2 buses

  Wrong! QEMU uses a single bus to plug the 4 disks.

As all these false assumptions are not obvious (we don't plug a disk,
we plug a block drive into a disk, etc...), start documenting the QOM
relationships with a simple ASCII schema.

Signed-off-by: Philippe Mathieu-Daudé <f4bug@amsat.org>
---
 hw/block/fdc.c | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/hw/block/fdc.c b/hw/block/fdc.c
index 6944b06e4b..b109f37050 100644
--- a/hw/block/fdc.c
+++ b/hw/block/fdc.c
@@ -47,6 +47,28 @@
 #include "qemu/module.h"
 #include "trace.h"
 
+/*
+ * QOM relationship:
+ * =================
+ *
+ *                  +-------------------+
+ *                  |                   |
+ * isa/sysbus  <--->|                   |
+ *                  |                   |
+ *  irq/dma    <----|        fdc        |
+ *                  |
+ *      clk    ---->|                   |        +-+------+-+    +-+------+-+
+ *                  |                   |        | | blk  | |    | | blk  | |
+ *                  +--------+----------+        | |      | |    | |      | |
+ *                           |                   | +------+ |    | +------+ |
+ *                           |                   |          |    |          |
+ *                           |                   |  floppy  |    |  floppy  |
+ *                           |                   +----+-----+    +----+-----+
+ *                           |   floppy-bus           |               |
+ *                           +------------------------v---------------v---
+ *
+ */
+
 /********************************************************/
 /* debug Floppy devices */
 
-- 
2.21.3