Merge "doc: Final, pre-release fixes and updates" into integration

doc: Final, pre-release fixes and updates

A small set of misc changes to ensure correctness before the v2.2
release tagging.

Change-Id: I888840b9483ea1a1633d204fbbc0f9594072101e
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Merge "doc: Expand contact information in About section" into integration

doc: Expand contact information in About section

Giving a bit more background information about the issue tracker
and mailing lists.

Change-Id: I68921d54e3113d348f1e16c685f74d32df2ca19f
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Merge "doc: Move platform list to the Platform Ports index page" into integration

Merge "doc: Move "About" content from index.rst to a new chapter" into integration

doc: Move platform list to the Platform Ports index page

The list of upstream platforms on the index page is growing
quite long, especially with all the FVP variants being listed
individually.

This patch leverages the "Platform Ports" chapter in the docs
table of contents to condense this information. Almost all
platform ports now have documentation, so the table of
contents serves as the list of upstream platforms by itself.

For those upstream platforms that do not have corresponding
documentation, the top-level "Platform Ports" page mentions
them individually. It also mentions each Arm FVP, just as
the index page did before.

Note that there is an in-progress patch that creates new
platform port documentation for the Arm Juno and Arm FVP
platforms, so this list of "other platforms" will soon be
reduced further as those platforms become part of the
table of contents as well.

Change-Id: I6b1eab8cba71a599d85a6e22553a34b07f213268
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

doc: Move "About" content from index.rst to a new chapter

The index.rst page is now the primary landing page for the TF-A
documentation. It contains quite a lot of content these days,
including:

- The project purpose and general intro
- A list of functionality
- A list of planned functionality
- A list of supported platforms
- "Getting started" links to other documents
- Contact information for raising issues

This patch creates an "About" chapter in the table
of contents and moves some content there. In order,
the above listed content:

- Stayed where it is. This is the right place for it.
- Moved to About->Features
- Moved to About->Features (in subsection)
- Stayed where it is. Moved in a later patch.
- Was expanded in-place
- Moved to About->Contact

Change-Id: I254bb87560fd09140b9e485cf15246892aa45943
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Merge "xlat_table_v2: Fix enable WARMBOOT_ENABLE_DCACHE_EARLY config" into integration

Merge "Replace deprecated __ASSEMBLY__ macro with __ASSEMBLER__" into integration

xlat_table_v2: Fix enable WARMBOOT_ENABLE_DCACHE_EARLY config

The WARMBOOT_ENABLE_DCACHE_EARLY allows caches to be turned on early during
the boot. But the xlat_change_mem_attributes_ctx() API did not do the required
cache maintenance after the mmap tables are modified if
WARMBOOT_ENABLE_DCACHE_EARLY is enabled. This meant that when the caches are turned
off during power down, the tables in memory are accessed as part of cache
maintenance for power down, and the tables are not correct at this point which
results in a data abort.
This patch removes the optimization within xlat_change_mem_attributes_ctx()
when WARMBOOT_ENABLE_DCACHE_EARLY is enabled.

Signed-off-by: Artsem Artsemenka <artsem.artsemenka@arm.com>
Change-Id: I82de3decba87dd13e9856b5f3620a1c8571c8d87

Merge "Fix documentation" into integration

Merge "doc: Remove version and release variables from conf.py" into integration

doc: Remove version and release variables from conf.py

We would need to update this version for the release but, in fact,
it is not required for our publishing workflow; the hosted version
of the docs uses git commit/tag information in place of these
variables anyway.

Instead of updating the version, just remove these variables
entirely.

Change-Id: I424c4e45786e87604e91c7197b7983579afe4806
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Fix documentation

User guide:
1. Remove obsolete note saying only FVP is supported with AArch32
2. Switch compiler for Juno AArch32 to arm-eabi
3. Mention SOFTWARE folder in Juno Linaro release

Index.rst:
1. Switch default FVP model to Version 11.6 Build 45

Signed-off-by: Artsem Artsemenka <artsem.artsemenka@arm.com>
Change-Id: Ib47a2ea314e2b8394a20189bf91796de0e17de53

Merge "Correct UART PL011 initialization calculation" into integration

Merge "doc: Update Linaro release mentioned on index page" into integration

doc: Update Linaro release mentioned on index page

The version of the Linaro release that is used for testing was
updated in 35010bb8 and the user guide was updated with the
correct version, however the version is also mentioned on the
index page and that was missed. Update the index page with the
new version.

We can come back and de-duplicate this content later, to ease
future maintenance.

Change-Id: I3fe83d7a1c59ab8d3ce2b18bcc23e16c93f7af97
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Merge "doc: Misc syntax and spelling fixes" into integration

doc: Misc syntax and spelling fixes

Tidying up a few Sphinx warnings that had built-up over time.
None of these are critical but it cleans up the Sphinx output.

At the same time, fixing some spelling errors that were detected.

Change-Id: I38209e235481eed287f8008c6de9dedd6b12ab2e
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Replace deprecated __ASSEMBLY__ macro with __ASSEMBLER__

Change-Id: I497072575231730a216220f84a6d349a48eaf5e3
Signed-off-by: Balint Dobszay <balint.dobszay@arm.com>

Merge "doc: Formatting fixes for readme.rst" into integration

doc: Formatting fixes for readme.rst

The readme.rst file in the project root is the front-page that
is displayed on Github and if viewing the TF-A repository on
git.trustedfirmware.org in the "about" view. It now contains a
small amount of stub content, and directs readers to the
ReadTheDocs documentation via trustedfirmware.org/docs/tf-a.

The Github renderer is displaying the content fine but the cgit
viewer displays some "backlink" errors because some content
substitutions were left in place (terms surrounded by pipe
symbols), e.g. |TF-A|.

This patch removes those substitutions, that are not supported
by cgit, and also updates one heading to clarify where to find
the new docs.

Change-Id: I358451df45b8c99975ba0b6db8ea61253a10560d
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Merge changes from topic "pb/readthedocs" into integration

* changes:
  doc: Add guide for building the docs locally
  doc: De-duplicate readme and license files
  doc: Convert internal links to RST format

doc: Add guide for building the docs locally

This new page contains instructions for doing a local
build of the documentation, plus information on the environment
setup that needs to be done beforehand.

Change-Id: If563145ab40639cabbe25d0f62759981a33692c6
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

doc: De-duplicate readme and license files

The readme.rst and license.rst files in the project root overlap
with the index.rst and license.rst files in the docs/ folder. We
need to use the latter when building the documentation, as Sphinx
requires all included files to be under a common root. However,
the files in the root are currently used by the cgit and Github
viewers.

Using symlinks in Git presents some difficulties so the best
course of action is likely to leave these files but in stub form.

The license.rst file in the root will simply tell the reader to
refer to docs/license.rst.

The readme.rst file will contain a small amount of content that
is derived from the docs/index.rst file, so that the Github main
page will have something valid to show, but it will also contain
a link to the full documentation on ReadTheDocs.

Change-Id: I6dc46f08777e8d7ecb32ca7afc07a28486c9f77a
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

doc: Convert internal links to RST format

Currently links between documents are using the format:

<path/to/><filename>.rst

This was required for services like GitHub because they render each
document in isolation - linking to another document is like linking
to any other file, just provide the full path.

However, with the new approach, the .rst files are only the raw
source for the documents. Once the documents have been rendered
the output is now in another format (HTML in our case) and so,
when linking to another document, the link must point to the
rendered version and not the .rst file.

The RST spec provides a few methods for linking between content.
The parent of this patch enabled the automatic creation of anchors
for document titles - we will use these anchors as the targets for
our links. Additional anchors can be added by hand if needed, on
section and sub-section titles, for example.

An example of this new format, for a document with the title
"Firmware Design" is :ref:`Firmware Design`.

One big advantage of this is that anchors are not dependent on
paths. We can then move documents around, even between directories,
without breaking any links between documents. Links will need to be
updated only if the title of a document changes.

Change-Id: I9e2340a61dd424cbd8fd1ecc2dc166f460d81703
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Merge "doc: Add more missing platforms" into integration

Merge "delay: correct timeout_init_us()" into integration

Correct UART PL011 initialization calculation

Currently for Armv7 plaforms the quotient calculated in pl011
uart init code is moved to register r1.

This patch moves the quotient to register r2 as done for other
platforms in the udiv instruction. Value of register r2 is then
used to calculate the values for IBRD and FBRD register

Change-Id: Ie6622f9f0e6d634378b471df5d02823b492c8a24
Signed-off-by: Avinash Mehta <avinash.mehta@arm.com>

delay: correct timeout_init_us()

The function has to use read_cntpct_el0() to update the counter, and not
read_cntfrq_el0().

Change-Id: I9c676466e784c3122e9ffc2d87e66708797086e7
Signed-off-by: Yann Gautier <yann.gautier@st.com>

doc: Add more missing platforms

Add meson-g12a, qemu-sbsa and rpi4 to the documentation index so
that they will have their docs rendered and integrated into the
table of contents.

Change-Id: Id972bf2fee67312dd7bff29f92bea67842e62431
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Merge "Explicitly disable the SPME bit in MDCR_EL3" into integration

Merge "Neoverse N1 Errata Workaround 1542419" into integration

Merge "Fix the CAS spinlock implementation" into integration

Explicitly disable the SPME bit in MDCR_EL3

Currently the MDCR_EL3 initialisation implicitly disables
MDCR_EL3.SPME by using mov_imm.

This patch makes the SPME bit more visible by explicitly
disabling it and documenting its use in different versions
of the architecture.

Signed-off-by: Petre-Ionut Tudor <petre-ionut.tudor@arm.com>
Change-Id: I221fdf314f01622f46ac5aa43388f59fa17a29b3

Neoverse N1 Errata Workaround 1542419

Coherent I-cache is causing a prefetch violation where when the core
executes an instruction that has recently been modified, the core might
fetch a stale instruction which violates the ordering of instruction
fetches.

The workaround includes an instruction sequence to implementation
defined registers to trap all EL0 IC IVAU instructions to EL3 and a trap
handler to execute a TLB inner-shareable invalidation to an arbitrary
address followed by a DSB.

Signed-off-by: Lauren Wehrmeister <lauren.wehrmeister@arm.com>
Change-Id: Ic3b7cbb11cf2eaf9005523ef5578a372593ae4d6

Merge "delay: timeout detection support" into integration

Fix the CAS spinlock implementation

Make the spinlock implementation use ARMv8.1-LSE CAS instruction based
on a platform build option. The CAS-based implementation used to be
unconditionally selected for all ARM8.1+ platforms.

The previous CAS spinlock implementation had a bug wherein the spin_unlock()
implementation had an `sev` after `stlr` which is not sufficient. A dsb is
needed to ensure that the stlr completes prior to the sev. Having a dsb is
heavyweight and a better solution would be to use load exclusive semantics
to monitor the lock and wake up from wfe when a store happens to the lock.
The patch implements the same.

Change-Id: I5283ce4a889376e4cc01d1b9d09afa8229a2e522
Signed-off-by: Soby Mathew <soby.mathew@arm.com>
Signed-off-by: Olivier Deprez <olivier.deprez@arm.com>

delay: timeout detection support

Introduce timeout_init_us/timeout_elapsed() delay tracking with CNTPCT.

timeout_init_us(some_timeout_us); returns a reference to detect
timeout for the provided microsecond delay value from current time.

timeout_elapsed(reference) return true/false whether the reference
timeout is elapsed.

Cherry picked from OP-TEE implementation [1].
  [1] commit 33d30a74502b ("core: timeout detection support")

Minor:
- Remove stm32mp platform duplicated implementation.
- Add new include in marvell ble.mk

Signed-off-by: Etienne Carriere <etienne.carriere@linaro.org>
Signed-off-by: Lionel Debieve <lionel.debieve@st.com>
Change-Id: Iaef6d43c11a2e6992fb48efdc674a0552755ad9c

Merge "TF-A: Add support for ARMv8.3-PAuth in BL1 SMC calls and BL2U" into integration

TF-A: Add support for ARMv8.3-PAuth in BL1 SMC calls and BL2U

This patch adds support for ARMv8.3-PAuth in BL1 SMC calls and
BL2U image for firmware updates by programming APIAKey_EL1 registers
and enabling Pointer Authentication in EL3 and EL1 respectively.

Change-Id: I875d952aba8242caf74fb5f4f2d2af6f0c768c08
Signed-off-by: Alexei Fedorov <Alexei.Fedorov@arm.com>

Merge "Introducing support for Cortex-A65AE" into integration

Introducing support for Cortex-A65AE

Change-Id: I1ea2bf088f1e001cdbd377cbfb7c6a2866af0422
Signed-off-by: Imre Kis <imre.kis@arm.com>

Merge changes from topic "stm32mp_corrections_w40" into integration

* changes:
  gpio: stm32_gpio: do not mix error code types
  fdts: stm32mp1: move FDCAN to PLL4_R
  mmc: increase delay between ACMD41 retries
  crypto: stm32_hash: align stm32_hash_update() prototype

Merge "Add missing support for BL2_AT_EL3 in XIP memory" into integration

Merge changes from topic "qemu_sbsa" into integration

* changes:
  qemu/qemu_sbsa: Adding memory mapping for both FLASH0/FLASH1
  qemu/qemu_sbsa: Adding Qemu SBSA platform

Merge changes I0355e084,I6a6dd1c0 into integration

* changes:
  mediatek: mt8183: add EMI MPU driver for DRAM protection
  mediatek: mt8183: add DEVAPC driver to control protection

Merge "a5ds: Add handler for when user tries to switch off secondary cores" into integration

gpio: stm32_gpio: do not mix error code types

Change-Id: I84f8a99be2dcdf7c51fbecdb324df8e2f32cc855
Signed-off-by: Nicolas Le Bayon <nicolas.le.bayon@st.com>
Signed-off-by: Yann Gautier <yann.gautier@st.com>

fdts: stm32mp1: move FDCAN to PLL4_R

LTDC modifies the clock frequency to adapt it to the display. Such
frequency change is not detected by the FDCAN driver that instead
caches the value at probe and pretends to use it later.

This change fixes the issue by moving the FDCAN to PLL4_R,
leaving the LTDC alone on PLL4_Q.

Signed-off-by: Antonio Borneo <antonio.borneo@st.com>
Signed-off-by: Yann Gautier <yann.gautier@st.com>
Change-Id: I8230868b2b5fd6deb6e3f9dc3911030d8d484c58

mmc: increase delay between ACMD41 retries

In the SD Specification, Power Up Diagram of Card figure, the Timeout
value for initialization process (ACMD41 command retries) is 1 second.
Align to match MMC cards (in mmc_send_op_cond()) and Linux kernel code,
and set the delay between ACMD41 command retries to 10ms.

Change-Id: I2e07cb9944e7d7b72f2d4b13e0505e6751458091
Signed-off-by: Yann Gautier <yann.gautier@st.com>

crypto: stm32_hash: align stm32_hash_update() prototype

Use size_t for length parameter in header file, as in .c file.

Change-Id: I310f2a6159cde1c069b4f814f6558c2488c203ec
Signed-off-by: Yann Gautier <yann.gautier@st.com>

a5ds: Add handler for when user tries to switch off secondary cores

a5ds only has always-on power domain and there is no power control
present. However, without the pwr_domain_off handler, the kernel
panics when the user will try to switch off secondary cores. The
a5ds_pwr_domain_off handler will prevent kernel from crashing,
i.e. the kernel will attempt but fail to shut down the secondary CPUs
if the user tries to switch them offline.

Change-Id: I3c2239a1b6f035113ddbdda063c8495000cbe30c
Signed-off-by: Usama Arif <usama.arif@arm.com>

mediatek: mt8183: add EMI MPU driver for DRAM protection

Add EMI MPU driver for DRAM protection.

Signed-off-by: kenny liang <kenny.liang@mediatek.com>
Change-Id: I0355e084184b5396ad8ac99fff6ef9d050fb5e96

mediatek: mt8183: add DEVAPC driver to control protection

Add DEVAPC driver to control protection.

Signed-off-by: kenny liang <kenny.liang@mediatek.com>
Change-Id: I6a6dd1c0bffa372b6df2cb604ca5e02eabbb9d26

Merge "Introducing support for Cortex-A65" into integration

Introducing support for Cortex-A65

Change-Id: I645442d52a295706948e2cac88c36c1a3cb0bc47
Signed-off-by: Imre Kis <imre.kis@arm.com>

Add missing support for BL2_AT_EL3 in XIP memory

Add the missing flag for aarch32 XIP memory mode. It was
previously added in aarch64 only.
Minor: Correct the aarch64 missing flag.

Signed-off-by: Lionel Debieve <lionel.debieve@st.com>
Change-Id: Iac0a7581a1fd580aececa75f97deb894858f776f

Merge "doc: Fix GCC version to 8.3-2019.03" into integration

doc: Fix GCC version to 8.3-2019.03

Change-Id: I3b866e927d93f4b690aa4891940fc8afabf4146e
Signed-off-by: Louis Mayencourt <louis.mayencourt@arm.com>

Merge "Cortex_hercules: Add support for Hercules-AE" into integration

Merge "doc: Migrate to Linaro release 19.06" into integration

qemu/qemu_sbsa: Adding memory mapping for both FLASH0/FLASH1

This patch adds mapping for secure FLASH0 for qemu/virt and
qemu/qemu_sbsa platforms. This change is targeted for sbsa but since both
platforms share common code, changes in common defines was necessary.

For qemu_sbsa, this patch adds necessary mapping in order to boot without
semi-hosting from secure FLASH0. EFI need to stay in FLASH1 (share it with
variables) since it need to "run in place" in non secure domain. Changes
for this are under RFC at edk2-platforms mailing list:
https://patches.linaro.org/patch/171327/
(edk2-platforms/Platform/Qemu/SbsaQemu/SbsaQemu.dsc).

In docs qemu/virt is described as using semi-hosting, therefore this change
should be orthogonal to existing assumptions while giving possibility to
store both bl1 and fip in FLASH0 at some point (additional changes required
for that).

Signed-off-by: Radoslaw Biernacki <radoslaw.biernacki@linaro.org>
Change-Id: I782bc3637c91c01eaee680b3c5c408e24b4b6e28

qemu/qemu_sbsa: Adding Qemu SBSA platform

This patch introduces Qemu SBSA platform.
Both platform specific files where copied from qemu/qemu with changes for
DRAM base above 32bit and removal of ARMv7 conditional defines/code.
Documentation is aligned to rest of SBSA patches along the series and
planed changes in edk2-platform repo.

Fixes ARM-software/tf-issues#602

Signed-off-by: Radoslaw Biernacki <radoslaw.biernacki@linaro.org>
Change-Id: I8ebc34eedb2268365e479ef05654b2df1b99128c

doc: Migrate to Linaro release 19.06

- Updated Linaro release version number to 19.06
- Updated links to Linaro instructions and releases
- Removed the Linaro old releases link

Signed-off-by: zelalem-aweke <zelalem.aweke@arm.com>
Change-Id: Ib786728106961e89182b42183e7b889f6fc74190

Cortex_hercules: Add support for Hercules-AE

Not tested on FVP Model.

Change-Id: Iedebc5c1fbc7ea577e94142b7feafa5546f1f4f9
Signed-off-by: Artsem Artsemenka <artsem.artsemenka@arm.com>

Merge "AArch32: Disable Secure Cycle Counter" into integration

Merge changes from topic "ld/stm32-authentication" into integration

* changes:
  stm32mp1: add authentication support for stm32image
  bsec: move bsec_mode_is_closed_device() service to platform
  crypto: stm32_hash: Add HASH driver

Merge "doc: Fix platform port inclusion" into integration

Merge changes from topic "amlogic-g12a" into integration

* changes:
  amlogic: g12a: Add support for the S905X2 (G12A) platform
  amlogic: makefile: Use PLAT variable when possible
  amlogic: sha_dma: Move register mappings to platform header

Merge changes from topic "a5ds-multicore" into integration

* changes:
  a5ds: add multicore support
  a5ds: Hold the secondary cpus in pen rather than panic

Merge "GICv3 driver: Fix support for full SPI range" into integration

Merge "Fix MTE support from causing unused variable warnings" into integration

Merge changes from topic "raspberry-pi-4-support" into integration

* changes:
  rpi4: Add initial documentation file
  rpi4: Add stdout-path to device tree
  rpi4: Add GIC maintenance interrupt to GIC DT node
  rpi4: Cleanup memory regions, move pens to first page
  rpi4: Reserve resident BL31 region from non-secure world
  rpi4: Amend DTB to advertise PSCI
  rpi4: Determine BL33 entry point at runtime
  rpi4: Accommodate "armstub8.bin" header at the beginning of BL31 image
  Add basic support for Raspberry Pi 4
  rpi3: Allow runtime determination of UART base clock rate
  FDT helper functions: Respect architecture in PSCI function IDs
  FDT helper functions: Add function documentation

Merge changes from topic "mp/giv3-discovery" into integration

* changes:
  Migrate ARM platforms to use the new GICv3 API
  Adding new optional PSCI hook pwr_domain_on_finish_late
  GICv3: Enable multi socket GIC redistributor frame discovery

AArch32: Disable Secure Cycle Counter

This patch changes implementation for disabling Secure Cycle
Counter. For ARMv8.5 the counter gets disabled by setting
SDCR.SCCD bit on CPU cold/warm boot. For the earlier
architectures PMCR register is saved/restored on secure
world entry/exit from/to Non-secure state, and cycle counting
gets disabled by setting PMCR.DP bit.
In 'include\aarch32\arch.h' header file new
ARMv8.5-PMU related definitions were added.

Change-Id: Ia8845db2ebe8de940d66dff479225a5b879316f8
Signed-off-by: Alexei Fedorov <Alexei.Fedorov@arm.com>

Merge changes I0283fc2e,Ib476d024,Iada05f7c into integration

* changes:
  hikey: fix to load FIP by partition table.
  hikey960: fix to load FIP by partition table
  drivers: partition: support different block size

amlogic: g12a: Add support for the S905X2 (G12A) platform

Introduce the preliminary support for the Amlogic S905X2 (G12A) SoC.

This port is a minimal implementation of BL31 capable of booting
mainline U-Boot and Linux. Tested on a SEI510 board.

Signed-off-by: Carlo Caione <ccaione@baylibre.com>
Change-Id: Ife958f10e815a4530292c45446adb71239f3367f

Migrate ARM platforms to use the new GICv3 API

This patch invokes the new function gicv3_rdistif_probe() in the
ARM platform specific gicv3 driver. Since this API modifies the
shared GIC related data structure, it must be invoked coherently
by using the platform specific pwr_domain_on_finish_late hook.

Change-Id: I6efb17d5da61545a1c5a6641b8f58472b31e62a8
Signed-off-by: Madhukar Pappireddy <madhukar.pappireddy@arm.com>

Adding new optional PSCI hook pwr_domain_on_finish_late

This PSCI hook is similar to pwr_domain_on_finish but is
guaranteed to be invoked with the respective core and cluster are
participating in coherency. This will be necessary to safely invoke
the new GICv3 API which modifies shared GIC data structures concurrently.

Change-Id: I8e54f05c9d4ef5712184c9c18ba45ac97a29eb7a
Signed-off-by: Madhukar Pappireddy <madhukar.pappireddy@arm.com>

GICv3: Enable multi socket GIC redistributor frame discovery

This patch provides declaration and definition of new GICv3 driver
API: gicv3_rdistif_probe().This function delegates the responsibility
of discovering the corresponding Redistributor base frame to each CPU
itself. It is a modified version of gicv3_rdistif_base_addrs_probe()
and is executed by each CPU in the platform unlike the previous
approach in which only the Primary CPU did the discovery of all the
Redistributor frames for every CPU.

The flush operations as part of gicv3_driver_init() function are
made necessary even for platforms with WARMBOOT_ENABLE_DCACHE_EARLY
because the GICv3 driver data structure contents are accessed by CPU
with D-Cache turned off during power down operations.

Change-Id: I1833e81d3974b32a3e4a3df4766a33d070982268
Signed-off-by: Madhukar Pappireddy <madhukar.pappireddy@arm.com>

doc: Fix platform port inclusion

This patch:

- Adds any leftover platform ports that were not having their
  documentation built (not in the index.rst table of contents)
- Corrects a handful of RST formatting errors that cause poor
  rendering
- Reorders the list of platforms so that they are displayed
  in alphabetical order

Change-Id: If8c135a822d581c3c5c4fca2936d501ccfd2e94c
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Merge "FVP: Fix plat_set_nv_ctr() function" into integration

Merge "doc: Render Marvell platform documents" into integration

rpi4: Add initial documentation file

As the Raspberry Pi4 port is now in a usable state, add the build
instructions together with some background information to the
documentation directory.
The port differs quite a bit from the Raspberry Pi 3, so we use a
separate file for that.

Change-Id: I7d9f5967fdf3ec3bfe97d78141f59cbcf03388d4
Signed-off-by: Andre Przywara <andre.przywara@arm.com>

rpi4: Add stdout-path to device tree

Some device tree users like to find a pointer to the standard serial
console in the device tree, in the "stdout-path" property of the /chosen
node.

Add the location of the Mini UART in that property, so that DT users are
happy, for instance Linux' earlycon detection.

Change-Id: I178e55016e5640de5ab0bc6e061944bd3583ea96
Signed-off-by: Andre Przywara <andre.przywara@arm.com>

rpi4: Add GIC maintenance interrupt to GIC DT node

For being able to use the virtualisation support the GIC offers, we need
to know the interrupt number of the maintenance interrupt. This
information is missing from the official RPi4 device tree.

Use libfdt to add the "interrupts" property to the GIC node, which
allows hypervisors like KVM or Xen to be able to use the GIC's help on
virtualising interrupts.

Change-Id: Iab84f0885a5bf29fb84ca8f385e8a39d27700c75
Signed-off-by: Andre Przywara <andre.przywara@arm.com>

rpi4: Cleanup memory regions, move pens to first page

Now that we have the SMP pens in the first page of DRAM, we can get rid
of all the fancy RPi3 memory regions that our RPi4 port does not really
need. This avoids using up memory all over the place, restricting ATF
to just run in the first 512KB of DRAM.

Remove the now unused regions. This also moves the SMP pens into our
first memory page (holding the firmware magic), where the original
firmware put them, but where there is also enough space for them.

Since the pens will require code execution privileges, we amend the
memory attributes used for that page to include write and execution
rights.

Change-Id: I131633abeb4a4d7b9057e737b9b0d163b73e47c6
Signed-off-by: Andre Przywara <andre.przywara@arm.com>

rpi4: Reserve resident BL31 region from non-secure world

The GPU firmware loads the armstub8.bin (BL31) image at address 0, the
beginning of DRAM. As this holds the resident PSCI code and the SMP
pens, the non-secure world should better know about this, to avoid
accessing memory owned by TF-A. This is particularly criticial as the
Raspberry Pi 4 does not feature a secure memory controller, so
overwriting code is a very real danger.

Use the newly introduced function to add a node into reserved-memory
node, where non-secure world can check for regions to be excluded from
its mappings.

Reserve the first 512KB of memory for now. We can refine this later if
need be.

Change-Id: I00e55e70c5c02615320d79ff35bc32b805d30770
Signed-off-by: Andre Przywara <andre.przywara@arm.com>

rpi4: Amend DTB to advertise PSCI

The device tree provided by the official Raspberry Pi firmware uses
spin tables for SMP bringup.

One of the benefit of having TF-A is that it provides PSCI services, so
let's rewrite the DTB to advertise PSCI instead of spin tables.
This uses the (newly exported) routine from the QEMU platform port.

Change-Id: Ifddcb14041ca253a333f8c2d5e97a42db152470c
Signed-off-by: Andre Przywara <andre.przywara@arm.com>

rpi4: Determine BL33 entry point at runtime

Now that we have the armstub magic value in place, the GPU firmware will
write the kernel load address (and DTB address) into our special page,
so we can always easily access the actual location without hardcoding
any addresses into the BL31 image.

Make the compile-time defined PRELOADED_BL33_BASE macro optional, and
read the BL33 entry point from the magic location, if the macro was not
defined. We do the same for the DTB address.

This also splits the currently "common" definition of
plat_get_ns_image_entrypoint() to be separate between RPi3 and RPi4.

Change-Id: I6f26c0adc6fce2df47786b271c490928b4529abb
Signed-off-by: Andre Przywara <andre.przywara@arm.com>

rpi4: Accommodate "armstub8.bin" header at the beginning of BL31 image

The Raspberry Pi GPU firmware checks for a magic value at offset 240
(0xf0) of the armstub8.bin image it loads. If that value matches,
it writes the kernel load address and the DTB address into subsequent
memory locations.
We can use these addresses to avoid hardcoding these values into the BL31
image, to make it more flexible and a drop-in replacement for the
official armstub8.bin.

Reserving just 16 bytes at offset 240 of the final image file is not easily
possible, though, as this location is in the middle of the generic BL31
entry point code.
However we can prepend an extra section before the actual BL31 image, to
contain the magic and addresses. This needs to be 4KB, because the
actual BL31 entry point needs to be page aligned.

Use the platform linker script hook that the generic code provides, to
add an almost empty 4KB code block before the entry point code. The very
first word contains a branch instruction to jump over this page, into
the actual entry code.
This also gives us plenty of room for the SMP pens later.

Change-Id: I38caa5e7195fa39cbef8600933a03d86f09263d6
Signed-off-by: Andre Przywara <andre.przywara@arm.com>

Add basic support for Raspberry Pi 4

The Raspberry Pi 4 is a single board computer with four Cortex-A72
cores. From a TF-A perspective it is quite similar to the Raspberry Pi
3, although it comes with more memory (up to 4GB) and has a GIC.

This initial port though differs quite a lot from the existing rpi3
platform port, mainly due to taking a much simpler and more robust
approach to loading the non-secure payload:
The GPU firmware of the SoC, which is responsible for initial platform
setup (including DRAM initialisation), already loads the kernel, device
tree and the "armstub" into DRAM. We take advantage of this, by placing
just a BL31 component into the armstub8.bin component, which will be
executed first, in AArch64 EL3.
The non-secure payload can be a kernel or a boot loader (U-Boot or
EDK-2), disguised as the "kernel" image and loaded by the GPU firmware.

So this is just a BL31-only port, which directly drops into EL2
and executes whatever has been loaded as the "kernel" image, handing
over the DTB address in x0.

Change-Id: I636f4d1f661821566ad9e341d69ba36f6bbfb546
Signed-off-by: Andre Przywara <andre.przywara@arm.com>

rpi3: Allow runtime determination of UART base clock rate

At the moment the UART input clock rate is hard coded at compile time.
This works as long as the GPU firmware always sets up the same rate,
which does not seem to be true for the Raspberry Pi 4.

In preparation for being able to change this at runtime, add a base
clock parameter to the console setup function. This is still hardcoded
for the Raspberry Pi 3.

Change-Id: I398bc2f1e9b46f7af9a84cb0b33cbe8e78f2d900
Signed-off-by: Andre Przywara <andre.przywara@arm.com>

FDT helper functions: Respect architecture in PSCI function IDs

PSCI uses different function IDs for CPU_SUSPEND and CPU_ON, depending on
the architecture used (AArch64 or AArch32).
For recent PSCI versions the client will determine the right version,
but for PSCI v0.1 we need to put some ID in the DT node. At the moment
we always add the 64-bit IDs, which is not correct if TF-A is built for
AArch32.

Use the function IDs matching the TF-A build architecture, for the two
IDs where this differs. This only affects legacy OSes using PSCI v0.1.

On the way remove the sys_poweroff and sys_reset properties, which were
never described in the official PSCI DT binding.

Change-Id: If77bc6daec215faeb2dc67112e765aacafd17f33
Signed-off-by: Andre Przywara <andre.przywara@arm.com>

FDT helper functions: Add function documentation

Since we moved some functions that amend a DT blob in memory to common
code, let's add proper function documentation.
This covers the three exported functions in common/fdt_fixup.c.

Change-Id: I67d7d27344e62172c789d308662f78d54903cf57
Signed-off-by: Andre Przywara <andre.przywara@arm.com>

FVP: Fix plat_set_nv_ctr() function

The Fast Models provide a non-volatile counter component, which is used
in the Trusted Board Boot implementation to protect against rollback
attacks.

This component comes in 2 versions (see [1]).

- Version 0 is the default and models a locked non-volatile counter,
  whose value is fixed.

- Version 1 of the counter may be incremented in a monotonic fashion.

plat_set_nv_ctr() must cope with both versions. This is achieved by:
1) Attempting to write the new value in the counter.
2) Reading the value back.
3) If there is a mismatch, we know the counter upgrade failed.

When using version 0 of the counter, no upgrade is possible so the
function is expected to fail all the time. However, the code is
missing a compiler barrier between the write operation and the next
read. Thus, the compiler may optimize and remove the read operation on
the basis that the counter value has not changed. With the default
optimization level used in TF-A (-Os), this is what's happening.

The fix introduced in this patch marks the write and subsequent read
accesses to the counter as volatile, such that the compiler makes no
assumption about the value of the counter.

Note that the comment above plat_set_nv_ctr() was clearly stating
that when using the read-only version of the non-volatile counter,
"we expect the values in the certificates to always match the RO
values so that this function is never called". However, the fact that
the counter value was read back seems to contradict this comment, as
it is implementing a counter-measure against misuse of the
function. The comment has been reworded to avoid any confusion.

Without this patch, this bug may be demonstrated on the Base AEM FVP:
- Using version 0 of the non-volatile counter (default version).
- With certificates embedding a revision number value of 32
  (compiling TF-A with TFW_NVCTR_VAL=32).

In this configuration, the non-volatile counter is tied to value 31 by
default. When BL1 loads the Trusted Boot Firmware certificate, it
notices that the two values do not match and tries to upgrade the
non-volatile counter. This write operation is expected to fail
(because the counter is locked) and the function is expected to return
an error but it succeeds instead.

As a result, the trusted boot does not abort as soon as it should and
incorrectly boots BL2. The boot is finally aborted when BL2 verifies
the BL31 image and figures out that the version of the SoC Firmware
Key Certificate does not match. On Arm platforms, only certificates
signed with the Root-of-Trust Key may trigger an upgrade of the
non-volatile Trusted counter.

[1] https://developer.arm.com/docs/100964/1160/fast-models-components/peripheral-components/nonvolatilecounter

Change-Id: I9979f29c23b47b338b9b484013d1fb86c59db92f
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>

a5ds: add multicore support

Enable cores 1-3 using psci. On receiving the smc call from kernel,
core 0 will bring the secondary cores out pen and signal an event for
the cores. Currently on switching the cores is enabled i.e. it is not
possible to suspend, switch cores off, etc.

Change-Id: I6087e1d2ec650e1d587fd543efc1b08cbb50ae5f
Signed-off-by: Usama Arif <usama.arif@arm.com>

a5ds: Hold the secondary cpus in pen rather than panic

For the secondary CPUs, hold the cpu in wfe rather then panic.
This will be needed when multicore support is added to a5ds as
the smc call will write to the hold base and signal an event to
power on the secondary CPUs.

Change-Id: I0ffc2059e9ef894c21375ca5c94def859bfa6599
Signed-off-by: Usama Arif <usama.arif@arm.com>