+++ /dev/null
-From: Robert Love <robert.w.love@intel.com>
-Subject: [FcOE] Improve fc_lport.c locking comment block
-References: bnc #459142
-
-Signed-off-by: Robert Love <robert.w.love@intel.com>
-Acked-by: Bernhard Walle <bwalle@suse.de>
----
-
- drivers/scsi/libfc/fc_lport.c | 76 ++++++++++++++++++++++++------------------
- 1 file changed, 45 insertions(+), 31 deletions(-)
-
-
---- a/drivers/scsi/libfc/fc_lport.c
-+++ b/drivers/scsi/libfc/fc_lport.c
-@@ -18,34 +18,51 @@
- */
-
- /*
-- * General locking notes:
-+ * PORT LOCKING NOTES
- *
-- * The lport and rport blocks both have mutexes that are used to protect
-- * the port objects states. The main motivation for this protection is that
-- * we don't want to be preparing a request/response in one context while
-- * another thread "resets" the port in question. For example, if the lport
-- * block is sending a SCR request to the directory server we don't want
-- * the lport to be reset before we fill out the frame header's port_id. The
-- * problem is that a reset would cause the lport's port_id to reset to 0.
-- * If we don't protect the lport we'd spew incorrect frames.
-- *
-- * At the time of this writing there are two primary mutexes, one for the
-- * lport and one for the rport. Since the lport uses the rport and makes
-- * calls into that block the rport should never make calls that would cause
-- * the lport's mutex to be locked. In other words, the lport's mutex is
-- * considered the outer lock and the rport's lock is considered the inner
-- * lock. The bottom line is that you can hold a lport's mutex and then
-- * hold the rport's mutex, but not the other way around.
-- *
-- * The only complication to this rule is the callbacks from the rport to
-- * the lport's rport_callback function. When rports become READY they make
-- * a callback to the lport so that it can track them. In the case of the
-- * directory server that callback might cause the lport to change its
-- * state, implying that the lport mutex would need to be held. This problem
-- * was solved by serializing the rport notifications to the lport and the
-- * callback is made without holding the rport's lock.
-+ * These comments only apply to the 'port code' which consists of the lport,
-+ * disc and rport blocks.
- *
-- * lport locking notes:
-+ * MOTIVATION
-+ *
-+ * The lport, disc and rport blocks all have mutexes that are used to protect
-+ * those objects. The main motivation for these locks is to prevent from
-+ * having an lport reset just before we send a frame. In that scenario the
-+ * lport's FID would get set to zero and then we'd send a frame with an
-+ * invalid SID. We also need to ensure that states don't change unexpectedly
-+ * while processing another state.
-+ *
-+ * HEIRARCHY
-+ *
-+ * The following heirarchy defines the locking rules. A greater lock
-+ * may be held before acquiring a lesser lock, but a lesser lock should never
-+ * be held while attempting to acquire a greater lock. Here is the heirarchy-
-+ *
-+ * lport > disc, lport > rport, disc > rport
-+ *
-+ * CALLBACKS
-+ *
-+ * The callbacks cause complications with this scheme. There is a callback
-+ * from the rport (to either lport or disc) and a callback from disc
-+ * (to the lport).
-+ *
-+ * As rports exit the rport state machine a callback is made to the owner of
-+ * the rport to notify success or failure. Since the callback is likely to
-+ * cause the lport or disc to grab its lock we cannot hold the rport lock
-+ * while making the callback. To ensure that the rport is not free'd while
-+ * processing the callback the rport callbacks are serialized through a
-+ * single-threaded workqueue. An rport would never be free'd while in a
-+ * callback handler becuase no other rport work in this queue can be executed
-+ * at the same time.
-+ *
-+ * When discovery succeeds or fails a callback is made to the lport as
-+ * notification. Currently, succesful discovery causes the lport to take no
-+ * action. A failure will cause the lport to reset. There is likely a circular
-+ * locking problem with this implementation.
-+ */
-+
-+/*
-+ * LPORT LOCKING
- *
- * The critical sections protected by the lport's mutex are quite broad and
- * may be improved upon in the future. The lport code and its locking doesn't
-@@ -54,9 +71,9 @@
- *
- * The strategy is to lock whenever processing a request or response. Note
- * that every _enter_* function corresponds to a state change. They generally
-- * change the lports state and then sends a request out on the wire. We lock
-+ * change the lports state and then send a request out on the wire. We lock
- * before calling any of these functions to protect that state change. This
-- * means that the entry points into the lport block to manage the locks while
-+ * means that the entry points into the lport block manage the locks while
- * the state machine can transition between states (i.e. _enter_* functions)
- * while always staying protected.
- *
-@@ -68,9 +85,6 @@
- * Retries also have to consider the locking. The retries occur from a work
- * context and the work function will lock the lport and then retry the state
- * (i.e. _enter_* function).
-- *
-- * The implication to all of this is that each lport can only process one
-- * state at a time.
- */
-
- #include <linux/timer.h>
projects / people / teissler / ipfire-2.x.git / blobdiff