Merge pull request #758 from douglas-raillard-arm/dr/doc_interrupt_handler

Docs: Clarify IRQ/FIQ handler API in Interrupt Design Guide

docs/interrupt-framework-design.md

@@ -358,10 +358,16 @@ The `handle` parameter points to the `cpu_context` structure of the current CPU
 for the security state specified in the `flags` parameter.
 
 Once the handler routine completes, execution will return to either the secure
-or non-secure state. The handler routine should return a pointer to
-`cpu_context` structure of the current CPU for the target security state. It
-should treat all error conditions as critical errors and take appropriate action
-within its implementation e.g. use assertion failures.
+or non-secure state. The handler routine must return a pointer to
+`cpu_context` structure of the current CPU for the target security state. On
+AArch64, this return value is currently ignored by the caller as the
+appropriate `cpu_context` to be used is expected to be set by the handler
+via the context management library APIs.
+A portable interrupt handler implementation must set the target context both in
+the structure pointed to by the returned pointer and via the context management
+library APIs. The handler should treat all error conditions as critical errors
+and take appropriate action within its implementation e.g. use assertion
+failures.
 
 The runtime firmware provides the following API for registering a handler for a
 particular type of interrupt. A Secure Payload Dispatcher service should use