Final Version of the Enigma in Amaranth HDL

2.1.1   V2 Rotor initialization

First, let's look at the setup of the Rotor component (while omitting the ports for brevity, which are shown in the diagram above anyway).

class Rotor (wiring.Component):
    # All the ports
    # ....

    N = 3  # Number of rotor slots

    def __init__(self):
        N = self.N
        self.cnts = Array([Signal(5) for i in range(N)])   # Registers for each of the rotors (as well as start position)
        self.ring_settings = Array([Signal(5) for i in range(N)])
        self.generate_wirings()
        super().__init__()

In the constructor, I'm defining two sets of registers:

1. cnts[2:0]: A 5-bit counter for each of the 3 rotors to keep track of the current rotational position.
2. ring_settings[2:0]: A 5-bit register for each of the 3 rotors to save the ring setting.

We don't need to save the start setting of each Rotor because we can just load that value into cnt at the start of each encryption session.

Now, let's look at the first part of the method used to generate the wiring patterns that will swizzle each input character.

 1def generate_wirings(self):
 2    from test.enigma import Enigma
 3    _wirings = []
 4    _turnovers = []
 5
 6    for rotor_type in Rotors:
 7        # Gather up the wiring and turnover positions from the golden model
 8        rotor_class = Enigma.ROTORS[rotor_type]
 9        _wirings.append(rotor_class.wiring)
10        _turnovers.append(rotor_class.turnover)
11
12        wiring_list_right_to_left = []
13        wiring_list_left_to_right = []
14
15        for w in _wirings:
16            mapping = [ord(c)-65 for c in w]
17            mapping_ltor = [0]*26
18            for i, c in enumerate(w):
19                mapping_ltor[ord(c)-65] = i
20
21            wiring_list_right_to_left.append(Array(mapping)) # right_to_left mapping
22            wiring_list_left_to_right.append(Array(mapping_ltor))
23
24        self.Wiring_right_to_left = Array(wiring_list_right_to_left)
25        self.Wiring_left_to_right = Array(wiring_list_left_to_right)
26
27        self.turnovers = Array([Const(ord(t)-65) for t in _turnovers])

In lines 2-10 we are directly importing our golden model so there's no danger of the Rotor wiring patterns and turnover points getting out of sync. I've defined 5 different rotor types (from the WWII Enigma I Army kit), so _wirings and _turnovers will be Python lists of length 5, with each entry being a string.

Next, we convert the ASCII characters into 5-bit numbers (lines 12-18), and convert the Python lists into Amaranth Arrays that can be synthesized into table lookups in the hardware.

Now, self.Wiring_right_to_left is a two-dimensional Array. It's first-dimension can be indexed at runtime by a 3-bit number that selects the Rotor type. The result of that indexing will be the wiring pattern for that Rotor, which is an 1D Array. That wiring pattern can be indexed at runtime by a 5-bit number (input contact point) that yields the output contact point (swizzle). So, for example, self.Wiring_right_to_left[2][9] returns the output contact point if entering a Rotor of type Rotor III at the 10th input contact point.

self.Wiring_left_to_right is just the reverse mapping when going back from the reflector.

2.1.2   V2 Rotor Computation

Now let's look at the elaborate method that Amaranth uses to build the hardware. The first thing we'll do in lines 2-11 is create a Module for the Rotor, and then define some hardware signals/wires with associated bit-widths. Then, we'll define a register that keeps track of what Rotor type is in each slot: self.slot[0] will store the Rotor type in Slot 0 (right-most Rotor). We initialize this (unless the state machine loads this in explicitly) with Rotor I, Rotor II, and Rotor III in slots 0, 1, and 2 respectively.

Next, we instantiate the input mux (shown in rotor_schematic on the top-right) with a Switch statement.

 1def elaborate(self, platform):
 2    m = Module()
 3    N = self.N
 4
 5    ring_setting = Signal(5)       # The enabled Rotor's ring setting
 6    cnt = Signal(5)                # The enabled Rotor's position
 7    cnt_ring_combined = Signal(5)  # Computed position based on current cnt, and ring_setting
 8    muxed_din = Signal(5)          # Output of input data mux
 9    right_ptr = Signal(5)          # Index into wiring swizzle table
10    wiring_rtol = Signal(5)        # The output character after swizzling going rtol
11    wiring_ltor = Signal(5)        # The output character after swizzling if going ltor
12    cnt_eq_25 = Signal(1)    # Whether the cnt is going to overflow
13
14    # Picking the rotor for each slot
15    self.slot = Array([Signal(3, init=0), Signal(3,init=1), Signal(3, init=2)]) # Choose from one of 8 rotor types for each of the 3 slots
16
17    # Mux on the inputs
18    with m.Switch(self.din_sel):
19        with m.Case(1):
20            m.d.comb += muxed_din.eq(self.dout)
21        with m.Case(2):
22            m.d.comb += muxed_din.eq(self.reflector_in)
23        with m.Default():
24            m.d.comb += muxed_din.eq(self.din)

Now, we come to the meat of the swizzle computation with dynamically selected Rotors and slots. Here's an interesting design pattern from Amaranth for Switch/Case statements: We can generate case statements using Python loops to reduce hugely repetitive code. Below, we're switching on a one-hot encoded en signal that picks the Rotor slot. The for-loop iterates over all the one-hot codes (and also has the associated conversion to binary rotor number) to generate each Case statement. Within each Case, we can use the for-loop variables to index into the wiring tables generated above like so:

self.Wiring_right_to_left[self.slot[rotor]][right_ptr]

With the three loop-generated Case statements below, we've taken care of selecting the proper Rotor type in each slot, and getting the associated swizzled output. The synthesis tool (Yosys) should be able to optimize all the lookup tables for the rotor wiring for us.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

    with m.Switch(self.en):
         # Pick settings based on which Rotor Slot is selected by self.en (one-hot)
        for one_hot, rotor in [(0b001, 0), (0b010,1), (0b100, 2)]:
            with m.Case(one_hot):
                m.d.comb += [
                    ring_setting.eq(self.ring_settings[rotor]),
                    cnt.eq(self.cnts[rotor]),
                    cnt_eq_25.eq(cnt==25),
                    # Pick the wiring swizzles based on which Rotor type is loaded into each slot
                    wiring_rtol.eq(self.Wiring_right_to_left[self.slot[rotor]][right_ptr]),
                    wiring_ltor.eq(self.Wiring_left_to_right[self.slot[rotor]][right_ptr]),
                ]
                with m.If(self.load_start):
                    m.d.sync += self.cnts[rotor].eq(muxed_din)
                with m.Elif(self.load_ring):
                    m.d.sync += self.ring_settings[rotor].eq(muxed_din)
                with m.Elif(self.load_rotor_type):
                    m.d.sync += self.slot[rotor].eq(muxed_din[0:3])
                with m.Elif(self.inc):
                    with m.If(cnt_eq_25):
                        m.d.sync += self.cnts[rotor].eq(0)
                    with m.Else():
                        m.d.sync += self.cnts[rotor].eq(cnt+1)
        with m.Default():
            m.d.comb += [
                ring_setting.eq(0),
                cnt.eq(0)
            ]

Now, let's take a look at how the right_ptr or index into the wiring swizzles are calculated: Recall from the previous part that our calculations looked like the following:

cnt_ring_combined = (cnt - ring_setting) % 26
contact_point     = (input_char + cnt_ring_combined) % 26
exit_point = rotor_swizzle[contact_point]
result = (exit_point - cnt_ring_combined) % 26

We want to avoid the modulus operation, so we can define subtract and addition routines that check for overflow to implement the wrap-around:

# Return (a - b) % 26
def sub2_mod_26(out, a, b):
    with m.If(b > a):
        m.d.comb += out.eq( (26-(b-a))[0:5])
    with m.Else():
        m.d.comb += out.eq( (a-b)[0:5])

# Return (a + b) % 26
def add2_mod_26(sum_signal, a,b):
    s = Signal(6)
    m.d.comb += s.eq(a+b)
    with m.If(s > 25):
        m.d.comb += sum_signal.eq( (s-26)[0:5])
    with m.Else():
        m.d.comb += sum_signal.eq( s[0:5])

We make sure to slice the output signal to 5 bits, just to avoid any issues with Amaranth's implicit extension to 6-bits and subsequent comparison.

With these helper inner functions, we can then complete the elaborate method:

sub2_mod_26(cnt_ring_combined, cnt, ring_setting)
add2_mod_26(right_ptr, muxed_din, cnt_ring_combined)

# right to left traversal
swizz_minus_cnt_ring = Signal(5)
sub2_mod_26(swizz_minus_cnt_ring, wiring_rtol, cnt_ring_combined)

# left to right traversal
swizz_l_minus_cnt_ring = Signal(5)
sub2_mod_26(swizz_l_minus_cnt_ring, wiring_ltor, cnt_ring_combined)

m.d.sync += self.dout.eq(
    Mux(self.ltor,
        swizz_l_minus_cnt_ring,
        swizz_minus_cnt_ring,))

return m

Putting everything together yields the following block diagram, with the input contact point being calculated and fed to all three slots, and then the exit contact point muxed from the correct slot and adjusted for the cnt and ring_setting before being output: