Scrap Mechanic EDA is a set of EDA tools that bring industrial-level circuit design to the game Scrap Mechanic. This toolset consists of a series of command-line executables packaged in a docker container. It enables the creation of complex circuits with minimum effort.
This repo also serves as the SM-EDA Swift Package. By using this repo directly with SPM, you can develop a Swift program that interfaces with SM-EDA Netlist, Yosys Netlist, and SM Blueprints.
For example, the following Verilog code describes an 8-bit counter that counts up during clock rise but resets (synchronously) if RES is high.
// Resources/Example-1/design.v
module counter(
(* device = "button" *)
(* color = "purple" *)
input CLK, // clock port
(* color = "yellow" *)
input RES, // reset
output [7:0] C
);
// Setup a register that holds 8 bits
reg [7:0] register;
assign C = register;
always @(posedge CLK) begin
if (RES) begin
// Reset counter to zero if RES is high
register <= 8'b0;
end else begin
register <= register + 1;
end
end
endmoduleAfter the complete synthesis flow using Yosys and SM-EDA, you get a behaviorally identical Scrap Mechanic blueprint: a resettable counter.
The following Verilog code describes a module that performs 32-bit integer division. This division module is purely combinational.
module divider(
input [31:0] A,
input [31:0] B,
output [31:0] C
);
assign C = A / B;
endmoduleAfter the complete synthesis flow using Yosys and SM-EDA, you get this massive blueprint. It contains 4924 logic gates and 11947 connections. The critical path is 341 ticks (8.525s). This will take a week to build by hand.
The image above shows dividing 277,350,948 by 49 and obtaining 5,660,223.
// Don't believe me?
C = 0000'0000'0101'0110
0101'1110'0011'1111 = 277,350,948
B = 0000'0000'0000'0000
0000'0000'0011'0001 = 49
A = 0001'0000'1000'1000
0000'1010'0010'0100 = 5,660,223
As you can see, SM-EDA makes building complex logical creations much more simple by automating the creation of any modules like this one.
SM-EDA is a collection of custom tools that enable Electronic Design Automation (EDA) for Scrap Mechanic. All the tools are subcommands of a single command line executable sm-eda. The function of each tool is listed below.
sm-eda ys2sm- Read Yosys JSON and convert it into SM netlist JSON
sm-eda place- Read a sm netlist JSON and a placement configuration, then generate a blueprint from them
sm-eda autoplace- Read a sm netlist JSON and generate a blueprint from it
sm-eda autoplan- Generate a barebone placement configuration given a netlist
sm-eda bram- Generate a ram module netlist JSON using XOR-based DFF or timer-based memory with arbitrary size, addressability, and port configuration
sm-eda edit- Perform edits on SM netlist JSONs, like merging different netlists, shorting, driving, and deleting ports, etc.
sm-eda sim- Perform interactive, or scripted simulation on SM netlist JSONs
sm-eda show- Visualize the netlist by exporting to graphvis
.dotformat - Can be used to explore netlists visually
- Visualize the netlist by exporting to graphvis
Almost all tools work by operating on a JSON netlist format tailored to Scrap Mechanic logic. This interchanged represents the logic network without solidifying them into a blueprint. It is designed to be passed around different tools. For example, you may run sm-eda bram first to generate a timer memory netlist, then use sm-eda autoplace to create a blueprint.
Although SM-EDA includes many useful tools, it is only the backend of a proper EDA pipeline.
We rely on Yosys to parse, optimize, and techmap RTL designs written in HDL languages (like Verilog). Yosys is a generic synthesis frontend.
The SM-EDA Bundle is a docker image that contains both SM-EDA tools and Yosys. Installing the SM-EDA as a docker image is preferred, as it requires minimum setup and works out of the box. This docker image is built automatically via GitHub actions on every release, and the image is available via GitHub Packages.
To make Yosys work the way we want it to, we provide a custom synthesis script script.ys. We also provide cell libraries and other resources that the script use under Resources/Flow.
Yosys parses, optimizes, and techmaps the RTL design in Verilog, and our tool SM-EDA converts it into our netlist JSON and generates a blueprint. Together, Yosys and SM-EDA are the complete EDA pipeline.
If you want to know how all of this works, read the additional doc Inner Workings.
Note that Yosys is an independent project, and we are not affiliated with them.
This repo contains the source code of the tools in SM-EDA only. SM-EDA is released under GPLv3. A copy of this license is available in the root directory of this repo. It is also available in the /sm-eda folder in the docker image, as well as the root folder of the binary release.
Yosys is not part of this repo and is released under the ISC License. We do not intend to re-release Yosys, under a different license. However, if this behavior constitutes redistribution, the ISC license is compatible with GPLv3. Meanwhile, we have no intention to (and physically cannot) monopolize Yosys. Yosys is always available in its own repo.
You don't need to install anything to use SM-EDA. You can use our template to create a GitHub repo, and use GitHub's servers to compile your blueprint. Everything is set up already, and it's hassle-free.
After creating your repository from the template, you can compile your blueprint just by clicking on the Run workflow button under the provided Compile and Generate workflow. You can then download the blueprint as a Workflow Artifact when the workflow is done. The logs will also be saved along the way in a ZIP file, even if compilation fails.
Learn more at SM-EDA Project Template.
First, Install Docker. Then download the docker image by running the following command:
docker pull ghcr.io/yliu-hashed/sm-eda-bundle:latestThen, run the image by running its bash in an interactive mode:
docker run -it ghcr.io/yliu-hashed/sm-eda-bundle:latest bashThen, you should be able to do things in it. Commands like yosys and sm-eda will be immediately available inside the image. You can use yosys -h and sm-eda -h to verify that each tool in each package is working. You can now exit the image using exit or continue to Example-1.
Also, optionally install GNU Make if you don't have it. It is a preferred way of saving you the trouble of typing lengthy commands for every build. You can optionally accomplish the same thing with shell scripts.
If you wish to contribute to SM-EDA, you might want to also build the docker container from the sources. You should first Install Docker. The following command will build the docker image from the sources.
# run the command from repo root
docker build -t sm-eda . -f Docker/DockerfileNote: Expect it to take roughly 20 minutes, since the container also has to build Yosys from source.
Note: Local installations are highly discouraged. A multiplatform docker image is provided to save you trouble. But you can always install it locally if you want to. Keep in mind that you may encounter many hard-to-solve problems.
Since Swift on many platforms still needs to be matured, we do not distribute pre-built binaries other than the one in the docker container. If you wish to run sm-eda tools locally, you have to compile them yourself. If you are running Windows, doing all this in WSL is highly recommended.
- Install Swift
- Download the source code of this repo via
git cloneor your browser, andcdinto it - Run
swift build -c releaseto build the binaries - Add the built binaries to your
PATH(built binaries normally are in.build/release) - (optional) Install Yosys via OSS CAD Suite, from your OS's package manager, or build Yosys yourself.
- (optional) Install GNU Make - recommended to automate project build
If you have installed Yosys and SM-EDA locally, the samples below will not work due to them relying on the docker container. But since you somehow installed it locally, you should have no trouble modifying the examples as they are quite rudimentary. Typically, replacing $(call DOCKER_RUN,<command>) with <command> will just work.
The examples will also reference synthesis scripts inside the image like /flow/script.ys and /flow/script.abc that are not available on your machine under such paths. These scripts are available under /Resources/Flow/ of this repo. You need to place them somewhere general and update everything to reference them. Scripts can often reference other scripts. For example, script.ys references script.abc.
Going into this will require you to understand many industry-specific information. If you need help, The NOOB Guide is here to help. If you need more help, reach for the Discussions Tab of this repo.
To get started in SM-EDA, please view the two examples:
Resources/Example-1 - demonstrates how to use SM-EDA Docker Image from the command line.
Resources/Example-2 - demonstrates how to use GNU Make to construct an auto-building project.
If you are planning to make large circuits, read the note on Docs/Logic-Limitation.md that talk about the blueprint size limit.
If you like to tinker, try reading the Docs/Inner-Workings.md. This talks about how all this work under the hood.