Coding conventions

Introduction

The coding conventions used in SpinalHDL are the same as the ones documented in the scala doc.

Some additional practical details and cases are explained in next chapters.

class vs case class

When you define a Bundle or a Component, have a preference to declare them as case class.

The reasons are:

It avoids the use of new keywords. Never having to use it is better than sometimes under some conditions.
A case class provides an clone function. This is useful in SpinalHDL where there is a need to clone one Bundle. For example, when you define a new Reg or a new Stream of some kind.
Construction parameters are directly visible from outside.

[case] class

All classes names should start with a upper case letter

class Fifo extends Component {

}

class Counter extends Area {

}

case class Color extends Bundle {

}

companion object

A companion object should start with a upper case letter.

object Fifo {
  def apply(that: Stream[Bits]): Stream[Bits] = {...}
}

object MajorityVote {
  def apply(that: Bits): UInt = {...}
}

An exception to this rule is when the companion object is used as a function (only apply inside), and these apply functions don’t generate hardware:

object log2{
  def apply(value: Int): Int = {...}
}

function

A function should always start with a lower case letter:

def sinTable = (0 until sampleCount).map(sampleIndex => {
  val sinValue = Math.sin(2 * Math.PI * sampleIndex / sampleCount)
  S((sinValue * ((1 << resolutionWidth) / 2 - 1)).toInt, resolutionWidth bits)
})

val rom =  Mem(SInt(resolutionWidth bit),initialContent = sinTable)

instances

Instances of classes should always start with a lower case letter:

val fifo   = new Fifo()
val buffer = Reg(Bits(8 bits))

if / when

Scala if and SpinalHDL when should normally be written in the following way:

if(cond){
  ...
} else if(cond){

} else {

}

when(cond){

}.elseWhen(cond){

}.otherwise{

}

Exceptions could be:

It’s fine to omit the dot before otherwise.
It’s fine to compress a whole if/when statements on a single line if it makes the code more readable.

switch

SpinalHDL switch should normally be written in the following way:

switch(value){
  is(key){

  }
  is(key){

  }
  default{

  }
}

It’s fine to compress a is/default statement on a single line if it makes the code more readable.

Parameters

Grouping parameters of a component/bundle inside a case class is in general welcome:

Easier to carry/manipulate to configure the design
Better maintainability

case class RgbConfig(rWidth: Int, gWidth: Int, bWidth: Int){
  def getWidth = rWidth + gWidth + bWidth
}

case class Rgb(c: RgbConfig) extends Bundle {
  val r = UInt(c.rWidth bit)
  val g = UInt(c.gWidth bit)
  val b = UInt(c.bWidth bit)
}

But this should not be applied in all cases. For example: in a Fifo, it doesn’t make sense to group the dataType parameter with the depth of the fifo because, in general, the dataType is something related to the design, while the depth is something related to the configuration of the design.

class Fifo[T <: Data](dataType: T, depth: Int) extends Component {

}