xref: /illumos-gate/usr/src/cmd/mdb/common/kmdb/kmdb_wr.c (revision 7c478bd9)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License, Version 1.0 only
6  * (the "License").  You may not use this file except in compliance
7  * with the License.
8  *
9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10  * or http://www.opensolaris.org/os/licensing.
11  * See the License for the specific language governing permissions
12  * and limitations under the License.
13  *
14  * When distributing Covered Code, include this CDDL HEADER in each
15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16  * If applicable, add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your own identifying
18  * information: Portions Copyright [yyyy] [name of copyright owner]
19  *
20  * CDDL HEADER END
21  */
22 /*
23  * Copyright 2005 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 
27 #pragma ident	"%Z%%M%	%I%	%E% SMI"
28 
29 /*
30  * The communication mechanism for requesting that the driver perform work on
31  * behalf of the debugger.  Messages are passed and processed in FIFO order,
32  * with no provision for high priority messages.  High priority messages, such
33  * as debugger termination requests, should be passed using a different
34  * mechanism.
35  *
36  * Two FIFO queues are used for communication - one from the debugger to the
37  * driver, known as the driver_notify queue, and one from the driver to the
38  * debugger, known as the debugger_notify queue.  Messages are added to one
39  * queue, processed by the party on the other end, and are sent back as
40  * acknowledgements on the other queue.  All messages must be acknowledged, in
41  * part because the party who sent the message is the only one who can free it.
42  *
43  * Debugger-initiated work requests are usually triggered by dcmds such as
44  * ::load.  In the case of a ::load, the debugger adds a load request to the
45  * driver_notify queue.  The driver removes the request from the queue and
46  * processes it.  When processing is complete, the message is turned into an
47  * acknowledgement, and completion status is added.  The message is then added
48  * to the debugger_notify queue.  Upon receipt, the debugger removes the
49  * message from the queue, notes the completion status, and frees it.
50  *
51  * The driver can itself initiate unsolicited work, such as the automatic
52  * loading of a dmod in response to a krtld module load notification.  In this
53  * case, the driver loads the module and creates a work-completion message.
54  * This completion is identical to the one sent in the solicited load case
55  * above, with the exception of the acknowledgement bit, which isn't be set.
56  * When the debugger receives the completion message, it notes the completion
57  * status, and sends the message back to the driver via the driver_notify queue,
58  * this time with the acknowledgement bit set.
59  */
60 
61 #include <sys/types.h>
62 
63 #include <kmdb/kmdb_asmutil.h>
64 #include <kmdb/kmdb_wr_impl.h>
65 #include <mdb/mdb_debug.h>
66 #include <mdb/mdb.h>
67 
68 /*
69  * Called by the driver to pass a message to the debugger.  The debugger could
70  * start running at any time.  Nodes are added to the queue in FIFO order, but
71  * with links pointing in reverse order.
72  */
73 void
kmdb_wr_debugger_notify(void * arg)74 kmdb_wr_debugger_notify(void *arg)
75 {
76 	kmdb_wr_t *new = arg;
77 	kmdb_wr_t *curtail;
78 
79 	new->wn_next = new->wn_prev = NULL;
80 	membar_producer();
81 
82 	do {
83 		if ((curtail = mdb.m_dbgwrtail) == NULL) {
84 			/*
85 			 * The queue is empty, because tail will only be NULL if
86 			 * head is NULL too.  We're the only one who can add
87 			 * to the queue, so we can blindly add our node.  The
88 			 * debugger can't look at tail until head is non-NULL,
89 			 * so we set tail first.
90 			 */
91 			mdb.m_dbgwrtail = new;
92 			membar_producer();
93 			mdb.m_dbgwrhead = new;
94 			membar_producer();
95 			break;
96 		}
97 
98 		/*
99 		 * Point the new node at the current tail.  Attempt to set tail
100 		 * to point to our new node, but only as long as tail is what
101 		 * we think it is.
102 		 */
103 		new->wn_prev = curtail;
104 		membar_producer();
105 	} while (cas((uintptr_t *)&mdb.m_dbgwrtail, (uintptr_t)curtail,
106 	    (uintptr_t)new) != (uintptr_t)curtail);
107 }
108 
109 /*
110  * Called by the debugger to receive messages from the driver.  The driver
111  * has added the nodes in FIFO order, but has only set the prev pointers.  We
112  * have to correct that before processing the nodes.  This routine will not
113  * be preempted.
114  */
115 int
kmdb_wr_debugger_process(int (* cb)(kmdb_wr_t *,void *),void * arg)116 kmdb_wr_debugger_process(int (*cb)(kmdb_wr_t *, void *), void *arg)
117 {
118 	kmdb_wr_t *wn, *wnn;
119 	int i;
120 
121 	if (mdb.m_dbgwrhead == NULL)
122 		return (0); /* The queue is empty, so there's nothing to do */
123 
124 	/* Re-establish the next links so we can traverse in FIFO order */
125 	mdb.m_dbgwrtail->wn_next = NULL;
126 	for (wn = mdb.m_dbgwrtail; wn->wn_prev != NULL;
127 	    wn = wn->wn_prev)
128 		wn->wn_prev->wn_next = wn;
129 
130 	/* We don't own wn after we've invoked the callback */
131 	wn = mdb.m_dbgwrhead;
132 	i = 0;
133 	do {
134 		wnn = wn->wn_next;
135 		i += cb(wn, arg);
136 	} while ((wn = wnn) != NULL);
137 
138 	mdb.m_dbgwrhead = mdb.m_dbgwrtail = NULL;
139 
140 	return (i);
141 }
142 
143 /*
144  * Called by the debugger to check queue status.
145  */
146 int
kmdb_wr_debugger_notify_isempty(void)147 kmdb_wr_debugger_notify_isempty(void)
148 {
149 	return (mdb.m_dbgwrhead == NULL);
150 }
151 
152 /*
153  * Called by the debugger to pass a message to the driver.  This routine will
154  * not be preempted.
155  */
156 void
kmdb_wr_driver_notify(void * arg)157 kmdb_wr_driver_notify(void *arg)
158 {
159 	kmdb_wr_t *new = arg;
160 
161 	/*
162 	 * We restrict ourselves to manipulating the rear of the queue.  We
163 	 * don't look at the head unless the tail is NULL.
164 	 */
165 	if (mdb.m_drvwrtail == NULL) {
166 		new->wn_next = new->wn_prev = NULL;
167 		mdb.m_drvwrhead = mdb.m_drvwrtail = new;
168 	} else {
169 		mdb.m_drvwrtail->wn_next = new;
170 		new->wn_prev = mdb.m_drvwrtail;
171 		new->wn_next = NULL;
172 		mdb.m_drvwrtail = new;
173 	}
174 }
175 
176 /*
177  * Called by the driver to receive messages from the debugger.  The debugger
178  * could start running at any time.
179  *
180  * NOTE: This routine may run *after* mdb_destroy(), and may *NOT* use any MDB
181  * services.
182  */
183 int
kmdb_wr_driver_process(int (* cb)(kmdb_wr_t *,void *),void * arg)184 kmdb_wr_driver_process(int (*cb)(kmdb_wr_t *, void *), void *arg)
185 {
186 	kmdb_wr_t *worklist, *wn, *wnn;
187 	int rc, rv, i;
188 
189 	if ((worklist = mdb.m_drvwrhead) == NULL) {
190 		return (0); /* The queue is empty, so there's nothing to do */
191 	}
192 
193 	mdb.m_drvwrhead = NULL;
194 	/* The debugger uses tail, so enqueues still work */
195 	membar_producer();
196 	mdb.m_drvwrtail = NULL;
197 	membar_producer();
198 
199 	/*
200 	 * The current set of messages has been removed from the queue, so
201 	 * we can process them at our leisure.
202 	 */
203 
204 	wn = worklist;
205 	rc = i = 0;
206 	do {
207 		wnn = wn->wn_next;
208 		if ((rv = cb(wn, arg)) < 0)
209 			rc = -1;
210 		else
211 			i += rv;
212 	} while ((wn = wnn) != NULL);
213 
214 	return (rc == 0 ? i : -1);
215 }
216 
217 /*
218  * Called by the debugger to check queue status
219  */
220 int
kmdb_wr_driver_notify_isempty(void)221 kmdb_wr_driver_notify_isempty(void)
222 {
223 	return (mdb.m_drvwrhead == NULL);
224 }
225