[PATCH v3 2/2] Add AArch64 documentation

[Gedare Bloom]

On Mon, Oct 5, 2020 at 9:13 AM Gedare Bloom <gedare at rtems.org> wrote:
>
> On Sat, Oct 3, 2020 at 10:23 PM Kinsey Moore <kinsey.moore at oarcorp.com> wrote:
> >
> > ---
> >  cpu-supplement/aarch64.rst | 134 +++++++++++++++++++++++++++++++++++++
> >  user/bsps/aarch64/a53.rst  |  26 +++++++
> >  user/bsps/bsps-aarch64.rst |   2 +-
> >  3 files changed, 161 insertions(+), 1 deletion(-)
> >  create mode 100644 cpu-supplement/aarch64.rst
> >  create mode 100644 user/bsps/aarch64/a53.rst
> >
> > diff --git a/cpu-supplement/aarch64.rst b/cpu-supplement/aarch64.rst
> > new file mode 100644
> > index 0000000..178ea10
> > --- /dev/null
> > +++ b/cpu-supplement/aarch64.rst
> > @@ -0,0 +1,134 @@
> > +.. SPDX-License-Identifier: CC-BY-SA-4.0
> > +
> > +.. Copyright (C) 1988, 2020 On-Line Applications Research Corporation (OAR)
> > +
> > +AArch64 Specific Information
> > +************************
> > +
> > +This chapter discusses the dependencies of the
> > +*ARM AArch64 architecture*
> > +(https://en.wikipedia.org/wiki/ARM_architecture#AArch64_features) in this port
> > +of RTEMS.  The ARMv8-A versions are supported by RTEMS.  Processors with a MMU
> > +use a static configuration which is set up during system start.  SMP is not
> > +supported.
> > +
> > +**Architecture Documents**
> > +
> > +For information on the ARM AArch64 architecture refer to the *ARM Infocenter*
> > +(http://infocenter.arm.com/).
> > +
> > +CPU Model Dependent Features
> > +============================
> > +
> > +This section presents the set of features which vary across ARM AArch64
> > +implementations and are of importance to RTEMS.  The set of CPU model feature
> > +macros are defined in the file :file:`cpukit/score/cpu/aarch64/rtems/score/aarch64.h`
> > +based upon the particular CPU model flags specified on the compilation command
> > +line.
> > +
> > +CPU Model Name
> > +--------------
> > +
> > +The macro ``CPU_MODEL_NAME`` is a string which designates the architectural
> > +level of this CPU model.  See in :file:`cpukit/score/cpu/aarch64/rtems/score/aarch64.h`
> > +for the values.
> > +
> > +Floating Point Unit and SIMD
> > +----------------------------
> > +
> > +The Advanced SIMD (NEON) and Floating-point instruction set extension is
> > +supported and expected to be present since all ARMv8-A CPUs are expected to
> > +support it as per the *ARMv8-A Programmer's Guide Chapter 7 introduction*
> > +(https://developer.arm.com/docs/den0024/a/aarch64-floating-point-and-neon). As
> > +such, ``CPU_HARDWARE_FP`` will always be set to ``TRUE``.
> > +
> > +Multilibs
> > +=========
> > +
> > +The following multilib variants are available:
> > +
> > +#. ``ILP32``: AArch64 instruction set and registers using 32bit long int and pointers
> > +
> > +#. ``LP64``: AArch64 instruction set and registers using 64bit long int and pointers
> > +
> > +Use for example the following GCC options:
> > +
> > +.. code-block:: shell
> > +
> > +    -mcpu=cortex-a53 -mabi=ilp32
> > +
> > +to build an application or BSP for the ARMv8-A architecture and tune the code
> > +for a Cortex-A53 processor.  It is important to select the correct ABI.
> > +
> > +Calling Conventions
> > +===================
> > +
> > +Please refer to the *Procedure Call Standard for the ARM 64-bit Architecture*
> > +(https://github.com/ARM-software/abi-aa/releases/download/2019Q4/aapcs64.pdf).
> > +
> > +Memory Model
> > +============
> > +
> > +A flat 64-bit or 32-bit memory model is supported depending on the selected multilib
> > +variant.  All AArch64 CPU variants support a built-in MMU for which basic initialization
> > +for a flat memory model is handled.
> > +
> > +Interrupt Processing
> > +====================
> > +
> > +The Reset Vector is determined using RVBAR and is Read-Only. RVBAR is set using
> > +configuration signals only sampled at reset.  The ARMv8 architecture has four
> > +exception types:
> > +
> > +- Synchronous Exception
> > +
> > +- Interrupt (IRQ)
> > +
> > +- Fast Interrupt (FIQ)
> > +
> > +- System Error Exception
> > +
> > +Of these types only the synchronous and IRQ exceptions have explicit operating
> > +system support.  It is intentional that the FIQ is not supported by the operating
> > +system.  Without operating system support for the FIQ it is not necessary to
> > +disable them during critical sections of the system.
> > +
> > +Interrupt Levels
> > +----------------
> > +
> > +There are exactly two interrupt levels on ARMv8 with respect to RTEMS.  Level
> > +zero corresponds to interrupts enabled.  Level one corresponds to interrupts
> > +disabled.
> > +
> > +Interrupt Stack
> > +---------------
> > +
> > +The board support package must initialize the interrupt stack. The memory for
> > +the stacks is usually reserved in the linker script.
> > +
> > +Default Fatal Error Processing
> > +==============================
> > +
> > +The default fatal error handler for this architecture performs the following
> > +actions:
> > +
> > +- disables operating system supported interrupts (IRQ),
> > +
> > +- places the error code in ``x0``, and
> > +
> > +- executes an infinite loop to simulate a halt processor instruction.
> > +
> > +Symmetric Multiprocessing
> > +=========================
> > +
> > +SMP is not currently supported on ARMv8-A.
> > +
> > +Thread-Local Storage
> > +====================
> > +
> > +Thread-local storage (TLS) is supported. AArch64 uses unmodified TLS variant I
> > +which is not explcitly stated, but can be inferred from the behavior of GCC and
> > +*Addenda to, and Errata in, the ABI for the Arm® Architecture*
> > +(https://developer.arm.com/documentation/ihi0045/g). This alters expectations
> > +for the size of the TLS Thread Control Block (TCB) such that, under the LP64
> > +multilib variant, the the TCB is 16 bytes in size instead of 8 bytes.
> s/the the/the
>
I missed that you sent v4, but this is still in it too.

> > diff --git a/user/bsps/aarch64/a53.rst b/user/bsps/aarch64/a53.rst
> > new file mode 100644
> > index 0000000..0052773
> > --- /dev/null
> > +++ b/user/bsps/aarch64/a53.rst
> > @@ -0,0 +1,26 @@
> > +.. SPDX-License-Identifier: CC-BY-SA-4.0
> > +
> > +.. Copyright (C) 2020 Kinsey Moore, On-Line Applications Research Corporation (OAR)
> > +
> > +.. _BSP_aarch64_qemu_a53_ilp32:
> > +.. _BSP_aarch64_qemu_a53_lp64:
> > +
> > +Qemu A53
> > +========
> > +
> > +This BSP supports two variants, `qemu_a53_ilp32` and `qemu-a53_lp64`. The basic
> > +hardware initialization is performed by the BSP.
> > +
> > +Boot via ELF
> > +------------
> > +The executable image is booted by Qemu in ELF format.
> > +
> > +Clock Driver
> > +------------
> > +
> > +The clock driver uses the `ARM Generic Timer`.
> > +
> > +Console Driver
> > +--------------
> > +
> > +The console driver supports the default Qemu emulated ARM PL011 PrimeCell UART.
> > diff --git a/user/bsps/bsps-aarch64.rst b/user/bsps/bsps-aarch64.rst
> > index 4b2e749..319310e 100644
> > --- a/user/bsps/bsps-aarch64.rst
> > +++ b/user/bsps/bsps-aarch64.rst
> > @@ -5,4 +5,4 @@
> >  aarch64 (AArch64)
> >  *****************
> >
> > -There are no AArch64 BSPs yet.
> > +.. include:: aarch64/a53.rst
> > --
> > 2.20.1
> >
> > _______________________________________________
> > devel mailing list
> > devel at rtems.org
> > http://lists.rtems.org/mailman/listinfo/devel