1 """Cascading Power ISA Decoder
3 This module uses CSV tables in a hierarchical/peer cascading fashion,
4 to create a multi-level instruction decoder by recognising appropriate
5 patterns. The output is a wide, flattened (1-level) series of bitfields,
6 suitable for a simple RISC engine.
8 This is based on Anton Blanchard's excellent microwatt work:
9 https://github.com/antonblanchard/microwatt/blob/master/decode1.vhdl
11 The basic principle is that the python code does the heavy lifting
12 (reading the CSV files, constructing the hierarchy), creating the HDL
13 AST with for-loops generating switch-case statements.
15 Where "normal" HDL would do this, in laborious excruciating detail:
17 switch (opcode & major_mask_bits):
18 case opcode_2: decode_opcode_2()
20 switch (opcode & minor_19_mask_bits)
21 case minor_opcode_19_operation_X:
22 case minor_opcode_19_operation_y:
24 we take *full* advantage of the decoupling between python and the
25 nmigen AST data structure, to do this:
27 with m.Switch(opcode & self.mask):
28 for case_bitmask in subcases:
29 with m.If(opcode & case_bitmask): {do_something}
31 this includes specifying the information sufficient to perform subdecoding.
35 the full hierarchical tree for decoding POWER9 is specified here
39 takes a *list* of CSV files with an associated bit-range that it
40 is requested to match against the "opcode" row of the CSV file.
41 This pattern can be either an integer, a binary number, *or* a
42 wildcard nmigen Case pattern of the form "001--1-100".
46 these are *additional* cases with further decoding. The "pattern"
47 argument is specified as one of the Case statements (a peer of the
48 opcode row in the CSV file), and thus further fields of the opcode
49 may be decoded giving increasing levels of detail.
53 [ (extra.csv: bit-fields entire 32-bit range
55 000000---------------01000000000 -> ILLEGAL instruction
56 01100000000000000000000000000000 -> SIM_CONFIG instruction
57 ................................ ->
59 (major.csv: first 6 bits ONLY
61 001100 -> ALU,OP_ADD (add)
62 001101 -> ALU,OP_ADD (another type of add)
66 001011 this must match *MAJOR*.CSV
67 [ (minor_19.csv: bits 21 through 30 inclusive:
69 0b0000000000 -> ALU,OP_MCRF
72 (minor_19_00000.csv: bits 21 through 25 inclusive:
74 0b00010 -> ALU,add_pcis
82 from collections
import namedtuple
83 from nmigen
import Module
, Elaboratable
, Signal
, Cat
, Mux
84 from nmigen
.cli
import rtlil
85 from soc
.decoder
.power_enums
import (Function
, Form
, InternalOp
,
86 In1Sel
, In2Sel
, In3Sel
, OutSel
,
87 RC
, LdstLen
, CryIn
, get_csv
,
88 single_bit_flags
, CRInSel
,
89 CROutSel
, get_signal_name
,
90 default_values
, insns
, asmidx
)
91 from soc
.decoder
.power_fields
import DecodeFields
92 from soc
.decoder
.power_fieldsn
import SigDecode
, SignalBitRange
95 # key data structure in which the POWER decoder is specified,
96 # in a hierarchical fashion
97 Subdecoder
= namedtuple("Subdecoder",
98 ["pattern", # the major pattern to search for (e.g. major opcode)
99 "opcodes", # a dictionary of minor patterns to find
100 "opint", # true => the pattern must not be in "10----11" format
101 "bitsel", # the bits (as a range) against which "pattern" matches
102 "suffix", # shift the opcode down before decoding
103 "subdecoders" # list of further subdecoders for *additional* matches,
104 # *ONLY* after "pattern" has *ALSO* been matched against.
109 """PowerOp: spec for execution. op type (ADD etc.) reg specs etc.
111 this is an internal data structure, set up by reading CSV files
112 (which uses _eq to initialise each instance, not eq)
114 the "public" API (as far as actual usage as a useful decoder is concerned)
115 is Decode2ToExecute1Type
118 def __init__(self
, incl_asm
=True):
119 self
.function_unit
= Signal(Function
, reset_less
=True)
120 self
.internal_op
= Signal(InternalOp
, reset_less
=True)
121 self
.form
= Signal(Form
, reset_less
=True)
122 if incl_asm
: # for simulator only
123 self
.asmcode
= Signal(8, reset_less
=True)
124 self
.in1_sel
= Signal(In1Sel
, reset_less
=True)
125 self
.in2_sel
= Signal(In2Sel
, reset_less
=True)
126 self
.in3_sel
= Signal(In3Sel
, reset_less
=True)
127 self
.out_sel
= Signal(OutSel
, reset_less
=True)
128 self
.cr_in
= Signal(CRInSel
, reset_less
=True)
129 self
.cr_out
= Signal(CROutSel
, reset_less
=True)
130 self
.ldst_len
= Signal(LdstLen
, reset_less
=True)
131 self
.rc_sel
= Signal(RC
, reset_less
=True)
132 self
.cry_in
= Signal(CryIn
, reset_less
=True)
133 for bit
in single_bit_flags
:
134 name
= get_signal_name(bit
)
135 setattr(self
, name
, Signal(reset_less
=True, name
=name
))
137 def _eq(self
, row
=None):
140 # TODO: this conversion process from a dict to an object
141 # should really be done using e.g. namedtuple and then
143 if row
['CR in'] == '1':
144 import pdb
; pdb
.set_trace()
146 if row
['CR out'] == '0':
147 import pdb
; pdb
.set_trace()
150 res
= [self
.function_unit
.eq(Function
[row
['unit']]),
151 self
.form
.eq(Form
[row
['form']]),
152 self
.internal_op
.eq(InternalOp
[row
['internal op']]),
153 self
.in1_sel
.eq(In1Sel
[row
['in1']]),
154 self
.in2_sel
.eq(In2Sel
[row
['in2']]),
155 self
.in3_sel
.eq(In3Sel
[row
['in3']]),
156 self
.out_sel
.eq(OutSel
[row
['out']]),
157 self
.cr_in
.eq(CRInSel
[row
['CR in']]),
158 self
.cr_out
.eq(CROutSel
[row
['CR out']]),
159 self
.ldst_len
.eq(LdstLen
[row
['ldst len']]),
160 self
.rc_sel
.eq(RC
[row
['rc']]),
161 self
.cry_in
.eq(CryIn
[row
['cry in']]),
164 asmcode
= row
['comment']
165 if hasattr(self
, "asmcode") and asmcode
in asmidx
:
166 res
.append(self
.asmcode
.eq(asmidx
[asmcode
]))
167 for bit
in single_bit_flags
:
168 sig
= getattr(self
, get_signal_name(bit
))
169 res
.append(sig
.eq(int(row
.get(bit
, 0))))
172 def eq(self
, otherop
):
173 res
= [self
.function_unit
.eq(otherop
.function_unit
),
174 self
.form
.eq(otherop
.form
),
175 self
.internal_op
.eq(otherop
.internal_op
),
176 self
.in1_sel
.eq(otherop
.in1_sel
),
177 self
.in2_sel
.eq(otherop
.in2_sel
),
178 self
.in3_sel
.eq(otherop
.in3_sel
),
179 self
.out_sel
.eq(otherop
.out_sel
),
180 self
.cr_in
.eq(otherop
.cr_in
),
181 self
.cr_out
.eq(otherop
.cr_out
),
182 self
.rc_sel
.eq(otherop
.rc_sel
),
183 self
.ldst_len
.eq(otherop
.ldst_len
),
184 self
.cry_in
.eq(otherop
.cry_in
)]
185 for bit
in single_bit_flags
:
186 sig
= getattr(self
, get_signal_name(bit
))
187 res
.append(sig
.eq(getattr(otherop
, get_signal_name(bit
))))
188 if hasattr(self
, "asmcode"):
189 res
.append(self
.asmcode
.eq(otherop
.asmcode
))
193 regular
= [self
.function_unit
,
204 if hasattr(self
, "asmcode"):
205 regular
.append(self
.asmcode
)
206 single_bit_ports
= [getattr(self
, get_signal_name(x
))
207 for x
in single_bit_flags
]
208 return regular
+ single_bit_ports
211 class PowerDecoder(Elaboratable
):
212 """PowerDecoder - decodes an incoming opcode into the type of operation
215 def __init__(self
, width
, dec
):
216 if not isinstance(dec
, list):
219 self
.opcode_in
= Signal(width
, reset_less
=True)
223 if d
.suffix
is not None and d
.suffix
>= width
:
227 def suffix_mask(self
, d
):
228 return ((1 << d
.suffix
) - 1)
230 def divide_opcodes(self
, d
):
232 mask
= self
.suffix_mask(d
)
233 print("mask", hex(mask
))
234 for row
in d
.opcodes
:
235 opcode
= row
['opcode']
236 if d
.opint
and '-' not in opcode
:
237 opcode
= int(opcode
, 0)
239 opcode
= opcode
>> d
.suffix
240 if key
not in divided
:
244 divided
[key
].append(r
)
247 def elaborate(self
, platform
):
251 # note: default opcode is "illegal" as this is a combinatorial block
252 # this only works because OP_ILLEGAL=0 and the default (unset) is 0
254 # go through the list of CSV decoders first
256 opcode_switch
= Signal(d
.bitsel
[1] - d
.bitsel
[0],
258 comb
+= opcode_switch
.eq(self
.opcode_in
[d
.bitsel
[0]:d
.bitsel
[1]])
260 opcodes
= self
.divide_opcodes(d
)
261 opc_in
= Signal(d
.suffix
, reset_less
=True)
262 comb
+= opc_in
.eq(opcode_switch
[:d
.suffix
])
263 # begin the dynamic Switch statement here
264 with m
.Switch(opc_in
):
265 for key
, row
in opcodes
.items():
266 bitsel
= (d
.suffix
+d
.bitsel
[0], d
.bitsel
[1])
267 sd
= Subdecoder(pattern
=None, opcodes
=row
,
268 bitsel
=bitsel
, suffix
=None,
269 opint
=False, subdecoders
=[])
270 subdecoder
= PowerDecoder(width
=32, dec
=sd
)
271 setattr(m
.submodules
, "dec_sub%d" % key
, subdecoder
)
272 comb
+= subdecoder
.opcode_in
.eq(self
.opcode_in
)
273 # add in the dynamic Case statement here
275 comb
+= self
.op
.eq(subdecoder
.op
)
277 # TODO: arguments, here (all of them) need to be a list.
278 # a for-loop around the *list* of decoder args.
279 with m
.Switch(opcode_switch
):
280 self
.handle_subdecoders(m
, d
)
281 for row
in d
.opcodes
:
282 opcode
= row
['opcode']
283 if d
.opint
and '-' not in opcode
:
284 opcode
= int(opcode
, 0)
287 # add in the dynamic Case statement here
289 comb
+= self
.op
._eq
(row
)
292 def handle_subdecoders(self
, m
, d
):
293 for dec
in d
.subdecoders
:
294 subdecoder
= PowerDecoder(self
.width
, dec
)
295 if isinstance(dec
, list): # XXX HACK: take first pattern
297 setattr(m
.submodules
, "dec%d" % dec
.pattern
, subdecoder
)
298 m
.d
.comb
+= subdecoder
.opcode_in
.eq(self
.opcode_in
)
299 with m
.Case(dec
.pattern
):
300 m
.d
.comb
+= self
.op
.eq(subdecoder
.op
)
303 return [self
.opcode_in
] + self
.op
.ports()
306 class TopPowerDecoder(PowerDecoder
):
309 top-level hierarchical decoder for POWER ISA
310 bigendian dynamically switches between big and little endian decoding
311 (reverses byte order). See V3.0B p44 1.11.2
314 def __init__(self
, width
, dec
):
315 PowerDecoder
.__init
__(self
, width
, dec
)
316 self
.fields
= df
= DecodeFields(SignalBitRange
, [self
.opcode_in
])
317 self
.fields
.create_specs()
318 self
.raw_opcode_in
= Signal
.like(self
.opcode_in
, reset_less
=True)
319 self
.bigendian
= Signal(reset_less
=True)
321 for name
, value
in self
.fields
.common_fields
.items():
322 sig
= Signal(value
[0:-1].shape(), reset_less
=True, name
=name
)
323 setattr(self
, name
, sig
)
325 # create signals for all field forms
326 self
.form_names
= forms
= self
.fields
.instrs
.keys()
329 fields
= self
.fields
.instrs
[form
]
331 Fields
= namedtuple("Fields", fk
)
333 for k
, value
in fields
.items():
334 name
= "%s_%s" % (form
, k
)
335 sig
= Signal(value
[0:-1].shape(), reset_less
=True, name
=name
)
338 setattr(self
, "Form%s" % form
, instr
)
339 self
.sigforms
[form
] = instr
341 def elaborate(self
, platform
):
342 m
= PowerDecoder
.elaborate(self
, platform
)
344 raw_be
= self
.raw_opcode_in
346 for i
in range(0, self
.width
, 8):
347 l
.append(raw_be
[i
:i
+8])
350 comb
+= self
.opcode_in
.eq(Mux(self
.bigendian
, raw_be
, raw_le
))
352 # add all signal from commonly-used fields
353 for name
, value
in self
.fields
.common_fields
.items():
354 sig
= getattr(self
, name
)
355 comb
+= sig
.eq(value
[0:-1])
357 # link signals for all field forms
358 forms
= self
.form_names
360 sf
= self
.sigforms
[form
]
361 fields
= self
.fields
.instrs
[form
]
362 for k
, value
in fields
.items():
364 comb
+= sig
.eq(value
[0:-1])
369 return [self
.raw_opcode_in
, self
.bigendian
] + PowerDecoder
.ports(self
)
372 ####################################################
373 # PRIMARY FUNCTION SPECIFYING THE FULL POWER DECODER
375 def create_pdecode():
376 """create_pdecode - creates a cascading hierarchical POWER ISA decoder
379 # minor 19 has extra patterns
381 m19
.append(Subdecoder(pattern
=19, opcodes
=get_csv("minor_19.csv"),
382 opint
=True, bitsel
=(1, 11), suffix
=None, subdecoders
=[]))
383 m19
.append(Subdecoder(pattern
=19, opcodes
=get_csv("minor_19_00000.csv"),
384 opint
=True, bitsel
=(1, 6), suffix
=None, subdecoders
=[]))
389 Subdecoder(pattern
=30, opcodes
=get_csv("minor_30.csv"),
390 opint
=True, bitsel
=(1, 5), suffix
=None, subdecoders
=[]),
391 Subdecoder(pattern
=31, opcodes
=get_csv("minor_31.csv"),
392 opint
=True, bitsel
=(1, 11), suffix
=0b00101, subdecoders
=[]),
393 Subdecoder(pattern
=58, opcodes
=get_csv("minor_58.csv"),
394 opint
=True, bitsel
=(0, 2), suffix
=None, subdecoders
=[]),
395 Subdecoder(pattern
=62, opcodes
=get_csv("minor_62.csv"),
396 opint
=True, bitsel
=(0, 2), suffix
=None, subdecoders
=[]),
399 # top level: extra merged with major
401 opcodes
= get_csv("major.csv")
402 dec
.append(Subdecoder(pattern
=None, opint
=True, opcodes
=opcodes
,
403 bitsel
=(26, 32), suffix
=None, subdecoders
=pminor
))
404 opcodes
= get_csv("extra.csv")
405 dec
.append(Subdecoder(pattern
=None, opint
=False, opcodes
=opcodes
,
406 bitsel
=(0, 32), suffix
=None, subdecoders
=[]))
408 return TopPowerDecoder(32, dec
)
411 if __name__
== '__main__':
412 pdecode
= create_pdecode()
413 vl
= rtlil
.convert(pdecode
, ports
=pdecode
.ports())
414 with
open("decoder.il", "w") as f
: