1// Licensed to the .NET Foundation under one or more agreements.
2// The .NET Foundation licenses this file to you under the MIT license.
3// See the LICENSE file in the project root for more information.
4//*****************************************************************************
5// EventChannel.h
6//
7
8//
9// This file contains the old-style event channel interface.
10//*****************************************************************************
11
12
13#ifndef _EVENT_CHANNEL_H_
14#define _EVENT_CHANNEL_H_
15
16//---------------------------------------------------------------------------------------
17//
18// This is the abstract base class for the old-style "IPC" event channel. (Despite the name, these events are
19// no longer transmitted in an IPC shared memory block.) The event channel owns the DebuggerIPCControlBlock.
20//
21// Assumptions:
22// This class is NOT thread-safe. Caller is assumed to have taken the appropriate measures for
23// synchronization.
24//
25// Notes:
26// In Whidbey, both LS-to-RS and RS-to-LS communication are done by IPC shared memory block. We allocate
27// a DebuggerIPCControlBlock (DCB) on the IPC shared memory block. The DCB contains both a send buffer
28// and a receive buffer (from the perspective of the LS, e.g. the send buffer is for LS-to-RS communication).
29//
30// In the new architecture, LS-to-RS communication is mostly done by raising an exception on the LS and
31// calling code:INativeEventPipeline::WaitForDebugEvent on the RS. This communication is handled by
32// code:INativeEventPipeline. RS-to-LS communication is mostly done by calling into the code:IDacDbiInterface,
33// which on Windows is just a structured way to do ReadProcessMemory().
34//
35// There are still cases where we are sending IPC events in not-yet-DACized code. There are two main
36// categories:
37//
38// 1) There are three types of events which the RS can send to the LS:
39// a) asynchronous: the RS can just send the event and continue
40// b) synchronous, but no reply: the RS must wait for an acknowledgement, but there is no reply
41// c) synchronous, reply required: the RS must wait for an acknowledgement before it can get the reply
42//
43// For (c), the RS sends a synchronous IPC event to the LS and wait for a reply. The reply is returned
44// in the same buffer space used to send the event, i.e. in the receive buffer.
45// - RS: code:CordbRCEventThread::SendIPCEvent
46// - LS: code:DebuggerRCThread::SendIPCReply
47//
48// 2) In the case where the information from the LS has a variable size (and so we are not sure if it will
49// fit in one event), the RS sends an asynchronous IPC event to the LS and wait for one or more
50// events from the LS. The events from the LS are actually sent using the native pipeline. This is
51// somewhat tricky because we need to make sure the event from the native pipeline is passed along to
52// the thread which is waiting for the IPC events from the LS. (For more information, see how we use
53// code:CordbProcess::m_leftSideEventAvailable and code:CordbProcess::m_leftSideEventRead). Currently,
54// the only place where we use send IPC events this way is in the inspection code used to check the
55// results from the DAC against the results from the IPC events.
56// - RS: code:Cordb::WaitForIPCEventFromProcess
57// - LS: code:DebuggerRCThread::SendIPCEvent
58//
59// In a sense, you can think of the LS and the RS sharing 3 channels: one for debug events (see
60// code:INativeEventPipeline), one for DDI calls (see code:IDacDbiInterface),
61// and one for "IPC" events. This is the interface for the "IPC" events.
62//
63
64class IEventChannel
65{
66public:
67
68 //
69 // Inititalize the event channel.
70 //
71 // Arguments:
72 // hTargetProc - the handle of the debuggee process
73 //
74 // Return Value:
75 // S_OK if successful
76 //
77 // Notes:
78 // For Mac debugging, the handle is not necessary.
79 //
80
81 virtual HRESULT Init(HANDLE hTargetProc) = 0;
82
83 //
84 // Called when the debugger is detaching. Depending on the implementation, this may be necessary to
85 // make sure the debuggee state is reset in case another debugger attaches to it.
86 //
87 // Notes:
88 // This is currently a nop on for Mac debugging.
89 //
90
91 virtual void Detach() = 0;
92
93 //
94 // Delete the event channel and clean up all the resources it owns. This function can only be called once.
95 //
96
97 virtual void Delete() = 0;
98
99 //
100 // Update a single field with a value stored in the RS copy of the DCB. We can't update the entire LS DCB
101 // because in some cases, the LS and RS are simultaneously initializing the DCB. If we initialize a field on
102 // the RS and write back the whole thing, we may overwrite something the LS has initialized in the interim.
103 //
104 // Arguments:
105 // rsFieldAddr - the address of the field in the RS copy of the DCB that we want to write back to
106 // the LS DCB. We use this to compute the offset of the field from the beginning of the
107 // DCB and then add this offset to the starting address of the LS DCB to get the LS
108 // address of the field we are updating
109 // size - the size of the field we're updating.
110 //
111 // Return Value:
112 // S_OK if successful, otherwise whatever failure HR returned by the actual write operation
113 //
114
115 virtual HRESULT UpdateLeftSideDCBField(void * rsFieldAddr, SIZE_T size) = 0;
116
117 //
118 // Update the entire RS copy of the debugger control block by reading the LS copy. The RS copy is treated as
119 // a throw-away temporary buffer, rather than a true cache. That is, we make no assumptions about the
120 // validity of the information over time. Thus, before using any of the values, we need to update it. We
121 // update everything for simplicity; any perf hit we take by doing this instead of updating the individual
122 // fields we want at any given point isn't significant, particularly if we are updating multiple fields.
123 //
124 // Return Value:
125 // S_OK if successful, otherwise whatever failure HR returned by the actual read operation
126 //
127
128 virtual HRESULT UpdateRightSideDCB() = 0;
129
130 //
131 // Get the pointer to the RS DCB. The LS copy isn't updated until UpdateLeftSideDCBField() is called.
132 // Note that the DCB is owned by the event channel.
133 //
134 // Return Value:
135 // Return a pointer to the RS DCB. The memory is owned by the event channel.
136 //
137
138 virtual DebuggerIPCControlBlock * GetDCB() = 0;
139
140 //
141 // Check whether we need to wait for an acknowledgement from the LS after sending an IPC event.
142 // If so, wait for GetRightSideEventAckHandle().
143 //
144 // Arguments:
145 // pEvent - the IPC event which has just been sent to the LS
146 //
147 // Return Value:
148 // TRUE if an acknowledgement is required (see the comment for this class for more information)
149 //
150
151 virtual BOOL NeedToWaitForAck(DebuggerIPCEvent * pEvent) = 0;
152
153 //
154 // Get a handle to wait on after sending an IPC event to the LS. The caller should call NeedToWaitForAck()
155 // first to see if it is necessary to wait for an acknowledgement.
156 //
157 // Return Value:
158 // a handle to a Win32 event which will be signaled when the LS acknowledges the receipt of the IPC event
159 //
160 // Assumptions:
161 // NeedToWaitForAck() returns true after sending an IPC event to the LS
162 //
163
164 virtual HANDLE GetRightSideEventAckHandle() = 0;
165
166 //
167 // After sending an event to the LS and determining that we need to wait for the LS's acknowledgement,
168 // if any failure occurs, the LS may not have reset the Win32 event which is signaled when an event is
169 // available on the RS (i.e. what's called the Right-Side-Event-Available (RSEA) event). This function
170 // should be called if any failure occurs to make sure our state is consistent.
171 //
172
173 virtual void ClearEventForLeftSide() = 0;
174
175 //
176 // Send an IPC event to the LS. The caller should call NeedToWaitForAck() to check if it needs to wait
177 // for an acknowledgement, and wait on GetRightSideEventAckHandle() if necessary.
178 //
179 // Arguments:
180 // pEvent - the IPC event to be sent over to the LS
181 // eventSize - the size of the IPC event; cannot be bigger than CorDBIPC_BUFFER_SIZE
182 //
183 // Return Value:
184 // S_OK if successful
185 //
186 // Notes:
187 // This function returns a failure HR for recoverable errors. It throws on unrecoverable errors.
188 //
189
190 virtual HRESULT SendEventToLeftSide(DebuggerIPCEvent * pEvent, SIZE_T eventSize) = 0;
191
192 //
193 // Get the reply from the LS for a previously sent IPC event. The caller must have waited on
194 // GetRightSdieEventAckHandle().
195 //
196 // Arguments:
197 // pReplyEvent - buffer for the replyl event
198 // eventSize - size of the buffer
199 //
200 // Return Value:
201 // S_OK if successful
202 //
203
204 virtual HRESULT GetReplyFromLeftSide(DebuggerIPCEvent * pReplyEvent, SIZE_T eventSize) = 0;
205
206 //
207 // This function and GetEventFromLeftSide() are for the second category of IPC events described in the
208 // class header above, i.e. for events which take more than one IPC event to reply. The event actually
209 // doesn't come from the IPC channel. Instead, it comes from the native pipeline. We need to save the
210 // event from the native pipeline and then wake up the thread which is waiting for this event. Then the
211 // thread can call GetEventFromLeftSide() to receive this event.
212 //
213 // Arguments:
214 // pEventFromLeftSide - IPC event from the LS
215 //
216 // Return Value:
217 // S_OK if successful, E_FAIL if an event has already been saved
218 //
219 // Assumptions:
220 // At any given time there should only be one event saved. The caller is responsible for the
221 // synchronization.
222 //
223
224 virtual HRESULT SaveEventFromLeftSide(DebuggerIPCEvent * pEventFromLeftSide) = 0;
225
226 //
227 // See the function header for SaveEventFromLeftSide.
228 //
229 // Arguments:
230 // pLocalManagedEvent - buffer to be filled with the IPC event from the LS
231 //
232 // Return Value:
233 // S_OK if successful
234 //
235 // Assumptions:
236 // At any given time there should only be one event saved. The caller is responsible for the
237 // synchronization.
238 //
239
240 virtual HRESULT GetEventFromLeftSide(DebuggerIPCEvent * pLocalManagedEvent) = 0;
241};
242
243//-----------------------------------------------------------------------------
244//
245// Allocate and return an old-style event channel object for this target platform.
246//
247// Arguments:
248// pLeftSideDCB - target address of the DCB on the LS
249// pMutableDataTarget - data target for reading from and writing to the target process's address space
250// dwProcessId - used for Mac debugging; specifies the target process ID
251// machineInfo - used for Mac debugging; specifies the machine and the port number of the proxy
252// ppEventChannel - out parament; returns the newly created event channel
253//
254// Return Value:
255// S_OK if successful
256//
257
258HRESULT NewEventChannelForThisPlatform(CORDB_ADDRESS pLeftSideDCB,
259 ICorDebugMutableDataTarget * pMutableDataTarget,
260 const ProcessDescriptor * pProcessDescriptor,
261 MachineInfo machineInfo,
262 IEventChannel ** ppEventChannel);
263
264#endif // _EVENT_CHANNEL_H_
265