|
| 1 | +<div class="title-block" style="text-align: center;" align="center"> |
| 2 | + |
| 3 | +# Bluespec Compiler - Information for developers |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +</div> |
| 8 | + |
| 9 | +Here you can find documentation on the internal architecture of [BSC](./README.md) |
| 10 | +and other helpful information for people who want to contribute to the source code. |
| 11 | + |
| 12 | +Feel free to ask questions on GitHub (in an Issue or a Discussion) |
| 13 | +or on the [`bsc-dev`](https://groups.io/g/bsc-dev) mailing list. |
| 14 | +The `bsc-dev` list is for questions that are only relevant to developers, |
| 15 | +to keep traffic on the [`b-lang-discuss`](https://groups.io/g/b-lang-discuss) |
| 16 | +mailing list light for people who are just users. |
| 17 | + |
| 18 | +--- |
| 19 | + |
| 20 | +At the moment there is no formal documentation. |
| 21 | +However, there are written responses to questions on GitHub and the mailing lists, |
| 22 | +that can someday be collected and turned into a document. |
| 23 | +The following is a running list of those writings. |
| 24 | + |
| 25 | +### Basics / General info |
| 26 | + |
| 27 | +* [BSC is a series of stages](https://groups.io/g/bsc-dev/message/14) |
| 28 | + * This write-up includes a link to the following (incomplete) |
| 29 | + [diagrams of the BSC stages](https://docs.google.com/document/d/1130fyOsPtS6gMppB6BaO-qVXxzO5b_ha7sXwLdd8Dtg/edit?usp=sharing) |
| 30 | + * See also [this brief breakdown of BSC](https://groups.io/g/b-lang-discuss/message/358) |
| 31 | + by its three internal representations (CSyntax, ISyntax, ASyntax) |
| 32 | + * Briefly on [printing and dumping from BSC and intermediate files](https://groups.io/g/b-lang-discuss/message/356) |
| 33 | +* [More on the stages, the backend split, Bluesim stages, and the structure of Bluesim output](https://github.com/B-Lang-org/bsc/issues/743#issuecomment-2436483892) |
| 34 | +* [The meaning of `.bo` and `.ba` files and compiler flow](https://github.com/B-Lang-org/bsc/discussions/575#discussioncomment-6458212) |
| 35 | +* Hidden flags |
| 36 | + * BSC has a flag `-help-hidden` for developers, |
| 37 | + which shows more information than the `-help` for users |
| 38 | + * Like the LaTeX documentation for flags in the BSC User Guide, |
| 39 | + there is short LaTeX document for hidden flags at BS Inc (called `internal-user-guide`), |
| 40 | + which could become part of a BSC Developer Guide |
| 41 | + |
| 42 | +### Compiling |
| 43 | + |
| 44 | +* See [INSTALL.md](./INSTALL.md) for info on building and installing |
| 45 | +* TBD: Any info on tools, dependencies, and compiling options |
| 46 | + * e.g. individual SMT libraries can be omitted using `STP_STUB=1` or `YICES_STUB=1` |
| 47 | + |
| 48 | +### Testing |
| 49 | + |
| 50 | +* See the test suite's own [README file](./testsuite/README.md) |
| 51 | + |
| 52 | +### BSC stage: Parsing |
| 53 | + |
| 54 | +* [Keyword parsing in BH/Classic](https://github.com/B-Lang-org/language-bh/issues/5#issuecomment-1856814271) |
| 55 | + |
| 56 | +### BSC stage: Type checking |
| 57 | + |
| 58 | +* See the link on the use of SMT solvers, below |
| 59 | + |
| 60 | +### BSC stage: Elaboration |
| 61 | + |
| 62 | +* [How to add a new evaluator primitive to BSC](https://groups.io/g/b-lang-discuss/message/526) |
| 63 | + * specifically how to add a function to get the current module name |
| 64 | +* See the link on the use of SMT solvers, below |
| 65 | + |
| 66 | +### BSC stage: Scheduling |
| 67 | + |
| 68 | +* [Understanding scheduling](https://github.com/B-Lang-org/bsc/discussions/622#discussioncomment-7203579) |
| 69 | +* See the link on the use of SMT solvers, below |
| 70 | + |
| 71 | +### BSC backends / naming |
| 72 | + |
| 73 | +* [Naming conventions in the generated Verilog](https://groups.io/g/b-lang-discuss/topic/106903347) |
| 74 | +* [Verilog/Bluesim "main" and the naming of clock and reset ports](https://groups.io/g/b-lang-discuss/message/606) |
| 75 | + |
| 76 | +### BSC backend: Verilog |
| 77 | + |
| 78 | +* [BSC's deduction of portprops](https://groups.io/g/b-lang-discuss/topic/106516831) |
| 79 | +* [How to use the different Verilog directories (for different synth tools)](https://groups.io/g/b-lang-discuss/topic/106402322) |
| 80 | + |
| 81 | +### BSC backend: Bluesim |
| 82 | + |
| 83 | +* See the link on Bluesim stages, above, under Basics |
| 84 | +* [How Bluesim works (mostly the VCD dumping)](https://github.com/B-Lang-org/bsc/issues/519#issuecomment-1873853532) |
| 85 | +* [How Bluesim provides implementations for import-BVI](https://groups.io/g/b-lang-discuss/topic/106520424) |
| 86 | +* [How the Bluesim C API is imported into Bluetcl](https://groups.io/g/b-lang-discuss/message/554) |
| 87 | +* There is a template for making Bluesim standalone programs (without Tcl) in `bsc/util/bsim_standalone/` |
| 88 | + |
| 89 | +### Bluetcl |
| 90 | + |
| 91 | +* [Support for reflection in BSC](https://groups.io/g/b-lang-discuss/message/513) |
| 92 | + * specifically, Bluetcl (outside the language) and Generics (inside the language) |
| 93 | +* See the link on how Bluesim's C API is imported into Bluetcl, above, under Bluesim |
| 94 | + |
| 95 | +### SMT solvers |
| 96 | + |
| 97 | +* [The ways that SMT solvers are used in BSC](https://groups.io/g/b-lang-discuss/message/370) |
| 98 | +* [SAT solver usage and dumping](https://github.com/B-Lang-org/bsc/discussions/693#discussioncomment-9148985) |
| 99 | +* TBD: Status of the SMT solver source codes and how they are incorporated into BSC |
| 100 | + |
| 101 | +### Clock and Reset methodology |
| 102 | + |
| 103 | +* [Clock/reset inference](https://github.com/B-Lang-org/bsc/discussions/661) |
| 104 | +* BSC implements certain design decisions for clocks and resets -- |
| 105 | + for example, the choice to implement reset inside of state elements (to ignore the `EN` input) |
| 106 | + instead of outside (as part of the `RDY` logic) -- |
| 107 | + and there may be some documentation (perhaps internal to BS Inc) on those decisions |
| 108 | + * There was a paper at MEMOCODE 2006, |
| 109 | + ["Reliable Design with Multiple Clock Domains"](https://www.researchgate.net/publication/224648422_Reliable_design_with_multiple_clock_domains) |
| 110 | + * An earlier version of this paper was submitted to DCC'06 (Designing Correct Circuits) |
| 111 | + * There is a BS Inc document from 16 Dec 2004 (`mcd.pdf`) that discusses some options, but only clocks, not yet reset |
| 112 | + * There is a BS Inc document from 28 Oct 2004 (`resets.txt`) that purports to be "a proposal on reset handling" |
| 113 | + but is very prelimary about the problem, not yet the solution |
| 114 | + * There is a BS Inc file `bsc-doc/doc/MCD-extensions.txt` that describes |
| 115 | + the new things in BSC to support MCD, both user visible attributes and |
| 116 | + the BSC source code changes |
| 117 | + * The BS Inc training slides include a |
| 118 | + [lecture on MCD](https://github.com/BSVLang/Main/blob/master/Tutorials/BSV_Training/Reference/Lec12_Multiple_Clock_Domains.pdf) |
| 119 | + |
| 120 | +--- |
0 commit comments