GXemul.h Source File

Back to the index.

GXemul.h
Go to the documentation of this file.
1 #ifndef GXEMUL_H
2 #define GXEMUL_H
3 
4 /*
5  * Copyright (C) 2007-2010 Anders Gavare. All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions are met:
9  *
10  * 1. Redistributions of source code must retain the above copyright
11  * notice, this list of conditions and the following disclaimer.
12  * 2. Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in the
14  * documentation and/or other materials provided with the distribution.
15  * 3. The name of the author may not be used to endorse or promote products
16  * derived from this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21  * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
22  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28  * SUCH DAMAGE.
29  */
30 
31 #include "misc.h"
32 
33 #include <sys/time.h>
34 
35 #include "CommandInterpreter.h"
36 #include "Component.h"
37 #include "UI.h"
38 
39 
40 /**
41  * \brief The main emulator class.
42  *
43  * A %GXemul instance basically has the following member variables:
44  *
45  * <ol>
46  * <li>a tree of components, which make up the full
47  * state of the current emulation setup
48  * <li>a UI, which runs the main [interactive] loop
49  * <li>a CommandInterpreter
50  * <li>a RunState
51  * <li>a list of "on reset commands", which are executed on Reset().
52  * </ol>
53  */
54 class GXemul
55 {
56 public:
57  enum RunState
58  {
60  SingleStepping, // Single-step execution
61  Running, // Continuous execution
63  };
64 
65 public:
66  /**
67  * \brief Creates a GXemul instance.
68  */
69  GXemul();
70 
71  /**
72  * \brief Parses command line arguments (file names).
73  *
74  * @param templateMachine The template machine to use.
75  * @param filenameCount for parsing command line options.
76  * @param filenames for parsing command line options.
77  * @return true if options were parsable, false if there was
78  * some error.
79  */
80  bool ParseFilenames(string templateMachine, int filenameCount, char *filenames[]);
81 
82  /**
83  * \brief Discards the current emulation, and starts anew with just
84  * an empty root component.
85  */
86  void ClearEmulation();
87 
88  /**
89  * \brief Initializes the %UI.
90  */
91  void InitUI();
92 
93  /**
94  * \brief Runs GXemul's main loop.
95  *
96  * @return Zero on success, non-zero on error.
97  */
98  int Run();
99 
100  /**
101  * \brief Gets the current emulation setup's filename.
102  *
103  * @return The name of the file that is used for the current emulation
104  * setup. If no filename is defined yet, this is an empty string.
105  */
106  const string& GetEmulationFilename() const;
107 
108  /**
109  * \brief Sets the current emulation setup's filename.
110  *
111  * @param filename This is the name of the file that is used
112  * for the current emulation setup.
113  */
114  void SetEmulationFilename(const string& filename);
115 
116  /**
117  * \brief Gets a reference to the CommandInterpreter.
118  *
119  * @return A reference to the %GXemul instance' CommandInterpreter.
120  */
122 
123  /**
124  * \brief Gets a pointer to the %GXemul instance' active UI.
125  *
126  * Note: Never NULL. The UI may be the NullUI, or another UI (such
127  * as the ConsoleUI).
128  *
129  * @return A pointer to the UI in use.
130  */
131  UI* GetUI();
132 
133  /**
134  * \brief Gets a pointer to the root configuration component.
135  *
136  * @return A pointer to the root component. If no configuration tree
137  * is loaded, then this is at least an empty dummy component.
138  * (The return value is never NULL.)
139  */
142 
143  /**
144  * \brief Sets the root component, discarding the previous one.
145  *
146  * This function should not be used to set the root component
147  * to NULL. Use ClearEmulation() instead.
148  *
149  * @param newRootComponent A reference counted pointer to the new
150  * root component. It may not be a NULL pointer.
151  */
152  void SetRootComponent(refcount_ptr<Component> newRootComponent);
153 
154  /**
155  * \brief Resets the emulation.
156  *
157  * This function recursively resets all components in the tree, and
158  * then executes the "on reset" commands (usually commands to load
159  * files into CPUs).
160  *
161  * @return false if any of the reset commands failed.
162  */
163  bool Reset();
164 
165  /**
166  * \brief Interrupts emulation.
167  *
168  * Only meaningful if RunState is Running or SingleStepping.
169  */
170  void Interrupt();
171 
172  /**
173  * \brief Returns whether or not the current emulation is being
174  * interrupted.
175  *
176  * Only meaningful if RunState is Running or SingleStepping.
177  */
178  bool IsInterrupting() const
179  {
180  return m_interrupting;
181  }
182 
183  /**
184  * \brief Sets the RunState.
185  *
186  * @param newState The new RunState.
187  */
188  void SetRunState(RunState newState);
189 
190  /**
191  * \brief Gets the current RunState.
192  *
193  * @return The current RunState.
194  */
195  RunState GetRunState() const;
196 
197  /**
198  * \brief Gets the current RunState as a string.
199  *
200  * @return The current RunState, formatted as a string.
201  */
202  string GetRunStateAsString() const;
203 
204  /**
205  * \brief Gets the current step of the emulation.
206  *
207  * @return The nr of steps that the emulation has been executing,
208  * since the start.
209  */
210  uint64_t GetStep() const;
211 
212  /**
213  * \brief Checks whether snapshots are currently enabled or not.
214  *
215  * @return True if running in quiet mode, false for normal operation.
216  */
217  bool GetSnapshottingEnabled() const;
218 
219  /**
220  * \brief Sets whether or not to use snapshots.
221  *
222  * @param enabled true to enable snapshotting, false to disable it.
223  */
224  void SetSnapshottingEnabled(bool enabled);
225 
226  /**
227  * \brief Gets the current quiet mode setting.
228  *
229  * @return True if running in quiet mode, false for normal operation.
230  */
231  bool GetQuietMode() const;
232 
233  /**
234  * \brief Sets whether or not to run in quiet mode.
235  *
236  * @param quietMode true to run in quiet mode, false otherwise.
237  */
238  void SetQuietMode(bool quietMode);
239 
240  /**
241  * \brief Sets the nr of single-steps to perform in a row.
242  *
243  * @param steps The number of steps, at least 1.
244  */
245  void SetNrOfSingleStepsInARow(uint64_t steps);
246 
247  /**
248  * \brief Change step either forwards or backwards.
249  *
250  * @param oldStep The old step count.
251  * @param newStep The new step count.
252  * @return True if changing step worked, false if there was a failure.
253  */
254  bool ModifyStep(int64_t oldStep, int64_t newStep);
255 
256  /**
257  * \brief Run the emulation for "a while".
258  *
259  * When single-stepping, this function will:
260  * <ul>
261  * <li>execute one step,
262  * <li>set the run state to Paused,
263  * <li>and then return.
264  * </ul>
265  *
266  * When not single-stepping, components will execute multiple steps at
267  * once, if possible. In the most common case (no breakpoints or other
268  * special cases), when this function returns, the run state will not
269  * have been affected.
270  *
271  * @param longestTotalRun Maximum number of steps to execute.
272  */
273  void Execute(const int longestTotalRun = 100000);
274 
275  /**
276  * \brief Dump a list to stdout with all available machine templates.
277  */
278  static void ListTemplates();
279 
280  /**
281  * \brief Returns the GXemul version string.
282  *
283  * @return A string describing the GXemul version.
284  */
285  static string Version();
286 
287  bool IsTemplateMachine(const string& templateName) const;
288  static void DumpMachineAsHTML(const string& machineName);
289  static void GenerateHTMLListOfComponents(bool machines);
290 
291 private:
292  /**
293  * \brief Creates an emulation setup from a template machine name.
294  *
295  * @param templateName The name of the template machine.
296  * @return True if the emulation was created, false otherwise.
297  */
298  bool CreateEmulationFromTemplateMachine(const string& templateName);
299 
300  /**
301  * \brief Prints help message to std::cout.
302  */
303  void PrintUsage() const;
304 
305  /**
306  * \brief Sets the current step of the emulation.
307  *
308  * @param step The number of steps.
309  */
310  void SetStep(uint64_t step);
311 
312  /**
313  * \brief Takes a snapshot of the full emulation state.
314  */
315  void TakeSnapshot();
316 
317 
318  /********************************************************************/
319 public:
320  static void RunUnitTests(int& nSucceeded, int& nFailures);
321 
322 private:
323  // Base:
324  bool m_quietMode;
325  refcount_ptr<UI> m_ui;
326  CommandInterpreter m_commandInterpreter;
327  vector<string> m_onResetCommands;
328 
329  // Runtime:
330  RunState m_runState;
331  bool m_interrupting;
332  uint64_t m_nrOfSingleStepsLeft;
333 
334  // Performance measurement:
335  struct timeval m_lastOutputTime;
336  uint64_t m_lastOutputStep;
337 
338  // Model:
339  string m_emulationFileName;
340  refcount_ptr<Component> m_rootComponent;
341 
342  // Snapshotting: TODO: Multiple snapshots!
343  bool m_snapshottingEnabled;
344  refcount_ptr<Component> m_snapshot;
345 };
346 
347 #endif // GXEMUL_H
GXemul::SetSnapshottingEnabled
void SetSnapshottingEnabled(bool enabled)
Sets whether or not to use snapshots.
Definition: GXemul.cc:778
GXemul::Running
@ Running
Definition: GXemul.h:61
GXemul::IsInterrupting
bool IsInterrupting() const
Returns whether or not the current emulation is being interrupted.
Definition: GXemul.h:178
GXemul::ParseFilenames
bool ParseFilenames(string templateMachine, int filenameCount, char *filenames[])
Parses command line arguments (file names).
Definition: GXemul.cc:427
GXemul::GetSnapshottingEnabled
bool GetSnapshottingEnabled() const
Checks whether snapshots are currently enabled or not.
Definition: GXemul.cc:772
GXemul
The main emulator class.
Definition: GXemul.h:54
GXemul::SetNrOfSingleStepsInARow
void SetNrOfSingleStepsInARow(uint64_t steps)
Sets the nr of single-steps to perform in a row.
Definition: GXemul.cc:800
GXemul::ClearEmulation
void ClearEmulation()
Discards the current emulation, and starts anew with just an empty root component.
Definition: GXemul.cc:192
GXemul::GetCommandInterpreter
CommandInterpreter & GetCommandInterpreter()
Gets a reference to the CommandInterpreter.
Definition: GXemul.cc:631
GXemul::Quitting
@ Quitting
Definition: GXemul.h:62
refcount_ptr< Component >
GXemul::Run
int Run()
Runs GXemul's main loop.
Definition: GXemul.cc:557
GXemul::InitUI
void InitUI()
Initializes the UI.
Definition: GXemul.cc:545
GXemul::IsTemplateMachine
bool IsTemplateMachine(const string &templateName) const
Definition: GXemul.cc:204
UI.h
UI
Base class for a User Interface.
Definition: UI.h:40
GXemul::GetRootComponent
refcount_ptr< Component > GetRootComponent()
Gets a pointer to the root configuration component.
Definition: GXemul.cc:667
GXemul::SetRunState
void SetRunState(RunState newState)
Sets the RunState.
Definition: GXemul.cc:741
misc.h
GXemul::SetEmulationFilename
void SetEmulationFilename(const string &filename)
Sets the current emulation setup's filename.
Definition: GXemul.cc:623
GXemul::GetRunStateAsString
string GetRunStateAsString() const
Gets the current RunState as a string.
Definition: GXemul.cc:755
GXemul::Execute
void Execute(const int longestTotalRun=100000)
Run the emulation for "a while".
Definition: GXemul.cc:894
GXemul::ModifyStep
bool ModifyStep(int64_t oldStep, int64_t newStep)
Change step either forwards or backwards.
Definition: GXemul.cc:809
GXemul::GXemul
GXemul()
Creates a GXemul instance.
Definition: GXemul.cc:175
Component.h
GXemul::Reset
bool Reset()
Resets the emulation.
Definition: GXemul.cc:700
GXemul::ListTemplates
static void ListTemplates()
Dump a list to stdout with all available machine templates.
Definition: GXemul.cc:239
GXemul::GetRunState
RunState GetRunState() const
Gets the current RunState.
Definition: GXemul.cc:749
GXemul::SetQuietMode
void SetQuietMode(bool quietMode)
Sets whether or not to run in quiet mode.
Definition: GXemul.cc:794
CommandInterpreter
An interactive command interpreter, which run Commands.
Definition: CommandInterpreter.h:48
GXemul::GenerateHTMLListOfComponents
static void GenerateHTMLListOfComponents(bool machines)
Definition: GXemul.cc:279
GXemul::GetUI
UI * GetUI()
Gets a pointer to the GXemul instance' active UI.
Definition: GXemul.cc:661
GXemul::Paused
@ Paused
Definition: GXemul.h:59
GXemul::SingleStepping
@ SingleStepping
Definition: GXemul.h:60
GXemul::GetStep
uint64_t GetStep() const
Gets the current step of the emulation.
Definition: GXemul.cc:637
GXemul::DumpMachineAsHTML
static void DumpMachineAsHTML(const string &machineName)
Definition: GXemul.cc:266
GXemul::GetEmulationFilename
const string & GetEmulationFilename() const
Gets the current emulation setup's filename.
Definition: GXemul.cc:617
CommandInterpreter.h
GXemul::RunState
RunState
Definition: GXemul.h:57
GXemul::Version
static string Version()
Returns the GXemul version string.
Definition: GXemul.cc:509
GXemul::SetRootComponent
void SetRootComponent(refcount_ptr< Component > newRootComponent)
Sets the root component, discarding the previous one.
Definition: GXemul.cc:679
GXemul::GetQuietMode
bool GetQuietMode() const
Gets the current quiet mode setting.
Definition: GXemul.cc:788
GXemul::Interrupt
void Interrupt()
Interrupts emulation.
Definition: GXemul.cc:728
GXemul::RunUnitTests
static void RunUnitTests(int &nSucceeded, int &nFailures)

Generated on Tue Mar 24 2020 14:04:48 for GXemul by doxygen 1.8.17