Witch On A Board

From witch-e.org
Jump to: navigation, search

Contents to the following article is actively being added and improved. Please note that the possibility of errors creeping in is very high at this stage


Witch On A Board started as a Google Summer Of Code 2015 project which uses the MinnowBoard Max as the base for creating an unique replica of the WITCH. This project is another attribute of the witch-e project which aims to use the Harwell WITCH as an effective educational tool for children.

The google student working on the project is Don Dennis (metastableB) mentored by David Anders (prpplague) and Tom King (ka6sox).

For more information about the working of the WITCH visit here

The Simulator[edit]

Introduction[edit]

The simulator currently is C++ based command line utility. It can accept programs on text files as well as individual commands. The interface allows a variety of operations which can be used to edit and change the internal state of the WITCH, view the states, and so forth. The simulator is hosted on github : WITCH_On_A_Board.

Installation[edit]

Requirements[edit]

Linux[edit]
  • make
  • g++ 4.8.4 or higher

You need GNU make to build from source. make is generally included in the default package set. Alternatively you can download make from here in case you don't have it.

We also recommend g++ 4.8.4 or higher with c++11 support. Other compilers have not been tested and might not produce proper results.

Building The Simulator[edit]

Fetch the source code from github using git clone. Use

   $ git clone https://github.com/metastableB/WITCH_On_A_Board.git WITCH_On_A_Board

to clone the repository to WITCH_On_A_Board folder.

Alternatively you can download the zip archive from the github repository and extract it to a folder of your choice.

Use make to build the files. That is, within the directory , type

   $ make 

to build the files. To run the files, from the project directory, type

   $ ./bin/witch_sim

make creates the executable with the name witch_sim in the bin folder.

Make accepts the following command line arguments.

  • debug=1
  • log=1

debug=1turns on debug messages for the simulator. These are echoed to stderr by default. You can redirect them using regular terminal redirection

   $ ./bin/witch_sim 2>FILE_FOR_DEBUG_MESSAGES

log=1turns on the log messages similar to debug=1 above.

This information is also included in the README.md file.

Building Test Suits[edit]

The make also allows you to run tests against the existing source code. This might help when you are hacking the source files.

To run all the tests, use

   $ make testAll debug=1 log=1

You can also choose to run tests only for particular units of the WITCH like the accumulator or ALU specifically. The general command to use is

   make COMPONENET_NAME  debug=1 log=1

Where the component name is given in the following table.

Testing Components
Component to test COMPONENT_NAME
Dekatron testDekatron
Dekatron Store testDekatronStore
Transfer Unit testTransferUnit
Shift Circuit testShiftCircuit
Accumulator testAccumulator
ALU testALU
Interactive ALU Ops ui_alu
Clean Tests cleanTests

make cleanTests can be used to clean all the test files and ui_alu can be used to perform arithmetic operations.


Commands[edit]

Strings included is '{' and '}' are aliases for the mentioned command.

Running Programs[edit]

inp[edit]

   $ inp INPUT_FILE [OUTPUT_FILE]

INPUT_FILE specifying path to Input file on disk. The file can only contain instructions, input numbers, or block marking character. At most one of any of them are allowed per line.

If an OUTPUT_FILE is specified, the output will be written to it. If no file is specified, standard output will be used.

run[edit]

   $ run {r}

Starts running the program till end/warning is reached. The input file should be preloaded using 'inp' before using this command.

continue[edit]

   $ continue {c} 

Continue program from previously paused state till an alarm/finish/break point is reached.

order[edit]

   $ order {c} ORDER

Execute the ORDER specified. The order should be a valid WITCH order. Which generally is a 5 digit number.

Modifying Internal Values[edit]

set[edit]

   $ set STORE_INDEX VALUE 

Sets the value at the store specified by STORE_INDEX to VALUE. Both STORE_INDEX and VALUE have to be valid according to the following rules:

STORE_INDEX : The original WITCH had 90 stores, indexed from 10 to 99,though WITCH was never built to its full capacity. Hence, we restrict the number of stores you can index by defining two parameters: NO_OF_STORE_ROW and NO_OF_STORE_COL defined in definitions file. The default values are 10 for each of them.

The STORE_INDEX should be two digit numbers such that the first digit represents the store row and lies in [1, NO_OF_STORE_ROW], and the second digit represents the column which should be in [0, NO_OF_STORE_COL]

VALUE  : Value can be in the two forms. A + or - sign followed by 8 an 8 digit number or an * followed by a 5 digit number.

Viewing contents[edit]

print[edit]

   $ print [-r|d] STORE_INDEX

Prints the value in the store specified by STORE_INDEX to the console. Optional arguments can be used to format the output. The decimal format is the default. -r : Raw - The digits will be printed as they are in the store. -d : Decimal - The values in the store will be printed in human readable decimal format.

Setting Break Points[edit]