params.json

{"name":"Bru","tagline":"A command line electronics simulator, written in Go !","body":"## Introduction\r\nWelcome to Bru's official documentation. If you have been following the Youtube\r\nseries, you will find this document to be completely compatible with it. If you\r\nhaven't been following it, no problems! This document is complete in itself,\r\nyou'll do just fine even if you are new to Bru. This document takes you through\r\nthe whole process, from writing your first bru file, to silumating it.\r\n\r\nInterested? Cool! You've come to the right place.\r\n\r\n## Prerequisites\r\nThere aren't that many prerequisites to Bru. In terms of software, you will\r\nneed to install the Go programming language first. This can be done easily for\r\nany platform, be it Windows, Mac or Gnu/Linux. You can find the instructions\r\nfor installing Go for your system at the link below.\r\n\r\n[Go Programming Language](https://golang.org/dl/)\r\n\r\nThe other software prerequisite for Bru is the Bru source file itself. This can\r\nbe obtained from my GitHub repository.\r\n\r\nYou can download the file in any way you like. If you have Git installed on \r\nyour computer, you can clone the repository using the command given below.\r\n\r\nClone the GitHub repository using : ```git clone https://github.com/ashvin-godbole/bru```\r\n\r\nOnce you have installed Go and downloaded the Bru source code, you're all set.\r\nNow the only other thing that you need is an interest in goofing around with\r\ntool!\r\n\r\n## Bru Project Structure\r\nEvery Bru project consists of HDL files and their corresponding SCRIPT files.\r\nThe HDL files describe the construction of a particular circuit and the SCRIPT\r\nfiles contain the inputs to be provided to the circuits described. These files\r\ndon't require any specific file extensions. This means that you can give these\r\nHDL and SCRIPT files may or may not have any file extension and if they do have\r\nan extension, it may be anything you wish.\r\n\r\nOne thing you need to keep in mind is that all files in your project must be\r\nstored in ONE FOLDER ONLY. This means that you can't, at the moment, segregate\r\nyour HDL and SCRIPT files in their own separate folders. This is a bug that we \r\nmust unfortunately must live with, for now at least.\r\n\r\nSo your folder must look something like this: \r\n\r\n```\r\n- Project Root\r\n    - HDL_FILE_ONE\r\n    - HDL_FILE_TWO\r\n    - SCRIPT_FILE_ONE\r\n    - SCRIPT_FILE_TWO\r\n    - ...\r\n```\r\n\r\n## Bru Hardware Description Language\r\nLike many other tools, Bru uses a flavor of HDL to describe the structure of\r\na circuit. This falvor of HDL is designed to be super simple. There are only 6\r\nkeywords in total in Bru's HDL. They are : *, IN, OUT, CON, END, SIM, CLK. (yes\r\n, the '*' character is a keyword).\r\n\r\nLet's look at a sample HDL file:\r\n```\r\n* nand\r\nIN  i1 i2\r\nOUT o1\r\nCON\r\n    t1 = and(i1, i2)\r\n    o1 = not(t1)\r\nEND\r\n```\r\n(Note: Indentation isn't compulsory, it may be ommited as per your preferences)\r\n\r\nThis is a simple \"nand\" gate in BruHDl. If you have any experience with any\r\nof the other HDLs out there, you may find certain similarities and a LOT of\r\ndifferences when you compare BruHDL with them. Most of the syntax choices\r\nthat have been made for BruHDL have not been chosen for any specific reason,\r\nother than that I felt like implementing it in a certain way to either make\r\nit simpler for you to write in it or to make it simpler for me to write its\r\nimplementation.\r\n\r\n### Syntax\r\nWondering what you just read (above)? No worries! here's an explanation for it.\r\nThe syntax of Bru's HDL is divided into the following sections, roughly:\r\n\r\n* Component Declaration\r\n* Special Flags/Keywords\r\n* The Input and Output specifiers.\r\n* Component design instructions\r\n    \r\nLets look at each one of these one by one.\r\n\r\n#### Component Declaration.\r\nEvery component starts with a '*' followed by the name of the component.\r\nThe name of any component may not have spaces in it. If you want to separate\r\nwords in the name, you may use underscores(_) or pascalCase, but not spaces.\r\nThis section should also always be followed by the components 'definition'\r\nor its 'body'. From the above example, 'nand' may be declared as :\r\n```\r\n* nand\r\n```\r\n\r\n(Note: the space between '*' and the name is just for clarity. You may have as \r\nmany spaces as you want, or even none, after the '*')\r\n\r\n\r\n#### Special Flags/Keywords\r\nBru provides 2 flags/keywords for which tell the simulator different things. \r\nThese flags are :\r\n```\r\n- SIM\r\n- CLK\r\n```\r\n\r\nIf you are designing a component, chances are you want to also simulate it\r\nto check its 'correctness'. Bru allows you to simulate _one component_ per\r\n'run'. To indicate which one of the multiple components you may have in a\r\nfile, you can use the SIM flag. This tag would immediately follow the\r\ndeclaration of the component like so :\r\n```\r\n* nand\r\nSIM\r\n```\r\n\r\nIf you want to indicate to Bru that a particular component is sequential, \r\nnot combinational in nature, you may use the CLK flag. More details on this\r\nflag later. For now, just know that there is another flag. When you use it, \r\nit will look like this :\r\n```\r\n* some_sequential_circuit\r\nCLK\r\n```\r\n\r\nWhat if you want to simulate a sequential component ? Well it's simple.\r\nJust stack the flags after the declaration like so :\r\n```\r\n* some_sequential_circuit\r\nSIM\r\nCLK\r\n```\r\n(Note: The order of flags in not important)\r\n\r\n#### The Input and Output specifiers.\r\nFollowing the optional flags are the INput and OUTput lines. These are very\r\nsimple to understand, other than maybe one case, where you may want one of the\r\ncircuit's outputs to link back into one of its inputs. More on that in a bit.\r\n\r\nFor any component, all its inputs may be specified as a list of SPACE\r\nseparated indentifiers. This list must follow the IN keyword, where 'IN'\r\nhas to be in _UPPERCASE_. For example, for the 'nand' gate we would have\r\n(assuming that the nand gate is a 2 input gate)\r\n```\r\nIN i1 i2\r\n```\r\n(Note: using 'i' followed by a number is a convention that I follow. You may\r\nuse any names for the inputs that you wish, like a, b, inp1, inp2 etc.)\r\n\r\nYou may also use input buffers if the number of inputs is large. This means\r\nthat if you want to represent 2 inputs as a buffer, you may do so like this :\r\n```\r\nIN i[2]\r\n```\r\nand the individual elements of this can be used as you would access the\r\nelements of a zero-indexed array, like so:\r\n```\r\ni[0], i[1]\r\n```\r\n\r\nAll of the aforementioned things can be done the _exact same way for outputs_\r\nusing the OUT keyword.\r\n\r\nAn interesting, but weird case arises if you want to connect the output of\r\na particular component back into one of its inputs. This may be useful when\r\ndesigning sequential circuits like memory elements and such. Bru supports\r\nthis feature too ! If you want to link any output back to any of the inputs\r\nyou can do this :\r\n```\r\nIN i1 (i2|o1)\r\nOUT o1 o2\r\n```\r\n\r\n(Note: the position of (i2|o1) is not fixed. It may occur anywhere within the \r\ninputs list)\r\n\r\n(Note: This feature currently works only on components that are being simulated.\r\nI cannot guarentee that it will work in any other case. This feature is not \r\nmeant to be used very often and is untested. Please think before using this)\r\n\r\n\r\n#### Component design instructions\r\nThis is the last section of a component's definition. The description of how\r\nthe circuit is designed is contained within two keywords, CON and END. For our\r\nexample nand gate, we would have to put the following instructions inside the\r\nCON and END 'tags' or keywords:\r\n```\r\nCON\r\n    t1 = and(i1, i2)\r\n    o1 = not(t1)\r\nEND\r\n```\r\n\r\nIf you feel like doing it all in one line, you can do that as well ! Just do\r\nit like this:\r\n```\r\nCON\r\n    o1 = not(and(i1, i2))\r\nEND\r\n```\r\n\r\nThats it for the HDL ! Let's move on to the Script then !\r\n\r\n## Bru scripts\r\nThe script files in Bru have different syntax when it comes to combinational\r\nand sequential circuits. We'll start with combinational circuit scripts first.\r\n\r\n### Combinational Circuit Scripts\r\nThese scripts are very straightforward. All you need to know to write a script\r\nare the names of the inputs given to the circuit marked with SIM, and the 'call'\r\nkeyword. So for our nand gate, the script would look something like this:\r\n```\r\ni1 = 1\r\ni2 = 1\r\ncall\r\n```\r\n\r\nThis will cause the bru program to print the result of (1 NAND 1) to the\r\nstandard output, your terminal. If you pile up multiple such entries, it will\r\nlook something like this:\r\n```\r\ni1 = 1\r\ni2 = 1\r\ncall\r\n\r\ni1 = 0\r\ni2 = 1\r\ncall\r\n\r\ni1 = 0\r\ni2 = 0\r\ncall\r\n\r\ni1 = 1\r\ni2 = 0\r\ncall\r\n```\r\n\r\nThis is effectively going to print out the truth table for our nand gate.\r\n\r\n### Sequential Circuit Scripts\r\nFor these scripts, there are certain rules that should be kept in mind. One of\r\nthese rules is that any sequential circuit script must start by declaring the \r\nnumber of cycles to simulate the circuit for. This is done by assigning a whole\r\nnumber value (integer >= 0) to the 'dur' property in the script, like so:\r\n```\r\ndur = 5\r\n```\r\n\r\nOnce this is done, you can provide the values for the inputs during different\r\ncycles using the syntax below. It is important to know that if no input is \r\nspecified for a cycle 'n', then the values of the input in cycle 'n-1' are \r\ncarried over to be the values of inputs in cycle 'n'.\r\n```\r\nt = 0 {\r\n    an_input = 1\r\n    another_input = 0\r\n}\r\n\r\n(Note: since there are no inputs specified for t = 1, the inputs for t = 1 will\r\nbe the same as those for t = 0)\r\n\r\nt = 2 {\r\n    an_input = 0\r\n    another_input = 1\r\n}\r\n\r\nt = 3 {\r\n    another_input = 1\r\n}\r\n```\r\n\r\n(Note: since the value of 'an_input' is not provided at t = 3, the value of \r\n'an_input' at t = 3 is taken to be what it was at t = 2, which was 0 in this\r\ncase)\r\n\r\nThat's it ! That's all that there is to Bru ! Now its up to you and your\r\ncreativity to come up with all kinds of different circuits using this tool.","note":"Don't delete this file! It's used internally to help with page regeneration."}