diff options
| author | Peter Maydell <peter.maydell@linaro.org> | 2020-03-12 15:20:52 +0000 |
|---|---|---|
| committer | Peter Maydell <peter.maydell@linaro.org> | 2020-03-12 15:20:52 +0000 |
| commit | 67d9ef7d541c3d21a25796c51c26da096a433565 (patch) | |
| tree | 727ec5df140f6b6ad6bd56270ba2d550d54e5e3e | |
| parent | 474acbe05d6a9c53ac358b45d8a095c6a68a10d6 (diff) | |
| parent | 6fe6d6c9a953901251e1a85088f0a61ff5caf648 (diff) | |
Merge remote-tracking branch 'remotes/pmaydell/tags/pull-docs-20200312' into staging
docs queue:
* Remove some no longer needed texinfo infrastructure
* Reorder the top level index docs to put most useful manuals first
* Split the Arm target-specific info into sub-pages
* Improve the Arm documentation a bit with info previously
only on the wiki page
# gpg: Signature made Thu 12 Mar 2020 11:42:10 GMT
# gpg: using RSA key E1A5C593CD419DE28E8315CF3C2525ED14360CDE
# gpg: issuer "peter.maydell@linaro.org"
# gpg: Good signature from "Peter Maydell <peter.maydell@linaro.org>" [ultimate]
# gpg: aka "Peter Maydell <pmaydell@gmail.com>" [ultimate]
# gpg: aka "Peter Maydell <pmaydell@chiark.greenend.org.uk>" [ultimate]
# Primary key fingerprint: E1A5 C593 CD41 9DE2 8E83 15CF 3C25 25ED 1436 0CDE
* remotes/pmaydell/tags/pull-docs-20200312:
docs: Be consistent about capitalization of 'Arm'
docs: Move arm-cpu-features.rst into the system manual
docs/system/target-arm.rst: Add some introductory text
docs/system: Split target-arm.rst into sub-documents
Makefile: Allow for subdirectories in Sphinx manual dependencies
docs/qemu-option-trace.rst.inc: Remove redundant comment
docs/index.rst, docs/index.html.in: Reorder manuals
Makefile: Make all Sphinx documentation depend on the extensions
docs/sphinx/hxtool.py: Remove STEXI/ETEXI support
hxtool: Remove Texinfo generation support
Update comments in .hx files that mention Texinfo
Makefile: Remove redundant Texinfo related code
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
31 files changed, 369 insertions, 378 deletions
diff --git a/MAINTAINERS b/MAINTAINERS index 857f969aa1..2903cbe564 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -155,6 +155,7 @@ F: include/hw/cpu/a*mpcore.h F: disas/arm.c F: disas/arm-a64.cc F: disas/libvixl/ +F: docs/system/target-arm.rst ARM SMMU M: Eric Auger <eric.auger@redhat.com> @@ -615,6 +616,7 @@ F: hw/arm/integratorcp.c F: hw/misc/arm_integrator_debug.c F: include/hw/misc/arm_integrator_debug.h F: tests/acceptance/machine_arm_integratorcp.py +F: docs/system/arm/integratorcp.rst MCIMX6UL EVK / i.MX6ul M: Peter Maydell <peter.maydell@linaro.org> @@ -673,6 +675,7 @@ M: Peter Maydell <peter.maydell@linaro.org> L: qemu-arm@nongnu.org S: Odd Fixes F: hw/arm/musicpal.c +F: docs/system/arm/musicpal.rst nSeries M: Andrzej Zaborowski <balrogg@gmail.com> @@ -689,6 +692,7 @@ F: include/hw/display/blizzard.h F: include/hw/input/tsc2xxx.h F: include/hw/misc/cbus.h F: tests/acceptance/machine_arm_n8x0.py +F: docs/system/arm/nseries.rst Palm M: Andrzej Zaborowski <balrogg@gmail.com> @@ -698,6 +702,7 @@ S: Odd Fixes F: hw/arm/palm.c F: hw/input/tsc210x.c F: include/hw/input/tsc2xxx.h +F: docs/system/arm/palm.rst Raspberry Pi M: Peter Maydell <peter.maydell@linaro.org> @@ -719,6 +724,7 @@ F: hw/arm/realview* F: hw/cpu/realview_mpcore.c F: hw/intc/realview_gic.c F: include/hw/intc/realview_gic.h +F: docs/system/arm/realview.rst PXA2XX M: Andrzej Zaborowski <balrogg@gmail.com> @@ -738,6 +744,7 @@ F: hw/misc/max111x.c F: include/hw/arm/pxa.h F: include/hw/arm/sharpsl.h F: include/hw/display/tc6393xb.h +F: docs/system/arm/xscale.rst SABRELITE / i.MX6 M: Peter Maydell <peter.maydell@linaro.org> @@ -773,6 +780,7 @@ L: qemu-arm@nongnu.org S: Maintained F: hw/*/stellaris* F: include/hw/input/gamepad.h +F: docs/system/arm/stellaris.rst Versatile Express M: Peter Maydell <peter.maydell@linaro.org> @@ -786,6 +794,7 @@ L: qemu-arm@nongnu.org S: Maintained F: hw/*/versatile* F: hw/misc/arm_sysctl.c +F: docs/system/arm/versatile.rst Virt M: Peter Maydell <peter.maydell@linaro.org> @@ -795,7 +795,7 @@ rm -f $(MANUAL_BUILDDIR)/$1/objects.inv $(MANUAL_BUILDDIR)/$1/searchindex.js $(M endef distclean: clean - rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi + rm -f config-host.mak config-host.h* config-host.ld $(DOCS) rm -f tests/tcg/config-*.mak rm -f config-all-devices.mak config-all-disas.mak config.status rm -f $(SUBDIR_DEVICES_MAK) @@ -1078,9 +1078,10 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \ # a single doctree: https://github.com/sphinx-doc/sphinx/issues/2946 build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" $(SPHINX_BUILD) $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1") # We assume all RST files in the manual's directory are used in it -manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) \ +manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst $(SRC_PATH)/docs/$1/*/*.rst) \ $(SRC_PATH)/docs/defs.rst.inc \ - $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py + $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py \ + $(SRC_PATH)/docs/sphinx/*.py # Macro to write out the rule and dependencies for building manpages # Usage: $(call define-manpage-rule,manualname,manpage1 manpage2...[,extradeps]) # 'extradeps' is optional, and specifies extra files (eg .hx files) that @@ -1122,15 +1123,6 @@ $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h $(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \ "GEN","$@") -qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool - $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@") - -qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx $(SRC_PATH)/scripts/hxtool - $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@") - -qemu-monitor-info.texi: $(SRC_PATH)/hmp-commands-info.hx $(SRC_PATH)/scripts/hxtool - $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@") - docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi @cp -p $< $@ diff --git a/docs/can.txt b/docs/can.txt index 9fa6ed51c8..11ed8f2d68 100644 --- a/docs/can.txt +++ b/docs/can.txt @@ -13,7 +13,7 @@ controller is implemented. The PCI addon card hardware has been selected as the first CAN interface to implement because such device can be easily connected -to systems with different CPU architectures (x86, PowerPC, ARM, etc.). +to systems with different CPU architectures (x86, PowerPC, Arm, etc.). The project has been initially started in frame of RTEMS GSoC 2013 slot by Jin Yang under our mentoring The initial idea was to provide generic diff --git a/docs/devel/atomics.txt b/docs/devel/atomics.txt index a4db3a4aaa..67bdf82628 100644 --- a/docs/devel/atomics.txt +++ b/docs/devel/atomics.txt @@ -87,7 +87,7 @@ Sequentially consistent loads and stores can be done using: atomic_xchg(ptr, val) for stores However, they are quite expensive on some platforms, notably POWER and -ARM. Therefore, qemu/atomic.h provides two primitives with slightly +Arm. Therefore, qemu/atomic.h provides two primitives with slightly weaker constraints: typeof(*ptr) atomic_mb_read(ptr) diff --git a/docs/devel/kconfig.rst b/docs/devel/kconfig.rst index b7bca44704..e5df72b342 100644 --- a/docs/devel/kconfig.rst +++ b/docs/devel/kconfig.rst @@ -8,7 +8,7 @@ time different targets can share large amounts of code. For example, a POWER and an x86 board can run the same code to emulate a PCI network card, even though the boards use different PCI host bridges, and they can run the same code to emulate a SCSI disk while using different -SCSI adapters. ARM, s390 and x86 boards can all present a virtio-blk +SCSI adapters. Arm, s390 and x86 boards can all present a virtio-blk disk to their guests, but with three different virtio guest interfaces. Each QEMU target enables a subset of the boards, devices and buses that diff --git a/docs/devel/loads-stores.rst b/docs/devel/loads-stores.rst index 03aa9e7ff8..0d99eb24c1 100644 --- a/docs/devel/loads-stores.rst +++ b/docs/devel/loads-stores.rst @@ -302,7 +302,7 @@ way QEMU defines the view of memory that a device or CPU has. or bus fabric.) Each CPU has an AddressSpace. Some kinds of CPU have more than -one AddressSpace (for instance ARM guest CPUs have an AddressSpace +one AddressSpace (for instance Arm guest CPUs have an AddressSpace for the Secure world and one for NonSecure if they implement TrustZone). Devices which can do DMA-type operations should generally have an AddressSpace. There is also a "system address space" which typically diff --git a/docs/devel/multi-thread-tcg.txt b/docs/devel/multi-thread-tcg.txt index 782bebc28b..3c85ac0eab 100644 --- a/docs/devel/multi-thread-tcg.txt +++ b/docs/devel/multi-thread-tcg.txt @@ -227,7 +227,7 @@ minimise contention. (Current solution) MMIO access automatically serialises hardware emulation by way of the -BQL. Currently ARM targets serialise all ARM_CP_IO register accesses +BQL. Currently Arm targets serialise all ARM_CP_IO register accesses and also defer the reset/startup of vCPUs to the vCPU context by way of async_run_on_cpu(). @@ -268,7 +268,7 @@ ordered backends this could become a NOP. Aside from explicit standalone memory barrier instructions there are also implicit memory ordering semantics which comes with each guest memory access instruction. For example all x86 load/stores come with -fairly strong guarantees of sequential consistency where as ARM has +fairly strong guarantees of sequential consistency whereas Arm has special variants of load/store instructions that imply acquire/release semantics. @@ -317,7 +317,7 @@ x86 cmpxchg instruction. The second type offer a pair of load/store instructions which offer a guarantee that a region of memory has not been touched between the -load and store instructions. An example of this is ARM's ldrex/strex +load and store instructions. An example of this is Arm's ldrex/strex pair where the strex instruction will return a flag indicating a successful store only if no other CPU has accessed the memory region since the ldrex. @@ -339,7 +339,7 @@ CURRENT OPEN QUESTIONS: The TCG provides a number of atomic helpers (tcg_gen_atomic_*) which can be used directly or combined to emulate other instructions like -ARM's ldrex/strex instructions. While they are susceptible to the ABA +Arm's ldrex/strex instructions. While they are susceptible to the ABA problem so far common guests have not implemented patterns where this may be a problem - typically presenting a locking ABI which assumes cmpxchg like semantics. diff --git a/docs/devel/tcg.rst b/docs/devel/tcg.rst index 4956a30a4e..4ebde44b9d 100644 --- a/docs/devel/tcg.rst +++ b/docs/devel/tcg.rst @@ -83,7 +83,7 @@ memory until the end of the translation block. This is done for internal emulation state that is rarely accessed directly by the program and/or changes very often throughout the execution of a translation block---this includes condition codes on x86, delay slots on SPARC, conditional execution on -ARM, and so on. This state is stored for each target instruction, and +Arm, and so on. This state is stored for each target instruction, and looked up on exceptions. MMU emulation diff --git a/docs/index.html.in b/docs/index.html.in index cc19aad2ec..e9a160384c 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -7,13 +7,13 @@ <body> <h1>QEMU @@VERSION@@ Documentation</h1> <ul> - <li><a href="qemu-qmp-ref.html">QMP Reference Manual</a></li> - <li><a href="qemu-ga-ref.html">Guest Agent Protocol Reference</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> <li><a href="system/index.html">System Emulation User's Guide</a></li> - <li><a href="tools/index.html">Tools 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> + <li><a href="qemu-qmp-ref.html">QMP Reference Manual</a></li> + <li><a href="qemu-ga-ref.html">Guest Agent Protocol Reference</a></li> </ul> </body> </html> diff --git a/docs/index.rst b/docs/index.rst index 376dab2885..763e3d0426 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,9 +10,9 @@ Welcome to QEMU's documentation! :maxdepth: 2 :caption: Contents: - interop/index - devel/index - specs/index system/index - tools/index user/index + tools/index + interop/index + specs/index + devel/index diff --git a/docs/qemu-option-trace.rst.inc b/docs/qemu-option-trace.rst.inc index 23cfcb4853..7e09773a9c 100644 --- a/docs/qemu-option-trace.rst.inc +++ b/docs/qemu-option-trace.rst.inc @@ -1,7 +1,3 @@ -.. - The contents of this file must be kept in sync with qemu-option-trace.texi - until all the users of the texi file have been converted to rst and - the texi file can be removed. Specify tracing options. diff --git a/docs/replay.txt b/docs/replay.txt index f4619a62a3..70c27edb36 100644 --- a/docs/replay.txt +++ b/docs/replay.txt @@ -19,7 +19,7 @@ Deterministic replay has the following features: the memory, state of the hardware devices, clocks, and screen of the VM. * Writes execution log into the file for later replaying for multiple times on different machines. - * Supports i386, x86_64, and ARM hardware platforms. + * Supports i386, x86_64, and Arm hardware platforms. * Performs deterministic replay of all operations with keyboard and mouse input devices. diff --git a/docs/specs/fw_cfg.txt b/docs/specs/fw_cfg.txt index 08c00bdf44..8f1ebc66fa 100644 --- a/docs/specs/fw_cfg.txt +++ b/docs/specs/fw_cfg.txt @@ -82,7 +82,7 @@ Selector Register IOport: 0x510 Data Register IOport: 0x511 DMA Address IOport: 0x514 -=== ARM Register Locations === +=== Arm Register Locations === Selector Register address: Base + 8 (2 bytes) Data Register address: Base + 0 (8 bytes) diff --git a/docs/specs/tpm.rst b/docs/specs/tpm.rst index da9eb39ca9..5e61238bc5 100644 --- a/docs/specs/tpm.rst +++ b/docs/specs/tpm.rst @@ -25,7 +25,7 @@ QEMU files related to TPM TIS interface: Both an ISA device and a sysbus device are available. The former is used with pc/q35 machine while the latter can be instantiated in the -ARM virt machine. +Arm virt machine. CRB interface ------------- @@ -331,7 +331,7 @@ In case a pSeries machine is emulated, use the following command line: -device virtio-blk-pci,scsi=off,bus=pci.0,addr=0x3,drive=drive-virtio-disk0,id=virtio-disk0 \ -drive file=test.img,format=raw,if=none,id=drive-virtio-disk0 -In case an ARM virt machine is emulated, use the following command line: +In case an Arm virt machine is emulated, use the following command line: .. code-block:: console @@ -346,7 +346,7 @@ In case an ARM virt machine is emulated, use the following command line: -drive if=pflash,format=raw,file=flash0.img,readonly \ -drive if=pflash,format=raw,file=flash1.img - On ARM, ACPI boot with TPM is not yet supported. + On Arm, ACPI boot with TPM is not yet supported. In case SeaBIOS is used as firmware, it should show the TPM menu item after entering the menu with 'ESC'. diff --git a/docs/sphinx/hxtool.py b/docs/sphinx/hxtool.py index 7dd223fe36..fb0649a3d5 100644 --- a/docs/sphinx/hxtool.py +++ b/docs/sphinx/hxtool.py @@ -37,13 +37,11 @@ else: __version__ = '1.0' -# We parse hx files with a state machine which may be in one of three -# states: reading the C code fragment, inside a texi fragment, -# or inside a rST fragment. +# We parse hx files with a state machine which may be in one of two +# states: reading the C code fragment, or inside a rST fragment. class HxState(Enum): CTEXT = 1 - TEXI = 2 - RST = 3 + RST = 2 def serror(file, lnum, errtext): """Raise an exception giving a user-friendly syntax error message""" @@ -110,31 +108,13 @@ class HxtoolDocDirective(Directive): if directive == 'HXCOMM': pass - elif directive == 'STEXI': - if state == HxState.RST: - serror(hxfile, lnum, 'expected ERST, found STEXI') - elif state == HxState.TEXI: - serror(hxfile, lnum, 'expected ETEXI, found STEXI') - else: - state = HxState.TEXI - elif directive == 'ETEXI': - if state == HxState.RST: - serror(hxfile, lnum, 'expected ERST, found ETEXI') - elif state == HxState.CTEXT: - serror(hxfile, lnum, 'expected STEXI, found ETEXI') - else: - state = HxState.CTEXT elif directive == 'SRST': if state == HxState.RST: serror(hxfile, lnum, 'expected ERST, found SRST') - elif state == HxState.TEXI: - serror(hxfile, lnum, 'expected ETEXI, found SRST') else: state = HxState.RST elif directive == 'ERST': - if state == HxState.TEXI: - serror(hxfile, lnum, 'expected ETEXI, found ERST') - elif state == HxState.CTEXT: + if state == HxState.CTEXT: serror(hxfile, lnum, 'expected SRST, found ERST') else: state = HxState.CTEXT diff --git a/docs/arm-cpu-features.rst b/docs/system/arm/cpu-features.rst index fc1623aeca..2d5c06cd01 100644 --- a/docs/arm-cpu-features.rst +++ b/docs/system/arm/cpu-features.rst @@ -1,19 +1,13 @@ +Arm CPU Features ================ -ARM CPU Features -================ - -Examples of probing and using ARM CPU features - -Introduction -============ CPU features are optional features that a CPU of supporting type may choose to implement or not. In QEMU, optional CPU features have corresponding boolean CPU proprieties that, when enabled, indicate that the feature is implemented, and, conversely, when disabled, -indicate that it is not implemented. An example of an ARM CPU feature +indicate that it is not implemented. An example of an Arm CPU feature is the Performance Monitoring Unit (PMU). CPU types such as the -Cortex-A15 and the Cortex-A57, which respectively implement ARM +Cortex-A15 and the Cortex-A57, which respectively implement Arm architecture reference manuals ARMv7-A and ARMv8-A, may both optionally implement PMUs. For example, if a user wants to use a Cortex-A15 without a PMU, then the `-cpu` parameter should contain `pmu=off` on the QEMU diff --git a/docs/system/arm/integratorcp.rst b/docs/system/arm/integratorcp.rst new file mode 100644 index 0000000000..e6f050f602 --- /dev/null +++ b/docs/system/arm/integratorcp.rst @@ -0,0 +1,16 @@ +Integrator/CP (``integratorcp``) +================================ + +The Arm Integrator/CP board is emulated with the following devices: + +- ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU + +- Two PL011 UARTs + +- SMC 91c111 Ethernet adapter + +- PL110 LCD controller + +- PL050 KMI with PS/2 keyboard and mouse. + +- PL181 MultiMedia Card Interface with SD card. diff --git a/docs/system/arm/musicpal.rst b/docs/system/arm/musicpal.rst new file mode 100644 index 0000000000..9de380edf8 --- /dev/null +++ b/docs/system/arm/musicpal.rst @@ -0,0 +1,19 @@ +Freecom MusicPal (``musicpal``) +=============================== + +The Freecom MusicPal internet radio emulation includes the following +elements: + +- Marvell MV88W8618 Arm core. + +- 32 MB RAM, 256 KB SRAM, 8 MB flash. + +- Up to 2 16550 UARTs + +- MV88W8xx8 Ethernet controller + +- MV88W8618 audio controller, WM8750 CODEC and mixer + +- 128x64 display with brightness control + +- 2 buttons, 2 navigation wheels with button function diff --git a/docs/system/arm/nseries.rst b/docs/system/arm/nseries.rst new file mode 100644 index 0000000000..cd9edf5d88 --- /dev/null +++ b/docs/system/arm/nseries.rst @@ -0,0 +1,33 @@ +Nokia N800 and N810 tablets (``n800``, ``n810``) +================================================ + +Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / +48) emulation supports the following elements: + +- Texas Instruments OMAP2420 System-on-chip (ARM1136 core) + +- RAM and non-volatile OneNAND Flash memories + +- Display connected to EPSON remote framebuffer chip and OMAP on-chip + display controller and a LS041y3 MIPI DBI-C controller + +- TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen + controllers driven through SPI bus + +- National Semiconductor LM8323-controlled qwerty keyboard driven + through |I2C| bus + +- Secure Digital card connected to OMAP MMC/SD host + +- Three OMAP on-chip UARTs and on-chip STI debugging console + +- Mentor Graphics \"Inventra\" dual-role USB controller embedded in a + TI TUSB6010 chip - only USB host mode is supported + +- TI TMP105 temperature sensor driven through |I2C| bus + +- TI TWL92230C power management companion with an RTC on + |I2C| bus + +- Nokia RETU and TAHVO multi-purpose chips with an RTC, connected + through CBUS diff --git a/docs/system/arm/palm.rst b/docs/system/arm/palm.rst new file mode 100644 index 0000000000..47ff9b36d4 --- /dev/null +++ b/docs/system/arm/palm.rst @@ -0,0 +1,23 @@ +Palm Tungsten|E PDA (``cheetah``) +================================= + +The Palm Tungsten|E PDA (codename \"Cheetah\") emulation includes the +following elements: + +- Texas Instruments OMAP310 System-on-chip (ARM925T core) + +- ROM and RAM memories (ROM firmware image can be loaded with + -option-rom) + +- On-chip LCD controller + +- On-chip Real Time Clock + +- TI TSC2102i touchscreen controller / analog-digital converter / + Audio CODEC, connected through MicroWire and |I2S| busses + +- GPIO-connected matrix keypad + +- Secure Digital card connected to OMAP MMC/SD host + +- Three on-chip UARTs diff --git a/docs/system/arm/realview.rst b/docs/system/arm/realview.rst new file mode 100644 index 0000000000..65f5be346b --- /dev/null +++ b/docs/system/arm/realview.rst @@ -0,0 +1,34 @@ +Arm Realview boards (``realview-eb``, ``realview-eb-mpcore``, ``realview-pb-a8``, ``realview-pbx-a9``) +====================================================================================================== + +Several variants of the Arm RealView baseboard are emulated, including +the EB, PB-A8 and PBX-A9. Due to interactions with the bootloader, only +certain Linux kernel configurations work out of the box on these boards. + +Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET +enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board +should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET +disabled and expect 1024M RAM. + +The following devices are emulated: + +- ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU + +- Arm AMBA Generic/Distributed Interrupt Controller + +- Four PL011 UARTs + +- SMC 91c111 or SMSC LAN9118 Ethernet adapter + +- PL110 LCD controller + +- PL050 KMI with PS/2 keyboard and mouse + +- PCI host bridge + +- PCI OHCI USB controller + +- LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM + devices + +- PL181 MultiMedia Card Interface with SD card. diff --git a/docs/system/arm/stellaris.rst b/docs/system/arm/stellaris.rst new file mode 100644 index 0000000000..8af4ad79c7 --- /dev/null +++ b/docs/system/arm/stellaris.rst @@ -0,0 +1,26 @@ +Stellaris boards (``lm3s6965evb``, ``lm3s811evb``) +================================================== + +The Luminary Micro Stellaris LM3S811EVB emulation includes the following +devices: + +- Cortex-M3 CPU core. + +- 64k Flash and 8k SRAM. + +- Timers, UARTs, ADC and |I2C| interface. + +- OSRAM Pictiva 96x16 OLED with SSD0303 controller on + |I2C| bus. + +The Luminary Micro Stellaris LM3S6965EVB emulation includes the +following devices: + +- Cortex-M3 CPU core. + +- 256k Flash and 64k SRAM. + +- Timers, UARTs, ADC, |I2C| and SSI interfaces. + +- OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via + SSI. diff --git a/docs/system/arm/sx1.rst b/docs/system/arm/sx1.rst new file mode 100644 index 0000000000..8bce30d4b2 --- /dev/null +++ b/docs/system/arm/sx1.rst @@ -0,0 +1,18 @@ +Siemens SX1 (``sx1``, ``sx1-v1``) +================================= + +The Siemens SX1 models v1 and v2 (default) basic emulation. The +emulation includes the following elements: + +- Texas Instruments OMAP310 System-on-chip (ARM925T core) + +- ROM and RAM memories (ROM firmware image can be loaded with + -pflash) V1 1 Flash of 16MB and 1 Flash of 8MB V2 1 Flash of 32MB + +- On-chip LCD controller + +- On-chip Real Time Clock + +- Secure Digital card connected to OMAP MMC/SD host + +- Three on-chip UARTs diff --git a/docs/system/arm/versatile.rst b/docs/system/arm/versatile.rst new file mode 100644 index 0000000000..51221c30a4 --- /dev/null +++ b/docs/system/arm/versatile.rst @@ -0,0 +1,29 @@ +Arm Versatile boards (``versatileab``, ``versatilepb``) +======================================================= + +The Arm Versatile baseboard is emulated with the following devices: + +- ARM926E, ARM1136 or Cortex-A8 CPU + +- PL190 Vectored Interrupt Controller + +- Four PL011 UARTs + +- SMC 91c111 Ethernet adapter + +- PL110 LCD controller + +- PL050 KMI with PS/2 keyboard and mouse. + +- PCI host bridge. Note the emulated PCI bridge only provides access + to PCI memory space. It does not provide access to PCI IO space. This + means some devices (eg. ne2k_pci NIC) are not usable, and others (eg. + rtl8139 NIC) are only usable when the guest drivers use the memory + mapped control registers. + +- PCI OHCI USB controller. + +- LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM + devices. + +- PL181 MultiMedia Card Interface with SD card. diff --git a/docs/system/arm/xscale.rst b/docs/system/arm/xscale.rst new file mode 100644 index 0000000000..89ec93e904 --- /dev/null +++ b/docs/system/arm/xscale.rst @@ -0,0 +1,29 @@ +Sharp XScale-based PDA models (``akita``, ``borzoi``, ``spitz``, ``terrier``) +============================================================================= + +The XScale-based clamshell PDA models (\"Spitz\", \"Akita\", \"Borzoi\" +and \"Terrier\") emulation includes the following peripherals: + +- Intel PXA270 System-on-chip (ARMv5TE core) + +- NAND Flash memory + +- IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in \"Akita\" + +- On-chip OHCI USB controller + +- On-chip LCD controller + +- On-chip Real Time Clock + +- TI ADS7846 touchscreen controller on SSP bus + +- Maxim MAX1111 analog-digital converter on |I2C| bus + +- GPIO-connected keyboard controller and LEDs + +- Secure Digital card connected to PXA MMC/SD host + +- Three on-chip UARTs + +- WM8750 audio CODEC on |I2C| and |I2S| busses diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst index d2a3b44ce8..1425bd5303 100644 --- a/docs/system/target-arm.rst +++ b/docs/system/target-arm.rst @@ -1,217 +1,86 @@ .. _ARM-System-emulator: -ARM System emulator +Arm System emulator ------------------- -Use the executable ``qemu-system-arm`` to simulate a ARM machine. The -ARM Integrator/CP board is emulated with the following devices: - -- ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU - -- Two PL011 UARTs - -- SMC 91c111 Ethernet adapter - -- PL110 LCD controller - -- PL050 KMI with PS/2 keyboard and mouse. - -- PL181 MultiMedia Card Interface with SD card. - -The ARM Versatile baseboard is emulated with the following devices: - -- ARM926E, ARM1136 or Cortex-A8 CPU - -- PL190 Vectored Interrupt Controller - -- Four PL011 UARTs - -- SMC 91c111 Ethernet adapter - -- PL110 LCD controller - -- PL050 KMI with PS/2 keyboard and mouse. - -- PCI host bridge. Note the emulated PCI bridge only provides access - to PCI memory space. It does not provide access to PCI IO space. This - means some devices (eg. ne2k_pci NIC) are not usable, and others (eg. - rtl8139 NIC) are only usable when the guest drivers use the memory - mapped control registers. - -- PCI OHCI USB controller. - -- LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM - devices. - -- PL181 MultiMedia Card Interface with SD card. - -Several variants of the ARM RealView baseboard are emulated, including -the EB, PB-A8 and PBX-A9. Due to interactions with the bootloader, only -certain Linux kernel configurations work out of the box on these boards. - -Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET -enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board -should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET -disabled and expect 1024M RAM. - -The following devices are emulated: - -- ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU - -- ARM AMBA Generic/Distributed Interrupt Controller - -- Four PL011 UARTs - -- SMC 91c111 or SMSC LAN9118 Ethernet adapter - -- PL110 LCD controller - -- PL050 KMI with PS/2 keyboard and mouse - -- PCI host bridge - -- PCI OHCI USB controller - -- LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM - devices - -- PL181 MultiMedia Card Interface with SD card. - -The XScale-based clamshell PDA models (\"Spitz\", \"Akita\", \"Borzoi\" -and \"Terrier\") emulation includes the following peripherals: - -- Intel PXA270 System-on-chip (ARM V5TE core) - -- NAND Flash memory - -- IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in \"Akita\" - -- On-chip OHCI USB controller - -- On-chip LCD controller - -- On-chip Real Time Clock - -- TI ADS7846 touchscreen controller on SSP bus - -- Maxim MAX1111 analog-digital converter on |I2C| bus - -- GPIO-connected keyboard controller and LEDs - -- Secure Digital card connected to PXA MMC/SD host - -- Three on-chip UARTs - -- WM8750 audio CODEC on |I2C| and |I2S| busses - -The Palm Tungsten|E PDA (codename \"Cheetah\") emulation includes the -following elements: - -- Texas Instruments OMAP310 System-on-chip (ARM 925T core) - -- ROM and RAM memories (ROM firmware image can be loaded with - -option-rom) - -- On-chip LCD controller - -- On-chip Real Time Clock - -- TI TSC2102i touchscreen controller / analog-digital converter / - Audio CODEC, connected through MicroWire and |I2S| busses - -- GPIO-connected matrix keypad - -- Secure Digital card connected to OMAP MMC/SD host - -- Three on-chip UARTs - -Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / -48) emulation supports the following elements: - -- Texas Instruments OMAP2420 System-on-chip (ARM 1136 core) - -- RAM and non-volatile OneNAND Flash memories - -- Display connected to EPSON remote framebuffer chip and OMAP on-chip - display controller and a LS041y3 MIPI DBI-C controller - -- TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen - controllers driven through SPI bus - -- National Semiconductor LM8323-controlled qwerty keyboard driven - through |I2C| bus - -- Secure Digital card connected to OMAP MMC/SD host - -- Three OMAP on-chip UARTs and on-chip STI debugging console - -- Mentor Graphics \"Inventra\" dual-role USB controller embedded in a - TI TUSB6010 chip - only USB host mode is supported - -- TI TMP105 temperature sensor driven through |I2C| bus - -- TI TWL92230C power management companion with an RTC on - |I2C| bus - -- Nokia RETU and TAHVO multi-purpose chips with an RTC, connected - through CBUS - -The Luminary Micro Stellaris LM3S811EVB emulation includes the following -devices: - -- Cortex-M3 CPU core. - -- 64k Flash and 8k SRAM. - -- Timers, UARTs, ADC and |I2C| interface. - -- OSRAM Pictiva 96x16 OLED with SSD0303 controller on - |I2C| bus. - -The Luminary Micro Stellaris LM3S6965EVB emulation includes the -following devices: - -- Cortex-M3 CPU core. - -- 256k Flash and 64k SRAM. - -- Timers, UARTs, ADC, |I2C| and SSI interfaces. - -- OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via - SSI. - -The Freecom MusicPal internet radio emulation includes the following -elements: - -- Marvell MV88W8618 ARM core. - -- 32 MB RAM, 256 KB SRAM, 8 MB flash. - -- Up to 2 16550 UARTs - -- MV88W8xx8 Ethernet controller - -- MV88W8618 audio controller, WM8750 CODEC and mixer - -- 128x64 display with brightness control - -- 2 buttons, 2 navigation wheels with button function - -The Siemens SX1 models v1 and v2 (default) basic emulation. The -emulation includes the following elements: - -- Texas Instruments OMAP310 System-on-chip (ARM 925T core) - -- ROM and RAM memories (ROM firmware image can be loaded with - -pflash) V1 1 Flash of 16MB and 1 Flash of 8MB V2 1 Flash of 32MB - -- On-chip LCD controller - -- On-chip Real Time Clock - -- Secure Digital card connected to OMAP MMC/SD host - -- Three on-chip UARTs - -A Linux 2.6 test image is available on the QEMU web site. More -information is available in the QEMU mailing-list archive. +QEMU can emulate both 32-bit and 64-bit Arm CPUs. Use the +``qemu-system-aarch64`` executable to simulate a 64-bit Arm machine. +You can use either ``qemu-system-arm`` or ``qemu-system-aarch64`` +to simulate a 32-bit Arm machine: in general, command lines that +work for ``qemu-system-arm`` will behave the same when used with +``qemu-system-aarch64``. + +QEMU has generally good support for Arm guests. It has support for +nearly fifty different machines. The reason we support so many is that +Arm hardware is much more widely varying than x86 hardware. Arm CPUs +are generally built into "system-on-chip" (SoC) designs created by +many different companies with different devices, and these SoCs are +then built into machines which can vary still further even if they use +the same SoC. Even with fifty boards QEMU does not cover more than a +small fraction of the Arm hardware ecosystem. + +The situation for 64-bit Arm is fairly similar, except that we don't +implement so many different machines. + +As well as the more common "A-profile" CPUs (which have MMUs and will +run Linux) QEMU also supports "M-profile" CPUs such as the Cortex-M0, +Cortex-M4 and Cortex-M33 (which are microcontrollers used in very +embedded boards). For most boards the CPU type is fixed (matching what +the hardware has), so typically you don't need to specify the CPU type +by hand, except for special cases like the ``virt`` board. + +Choosing a board model +====================== + +For QEMU's Arm system emulation, you must specify which board +model you want to use with the ``-M`` or ``--machine`` option; +there is no default. + +Because Arm systems differ so much and in fundamental ways, typically +operating system or firmware images intended to run on one machine +will not run at all on any other. This is often surprising for new +users who are used to the x86 world where every system looks like a +standard PC. (Once the kernel has booted, most userspace software +cares much less about the detail of the hardware.) + +If you already have a system image or a kernel that works on hardware +and you want to boot with QEMU, check whether QEMU lists that machine +in its ``-machine help`` output. If it is listed, then you can probably +use that board model. If it is not listed, then unfortunately your image +will almost certainly not boot on QEMU. (You might be able to +extract the filesystem and use that with a different kernel which +boots on a system that QEMU does emulate.) + +If you don't care about reproducing the idiosyncrasies of a particular +bit of hardware, such as small amount of RAM, no PCI or other hard +disk, etc., and just want to run Linux, the best option is to use the +``virt`` board. This is a platform which doesn't correspond to any +real hardware and is designed for use in virtual machines. You'll +need to compile Linux with a suitable configuration for running on +the ``virt`` board. ``virt`` supports PCI, virtio, recent CPUs and +large amounts of RAM. It also supports 64-bit CPUs. + +Board-specific documentation +============================ + +Unfortunately many of the Arm boards QEMU supports are currently +undocumented; you can get a complete list by running +``qemu-system-aarch64 --machine help``. + +.. toctree:: + + arm/integratorcp + arm/versatile + arm/realview + arm/xscale + arm/palm + arm/nseries + arm/stellaris + arm/musicpal + arm/sx1 + +Arm CPU features +================ + +.. toctree:: + arm/cpu-features diff --git a/docs/user/main.rst b/docs/user/main.rst index ca69f7727d..bd99b0fdbe 100644 --- a/docs/user/main.rst +++ b/docs/user/main.rst @@ -35,7 +35,7 @@ QEMU user space emulation has the following notable features: On Linux, QEMU can emulate the ``clone`` syscall and create a real host thread (with a separate virtual CPU) for each emulated thread. Note that not all targets currently emulate atomic operations - correctly. x86 and ARM use a global lock in order to preserve their + correctly. x86 and Arm use a global lock in order to preserve their semantics. QEMU was conceived so that ultimately it can emulate itself. Although it @@ -173,11 +173,11 @@ Other binaries user mode (Alpha) ``qemu-alpha`` TODO. -user mode (ARM) +user mode (Arm) ``qemu-armeb`` TODO. -user mode (ARM) -``qemu-arm`` is also capable of running ARM \"Angel\" semihosted ELF +user mode (Arm) +``qemu-arm`` is also capable of running Arm \"Angel\" semihosted ELF binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB configurations), and arm-uclinux bFLT format binaries. diff --git a/hmp-commands-info.hx b/hmp-commands-info.hx index 499d6d54b0..ca5198438d 100644 --- a/hmp-commands-info.hx +++ b/hmp-commands-info.hx @@ -1,9 +1,9 @@ -HXCOMM Use DEFHEADING() to define headings in both help text and texi -HXCOMM Text between STEXI and ETEXI are copied to texi version and -HXCOMM discarded from C version +HXCOMM Use DEFHEADING() to define headings in both help text and rST. +HXCOMM Text between SRST and ERST is copied to the rST version and +HXCOMM discarded from C version. HXCOMM DEF(command, args, callback, arg_string, help) is used to construct HXCOMM monitor info commands -HXCOMM HXCOMM can be used for comments, discarded from both texi and C +HXCOMM HXCOMM can be used for comments, discarded from both rST and C. HXCOMM HXCOMM In this file, generally SRST fragments should have two extra HXCOMM spaces of indent, so that the documentation list item for "info foo" diff --git a/hmp-commands.hx b/hmp-commands.hx index f12263e071..7f0f3974ad 100644 --- a/hmp-commands.hx +++ b/hmp-commands.hx @@ -1,9 +1,9 @@ -HXCOMM Use DEFHEADING() to define headings in both help text and texi -HXCOMM Text between STEXI and ETEXI are copied to texi version and -HXCOMM discarded from C version +HXCOMM Use DEFHEADING() to define headings in both help text and rST. +HXCOMM Text between SRST and ERST is copied to the rST version and +HXCOMM discarded from C version. HXCOMM DEF(command, args, callback, arg_string, help) is used to construct HXCOMM monitor commands -HXCOMM HXCOMM can be used for comments, discarded from both texi and C +HXCOMM HXCOMM can be used for comments, discarded from both rST and C. { diff --git a/qemu-options.hx b/qemu-options.hx index f9fefd43be..1d8f852d89 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -1,10 +1,10 @@ -HXCOMM Use DEFHEADING() to define headings in both help text and texi -HXCOMM Text between STEXI and ETEXI are copied to texi version and -HXCOMM discarded from C version +HXCOMM Use DEFHEADING() to define headings in both help text and rST. +HXCOMM Text between SRST and ERST is copied to the rST version and +HXCOMM discarded from C version. HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to HXCOMM construct option structures, enums and help message for specified HXCOMM architectures. -HXCOMM HXCOMM can be used for comments, discarded from both texi and C +HXCOMM HXCOMM can be used for comments, discarded from both rST and C. DEFHEADING(Standard options:) diff --git a/scripts/hxtool b/scripts/hxtool index 0003e7b673..7b1452f3cf 100644 --- a/scripts/hxtool +++ b/scripts/hxtool @@ -7,7 +7,7 @@ hxtoh() case $str in HXCOMM*) ;; - STEXI*|ETEXI*|SRST*|ERST*) flag=$(($flag^1)) + SRST*|ERST*) flag=$(($flag^1)) ;; *) test $flag -eq 1 && printf "%s\n" "$str" @@ -16,84 +16,8 @@ hxtoh() done } -print_texi_heading() -{ - if test "$*" != ""; then - title="$*" - printf "@subsection %s\n" "${title%:}" - fi -} - -hxtotexi() -{ - flag=0 - rstflag=0 - line=1 - while read -r str; do - case "$str" in - HXCOMM*) - ;; - STEXI*) - if test $rstflag -eq 1 ; then - printf "line %d: syntax error: expected ERST, found '%s'\n" "$line" "$str" >&2 - exit 1 - fi - if test $flag -eq 1 ; then - printf "line %d: syntax error: expected ETEXI, found '%s'\n" "$line" "$str" >&2 - exit 1 - fi - flag=1 - ;; - ETEXI*) - if test $rstflag -eq 1 ; then - printf "line %d: syntax error: expected ERST, found '%s'\n" "$line" "$str" >&2 - exit 1 - fi - if test $flag -ne 1 ; then - printf "line %d: syntax error: expected STEXI, found '%s'\n" "$line" "$str" >&2 - exit 1 - fi - flag=0 - ;; - SRST*) - if test $rstflag -eq 1 ; then - printf "line %d: syntax error: expected ERST, found '%s'\n" "$line" "$str" >&2 - exit 1 - fi - if test $flag -eq 1 ; then - printf "line %d: syntax error: expected ETEXI, found '%s'\n" "$line" "$str" >&2 - exit 1 - fi - rstflag=1 - ;; - ERST*) - if test $flag -eq 1 ; then - printf "line %d: syntax error: expected ETEXI, found '%s'\n" "$line" "$str" >&2 - exit 1 - fi - if test $rstflag -ne 1 ; then - printf "line %d: syntax error: expected SRST, found '%s'\n" "$line" "$str" >&2 - exit 1 - fi - rstflag=0 - ;; - DEFHEADING*) - print_texi_heading "$(expr "$str" : "DEFHEADING(\(.*\))")" - ;; - ARCHHEADING*) - print_texi_heading "$(expr "$str" : "ARCHHEADING(\(.*\),.*)")" - ;; - *) - test $flag -eq 1 && printf '%s\n' "$str" - ;; - esac - line=$((line+1)) - done -} - case "$1" in "-h") hxtoh ;; -"-t") hxtotexi ;; *) exit 1 ;; esac |