Commit Graph

255 Commits

Author SHA1 Message Date
Krystine Sherwin e2e7065590
Docs: some restructure of advanced section
- Filling out index descriptions for `using_yosys` and `using_yosys/synthesis`.
- To discourage skipping over these index pages, the toctree in
  `using_yosys/index` is hidden and instead has inline links to the two
  subsections.
- Tidying todos.
- Moves technology mapping to `techmap_synth`, leaving the techmap by example in
  the internals section. `yosys_flows` gets split up, with the coarse-grain
  intro replaced by `synthesis/index`, the extract pass moving to
  `synthesis/extract` and model checking to `more_scripting/model_checking`.
2024-01-26 13:08:22 +13:00
Krystine Sherwin 4582ab59da
Docs: intro to memory_libmap 2024-01-26 11:15:01 +13:00
Krystine Sherwin 6e38848b92
Docs: updating makefiles 2024-01-25 12:35:03 +13:00
Krystine Sherwin 2a14c72110
test-docs: target examples directly 2024-01-25 11:36:59 +13:00
Krystine Sherwin 57a7532227
Docs: add test-examples target
`test` becomes `test-macros`, with a new `test` calling both `test-*` targets.
2024-01-25 10:15:00 +13:00
Krystine Sherwin 9b820108d6
Docs: add test-docs.yml 2024-01-24 11:22:38 +13:00
Krystine Sherwin 449135a9d4
Docs: adding other macro command lists
Also updates `macro_commands.py` to skip empty lines, and moves comment
stripping earlier in parsing.
2024-01-24 10:29:40 +13:00
Krystine Sherwin 6c8949cacc
Docs: static opt macro list
Also adds `docs/tests/macro_commands.py` which checks all commands in
`code_examples/macro_commands` against the current yosys build. Format similar
to `run-test.sh` files: logging the file under test and reporting errors.
2024-01-24 09:56:00 +13:00
Krystine Sherwin 95849edbba
Docs: changes from JF
`yosys-witness` prereq `click`.
Yosys environment vars & `yosys --help` output.
Removing Ubuntu/macOS version numbers/names.
Hide `troubleshooting` page.
2024-01-23 17:35:06 +13:00
Krystine Sherwin 9ec1536f1f
Docs: getting_started tidy
Rename `show` intro and point to `/cmd/show`.
Add getting_started section overview.
2024-01-22 11:44:43 +13:00
Krystine Sherwin 65bb0d3059
Docs: updating to current 'master'
Pulling for #4133 and removing related TODO.
2024-01-22 11:18:07 +13:00
Krystine Sherwin 794ad381c6
Docs: scripting_intro/show_intro
Adds two new `show` commands to `fifo.ys` for demo purposes.
Mention referencing named selections with `@<name>`.
Also adds a note to `example_synth` to point to the show intro.
2024-01-22 11:10:02 +13:00
Krystine Sherwin 14b7c581fa
Docs: reworking scripting_intro
Now comes *after* example_synth, with references back to it.
Includes some minor adjustment to the `fifo.ys` script to better demonstrate the `select` command.
Still needs an updated section on `show`.

Also includes some other minor updates.
2024-01-18 15:33:59 +13:00
Krystine Sherwin 74d2c918cd
Docs: installation/source tree 2024-01-18 14:05:34 +13:00
Krystine Sherwin 93ceda5c63
Docs: auxlibs 2024-01-18 12:14:00 +13:00
Krystine Sherwin 27ae093dba
Docs: working on opt page
Replace leftover `opt` example source/images with examples specific to the `opt_*` pass.
Currently has images for `opt_expr`, `opt_merge`, `opt_muxtree`, and `opt_share`.
Also includes some other TODO updates.
2024-01-17 11:00:42 +13:00
Krystine Sherwin 63a0f80996
Docs: opt_share 2024-01-17 08:47:50 +13:00
Krystine Sherwin 14f2208e47
Docs: opt_expr 2024-01-17 08:40:48 +13:00
Krystine Sherwin aa652f9634
Docs: fix scripting_intro.rst images 2024-01-16 13:23:30 +13:00
Krystine Sherwin 5a4c2e5c79
example_synth: proc and opt_expr
Highlight `proc` blocks and intro `opt_expr`.
2024-01-16 13:23:04 +13:00
Krystine Sherwin 646ff6d32d
Docs: interactive investigation
More `literalinclude` and references to source.
Adding `example_show.ys` and `example_lscd.ys`.
Rename `example_00` et al to `example_first` et al.
Also some other minor tidying.
2024-01-15 15:32:14 +13:00
Krystine Sherwin 9fe3dcda78
Docs: optimization passes
Working on `opt.rst`.
Replace the hardcoded `opt` psuedo code listing with a `literalinclude` from `/cmd/opt.rst`.
Reorder and update `opt_*` list to match current `opt`.
Expand sub-section titles with the function of the pass (keeping the `:cmd:ref:` part at the end to prevent the Esbonio error in vscode when a heading starts with a directive).
Move comments about `clean` and `;;` being aliases into final `opt` subsection.

Also renames `Test suites` -> `Testing Yosys`.
2024-01-15 13:15:11 +13:00
Krystine Sherwin 9eab5d8b24
Updated Yosys family 2024-01-15 12:27:38 +13:00
Krystine Sherwin 3360c612d5
Docs: remove hanging reference 2024-01-13 17:46:19 +13:00
Krystine Sherwin 12fa443fe3
example_synth: more on hierarchy and stat 2024-01-13 17:46:04 +13:00
Krystine Sherwin a3255fd8d3
Docs: opt_rmunused -> opt_clean 2024-01-13 16:57:10 +13:00
Krystine Sherwin 064723a1cc
example_synth: tidying
Adds note on `+/`.
Clarifies that we can't entirely skip loading `cells_sim.v`, and then mentions it again later once we need it.
More on final steps (and synthesis outputs).
2024-01-13 15:46:00 +13:00
Catherine 1159e48721 write_verilog: emit `initial $display` correctly. 2024-01-11 13:13:04 +01:00
Krystine Sherwin eb5da87d52
example_synth: hardware mapping
Filling out the hardware mapping sections, and actually highlighting the changes in schematics instead of just the memory block.
Also includes Part 4 of the coarse-grain rep, looking at `memory_collect` and putting the `synth_ice40 -top fifo -run :map_ram` command in its own (sub)section.
Includes a `no_rw_check` section label in `memory.rst` for reference (because I can't remember how to reference by heading).

Not sure about the opt output after map_ram section which has an open TODO, and the final steps section is also still open.
2024-01-08 16:59:03 +13:00
Krystine Sherwin e6f8804e6a
example_synth: more on DSP mapping 2024-01-08 13:24:52 +13:00
Krystine Sherwin 3e653fe4a6
docs: more on wreduce in synth starter 2024-01-04 12:49:48 +13:00
Krystine Sherwin 9f1c445fbf
docs: work on example_synth
Split hardware mapping from `fifo.ys` into `fifo_map.ys`.  Reduces size of `fifo.out` log and allows separate yosys calls in the makefile.

Some tidy up and minor changes in `fifo.ys` for better discussion.
Filled out note on `clean` (changed from `opt_clean`) and introduced `;;`.
Highlighted `$memrd` and added a paragraph about it.
More detail on the flatten and merging of `fifo_reader` block.
Brief discussion on the changes from `$memrd` to `$memrd_v2`.
2024-01-03 11:47:33 +13:00
Krystine Sherwin 50d8c1b258
First pass example_synth done
Split coarse grain representation into 4 parts, loosely: fsm/opt, other optimizations/techmap/memory_dff, DSPs, alumacc/memory -nomap.
Split hardware mapping into subsections as well: memory blocks (map_ram and map_ffram), arithmetic (map_gates), FFs (map_ffs), LUTs (map_luts and briefly abc), and other (map_cells and a note on hilomap and iopadmap).

Also add `-T` flag to Yosys call to remove footer from log output.
2023-12-20 14:08:06 +13:00
Krystine Sherwin a33b1b6059
More work on example_synth
Added highlighting in (most) schematics.
Written down to end of coarse-grain, with a couple of TODOs for filling in gaps.
Includes `techmap_synth.rst` stub.
2023-12-18 17:49:15 +13:00
Krystine Sherwin 742ec78ca3
Switching example synth to fifo
Fifo code based on SBY quick start.
Instead of showing the full design we are (currently) focusing on a single output (rdata), using `%ci*` to get the subcircuit it relies on.
2023-12-18 13:19:01 +13:00
Krystine Sherwin 80c78aaad6
New example_synth code
`example_synth.rst` updated down to coarse-grain representation.
2023-12-14 16:21:52 +13:00
Krystine Sherwin 6d1caf6134
Initial synth_ice40 example
Overall structure in place to match the iCE40 flow.
Still needs a new example design, and more text for the later sections (which the counter doesn't cover).
2023-12-14 11:33:32 +13:00
Krystine Sherwin 3a153f99db
Add cell_libs.rst
Updates code examples, removing `counter_outputs.ys` in favour of a single script.  Also adds a .gitignore for the output file `synth.v`.
`example_synth.rst` still pending updated example.
2023-12-14 10:08:46 +13:00
Krystine Sherwin f44e8d0124
Working on extensions doc
Moved the last files out of the resources directory.
Some tidy up/reformatting of the extensions to allow literalincludes from `my_cmd.cc`.
Most (all?) of the getting started guidelines file is either in the quick guide section, or sections referenced by it.  Instead of including it verbatim, we'll instead just leave a reference to it but then jump straight into the quick guide.
Include an image for the absval generated module.  Still needs more surrounding text but it's good enough for now.

Also includes some other minor tidying, including removing the no longer used abc_01 code example.
2023-12-13 11:34:42 +13:00
Krystine Sherwin 7f24ef37f8
Add todo 2023-12-13 10:15:51 +13:00
Krystine Sherwin 1733a76273
Updated ABC info
Includes comparison of `abc` v `abc9`. Also creates a new subsection of the
yosys internals for extending yosys (moving the previous extensions.rst into it).

Co-authored-by: Lofty <dan.ravensloft@gmail.com>
2023-12-13 10:08:45 +13:00
Krystine Sherwin e34a25ea27
TODOs
Blocking tasks are now capital TODO (compared to non-blocking todo).
Updated some of the todos.
Added note about which intel synth does which families.
Rename extended Yosys universe to Yosys family.
Added brief text to landing page, and also a note about the restructure and where to find old docs.
Moved todolist above ToC in preparation for disabling it in the config (so that it doesn't need it's own header).

Fixed pdf build, was previously breaking on trying to include the svg badges.
2023-12-12 12:05:45 +13:00
Krystine Sherwin 4ecceaed44
Updates to install and tests
Includes CAD suite info and details on the OSS CAD suite nightly build targets.
Instructions for building from source, largely based on the readme but with some minor modifications.
Tests are still WIP, but we replaced the old test suites with a brief comment on the github workflow tests.  Still needs more on the tests themselves and how to run them locally.
Also an extra todo on the index page.
2023-12-11 12:44:05 +13:00
Krystine Sherwin f949579cf3
Testing latexpdf build
Also added `seealso` blocks to example synth.
2023-12-08 11:19:12 +13:00
Krystine Sherwin 25f6a98f52
Updating the intro
Based on the Ignite presentation and github.
Adds links for the extended Yosys universe.
Moves the original thesis stuff further down (and labels it as such).
2023-12-08 10:46:05 +13:00
Krystine Sherwin aef9921fc9
Tidying TODOs 2023-12-08 09:50:10 +13:00
Krystine Sherwin 1e3b90ae56
Removing typical phases doc
Moved remaining content into relevant places.
Added `load_design.rst` to more scripting.
Split fsm handling and abc out of optimization passes. Also moved things around to match the general flow previously described.
Changed generic `synth` for `prep` instead.
2023-12-07 17:14:21 +13:00
Krystine Sherwin f9ce3d1c26
WIP merging synth phases with example
Replace `typical_phases.rst` and `examples.rst` with a single `example_synth.rst`.
Also updating the counter example to match.

Aims to reduce redundancy, and simplify the getting started section.
Details on things like `proc`, `memory` and `fsm` should instead be in the advanced section (under the new `synth` subsection).
2023-12-07 13:04:46 +13:00
Krystine Sherwin bad8dba2cd
Correcting plurals 2023-12-05 11:22:00 +13:00
Krystine Sherwin a8b2525b08
typical phases: Expand/split sections
More consistent indentation and section headings.
Convert yoscrypt blocks to lists of cmdrefs (so they link to the commands in question).
Also update said lists.
Add other common optimizations/mapping commands.
Remove example synth script in favour of the examples on the next page.
2023-12-05 11:21:39 +13:00
Krystine Sherwin 0fb511905a
docs: more tidying
Fix 010 pdf link.
Swap yosys script code blocks for literal includes.
Fix broken example code.
2023-11-16 09:46:47 +13:00
Krystine Sherwin 2b270b2270
docs: Tidying image generation
Makefiles now have `clean` target.
Also fixed top level makefile calls to images directory.
More yosys scripts instead of inline yosys commands in makefiles (which also means they can be included in the accompanying document when talking about the image generated).
Fixed another couple image generators that were still outputting pdf directly.
Fixed some hanging image references which hadn't been updated.
Adjusted some text related to images, and included a couple more intermediate images on `memdemo`.
2023-11-16 09:08:22 +13:00
Krystine Sherwin b6e61c16b1
docs: restructuring images directory
see also previous commit
Also updates `scripting_intro.rst` to use literal includes, and uses individual image outputs to avoid the intermediary `.tex` file to join them all.
2023-11-14 18:54:16 +13:00
Krystine Sherwin dbc38d72cf
docs: moving code examples
Code now resides in `docs/source/code_examples`.
`CHAPTER_Prog` -> `stubnets`
`APPNOTE_011_Design_Investigation` -> `selections` and `show`
`resources/PRESENTATION_Intro` -> `intro`
`resources/PRESENTATION_ExSyn` -> `synth_flow`
`resources/PRESENTATION_ExAdv` -> `techmap`,  `macc`, and `selections`
`resources/PRESENTATION_ExOth` -> `scrambler` and `axis`

Note that generated images are not yet configured to build from the new code locations.
2023-11-14 12:55:39 +13:00
Krystine Sherwin 3d70867809
docs: remove synth_machxo2, add _lattice 2023-11-13 16:27:10 +13:00
Krystine Sherwin 2b10bd5070
docs: update images makefile
Correct path to 011 source.
Also path for resources target.
Set timezone to 'Z' for faketime.

Not sure how to avoid needing to `make resources` before `make all` (or running
`make all` twice) in order to properly generate the presentation images.
2023-11-01 10:48:04 +13:00
Krystine Sherwin 8e07030fee
docs: update auxiliary programs
Now includes usage output, (hopefully) generated by the tool during the docs build process so it will always be up to date.
Included in makefile as `docs/usage` target.
Also some updates/additions to the description text, esp `yosys-filterlib` and `yosys-smtbmc`.
2023-11-01 10:15:58 +13:00
Krystine Sherwin 74c1fc1cdd
docs: Reference chapters with doc tag
Fix some formatting.
2023-10-30 22:38:47 +13:00
Krystine Sherwin d4e45cdccb
docs: Stub new(er) auxlibs and auxprogs
Still need to actually be filled in.
Also rearranges auxlibs to be alphabetical order.
2023-10-30 11:21:31 +13:00
Krystine Sherwin e49903f8b1
List all synth commands on synth page 2023-10-30 11:04:03 +13:00
Krystine Sherwin a1c3755dd6
Fix typo 2023-10-30 10:35:23 +13:00
Krystine Sherwin abd92225a3
Replace 010 and 012 with pdf
Comment out the body text and instead include just the abstract and a download link.
Also orphan the pages so they aren't accessible except by direct link, or via search.
2023-10-30 10:34:30 +13:00
Krystine Sherwin 17749ce688
docs: absolute cmd directory 2023-10-16 21:10:03 +13:00
Krystine Sherwin ebcbb94a21
Fixing makefile 2023-10-12 04:50:27 +13:00
Krystine Sherwin 8335044c35
docs: reflowing selections doc
Combined presentation sections with appnote sections.
Moved a bunch of Yosys one-liners in-line.
Better reference in interactive investigation to memdemo as a part of advanced logic cone selection (esp. because the show commands use some of the advanced features)
2023-10-11 12:46:26 +13:00
Krystine Sherwin c61ab7d627
docs: Tidying interactive investigation
More :numref: because I figured out they were only failing if I didn't do a full re-make.
Reflow first section a little to help readability.
Also includes a css change to prevent code block caption text from bunching into the caption number.
2023-10-11 11:13:06 +13:00
Krystine Sherwin 9e35848c8e
docs: initial 011 selections move
Also deleting the 011 document.
2023-10-10 12:36:10 +13:00
Krystine Sherwin a019c26b9d
docs: Moving 011 into main body of manual
Mostly in the `more_scripting` section, with part of the intro in the `scripting_intro`.
Also includes an extra todo on the installation page and some extra notes on where to find `show` details where relevant.
2023-10-10 12:35:23 +13:00
Krystine Sherwin b0f8059bce
Moving images and static folders
Images now included relative to the `docs/source` folder instead of the rst file.
Also makes sure to add the updated `yosyshq.css` (which as a sidenote has ended up as `custom.css` in most of the other docs).
2023-10-10 10:12:50 +13:00
Krystine Sherwin 98d0e749d6
Merge updates from 'master' into krys/docs 2023-09-19 11:28:36 +12:00
Krystine Sherwin 10ecbe9f5b
docs: updating memory mapping text
More complete code examples and confirming Verific support thanks to @povik
2023-09-19 11:26:57 +12:00
Krystine Sherwin 93c9bf2f5d
docs: Updating todos 2023-09-19 11:21:15 +12:00
Krystine Sherwin 70c47690b3
Updating todo text and assorted fixes
Fix #3905 by removing emoji (and move the comment into the if block for less ambiguity).
Adds `latexmk` to README.

Note that latexpdf doesn't seem to like `cmd:ref` links, possibly because the
reference location is inside a latex comment block, but I was under the
impression that there was a reference location in there previously which was
working fine.  May be related to how the `cmd:def` block expands (or doesn't as
the case may be).
2023-08-28 10:09:43 +12:00
Krystine Sherwin aad8a3b959
Rearrange command ordering and model checking
Now under the yosys flows section.
2023-08-28 10:02:06 +12:00
Krystine Sherwin e2c0f8fc50
Some tidy up 2023-08-14 12:13:29 +12:00
Charlotte f9d38253c5 ast: add `PRIORITY` to `$print` cells 2023-08-11 04:46:52 +02:00
Charlotte 843ad9331b cxxrtl: WIP: adjust comb display cells to only fire on change
Naming and use of statics to be possibly revised.
2023-08-11 04:46:52 +02:00
Charlotte 7f7c61c9f0 fmt: remove lzero by lowering during Verilog parse
See https://github.com/YosysHQ/yosys/pull/3721#issuecomment-1502037466
-- this reduces logic within the cell, and makes the rules that apply
much more clear.
2023-08-11 04:46:52 +02:00
Charlotte c391ee7a0d docs: document simulation time format specifiers 2023-08-11 04:46:52 +02:00
Charlotte 202c3776e2 docs: elaborate $print documentation 2023-08-11 04:46:52 +02:00
Charlotte 2d7b8f71cc docs: first pass $print documentation 2023-08-11 04:46:52 +02:00
Krystine Sherwin 685da6a2e5
Converting a number of inline commands to refs
Also reflowing text for line width.
Maybe look into supporting commands with options?
2023-08-08 12:45:47 +12:00
Krystine Sherwin f8333e52f7
cmd links use title text 2023-08-08 12:19:13 +12:00
Krystine Sherwin 9fcf353734
Makefile adjustments to match top make
Hopefully matches enough that any `make docs` call will work from the yosys being built, while still being overridable locally.
2023-08-08 11:53:36 +12:00
Krystine Sherwin 8203a01ba9
Adding custom domain for cmdref 2023-08-08 11:51:57 +12:00
Krystine Sherwin d8b8880ad6
Convert todo comments to directives
Could be left in for final version, but my current thinking is not?
2023-08-08 10:06:19 +12:00
Krystine Sherwin ce9e56db47
Move the last presentation slides 2023-08-08 09:50:36 +12:00
Krystine Sherwin afc25afaf9
Minor tidying 2023-08-07 12:58:52 +12:00
Krystine Sherwin 8ade2182b0
Move (most of) ExOth and ExAdv slides 2023-08-07 12:58:40 +12:00
Krystine Sherwin 7ab051778e
Add copypaste reminder for typical_phases.rst 2023-08-07 10:40:36 +12:00
Krystine Sherwin 330a2272da
Converting PRESENTATION_ExSyn 2023-08-04 10:29:14 +12:00
Krystine Sherwin 4b40372446
Tidy/reflow some things 2023-08-03 10:37:43 +12:00
Krystine Sherwin 2c75b103d6
Include test suites doc with note 2023-08-03 09:20:30 +12:00
Krystine Sherwin 9a9aa2c45a
Finished presentation intro
Also some other tidy up.
2023-08-03 09:20:30 +12:00
Krystine Sherwin 20c2708383
Move presentation intro example
Rework images makefile a bit to get it to import and build from resources folder(s).
Currently requires running twice from a clean build due to the way it finds `.dot` files to convert.
2023-08-03 09:20:29 +12:00
Krystine Sherwin cd6e63e1a9
Moved presentation_prog 2023-08-03 09:20:29 +12:00
Krystine Sherwin 045c04096e
Reorganising documentation
Also changing to furo theme.
2023-08-03 09:20:29 +12:00
Krystine Sherwin 4f1cd66829
New structure headings
Also adds a note to readme for installing pdflatex if it's missing.
2023-08-03 09:20:24 +12:00
Charlotte 0c0171bd60 docs: RD_DATA is an output, not input 2023-06-21 17:21:04 +10:00
Krystine Sherwin d1b86d2fcf
docs: reflow memory map
Move additional notes up to the top and give it its own section.  Also reformat some paragraphs, and turn some bullet points into paragraphs.
Split supported patterns section into some kind of grouping.
Currently:
- SDP
- single-port RAM
- reset patterns
- asymmetric
- TDP
2023-06-19 12:05:51 +12:00
Krystine Sherwin 3aee765793
Initial version of memory mapping doc 2023-05-26 09:36:01 +12:00
KrystalDelusion b9b5899cce
Remove docs dependency on yosys repo (#3558)
* Copies guidelines files into docs/ for website

* Copying manual/CHAPTER_Prog for new docs

* Copying manual/APPNOTE_011... for new docs

Also adding faketime to list of packages for website build.

Co-authored-by: KrystalDelusion <krystinedawn@yosyshq.com>
2022-11-24 15:56:44 +01:00
Miodrag Milanovic 48659ee2bb Slowing down clock to have same metadata 2022-11-16 10:11:05 +01:00
Miodrag Milanovic 7de226878d faketime to make PDFs unique 2022-11-15 14:13:41 +01:00
KrystalDelusion a14dec79eb
Rst docs conversion (#3496)
Rst docs conversion
2022-11-15 12:55:22 +01:00