[RFC] Python vs Magma if statements in combinational

[leonardt]

Overview

The goal is to allow the use of the if statement to describe both Python (metaprogram/generator) control flow and magma (hardware) control logic. The existing combinational syntax only supports converting all if statements to mux logic via SSA. By allowing Python if statements, the user can interleave generator code inside their combinational syntax (this is a main gripe with adopting the combinational syntax, in that it doesn't seamlessly integrate with core magma generator code).

Issues

1. Distinguishing between Python vs magma ifs - If we allow both styles of if statements to appear in the code, we should develop a syntax for easily specifying which kind of if statement is desired. This explicit approach will be much simpler to implement than analyzing the code to determine if an if statement should be executed in Python or magma.
   • Option 1 - since combinational currently uses if to implicitly map to muxes, we can add a function call to indicate that an if statement should be evaluated in python, for example:

     if eval(cond_a and not cond_b):
         ...
     

     other options might be to use a magma specific construct, such as m.python(...) or an ast_tools style macro such as ast_tools.macro(...) (more on this in the next section on when ifs are evaluated).
   • Option 2 - we change the combinational syntax to use implicit Python ifs, and use an explicit magma mux function to mark an if that should be transformed, for example:

     if m.mux(x & y):
         ...
     

     This has the nice property that if statements are now treated as they are expected (Python code) unless explicitly marked by the user (no more implicit SSA conversion). The downside is that this will break existing combinational code.
   • Option 3 - make both explicit (i.e. mark python ifs with a function call and magma ifs with a mux call). This is the most explicit option, and would allow us to error if the user does not provide a wrapper (forcing them to acknowledge and specify which kind of if statement they want). This is strict, but could be tedious.
2. When to evaluate Python ifs - Once a syntax is chosen, another problem to address is when if statements are evaluated. There are two choices:
   • Option 1 - Evaluate as a macro - This would run a pass over the combinational program and rewrite it by evaluate if statements to generate a new program. This fits nicely into our ast_tools pattern and the fact that we're already doing rewrites, but the downside is that it requires conditions be evaluated at macro time (before the combinational program runs). This would mean that the following code would not work since y = True would not be executed during macro expansion.

     if ast_tools.macro(x):
          y = True
     ...
     if ast_tools.macro(y):
         ...
     

   • Option 2 - Use function call as marker to block SSA conversion. This would effectively introduce some logic in SSA that would allow us to mark certain if statements to not be processed by the SSA logic. This might be complicated to implement, but would resolve the above issue since the if statements would be run when the combinational program is constructed. I haven't thought too deeply on whether it would be complicated to support this pattern in SSA (CC @cdonovick). This also has the benefit of not having to require that the user think about macros, which tends to make things more complicated.

Summary

There are two key issues: how should we specify whether an if statement is to be executed in Python versus Magma, and when are if statements evaluated. My initial reaction is if I was doing the combinational syntax from scratch, I would choose an implicit python if (so normal if statements execute normally) and an explicit magma if (so wrap conditions in mux for SSA conversion). With this in mind, I would use the approach to have SSA only performed on if statements marked explicitly, since this approach is more expressive and allows more natural programs to be written (don't have to separate compile time and runtime logic for macros). The downside to this is we would have to change the combinational syntax in a breaking way, and that the SSA implementation will become more complicated. We could compromise and avoid changing syntax by using an explicit python if marker. We could also use macros, the implementation would likely be simpler than extending SSA and offer some basic functionality quickly (and perhaps allow us to see if this is sufficient for most use cases).

[splhack]

How about having @m.inline_python in combinational? The opposite counterpart of @m.inline_combinational in Python.

Inside @m.inline_python, SSA only does Magma value conversion. It allows to write Python if, for, etc in combinational.