Skip to content

Commit 81bbef9

Browse files
quark17quark17
authored
Initial documentation for developers
1 parent 919cb90 commit 81bbef9

File tree

2 files changed

+122
-1
lines changed

2 files changed

+122
-1
lines changed

‎DEVELOP.md

+120
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
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+
---

‎README.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,14 @@
1010
[Version]: https://img.shields.io/badge/release-2024.07-red.svg?logo=v
1111
[Build Status]: https://github.com/b-lang-org/bsc/workflows/CI/badge.svg?branch=main&event=push
1212

13-
**[Community] &bull; [Download] &bull; [Documentation] &bull; [Build] &bull; [Test]**
13+
**[Community] &bull; [Download] &bull; [Documentation] &bull; [Build] &bull; [Test] &bull; [Develop]**
1414

1515
[Community]: #community
1616
[Download]: #download
1717
[Documentation]: #documentation
1818
[Build]: ./INSTALL.md
1919
[TEST]: ./testsuite/README.md
20+
[Develop]: ./DEVELOP.md
2021

2122
---
2223

0 commit comments

Comments
 (0)