From: Bill Fischofer <bill.fischo...@linaro.org> Replace the FSMs used to describe SA state transitions and IPsec operations with a Message Sequence Diagram (MSC) that shows the same information in an easier to follow form.
Update User Guide to reflect these changes as well. Signed-off-by: Bill Fischofer <bill.fischo...@linaro.org> --- /** Email created from pull request 320 (Bill-Fischofer-Linaro:ipsec-doc2) ** https://github.com/Linaro/odp/pull/320 ** Patch: https://github.com/Linaro/odp/pull/320.patch ** Base sha: d96a8207591fbcaac25b79286d7d72a537354c1f ** Merge commit sha: 958cf8c2adebe816b2e186ee4906b8538cb8f061 **/ doc/images/.gitignore | 2 +- doc/images/ipsec_fsm.gv | 32 -------------- doc/images/ipsec_sa_states.msc | 76 ++++++++++++++++++++++++++++++++++ doc/users-guide/Makefile.am | 4 +- doc/users-guide/users-guide-ipsec.adoc | 9 ++-- 5 files changed, 84 insertions(+), 39 deletions(-) delete mode 100644 doc/images/ipsec_fsm.gv create mode 100644 doc/images/ipsec_sa_states.msc diff --git a/doc/images/.gitignore b/doc/images/.gitignore index 0aa34793f..9bcc44f58 100644 --- a/doc/images/.gitignore +++ b/doc/images/.gitignore @@ -1,5 +1,5 @@ resource_management.svg -ipsec_fsm.svg +ipsec_sa_states.svg pktio_fsm.svg timer_fsm.svg timeout_fsm.svg diff --git a/doc/images/ipsec_fsm.gv b/doc/images/ipsec_fsm.gv deleted file mode 100644 index 1e78c8b85..000000000 --- a/doc/images/ipsec_fsm.gv +++ /dev/null @@ -1,32 +0,0 @@ -digraph ipsec_state_machine { - rankdir=LR; - size="12,12"; - node [fontsize=28]; - edge [fontsize=28]; - node [shape=doublecircle]; Unconfigured Configured SA_Ready SA_Expired; - node [shape=circle]; - Unconfigured -> Configured [label="odp_ipsec_config()" - constraint=false]; - Configured -> SA_Ready [label="odp_ipsec_sa_create()"]; - SA_Ready -> Disable_Pending [label="odp_ipsec_sa_disable()"]; - Disable_Pending -> Disable_Check [label="odp_queue_deq()"]; - Disable_Pending -> Disable_Check [label="odp_schedule()"]; - SA_Disabled -> Configured [label="odp_ipsec_sa_destroy()" - constraint=false]; - SA_Ready -> Processing [label="odp_ipsec_in_enq()"]; - SA_Ready -> Processing [label="odp_ipsec_out_enq()"]; - Processing -> Op_Complete [label="odp_queue_deq()"]; - Processing -> Op_Complete [label="odp_schedule()"]; - Op_Complete -> SA_Expired [label="hard limit reached" constraint=false]; - SA_Ready -> SA_Ready [label="odp_ipsec_in()"]; - SA_Ready -> SA_Ready [label="odp_ipsec_out()"]; - SA_Ready -> SA_Ready [label="odp_ipsec_out_inline()"]; - SA_Ready -> SA_Expired [label="hard limit reached"]; - Op_Complete -> SA_Ready [label="odp_ipsec_result()"] - Op_Complete -> SA_Ready [label="odp_ipsec_status()"] - Disable_Check -> SA_Disabled [label="odp_ipsec_status()" - constraint=false]; - Disable_Check -> Disable_Pending [label="odp_ipsec_result()" - constraint=false]; - SA_Expired -> Disable_Pending [label="odp_ipsec_sa_disable()"]; -} diff --git a/doc/images/ipsec_sa_states.msc b/doc/images/ipsec_sa_states.msc new file mode 100644 index 000000000..7030877e3 --- /dev/null +++ b/doc/images/ipsec_sa_states.msc @@ -0,0 +1,76 @@ +msc { + + a [label = "Application"], + o [label = "ODP"], + p [label = "Platform"]; + + --- [label = "IPsec configuration, done once"]; + a->o [label = "odp_ipsec_config()"]; + o->p [label = "Config IPsec"]; + o->a [label = "OK"]; + + |||; + --- [label = "IPsec SA creation, per SA"]; + |||; + + a->o [label = "odp_ipsec_sa_create()"]; + o->p [label = "SA Create"]; + o->a [label = "OK"]; + + |||; + --- [label = "IPsec operations, per SA"]; + |||; + + a->o [label = "odp_ipsec_in()"]; + o->p [label = "IPsec Decrypt"]; + p->a [label = "Done"]; + + a->o [label = "odp_ipsec_out()"]; + o->p [label = "IPsec Encrypt"]; + p->a [label = "Done"]; + + a->o [label = "odp_ipsec_out_inline()"]; + o->p [label = "IPsec Encrypt Inline"]; + o->a [label = "OK"]; + p->o [label = "OK"]; + + a->o [label = "odp_ipsec_in_enq()"]; + o->p [label = "Initiate IPsec operation"]; + a->o [label = "odp_ipsec_out_enq()"]; + o->p [label = "Initiate IPsec operation"]; + + |||; + --- [label = "Time passes"]; + |||; + + p->o [label = "IPsec op complete"]; + a->o [label = "odp_schedule()"]; + o->p [label = "Get Event"]; + p->a [label = "ODP_EVENT_PACKET subtype ODP_EVENT_PACKET_IPSEC"]; + a->o [label = "odp_ipsec_result()"]; + o->a [label = "OK"]; + + |||; + --- [label = "App done with SA, per SA"]; + |||; + + a->o [label = "odp_ipsec_sa_disable()"]; + o->p [label = "Disable/Delete SA"]; + o->a [label = "OK"]; + p->o [label = "Done"]; + + |||; + --- [label = "Time passes"]; + |||; + + a->o [label = "odp_schedule()"]; + o->p [label = "Get Event"]; + p->a [label = "ODP_EVENT_IPSEC_STATUS"]; + a->o [label = "odp_ipsec_status"]; + o->a [label = "ODP_IPSEC_STATUS_SA_DISABLED"]; + + a->o [label = "odp_ipsec_sa_destroy()"]; + o->a [label = "OK"]; + + +} \ No newline at end of file diff --git a/doc/users-guide/Makefile.am b/doc/users-guide/Makefile.am index 54f87bb63..b2ebd4d4f 100644 --- a/doc/users-guide/Makefile.am +++ b/doc/users-guide/Makefile.am @@ -11,7 +11,7 @@ SRC = users-guide.adoc \ TARGET = users-guide.html IMAGES = $(IMAGES_DIR)/overview.svg \ $(IMAGES_DIR)/atomic_queue.svg \ - $(IMAGES_DIR)/ipsec_fsm.svg \ + $(IMAGES_DIR)/ipsec_sa_states.svg \ $(IMAGES_DIR)/odp_components.svg \ $(IMAGES_DIR)/ODP-Logo-HQ.svg \ $(IMAGES_DIR)/odp_rx_processing.svg \ @@ -48,7 +48,7 @@ IMAGES += $(IMAGES_DIR)/resource_management.svg endif IMAGES_SRCS = \ - $(IMAGES_DIR)/ipsec_fsm.gv \ + $(IMAGES_DIR)/ipsec_sa_states.msc \ $(IMAGES_DIR)/pktio_fsm.gv \ $(IMAGES_DIR)/resource_management.msc \ $(IMAGES_DIR)/timeout_fsm.gv \ diff --git a/doc/users-guide/users-guide-ipsec.adoc b/doc/users-guide/users-guide-ipsec.adoc index d560df9c4..ac4eae85d 100644 --- a/doc/users-guide/users-guide-ipsec.adoc +++ b/doc/users-guide/users-guide-ipsec.adoc @@ -244,12 +244,13 @@ IPsec operations may produce. This can be changed dynamically by the As can be seen, SAs have a large degree of configurability. ==== SA Lifecycle Management -In discussing the lifecycle of an SA, it is useful to refer to the following -state diagram: +In discussing the lifecycle of an SA and the operations it supports, it is +useful to refer to the following sequence diagram for IPsec configuration, SA +management, and IPsec operations: -image::ipsec_fsm.svg[align="center"] +image:ipsec_sa_states.svg[align="center"] -After creation, IPsec services are active for this Security Association. The +After creation, IPsec services are active for this Security Association. The specific APIs that can be used on this SA depends on the IPsec operating mode that has been configured.
