architecture: add a binaries section

Add a section describing the various OP-TEE binaries produced by a
build.

Suggested-by: Caleb Connolly <[email protected]>
Signed-off-by: Jens Wiklander <[email protected]>
Acked-by: Etienne Carriere <[email protected]>

architecture/porting_guidelines.rst

@@ -207,6 +207,54 @@ typically will need to be shared with normal world, so there is need for some
 kind of memory firewall for this (more about that further down). As you can see
 we have also added the UART configuration here, i.e., the ``DEVICE0_xyz`` part.
 
+Binaries
+========
+Building OP-TEE results in a few binaries in the out directory.  Which
+binaries are used depends on how OP-TEE is loaded into memory.
+
+.. list-table:: Binaries generated by default
+   :header-rows: 1
+
+   * - Name
+     - Description
+   * - tee.elf
+     - The main ELF file. All other binaries are created with this
+       as input.
+   * - tee-header_v2.bin
+     - Combined header for tee-pager_v2.bin and tee-pageable_v2.bin. Used
+       by TF-A as bl32.bin to describe bl32_extra1.bin and bl32_extra2.bin.
+       Passed to TF-A with BL32=<filename>.bin when building the FIP.
+   * - tee-pager_v2.bin
+     - Raw binary for the unpaged and init parts of OP-TEE. Used by TF-A as
+       bl32_extra1.bin, requires tee-header_v2.bin. Passed to TF-A with
+       BL32_EXTRA1=<filename>.bin
+   * - tee-pageable_v2.bin
+     - Raw binary for the paged part of OP-TEE. Used by TF-A as
+       bl32_extra2.bin, requires tee-header_v2.bin. Passed to TF-A with
+       BL32_EXTRA2=<filename>.bin. This file is empty and the parameter is
+       optional if OP-TEE is built with CFG_WITH_PAGER=n
+   * - tee.bin
+     - The original binary with a header and combined init, paged, and
+       unpaged parts
+   * - tee.dmp
+     - A dump of the ELF file using ``objdump -lxd``
+   * - tee-raw.bin
+     - Raw binary suitable to copy into physical memory where OP-TEE
+       be can executed from. Used by Hafnium to load OP-TEE, passed via
+       sp_layout.json.
+
+.. list-table:: Binaries generated only if given as targets to make
+   :header-rows: 1
+
+   * - Name
+     - Description
+   * - tee.srec
+     - Dump an SREC file from tee-raw.bin using ``objcopy -I binary -O srec``
+   * - tee-pager.bin
+     - Legacy raw binary with unpaged sections.
+   * - tee-pageable.bin
+     - Legacy raw binary with paged and init sections.
+
 Official board support in OP-TEE?
 =================================
 We do encourage everyone to submit their board support to the OP-TEE project