FWU SUIT RFC v0.4

* Removed the FETCHING state
* Addressed the issues relating to the use of payload fetching during the suit-install sequence.
* Added extra flow diagrams
* Further clarification of component ids
* Realised that an alternate flow might be a better API fit - see the Appendix with alternate sequence diagrams.

design/rfc-01-fwu-suit/fetch-sequence-v2.puml

@@ -0,0 +1,113 @@
+' SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates <[email protected]>
+' SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
+
+@startuml
+
+' SUIT update using the FWU API, reboot to install v2
+
+!include atg-spec.pumh
+
+box Network
+participant "Update server" as server
+end box
+box Device
+participant "Update client" as client
+participant "Firmware Update API" as api
+participant "Update service" as service
+end box
+entity "Envelope state" as envelope
+entity "Payload state" as payload
+
+autonumber
+activate client
+activate envelope #LightBlue
+rnote over envelope #LightBlue: READY
+
+client -> service: ""psa_fwu_start(envelope_id)""
+note left: Transfer SUIT Envelope
+deactivate envelope
+activate service #ddd
+return ""PSA_SUCCESS""
+deactivate service
+activate envelope #PaleGreen
+rnote over envelope #PaleGreen: WRITING
+
+client -> service #ddd: ""psa_fwu_write(envelope_id, ...)""
+activate service #ddd
+return ""PSA_SUCCESS""
+deactivate service
+
+client -> service: ""psa_fwu_finish(envelope_id)""
+deactivate envelope
+activate service #ddd
+return ""PSA_SUCCESS""
+deactivate service
+activate envelope #LightSalmon
+rnote over envelope #LightSalmon: CANDIDATE
+
+client -> service #ddd: ""psa_fwu_install()""
+note left: Proceed with installation
+deactivate envelope
+activate service #ddd
+return ""PSA_FWU_PROCESSING_REQUIRED""
+deactivate service
+activate envelope #PaleGoldenRod
+rnote over envelope #PaleGoldenRod: PROCESSING
+
+client -> service: ""psa_fwu_process()""
+note left: Process SUIT manifest
+note over service: ""suit-payload-fetch ""sequence
+activate service #ddd
+
+loop While additional payloads are required
+    return ""PSA_FWU_PAYLOAD_REQUIRED""\n  + payload information
+    deactivate service
+    activate payload #LightBlue
+    rnote over payload #LightBlue: READY
+
+    server <<- client ++ : Fetch payload
+    client -> service: ""psa_fwu_start(payload_id)""
+    note left: Transfer payload
+    deactivate payload
+    activate service #ddd
+    return ""PSA_SUCCESS""
+    deactivate service
+    activate payload #PaleGreen
+    rnote over payload #PaleGreen: WRITING
+
+    server -->> client: Download payload
+    client -> service: ""psa_fwu_write(payload_id, ...)""
+    activate service #ddd
+    return ""PSA_SUCCESS""
+    deactivate service
+
+    server -->> client -- : Download payload
+    client -> service: ""psa_fwu_write(payload_id, ...)""
+    activate service #ddd
+    client <-- service: ""PSA_SUCCESS""
+    deactivate service
+
+    client -> service: ""psa_fwu_finish(payload_id)""
+    deactivate payload
+    activate service #ddd
+    return ""PSA_SUCCESS""
+    deactivate service
+
+    client -> service: ""psa_fwu_process()""
+    note left: Resume SUIT processing
+    deactivate envelope
+    activate service #ddd
+
+end
+return  ""PSA_FWU_REBOOT_REQUIRED""
+note left: Reboot to continue installation
+deactivate service
+
+activate envelope #LightCoral
+rnote over envelope #LightCoral: STAGED
+
+client -->>] --: Request reboot
+
+== System restarts ==
+
+@enduml

design/rfc-01-fwu-suit/fetch-as-state.puml → design/rfc-01-fwu-suit/fetch-sequence.puml

@@ -45,22 +45,16 @@ deactivate service
 activate envelope #PaleGoldenRod
 rnote over envelope #PaleGoldenRod: PROCESSING
 
-client -> service: ""psa_fwu_process(envelope_id)""
-note left
-    Process SUIT manifest
-    - verify manifest
-    - suit-payload-fetch sequence
-end note
-'deactivate envelope
+client -> service: ""psa_fwu_process()""
+note left: Process SUIT manifest
+note over service: ""suit-payload-fetch ""sequence
 activate service #ddd
 
 loop While additional payloads are required
     return ""PSA_FWU_PAYLOAD_REQUIRED""\n  + payload information
     deactivate service
-    activate envelope #LightGoldenRodYellow
     activate payload #LightBlue
-    rnote over envelope #LightGoldenRodYellow: FETCHING ?
-    / rnote over payload #LightBlue: READY
+    rnote over payload #LightBlue: READY
 
     server <<- client ++ : Fetch payload
     client -> service: ""psa_fwu_start(payload_id)""
@@ -86,14 +80,11 @@ loop While additional payloads are required
 
     client -> service: ""psa_fwu_finish(payload_id)""
     deactivate payload
-    deactivate envelope
     activate service #ddd
     return ""PSA_SUCCESS""
     deactivate service
-'    activate envelope #PaleGoldenRod
-'    rnote over envelope #PaleGoldenRod: PROCESSING
 
-    client -> service: ""psa_fwu_process(envelope_id)""
+    client -> service: ""psa_fwu_process()""
     note left: Resume SUIT processing
     deactivate envelope
     activate service #ddd

design/rfc-01-fwu-suit/install-api-sequence.puml → design/rfc-01-fwu-suit/installer-sequence.puml

@@ -41,25 +41,15 @@ fetcher <<- installer ++: Start Fetcher
 activate envelope #PaleGoldenRod
 rnote over envelope #PaleGoldenRod: PROCESSING
 
-fetcher -> installer: ""psa_fwu_query(envelope_id)""
-activate installer #ddd
-note left: Query envelope status
-return ""PSA_SUCCESS""
-
-fetcher -> installer: ""psa_fwu_process(envelope_id)""
-note left
-    Process SUIT commands
-    - suit-install sequence
-end note
-'deactivate envelope
+fetcher -> installer: ""psa_fwu_process()""
+note left: Process SUIT commands
+note over installer: ""suit-install ""sequence
 activate installer #ddd
 
 loop While additional payloads are required
     return ""PSA_FWU_PAYLOAD_REQUIRED""\n  + payload information
-    activate envelope #LightGoldenRodYellow
     activate payload #LightBlue
-    rnote over envelope #LightGoldenRodYellow: FETCHING ?
-    / rnote over payload #LightBlue: READY
+    rnote over payload #LightBlue: READY
 
     server <<- fetcher ++ : Fetch payload
     fetcher -> installer: ""psa_fwu_start(payload_id)""
@@ -77,13 +67,10 @@ loop While additional payloads are required
 
     fetcher -> installer: ""psa_fwu_finish(payload_id)""
     deactivate payload
-    deactivate envelope
     activate installer #ddd
     return ""PSA_SUCCESS""
-'    activate envelope #PaleGoldenRod
-'    rnote over envelope #PaleGoldenRod: PROCESSING
 
-    fetcher -> installer: ""psa_fwu_process(envelope_id)""
+    fetcher -> installer: ""psa_fwu_process()""
     note left: Resume SUIT processing
     deactivate envelope
     activate installer #ddd
@@ -99,11 +86,10 @@ deactivate fetcher
 
 installer -> installer: SUIT Invocation
 deactivate installer
-note left
-    Process SUIT commands
-    - suit-validate sequence
-    - suit-load sequence
-    - suit-invoke sequence
+note over installer
+    ""suit-validate ""sequence
+    ""suit-load ""sequence
+    ""suit-invoke ""sequence
 end note
 
 

design/rfc-01-fwu-suit/no-reboot-sequence-v2.puml

@@ -0,0 +1,116 @@
+' SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates <[email protected]>
+' SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
+
+@startuml
+
+!include atg-spec.pumh
+
+' Streamlined flow?
+
+box Network
+participant "Update server" as server
+end box
+box Device
+participant "Update client" as client
+participant "Firmware Update API" as api
+participant "Update service" as service
+end box
+entity "Envelope state" as envelope
+entity "Payload state" as payload
+
+autonumber
+activate client
+activate envelope #LightBlue
+rnote over envelope #LightBlue: READY
+
+client -> service: ""psa_fwu_start(envelope_id)""
+note left: Transfer SUIT Envelope
+deactivate envelope
+activate service #ddd
+return ""PSA_SUCCESS""
+deactivate service
+activate envelope #PaleGreen
+rnote over envelope #PaleGreen: WRITING
+
+client -> service #ddd: ""psa_fwu_write(envelope_id, ...)""
+activate service #ddd
+return ""PSA_SUCCESS""
+deactivate service
+
+client -> service: ""psa_fwu_finish(envelope_id)""
+deactivate envelope
+activate service #ddd
+return ""PSA_SUCESS""
+deactivate service
+activate envelope #LightSalmon
+rnote over envelope #LightSalmon: CANDIDATE
+
+client -> service #ddd: ""psa_fwu_install()""
+note left: Proceed with installation
+deactivate envelope
+activate service #ddd
+
+return ""PSA_FWU_PROCESSING_REQUIRED""
+deactivate service
+activate envelope #PaleGoldenRod
+rnote over envelope #PaleGoldenRod: PROCESSING
+
+client -> service: ""psa_fwu_process()""
+note left: Process SUIT commands
+note over service
+    ""suit-payload-fetch ""sequence
+    ""suit-install ""sequence
+end note
+activate service #ddd
+
+loop While additional payloads are required
+    return ""PSA_FWU_PAYLOAD_REQUIRED""\n  + payload information
+    deactivate service
+    activate payload #LightBlue
+    rnote over payload #LightBlue: READY
+
+    server <<- client ++ : Fetch payload
+    client -> service: ""psa_fwu_start(payload_id)""
+    note left: Transfer payload
+    deactivate payload
+    activate service #ddd
+    return ""PSA_SUCCESS""
+    deactivate service
+    activate payload #PaleGreen
+    rnote over payload #PaleGreen: WRITING
+
+    server -->> client: Download payload
+    client -> service: ""psa_fwu_write(payload_id, ...)""
+    activate service #ddd
+    return ""PSA_SUCCESS""
+    deactivate service
+
+    server -->> client -- : Download payload
+    client -> service: ""psa_fwu_write(payload_id, ...)""
+    activate service #ddd
+    client <-- service: ""PSA_SUCCESS""
+    deactivate service
+
+    client -> service: ""psa_fwu_finish(payload_id)""
+    deactivate payload
+    activate service #ddd
+    return ""PSA_SUCCESS""
+    deactivate service
+
+    client -> service: ""psa_fwu_process()""
+    note left: Resume SUIT processing
+    deactivate envelope
+    activate service #ddd
+
+end
+note over service
+    ""suit-validate ""sequence
+    ""suit-load ""sequence
+    ""suit-invoke ""sequence
+end note
+client <-- service: ""PSA_SUCCESS""
+deactivate service
+activate envelope #aad
+rnote over envelope #aad: UPDATED
+
+@enduml