Update documentation to PSCI v1.1 ...

This patch adds documentation about the new PCSI API to the porting guide
and it also update the version and function list in the firmware design.

Change-Id: Ie4edd190926a501922c061f5fcad53c9b389e331
Signed-off-by: Roberto Vargas <roberto.vargas@arm.com>

GICv3: Document GICv3 save/restore helpers ...

Give hints on how to use the GICv3 save/restore helpers in the
implementation of the PSCI handlers.

Change-Id: I86de1c27417b64c7ce290974964ef97ff678f676
Signed-off-by: Douglas Raillard <douglas.raillard@arm.com>

Implement log framework ...

This patch gives users control over logging messages printed from the C
code using the LOG macros defined in debug.h Users now have the ability
to reduce the log_level at run time using the tf_log_set_max_level()
function. The default prefix string can be defined by platform by
overriding the `plat_log_get_prefix()` platform API which is also
introduced in this patch.

The new log framework results in saving of some RO data. For example,
when BL1 is built for FVP with LOG_LEVEL=LOG_LEVEL_VERBOSE, resulted
in saving 384 bytes of RO data and increase of 8 bytes of RW data. The
framework also adds about 108 bytes of code to the release build of FVP.

Fixes ARM-software/tf-issues#462

Change-Id: I476013d9c3deedfdd4c8b0b0f125665ba6250554
Co-authored-by: Eleanor Bonnici <Eleanor.bonnici@arm.com>
Signed-off-by: Soby Mathew <soby.mathew@arm.com>

porting-guide.rst: Fix some sections' level ...

Fix the level of the section
"13.   Function : plat_setup_psci_ops() [mandatory]",
including all the subsections.

Fix the level of the section
"12.7.   plat_psci_ops.pwr_domain_suspend_pwrdown_early() [optional]"
to lower it like the surrounding functions.

Change-Id: I781823bc96ece669f8fde4bd39c4e333c7bf4d1a
Signed-off-by: Douglas Raillard <douglas.raillard@arm.com>

lib: psci: early suspend handler for platforms ...

This patch adds an early suspend handler, that executes with
SMP and data cache enabled. This handler allows platforms to
perform any early actions during the CPU suspend entry sequence.

This handler is optional and platforms can choose to implement it
depending on their needs. The `pwr_domain_suspend` handler still
exists and platforms can keep on using it without any side effects.

Signed-off-by: Varun Wadekar <vwadekar@nvidia.com>

Emphasize that TF only supports 4 KB granule size ...

At the moment, various parts of the Trusted Firmware code assume
that the granule size used is 4 KB. For example, the linker scripts
enforce 4 KB alignment restrictions on some sections.

However, the ARMv8-A architecture allows 16 KB and 64 KB granule
sizes as well. Some other parts of the TF code, particularly the
architectural code and definitions, have been implemented with
this in mind and cater for all 3 cases.

This discrepancy creates some confusion as to what is effectively
supported in TF. This patch adds some code comments and clarification
in the documentation to make this limitation clearer.

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

Convert documentation to reStructuredText ...

Due to recent issues in the rendering of the documentation on GitHub and
some long-standing issues like the lack of automatic table of content in
Markdown, the documentation has been converted to reStructuredText.
Basic constructs looks pretty similar to Markdown.

Automatically convert GitHub markdown documentation to reStructuredText
using pandoc.

Change-Id: If20b695acedc6d1b49c8d9fb64efd6b6ba23f4a9
Signed-off-by: Douglas Raillard <douglas.raillard@arm.com>