Getting Started

2026-02-19T00:00:00+00:00

So you want to get started working with FPGAs? Great! This page will go through everything you need to know to dive right in.

Not sure what an FPGA is? Check out our Why Use FPGAs</a> page.

Requirements</h1>
To get started, the only thing you really need is a computer.
Alchitry Labs</a> lets you run interactive simulations with a virtual Io element</a>. This is enough to get through the first three starter tutorials</a>. That should give you an idea what programmable hardware is all about without having to spend any money.
Ideally, your computer is running Windows or Linux, however, you can get started on a Mac as well. While Alchitry Labs runs on all three systems, the tools from the FPGA manufactures only work on Windows and Linux.
On a Mac, you have the option of using the open source tools if you have a Cu</a> or running inside a virtual machine. While the open source tools are cool, they generally aren't as robust as the proprietary ones.
Go ahead and download Alchitry Labs</a> then start Your First FPGA Project</a>.

Choosing a Board</h1>

Assuming you've seen enough to want to get some real hardware, the next question is which board should you get?

Our recommendation for most people is to get an Au</a>. The reason we recommend it over the Cu</a> is that the FPGA on the board is a modern chip from Xilinx. The Artix 7 on the Au is supported by Xilinx's tool called Vivado. This tool is free for the Au's FPGA for both commercial and personal use (you need to make an account).

The iCE40 FPGA on the Cu is an older FPGA made by Lattice and is supported by iCEcube2. Unfortunately, Lattice decided to make iCEcube2 no-longer free. It also hasn't been meaningfully updated in almost a decade, so I'm not sure what the new licensing cost is covering.

They still offer a free license to "hobbyists, enthusiasts, community educators & start-up companies." To get one, you have to email them. See the Licensing section of this page</a> for more details. For what it is worth, I haven't heard of them denying anyone and they are pretty quick to get back to you.

Vivado, the tool for the Au and Pt, also has Xilinx's IP catalog, which offers a lot of powerful blocks you can drop into your designs. Things like digital filters, FFTs, and floating point math.

So what about the Pt</a>? The Pt is really just a supped-up Au. The FPGA has about 3x the capacity of the Au, and it has almost twice the IO.

The only feature it has that isn't just more of an Au's feature are the GTPs. This is a set of specialized pins that allow for up to 6.25 Gbps of data for each pair. It's an advanced feature.

Here's a table summarizing the different features for the three boards.

Board</th> IO Pins</th> Relative FPGA Capacity</th> Free Tools</th> Open Source Tools</th> IO Voltages</th> Differential Signals</th> On-board DDR</th> IP Catalogs</th></tr></thead>

Cu</td> 79</td> 1x</td> yes*</td> yes</td> 3.3V</td> No</td> No</td> Alchitry</td></tr>

Au</td> 104</td> 3x</td> yes</td> yes**</td> 3.3V, 2.5V, 1.8V</td> LVDS, TMDS</td> 256MB</td> Alchitry, Xilinx</td></tr>

Pt</td>

206</td>

9x</td>

yes</td>

yes**</td>

3.3V, 2.5V, 1.8V</td>

LVDS, TMDS</td>

256MB</td>

Alchitry, Xilinx</td></tr> </tbody></table>

* for hobbyists, enthusiasts, community educators, and start-up companies
** they exist</a> but aren't included in Alchitry Labs yet

Extra Elements</h2>
In addition to your main FPGA board, you probably should pick up at least a Br</a>. I generally recommend going with the Wide version, which allows you to solder in headers</a> for easy access to signals.
The Io element</a> is also a great pickup for experimenting if you want to bring your simulations to life.
The other elements are highly situational. If you need to dump a lot of data to or from your FPGA, the Ft</a> is what you need. If you want HDMI in/out, then the Hd</a> has you covered.

Software Setup</h1>
No matter what board you have, you'll need Alchitry Labs</a>. Even if you don't plan to use it as an IDE, you still need it for the Alchitry Loader to get the bin file onto your board.
If you have an Au or Pt, you need to install Vivado</a>.
If you have a Cu, you can use the built-in open-source tools by clicking the beaker logo and going to Settings → Cu Toolchain → Yosys (Open Source) in Alchitry Labs. Alternatively, you can install iCEcube2</a>.
Tutorials</h1>
With everything set up, you can jump into the catalog of tutorials</a>.
If you run into issues, have questions, or just want to talk FPGAs, head over to the forum</a>.

Why Use FPGAs?

2026-02-11T00:00:00+00:00

So you've heard the term FPGA and want to know what they are and why people use them? Well, you've come to the right place!
First, FPGA stands for Field Programmable Gate Array. Phew, with that mouthful out of the way, we can get into what that actually means.
FPGAs belong to a family of devices known as programmable hardware. They let you design a digital circuit using text on a computer, similar to writing code. However, FPGAs don't run code. Instead, the text is something called a Hardware Description Language (HDL).
These are languages specifically designed for describing digital circuits.
The tools on your computer take your HDL and turn it into a configuration file for the FPGA. Almost like magic, once loaded onto the FPGA, the FPGA becomes the circuit you described.
Ok, ok let's get out of the weeds and take a step back. While this sounds cool, why bother with it when we have powerful processors we can make do whatever we want with code?
Processors vs FPGAs</h1>
Let me give a quick analogy for these two systems to give you some intuition on when you might use one or the other.
Imagine you sell sandwiches. You have a small shop with a few sandwiches on the menu, and you even allow customers to create their own custom orders.
However, you find that the majority of your customers order one of three sandwiches. As your business grows, you have a hard time keeping up with demand of these three sandwiches. You decide that personally creating hundreds of the exact same three sandwiches every day isn't very efficient.
Instead, you decide to set up an assembly line. You invest in some robots that can cut the bread, place the cheese, spray on condiments, etc.
While setting up this line was a lot more work than just making a sandwich, you can now pump out way more than you could before very efficiently.
In this scenario, you, a sandwich master chef capable of creating any unique sandwich to order, are like a processor. Processors are fantastic at handling a wide variety of complicated tasks and dealing with complicated control flow. Someone wants their one sandwich cut into a star shape? No problem, you can do that.
On the other hand, the assembly line is like an FPGA.
Each piece of the assembly line operates in tandem with every other piece. Where you, the processor, do one task at a time, cut the bread, then place the cheese, etc., the assembly line does them all at once. Sandwiches flow through the line continuously. When one sandwich is having mayo dispensed on it, another is having the cheese placed, and yet another is just being started by slicing bread.
The individual pieces all work together in parallel. This makes the throughput of the assembly line very high.
The assembly line equivalent in digital design is known as a pipeline. You've likely heard that term before, and in this context it describes a circuit where each section processes some data in some way before passing to the next section. All the sections run in parallel with many pieces of data flowing through the pipeline at any given time in various stages of completeness.
However, while pipelines are very powerful and commonplace, FPGAs can implement any digital circuit you want, including things like processors.
Processors and FPGAs</h2>
While it's common to want to compare FPGAs to processors, it isn't really a strictly fair comparison. That's because you can implement processors inside an FPGA.
Just for reference, processors inside an FPGA are often called soft processors.
You can imagine a situation on our hypothetical sandwich line where one stage is very complicated to automate or requires immense flexibility. In that case, it might be worth hiring someone to fill that role instead.
That's the power of being able to incorporate a processor directly into an FPGA.
Inside the FPGA, you can also scale up or down that processor's capabilities depending on the job it needs to perform. If all it has to do is cut the sandwich into a funny shape, it doesn't need a PhD in astrophysics.
There are even some FPGAs that have hard processors (i.e. ones that are fixed) in them to give you both high software performance and custom hardware flexibility. It's also common to see FPGAs paired with external processors. They're often complimentary rather than exclusive.
FPGAs vs ASIC</h2>
All the benefits I've said up to this point aren't specific to FPGAs. Instead, they're just benefits to creating a custom circuit.
The term ASIC, or Application Specific Integrated Circuit, is used to describe a custom circuit made into a custom chip. This is the gold standard when it comes to performance (both speed and power consumption). However, it isn't always in reach.
There are two major downsides to having your design turned into an ASIC.
First, once you get your chip back from the fab, that's it. If you find you made a mistake, even a tiny one, it is baked into the design and requires new chips to be made to fix. Second, getting them made a slow and expensive process. Typically, you're looking somewhere North of a million USD.
This is where FPGAs come into play. FPGAs allow you to make your digital circuit without having to actually make it.
That flexibility comes at a cost.
First is the real dollars cost. FPGAs aren't cheap. While today, you can get a lot for the money, the FPGA itself is rarely less than $10 for the smallest ones and high-end FPGAs easily go into five digits with some in the six digit range. On top of that, FPGAs generally require quite a bit of extra stuff to make them work like multiple power supplies and external memory.
The second cost is in performance. FPGAs are both slower and more power hungry than an ASIC. There is inherent overhead in the circuitry that makes them so flexible.
So why use them?
While their per-unit cost is terrible compared to a huge batch of ASICs, there is no NRE (non-recurring engineering) costs associated with production. This is a game changer when you have lower volumes or your design is likely to change. They're also useful in prototyping designs that will later become ASICs.
FPGAs also can be reconfigured over and over again making any circuit using them field programmable (hey, that's where the FP part of FPGA came from). This is an incredible superpower.
When to Use an FPGA</h1>
Given that FPGAs are more expensive and power-hungry than a typical microcontroller, you may be wondering when you should use one. There are a handful of places, such as tons of IO, predictable latency, and high throughput, where FPGAs really excel.
IO</h2>
The first is in anything IO heavy. By IO, I mean inputs and outputs of the chip.
FPGAs often have a ton of pins to connect to the external world. On top of that, these pins often have capabilities not seen on microcontrollers.
For example, on our Au FPGA development board</a>, most of the IO can be used as differential input pairs capable of receiving 1.2 Gbps (1.2 BILLION bits per second). This also happens passively. That data simply comes into the FPGA and is fed into whatever circuit is designed to handle it. The rest of the FPGA is free to do whatever it was designed for.
Contrast that to a microcontroller where something like a basic Arduino could spend 100% of its CPU time toggling a pin at only around 100 thousand times per second (highly dependent on the code and the specific chip). And that's leaving zero time for the CPU to do anything else.
The IO on an FPGA offers unparalleled flexibility. For example, with a typical microcontroller you'll have a bunch of different peripherals (extra dedicated circuits) attached to the main processors. Usually, these include things like timers, UART (serial ports), or other communication protocols.
Using one of the built-in peripherals for sending and receiving data is basically mandatory as bit-banging it (using the CPU to generate all the signals) is slow and wastes a lot of CPU time. However, you have a limited number of each peripheral, and they typically route to specific pins on the chip.
In an FPGA, for the most part, IO pins are IO pins. If you need two of them to be a serial port, connect them to a circuit that knows how to deal with that signal. If you need 20 serial ports, duplicate that circuit 20 times.
If you have some weird custom protocol you need to interface with, no problem! Whip up a circuit that can handle it and attach it wherever.
Check out our FPGA IO video tutorial</a> for more details!
Predictable Latency</h2>
If we go back to our sandwich shop example, when making sandwiches, you might take 3 minutes per sandwich on average. However, sometimes in the middle of making one, the phone rings. You answer the phone and deal with that, but now the total time for that sandwich is 8 minutes.
This is inherent with multitasking. A CPU may be doing its main task, but then an interrupt fires and that needs to be dealt with before resuming the main task. Usually that's exactly what you want to happen, but in some systems that unpredictability is unacceptable.
The sandwich assembly line always pumps out sandwiches at the same rate. Timing when each step happens is straightforward and performance is guaranteed by design.
High Throughput</h2>
This point is probably already obvious to you at this point, but the ability to have many small dedicated portions of the FPGA all running in parallel lends itself to processing a lot of data.
Think things like a GPU pipeline</a> or heavy digital-signal processing (filters, Fourier transforms, etc.).
The parallel nature of an FPGA is seen in breaking down each task into parallelizable chunks and in that every task can be performed independently. Adding some extra unrelated functionality to your design does not slow down other parts like it would in a CPU.
How They Work</h1>
Being able to just load a configuration file onto the chip and have it transform into whatever digital circuit we want seems a bit magical. However, at a high level, FPGAs aren't that complicated to understand.
You don't need to know how they work to use them, but you may still find this section interesting. You will need some background</a> in digital circuits like knowing what a multiplexer</a> is.
An FPGA has three main elements, Look-Up Tables (LUT), flip-flops, and the routing matrix.
Look-Up Tables</h2>
Look-up tables are how your logic actually gets implemented. A LUT consists of some number of inputs and one output. What makes a LUT powerful is that you can program what the output should be for every single possible input.
A LUT consists of a block of RAM (memory) that is indexed by the LUT's inputs. The output of the LUT is whatever value is in the indexed location in its RAM.
As an example, let's look at a 2-input LUT.

Since the RAM in the LUT can be set to anything, a 2-input LUT can become any logic gate!
For example, if we want to implement an AND gate the contents of the RAM would look like this.
Address (In[1:0])</th> Value (Out)</th></tr></thead>

00</td> 0</td></tr>
01</td> 0</td></tr>
10</td> 0</td></tr>
11</td> 1</td></tr> </tbody></table>
It's important to understand that the column Value (Out) could be set to anything! It doesn't have to model a single logic gate. If the value for address 01 was a 1, then the LUT would still perform as expected, but the equivalent logic circuit would require more than one gate to implement. This is why the metric of equivalent gate count for an FPGA is a confusing and poor metric! It is tricky to specify how complicated of a circuit you can implement in a given FPGA because of all the variables.
LUTs in the Au and Pt</h2>
In the Artix 7 used by the Au</a> and Pt</a>, each LUT is a 6-input LUT. However, it isn't a true 6-input LUT but rather two 5-input LUTs connected by a multiplexer (MUX).

The reason the LUT is designed this way is that it can either be used as a single 6-input LUT, or two 5-input LUTs. The only restriction is that both 5-input LUTs must share the same inputs. When it is configured as two 5-input LUTs, In[5] is set to 0.
Flip-flops and Slices</h2> Each LUT's output can be optionally connected to a flip-flop</a>. Groups of LUTs and flip-flops are called slices. In the Artix 7, a slice has 4 LUT6 and eight flip-flops. These flip-flops are configurable, allowing the type of reset (asynchronous vs. synchronous) and the reset level (high vs. low) to be specified. 
The FPGA used by the Au has 5,200 slices in it for a total of 20,800 LUTs. The Pt has just about tripled that with 15,850 slices and 63,400 LUTs!
All slices are not created equal, however. In the Artix 7 FPGAs there are two types of slices, SLICEL, and SLICEM. 
The SLICEL is the basic type of slice and just consists of the four LUT6's and the eight flip-flops plus some extra routing resources.
A SLICEM is the same as a SLICEL except the LUTs can be used as 64 bits of RAM or a shift register up to 32 bits long. The breakdown of the slices is roughly SLICEL 70%, and SLICEM 30%.
The Routing Matrix</h2>
The next size block in the FPGA is the Configurable Logic Block (CLB) and each CLB consists of two slices. Each CLB connects to a switch matrix that is responsible for connecting the CLB to the rest of the FPGA. The switch matrix can connect the inputs and outputs of the CLB to the general routing matrix or to each other. That way the output from one LUT can feed into the input of another LUT without having to travel far.
The routing resources in an FPGA are pretty complicated, but they are essentially a bunch of multiplexers and wires that are used to define what CLBs and other FPGA resources are connected to each other. These connections are again defined in RAM, which is why the FPGA must be reconfigured every time the power is cycled (on Alchitry boards this happens automatically via the on-board persistent memory).
There are also special routing resources available on the FPGA. The most notable are the clock routing resources. When you have a clock being used in your design, it is crucial that the clock signal be distributed as evenly as possible throughout the FPGA so all the flip-flops will flip at roughly the same time. If you were to try and use the general routing resources for this, the clock signal would have large propagation delays from traveling through all the multiplexers. 
To solve this problem, there are global and local routing resources dedicated to clocks. These are basically wires that connect through the entire chip (for global) or sections of the chip (for local) with very little propagation delay. 
Only inputs from certain pins on the FPGA are allowed to drive a signal on the global clock routing resources. These are the MRCC/SRCC pins on the Au and Pt and GBIN pins on the Cu.
On the Alchitry V2 headers, these are normally connected to pins 41, 42, 47, and 48 of each bank where available. For more info on the pinout, see the Pinout and Custom Elements</a> page.
All of these resources that are used in an FPGA to make them very flexible also slow things down. This is why you will never be able to clock an FPGA at speeds comparable to a dedicated chip. An ASIC design can reach speeds faster than 4GHz, while an FPGA is very fast if it's running at 450MHz (internally, IO can go faster). 
This is also why FPGAs consume considerably more power than their ASIC counterparts. An FPGA will require an order of magnitude more power to run than an 8-bit microcontroller, like an AVR. However, they still have the huge advantage of being low-cost for small runs (or hobbyists) and reconfigurable virtually unlimited times.
If you're interested in digging into the nitty-gritty, check out the official UG474 doc from Xilinx</a>.

Basic CPU

2025-12-11T00:00:00+00:00

In this tutorial we will create a super basic CPU that you can write some assembly for. You can then go brag to all your friends about how cool you are.
What is a CPU?</h1>
If you are reading this, there is an excellent chance you already have a decent idea what a CPU is. However, since we are going to be making one, we need to have a clear idea of exactly what we are going to be making.
In its most abstract form, a CPU is a circuit whose behavior is determined by the code it is fed. This way, the same circuit can perform a completely different task simply by changing some values in a ROM. In general, a CPU will also have some form of memory to perform work, and they all need a way to input and output data (if you don't have any IO, you can't do anything useful).
A CPU is some circuit that has a stream of instructions fed to it, and those instructions determine what it will do. But what sort of operations do we need?
Instruction Set</h2>
A CPU's instruction set is the set of instructions that the CPU understands. It is the language of that particular processor. However, many CPUs share the same, or very similar, instruction sets. For example, x86 is the name of Intel's instruction set for their 32-bit processors. By keeping the instruction set the same between generations of processors, the exact same software can run on different processors without needing to be modified.
For our super basic CPU, we will be making up our own instruction set (because we are cool like that). Our set will be pretty minimal (16 instructions) and will consist only of the essentials.
There are two important sizes in a CPU. The first, and the one you hear about the most, is the data path size. This determines the largest values that can be operated on at any time. When you hear that a CPU is 8 bit, 32 bit, etc., these are the data path sizes. An 8-bit processor can only operate on 8 bits at a time while a 64-bit processor can operate on eight times that. 
The other important size is the instruction size. Depending on the CPU, these may or may not be the same size, and depending on the instruction set, instructions may actually have varying lengths!
For our CPU, we are going to make it operate on 8 bit data with a 16 bit instruction size. This means all our instructions need to be encoded with 16 bits. By having a fixed instruction size, it is easy to know where the next instruction starts without having to inspect every instruction before it.
Memory</h2>
Before we dive into what our CPU will actually do, we need to figure out how data will get in and out and when it is in, how do we work with it? CPUs typically have a tiny bit of super-duper fast memory built into them. This memory is known as the CPU's registers and serves as the working memory of the CPU. Our CPU will only be able to perform operations directly on its registers. 
So if all the work happens on these registers, how do we process outside data? We need a way to load data into a register and output the value of a register. The interface we will use will be basically the same as the RAM interface in the Hello YOUR_NAME_HERE</a> tutorial. We will specify an address and data (for a write) or an address, and we will receive data (for a read). This will be covered a bit more later. 
For now, know that we have internal memory called registers, and we will have a way to load and store values to/from the outside world.
Operations</h2>
We now need a way to encode the instructions for our CPU. We are going to fit each instruction into 16 bits. The first four bits will be used to encode what the operation is (since we will have 16 operations), and the remaining 12 bits will be unique to each operation. 
The four bits that encode the type of operation are known as the opcode.
Because some of our instructions will require three arguments, that leaves four bits for each argument. If each argument is the address of a register, we can have at most 16 registers without increasing our instruction size.
NOP</h3>
What is the most basic operation you can think of? If you thought of nothing, you win! 
The do nothing instruction, or no operation (often abbreviated to NOP</code>), is going to be our first instruction.
</th> </th></tr></thead>

NOP</td> 0</td></tr> </tbody></table>
This instruction does nothing, so we can just fill the 12 bits with 0.
LOAD and STORE</h3>
As you should recall from only a few lines above, all CPUs need some form of IO. If you can't input data and output results, the CPU would be useless. 
It would be like a fully paralyzed person with no senses. They may have fascinating thoughts, but no one would ever know. 
We can then create two more instructions, LOAD</code> and STORE</code> for loading a value (input) and storing a value (output) respectively.
</th> </th> </th> </th></tr></thead>

LOAD</td> DEST</td> ADDR</td> OFFSET</td></tr>
STORE</td> SRC</td> ADDR</td> OFFSET</td></tr> </tbody></table>
Since the loads and stores need to provide both a value and an address, we need two arguments. 
The DEST</code> argument is the register that will get the value from a LOAD</code>. 
The SRC</code> argument is the register whose value will be output. 
The ADDR</code> argument is the register whose value should be used as the address. 
Finally, OFFSET</code> is a constant that will be added to the value of the ADDR</code> register to get the address. This offset can be convenient to have, but you don't really need it. I added it because there were four extra bits we could do something with.
SET</h3> We will commonly need to set the value of a register to some constant. The SET</code> operation will let us do that. </th> </th> </th></tr></thead> SET</td> DEST</td> CONST</td></tr> </tbody></table> Here DEST</code> is the register that will be set and CONST</code> is the 8-bit value to set it to. Keep in mind that since we are making an 8-bit processor, the registers are 8 bits wide. LT and EQ</h3> We will likely want to be able to compare two different values. To do any comparison, we only need two operators, less-than (LT</code>) and equal (EQ</code>). If we then wanted to perform a greater-than, we could use less-than and flip the arguments. Less-than or equal to (≤) can be achieved by using both. </th> </th> </th> </th></tr></thead> LT</td> DEST</td> OP1</td> OP2</td></tr> EQ</td> DEST</td> OP1</td> OP2</td></tr> </tbody></table> In the LT</code> case the DEST</code> register will be 1</code> if OP1</code> is less than OP2</code> and 0</code> otherwise. EQ</code> is the same, except it checks for equality. BEQ and BNEQ</h3> Typically, a program will execute instruction after instruction. However, it can be really powerful to be able to control the flow. This is where branching instructions are useful. </th> </th> </th></tr></thead> BEQ</td> OP1</td> CONST</td></tr> BNEQ</td> OP1</td> CONST</td></tr> </tbody></table> If register OP1</code> is equal to the value CONST</code> then the BEQ</code> instruction will skip the instruction following it. Otherwise, the program will continue as normal. BNEQ</code> does the same thing but skips is they are not equal. These instructions allow you to create if statements in your code. The ALU</h3> CPUs commonly need to manipulate the values in the registers. Operations like addition, AND, OR, bit shifting, etc. are all typically contained in something called the ALU or Arithmetic Logic Unit. These types of instructions will make up the remainder of our instruction set. </th> </th> </th> </th></tr></thead> ADD</td> DEST</td> OP1</td> OP2</td></tr> SUB</td> DEST</td> OP1</td> OP2</td></tr> SHL</td> DEST</td> OP1</td> OP2</td></tr> SHR</td> DEST</td> OP1</td> OP2</td></tr> AND</td> DEST</td> OP1</td> OP2</td></tr> OR</td> DEST</td> OP1</td> OP2</td></tr> INV</td> DEST</td> OP1</td> 0</td></tr> XOR</td> DEST</td> OP1</td> OP2</td></tr> </tbody></table> ADD</code> and SUB</code> add or subtract OP1</code> and OP2</code> and store the result into DEST</code>. SHL</code> and SHR</code> shift OP1</code> to the right or left by OP2</code> bits and store the result into DEST</code>. AND</code>, OR</code>, and XOR</code> perform their respective bit-wise operations on OP1</code> and OP2</code> and store their result into DEST</code>. INV</code> does a bit-wise inversion of OP1</code> and stores the result into DEST</code>. The Program Counter</h2> We are going to put all the instructions for whatever program we write into a ROM. The ROM will need an address to know what instruction we need. This address will be specified by the program counter. For our CPU, we will use register 0 as our program counter. This will allow us to directly manipulate the flow of the program by messing with its value. The CPU</h1> Now that we have all the pieces, let's take a look at the actual module. You should create a new project using the Base Project template and create a new module named cpu. 1</td> global Inst { </td></tr> 2</td> const NOP = 4d0 // 0 filled </td></tr> 3</td> const LOAD = 4d1 // dest, op1, offset : R[dest] = M[R[op1] + offset] </td></tr> 4</td> const STORE = 4d2 // src, op1, offset : M[R[op1] + offset] = R[src] </td></tr> 5</td> const SET = 4d3 // dest, const : R[dest] = const </td></tr> 6</td> const LT = 4d4 // dest, op1, op2 : R[dest] = R[op1] < R[op2] </td></tr> 7</td> const EQ = 4d5 // dest, op1, op2 : R[dest] = R[op1] == R[op2] </td></tr> 8</td> const BEQ = 4d6 // op1, const : R[0] = R[0] + (R[op1] == const ? 2 : 1) </td></tr> 9</td> const BNEQ = 4d7 // op1, const : R[0] = R[0] + (R[op1] != const ? 2 : 1) </td></tr> 10</td> const ADD = 4d8 // dest, op1, op2 : R[dest] = R[op1] + R[op2] </td></tr> 11</td> const SUB = 4d9 // dest, op1, op2 : R[dest] = R[op1] - R[op2] </td></tr> 12</td> const SHL = 4d10 // dest, op1, op2 : R[dest] = R[op1] << R[op2] </td></tr> 13</td> const SHR = 4d11 // dest, op1, op2 : R[dest] = R[op1] >> R[op2] </td></tr> 14</td> const AND = 4d12 // dest, op1, op2 : R[dest] = R[op1] & R[op2] </td></tr> 15</td> const OR = 4d13 // dest, op1, op2 : R[dest] = R[op1] | R[op2] </td></tr> 16</td> const INV = 4d14 // dest, op1 : R[dest] = ~R[op1] </td></tr> 17</td> const XOR = 4d15 // dest, op1, op2 : R[dest] = R[op1] ^ R[op2] </td></tr> 18</td> } </td></tr> 19</td> </td></tr> 20</td> module cpu ( </td></tr> 21</td> input clk, // clock </td></tr> 22</td> input rst, // reset </td></tr> 23</td> output write, // CPU write request </td></tr> 24</td> output read, // CPU read request </td></tr> 25</td> output address[8], // read/write address </td></tr> 26</td> output dout[8], // write data </td></tr> 27</td> input din[8] // read data </td></tr> 28</td> ) { </td></tr> 29</td> </td></tr> 30</td> .clk(clk), .rst(rst) { </td></tr> 31</td> dff reg[16][8] // CPU Registers </td></tr> 32</td> } </td></tr> 33</td> </td></tr> 34</td> instRom instRom // program ROM </td></tr> 35</td> </td></tr> 36</td> sig op[4] // opcode </td></tr> 37</td> sig arg1[4] // first arg </td></tr> 38</td> sig arg2[4] // second arg </td></tr> 39</td> sig dest[4] // destination arg </td></tr> 40</td> sig constant[8] // constant arg </td></tr> 41</td> </td></tr> 42</td> always { </td></tr> 43</td> // defaults </td></tr> 44</td> write = 0 // don't write </td></tr> 45</td> read = 0 // don't read </td></tr> 46</td> address = 8hxx // don't care </td></tr> 47</td> dout = 8hxx // don't care </td></tr> 48</td> </td></tr> 49</td> instRom.address = reg.q[0] // reg 0 is program counter </td></tr> 50</td> reg.d[0] = reg.q[0] + 1 // increment PC by default </td></tr> 51</td> </td></tr> 52</td> op = instRom.inst[15:12] // opcode is top 4 bits </td></tr> 53</td> dest = instRom.inst[11:8] // dest is next 4 bits </td></tr> 54</td> arg1 = instRom.inst[7:4] // arg1 is next 4 bits </td></tr> 55</td> arg2 = instRom.inst[3:0] // arg2 is last 4 bits </td></tr> 56</td> constant = instRom.inst[7:0] // constant is last 8 bits </td></tr> 57</td> </td></tr> 58</td> // Perform the operation </td></tr> 59</td> case (op) { </td></tr> 60</td> Inst.LOAD: </td></tr> 61</td> read = 1 // request a read </td></tr> 62</td> reg.d[dest] = din // save the data </td></tr> 63</td> address = reg.q[arg1] + arg2 // set the address </td></tr> 64</td> Inst.STORE: </td></tr> 65</td> write = 1 // request a write </td></tr> 66</td> dout = reg.q[dest] // output the data </td></tr> 67</td> address = reg.q[arg1] + arg2 // set the address </td></tr> 68</td> Inst.SET: </td></tr> 69</td> reg.d[dest] = constant // set the reg to constant </td></tr> 70</td> Inst.LT: </td></tr> 71</td> reg.d[dest] = reg.q[arg1] < reg.q[arg2] // less-than comparison </td></tr> 72</td> Inst.EQ: </td></tr> 73</td> reg.d[dest] = reg.q[arg1] == reg.q[arg2] // equals comparison </td></tr> 74</td> Inst.BEQ: </td></tr> 75</td> if (reg.q[dest] == constant) // if R[dest] == constant </td></tr> 76</td> reg.d[0] = reg.q[0] + 2 // skip next instruction </td></tr> 77</td> Inst.BNEQ: </td></tr> 78</td> if (reg.q[dest] != constant) // if R[dest] != constant </td></tr> 79</td> reg.d[0] = reg.q[0] + 2 // skip next instruction </td></tr> 80</td> Inst.ADD: </td></tr> 81</td> reg.d[dest] = reg.q[arg1] + reg.q[arg2] // addition </td></tr> 82</td> Inst.SUB: </td></tr> 83</td> reg.d[dest] = reg.q[arg1] - reg.q[arg2] // subtraction </td></tr> 84</td> Inst.SHL: </td></tr> 85</td> reg.d[dest] = reg.q[arg1] << reg.q[arg2] // shift left </td></tr> 86</td> Inst.SHR: </td></tr> 87</td> reg.d[dest] = reg.q[arg1] >> reg.q[arg2] // shift right </td></tr> 88</td> Inst.AND: </td></tr> 89</td> reg.d[dest] = reg.q[arg1] & reg.q[arg2] // bit-wise AND </td></tr> 90</td> Inst.OR: </td></tr> 91</td> reg.d[dest] = reg.q[arg1] | reg.q[arg2] // bit-wise OR </td></tr> 92</td> Inst.INV: </td></tr> 93</td> reg.d[dest] = ~reg.q[arg1] // bit-wise invert </td></tr> 94</td> Inst.XOR: </td></tr> 95</td> reg.d[dest] = reg.q[arg1] ^ reg.q[arg2] // bit-wise XOR </td></tr> 96</td> } </td></tr> 97</td> } </td></tr> 98</td> } </td></tr></tbody></table></code></pre> The astute observer will notice that the entire CPU file is less than 100 lines long! It's pretty amazing how much functionality you can get with such a simple design. Take a look at the global</code> block at the beginning of the file. 1</td> global Inst { </td></tr> 2</td> const NOP = 4d0 // 0 filled </td></tr> 3</td> const LOAD = 4d1 // dest, op1, offset : R[dest] = M[R[op1] + offset] </td></tr> 4</td> const STORE = 4d2 // src, op1, offset : M[R[op1] + offset] = R[src] </td></tr> 5</td> const SET = 4d3 // dest, const : R[dest] = const </td></tr> 6</td> const LT = 4d4 // dest, op1, op2 : R[dest] = R[op1] < R[op2] </td></tr> 7</td> const EQ = 4d5 // dest, op1, op2 : R[dest] = R[op1] == R[op2] </td></tr> 8</td> const BEQ = 4d6 // op1, const : R[0] = R[0] + (R[op1] == const ? 2 : 1) </td></tr> 9</td> const BNEQ = 4d7 // op1, const : R[0] = R[0] + (R[op1] != const ? 2 : 1) </td></tr> 10</td> const ADD = 4d8 // dest, op1, op2 : R[dest] = R[op1] + R[op2] </td></tr> 11</td> const SUB = 4d9 // dest, op1, op2 : R[dest] = R[op1] - R[op2] </td></tr> 12</td> const SHL = 4d10 // dest, op1, op2 : R[dest] = R[op1] << R[op2] </td></tr> 13</td> const SHR = 4d11 // dest, op1, op2 : R[dest] = R[op1] >> R[op2] </td></tr> 14</td> const AND = 4d12 // dest, op1, op2 : R[dest] = R[op1] & R[op2] </td></tr> 15</td> const OR = 4d13 // dest, op1, op2 : R[dest] = R[op1] | R[op2] </td></tr> 16</td> const INV = 4d14 // dest, op1 : R[dest] = ~R[op1] </td></tr> 17</td> const XOR = 4d15 // dest, op1, op2 : R[dest] = R[op1] ^ R[op2] </td></tr> 18</td> } </td></tr></tbody></table></code></pre> This block allows us to define constants that can be used in any Lucid file in our project. This is helpful since we will be using these in our instruction ROM. The name you give a global</code> block is the namespace that its contents live in. To access a globally defined constant, you use the syntax Namespace.CONST</code>. The name of a namespace needs to start with a capital and contain at least one lowercase letter. 30</td> .clk(clk), .rst(rst) { </td></tr> 31</td> dff reg[16][8] // CPU Registers </td></tr> 32</td> } </td></tr></tbody></table></code></pre> Our CPU's registers are nothing other than a set of dff</code>. We use a 2D array of 16 by 8 since we want 16 registers with a width of 8 bits. 34</td> instRom instRom // program ROM </td></tr></tbody></table></code></pre> We can't forget our program ROM! We will cover the actual ROM in a bit. However, it has only two ports, address</code> and inst</code>. It outputs the corresponding instruction on inst</code> for the given address</code>. 37</td> // defaults </td></tr> 38</td> write = 0 // don't write </td></tr> 39</td> read = 0 // don't read </td></tr> 40</td> address = 8hxx // don't care </td></tr> 41</td> dout = 8hxx // don't care </td></tr></tbody></table></code></pre> In the beginning of an always</code> block, it is a good idea to assign defaults at the top so you don't have to worry about assigning a value in every possible conditional branch. In this case, by default we don't want to perform a read or write, and if we aren't performing a read or write, we don't care what the values of address</code> or dout</code> are. 43</td> instRom.address = reg.q[0] // reg 0 is program counter </td></tr> 44</td> reg.d[0] = reg.q[0] + 1 // increment PC by default </td></tr></tbody></table></code></pre> We decided to use the first register as our program counter. This means we are going to feed its value into the instruction ROM. We also need to increment it each cycle so that our program continues to execute. Since the line to perform the increment comes before the code to execute the instruction, if the instruction writes to the first register, it will have precedence over the increment. This will allow us to manipulate the program counter with our code. 46</td> sig op[4] = instRom.inst[15:12] // opcode is top 4 bits </td></tr> 47</td> sig dest[4] = instRom.inst[11:8] // dest is next 4 bits </td></tr> 48</td> sig arg1[4] = instRom.inst[7:4] // arg1 is next 4 bits </td></tr> 49</td> sig arg2[4] = instRom.inst[3:0] // arg2 is last 4 bits </td></tr> 50</td> sig constant[8] = instRom.inst[7:0] // constant is last 8 bits </td></tr></tbody></table></code></pre> These signals aren't strictly needed, but they help make the code a bit more readable by allowing us to rename parts of the instruction. The way we defined our instruction set, the opcode is always the four most-significant bits. The other four signals are just the common names for the different parts of the instruction. 52</td> // Perform the operation </td></tr> 53</td> case (op) { </td></tr> 54</td> Inst.LOAD: </td></tr> 55</td> read = 1 // request a read </td></tr> 56</td> reg.d[dest] = din // save the data </td></tr> 57</td> address = reg.q[arg1] + arg2 // set the address </td></tr> 58</td> Inst.STORE: </td></tr> 59</td> write = 1 // request a write </td></tr> 60</td> dout = reg.q[dest] // output the data </td></tr> 61</td> address = reg.q[arg1] + arg2 // set the address </td></tr> 62</td> Inst.SET: </td></tr> 63</td> reg.d[dest] = constant // set the reg to constant </td></tr> 64</td> Inst.LT: </td></tr> 65</td> reg.d[dest] = reg.q[arg1] < reg.q[arg2] // less-than comparison </td></tr> 66</td> Inst.EQ: </td></tr> 67</td> reg.d[dest] = reg.q[arg1] == reg.q[arg2] // equals comparison </td></tr> 68</td> Inst.BEQ: </td></tr> 69</td> if (reg.q[dest] == constant) // if R[dest] == constant </td></tr> 70</td> reg.d[0] = reg.q[0] + 2 // skip next instruction </td></tr> 71</td> Inst.BNEQ: </td></tr> 72</td> if (reg.q[dest] != constant) // if R[dest] != constant </td></tr> 73</td> reg.d[0] = reg.q[0] + 2 // skip next instruction </td></tr> 74</td> Inst.ADD: </td></tr> 75</td> reg.d[dest] = reg.q[arg1] + reg.q[arg2] // addition </td></tr> 76</td> Inst.SUB: </td></tr> 77</td> reg.d[dest] = reg.q[arg1] - reg.q[arg2] // subtraction </td></tr> 78</td> Inst.SHL: </td></tr> 79</td> reg.d[dest] = reg.q[arg1] << reg.q[arg2] // shift left </td></tr> 80</td> Inst.SHR: </td></tr> 81</td> reg.d[dest] = reg.q[arg1] >> reg.q[arg2] // shift right </td></tr> 82</td> Inst.AND: </td></tr> 83</td> reg.d[dest] = reg.q[arg1] & reg.q[arg2] // bit-wise AND </td></tr> 84</td> Inst.OR: </td></tr> 85</td> reg.d[dest] = reg.q[arg1] | reg.q[arg2] // bit-wise OR </td></tr> 86</td> Inst.INV: </td></tr> 87</td> reg.d[dest] = ~reg.q[arg1] // bit-wise invert </td></tr> 88</td> Inst.XOR: </td></tr> 89</td> reg.d[dest] = reg.q[arg1] ^ reg.q[arg2] // bit-wise XOR </td></tr> 90</td> } </td></tr></tbody></table></code></pre> Here we execute the instruction. You may be surprised how simple this is. We use a case</code> statement to select what behavior we want. When op</code> matches a specific instruction, the corresponding branch of the case</code> statement is evaluated. The Program</h1> Now that we have a CPU, we need to write a program for it. Before getting deep into it, let's get something running to make sure everything is working. Create a new module instRom</code> and paste in the following. 1</td> module instRom ( </td></tr> 2</td> input address[8], </td></tr> 3</td> output inst[16] </td></tr> 4</td> ) { </td></tr> 5</td> </td></tr> 6</td> always { </td></tr> 7</td> inst = c{Inst.NOP, 12b0} </td></tr> 8</td> </td></tr> 9</td> case (address) { </td></tr> 10</td> // begin: </td></tr> 11</td> 0: inst = c{Inst.SET, 4d2, 8d0} // SET R2, 0 </td></tr> 12</td> // loop: </td></tr> 13</td> 1: inst = c{Inst.SET, 4d1, 8d128} // SET R1, 128 </td></tr> 14</td> 2: inst = c{Inst.STORE, 4d2, 4d1, 4d0} // STORE R2, R1, 0 </td></tr> 15</td> 3: inst = c{Inst.SET, 4d1, 8d1} // SET R1, 1 </td></tr> 16</td> 4: inst = c{Inst.ADD, 4d2, 4d2, 4d1} // ADD R2, R2, R1 </td></tr> 17</td> 5: inst = c{Inst.SET, 4d15, 8d1} // SET R15, loop </td></tr> 18</td> 6: inst = c{Inst.SET, 4d0, 8d7} // SET R0, delay </td></tr> 19</td> // delay: </td></tr> 20</td> 7: inst = c{Inst.SET, 4d11, 8d0} // SET R11, 0 </td></tr> 21</td> 8: inst = c{Inst.SET, 4d12, 8d0} // SET R12, 0 </td></tr> 22</td> 9: inst = c{Inst.SET, 4d13, 8d0} // SET R13, 0 </td></tr> 23</td> 10: inst = c{Inst.SET, 4d1, 8d1} // SET R1, 1 </td></tr> 24</td> // delay_loop: </td></tr> 25</td> 11: inst = c{Inst.ADD, 4d11, 4d11, 4d1} // ADD R11, R11, R1 </td></tr> 26</td> 12: inst = c{Inst.BEQ, 4d11, 8d0} // BEQ R11, 0 </td></tr> 27</td> 13: inst = c{Inst.SET, 4d0, 8d11} // SET R0, delay_loop </td></tr> 28</td> 14: inst = c{Inst.ADD, 4d12, 4d12, 4d1} // ADD R12, R12, R1 </td></tr> 29</td> 15: inst = c{Inst.BEQ, 4d12, 8d0} // BEQ R12, 0 </td></tr> 30</td> 16: inst = c{Inst.SET, 4d0, 8d11} // SET R0, delay_loop </td></tr> 31</td> 17: inst = c{Inst.ADD, 4d13, 4d13, 4d1} // ADD R13, R13, R1 </td></tr> 32</td> 18: inst = c{Inst.BEQ, 4d13, 8d0} // BEQ R13, 0 </td></tr> 33</td> 19: inst = c{Inst.SET, 4d0, 8d11} // SET R0, delay_loop </td></tr> 34</td> 20: inst = c{Inst.SET, 4d1, 8d0} // SET R1, 0 </td></tr> 35</td> 21: inst = c{Inst.ADD, 4d0, 4d15, 4d1} // ADD R0, R15, R1 </td></tr> 36</td> } </td></tr> 37</td> } </td></tr> 38</td> } </td></tr></tbody></table></code></pre> This code will slowly increment a counter and output it to address 128. We will go over the details of it a bit later, but first let us hook it up to the LEDs. 1</td> module alchitry_top ( </td></tr> 2</td> input clk, // 100MHz clock </td></tr> 3</td> input rst_n, // reset button (active low) </td></tr> 4</td> output led[8], // 8 user controllable LEDs </td></tr> 5</td> input usb_rx, // USB->Serial input </td></tr> 6</td> output usb_tx // USB->Serial output </td></tr> 7</td> ) { </td></tr> 8</td> </td></tr> 9</td> sig rst // reset signal </td></tr> 10</td> </td></tr> 11</td> .clk(clk) { </td></tr> 12</td> // The reset conditioner is used to synchronize the reset signal to the FPGA </td></tr> 13</td> // clock. This ensures the entire FPGA comes out of reset at the same time. </td></tr> 14</td> reset_conditioner reset_cond </td></tr> 15</td> </td></tr> 16</td> .rst(rst) { </td></tr> 17</td> cpu cpu // our snazzy CPU </td></tr> 18</td> dff led_reg[8] // storage for LED value </td></tr> 19</td> } </td></tr> 20</td> } </td></tr> 21</td> </td></tr> 22</td> always { </td></tr> 23</td> reset_cond.in = ~rst_n // input raw inverted reset signal </td></tr> 24</td> rst = reset_cond.out // conditioned reset </td></tr> 25</td> </td></tr> 26</td> led = led_reg.q // connect LEDs to led_reg </td></tr> 27</td> </td></tr> 28</td> usb_tx = usb_rx // echo the serial data </td></tr> 29</td> </td></tr> 30</td> cpu.din = 8hxx // default to don't care </td></tr> 31</td> </td></tr> 32</td> // if cpu uses address 128 </td></tr> 33</td> if (cpu.address == 128) { </td></tr> 34</td> if (cpu.write) </td></tr> 35</td> led_reg.d = cpu.dout // update the LED value </td></tr> 36</td> if (cpu.read) </td></tr> 37</td> cpu.din = led_reg.q // let the CPU read the LED value </td></tr> 38</td> } </td></tr> 39</td> } </td></tr> 40</td> } </td></tr></tbody></table></code></pre> In alchitry_top</code> we need to add the CPU and a dff</code> to hold the value for the LEDs. When the CPU writes to address 128</code>, we can save the value in the dff</code> and connect that to the LEDs. This way, the CPU can directly control the LEDs by writing to this address! Why use address 128</code>? In practice, we could have chosen any address, but the reason we used 128</code> instead of, say 0</code>, is because the first half of the address space is typically reserved for RAM. Our CPU doesn't currently have access to RAM, but we could hook it up to some. Using a memory interface like this to perform IO is known as memory mapped IO. This is how basically all CPUs perform IO. If you've ever worked with AVRs and written something like PORTA = 0x5A;</code>, PORTA</code> is actually just a special memory address that instead of writing to RAM writes to the IO port (exactly what we are doing here). Go ahead and build/load the project to your board. The LEDs should now count slowly. The Assembler</h1> While we could write the instRom</code> module ourselves to create programs, but it becomes a huge pain to edit them. If you want to insert an instruction, you have to renumber everything. It is a nightmare. Luckily, we don't have to! I wrote a basic assembler for us (you're welcome ❤️). You can find the assembler code on GitHub</a>. If you just want to download the runnable JAR you can click here</a>. It should run on any OS with Java 1.7 or later. I used ANTLR</a> to parse the assembly. This is an awesome library that makes writing something like this pretty easy. To use the assembler, use the following command. java -jar skinny-asm.jar assembly-file.asm </code></pre> It should then turn your assembly in assembly-file.asm</code> into the instRom</code> module, or tell you what's wrong with your file. Here is the assembly file I used to generate the ROM from earlier. 1</td> begin: </td></tr> 2</td> SET R2, 0 // R2 = 0 </td></tr> 3</td> loop: </td></tr> 4</td> SET R1, 128 // R1 = 128 </td></tr> 5</td> STORE R2, R1, 0 // M[128] = R2 </td></tr> 6</td> SET R1, 1 // R1 = 1 </td></tr> 7</td> ADD R2, R2, R1 // R2++ </td></tr> 8</td> SET R15, loop // R15 = loop, R15 is return address </td></tr> 9</td> SET R0, delay // goto delay </td></tr> 10</td> delay: </td></tr> 11</td> SET R11, 0 // R11 = 0 </td></tr> 12</td> SET R12, 0 // R12 = 0 </td></tr> 13</td> SET R13, 0 // R13 = 0 </td></tr> 14</td> SET R1, 1 // R1 = 1 </td></tr> 15</td> delay_loop: </td></tr> 16</td> ADD R11, R11, R1 // R11++ </td></tr> 17</td> BEQ R11, 0 // skip next if (R11 == 0) </td></tr> 18</td> SET R0, delay_loop // goto delay_loop </td></tr> 19</td> ADD R12, R12, R1 // R12++ </td></tr> 20</td> BEQ R12, 0 // skip next if (R12 == 0) </td></tr> 21</td> SET R0, delay_loop // goto delay_loop </td></tr> 22</td> ADD R13, R13, R1 // R13++ </td></tr> 23</td> BEQ R13, 0 // skip next if (R13 == 0) </td></tr> 24</td> SET R0, delay_loop // goto delay_loop </td></tr> 25</td> SET R1, 0 // R1 = 0 </td></tr> 26</td> ADD R0, R15, R1 // R0 = R15 (return) </td></tr></tbody></table></code></pre> There are two types of lines that the assembler will accept, labels and instructions. A label is simply a name followed by a :</code>. These act as constants that will be replaced with the line number of the instruction following it. For example, the label begin</code> in the above code will have value 0</code> since it is before the first instruction. These make it easy to reference instructions without having to rely on fixed numbers (to avoid the insert problem). Instructions consist of the name of the opcode followed by a list of comma-separated arguments. Constants can either be a decimal number or a label. Registers take the form R#</code> where #</code> is the register number. Writing Code</h1> While our CPU only treats R0</code> specially (it's the program counter), it is helpful to assign special roles to some registers for use in our programs. For example, for many instructions it can be handy to have a temporary register to load a constant into. I used R1</code> for this purpose. The other special register I used was R15</code> to store the return address from a function call (more on this later). The goal of this program was to count and output the count to address 128</code>. Since we have no external RAM, all our memory needs to fit in the 16 registers. I chose R2</code> to store our primary counter. The first line initializes R2</code> to 0</code>, we then enter the main loop. The main loop starts by writing R2</code> to address 128</code>. R1</code> is used to store the constant 128</code> used as the address for the STORE</code> instruction. We then increment R2</code> by one. Again, we use R1</code> to store the constant 1</code> to add to R2</code>. We could simply loop here. However, it would count way too fast for us to see on the LEDs. So we need to create a delay function. A function is just a block of code that can be called from anywhere and will return to where it's called from. We use R15</code> to specify the address we want to return to. In our case, we cheat a little bit and set R15</code> to the beginning of our loop instead of the instruction after the call to delay</code>. This is just a little more efficient. We can use the SET</code> instruction with R0</code> to jump to anywhere in our program. This is where labels are really helpful since we don't care what the actual instruction number is as the label will get replaced with the proper value. The delay function uses R11</code>, R12</code>, and R13</code> to count from 0 to 16,777,215. This takes a decent amount of time so we can actually see the LEDs change. Once the counter overflows, the delay function returns to the address in R15</code> using the ADD</code> instruction to set R0</code> to R15</code>. Try editing this code, or write your own program! Feel free to even swap out some instructions for your own if you can think of something more useful. Maybe you'd rather have an instruction for directly setting a bit instead of XOR, or maybe you would rather be able to tell if a value is even instead of shifting right. That's it for this tutorial. I hope you enjoyed making a basic CPU! It's pretty awesome to write code for hardware that you designed! Go make something awesome! Vivado Setup 2025-07-29T00:00:00+00:00 The first step to setting up your environment is to install Vivado. Vivado is a program provided by Xilinx (the manufacture of the FPGA on the Au) that is used to build your projects. It holds all the secret sauce that converts your text into an FPGA configuration file (bin file). Head over to Xilinx's website and download the Vivado here</a>. Avoid version 2020.3. I recommend downloading the Web Installer as it will save you time. As of 2024.1, it they only offer the Web Installer. During installation, you get to select what gets installed saving space as well. You will need to create an account with Xilinx to download the software. This is required by the U.S. government since the software falls under some export regulations. You will also need this account during installation for the web installer to be able to download the various components. Launching the Installer</h2> If you are running Windows, double-click the .exe file that you downloaded. If you are on Linux, you may need to add execution privileges to the .bin file. You can do that with the following command. chmod +x Xilinx_Vivado_File.bin </code></pre> You will need to change the name of the .bin file to match the on you downloaded. You can then run it. You don't need root permissions if you are installing it somewhere you already have write permissions. I usually install mine to /opt/Xilinx</code> which I have set up to be owned by me. Installing</h2> The installer itself is pretty straight forward. First, you will have to log in to your account. You'll then have to accept some terms and conditions. The page after that asks what product you would like to install. Select Vivado. The next page asks what edition to install. If you don't want to pay for a license, select the Standard version. The main difference between the two (other than cost) is the devices that are supported. The free tier supports all the Alchitry boards. The next page allows you to choose what you install. The import option in our case is the Artix-7 FPGAs box under 7 Series under Devices. Nothing else is strictly required. On the next page, select where you want to install it. Now wack that Install button and let it do its thing. When you go to use Alchitry Labs, you'll need to point it to where Vivado is installed via the settings. In my case, I pointed it to /opt/Xilinx/2025.1/Vivado</code>. Register Interface 2025-04-28T00:00:00+00:00 This tutorial will introduce you to the Register Interface component and how you can use it to easily implement complex interfaces in your designs. Pinouts and Custom Elements 2025-02-25T00:00:00+00:00 This tutorial goes over all the information you need to create your own custom elements. Alchitry Constraints Reference 2025-02-04T00:00:00+00:00 This page is a reference for Alchitry Constraints V2. Lucid Reference 2025-02-04T00:00:00+00:00 This page is a reference to the Lucid V2 language. Alchitry Labs V2.0.24 - Negative Indices 2025-01-24T00:00:00+00:00 Alchitry Labs V2.0.24-BETA</a> is now out bringing many updates from the last blog post on 2.0.21. Alchitry Labs V2.0.21 - Alchitry Constraints Updated 2024-12-26T00:00:00+00:00 Alchitry Labs V2.0.21-BETA</a> just dropped with support for the new Alchitry V2 boards</a>. To properly support the new boards, the format for Alchitry Constraint Files (ACF) was updated. Alchitry V2 - Production Begins 2024-12-09T00:00:00+00:00 It has been a busy couple of months and things are starting to come together! Alchitry V2 - All New Boards 2024-11-13T00:00:00+00:00 It's official, all the boards are being redesigned into a new form factor. Alchitry Platinum and Board Rework 2024-10-09T00:00:00+00:00 The Alchitry Platinum (Pt), is in the early stages of design. This version will most likely be based on the XC7A100T-2FGG484C FPGA. Alchitry Labs V2 - snake_case 2024-09-23T00:00:00+00:00 Alchitry Labs V2.0.17 just release and is a major shift from previous releases. snake_case#</a> </h1> When starting on Lucid V2, I had originally though to make camelCase</code> the default style for names. However, I think this was a poor choice for a few reasons and decided to switch to snake_case</code>. The biggest reason to use snake_case</code> is because this is what is used by Verilog. All the Xilinx tools use snake_case</code> so when mixing Lucid and Verilog it is nicer to have a consistent style. Lucid V1 was also mostly documented in snake_case</code> but the styling wasn't super consistent. This is what made me think to switch in the first place. I generally prefer the aesthetics of camelCase</code>, but writing rst_n</code> as rstN</code> is just awful. Adding a _n</code> or _p</code> suffix to names is common with differential signals (as seen in the DDR3 MIG module). Single letters are hard to discern in camelCase</code> and are much better in snake_case</code>. What Changed#</a> </h1> In V2.0.17, all the components and example projects switched to use snake_case</code> for names. Functions names also changed so $silentTick()</code> became $silent_tick()</code>. The keyword testBench</code> also changed to testbench</code>. It seems a bit inconsistent if the word testbench is two words or one, but it seems like it is more often seen as one. I also thought using test_bench</code> as a keyword felt weird. Auto-migration#</a> </h2> If you open an older project with Alchitry Labs V2.0.17 or newer, it will automatically migrate your code. This means files will be renamed and all camelCase</code> will be replaced with snake_case</code>. Also, in the Io constraints and examples ioSel</code> became io_select</code> and ioSeg</code> became io_segment</code> for clarity. The migration will change these names as well. I'm sorry for any inconvenience this causes to anyone already using Alchitry Labs V2, but I believe in the long run this is the better choice. I'll be updating the tutorials and documentation today to reflect these changes. DDR3 Memory 2024-09-23T00:00:00+00:00 In this tutorial we are going to set up an interface to the DDR3 memory with the FPGA on the Alchitry Au or Pt. Hello YOUR_NAME_HERE 2024-09-19T00:00:00+00:00 In this tutorial we will be personalizing the greeter so that it first asks for your name and then prints "Hello NAME" where NAME is the name you entered. To do this we will need some form of memory and in this case we will use a single port RAM. ROMs and FSMs 2024-09-19T00:00:00+00:00 In this tutorial we will create a project that will send "Hello World!" over the USB (serial) port when the letter "h" is received. This will help teach you how to use finite state machines (FSM). Serial Interface 2024-09-19T00:00:00+00:00 In this tutorial we will use the USB port and create a project that will echo back all the data sent to the Alchitry board. This will teach you how to use the Component Library in your projects. Io Element 2024-09-18T00:00:00+00:00 This tutorial will introduce the Io Element</a> and walk through some basic examples to get your feet wet. If you don't own an Io Element, you can still follow along using the simulator. Synchronous Logic 2024-09-17T00:00:00+00:00 In this tutorial you will be introduced to the D flip-flop and how you can use these to make an LED blink. Alchitry Labs V2 - Now in Beta! 2024-09-16T00:00:00+00:00 Alchitry Labs V2.0.14 is now released, and with it the status of the project changes from preview to beta! You can download it here</a> and help out by reporting any issues you encounter to the GitHub issues page</a>. What's New#</a> </h1> Before getting into the technical details of V2, lets look at the fun stuff, what's new. The first thing you're likely to notice is the UI has been revamped. It is based on a modern UI toolkit that allows for easy animations, Sublime-style scroll bars, interactive virtual boards, and drag-and-drop window splitting. Alchitry Labs V2 supports the new Lucid V2</a>. See the V1 vs V2 blog post</a> for a summary of what has changed. Support for Lucid V2 is so much deeper than Lucid V1 ever was. Alchitry Labs now creates a full model of your Lucid code. This causes plenty of errors that would just fly under the radar in V1 to be caught and reported in real-time. It also allows for your project to be simulated. Simulations#</a> </h2> By clicking the little bug icon, you can launch the simulator. It currently supports the base board (Au, Au+, or Cu) as well as the Io. The simulator is an interactive virtual board running your design. You can toggle the DIP switches or press the buttons by clicking on them. PWM effects are also simulated on LEDs allowing for fade effects or multiplexing of the Io element's 7-segment displays. The only real catch is the simulator can't run as fast as dedicated hardware. By default, it runs at 1KHz which is a fair bit slower than the 100MHz clock on the real board. However, many educational designs don't need a fast clock. Hopefully, the Io simulator will make learning the basics that much easier. Test Benches#</a> </h3> Alchitry Labs V2 supports test benches. These allow you test out Lucid modules to make sure they are doing what you expect them to do. In a test block, you can manipulate the values feeding into a module then check their outputs. In the event that things didn't go according to plan, the values of every signal at every step of the simulation are saved, and you can view them after it finishes. See the test bench blog post</a> for more details. Open Source Tools#</a> </h2> Using the open source tools (yosys</a>, nextpnr</a>, icestorm</a>) for the Cu has never been easier. Alchitry Labs V1 had support for some of the older open source tools, but you had to install them yourself. V2 now comes with the open source tools so you can use them out of the box for the Cu. This also means that you can now build projects for the Cu natively on a Mac! Currently, the open source tools don't support the Artix 7 used on the Au, but they are in development</a>. All The Small Things#</a> </h2> Alchitry Labs V2 has been in the works for over two years now. There are way too many things to list here that has changed. Most of the important changes are under the hood and will allow future improvements to continue in a sustainable way. I hope you'll head over to the download page</a> and check it out. You can leave any general feedback on the discussions page</a> and report any issues to the issues page</a>. Why V2#</a> </h1> Alchitry Labs was originally the Mojo IDE. The goal of the Mojo IDE was to both create an IDE with creature comforts like real-time syntax error checking and support a new HDL, Lucid, to make programming FPGAs more accessible. The initial Lucid support was very basic. The IDE would show any syntax errors, but nothing more in depth than that. The focus was on creating a Lucid -> Verilog translator so you could even use it. Only later, more indepth parsing was added. At first, only the widths of signals and expressions were checked. It was able to warn you if an assignment would truncate your value. Over time, the types of errors being checked continued to grow. Eventually, it was doing full parsing of constant values. This lead to the idea that the parser could be used to simulate Lucid. All you have to do is run it over and over right... right? Turned out to be a tad more complicated. When looking into how to actually turn the parser into a simulator, it was clear the pile of tech debt had grown too much to ignore any longer. I started writing the Mojo IDE a decade ago during my junior year of college. It was by far the biggest piece of software I had written and I made plenty of questionable design choices. To make any meaningful improvements, a full rewrite looked like the only practical way forward. New Tools#</a> </h2> Since things were starting over, I was able to overhaul the GUI. V1 was based on the aging SWT. V2 is based on Compose. While I appreciated that SWT kept the look and feel of the native desktop environment, Compose is enormously more flexible. The new interactive virtual boards would have been incredibly difficult to pull off with SWT. The other major shift is that V2 is pure Kotlin. I was notoriously bad at checking for null values in the original Java based parser causing a vast number of bugs that would simply crash the IDE. Kotlin's built-in null safety has been incredibly helpful. Kotlin's other features, like coroutines, have also been instrumental for building out the simulator in an efficient manner. The last fundamental change was in the build system. Before V2, building distributables was a nightmare. It was a multistep error-prone process including firing up a Windows VM to build the Windows executable and installer. This inherently lead to infrequent updates since they were such a pain. The new system relies on Hydraulic Conveyor</a>. This software is awesome. It lets me build and publish distributables for Windows, Linux, and Mac, with one click from Linux. It is also free for open source software. What's Next#</a> </h1> With the beta released, the next step is to update the tutorials. I'll be working on the first few this week. Looking back at the V1 tutorials, I'm a bit disappointed I never got into the depth I should have. I'm planning to rectify that with V2. These will go hand in hand with work on the IDE. The best place to see what's coming is the issues page</a>. Your First FPGA Project 2024-09-16T00:00:00+00:00 This tutorial will walk you through creating your first project in Alchitry Labs and making the onboard LED light up when you press the reset button. Alchitry Labs V2.0.13 - Verilog Interoperability 2024-08-28T00:00:00+00:00 Today version V2.0.13</a> of Alchitry Labs was released! Verilog Interoperability#</a> </h1> A ton has changed/been added since the last post about V2.0.8</a>. The biggest feature, by far, is the addition of Verilog interoperability. You can now add Verilog modules and instantiate them from Lucid. This was an important missing feature to allow for vendor specific things to be easily integrated into Lucid projects. For example, in a Verilog module, you can instantiate the primitives outlined in UG953</a> for the Au/Au+. This is important for stuff like the upcoming Alchitry Hd that utilizes the OSERDESE2</code> primitive to output HDMI video data. While the entire Verilog module is checked for syntax error in the editor, Alchitry Labs doesn't look at the content inside the Verilog modules. It only ever looks at the module interface (parameters and ports). This means that Verilog inside Alchitry Labs has a lot less guards in place and should only really be used as glue to existing Verilog. It also has the major downside that Verilog modules are essentially ignored during simulations. String Indexing#</a> </h1> To make Verilog smoothly interoperate with Lucid, the indexing for strings was reverted to how it worked in Lucid V1. That is, the right-most letter is index 0 instead of the left-most. For example, the string "Hello"</code> in Lucid is represented as an [5][8]</code> array where index [0]</code> points to "o"</code>. In V2.0.12 and earlier, index [0]</code> pointed to "H"</code>. You can use the $reverse()</code> function to restore the indexing to the previous behavior. Verilog uses the right-side indexing so it now matches. This was important for passing strings as parameters which is often done with Xilinx's primitives. Before this change, the Verilog side would see the strings as reversed causing them not to be recognized. While having the right side of string be index 0 seems a little strange, it does nicely match how arrays and everything else are indexed. Now, the right side is always index 0. Build Flow#</a> </h1> The way projects are built underwent a huge change. Previously, when building a project, the tools would start with the top-level module and build out a tree of all instantiated modules underneath it. This has the huge benefit of knowing what all the parameter values are as they must be specified at this point. The big downside of this, is that a separate Verilog translation needs to happen for every different combination of parameters on a module. For example, if you used a counter module and set it's parameter #SIZE(8)</code> but in another location used the counter with #SIZE(16)</code> then two separate Verilog modules would have been generated. This was a fairly small downside to making all constant values calculable when converting to Verilog. However, it has the big downside of making it impossible to call a Lucid module directly from Verilog. In the new version, each module is translated to Verilog in isolation properly using parameters. This makes it possible for Lucid modules to be used inside Verilog modules. It also likely helps the build tools to do things more optimally. $isSim()</code>#</a> </h1> A new function, $isSim()</code>, was introduced. This function evaluates to 1b1</code> if running in an interactive simulation and 1b0</code> otherwise. This is useful for dealing with the much slower clock speeds when running an interactive simulation (usually around 1,000 Hz instead of 100,000,000 Hz). For example, providing a different DIV</code> parameter value to a multiSevenSeg</code> module with the following makes the display work well in simulation and builds. multiSevenSeg seg (#DIV($isSim() ? 1 : 16)) </code></pre> Note that $isSim()</code> evaluates to 1b0</code> during test benches. Beta Release#</a> </h1> Things are getting pretty close to the release of V2.1.0 which will mark the first beta release. Check out the V2.1.0 Milestone on GitHub</a> to track the remaining features to be added before the release. If you're using the preview builds and run into any issues, be sure to report them on GitHub</a> so I can get them fixed ASAP! Alchitry Labs V2.0.8 2024-05-14T00:00:00+00:00 Yesterday version 2.0.8 of Alchitry Labs</a> was released. It's been a while since 2.0.7 was released, so I'll do my best not to miss any import updates. First off, there is now an official Lucid V2 Reference</a>. This page should be able to answer any questions you have about the details of Lucid V2. Known Values#</a> </h1> A major refactoring was done for determining if a value is constant. The old code would keep track of if a value was constant or not with a simple boolean. This became a problem when working with repeat</code> blocks. The issue is that the loop variable isn't constant but it is known during synthesis and should be able to be used like a constant. To fix this, the state of an expression is now marked as dynamic, known, or constant. An important example of this is in the binToDec</code> component that uses the $pow()</code> function with a loop variable. sig scale[$width(value)] = $pow(10, j) // get the scale for the digit </code></pre> The value of j</code> is different for each loop iteration but can be replaced with a constant during synthesis. The $pow()</code> function accepts arguments that are known. Updated Repeat Block#</a> </h1> The repeat</code> block has been modified a bit. The old syntax was repeat(count, i)</code> where count</code> was the number of times to loop and i</code> was the optional loop variable that would be between 0</code> and count-1</code>. The repeat block can now take the form repeat(count)</code> where count</code> is the number of loops and there is no loop variable (like before). However, it can also take the form repeat(i, count, start, step)</code> where i</code> and count</code> are as before (but switched positions). The parameters start</code> and step</code> are optional and specify the starting value and amount to increment by each loop. If omitted they default to start = 0</code> and step = 1</code>. Note that this is a breaking change as the form repeat(count, i)</code> is now repeat(i, count)</code>. Component Library#</a> </h1> The component library has been added. It can be accessed by the three box icon in the main toolbar. Components are now designated in the project tree buy the same three box icon. Example Projects#</a> </h1> In addition to the components being added, the project templates have been added as well. This means you can easily start a project for the Io with the Io Base or Io Demo templates. Toolchain Settings#</a> </h1> A settings menu was added under the main drop down that is accessed by click on the Alchitry logo. Currently, it is populated with the toolchain settings. These let you select the locations for your Vivado and iCEcube2 installs. There is also an option to toggle between the built in Yosys toolchain or iCEcube2 when working with the Cu. The Yosys toolchain was updated in the Linux build to not require that a specific version of Python be installed. iCEcube2 No Longer Free 2024-04-17T00:00:00+00:00 </div> Lattice has since added a note about free licenses for "hobbyists, enthusiasts, community educators & start-up companies." See the Licensing section at the bottom of this page</a>. </div> </div> It appears that Lattice Semiconductors, the manufacture of the FPGA used in the Cu</a>, has decided to pull a fast one and silently change the license required to use iCEcube2</a> from free to an expensive subscription. It's unclear when exactly this change happened, but looking at the latest snapshot from the wayback machine</a> on February 24th, 2024, it was still free. On the live site</a> iCEcube2 is now only listed as Subscription for all FPGA families it supports. Heading over to their online store</a>, I'm currently seeing pricing of $471.31 for the first year and $353.15 to renew each additional year. This is insane! iCEcube2 hasn't had any meaningful software updates in many many years. Just take a look at the versions</a>. The only thing that makes sense to me is that they very much do not want you to use it. Contact Lattice#</a> </h1> If this change bothers you as much as it does me, I highly encourage you to contact Lattice</a> and let them know what you think. Click here for their general inquiries email</a>. I've sent them an email asking what's going on and I'll update this post if/when they respond. A Beacon of Hope#</a> </h1> Luckily, we have an alternative, Project IceStorm</a> and Yosys</a> more generally. The open source tools for FPGAs have continued to improve and my latest experiences with them for the Alchitry Cu</a> have been excellent. Alchitry Labs V2</a> comes with all the necessary open source tools bundled to work with the Cu without having to compile/install anything else. Lucid V1 to V2 2024-04-01T00:00:00+00:00 This post was created for people who are already familiar with Lucid V1 to get up to speed with what's new/different in Lucid V2. Style Changes#</a> </h1> Let's start off with the most basic changes, those to style. Optional Semicolons#</a> </h2> First off, the new Lucid grammar now accepts a new line as a semicolon. This means that as long as each expression is on a separate line, you don't need to use semicolons at all. This change was motivated by many modern programming languages. Trailing Commas#</a> </h2> Again taking inspiration from many other languages, trailing commas in lists are now supported. module trailingComma ( input clk, // clock input rst, // reset output out, // <- LOOK A COMMA ) ... </code></pre> By making trailing commas optional, it helps make it easier to re-arrange items in a list or add new items to the end without modifying previous lines. Camel Case#</a> </h2> This is fairly subtle, but camel case is now the preferred naming format for all basic names. The libraries and examples in Lucid V1 were fairly inconsistent between camelCase</code> and snake_case</code>. This is just to make things more consistent. Struct Position#</a> </h2> The first breaking change is that struct sizes are now specified after the array size (or name if there isn't an array size) instead of after the type. For example, before when declaring a sig</code> with an array of 8 structs with type myStruct</code> you would write the following. sig<myStruct> mySig[8]; </code></pre> This is now written as the following. sig mySig[8]<myStruct> </code></pre> This change was made to better match how the elements in the signal are structured. For example, mySig[1].structElement</code> is how you access the structElement</code> of the second element in the array. In both cases, the sig</code> is an array of structs so the array index always comes first. This also makes a bit more sense for the cases when you need to specify the width of a signal that doesn't have a type. For example, a struct declaration could look like this. struct myStruct { structElement<otherStruct>, structArray[3]<otherStruct>, } </code></pre> No More .WIDTH</code>#</a> </h1> Something that always felt kind of out of place to me was the .WIDTH</code> attribute attached to "all" signals in Lucid V1. While it worked for the most part, it had two issues I wanted to address. First, it just didn't seem to fit. There was nothing else like it in the language. Second, it could only be used on full signals, not expressions or anything else. Both of these are fixed by replacing it with the new $width()</code> function. Simply pass in whatever you want and it'll spit out a constant value representing the width of the signal/expression. This fits much better as there are plenty of other functions to calculate constant values. The use of .WIDTH</code> was in Lucid before there were custom Lucid functions. Otherwise, it probably would've been a function from the beginning. Simplification#</a> </h1> There are a few changes made to make things a bit simpler. repeat</code> Loops#</a> </h2> For loops were replaced with the new repeat</code> loop. Lucid V1 used C style for loop that were easy to write in a way that would be impossible to implement in hardware. The new repeat</code> loop has the simple syntax of repeat(i, count, start = 0, step = 1) {}</code> where i</code> is an optional loop variable. count</code> is a constant expression. start</code> and step</code> are also constant expressions but are optional. The loop will repeat count</code> times and i</code> will be set from start</code> to start + step * (count - 1)</code>. This syntax makes it impossible to write a loop with a variable number of iterations (which hardware can't accommodate). No More var</code>#</a> </h2> The var</code> type was always a bit weird. It was basically just a 32 bit sig</code> that you would use with for loops. No for loops means you doubly don't need it. Anywhere you had a var</code> before could be replaced with a sig</code>. Bye fsm</code>, Hello enum</code>#</a> </h2> The type fsm</code> was also kind of a weird type. It was a dff</code> with a list of constants attached. Nothing kept you from using these constants in other places in your designs and a few times I did just that. It always felt a little wrong. Now the enum</code> type lets you declare a list of constants that will have their values assigned by the tools just like fsm</code> but it is separate from any storage type. Something like fsm state { IDLE, START_BIT, DATA, STOP_BIT }; ... state.d = state.START_BIT; </code></pre> is now replaced with enum States { IDLE, START_BIT, DATA, STOP_BIT } dff state[$width(States)] ... state.d = States.START_BIT </code></pre> This makes the dff</code> type the only storage type. Parameter Test Values#</a> </h1> In Lucid V1 you had to choose between better error checking and making a parameter optional. Lucid V2 adds the ~</code> operator during parameter declaration to allow you to specify a test value. Here's an example. module uartTx #( CLK_FREQ ~ 100000000 : CLK_FREQ > 0, // clock frequency BAUD ~ 1000000 : BAUD > 0 && BAUD <= CLK_FREQ/2 // desired baud rate )( </code></pre> Both the parameter CLK_FREQ</code> and BAUD</code> have test values specified. These values are used when the module is being checked for errors but hasn't been instantiated. If these values were omitted, the error checking code doesn't know what they could be so it has to do its best to check for potential errors. You could provided a value with =</code> instead of ~</code> but this allows the parameter to be omitted when it is instantiated. The ~</code> version provides a value for the error checker to use but still requires a value to be explicitly presented when instantiated. Test Benches#</a> </h1> A huge reason for the whole Alchitry Labs/Lucid V2 rewrite was to add simulations. These have been covered in a previous post</a> New Site, New Forum, New Alchitry Labs 2024-03-26T00:00:00+00:00 A lot has happened since the last blog post! First lets start with the page you're reading this on, the new website! Alchitry Labs V2.0.5 - Simulations 2024-02-06T00:00:00+00:00 Version 2.0.5-Preview</a> of Alchitry Labs is now available. It now supports simulating the main Alchitry boards as well as the Io Element. Alchitry Labs V2 - Update 3 2024-01-15T00:00:00+00:00 Simulations are now supported! Test Benches#</a> </h2> The new update, 2.0.4-PREVIEW</a>, now has the first draft of the simulation GUI. To run a simulation you need to first create a test bench. I've covered these before when you could first run them from the command line so make sure to check that out</a> if you haven't already. There's been an addition to the $print</code> function though. You can still pass it a signal directly for the old behavior, but you can now pass in a formatting string followed by the values to use. This is similar to something like printf</code> in C/C++. The function call looks something like $print("my value is %d", mySig)</code> where mySig</code> is the signal to print in decimal where the %d is. The format options are "%d"</code> for decimal, "%b"</code> for binary, "%h"</code> for hexadecimal, and "%nf"</code> for fixed point where n is the number of fixed fractional bits (for example "%2f"</code>). Run the Test#</a> </h2> In the code editor, when it detects a test, there is an arrow in the left hand gutter on the line where the test was declared. You can click this arrow to run that test. Alternatively, clicking the bug icon in the toolbar will run every test. The results of the test are printed to the console and a new tab is opened displaying the resulting values captured at each $tick()</code>. The waveform viewer is currently pretty basic but its enough to start messing with it. You can use the mouse wheel to zoom and click/drag to pan around. The values at your cursor are show as an overlay. Alchitry Labs V2 - Update 2 2024-01-04T00:00:00+00:00 It's been a while since I've posted an update and a lot has happened. Most of the work I've been putting into Alchitry Labs has been for the new GUI. As I've mentioned in a previous blog post, this time around I'm using Compose Multiplatform</a> for creating the UI instead of the now very old SWT</a>. Compose is fundamentally different from SWT and allows for a lot more freedom in creating a beautiful UI. However, since Compose for desktop is so new, there are some growing pains I've had to overcome. Code Editor#</a> </h2> One of the first things I did when starting the Alchitry Labs rewrite was to see if I could make a text editor perform well with Compose. The built in TextField</code> widget is fine for small text fields but falls apart for something as complicated as a code editor. Compose exposes various levels of abstraction you can dig into depending on what you want to accomplish. I jumped a few layers down and created my own code editor composable. The most important difference between my code editor and the built in TextField</code> is that my code computes the layout of each line individually instead of the entire block of text. The big upside to this is that when text is being edited I only need to compute the lines that change instead of every single line. This makes editing text fast no matter how big the file is. There was a lot of complexity added to make this work but the payoff was worth it. In addition to performance, I was able to add some additional features that are nice to have for the code editor, such as the line numbers in the gutter. These are even flexible so I can potentially later add stuff like icons if needed. TextField</code> also doesn't provide any way to draw a background color behind text so I had to add this custom. This allows for highlighting the token the cursor is on as well as all matching tokens. Tabs#</a> </h2> The next major UI hurdle was making the editor tabs work. I already had written a sash composable that would allow me to split a section into left and right or top and bottom resize-able areas (I needed it already for the main layout). However, I wanted to make splitting the editor be as easy as dragging a dropping the tab to where you want it. Again, compose gives you plenty of tools to do this and I had already done something similar for a different project that I was able to steal most of the code from. With some modifications I ended up where it is now where you can not only drag and drop the tabs to rearrange them but drag them top any side of the window to split it. This is definitely a step up from the previous version that requires you to split then window then drag the tab over. Project Tree#</a> </h2> This is something that still needs some work, but one of the new features is that file names in the tree are color coded based on their state (yellow = has warnings, red = has errors). This was possible because the way projects/files are checked for errors is fundamentally different than before. When a file is changed, an error check is queued. The error check first parses all the project files for errors like syntax errors. Then starting from the top module, the project is parsed as a tree through the module instances. This allows for a thorough check of the modules using actual parameter values. Some of this could be improved in the future such as caching some of the results for files that haven't changed, but even as it is now it is quite fast. It currently doesn't fully check modules that fall outside the project tree (in other words, modules that are in the project but not used). I'll add this in a later update. Labs and Loader#</a> </h2> Alchitry Labs and the Alchitry Loader now share one executable/launcher. This was done because it isn't possible to create two launchers with one installer on macOS. Instead, when you open Alchitry Labs, it'll open whatever you were using last. To switch between Labs and the Loader, you simply click the Alchitry logo in the top left and choose "Switch to X" I have a feeling that most people are using either one or the other and don't often switch between the two. If this isn't you, let me know on the discussion page</a>. Test It Out#</a> </h2> There is still a lot of features missing, but if you would like you can download the latest version here</a>. Everything should be there to make a simple project, build, and load it to any of the Alchitry boards. This also means you should be able to use this to build projects for the Alchitry Cu on a Mac. Next Steps#</a> </h2> The code editor needs many quality of life improvements such as auto indenting/formatting, auto-complete, support for Verilog, error checking for ACF files, support for Xilinx and Lattice constraint files, context menus (right click), and I'm sure endless more. I need to also add in the component library, port the project templates to Lucid V2, and add back in support the Vivado's IP catalog. I also need to build the front end for running simulations. All the code is there to actually run it, there just isn't currently a way to conveniently start it or view the results. This will likely be my first next step. Alchitry Labs V2 - Update 1 2023-10-13T00:00:00+00:00 Today was the first time I built a .bin file from Alchitry Labs V2! Before we get too far ahead, there is a lot more to cover. In the last release, I use the Compose Multiplatform Gradle plugin to create native distributions</a>. At first, this seemed like an awesome solution. However, it has one fatal flaw. The plugin requires you to build each target on its respective platform. That means if you want to build for Windows, you need to be on Windows. If you want to build for an ARM based Mac, you need to have an ARM based Mac. This requirement was the same issue I had before with the original Alchitry Labs but it wasn't that bad since I only ever built for Windows and Linux X64. I was able to do everything from Linux using a Window VM. This time around, I want to add support for more systems. Alchitry Labs runs on a JVM (Java Virtual Machine) so in theory it should run in a ton of places with minimal work. I'm hoping to target everything that Compose supports, Windows x64, Linux x64, Linux ARM, Mac x64, and Mac ARM. When looking for solutions to this, I came across Conveyor</a> which seems to be almost everything I was looking for. Best of all, it is free for open source projects like Alchitry Labs! Conveyor lets you build for every target from a single system. It also deals with code signing and pushing updates. The only downside right now is that it doesn't support Linux AArch64 (ARM). I became a paid subscriber to get this feature onto the dev's radar and I was told it will likely make it into the next major release. Now that I have this all setup, I can run a single command that builds my project, creates update packages, creates an update website, and pushes it all to GitHub. You can now download the latest version from the GitHub page here</a> I'm currently just self signing everything. This only really matters for Windows and Macs where you'll see more security warnings when trying to install it. I'll likely get everything officially signed for the next release. For the Window's release, this means that it'll be available from the Microsoft Store. The Linux version is now packaged as a deb which makes installation so much easier! Installing the deb also adds an update site so that when updates for Alchitry Labs are available they show up in the package manager with everything else. Mac Support#</a> </h2> As I've mentioned above, the new releases have Mac versions. Before you get too excited, no, you still can't run Vivado or iceCube 2 on a Mac. This means that you still can't build FPGA projects using the proprietary tools. So why bother supporting Macs? First, many people run the build tools inside of virtual machines inside a Mac. USB devices don't always play nicely going across the VM layer so by having native support for the Alchitry Loader, we can avoid that issue. The Mac versions of the loader are already working! Second, there are open source tools that can run on a Mac. I'm hoping to bundle these with a later release of Alchitry Labs so that you will be able to develop for the Alchitry Cu natively on a Mac. The New Verilog Converter#</a> </h2> The biggest update to the Alchitry Labs V2 codebase is the Verilog converter. Continuing with the full rewrite, the new converter is much cleaner than the old one. The original converter was one of the first things I wrote back when the IDE was the "Mojo IDE." Back then, the converted was responsible for everything. Given some Lucid text, it had to spit out a Verilog version. The new converted is instead given a fully parsed Lucid module instance. A lot of the complicated tasks are already done in the previous stage such as dealing with signal indexing, declarations, etc. This, along with better coding practices, has made the new converter about 40% of the size of the original! I'm pretty excited for it. ACF Parser#</a> </h2> With a Lucid->Verilog translator working, the next step was to add support for constraint files. The Alchitry Constraint File format is super simple and adding a parser for it wasn't too complicated. I ended up modifying the format a bit from V1 though. Keeping with the change to Lucid, semicolons are now optional. Also, clock statements are considered a special type of pin statement so you don't need to specify both for a single pin. It now checks that the names of the ports and pins are valid. Wildly, I apparently never checked the pin names properly for V1 so they would just show up as "null" in the converted constraint file and cause silent issues. For now, I just have an ACF->XDC converter (XDC is the Xilinx format). Test Build#</a> </h2> With all the pieces in place, I was able to get a test build running. Once a project is open, calling Project.build()</code> simply builds the entire project! This only works for the Au/Au+ right now as I still have to port the Cu builders but it is a big milestone! Building Au projects is accessible from the command line interface now. If you want to check out the progress, see the GitHub page</a>. You can install the latest version here</a>. Alchitry Loader V2 2023-09-18T00:00:00+00:00 The Alchitry Loader portion of the Alchitry Labs V2 rewrite is mostly done! The new loader automatically detects connected boards and lists them in a drop down. This allows you to have more than one board connected without conflict. Under the hood, it now also handles the D2XX driver a bit more elegantly. It first tries to load the proprietary D2XX library (libd2xx) and if it fails, it falls back to the open source libUSB driver. On Windows, you'll almost always be using D2XX from FTDI. However, on Linux, libUSB is the default but you can install libd2xx and it'll be detected and used. There are still a few weird kinks to work out but it is overall usable (and an improvement over the old one). On Windows, I haven't been able to figure out how to configure the installer to not install a shortcut for the command line interface version of the launcher. After running the installer, you'll see a shortcut called "alchitry" which doesn't seem to do anything. This is the command line interface launcher. There seems to be a bug in jpackage</code> that ignores the value of the --win-shortcut</code> option and always makes shortcuts. I'll have to dig into more eventually. On Linux, I've been having a hard time getting the window's icon to be set correctly. On Gnome, it seems to be working but on Ubuntu (22.04) it shows the default Java icon and has some kind of secondary ghost window that you can't focus. Installers#</a> </h1> Windows Installer</a> Linux Installer</a> Alchitry Labs V2 - Command Line Interface 2023-09-11T00:00:00+00:00 It has been a while since I last wrote about the progress on Alchitry Labs V2 and a lot has changed. Build Tools#</a> </h2> I've spent a good amount of time working on building out the Gradle build script so that the deployment process will be much easier than it was for Alchitry Labs V1. When I was looking for a way to create the Window's installer, I discovered that Compose Multiplatform</a> has a built-in packaging tool</a>! It turns out that this still has the major downside of needing to be running on the OS that you want to package for. This means you can't build an installer for Windows from Linux. Bummer, but not the end of the world. I ran into two other issues when flushing out the build script. First, Compose's build tools only support creating one launcher per application. I need to create two. The main one to launch Alchitry Labs and the second to launch the Alchitry Loader. These two programs are actually the same thing with just a different argument passed to them to show a different GUI. It turns out that jpackage, the tool used by Compose, has a way to add additional launchers but Compose currently gives no way to access it. I add the support I needed, I forked the Compose plugin and submitted a pull request</a>. For now, I'm using my local forked version of the Compose plugin, but hopefully they'll accept the pull request or make some similar changes to allow creating additional launchers. Command Line Interface#</a> </h2> Something I often get emails about is for command line support in Alchitry Labs. Well, I'm happy to announce that the command line interface for Alchitry Labs V2 will be well supported. I've decided to get everything working via the command line before diving too much into the GUI. Right now, the loading tools already work. So if you've been looking for a way to load your Alchitry boards from the command line, check out the very early releases below. The command line is broken into a bunch of subcommands. $ alchitry --help Usage: alchitry_labs options_list Subcommands: new - Create a new project clone - Clone an existing project check - Check a project for errors build - Build an Alchitry Project load - Load a project or .bin file sim - Simulate a project labs - Launch Alchitry Labs GUI loader - Launch Alchitry Loader GUI Options: --help, -h -> Usage info </code></pre> If you install the .deb on Linux, you'll get access to the alchitry</code> command. On Windows, the Alchitry.exe</code> executable in the installation directory can be used. You can run --help</code> on each subcommand for more info. $ alchitry load --help Usage: alchitry_labs load options_list Options: --project, -p -> Alchitry project file { String } --flash, -f [false] -> Load project to FPGA's flash (persistent) --ram, -r [false] -> Load project to FPGA's RAM (temporary) --list, -l [false] -> List all detected boards --device, -d [0] -> Index of device to load { Int } --bin -> Bin file to load { String } --board, -b -> Board used in the project { Value should be one of [Au, Au+, Cu] } --help, -h -> Usage info </code></pre> For example, you can load a .bin file like this. $ alchitry load --bin alchitry.bin -b Au+ --flash Checking IDCODE... Loading bridge configuration... Erasing... Flashing 100% │███████████████████████████████████│ 335339/335339 (0:00:01 / 0:00:00) Resetting FPGA... Done. </code></pre> If you try this out, let me know what you think over at the discussions page</a>. Releases#</a> </h2> These aren't really a "release" as much as just something you can try and mess around with. That being said, the loading features should be fully working. Linux Deb</a> Windows Installer</a> The Labs GUI will open but it doesn't really do much. It is basically just a test right now for the custom text editor. The Loader GUI doesn't open/exist at all yet. The command line tools work for creating and simulating projects as well as loading .bin files. Alchitry Labs V2 2023-06-07T00:00:00+00:00 I am now starting to work on the UI of the Alchitry Labs rewrite! Alchitry Labs currently use UI toolkit, SWT. This is the UI toolkit developed and used by Eclipse. At the time I started working on what was then the Mojo IDE, SWT was a solid choice. It allowed me to create a single UI that worked on Windows and Linux with minimal effort, and it looked native on both platforms. However, it hasn't aged super well. I found it to be fairly limited when trying to do anything custom. For example, I wanted the project tree on the left side of the window to stay the same size when you resized the window. The main code editor should be the only thing that changes size to accommodate the new window size. SWT doesn't allow for this, and instead you specify the size of each side as a percent. My workaround was to recalculate the percentages every time the window size changes to keep one side a fixed size. This mostly works, but if you resize the window a lot, you may notice the divider jumps around due to rounding errors. In newer versions of SWT, something changed/broke that broke the tooltip window from popping up when hovering over an error in the text editor. I spend a stupid amount of time trying to figure out a fix for this before giving up and sticking with an old version of the library. This annoyingly prevents other bugs from getting fixed though. One of the worst offenders is the undo/redo bug in the current Alchitry Labs. I've spent days trying to get the undo/redo function to be reliable, but for whatever reason, the way SWT handles the edit events have prevented me from getting it to always work. V2 already has a fully reliable undo/redo working. TLDR, I'm moving to something else. Jetpack Compose#</a> </h2> If you do any UI work and haven't tried Jetpack Compose</a> you're missing out. This is a declarative UI framework originally developed for use on Android, but it has since made its way onto more platforms including desktop. I find it a joy to use, and it doesn't lock you into anything allowing me to create whatever custom UI elements or tweaks I need. Unfortunately, the built-in text editor (TextField) has terrible performance if you are trying to edit any decent amount of text. This led me to write my own custom editor that has solid performance for thousands of lines of code. While this was a substantial amount of work, it also opens up potential in the future for doing cool tricks like collapsable blocks. This was impossible with SWT. Lucid Parser#</a> </h2> I've also implemented the snapshots for $tick</code> and added $silentTick</code> which skips the snapshot step. The snapshots get compiled into a simulation result that holds the value of every signal in the design for every call of $tick</code>. This will allow the UI to display the results of the entire simulation. The Repo#</a> </h2> The Lucid Parser repo has been renamed to Alchitry Labs V2</a> and now contains the UI and parser code. This is where all the progress can be found. There is a discussion page</a>, or you can email me</a> and let me know your thoughts. Lucid V2 - Update 2 - Test Benches 2023-06-01T00:00:00+00:00 Test benches are here! I just pushed a working draft of the test bench code that has the necessities for writing quick tests for you modules! Test Bench Example#</a> </h2> Take a look at this revolutionary counter module I created. module counter ( input clk, output count[8] ) { dff counter[8] (.clk(clk)) always { counter.d = counter.q + 1 count = counter.q } } </code></pre> I designed it so that the output count</code> will increment by one on every rising edge of the clk</code> input. However, does it actually work?!? There's no way to know. Oh wait, we could test it. Here is my test bench that does just that. testBench myTestBench { sig clk // signal to use as my clock counter dut (.clk(clk)) // device under test fun tickClock() { clk = 1 $tick() clk = 0 $tick() } test simpleTest { clk = 0 // initialize the clock $tick() repeat(100, i) { $print(dut.count) $assert(dut.count == i) $tickClock() } $assert(dut.count == 100) } } </code></pre> The insides of a testBench</code> are very similar to a module</code> with a couple of key differences. There are no ports or parameters and instead of always</code> blocks you use test</code> and fun</code> blocks. On line 2, we create a signal named clk</code> that will act as our clock. On line 4, we instantiate the device under test or "dut". It is convention to call the module being tested "dut" but there is nothing special about the name. Next, we have our function declaration. Functions have the same properties as tests, but they aren't run directly. Instead, functions are little pieces of helper code that can be called from tests. Here I defined the very common function of toggling the clock and called it tickClock</code>. This function doesn't have any parameters, but it could. For example, we could give it a parameter to repeat a specified number of times. fun tickClock(times[32]) { repeat(times) { clk = 1 $tick() clk = 0 $tick() } } </code></pre> Function arguments act the same as module inputs and can be multidimensional arrays or structs. Test Bench Functions#</a> </h3> Before we move on, let me quickly go over the couple of test bench specific functions that I'm using. The function $tick()</code> is at the very core of the simulation. It initiates a simulation tick. So what is a simulation tick? This is when the simulator publishes all signal changes and recalculates the outputs for all the pieces in the design whose input signals changed. Those output changes then trigger other updates if they are used as inputs. This continues until the results of everything stabilize. The only time it won't stabilize is if you have some kind of dependency loop like a = b</code> and b = ~a</code>. In this case, the simulator will quit after 1000 iterations. I chose this number as a seemingly nice upper bound, but it may change if I find designs often need more or fewer iterations. A loop like this would result in faulty hardware, and anything requiring too many iterations to resolve would likely be too complicated to do in a single real clock cycle. So back to the test bench. Before we call $tick()</code>, first we need to set a value to all signals we are using. Signals default to having a bx</code> value so bad things will happen if we call $tick()</code> before setting a real value. By bad things, I mean that bx</code> value will propagate throughout the design contaminating our counter. With clk</code> set to 0, we call $tick()</code> to initialize the design. Next, we hit a repeat</code> block that will repeat its contents 100 times and use the signal i</code> as the iteration index. The first line in the loop prints the value of dut.count</code> using the $print()</code> function. This function takes one argument, the value to print. It currently outputs the value in the format dut.count = {00011100} : 28</code> where the value is shown in its binary form as well as its decimal value (if it has one). The next line uses the $assert()</code> function to check that the value of the counter matches the loop iteration we are on. The argument to $assert()</code> can be anything, and it is treated as a boolean. That means if it is non-zero, nothing happens, but if it is zero, the simulation is aborted and the $assert()</code> that caused it is called out. This is very useful for checking values quickly without having to look back through the simulation manually to see if values make sense. The last line in the loop is the call to the function $tickClock()</code> that we already defined. Finally, we end our test by checking that the counter output is 100 after the 100 cycles. This example is from one of the tests and can be found in the repo here</a>. Next Step#</a> </h2> The next step is to add snapshots of the entire design every time $tick()</code> is called. This will allow for the simulation results to be shown after it is run. Currently, it just runs discarding all intermediate values. I also plan to have a $silentTick()</code> or similarly named function that does a tick without taking a snapshot. This way you can use that when making the clock fall for most designs and avoid the overhead of an entire snapshot. As before, there is a discussion page</a> setup as part of the repo where you can let me know your thoughts. Lucid V2 - Update 1 2023-05-30T00:00:00+00:00 I just pushed what I believe is the last piece of the core Lucid 2 rewrite. Lucid V2 2023-05-18T00:00:00+00:00 A full rewrite of the Lucid parser in Alchitry Labs has been a long time coming.

Without Alchitry Labs

A Year of Updates

Getting Started

Why Use FPGAs?

IO</h2> The first is in anything IO heavy. By IO, I mean inputs and outputs of the chip.</p> FPGAs often have a ton of pins to connect to the external world. On top of that, these pins often have capabilities not seen on microcontrollers.</p>

Basic CPU

Vivado Setup

Register Interface

Pinouts and Custom Elements

Alchitry Constraints Reference

Lucid Reference

Alchitry Labs V2.0.24 - Negative Indices

Alchitry Labs V2.0.21 - Alchitry Constraints Updated

Alchitry V2 - Production Begins

Alchitry V2 - All New Boards

Alchitry Platinum and Board Rework

Alchitry Labs V2 - snake_case

Io Element

Synchronous Logic

Alchitry Labs V2 - Now in Beta!

Your First FPGA Project

Alchitry Labs V2.0.13 - Verilog Interoperability

Alchitry Labs V2.0.8

iCEcube2 No Longer Free

Lucid V1 to V2

New Site, New Forum, New Alchitry Labs

Alchitry Labs V2.0.5 - Simulations

Alchitry Labs V2 - Update 3

Alchitry Labs V2 - Update 2

Alchitry Labs V2 - Update 1

Alchitry Loader V2

Alchitry Labs V2 - Command Line Interface

Alchitry Labs V2

Lucid V2 - Update 2 - Test Benches

Lucid V2 - Update 1

Lucid V2