GitLab

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>

Currently we have some pre-rendered versions of certain diagrams
in SVG format. These diagrams have corresponding PlantUML source
that can be rendered automatically as part of the documentation
build, removing the need for any intermediate files.

This patch adds the Sphinx "plantuml" extension, replaces
references to the pre-rendered SVG files within the documents,
and finally removes the SVG files and helper script.

New requirements for building the docs are the
"sphinxcontrib-plantuml" Python module (added to the pip
requirements.txt file) and the Graphviz package (provides the
"dot" binary) which is in the Ubuntu package repositories.

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

Change-Id: Ic09e74f22b43fba51ee17cd02b5e1dc5d8e0bb63
Signed-off-by: John Tsichritzis <john.tsichritzis@arm.com>

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

Several code blocks do not specify a language for syntax
highlighting. This results in Sphinx using a default highlighter
which is Python.

This patch adds the correct language to each code block that doesn't
already specify it.

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

These are no longer needed as there will always be a table of contents
rendered to the left of every page.

Some of these lists can be quite long and, when opening a page, the
reader sees nothing but a huge list of contents! After this patch,
the document contents are front-and-centre and the contents are
nicely rendered in the sidebar without duplication.

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

This change creates the following directories under docs/
in order to provide a grouping for the content:

- components
- design
- getting_started
- perf
- process

In each of these directories an index.rst file is created
and this serves as an index / landing page for each of the
groups when the pages are compiled. Proper layout of the
top-level table of contents relies on this directory/index
structure.

Without this patch it is possible to build the documents
correctly with Sphinx but the output looks messy because
there is no overall hierarchy.

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

Fix some typos and clarify some sentences.

Change-Id: Id276d1ced9a991b4eddc5c47ad9a825e6b29ef74
Signed-off-by: Antonio Nino Diaz <antonio.ninodiaz@arm.com>

SDEI event dispatches currently only sets up the Non-secure context
before returning to the caller. The actual dispatch only happens upon
exiting EL3 next time.

However, for various error handling scenarios, it's beneficial to have
the dispatch happen synchronously. I.e. when receiving SDEI interrupt,
or for a successful sdei_dispatch_event() call, the event handler is
executed; and upon the event completion, dispatcher execution resumes
after the point of dispatch. The jump primitives introduced in the
earlier patch facilitates this feature.

With this patch:

  - SDEI interrupts and calls to sdei_dispatch_event prepares the NS
    context for event dispatch, then sets a jump point, and immediately
    exits EL3. This results in the client handler executing in
    Non-secure.

  - When the SDEI client completes the dispatched event, the SDEI
    dispatcher does a longjmp to the jump pointer created earlier. For
    the caller of the sdei_dispatch_event() in particular, this would
    appear as if call returned successfully.

The dynamic workaround for CVE_2018_3639 is slightly shifted around as
part of related minor refactoring. It doesn't affect the workaround
functionality.

Documentation updated.

NOTE: This breaks the semantics of the explicit dispatch API, and any
exiting usages should be carefully reviewed.

Change-Id: Ib9c876d27ea2af7fb22de49832e55a0da83da3f9
Signed-off-by: Jeenu Viswambharan <jeenu.viswambharan@arm.com>

The current macros only allow to define dynamic and statically-bound
SDEI events. However, there ought be a mechanism to define SDEI events
that are explicitly dispatched; i.e., events that are dispatched as a
result of a previous secure interrupt or other exception

This patch introduces SDEI_EXPLICIT_EVENT() macro to define an explicit
event. They must be placed under private mappings. Only the priority
flags are allowed to be additionally specified.

Documentation updated.

Change-Id: I2e12f5571381195d6234c9dfbd5904608ad41db3
Signed-off-by: Jeenu Viswambharan <jeenu.viswambharan@arm.com>

Update Arm Trusted Firmware references in the upstream documents to
Trusted Firmware-A (TF-A). This is for consistency with and
disambiguation from Trusted Firmware-M (TF-M).

Also update other Arm trademarks, e.g. ARM->Arm, ARMv8->Armv8-A.

Change-Id: I8bb0e18af29c6744eeea2dc6c08f2c10b20ede22
Signed-off-by: Dan Handley <dan.handley@arm.com>
Signed-off-by: David Cunado <david.cunado@arm.com>

The explicit event dispatch sequence currently depicts handling done in
Secure EL1, although further error handling is typically done inside a
Secure Partition. Clarify the sequence diagram to that effect.

Change-Id: I53deedc6d5ee0706626890067950c2c541a62c78
Signed-off-by: Jeenu Viswambharan <jeenu.viswambharan@arm.com>

The document includes SDEI sequence diagrams that are generated using
PlantUML [1].

A shell script is introduced to generate SVG files from PlantUML files
supplied in arguments.

[1] http://plantuml.com/PlantUML_Language_Reference_Guide.pdf



Change-Id: I433897856810bf1927f2800a7b2b1d81827c69b2
Signed-off-by: Jeenu Viswambharan <jeenu.viswambharan@arm.com>