Arm queue; not huge but I figured I might as well send it out since

I've been doing code review today and there's no queue of unprocessed

pullreqs...

Merge remote-tracking branch 'remotes/huth-gitlab/tags/pull-request-2021-01-11v2' into staging (2021-01-11 15:15:35 +0000)

https://git.linaro.org/people/pmaydell/qemu-arm.git tags/pull-target-arm-20210112

for you to fetch changes up to 19d131395ccaf503db21dadd8257e6dc9fc1d7de:

ui/cocoa: Fix openFile: deprecation on Big Sur (2021-01-12 11:38:37 +0000)

* arm: Support emulation of ARMv8.4-TTST extension

* arm: Update cpu.h ID register field definitions

* arm: Fix breakage of XScale instruction emulation

* hw/net/lan9118: Fix RX Status FIFO PEEK value

* npcm7xx: Add ADC and PWM emulation

* ui/cocoa: Make "open docs" help menu entry work again when binary

is run from the build tree

* ui/cocoa: Fix openFile: deprecation on Big Sur

* docs: Add qemu-storage-daemon(1) manpage to meson.build

* docs: Build and install all the docs in a single manual

Hao Wu (6):

hw/misc: Add clock converter in NPCM7XX CLK module

hw/timer: Refactor NPCM7XX Timer to use CLK clock

hw/adc: Add an ADC module for NPCM7XX

hw/misc: Add a PWM module for NPCM7XX

hw/misc: Add QTest for NPCM7XX PWM Module

hw/*: Use type casting for SysBusDevice in NPCM7XX

Leif Lindholm (6):

target/arm: fix typo in cpu.h ID_AA64PFR1 field name

target/arm: make ARMCPU.clidr 64-bit

target/arm: make ARMCPU.ctr 64-bit

target/arm: add descriptions of CLIDR_EL1, CCSIDR_EL1, CTR_EL0 to cpu.h

target/arm: add aarch64 ID register fields to cpu.h

target/arm: add aarch32 ID register fields to cpu.h

Peter Maydell (5):

docs: Add qemu-storage-daemon(1) manpage to meson.build

docs: Build and install all the docs in a single manual

target/arm: Don't decode insns in the XScale/iWMMXt space as cp insns

hw/net/lan9118: Fix RX Status FIFO PEEK value

hw/net/lan9118: Add symbolic constants for register offsets

Roman Bolshakov (2):

ui/cocoa: Update path to docs in build tree

ui/cocoa: Fix openFile: deprecation on Big Sur

Rémi Denis-Courmont (2):

target/arm: ARMv8.4-TTST extension

target/arm: enable Small Translation tables in max CPU

docs/conf.py | 46 ++-

docs/devel/conf.py | 15 -

docs/index.html.in | 17 -

docs/interop/conf.py | 28 --

docs/meson.build | 65 ++--

docs/specs/conf.py | 16 -

docs/system/arm/nuvoton.rst | 4 +-

docs/system/conf.py | 28 --

docs/tools/conf.py | 37 --

docs/user/conf.py | 15 -

meson.build | 1 +

hw/adc/trace.h | 1 +

include/hw/adc/npcm7xx_adc.h | 69 ++++

include/hw/arm/npcm7xx.h | 4 +

include/hw/misc/npcm7xx_clk.h | 146 ++++++-

include/hw/misc/npcm7xx_pwm.h | 105 +++++

include/hw/timer/npcm7xx_timer.h | 1 +

target/arm/cpu.h | 85 ++++-

hw/adc/npcm7xx_adc.c | 301 +++++++++++++++

hw/arm/npcm7xx.c | 55 ++-

hw/arm/npcm7xx_boards.c | 2 +-

hw/mem/npcm7xx_mc.c | 2 +-

hw/misc/npcm7xx_clk.c | 807 ++++++++++++++++++++++++++++++++++++++-

hw/misc/npcm7xx_gcr.c | 2 +-

hw/misc/npcm7xx_pwm.c | 550 ++++++++++++++++++++++++++

hw/misc/npcm7xx_rng.c | 2 +-

hw/net/lan9118.c | 26 +-

hw/nvram/npcm7xx_otp.c | 2 +-

hw/ssi/npcm7xx_fiu.c | 2 +-

hw/timer/npcm7xx_timer.c | 39 +-

target/arm/cpu64.c | 1 +

target/arm/helper.c | 15 +-

target/arm/translate.c | 7 +

tests/qtest/npcm7xx_adc-test.c | 377 ++++++++++++++++++

tests/qtest/npcm7xx_pwm-test.c | 490 ++++++++++++++++++++++++

hw/adc/meson.build | 1 +

hw/adc/trace-events | 5 +

hw/misc/meson.build | 1 +

hw/misc/trace-events | 6 +

tests/qtest/meson.build | 4 +-

ui/cocoa.m | 7 +-

41 files changed, 3124 insertions(+), 263 deletions(-)

delete mode 100644 docs/devel/conf.py

delete mode 100644 docs/index.html.in

delete mode 100644 docs/interop/conf.py

delete mode 100644 docs/specs/conf.py

delete mode 100644 docs/system/conf.py

delete mode 100644 docs/tools/conf.py

delete mode 100644 docs/user/conf.py

create mode 100644 hw/adc/trace.h

create mode 100644 include/hw/adc/npcm7xx_adc.h

create mode 100644 include/hw/misc/npcm7xx_pwm.h

create mode 100644 hw/adc/npcm7xx_adc.c

create mode 100644 hw/misc/npcm7xx_pwm.c

create mode 100644 tests/qtest/npcm7xx_adc-test.c

create mode 100644 tests/qtest/npcm7xx_pwm-test.c

create mode 100644 hw/adc/trace-events

From: Rémi Denis-Courmont <remi.denis.courmont@huawei.com>

This adds for the Small Translation tables extension in AArch64 state.

Signed-off-by: Rémi Denis-Courmont <remi.denis.courmont@huawei.com>

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

---

target/arm/cpu.h | 5 +++++

target/arm/helper.c | 15 +++++++++++++--

2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/target/arm/cpu.h b/target/arm/cpu.h

index XXXXXXX..XXXXXXX 100644

--- a/target/arm/cpu.h

+++ b/target/arm/cpu.h

@@ -XXX,XX +XXX,XX @@ static inline bool isar_feature_aa64_uao(const ARMISARegisters *id)

return FIELD_EX64(id->id_aa64mmfr2, ID_AA64MMFR2, UAO) != 0;

}

+static inline bool isar_feature_aa64_st(const ARMISARegisters *id)

+{

+ return FIELD_EX64(id->id_aa64mmfr2, ID_AA64MMFR2, ST) != 0;

+}

+

static inline bool isar_feature_aa64_bti(const ARMISARegisters *id)

{

return FIELD_EX64(id->id_aa64pfr1, ID_AA64PFR1, BT) != 0;

@@ -XXX,XX +XXX,XX @@ ARMVAParameters aa64_va_parameters(CPUARMState *env, uint64_t va,

{

uint64_t tcr = regime_tcr(env, mmu_idx)->raw_tcr;

bool epd, hpd, using16k, using64k;

- int select, tsz, tbi;

+ int select, tsz, tbi, max_tsz;

if (!regime_has_2_ranges(mmu_idx)) {

select = 0;

@@ -XXX,XX +XXX,XX @@ ARMVAParameters aa64_va_parameters(CPUARMState *env, uint64_t va,

hpd = extract64(tcr, 42, 1);

}

}

- tsz = MIN(tsz, 39); /* TODO: ARMv8.4-TTST */

+ if (cpu_isar_feature(aa64_st, env_archcpu(env))) {

+ max_tsz = 48 - using64k;

+ } else {

+ max_tsz = 39;

+ }

+

+ tsz = MIN(tsz, max_tsz);

tsz = MAX(tsz, 16); /* TODO: ARMv8.2-LVA */

/* Present TBI as a composite with TBID. */

@@ -XXX,XX +XXX,XX @@ static bool get_phys_addr_lpae(CPUARMState *env, uint64_t address,

if (!aarch64 || stride == 9) {

/* AArch32 or 4KB pages */

startlevel = 2 - sl0;

+

+ if (cpu_isar_feature(aa64_st, cpu)) {

+ startlevel &= 3;

+ }

} else {

/* 16KB or 64KB pages */

startlevel = 3 - sl0;

2.20.1

From: Rémi Denis-Courmont <remi.denis.courmont@huawei.com>

Signed-off-by: Rémi Denis-Courmont <remi.denis.courmont@huawei.com>

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

target/arm/cpu64.c | 1 +

diff --git a/target/arm/cpu64.c b/target/arm/cpu64.c

--- a/target/arm/cpu64.c

+++ b/target/arm/cpu64.c

@@ -XXX,XX +XXX,XX @@ static void aarch64_max_initfn(Object *obj)

t = cpu->isar.id_aa64mmfr2;

t = FIELD_DP64(t, ID_AA64MMFR2, UAO, 1);

t = FIELD_DP64(t, ID_AA64MMFR2, CNP, 1); /* TTCNP */

+ t = FIELD_DP64(t, ID_AA64MMFR2, ST, 1); /* TTST */

cpu->isar.id_aa64mmfr2 = t;

/* Replicate the same data to the 32-bit id registers. */

2.20.1

From: Leif Lindholm <leif@nuviainc.com>

target/arm/cpu.h | 2 +-

1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/target/arm/cpu.h b/target/arm/cpu.h

--- a/target/arm/cpu.h

+++ b/target/arm/cpu.h

@@ -XXX,XX +XXX,XX @@ FIELD(ID_AA64PFR0, RAS, 28, 4)

FIELD(ID_AA64PFR0, SVE, 32, 4)

FIELD(ID_AA64PFR1, BT, 0, 4)

-FIELD(ID_AA64PFR1, SBSS, 4, 4)

+FIELD(ID_AA64PFR1, SSBS, 4, 4)

FIELD(ID_AA64PFR1, MTE, 8, 4)

FIELD(ID_AA64PFR1, RAS_FRAC, 12, 4)

2.20.1

From: Leif Lindholm <leif@nuviainc.com>

target/arm/cpu.h | 2 +-

1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/target/arm/cpu.h b/target/arm/cpu.h

--- a/target/arm/cpu.h

+++ b/target/arm/cpu.h

@@ -XXX,XX +XXX,XX @@ struct ARMCPU {

uint32_t id_afr0;

uint64_t id_aa64afr0;

uint64_t id_aa64afr1;

- uint32_t clidr;

+ uint64_t clidr;

uint64_t mp_affinity; /* MP ID without feature bits */

/* The elements of this array are the CCSIDR values for each cache,

* in the order L1DCache, L1ICache, L2DCache, L2ICache, etc.

2.20.1

From: Leif Lindholm <leif@nuviainc.com>

When FEAT_MTE is implemented, the AArch64 view of CTR_EL0 adds the

TminLine field in bits [37:32].

Extend the ctr field to be able to hold this context.

Signed-off-by: Leif Lindholm <leif@nuviainc.com>

Reviewed-by: Hao Wu <wuhaotsh@google.com>

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

Reviewed-by: Laurent Desnogues <laurent.desnogues@gmail.com>

Message-id: 20210108185154.8108-4-leif@nuviainc.com

target/arm/cpu.h | 2 +-

1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/target/arm/cpu.h b/target/arm/cpu.h

--- a/target/arm/cpu.h

+++ b/target/arm/cpu.h

@@ -XXX,XX +XXX,XX @@ struct ARMCPU {

uint64_t midr;

uint32_t revidr;

uint32_t reset_fpsid;

- uint32_t ctr;

+ uint64_t ctr;

uint32_t reset_sctlr;

uint64_t pmceid0;

uint64_t pmceid1;

2.20.1

From: Leif Lindholm <leif@nuviainc.com>

Signed-off-by: Leif Lindholm <leif@nuviainc.com>

Reviewed-by: Laurent Desnogues <laurent.desnogues@gmail.com>

Message-id: 20210108185154.8108-5-leif@nuviainc.com

target/arm/cpu.h | 31 +++++++++++++++++++++++++++++++

1 file changed, 31 insertions(+)

diff --git a/target/arm/cpu.h b/target/arm/cpu.h

--- a/target/arm/cpu.h

+++ b/target/arm/cpu.h

@@ -XXX,XX +XXX,XX @@ FIELD(V7M_FPCCR, ASPEN, 31, 1)

/*

* System register ID fields.

*/

+FIELD(CLIDR_EL1, CTYPE1, 0, 3)

+FIELD(CLIDR_EL1, CTYPE2, 3, 3)

+FIELD(CLIDR_EL1, CTYPE3, 6, 3)

+FIELD(CLIDR_EL1, CTYPE4, 9, 3)

+FIELD(CLIDR_EL1, CTYPE5, 12, 3)

+FIELD(CLIDR_EL1, CTYPE6, 15, 3)

+FIELD(CLIDR_EL1, CTYPE7, 18, 3)

+FIELD(CLIDR_EL1, LOUIS, 21, 3)

+FIELD(CLIDR_EL1, LOC, 24, 3)

+FIELD(CLIDR_EL1, LOUU, 27, 3)

+FIELD(CLIDR_EL1, ICB, 30, 3)

+

+/* When FEAT_CCIDX is implemented */

+FIELD(CCSIDR_EL1, CCIDX_LINESIZE, 0, 3)

+FIELD(CCSIDR_EL1, CCIDX_ASSOCIATIVITY, 3, 21)

+FIELD(CCSIDR_EL1, CCIDX_NUMSETS, 32, 24)

+

+/* When FEAT_CCIDX is not implemented */

+FIELD(CCSIDR_EL1, LINESIZE, 0, 3)

+FIELD(CCSIDR_EL1, ASSOCIATIVITY, 3, 10)

+FIELD(CCSIDR_EL1, NUMSETS, 13, 15)

+

+FIELD(CTR_EL0, IMINLINE, 0, 4)

+FIELD(CTR_EL0, L1IP, 14, 2)

+FIELD(CTR_EL0, DMINLINE, 16, 4)

+FIELD(CTR_EL0, ERG, 20, 4)

+FIELD(CTR_EL0, CWG, 24, 4)

+FIELD(CTR_EL0, IDC, 28, 1)

+FIELD(CTR_EL0, DIC, 29, 1)

+FIELD(CTR_EL0, TMINLINE, 32, 6)

+

FIELD(MIDR_EL1, REVISION, 0, 4)

FIELD(MIDR_EL1, PARTNUM, 4, 12)

FIELD(MIDR_EL1, ARCHITECTURE, 16, 4)

2.20.1

From: Leif Lindholm <leif@nuviainc.com>

target/arm/cpu.h | 15 +++++++++++++++

1 file changed, 15 insertions(+)

diff --git a/target/arm/cpu.h b/target/arm/cpu.h

--- a/target/arm/cpu.h

+++ b/target/arm/cpu.h

@@ -XXX,XX +XXX,XX @@ FIELD(ID_AA64ISAR1, GPI, 28, 4)

FIELD(ID_AA64ISAR1, FRINTTS, 32, 4)

FIELD(ID_AA64ISAR1, SB, 36, 4)

FIELD(ID_AA64ISAR1, SPECRES, 40, 4)

+FIELD(ID_AA64ISAR1, BF16, 44, 4)

+FIELD(ID_AA64ISAR1, DGH, 48, 4)

+FIELD(ID_AA64ISAR1, I8MM, 52, 4)

FIELD(ID_AA64PFR0, EL0, 0, 4)

FIELD(ID_AA64PFR0, EL1, 4, 4)

@@ -XXX,XX +XXX,XX @@ FIELD(ID_AA64PFR0, ADVSIMD, 20, 4)

FIELD(ID_AA64PFR0, GIC, 24, 4)

FIELD(ID_AA64PFR0, RAS, 28, 4)

FIELD(ID_AA64PFR0, SVE, 32, 4)

+FIELD(ID_AA64PFR0, SEL2, 36, 4)

+FIELD(ID_AA64PFR0, MPAM, 40, 4)

+FIELD(ID_AA64PFR0, AMU, 44, 4)

+FIELD(ID_AA64PFR0, DIT, 48, 4)

+FIELD(ID_AA64PFR0, CSV2, 56, 4)

+FIELD(ID_AA64PFR0, CSV3, 60, 4)

FIELD(ID_AA64PFR1, BT, 0, 4)

FIELD(ID_AA64PFR1, SSBS, 4, 4)

FIELD(ID_AA64PFR1, MTE, 8, 4)

FIELD(ID_AA64PFR1, RAS_FRAC, 12, 4)

+FIELD(ID_AA64PFR1, MPAM_FRAC, 16, 4)

FIELD(ID_AA64MMFR0, PARANGE, 0, 4)

FIELD(ID_AA64MMFR0, ASIDBITS, 4, 4)

@@ -XXX,XX +XXX,XX @@ FIELD(ID_AA64MMFR0, TGRAN16_2, 32, 4)

FIELD(ID_AA64MMFR0, TGRAN64_2, 36, 4)

FIELD(ID_AA64MMFR0, TGRAN4_2, 40, 4)

FIELD(ID_AA64MMFR0, EXS, 44, 4)

+FIELD(ID_AA64MMFR0, FGT, 56, 4)

+FIELD(ID_AA64MMFR0, ECV, 60, 4)

FIELD(ID_AA64MMFR1, HAFDBS, 0, 4)

FIELD(ID_AA64MMFR1, VMIDBITS, 4, 4)

@@ -XXX,XX +XXX,XX @@ FIELD(ID_AA64MMFR1, LO, 16, 4)

FIELD(ID_AA64MMFR1, PAN, 20, 4)

FIELD(ID_AA64MMFR1, SPECSEI, 24, 4)

FIELD(ID_AA64MMFR1, XNX, 28, 4)

+FIELD(ID_AA64MMFR1, TWED, 32, 4)

+FIELD(ID_AA64MMFR1, ETS, 36, 4)

FIELD(ID_AA64MMFR2, CNP, 0, 4)

FIELD(ID_AA64MMFR2, UAO, 4, 4)

@@ -XXX,XX +XXX,XX @@ FIELD(ID_AA64DFR0, CTX_CMPS, 28, 4)

FIELD(ID_AA64DFR0, PMSVER, 32, 4)

FIELD(ID_AA64DFR0, DOUBLELOCK, 36, 4)

FIELD(ID_AA64DFR0, TRACEFILT, 40, 4)

+FIELD(ID_AA64DFR0, MTPMU, 48, 4)

FIELD(ID_DFR0, COPDBG, 0, 4)

FIELD(ID_DFR0, COPSDBG, 4, 4)

2.20.1

From: Leif Lindholm <leif@nuviainc.com>

target/arm/cpu.h | 28 ++++++++++++++++++++++++++++

1 file changed, 28 insertions(+)

diff --git a/target/arm/cpu.h b/target/arm/cpu.h

--- a/target/arm/cpu.h

+++ b/target/arm/cpu.h

@@ -XXX,XX +XXX,XX @@ FIELD(ID_ISAR6, DP, 4, 4)

FIELD(ID_ISAR6, FHM, 8, 4)

FIELD(ID_ISAR6, SB, 12, 4)

FIELD(ID_ISAR6, SPECRES, 16, 4)

+FIELD(ID_ISAR6, BF16, 20, 4)

+FIELD(ID_ISAR6, I8MM, 24, 4)

FIELD(ID_MMFR0, VMSA, 0, 4)

FIELD(ID_MMFR0, PMSA, 4, 4)

@@ -XXX,XX +XXX,XX @@ FIELD(ID_MMFR0, AUXREG, 20, 4)

FIELD(ID_MMFR0, FCSE, 24, 4)

FIELD(ID_MMFR0, INNERSHR, 28, 4)

+FIELD(ID_MMFR1, L1HVDVA, 0, 4)

+FIELD(ID_MMFR1, L1UNIVA, 4, 4)

+FIELD(ID_MMFR1, L1HVDSW, 8, 4)

+FIELD(ID_MMFR1, L1UNISW, 12, 4)

+FIELD(ID_MMFR1, L1HVD, 16, 4)

+FIELD(ID_MMFR1, L1UNI, 20, 4)

+FIELD(ID_MMFR1, L1TSTCLN, 24, 4)

+FIELD(ID_MMFR1, BPRED, 28, 4)

+

+FIELD(ID_MMFR2, L1HVDFG, 0, 4)

+FIELD(ID_MMFR2, L1HVDBG, 4, 4)

+FIELD(ID_MMFR2, L1HVDRNG, 8, 4)

+FIELD(ID_MMFR2, HVDTLB, 12, 4)

+FIELD(ID_MMFR2, UNITLB, 16, 4)

+FIELD(ID_MMFR2, MEMBARR, 20, 4)

+FIELD(ID_MMFR2, WFISTALL, 24, 4)

+FIELD(ID_MMFR2, HWACCFLG, 28, 4)

+

FIELD(ID_MMFR3, CMAINTVA, 0, 4)

FIELD(ID_MMFR3, CMAINTSW, 4, 4)

FIELD(ID_MMFR3, BPMAINT, 8, 4)

@@ -XXX,XX +XXX,XX @@ FIELD(ID_MMFR4, LSM, 20, 4)

FIELD(ID_MMFR4, CCIDX, 24, 4)

FIELD(ID_MMFR4, EVT, 28, 4)

+FIELD(ID_MMFR5, ETS, 0, 4)

+

FIELD(ID_PFR0, STATE0, 0, 4)

FIELD(ID_PFR0, STATE1, 4, 4)

FIELD(ID_PFR0, STATE2, 8, 4)

@@ -XXX,XX +XXX,XX @@ FIELD(ID_PFR1, SEC_FRAC, 20, 4)

FIELD(ID_PFR1, VIRT_FRAC, 24, 4)

FIELD(ID_PFR1, GIC, 28, 4)

+FIELD(ID_PFR2, CSV3, 0, 4)

+FIELD(ID_PFR2, SSBS, 4, 4)

+FIELD(ID_PFR2, RAS_FRAC, 8, 4)

+

FIELD(ID_AA64ISAR0, AES, 4, 4)

FIELD(ID_AA64ISAR0, SHA1, 8, 4)

FIELD(ID_AA64ISAR0, SHA2, 12, 4)

@@ -XXX,XX +XXX,XX @@ FIELD(ID_DFR0, MPROFDBG, 20, 4)

FIELD(ID_DFR0, PERFMON, 24, 4)

FIELD(ID_DFR0, TRACEFILT, 28, 4)

+FIELD(ID_DFR1, MTPMU, 0, 4)

+

FIELD(DBGDIDR, SE_IMP, 12, 1)

FIELD(DBGDIDR, NSUHD_IMP, 14, 1)

FIELD(DBGDIDR, VERSION, 16, 4)

2.20.1

From: Roman Bolshakov <r.bolshakov@yadro.com>

QEMU documentation can't be opened if QEMU is run from build tree

because executables are placed in the top of build tree after conversion

to meson.

Signed-off-by: Roman Bolshakov <r.bolshakov@yadro.com>

Reported-by: Peter Maydell <peter.maydell@linaro.org>

Message-id: 20210108213815.64678-1-r.bolshakov@yadro.com

ui/cocoa.m | 2 +-

1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ui/cocoa.m b/ui/cocoa.m

--- a/ui/cocoa.m

+++ b/ui/cocoa.m

@@ -XXX,XX +XXX,XX @@ QemuCocoaView *cocoaView;

- (void) openDocumentation: (NSString *) filename

{

/* Where to look for local files */

- NSString *path_array[] = {@"../share/doc/qemu/", @"../doc/qemu/", @"../docs/"};

+ NSString *path_array[] = {@"../share/doc/qemu/", @"../doc/qemu/", @"docs/"};

NSString *full_file_path;

/* iterate thru the possible paths until the file is found */

2.20.1

In commit 1982e1602d15 we added a new qemu-storage-daemon(1) manpage.

At the moment new manpages have to be listed both in the conf.py for

Sphinx and also in docs/meson.build for Meson. We forgot the second

of those -- correct the omission.

Message-id: 20210108161416.21129-2-peter.maydell@linaro.org

docs/meson.build | 1 +

1 file changed, 1 insertion(+)

diff --git a/docs/meson.build b/docs/meson.build

--- a/docs/meson.build

+++ b/docs/meson.build

@@ -XXX,XX +XXX,XX @@ if build_docs

'qemu-img.1': (have_tools ? 'man1' : ''),

'qemu-nbd.8': (have_tools ? 'man8' : ''),

'qemu-pr-helper.8': (have_tools ? 'man8' : ''),

+ 'qemu-storage-daemon.1': (have_tools ? 'man1' : ''),

'qemu-trace-stap.1': (config_host.has_key('CONFIG_TRACE_SYSTEMTAP') ? 'man1' : ''),

'virtfs-proxy-helper.1': (have_virtfs_proxy_helper ? 'man1' : ''),

'virtiofsd.1': (have_virtiofsd ? 'man1' : ''),

2.20.1

When we first converted our documentation to Sphinx, we split it into

multiple manuals (system, interop, tools, etc), which are all built

separately. The primary driver for this was wanting to be able to

avoid shipping the 'devel' manual to end-users. However, this is

working against the grain of the way Sphinx wants to be used and

causes some annoyances:

* Cross-references between documents become much harder or

possibly impossible

* There is no single index to the whole documentation

* Within one manual there's no links or table-of-contents info

that lets you easily navigate to the others

* The devel manual doesn't get published on the QEMU website

(it would be nice to able to refer to it there)

Merely hiding our developer documentation from end users seems like

it's not enough benefit for these costs. Combine all the

documentation into a single manual (the same way that the readthedocs

site builds it) and install the whole thing. The previous manual

divisions remain as the new top level sections in the manual.

* The per-manual conf.py files are no longer needed

* The man_pages[] specifications previously in each per-manual

conf.py move to the top level conf.py

* docs/meson.build logic is simplified as we now only need to run

Sphinx once for the HTML and then once for the manpages5B

* The old index.html.in that produced the top-level page with

links to each manual is no longer needed

Unfortunately this means that we now have to build the HTML

documentation into docs/manual in the build tree rather than directly

into docs/; otherwise it is too awkward to ensure we install only the

built manual and not also the dependency info, stamp file, etc. The

manual still ends up in the same place in the final installed

directory, but anybody who was consulting documentation from within

the build tree will have to adjust where they're looking.

Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>

Message-id: 20210108161416.21129-3-peter.maydell@linaro.org

docs/conf.py | 46 ++++++++++++++++++++++++++++++-

docs/devel/conf.py | 15 -----------

docs/index.html.in | 17 ------------

docs/interop/conf.py | 28 -------------------

docs/meson.build | 64 +++++++++++++++++---------------------------

docs/specs/conf.py | 16 -----------

docs/system/conf.py | 28 -------------------

docs/tools/conf.py | 37 -------------------------

docs/user/conf.py | 15 -----------

9 files changed, 70 insertions(+), 196 deletions(-)

delete mode 100644 docs/devel/conf.py

delete mode 100644 docs/index.html.in

delete mode 100644 docs/interop/conf.py

delete mode 100644 docs/specs/conf.py

delete mode 100644 docs/system/conf.py

delete mode 100644 docs/tools/conf.py

delete mode 100644 docs/user/conf.py

diff --git a/docs/conf.py b/docs/conf.py

--- a/docs/conf.py

+++ b/docs/conf.py

@@ -XXX,XX +XXX,XX @@ latex_documents = [

# -- Options for manual page output ---------------------------------------

# Individual manual/conf.py can override this to create man pages

-man_pages = []

+man_pages = [

+ ('interop/qemu-ga', 'qemu-ga',

+ 'QEMU Guest Agent',

+ ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),

+ ('interop/qemu-ga-ref', 'qemu-ga-ref',

+ 'QEMU Guest Agent Protocol Reference',

+ [], 7),

+ ('interop/qemu-qmp-ref', 'qemu-qmp-ref',

+ 'QEMU QMP Reference Manual',

+ [], 7),

+ ('interop/qemu-storage-daemon-qmp-ref', 'qemu-storage-daemon-qmp-ref',

+ 'QEMU Storage Daemon QMP Reference Manual',

+ [], 7),

+ ('system/qemu-manpage', 'qemu',

+ 'QEMU User Documentation',

+ ['Fabrice Bellard'], 1),

+ ('system/qemu-block-drivers', 'qemu-block-drivers',

+ 'QEMU block drivers reference',

+ ['Fabrice Bellard and the QEMU Project developers'], 7),

+ ('system/qemu-cpu-models', 'qemu-cpu-models',

+ 'QEMU CPU Models',

+ ['The QEMU Project developers'], 7),

+ ('tools/qemu-img', 'qemu-img',

+ 'QEMU disk image utility',

+ ['Fabrice Bellard'], 1),

+ ('tools/qemu-nbd', 'qemu-nbd',

+ 'QEMU Disk Network Block Device Server',

+ ['Anthony Liguori <anthony@codemonkey.ws>'], 8),

+ ('tools/qemu-pr-helper', 'qemu-pr-helper',

+ 'QEMU persistent reservation helper',

+ [], 8),

+ ('tools/qemu-storage-daemon', 'qemu-storage-daemon',

+ 'QEMU storage daemon',

+ [], 1),

+ ('tools/qemu-trace-stap', 'qemu-trace-stap',

+ 'QEMU SystemTap trace tool',

+ [], 1),

+ ('tools/virtfs-proxy-helper', 'virtfs-proxy-helper',

+ 'QEMU 9p virtfs proxy filesystem helper',

+ ['M. Mohan Kumar'], 1),

+ ('tools/virtiofsd', 'virtiofsd',

+ 'QEMU virtio-fs shared file system daemon',

+ ['Stefan Hajnoczi <stefanha@redhat.com>',

+ 'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1),

+]

# -- Options for Texinfo output -------------------------------------------

diff --git a/docs/devel/conf.py b/docs/devel/conf.py

deleted file mode 100644

index XXXXXXX..XXXXXXX

--- a/docs/devel/conf.py

+++ /dev/null

@@ -XXX,XX +XXX,XX @@

-# -*- coding: utf-8 -*-

-#

-# QEMU documentation build configuration file for the 'devel' manual.

-#

-# This includes the top level conf file and then makes any necessary tweaks.

-import sys

-import os

-

-qemu_docdir = os.path.abspath("..")

-parent_config = os.path.join(qemu_docdir, "conf.py")

-exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))

-

-# This slightly misuses the 'description', but is the best way to get

-# the manual title to appear in the sidebar.

-html_theme_options['description'] = u'Developer''s Guide'

diff --git a/docs/index.html.in b/docs/index.html.in

deleted file mode 100644

index XXXXXXX..XXXXXXX

--- a/docs/index.html.in

+++ /dev/null

@@ -XXX,XX +XXX,XX @@

-<!DOCTYPE html>

-<html lang="en">

- <head>

- <meta charset="UTF-8">

- <title>QEMU @VERSION@ Documentation</title>

- </head>

- <body>

- <h1>QEMU @VERSION@ Documentation</h1>

- <ul>

- <li><a href="system/index.html">System Emulation User's Guide</a></li>

- <li><a href="user/index.html">User Mode Emulation User's Guide</a></li>

- <li><a href="tools/index.html">Tools Guide</a></li>

- <li><a href="interop/index.html">System Emulation Management and Interoperability Guide</a></li>

- <li><a href="specs/index.html">System Emulation Guest Hardware Specifications</a></li>

- </ul>

- </body>

-</html>

diff --git a/docs/interop/conf.py b/docs/interop/conf.py

deleted file mode 100644

index XXXXXXX..XXXXXXX

--- a/docs/interop/conf.py

+++ /dev/null

@@ -XXX,XX +XXX,XX @@

-# -*- coding: utf-8 -*-

-#

-# QEMU documentation build configuration file for the 'interop' manual.

-#

-# This includes the top level conf file and then makes any necessary tweaks.

-import sys

-import os

-

-qemu_docdir = os.path.abspath("..")

-parent_config = os.path.join(qemu_docdir, "conf.py")

-exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))

-

-# This slightly misuses the 'description', but is the best way to get

-# the manual title to appear in the sidebar.

-html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

-

-# One entry per manual page. List of tuples

-# (source start file, name, description, authors, manual section).

-man_pages = [

- ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',

- ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),

- ('qemu-ga-ref', 'qemu-ga-ref', 'QEMU Guest Agent Protocol Reference',

- [], 7),

- ('qemu-qmp-ref', 'qemu-qmp-ref', 'QEMU QMP Reference Manual',

- [], 7),

- ('qemu-storage-daemon-qmp-ref', 'qemu-storage-daemon-qmp-ref',

- 'QEMU Storage Daemon QMP Reference Manual', [], 7),

-]

diff --git a/docs/meson.build b/docs/meson.build

--- a/docs/meson.build

+++ b/docs/meson.build

@@ -XXX,XX +XXX,XX @@ if build_docs

meson.source_root() / 'docs/sphinx/qmp_lexer.py',

qapi_gen_depends ]

- configure_file(output: 'index.html',

- input: files('index.html.in'),

- configuration: {'VERSION': meson.project_version()},

- install_dir: qemu_docdir)

- manuals = [ 'devel', 'interop', 'tools', 'specs', 'system', 'user' ]

man_pages = {

- 'interop' : {

'qemu-ga.8': (have_tools ? 'man8' : ''),

'qemu-ga-ref.7': 'man7',

'qemu-qmp-ref.7': 'man7',

'qemu-storage-daemon-qmp-ref.7': (have_tools ? 'man7' : ''),

- },

- 'tools': {

'qemu-img.1': (have_tools ? 'man1' : ''),

'qemu-nbd.8': (have_tools ? 'man8' : ''),

'qemu-pr-helper.8': (have_tools ? 'man8' : ''),

@@ -XXX,XX +XXX,XX @@ if build_docs

'qemu-trace-stap.1': (config_host.has_key('CONFIG_TRACE_SYSTEMTAP') ? 'man1' : ''),

'virtfs-proxy-helper.1': (have_virtfs_proxy_helper ? 'man1' : ''),

'virtiofsd.1': (have_virtiofsd ? 'man1' : ''),

- },

- 'system': {

'qemu.1': 'man1',

'qemu-block-drivers.7': 'man7',

'qemu-cpu-models.7': 'man7'

- },

}

sphinxdocs = []

sphinxmans = []

- foreach manual : manuals