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