Improve FWU documentation
- Clarify the documentation of the 'FWU_SMC_IMAGE_COPY' SMC in the
Firmware Update guide. Also extend the list of pre-conditions to
include the additional input validation implemented by previous
patches.
- Improve documentation of bl1_plat_mem_check() in the porting
guide. It now specifies that the generic FWU code protects
bl1_plat_mem_check() from integer overflows resulting from
the addition of the base address and size passed in arguments.
Change-Id: I07b47a3778df7b9c089529b2dd2135707640a91c
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
diff --git a/docs/firmware-update.md b/docs/firmware-update.md
index 97df8cf..21872fd 100644
--- a/docs/firmware-update.md
+++ b/docs/firmware-update.md
@@ -206,21 +206,31 @@
if (image_id is non-secure image) return -EPERM
if (image_id state is not (RESET or COPYING)) return -EPERM
if (secure world caller) return -EPERM
+ if (image_addr + block_size overflows) return -ENOMEM
+ if (image destination address + image_size overflows) return -ENOMEM
if (source block is in secure memory) return -ENOMEM
if (source block is not mapped into BL1) return -ENOMEM
if (image_size > free secure memory) return -ENOMEM
-This SMC copies the secure image indicated by `image_id` into secure memory. The
-image may be copied in a single block or multiple blocks. In either case, the
-total size of the image must be provided in `image_size` when invoking this SMC
-the first time for each image. The `image_addr` and `block_size` specify the
-source memory block to copy from. If `block_size` >= the size of the remaining
-image to copy, then BL1 completes the copy operation and sets the image state
-to COPIED. If there is still more to copy, BL1 sets the image state to COPYING.
+This SMC copies the secure image indicated by `image_id` from non-secure memory
+to secure memory for later authentication. The image may be copied in a single
+block or multiple blocks. In either case, the total size of the image must be
+provided in `image_size` when invoking this SMC for the first time for each
+image; it is ignored in subsequent calls (if any) for the same image.
+
+The `image_addr` and `block_size` specify the source memory block to copy from.
+The destination address is provided by the platform code.
+
+If `block_size` is greater than the amount of remaining bytes to copy for this
+image then the former is truncated to the latter. The copy operation is then
+considered as complete and the FWU state machine transitions to the "COPIED"
+state. If there is still more to copy, the FWU state machine stays in or
+transitions to the COPYING state (depending on the previous state).
+
When using multiple blocks, the source blocks do not necessarily need to be in
contiguous memory.
-BL1 returns from exception to the normal world caller.
+Once the SMC is handled, BL1 returns from exception to the normal world caller.
### FWU_SMC_IMAGE_AUTH
@@ -347,7 +357,7 @@
- - - - - - - - - - - - - - - - - - - - - - - - - -
-_Copyright (c) 2015, ARM Limited and Contributors. All rights reserved._
+_Copyright (c) 2015-2016, ARM Limited and Contributors. All rights reserved._
[Porting Guide]: ./porting-guide.md
diff --git a/docs/porting-guide.md b/docs/porting-guide.md
index a74966c..e8486f1 100644
--- a/docs/porting-guide.md
+++ b/docs/porting-guide.md
@@ -1121,10 +1121,15 @@
unsigned int flags
Return : int
-BL1 calls this function while handling FWU copy and authenticate SMCs. The
-platform must ensure that the provided `mem_base` and `mem_size` are mapped into
-BL1, and that this memory corresponds to either a secure or non-secure memory
-region as indicated by the security state of the `flags` argument.
+BL1 calls this function while handling FWU related SMCs, more specifically when
+copying or authenticating an image. Its responsibility is to ensure that the
+region of memory identified by `mem_base` and `mem_size` is mapped in BL1, and
+that this memory corresponds to either a secure or non-secure memory region as
+indicated by the security state of the `flags` argument.
+
+This function can safely assume that the value resulting from the addition of
+`mem_base` and `mem_size` fits into a `uintptr_t` type variable and does not
+overflow.
This function must return 0 on success, a non-null error code otherwise.
