1da6c28aaSamw /*
2da6c28aaSamw  * CDDL HEADER START
3da6c28aaSamw  *
4da6c28aaSamw  * The contents of this file are subject to the terms of the
5da6c28aaSamw  * Common Development and Distribution License (the "License").
6da6c28aaSamw  * You may not use this file except in compliance with the License.
7da6c28aaSamw  *
8da6c28aaSamw  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9da6c28aaSamw  * or http://www.opensolaris.org/os/licensing.
10da6c28aaSamw  * See the License for the specific language governing permissions
11da6c28aaSamw  * and limitations under the License.
12da6c28aaSamw  *
13da6c28aaSamw  * When distributing Covered Code, include this CDDL HEADER in each
14da6c28aaSamw  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15da6c28aaSamw  * If applicable, add the following below this CDDL HEADER, with the
16da6c28aaSamw  * fields enclosed by brackets "[]" replaced with your own identifying
17da6c28aaSamw  * information: Portions Copyright [yyyy] [name of copyright owner]
18da6c28aaSamw  *
19da6c28aaSamw  * CDDL HEADER END
20da6c28aaSamw  */
21148c5f43SAlan Wright 
22da6c28aaSamw /*
23c5866007SKeyur Desai  * Copyright (c) 2007, 2010, Oracle and/or its affiliates. All rights reserved.
2448bbca81SDaniel Hoffman  * Copyright (c) 2016 by Delphix. All rights reserved.
25*af536d7dSGordon Ross  * Copyright 2021 Tintri by DDN, Inc. All rights reserved.
26da6c28aaSamw  */
27da6c28aaSamw 
28da6c28aaSamw /*
29da6c28aaSamw  * General Structures Layout
30da6c28aaSamw  * -------------------------
31da6c28aaSamw  *
32da6c28aaSamw  * This is a simplified diagram showing the relationship between most of the
33da6c28aaSamw  * main structures.
34da6c28aaSamw  *
35da6c28aaSamw  * +-------------------+
36da6c28aaSamw  * |     SMB_INFO      |
37da6c28aaSamw  * +-------------------+
38da6c28aaSamw  *          |
39da6c28aaSamw  *          |
40da6c28aaSamw  *          v
41da6c28aaSamw  * +-------------------+       +-------------------+      +-------------------+
42da6c28aaSamw  * |     SESSION       |<----->|     SESSION       |......|      SESSION      |
43da6c28aaSamw  * +-------------------+       +-------------------+      +-------------------+
443b13a1efSThomas Keiser  *   |          |
453b13a1efSThomas Keiser  *   |          |
463b13a1efSThomas Keiser  *   |          v
473b13a1efSThomas Keiser  *   |  +-------------------+     +-------------------+   +-------------------+
483b13a1efSThomas Keiser  *   |  |       USER        |<--->|       USER        |...|       USER        |
493b13a1efSThomas Keiser  *   |  +-------------------+     +-------------------+   +-------------------+
503b13a1efSThomas Keiser  *   |
513b13a1efSThomas Keiser  *   |
523b13a1efSThomas Keiser  *   v
53da6c28aaSamw  * +-------------------+       +-------------------+      +-------------------+
54da6c28aaSamw  * |       TREE        |<----->|       TREE        |......|       TREE        |
55da6c28aaSamw  * +-------------------+       +-------------------+      +-------------------+
56da6c28aaSamw  *      |         |
57da6c28aaSamw  *      |         |
58da6c28aaSamw  *      |         v
59da6c28aaSamw  *      |     +-------+       +-------+      +-------+
60da6c28aaSamw  *      |     | OFILE |<----->| OFILE |......| OFILE |
61da6c28aaSamw  *      |     +-------+       +-------+      +-------+
62da6c28aaSamw  *      |
63da6c28aaSamw  *      |
64da6c28aaSamw  *      v
65da6c28aaSamw  *  +-------+       +------+      +------+
66da6c28aaSamw  *  | ODIR  |<----->| ODIR |......| ODIR |
67da6c28aaSamw  *  +-------+       +------+      +------+
68da6c28aaSamw  *
69da6c28aaSamw  *
70da6c28aaSamw  * Tree State Machine
71da6c28aaSamw  * ------------------
72da6c28aaSamw  *
73da6c28aaSamw  *    +-----------------------------+	 T0
74da6c28aaSamw  *    |  SMB_TREE_STATE_CONNECTED   |<----------- Creation/Allocation
75da6c28aaSamw  *    +-----------------------------+
76da6c28aaSamw  *		    |
77da6c28aaSamw  *		    | T1
78da6c28aaSamw  *		    |
79da6c28aaSamw  *		    v
80da6c28aaSamw  *    +------------------------------+
81da6c28aaSamw  *    | SMB_TREE_STATE_DISCONNECTING |
82da6c28aaSamw  *    +------------------------------+
83da6c28aaSamw  *		    |
84da6c28aaSamw  *		    | T2
85da6c28aaSamw  *		    |
86da6c28aaSamw  *		    v
87da6c28aaSamw  *    +-----------------------------+    T3
88da6c28aaSamw  *    | SMB_TREE_STATE_DISCONNECTED |----------> Deletion/Free
89da6c28aaSamw  *    +-----------------------------+
90da6c28aaSamw  *
91da6c28aaSamw  * SMB_TREE_STATE_CONNECTED
92da6c28aaSamw  *
93da6c28aaSamw  *    While in this state:
94da6c28aaSamw  *      - The tree is queued in the list of trees of its user.
95da6c28aaSamw  *      - References will be given out if the tree is looked up.
96da6c28aaSamw  *      - Files under that tree can be accessed.
97da6c28aaSamw  *
98da6c28aaSamw  * SMB_TREE_STATE_DISCONNECTING
99da6c28aaSamw  *
100da6c28aaSamw  *    While in this state:
101da6c28aaSamw  *      - The tree is queued in the list of trees of its user.
102da6c28aaSamw  *      - References will not be given out if the tree is looked up.
103da6c28aaSamw  *      - The files and directories open under the tree are being closed.
104da6c28aaSamw  *      - The resources associated with the tree remain.
105da6c28aaSamw  *
106da6c28aaSamw  * SMB_TREE_STATE_DISCONNECTED
107da6c28aaSamw  *
108da6c28aaSamw  *    While in this state:
109da6c28aaSamw  *      - The tree is queued in the list of trees of its user.
110da6c28aaSamw  *      - References will not be given out if the tree is looked up.
111da6c28aaSamw  *      - The tree has no more files and directories opened.
112da6c28aaSamw  *      - The resources associated with the tree remain.
113da6c28aaSamw  *
114da6c28aaSamw  * Transition T0
115da6c28aaSamw  *
116da6c28aaSamw  *    This transition occurs in smb_tree_connect(). A new tree is created and
117da6c28aaSamw  *    added to the list of trees of a user.
118da6c28aaSamw  *
119da6c28aaSamw  * Transition T1
120da6c28aaSamw  *
121da6c28aaSamw  *    This transition occurs in smb_tree_disconnect().
122da6c28aaSamw  *
123da6c28aaSamw  * Transition T2
124da6c28aaSamw  *
125811599a4SMatt Barden  *    This transition occurs in smb_tree_disconnect()
126811599a4SMatt Barden  *
127811599a4SMatt Barden  * Transition T3
128811599a4SMatt Barden  *
129da6c28aaSamw  *    This transition occurs in smb_tree_release(). The resources associated
130da6c28aaSamw  *    with the tree are freed as well as the tree structure. For the transition
131811599a4SMatt Barden  *    to occur, the tree must be in the SMB_TREE_STATE_DISCONNECTED and the
132811599a4SMatt Barden  *    reference count must be zero.
133da6c28aaSamw  *
134da6c28aaSamw  * Comments
135da6c28aaSamw  * --------
136da6c28aaSamw  *
137da6c28aaSamw  *    The state machine of the tree structures is controlled by 3 elements:
138da6c28aaSamw  *      - The list of trees of the user it belongs to.
139da6c28aaSamw  *      - The mutex embedded in the structure itself.
140da6c28aaSamw  *      - The reference count.
141da6c28aaSamw  *
142da6c28aaSamw  *    There's a mutex embedded in the tree structure used to protect its fields
143da6c28aaSamw  *    and there's a lock embedded in the list of trees of a user. To
144da6c28aaSamw  *    increment or to decrement the reference count the mutex must be entered.
145da6c28aaSamw  *    To insert the tree into the list of trees of the user and to remove
146da6c28aaSamw  *    the tree from it, the lock must be entered in RW_WRITER mode.
147da6c28aaSamw  *
148da6c28aaSamw  *    Rules of access to a tree structure:
149da6c28aaSamw  *
150da6c28aaSamw  *    1) In order to avoid deadlocks, when both (mutex and lock of the user
151811599a4SMatt Barden  *       list) have to be entered, the lock must be entered first. Additionally,
152811599a4SMatt Barden  *       when both the (mutex and lock of the ofile list) have to be entered,
153811599a4SMatt Barden  *       the mutex must be entered first. However, the ofile list lock must NOT
154811599a4SMatt Barden  *       be dropped while the mutex is held in such a way that the ofile deleteq
155811599a4SMatt Barden  *       is flushed.
156da6c28aaSamw  *
157da6c28aaSamw  *    2) All actions applied to a tree require a reference count.
158da6c28aaSamw  *
159c8ec8eeaSjose borrego  *    3) There are 2 ways of getting a reference count: when a tree is
160c8ec8eeaSjose borrego  *       connected and when a tree is looked up.
161da6c28aaSamw  *
162da6c28aaSamw  *    It should be noted that the reference count of a tree registers the
163da6c28aaSamw  *    number of references to the tree in other structures (such as an smb
164da6c28aaSamw  *    request). The reference count is not incremented in these 2 instances:
165da6c28aaSamw  *
16648bbca81SDaniel Hoffman  *    1) The tree is connected. An tree is anchored by its state. If there's
167da6c28aaSamw  *       no activity involving a tree currently connected, the reference
168da6c28aaSamw  *       count of that tree is zero.
169da6c28aaSamw  *
170da6c28aaSamw  *    2) The tree is queued in the list of trees of the user. The fact of
171da6c28aaSamw  *       being queued in that list is NOT registered by incrementing the
172da6c28aaSamw  *       reference count.
173da6c28aaSamw  */
174148c5f43SAlan Wright 
175c8ec8eeaSjose borrego #include <sys/refstr_impl.h>
176