{"id":26210449,"url":"https://github.com/drguildo/tecs","last_synced_at":"2025-07-23T17:05:33.186Z","repository":{"id":66655545,"uuid":"1925635","full_name":"drguildo/tecs","owner":"drguildo","description":"An Eclipse project of the source code for the software that comes with The Elements of Computing Systems, along with bug fixes.","archived":false,"fork":false,"pushed_at":"2011-06-29T00:06:39.000Z","size":496,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2023-04-13T10:36:13.704Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.idc.ac.il/tecs/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drguildo.png","metadata":{"files":{"readme":"Readme.txt","changelog":"ChangeLog.txt","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-06-20T20:18:55.000Z","updated_at":"2014-03-17T00:35:43.000Z","dependencies_parsed_at":"2023-02-20T08:31:05.336Z","dependency_job_id":null,"html_url":"https://github.com/drguildo/tecs","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drguildo%2Ftecs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drguildo%2Ftecs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drguildo%2Ftecs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drguildo%2Ftecs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drguildo","download_url":"https://codeload.github.com/drguildo/tecs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243176696,"owners_count":20248711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-12T07:29:11.322Z","updated_at":"2025-03-12T07:29:11.863Z","avatar_url":"https://github.com/drguildo.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"The contents of this file are subject to the GNU General Public License\r\n(GPL) Version 2 or later (the \"License\"); you may not use this file except\r\nin compliance with the License. You may obtain a copy of the License at\r\nhttp://www.gnu.org/copyleft/gpl.html\r\n\r\nSoftware distributed under the License is distributed on an \"AS IS\" basis,\r\nwithout warranty of any kind, either expressed or implied. See the License\r\nfor the specific language governing rights and limitations under the\r\nLicense.\r\n\r\nThis file was originally developed as part of the software suite that\r\nsupports the book \"The Elements of Computing Systems\" by Nisan and Schocken,\r\nMIT Press 2005. If you modify the contents of this file, please document and\r\nmark your changes clearly, for the benefit of others.\r\n\r\n\r\nThe Chip API for Implementation of Chips in Java\r\n------------------------------------------------\r\n\r\nThe TECS Software Suite allows the implementation in Java of new chips for\r\nuse with the Hardware Simulator via the Chip API which is henceforth described.\r\nThis feature allows both the ability to achieve greater simulation speed and\r\nthe ability to provide students with working chips without disclosing their\r\nimplementation.\r\n\r\nIt is strongly advised, before implementing a chip, to browse through the\r\nimplementations of chips provided with the TECS Software Suite. The HDL\r\nfiles of these chips are located under the InstallDir/builtInChips directory\r\nand Java sources for these chips - under the BuiltInChipsSource directory.\r\n\r\nThe input and output pins for each chip are specified by an HDL file for\r\nthe chip which should bare the name of the chip followed by a .hdl suffix\r\nand be located in the InstallDir/builtInChips directory.\r\nThe HDL should be formed like a normal HDL file (see the Hardware Simulator\r\nTutorial at the TECS site) and specify the chip name and all the input and\r\noutput pins in the usual manner. Instead of the list of gates which usually\r\ncomprise the implementation, the line:\r\nBUILTIN ChipName;\r\nshould appear (where ChipName should be substituted for the name of the chip).\r\n\r\nIn addition to the HDL file for the chip, each chip should be implemented in a\r\nseparate class named the same as the chip. The compiled implementation should\r\nreside in the builtInChips package somewhere in the CLASSPATH (for example\r\nthe compiled counterparts of the aforementioned chip provided with the TECS\r\nSoftware Suite are located under the InstallDir/builtInChips directory).\r\n\r\nThe chip class should extend (either directly or indirectly) the\r\nHack.Gates.BuiltInGate class and may overwrite any of the following three\r\nmethods (which by default do nothing):\r\nvoid clockUp() - called when the clock goes up (useful for clocked chips)\r\nvoid clockDown() - called when the clock goes down (useful for clocked chips)\r\nvoid reCompute() - called whenever any of the input pins changes\r\n                   (useful for combinatorial chips)\r\nRequired initialization code may be placed in a constructor accepting no\r\narguments and any number of data members may be defined.\r\n\r\nThe code for the chip may access the input and output pins via the data members\r\ninputPins and outputPins, respectively.\r\n\r\nThe value of a b-bit input pin/bus which was declared n-th (starting from zero)\r\nin the chip HDL file can be accessed by evaluating the b least significant bits\r\nof the value returned by calling inputPins[n].get().\r\n\r\nThe value of a b-bit output pin/bus which was declared n-th (starting from zero)\r\nin the chip HDL file can be updated to v (a value in which all but the v least\r\nsignificant bits are zero) by calling outputPins[n].set(v).\r\n\r\nThe TECS Software Suite Hardware Simulator Chip Java API also provides support\r\nfor implementing a GUI visualization of the chip (similar to the one\r\nimplemented by the provided ALU, RAM*, ROM32K, ARegister and DRegister chips).\r\nImplementing chips should extend the Hack.Gates.BuilInGateWithGUI class. See\r\nthe implementations of this class (located in\r\nSimulatorsPackageSource/Hack/Games/BuiltInGateWithGUI.java) and of the\r\naforementioned GUI-powered chips for examples and information regarding\r\nadditional methods which should be implemented by GUI-powered chips.\r\n\r\n\r\nThe VMCode API for Implementation of VM Functions/Classes in Java\r\n-----------------------------------------------------------------\r\n\r\nThe TECS Software Suite allows the implementation in Java of new VM functions\r\nfor use by the VM Emulator via the VMCode API which is henceforth described.\r\nThis feature allows both the ability to achieve much greater simulation speed\r\nand the ability to allow VM programs the access to features which aren't\r\notherwise available or feasible on the Hack platform (such features may\r\ninclude e.g. time \u0026 date queries, random number generation using an RNG daemon\r\nand performing complex calculation using 3rd-party closed libraries).\r\n\r\nWhenever the VM Emulator encounters a call to a VM function with a prefix for\r\nwhich the current program doesn't contain a *.vm implementation (e.g. a call\r\nto \"Screen.drawPixel\" when the current program doesn't contain a file called\r\nScreen.vm), the VM Emulator will invoke the Java implementation for that VM\r\nfunction, if such an implementation exists. This priority mechanism is similar\r\nto the priority mechanism of the Chip API in the Hardware Simulator.\r\nSince this mechanism is not discussed in the book, a dialog will pop up to\r\nconfirm the usage of Java implementation of VM functions upon loading of a\r\nprogram in which such usage is required.\r\n\r\nIt is strongly advised, before implementing a new VM function, to browse\r\nthrough the implementation of the Jack OS provided with the TECS Software Suite.\r\nThe Java sources for this implementation are located under the\r\nBuiltInVMCodeSource directory.\r\n\r\nIt should be noted that since the VMCode API allows the implementation of\r\nfunctions in the VM level and not in the Jack level, there is no concept of\r\nconstructors or methods in this API but only a concept of functions. Functions\r\nmay conceptually be class methods and therefore receive a this-style pointer\r\nas the first argument (e.g., as the String.* functions do) or may conceptually\r\nbe class constructors which return a this-style pointer which they allocated\r\nand initialized (e.g. as the String.new function does) but may conceptually\r\nbe mere functions or static methods (e.g., as the Output.* functions are).\r\n\r\nEach VM function is implemented by a single Java static method. Since all\r\nVM data is 16-bit quantities and Java shorts are 16-bit quantities, all of the\r\narguments to the static method should be Java shorts. For convenience, the\r\nstatic method may return void (a value of 0 will be returned to the calling\r\nfunction), boolean (false will be converted to 0, true to 0xffff), char (will\r\nbe cast to short and returned) or short.\r\n\r\nAs with normal .vm files (see the VM Emulator Tutorial at the TECS site), all\r\nVM functions which start with the same prefix (e.g., all VM functions which\r\nimplement methods, constructors and functions of the same Jack class) are\r\nimplemented together. In the case of normal .vm files, all such functions are\r\nimplemented in a single file baring the prefix (e.g., the class name) as its\r\nname and therefore all such function share the same static segment. In the\r\ncase of Java-implemented VM functions, all such functions are implemented by\r\nstatic methods of a single class baring the prefix as its name and therefore\r\nmay share data using static variables of the class.\r\n\r\nThe compiled class should extend (either directly or indirectly) the\r\nHack.VMEmulator.BuiltInVMClass class and should reside in the builtInVMCode\r\npackage somewhere in the CLASSPATH (for example the compiled classes\r\nimplementing the Jack OS provided with the TECS Software Suite are located\r\nunder the InstallDir/builtInVMCode directory).\r\n\r\nA Java static method which implements a VM function may communicate with the\r\nVirtual Machine using any of the following static methods which it inherits from\r\nHack.VMEmulator.BuiltInVMClass:\r\nshort readMemory(int address) - returns the value stored in the VM\r\n                                memory at the given address (the address\r\n                                argument is an int and not a short for\r\n                                convenience but may only be in the one of the\r\n                                ranges HEAP_START_ADDRESS - HEAP_END_ADDRESS or\r\n                                SCREEN_START_ADDRESS - SCREEN_END_ADDRESS\r\n                                (these are provided as static final constants\r\n                                of the Hack.VMEmulator.BuiltInVMClass).\r\nvoid writeMemory(int address, int value) - changes the value stored in the VM\r\n                                           memory at the given address (the\r\n                                           value is cast to short and the\r\n                                           address must be legal - see above).\r\n                                           If data flow animation is on, the\r\n                                           change in the VM memory will be\r\n                                           animated.\r\nshort callFunction(String functionName,\r\n                   short[] params) - Calls the named VM function (which may\r\n                                     be either be implemented in a normal .vm\r\n                                     files or in Java using the VMCode API)\r\n                                     with the given parameters. The return\r\n                                     from the function is returned. To allow\r\n                                     for maximum modularity, this function\r\n                                     should be used for all calls to VM\r\n                                     functions not implemented by the current\r\n                                     class, to ensure that the implementation\r\n                                     currently used by the VM Emulator (which\r\n                                     may or may not be implemented in Java) is\r\n                                     called.\r\nshort callFunction(String functionName,\r\n                   short param1, ...) - For convenience, versions of the\r\n                                        callFunction method are supplied for\r\n                                        calling VM functions accepting 0-4\r\n                                        arguments without the need to allocate\r\n                                        an array of parameters.\r\nvoid infiniteLoop(String message) - Used to halt the VM program (this is the\r\n                                    function called by the supplied Java\r\n                                    implementation of the Sys.halt function\r\n                                    of the Jack OS). If the optional message\r\n                                    is provided (non-null) then a pop-up\r\n                                    window is opened to display it.\r\n                                    * Important: A Java static method\r\n                                    implementing a VM function SHOULD NOT enter\r\n                                    a blocking infinite loop *\r\n\r\nA function calling any of the aforementioned static methods must be declared\r\nto throw Hack.VMEmulator.TerminateVMProgramThrowable. An instance of this\r\nThrowable class will be thrown by any of the aforementioned static methods\r\nif the user decides to restart the VM program (e.g. via the \u003c\u003c button). This\r\nthrowable may be caught by the calling method but must be re-thrown.\r\n\r\nFor convenience, the following constants are provided by the\r\nHack.VMEmulator.BuiltInVMClass for use by the classes which extend it:\r\nshort SCREEN_START_ADDRESS\r\nshort SCREEN_END_ADDRESS\r\nint SCREEN_WIDTH\r\nint SCREEN_HEIGHT\r\nshort HEAP_START_ADDRESS\r\nshort HEAP_END_ADDRESS\r\nshort KEYBOARD_ADDRESS\r\nshort NEWLINE_KEY\r\nshort BACKSPACE_KEY\r\n\r\nFinally, it should be noted that the Java language does not allow the\r\ndeclaration of a method called \"new\" (such as the String.new and Array.new\r\nconstructors from the Jack OS). The implementation of such VM functions using\r\nthe VMCode API is achieved by implementing a static Java method called \"NEW\"\r\n(all capitals) - the VM Emulator will call the \"NEW\" function whenever it\r\nreceives a request for calling the \"new\" function.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrguildo%2Ftecs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrguildo%2Ftecs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrguildo%2Ftecs/lists"}