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 //*****************************************************************************
9 // This file contains the old-style event channel interface.
10 //*****************************************************************************
13 #ifndef _EVENT_CHANNEL_H_
14 #define _EVENT_CHANNEL_H_
16 //---------------------------------------------------------------------------------------
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.
22 // This class is NOT thread-safe. Caller is assumed to have taken the appropriate measures for
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).
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().
35 // There are still cases where we are sending IPC events in not-yet-DACized code. There are two main
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
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
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
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.
69 // Inititalize the event channel.
72 // hTargetProc - the handle of the debuggee process
78 // For Mac debugging, the handle is not necessary.
81 virtual HRESULT Init(HANDLE hTargetProc) = 0;
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.
88 // This is currently a nop on for Mac debugging.
91 virtual void Detach() = 0;
94 // Delete the event channel and clean up all the resources it owns. This function can only be called once.
97 virtual void Delete() = 0;
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.
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.
112 // S_OK if successful, otherwise whatever failure HR returned by the actual write operation
115 virtual HRESULT UpdateLeftSideDCBField(void * rsFieldAddr, SIZE_T size) = 0;
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.
125 // S_OK if successful, otherwise whatever failure HR returned by the actual read operation
128 virtual HRESULT UpdateRightSideDCB() = 0;
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.
135 // Return a pointer to the RS DCB. The memory is owned by the event channel.
138 virtual DebuggerIPCControlBlock * GetDCB() = 0;
141 // Check whether we need to wait for an acknowledgement from the LS after sending an IPC event.
142 // If so, wait for GetRightSideEventAckHandle().
145 // pEvent - the IPC event which has just been sent to the LS
148 // TRUE if an acknowledgement is required (see the comment for this class for more information)
151 virtual BOOL NeedToWaitForAck(DebuggerIPCEvent * pEvent) = 0;
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.
158 // a handle to a Win32 event which will be signaled when the LS acknowledges the receipt of the IPC event
161 // NeedToWaitForAck() returns true after sending an IPC event to the LS
164 virtual HANDLE GetRightSideEventAckHandle() = 0;
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.
173 virtual void ClearEventForLeftSide() = 0;
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.
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
184 // S_OK if successful
187 // This function returns a failure HR for recoverable errors. It throws on unrecoverable errors.
190 virtual HRESULT SendEventToLeftSide(DebuggerIPCEvent * pEvent, SIZE_T eventSize) = 0;
193 // Get the reply from the LS for a previously sent IPC event. The caller must have waited on
194 // GetRightSdieEventAckHandle().
197 // pReplyEvent - buffer for the replyl event
198 // eventSize - size of the buffer
201 // S_OK if successful
204 virtual HRESULT GetReplyFromLeftSide(DebuggerIPCEvent * pReplyEvent, SIZE_T eventSize) = 0;
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.
214 // pEventFromLeftSide - IPC event from the LS
217 // S_OK if successful, E_FAIL if an event has already been saved
220 // At any given time there should only be one event saved. The caller is responsible for the
224 virtual HRESULT SaveEventFromLeftSide(DebuggerIPCEvent * pEventFromLeftSide) = 0;
227 // See the function header for SaveEventFromLeftSide.
230 // pLocalManagedEvent - buffer to be filled with the IPC event from the LS
233 // S_OK if successful
236 // At any given time there should only be one event saved. The caller is responsible for the
240 virtual HRESULT GetEventFromLeftSide(DebuggerIPCEvent * pLocalManagedEvent) = 0;
243 //-----------------------------------------------------------------------------
245 // Allocate and return an old-style event channel object for this target platform.
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
255 // S_OK if successful
258 HRESULT NewEventChannelForThisPlatform(CORDB_ADDRESS pLeftSideDCB,
259 ICorDebugMutableDataTarget * pMutableDataTarget,
261 MachineInfo machineInfo,
262 IEventChannel ** ppEventChannel);
264 #endif // _EVENT_CHANNEL_H_