SST 16.0.0
Structural Simulation Toolkit
debugConsole.h
1// Copyright 2009-2026 NTESS. Under the terms
2// of Contract DE-NA0003525 with NTESS, the U.S.
3// Government retains certain rights in this software.
4//
5// Copyright (c) 2009-2026, NTESS
6// All rights reserved.
7//
8// This file is part of the SST software package. For license
9// information, see the LICENSE file in the top level directory of the
10// distribution.
11
12#ifndef SST_CORE_IMPL_INTERACTIVE_DEBUGCONSOLE_H
13#define SST_CORE_IMPL_INTERACTIVE_DEBUGCONSOLE_H
14
15#include "sst/core/eli/elementinfo.h"
16#include "sst/core/impl/interactive/cmdLineEditor.h"
17#include "sst/core/impl/interactive/debugCommands.h"
18#include "sst/core/impl/interactive/debugStream.h"
19#include "sst/core/interactiveConsole.h"
20#include "sst/core/serialization/objectMapDeferred.h"
21#include "sst/core/sst_mpi.h"
22#include "sst/core/threadsafe.h"
23#include "sst/core/watchPoint.h"
24
25#include <atomic>
26#include <cassert>
27#include <cstddef>
28#include <cstdint>
29#include <deque>
30#include <fstream>
31#include <functional>
32#include <iostream>
33#include <list>
34#include <map>
35#include <ostream>
36#include <queue>
37#include <sstream>
38#include <stack>
39#include <string>
40#include <utility>
41#include <vector>
42
43namespace SST::IMPL::Interactive {
44
45
46class DebugConsole : public SST::InteractiveConsole
47{
48
49public:
50 SST_ELI_REGISTER_INTERACTIVE_CONSOLE(
51 DebugConsole, // class
52 "sst", // library
53 "interactive.debugger", // name
54 SST_ELI_ELEMENT_VERSION(1, 0, 0),
55 "{EXPERIMENTAL} Interactive console debug probe")
56
57 SST_ELI_DOCUMENT_PARAMS(
58 {"replayFile", "script for playback upon entering interactive debug console", ""}
59 )
60
61 /**
62 Creates a new self partition scheme.
63 */
64 explicit DebugConsole(Params& params);
65 ~DebugConsole();
66
67 int execute(const std::string& msg) override;
68 void summary() override;
69
70 // Callbacks from command line completions
71 void get_listing_strings(std::list<std::string>&);
72
73private:
74 // This is the stack of where we are in the class hierarchy. This
75 // is needed because when we advance time, we'll need to delete
76 // any ObjectMap because they could change during execution.
77 // After running, this will allow us to recreate the working
78 // directory as far as we can.
79 std::deque<std::string> name_stack;
80
81 SST::Core::Serialization::ObjectMap* obj_ = nullptr;
82 bool done = false;
83 bool exit_console = false;
84 int retState = -1; // -1 DONE, -2 SUMMARY, positive number is threadID
85
86 void save_name_stack();
87 void cd_name_stack();
88
89 ExecutionType exec_type;
90 RankInfo num_ranks_;
91 RankInfo rank_;
92
93 bool autoCompleteEnable = true;
94
95 // logging support
96 std::ofstream loggingFile;
97 std::ifstream replayFile;
98 std::string loggingFilePath = "sst-console.out";
99 std::string replayFilePath = "sst-console.in";
100 bool enLogging = false;
101
102 // command injection (for sst --replay option)
103 std::stringstream injectedCommand;
104
105 // execution state management for nested user commands
106 ExecState eState = {};
107 std::stack<ExecState> eStack = {};
108
109 // Keep a pointer to the ObjectMap for the top level Component
110 SST::Core::Serialization::ObjectMapDeferred<BaseComponent>* base_comp_ = nullptr;
111
112 // Keep track of all the WatchPoints
113 std::vector<std::pair<WatchPoint*, BaseComponent*>> watch_points_;
114 bool query_clear_watchlist();
115 bool clear_watchlist(std::vector<std::string>& tokens);
116 bool confirm_ = true; // Ask for confirmation to clear watchlist
117
118 std::vector<std::string> tokenize(std::vector<std::string>& tokens, const std::string& input);
119
120 // Navigation
121 bool cmd_help(std::string& cmd_str);
122
123 bool cmd_verbose_query();
124 bool cmd_verbose_serial(std::string& cmd_str);
125 bool cmd_verbose_thread(std::string& cmd_str);
126 bool cmd_verbose_rank_serial(std::string& cmd_str);
127 bool cmd_verbose_rank_parallel(std::string& cmd_str);
128 bool cmd_verbose_remote(std::vector<std::string>&(tokens));
129
130 bool cmd_info_serial(std::string& cmd_str);
131 bool cmd_info_thread(std::string& cmd_str);
132 bool cmd_info_rank_serial(std::string& cmd_str);
133 bool cmd_info_rank_parallel(std::string& cmd_str);
134 bool cmd_info_remote(std::vector<std::string>& tokens);
135
136 int parse_thread();
137 bool cmd_thread_serial(std::string& cmd_str);
138 bool cmd_thread_thread(std::string& cmd_str);
139 bool cmd_thread_rank_serial(std::string& cmd_str);
140 bool cmd_thread_rank_parallel(std::string& cmd_str);
141 bool cmd_thread_remote(std::vector<std::string>& tokens);
142
143 int parse_rank();
144 bool cmd_rank_serial(std::string& cmd_str);
145 bool cmd_rank_thread(std::string& cmd_str);
146 bool cmd_rank_rank_serial(std::string& cmd_str);
147 bool cmd_rank_rank_parallel(std::string& cmd_str);
148 bool cmd_rank_remote(std::vector<std::string>& tokens);
149
150 bool cmd_setConfirm(std::string& cmd_str);
151
152 bool cmd_pwd_serial(std::string& cmd_str);
153 bool cmd_pwd_thread(std::string& cmd_str);
154 bool cmd_pwd_rank_serial(std::string& cmd_str);
155 bool cmd_pwd_rank_parallel(std::string& cmd_str);
156 bool cmd_pwd_remote(std::vector<std::string>& tokens);
157
158 bool cmd_cd_serial(std::string& cmd_str);
159 bool cmd_cd_thread(std::string& cmd_str);
160 bool cmd_cd_rank_serial(std::string& cmd_str);
161 bool cmd_cd_rank_parallel(std::string& cmd_str);
162 bool cmd_cd_remote(std::vector<std::string>& tokens);
163
164 bool cmd_ls_serial(std::string& cmd_str);
165 bool cmd_ls_thread(std::string& cmd_str);
166 bool cmd_ls_rank_serial(std::string& cmd_str);
167 bool cmd_ls_rank_parallel(std::string& cmd_str);
168 bool cmd_ls_remote(std::vector<std::string>& tokens);
169
170 // State
171 bool cmd_time(std::string& cmd_str);
172
173 bool cmd_print_serial(std::string& cmd_str);
174 bool cmd_print_thread(std::string& cmd_str);
175 bool cmd_print_rank_serial(std::string& cmd_str);
176 bool cmd_print_rank_parallel(std::string& cmd_str);
177 bool cmd_print_remote(std::vector<std::string>& tokens);
178
179 bool cmd_set_serial(std::string& cmd_str);
180 bool cmd_set_thread(std::string& cmd_str);
181 bool cmd_set_rank_serial(std::string& cmd_str);
182 bool cmd_set_rank_parallel(std::string& cmd_str);
183 bool cmd_set_remote(std::vector<std::string>& tokens);
184
185 bool cmd_watch_serial(std::string& cmd_str);
186 bool cmd_watch_thread(std::string& cmd_str);
187 bool cmd_watch_rank_serial(std::string& cmd_str);
188 bool cmd_watch_rank_parallel(std::string& cmd_str);
189 bool cmd_watch_remote(std::vector<std::string>& tokens);
190
191 bool cmd_trace_serial(std::string& cmd_str);
192 bool cmd_trace_thread(std::string& cmd_str);
193 bool cmd_trace_rank_serial(std::string& cmd_str);
194 bool cmd_trace_rank_parallel(std::string& cmd_str);
195 bool cmd_trace_remote(std::vector<std::string>& tokens);
196
197 bool cmd_watchlist_serial(std::string& cmd_str);
198 bool cmd_watchlist_thread(std::string& cmd_str);
199 bool cmd_watchlist_rank_serial(std::string& cmd_str);
200 bool cmd_watchlist_rank_parallel(std::string& cmd_str);
201 bool cmd_watchlist_remote(std::vector<std::string>& tokens);
202
203 bool cmd_addTraceVar_serial(std::string& cmd_str);
204 bool cmd_addTraceVar_thread(std::string& cmd_str);
205 bool cmd_addTraceVar_rank_serial(std::string& cmd_str);
206 bool cmd_addTraceVar_rank_parallel(std::string& cmd_str);
207 bool cmd_addTraceVar_remote(std::vector<std::string>& tokens);
208
209 bool cmd_printWatchpoint_serial(std::string& cmd_str);
210 bool cmd_printWatchpoint_thread(std::string& cmd_str);
211 bool cmd_printWatchpoint_rank_serial(std::string& cmd_str);
212 bool cmd_printWatchpoint_rank_parallel(std::string& cmd_str);
213 bool cmd_printWatchpoint_remote(std::vector<std::string>& tokens);
214
215 bool cmd_printTrace_serial(std::string& cmd_str);
216 bool cmd_printTrace_thread(std::string& cmd_str);
217 bool cmd_printTrace_rank_serial(std::string& cmd_str);
218 bool cmd_printTrace_rank_parallel(std::string& cmd_str);
219 bool cmd_printTrace_remote(std::vector<std::string>& tokens);
220
221 bool cmd_resetTraceBuffer_serial(std::string& cmd_str);
222 bool cmd_resetTraceBuffer_thread(std::string& cmd_str);
223 bool cmd_resetTraceBuffer_rank_serial(std::string& cmd_str);
224 bool cmd_resetTraceBuffer_rank_parallel(std::string& cmd_str);
225 bool cmd_resetTraceBuffer_remote(std::vector<std::string>& tokens);
226
227 bool cmd_setHandler_serial(std::string& cmd_str);
228 bool cmd_setHandler_thread(std::string& cmd_str);
229 bool cmd_setHandler_rank_serial(std::string& cmd_str);
230 bool cmd_setHandler_rank_parallel(std::string& cmd_str);
231 bool cmd_setHandler_remote(std::vector<std::string>& tokens);
232
233 bool cmd_unwatch_serial(std::string& cmd_str);
234 bool cmd_unwatch_thread(std::string& cmd_str);
235 bool cmd_unwatch_rank_serial(std::string& cmd_str);
236 bool cmd_unwatch_rank_parallel(std::string& cmd_str);
237 bool cmd_unwatch_remote(std::vector<std::string>& tokens);
238
239 // Simulation
240 bool cmd_run(std::string& cmd_str);
241
242 bool cmd_exit_serial(std::string& cmd_str);
243 bool cmd_exit_thread(std::string& cmd_str);
244 bool cmd_exit_rank_serial(std::string& cmd_str);
245 bool cmd_exit_rank_parallel(std::string& cmd_str);
246
247 bool cmd_shutdown(std::string& cmd_str);
248
249 // Logging/Replay
250 bool cmd_logging(std::string& cmd_str);
251 bool cmd_replay(std::string& cmd_str);
252 bool cmd_history(std::string& cmd_str);
253
254 // Auto-completion toggle
255 bool cmd_autoComplete(std::string& cmd_str);
256
257 // Reset terminal
258 bool cmd_clear(std::string& cmd_str);
259
260 // User defined commands
261 bool cmd_define(std::string& cmd_str);
262 bool cmd_document(std::string& cmd_str);
263
264 // command entry point
265 bool dispatch_cmd(std::string& cmd);
266
267 // Command Registry
268 CommandRegistry cmdRegistry;
269
270 // Command History
271 CommandHistoryBuffer cmdHistoryBuf;
272
273 // Command Line Editor
274 CmdLineEditor cmdLineEditor;
275 LINE_ENTRY_MODE line_entry_mode = LINE_ENTRY_MODE::NORMAL;
276
277 // Verbosity controlled console printing
278 uint32_t verbosity = 0;
279 void msg(VERBOSITY_MASK mask, std::string message);
280
281 // Pagination support
282 DebuggerStream dout;
283
284 // Support for serial, threaded, rank serial, rank parallel execution
285 static uint32_t current_thread;
286 static uint32_t current_rank;
287 static std::vector<std::string> tokens;
288 static std::stringstream result;
289
290 int consoleExecute(const std::string& msg);
291 int executeThread(const std::string& msg);
292 int executeRankSerial(const std::string& msg);
293 int executeRankParallel(const std::string& msg);
294 bool handleCommand();
295 bool handleCommandAll();
296 bool sendCommand(uint32_t rank_id, uint32_t thread_id, const std::string& cmd);
297 bool sendCommandAll(const std::string& cmd);
298 void receiveCommandRankSerial();
299 void receiveCommandRankParallel();
300 bool sendDone();
301};
302
303} // namespace SST::IMPL::Interactive
304
305#endif
CmdLineEditor
The command line editor uses termios to detect key presses and perform auto-completions.
Definition cmdLineEditor.h:44
SST::Core::Serialization::ObjectMapDeferred
ObjectMap version that will delay building the internal data structures until the object is "selected...
Definition objectMapDeferred.h:30
SST::Core::Serialization::ObjectMap
Base class for objects created by the serializer mapping mode used to map the variables for objects.
Definition objectMap.h:188
SST::IMPL::Interactive::CommandHistoryBuffer
Definition debugCommands.h:159
SST::IMPL::Interactive::CommandRegistry
Definition debugCommands.h:186
SST::IMPL::Interactive::DebugConsole::DebugConsole
DebugConsole(Params &params)
Creates a new self partition scheme.
Definition debugConsole.cc:41
SST::IMPL::Interactive::DebugConsole::execute
int execute(const std::string &msg) override
Called by TimeVortex to trigger checkpoint on simulation clock interval - not used in parallel simula...
Definition debugConsole.cc:4601
SST::IMPL::Interactive::DebugConsole::summary
void summary() override
Called by SyncManager to get summary info for each thread.
Definition debugConsole.cc:419
SST::IMPL::Interactive::DebuggerStream
Definition debugStream.h:87
SST::IMPL::Interactive::ExecState
Definition debugCommands.h:239
SST::InteractiveConsole
Definition interactiveConsole.h:46
SST::Params
Parameter store.
Definition params.h:65
SST::RankInfo
Definition rankInfo.h:24