summaryrefslogtreecommitdiff
path: root/src/main/resources/emulator_api.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/main/resources/emulator_api.h')
-rw-r--r--src/main/resources/emulator_api.h684
1 files changed, 684 insertions, 0 deletions
diff --git a/src/main/resources/emulator_api.h b/src/main/resources/emulator_api.h
new file mode 100644
index 00000000..38b50963
--- /dev/null
+++ b/src/main/resources/emulator_api.h
@@ -0,0 +1,684 @@
+// Header for Chisel emulator API
+#ifndef __IS_EMULATOR_API__
+#define __IS_EMULATOR_API__
+
+#include "emulator_mod.h"
+
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wunused-function"
+#pragma GCC diagnostic ignored "-Wsign-compare"
+#pragma GCC diagnostic ignored "-Wunused-parameter"
+#pragma GCC diagnostic ignored "-Wunused-variable"
+
+#include <string>
+#include <sstream>
+#include <map>
+#include <cassert>
+#include <cerrno>
+
+/**
+ * Converts an integer to a std::string without needing additional libraries
+ * or C++11.
+ */
+static std::string itos(int in) {
+ std::stringstream out;
+ out << in;
+ return out.str();
+}
+
+/**
+ * Copy one val_t array to another.
+ * nb must be the exact number of bits the val_t represents.
+ */
+static __attribute__((unused)) void val_cpy(val_t* dst, val_t* src, int nb) {
+ for (int i=0; i<val_n_words(nb); i++) {
+ dst[i] = src[i];
+ }
+}
+
+/**
+ * Empty a val_t array (sets to zero).
+ * nb must be the exact number of bits the val_t represents.
+ */
+static void val_empty(val_t* dst, int nb) {
+ for (int i=0; i<val_n_words(nb); i++) {
+ dst[i] = 0;
+ }
+}
+
+/**
+ * Set a val_t array to a integer number. Obviously, the maximum integer
+ * is capped by the width of a single val_t element.
+ * nb must be the exact number of bits the val_t represents.
+ */
+static __attribute__((unused)) void val_set(val_t* dst, val_t nb, val_t num) {
+ val_empty(dst, nb);
+ dst[0] = num;
+}
+
+/**
+ * Sets a dat_t from a string, where the input radix is automatically determined
+ * from the string (or defaults to 10).
+ * Returns true on success.
+ */
+template <int w>
+bool dat_from_str(std::string in, dat_t<w>& res, int pos = 0) {
+ int radix = 10;
+ int negate = 0;
+
+ /* Handle leading minus sign. */
+ if (!in.substr(pos, 1).compare("-")) {
+ pos++;
+ negate = 1;
+ }
+
+ if (!in.substr(pos, 1).compare("d")) {
+ radix = 10;
+ pos++;
+ } else if (!in.substr(pos, 1).compare("h")
+ || !in.substr(pos, 1).compare("x")) {
+ radix = 16;
+ pos++;
+ } else if (!in.substr(pos, 2).compare("0h")
+ || !in.substr(pos, 2).compare("0x")) {
+ radix = 16;
+ pos += 2;
+ } else if (!in.substr(pos, 1).compare("b")) {
+ radix = 2;
+ pos++;
+ } else if (!in.substr(pos, 2).compare("0b")) {
+ radix = 2;
+ pos += 2;
+ }
+
+ const int log_max_radix = 4;
+ assert(radix <= (1 << log_max_radix));
+
+ dat_t<w> curr_base = 1;
+ res = 0;
+
+ for (int rpos=in.length()-1; rpos>=pos; rpos--) {
+ char c = in[rpos];
+ val_t c_val = 0;
+ if (c == '_') {
+ continue;
+ }
+ if (c >= '0' && c <= '9') {
+ c_val = c - '0';
+ } else if (c >= 'a' && c <= 'z') {
+ c_val = c - 'a' + 10;
+ } else if (c >= 'A' && c <= 'Z') {
+ c_val = c - 'A' + 10;
+ } else {
+ std::cerr << "dat_from_str: Invalid character '" << c << "' in '" << in << "'" << std::endl;
+ return false;
+ }
+ if (c_val > radix /* || c_val < 0 */) {
+ std::cerr << "dat_from_str: Invalid character '" << c << "'" <<
+ std::endl;
+ return false;
+ }
+
+ dat_t<w> temp_prod = curr_base * dat_t<log_max_radix>(c_val);
+ res = res + temp_prod;
+ curr_base = curr_base * dat_t<log_max_radix+1>(radix);
+ }
+ if (negate) {
+ res = -res;
+ }
+ return true;
+}
+
+// API base class, providing common functions
+class api_base {
+public:
+ api_base(const char* new_name, const char* new_path) :
+ name(new_name),
+ path(new_path)
+ {}
+ // returns the fully qualified name of this object (path + dot + name)
+ std::string get_pathname() {
+ if (*path == '\0') {
+ return name;
+ } else {
+ return get_path() + "." + name;
+ }
+ }
+ // returns the short name of this object
+ std::string get_name() {
+ return name;
+ }
+ // returns the path of this object (without a trailing dot)
+ std::string get_path() {
+ return path;
+ }
+protected:
+ const char* name;
+ const char* path;
+};
+
+// API base (non width templated) class for API accessors to dat_t
+class dat_api_base : public api_base {
+public:
+ dat_api_base(const char* new_name, const char* new_path) :
+ api_base(new_name, new_path)
+ {}
+ // returns the value of this wire as a string, or empty string on failure
+ virtual std::string get_value() = 0;
+ // sets the value of this wire from a string, returning true on success
+ virtual bool set_value(std::string value) = 0;
+ // returns the bitwidth of this wire
+ virtual std::string get_width() = 0;
+};
+
+// dat_api dummy class, does nothing except for return errors
+// to be used when a real dat_api object can't be found
+class dat_dummy : public dat_api_base {
+public:
+ dat_dummy() :
+ dat_api_base("error", "")
+ {}
+ std::string get_value() {
+ return "error";
+ }
+
+ bool set_value(std::string value) {
+ return false;
+ }
+
+ std::string get_width() {
+ return "error";
+ }
+};
+
+template<int w> class dat_api : public dat_api_base {
+public:
+ dat_api(dat_t<w>* new_dat, const char* new_name, const char* new_path) :
+ dat_api_base(new_name, new_path),
+ dat_ptr(new_dat)
+ {}
+
+ std::string get_value() {
+ return dat_ptr->to_str();
+ }
+
+ bool set_value(std::string value) {
+ return dat_from_str<w>(value, *dat_ptr);
+ }
+
+ std::string get_width() {
+ return itos(w);
+ }
+
+protected:
+ dat_t<w>* dat_ptr;
+};
+
+// API base (non width/depth templated) class for API accessors to mem_t
+class mem_api_base : public api_base {
+public:
+ mem_api_base(const char* new_name, const char* new_path) :
+ api_base(new_name, new_path)
+ {}
+ // return the value of an element as a string, or empty string on failure
+ virtual std::string get_element(std::string index) = 0;
+ // sets the value of an element from a string, returning true on success
+ virtual bool set_element(std::string index, std::string value) = 0;
+ // returns the bitwidth of a memory element
+ virtual std::string get_width() = 0;
+ // returns the number of memory elements
+ virtual std::string get_depth() = 0;
+};
+
+// mem_api dummy class, does nothing except for return errors
+// to be used when a real mem_api object can't be found
+class mem_dummy : public mem_api_base {
+public:
+ mem_dummy() :
+ mem_api_base("error", "")
+ {}
+ string get_element(std::string index) {
+ return "error";
+ }
+
+ bool set_element(std::string index, std::string value) {
+ return false;
+ }
+
+ std::string get_width() {
+ return "error";
+ }
+
+ std::string get_depth() {
+ return "error";
+ }
+};
+
+template<int w, int d> class mem_api : public mem_api_base {
+public:
+ mem_api(mem_t<w, d>* new_mem, const char* new_name, const char* new_path) :
+ mem_api_base(new_name, new_path),
+ mem_ptr(new_mem)
+ {}
+
+ string get_element(std::string index) {
+ int index_int = atoi(index.c_str());
+ return mem_ptr->contents[index_int].to_str();
+ }
+
+ bool set_element(std::string index, std::string value) {
+ int index_int = atoi(index.c_str());
+ return dat_from_str<w>(value, mem_ptr->contents[index_int]);
+ }
+
+ std::string get_width() {
+ return itos(w);
+ }
+
+ std::string get_depth() {
+ return itos(d);
+ }
+
+protected:
+ mem_t<w, d>* mem_ptr;
+};
+
+class mod_api_t {
+public:
+ mod_api_t():
+ teefile(NULL)
+ {}
+
+ void init(mod_t* new_module) {
+ module = new_module;
+ init_mapping_table();
+ }
+
+ void set_teefile(FILE* new_teefile) {
+ teefile = new_teefile;
+ }
+
+ mod_t* get_module() {
+ return module;
+ }
+
+ // API basic functions
+ std::string get_host_name() {return "C++ Emulator API";}
+ std::string get_api_version() {return "0";}
+ std::string get_api_support() {return "PeekPoke Introspection";}
+
+ // External access functions & helpers
+ std::vector< std::string > tokenize(std::string str) {
+ std::vector< std::string > res;
+ int i = 0;
+ int c = ' ';
+ while ( i < str.size() ) {
+ while (isspace(c)) {
+ if (i >= str.size()) return res;
+ c = str[i++];
+ }
+ std::string s;
+ while (!isspace(c) && i < str.size()) {
+ s.push_back(c);
+ c = str[i++];
+ }
+ if (i >= str.size()) s.push_back(c);
+ if (s.size() > 0)
+ res.push_back(s);
+ }
+ return res;
+ }
+
+ // helper to verify command length, returning false and printing an error
+ // to stderr if the length isn't in the specified range
+ bool check_command_length(std::vector<std::string>& tokenized_command,
+ int min_args, int max_args=-1) {
+ if (tokenized_command.size() - 1 < min_args) {
+ std::cerr << tokenized_command[0] << " expects at least " << min_args
+ << " args, got " << tokenized_command.size() - 1
+ << std::endl;
+ return false;
+ } else if (max_args >= 0 && tokenized_command.size() - 1 > max_args) {
+ std::cerr << tokenized_command[0] << " expects at most " << max_args
+ << " args, got " << tokenized_command.size() - 1
+ << std::endl;
+ return false;
+ }
+ return true;
+ }
+
+ // Evaluates an API command, returning the reply as a string (without
+ // the trailing newline).
+ // Errors return "error", printing a more detailed description to stderr.
+ // TODO: find a way to pass errors in-line, so transport layers other than
+ // stdin/stdout (like TCP/IP) are possible while also communicating errors.
+ std::string eval_command(string command) {
+ std::vector<std::string> tokens = tokenize(command);
+ if (tokens.size() == 0) {
+ std::cerr << "Empty command: '" << command << "'" << std::endl;
+ return "error";
+ }
+ if (tokens[0] == "get_host_name") {
+ // IN: get_host_name
+ // OUT: API host's name (arbitrary string)
+ if (!check_command_length(tokens, 0, 0)) { return "error"; }
+ return get_host_name();
+ } else if (tokens[0] == "get_api_version") {
+ // BETA FUNCTION: semantics subject to change, use with caution
+ // IN: get_api_version
+ // OUT: API version supported by this host
+ if (!check_command_length(tokens, 0, 0)) { return "error"; }
+ return get_api_version();
+ } else if (tokens[0] == "get_api_support") {
+ // BETA FUNCTION: semantics subject to change, use with caution
+ // IN: get_api_support
+ // OUT: list of supported API features
+ if (!check_command_length(tokens, 0, 0)) { return "error"; }
+ return get_api_support();
+ } else if (tokens[0] == "clock") {
+ // BETA FUNCTION: semantics subject to change, use with caution
+ // IN: clock <num_cycles>
+ // OUT: actual number of cycles stepped
+ if (!check_command_length(tokens, 1, 1)) { return "error"; }
+ int cycles = atoi(tokens[1].c_str());
+ module->propagate_changes();
+ for (int i=0; i<cycles; i++) {
+ module->clock(dat_t<1>(0));
+ }
+ return itos(cycles);
+ } else if (tokens[0] == "tick") {
+ // BETA FUNCTION: semantics subject to change, use with caution
+ // IN: tick
+ // OUT: ok (on success)
+ // Update registers without propagation
+ // updating registers.
+ module->clock_hi(dat_t<1>(0));
+ return "ok";
+ } else if (tokens[0] == "propagate") {
+ // BETA FUNCTION: semantics subject to change, use with caution
+ // IN: propagate
+ // OUT: ok (on success)
+ // This function propagates the combinational logic, without
+ // updating registers.
+ module->propagate_changes();
+ return "ok";
+ } else if (tokens[0] == "step") {
+ // IN: step <num_cycles>
+ // OUT: actual number of cycles stepped
+ if (!check_command_length(tokens, 1, 1)) { return "error"; }
+ int n = atoi(tokens[1].c_str());
+ module->propagate_changes();
+ int ret = module->step(false, n);
+ // Do we have print output to report?
+ int nBytes = module->has_output();
+ if (nBytes > 0) {
+ cout << "PRINT" << " " << nBytes << " " << module->drain_output();
+ }
+ return itos(ret);
+ } else if (tokens[0] == "set_clocks") {
+ // BETA FUNCTION: semantics subject to change, use with caution
+ // IN: set_clocks
+ // OUT: ???
+ // I'm not really sure what this is supposed to do, but it was
+ // in the old command API, so it's here now
+ std::vector< int > periods;
+ for (int i = 1; i < tokens.size(); i++) {
+ int period = atoi(tokens[i].c_str());
+ periods.push_back(period);
+ }
+ module->setClocks(periods);
+ return "ok";
+
+ } else if (tokens[0] == "reset") {
+ // IN: reset <num_cycles>
+ // OUT: actual number of cycles in reset
+ if (!check_command_length(tokens, 0, 1)) { return "error"; }
+ int cycles = 1;
+ if (tokens.size() >= 2) {
+ cycles = atoi(tokens[1].c_str());
+ }
+ for (int i=0; i<cycles; i++) {
+ module->clock_lo(dat_t<1>(1));
+ module->clock_hi(dat_t<1>(1));
+ }
+ module->clock_lo(dat_t<1>(0));
+ return itos(cycles);
+ } else if (tokens[0] == "peek") {
+ // LEGACY FUNCTION: do not use in new code
+ // IN: peek <node_name> | peek <mem_name> <mem_index>
+ // OUT: value
+ if (!check_command_length(tokens, 1, 2)) { return "error"; }
+ cerr << "peek is deprecated, use wire_peek or mem_peek" << std::endl;
+ module->propagate_changes();
+ if (tokens.size() == 2) {
+ return get_dat_by_name(tokens[1])->get_value();
+ } else if (tokens.size() == 3) {
+ return get_mem_by_name(tokens[1])->get_element(tokens[2]);
+ }
+ } else if (tokens[0] == "poke") {
+ // LEGACY FUNCTION: do not use in new code
+ // IN: poke <node_name> <value> | poke <mem_name> <mem_index> <value>
+ // OUT: true (on success), false (on failure)
+ if (!check_command_length(tokens, 2, 3)) { return ""; }
+ cerr << "poke is deprecated, use wire_poke or mem_poke" << std::endl;
+ bool success;
+ if (tokens.size() == 3) {
+ success = get_dat_by_name(tokens[1])->set_value(tokens[2]);
+ } else if (tokens.size() == 4) {
+ success = get_mem_by_name(tokens[1])->set_element(tokens[2], tokens[3]);
+ }
+ std::string result;
+ if (success) {
+ result = "true";
+ module->mark_stale();
+ } else {
+ result = "false";
+ }
+ return result;
+ } else if (tokens[0] == "wire_peek") {
+ // IN: wire_peek <node_name>
+ // OUT: value
+ if (!check_command_length(tokens, 1, 1)) { return "error"; }
+ module->propagate_changes();
+ return get_dat_by_name(tokens[1])->get_value();
+ } else if (tokens[0] == "wire_poke") {
+ // IN: wire_poke <node_name> <value>
+ // OUT: ok (on success)
+ if (!check_command_length(tokens, 2, 2)) { return "error"; }
+ bool success = get_dat_by_name(tokens[1])->set_value(tokens[2]);
+ std::string result;
+ if (success) {
+ result = "ok";
+ module->mark_stale();
+ } else {
+ result = "error";
+ }
+ return result;
+ } else if (tokens[0] == "mem_peek") {
+ // IN: mem_peek <mem_name> <mem_index>
+ // OUT: value
+ if (!check_command_length(tokens, 2, 2)) { return "error"; }
+ module->propagate_changes();
+ return get_mem_by_name(tokens[1])->get_element(tokens[2]);
+ } else if (tokens[0] == "mem_poke") {
+ // IN: mem_poke <mem_name> <mem_index> <value>
+ // OUT: ok (on success)
+ if (!check_command_length(tokens, 3, 3)) { return "error"; }
+ bool success = get_mem_by_name(tokens[1])->set_element(tokens[2], tokens[3]);
+ std::string result;
+ if (success) {
+ result = "ok";
+ module->mark_stale();
+ } else {
+ result = "error";
+ }
+ return result;
+ return success ? "ok" : "error";
+ } else if (tokens[0] == "trace") {
+ // IN: trace n <node_name>+
+ // OUT: values
+ // TODO: ADD MEM PEEK SUPPORT
+ stringstream ss;
+ if (!check_command_length(tokens, 2)) { return "bad"; }
+ int n = atoi(tokens[1].c_str());
+ for (int t = 0; t < n; t++) {
+ for (int i = 2; i < tokens.size(); i++)
+ ss << " " << get_dat_by_name(tokens[i])->get_value();
+ int ret = module->step(false, 1);
+ // if (!ret)
+ // return "error";
+ }
+ return ss.str();
+ } else if (tokens[0] == "list_wires") {
+ // IN: list_wires
+ // OUT: list of wires
+ if (!check_command_length(tokens, 0, 0)) { return "error"; }
+ std::string out = "";
+ for (std::map<const char*, dat_api_base*>::iterator it = dat_table.begin(); it != dat_table.end(); it++) {
+ out = out + it->second->get_pathname() + " ";
+ }
+ if (out.size() >= 1) {
+ return out.substr(0, out.size() - 1);
+ } else {
+ return "";
+ }
+ } else if (tokens[0] == "list_mems") {
+ // IN: list_mems
+ // OUT: list of memories
+ if (!check_command_length(tokens, 0, 0)) { return "error"; }
+ std::string out = "";
+ for (std::map<const char*, mem_api_base*>::iterator it = mem_table.begin(); it != mem_table.end(); it++) {
+ out = out + it->second->get_pathname() + " ";
+ }
+ if (out.size() >= 1) {
+ return out.substr(0, out.size() - 1);
+ } else {
+ return "";
+ }
+ } else if (tokens[0] == "wire_width") {
+ // IN: wire_width <node>
+ // OUT: bitwidth of wire
+ if (!check_command_length(tokens, 1, 1)) { return "error"; }
+ return get_dat_by_name(tokens[1])->get_width();
+ } else if (tokens[0] == "mem_width") {
+ // IN: mem_width <node>
+ // OUT: bitwidth of memory element
+ if (!check_command_length(tokens, 1, 1)) { return "error"; }
+ return get_mem_by_name(tokens[1])->get_width();
+ } else if (tokens[0] == "mem_depth") {
+ // IN: mem_depth <node>
+ // OUT: elements in memory
+ if (!check_command_length(tokens, 1, 1)) { return "error"; }
+ return get_mem_by_name(tokens[1])->get_depth();
+ } else if (tokens[0] == "referenced_snapshot_save") {
+ // BETA FUNCTION: semantics subject to change, use with caution
+ // IN: referenced_snapshot_save <name>
+ // OUT: Reference name (an arbitrary string) for saved snapshot
+ // of current state, should be equivalent to the input.
+ // Caution: the state may not be self-consistent (i.e. clk_lo
+ // does not need to have been applied before this, and calls to
+ // clk_lo immediately after restoring may change the state).
+ if (!check_command_length(tokens, 1, 1)) { return "error"; }
+ module->propagate_changes();
+ mod_t *snapshot = module->clone();
+ snapshot_table[tokens[1]] = snapshot;
+ return tokens[1];
+ } else if (tokens[0] == "referenced_snapshot_restore") {
+ // BETA FUNCTION: semantics subject to change, use with caution
+ // IN: referenced_snapshot_restore <name>
+ // OUT: ok (on success)
+ if (!check_command_length(tokens, 1, 1)) { return "error"; }
+ mod_t *snapshot = get_snapshot_by_reference(tokens[1]);
+ if (snapshot == NULL) { return "error"; }
+ bool success = module->set_circuit_from(snapshot);
+ std::string result;
+ if (success) {
+ result = "ok";
+ module->mark_stale();
+ } else {
+ result = "error";
+ }
+ return result;
+ } else {
+ std::cerr << "Unknown command: '" << tokens[0] << "'" << std::endl;
+ }
+ return "error";
+ }
+
+ void read_eval_print_loop() {
+ while (true) {
+ std::string str_in;
+ do {
+ std::getline(cin, str_in);
+ } while (cin.fail() && errno == EINTR);
+
+ if (!cin.good()) {
+ break;
+ }
+
+ if (teefile != NULL) {
+ fprintf(teefile, "%s\n", str_in.c_str());
+ fflush(teefile);
+ }
+ if (str_in == "quit") {
+ break;
+ } else {
+ cout << eval_command(str_in) << std::endl;
+ }
+ }
+ }
+
+protected:
+ FILE* teefile;
+ mod_t* module;
+
+ // Mapping table functions
+ virtual void init_mapping_table() = 0;
+
+ dat_api_base* get_dat_by_name(std::string name) {
+ if (dat_table.find(name.c_str()) != dat_table.end()) {
+ return dat_table[name.c_str()];
+ } else {
+ std::cerr << "Unable to find dat '" << name << "'" << std::endl;
+ return &this_dat_dummy;
+ }
+ }
+ mem_api_base* get_mem_by_name(std::string name) {
+ if (mem_table.find(name.c_str()) != mem_table.end()) {
+ return mem_table[name.c_str()];
+ } else {
+ std::cerr << "Unable to find mem '" << name << "'" << std::endl;
+ return &this_mem_dummy;
+ }
+ }
+
+ mod_t* get_snapshot_by_reference(std::string name) {
+ if (snapshot_table.find(name) != snapshot_table.end()) {
+ return snapshot_table[name];
+ } else {
+ std::cerr << "Unable to find snapshot reference '" << name << "'" << std::endl;
+ return NULL;
+ }
+ }
+
+ class string_comparator {
+ public:
+ bool operator()(const char* x, const char* y) const {
+ return strcmp(x, y) < 0;
+ }
+ };
+
+ std::map<const char*, dat_api_base*, string_comparator> dat_table;
+ std::map<const char*, mem_api_base*, string_comparator> mem_table;
+ // TODO: replace the dummy with explicit NULL checks - this is simple
+ // but a bit inelegant
+ dat_dummy this_dat_dummy;
+ mem_dummy this_mem_dummy;
+
+ // Snapshot functions
+ std::map<std::string, mod_t*> snapshot_table;
+};
+
+#pragma GCC diagnostic pop
+
+#endif
generated by cgit v1.2.3 (git 2.25.1) at 2026-02-05 10:00:21 +0000