What is the meaning of Masked() in Scala's library SpinalHDL

Question

I have seen many spinal cases using Masked(), but don't truly understand it. The source code is:

object Masked{
  def apply(ml : MaskedLiteral) : Masked = Masked(ml.value, ml.careAbout)
  def apply(lit : Any) : Masked = lit match {
    case e: SpinalEnumElement[_] => Masked(e.spinalEnum.defaultEncoding.getValue(e), (BigInt(1) << e.spinalEnum.defaultEncoding.getWidth(e.spinalEnum))-1)
    case bt: BaseType => bt.head.source match {
      case lit : Literal => Masked(lit.getValue(), (BigInt(1) << widthOf(bt))-1)
    }
  }
}

Answer 1

The top google hit for me at this time for "Masked SpinalHDL" provide the link into documentation at: https://spinalhdl.github.io/SpinalDoc-RTD/dev/SpinalHDL/Developers%20area/types.html

A Ctrl-F (to find) and type the word "Masked".

In the section marked Masked comparison there is a basic outline of what it does and the usage from the Scala language.

It can be used with an equality expression, when comparing a bus-of-bits (to use Verilog terms) against a pattern where the bit pattern (in hardware) being compared has the 2 usual states (0 or 1) but the Mask described in Scala code has 3 states:

• I care the bit is reset (0,LOW,off)
• I care the bit is set (1,HIGH,on)
• I don't care what state this bit position is.

From this an equality expression (using operators === or =/=) against the Masked value, provides a True or False result.

This might be considered a convenience method to describe the bit-pattern of interest in a form that is easier to read.

The alternative in Verilog maybe to isolate each bit you are interested in, into a wire the width of the bus-of-interesting-bits. The compare this to a constant. If you do this by hand you end up with a form in Verilog that is much more difficult to read (and therefore understand for the next designer). This introduces many angles for errors to occur. So the concept here is to be expressive while reducing chance for a design error.

It would not be valid to write a mask pattern where you describe all bit positions marked as Don't Care what state this bit position is.