[API-NEXT,v4,1/1] doc: userguide: ipsec state machine changes

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.