Commit 8db0ad04 authored by Bruno FERRES's avatar Bruno FERRES
Browse files

Version 1.0.0

### Project Specific stuff
### XilinxISE template
# intermediate build files
# project-wide generated files
# generated folders
### Eclipse template
# Eclipse Core
# External tool builders
# Locally stored "Eclipse launch configurations"
# CDT-specific
# JDT-specific (Eclipse Java Development Tools)
# Java annotation processor (APT)
# PDT-specific
# sbteclipse plugin
# TeXlipse plugin
### C template
# Object files
# Precompiled Headers
# Libraries
# Shared objects (inc. Windows DLLs)
# Executables
# Debug files
### SBT template
# Simple Build Tool
### Emacs template
# -*- mode: gitignore; -*-
# Org-mode
# flymake-mode
# eshell files
# elpa packages
# reftex files
# AUCTeX auto folder
# cask packages
### Vim template
### JetBrains template
# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio
## Directory-based project format:
# if you remove the above rule, at least ignore the following:
# User-specific stuff:
# .idea/workspace.xml
# .idea/tasks.xml
# .idea/dictionaries
# Sensitive or high-churn files:
# .idea/dataSources.ids
# .idea/dataSources.xml
# .idea/sqlDataSources.xml
# .idea/dynamic.xml
# .idea/uiDesigner.xml
# Gradle:
# .idea/gradle.xml
# .idea/libraries
# Mongo Explorer plugin:
# .idea/mongoSettings.xml
## File-based project format:
## Plugin-specific files:
# IntelliJ
# mpeltonen/sbt-idea plugin
# JIRA plugin
# Crashlytics plugin (for Android Studio and IntelliJ)
### C++ template
# Compiled Object files
# Precompiled Headers
# Compiled Dynamic libraries
# Fortran module files
# Compiled Static libraries
# Executables
### OSX template
# Icon must end with two \r
# Thumbnails
# Files that might appear in the root of a volume
# Directories potentially created on remote AFP share
Network Trash Folder
Temporary Items
### Xcode template
# Xcode
# gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore
## Build generated
## Various settings
## Other
### Scala template
# sbt specific
# Scala-IDE specific
### Java template
# Mobile Tools for Java (J2ME)
# Package Files #
# virtual machine crash logs, see
rules = [
align.preset = more
align.stripMargin = true
maxColumn = 120
assumeStandardLibraryStripMargin = true
continuationIndent.callSite = 4
continuationIndent.defnSite = 4
continuationIndent.ctorSite = 4
continuationIndent.extendSite = 4
continuationIndent.withSiteRelativeToExtends = 0
docstrings.wrap = yes
docstrings.oneline = fold = AsteriskSpace
comments.wrap = standalone
comments.wrapStandaloneSlcAsSlc = true
This diff is collapsed.
**QECE** (*Quick Exploration using Chisel Estimators*) is a **chisel based** project to provide circuit estimators and exploration functions for FPGA design processes.
## Structure
Sources can be found under `./src/main/scala/...` and associated unit-tests under `./src/test/scala/...`
Project is divided in different submodules:
* global project configuration file is `./src/main/scala/ProjectConfig.scala`
* resources for integration in other chisel projects are to be found in `./src/main/resources/...`
* estimation transforms can be found in `./src/main/scala/estimation/...`
* exploration relative functions - including exploration strategies - can be found in `./src/main/scala/exploration/...`
* backend bindings are available in `./src/main/scala/backend/...` - only Xilinx Virtex 7 boards are available currently
* characterization functions - *i.e.* functions to generate a characterized library of operators and macros for a given target board - can be found in `./src/main/scala/characterization/...`
## Running
To run the transformations on your own project, you need to take a few steps:
* publish your transformations on your environment, using `sbt quickPublish` (as `sbt publishLocal` generates *scaladoc*, which currently results in a bug)
* in your project, update the `build.sbt` with `libraryDependencies += "fr.tima" %% "chisel-transforms" % "1.0.0"`
* you can access to the different classes with `import qece.<package>.<Class>`
**N.B.:** You may have to reload/update your `sbt` project.
## Estimations
Three kinds of estimators are considered at the moment: **resource estimation**, **frequency estimation** and **quality of result estimation**.
* FIRRTL based **resource estimation** is based on prior **macro replacement** of some patterns in the circuits, and uses a library of characterized operators.</br>
Such library is to be found in `./src/main/resources/lib/<target>.json`, and can be generated using `qece.characterization.LibraryBuilder` class (`./src/main/scala/characterization/Library.scala`).</br>
Another resource estimator is based on **synthesis results** through backend calls.
* **Quality of result estimation** is based on an empirical approach, leveraging simulator bindings to provide insights of circuit behavior.
* FIRRTL based **frequency estimation** is currently deprecated, as chosen approach result in complex and non accurate estimations.</br>
However, frequency estimation through **synthesis results** are available using backend API.
Estimators can be call by using `qece.estimation.WithTransform` trait - and examples are to be found in `./src/test/scala/estimation/...`.
## Exploration
In order to be explorable, a **chisel** `Module` must implement `qece.exploration.utils.WithExplorable` trait - you can directly extend `qece.exploration.utils.Explorable` class to build a `MultiIOModule` implementing this trait.
Strategies can be defined using `qece.exploration.strategies.StrategyBuilder` - and examples are to be found in `./src/test/scala/exploration/strategies/...`.
## Linting
The code base is checked with a linter. We use three different linters:
* scalastyle is used to check the code base for formatting prior to merge.
* scalafmt is configure with the same parameters than scalastyle. It should be run before pushing, in order to limit
scalastyle errors. scalafmt is not able to check everything, especially it does not enforce names
* scalafix is used to check (and fix if run locally) semantic and syntactic rules (for now, only unused imports)
In order to automatically apply formatting rules, run:
In order to check the rules locally, you can run the following commands in sbt:
## Contact
Feel free to contact me at [](
The project was developed in **SLS team** at [TIMA lab](, under the supervision of [Frédéric ROUSSEAU]( and [Olivier MULLER](
// See for license details.
ThisBuild / scalaVersion := "2.12.12"
ThisBuild / version := "1.0.0"
ThisBuild / organization := "fr.tima"
parallelExecution in Test := true
lazy val root = (project in file("."))
name := "qece",
logLevel := Level.Warn,
libraryDependencies ++=
"edu.berkeley.cs" %% "chisel3" % "3.4.3",
"edu.berkeley.cs" %% "chisel-iotesters" % "1.5.3",
"edu.berkeley.cs" %% "chiseltest" % "0.3.3" % "test"
) ++ Seq( // used for reflectivity
"org.scala-lang" % "scala-compiler" % scalaVersion.value
) ++ Seq(
"org.apache.commons" % "commons-math3" % "3.3"
) ++ Seq( // used for json ser/des
"io.circe" %% "circe-core",
"io.circe" %% "circe-generic",
"io.circe" %% "circe-parser"
).map(_ % "0.12.3"),
scalacOptions ++= Seq(
addCompilerPlugin("edu.berkeley.cs" % "chisel3-plugin" % "3.4.2" cross CrossVersion.full),
addCompilerPlugin("org.scalamacros" % "paradise" % "2.1.1" cross CrossVersion.full)
/* ---------- LINTING ------------- */
// Necessary for scalafix
scalaVersion := scalaVersion.value,
semanticdbEnabled := true,
semanticdbVersion := scalafixSemanticdb.revision
addCommandAlias("lint", "scalafmt; test:scalafmt; scalafix; test:scalafix")
addCommandAlias("lintCheck", "; scalastyle; test:scalastyle" +
"; scalafmtCheck; test:scalafmtCheck" +
"; scalafix --check; test:scalafix --check")
/* ---- Stack overflow exception occurs when doc is generated ---- */
addCommandAlias("disableDocGeneration", "set publishArtifact in(Compile, packageDoc) := false")
addCommandAlias("enableDocGeneration", "set publishArtifact in(Compile, packageDoc) := true")
addCommandAlias("quickPublish", "disableDocGeneration; publishLocal; enableDocGeneration")
addCommandAlias("disableParallel", "set parallelExecution in Test := false;")
addCommandAlias("enableParallel", "set parallelExecution in Test := true;")
/* ------------ TEST --------------- */
// non regression tests,
addCommandAlias("unitTests", "testOnly -- -l Long -l Synthesis -l Deprecated")
// Disabling parallelExecution on heavy tests to avoid crashes
addCommandAlias("longTests", "disableParallel; testOnly -- -l Deprecated; enableParallel")
addCommandAlias("synthesisTests", "disableParallel; testOnly -- -n Synthesis -l Deprecated; enableParallel")
sbt.version = 1.3.4
logLevel := Level.Warn
addSbtPlugin("org.scalastyle" %% "scalastyle-sbt-plugin" % "1.0.0")
addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.4.0") // "2.4.0" is just sbt plugin version
addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.9.19")
<name>Scalastyle standard configuration</name>
<check level="warning" class="org.scalastyle.file.FileTabChecker" enabled="true"></check>
<check level="warning" class="org.scalastyle.file.FileLengthChecker" enabled="false">
<check level="warning" class="org.scalastyle.file.HeaderMatchesChecker" enabled="false">
<parameter name="header"><![CDATA[// Copyright (C) 2011-2012 the original author or authors.
// See the LICENCE.txt file distributed with this work for additional
// information regarding copyright ownership.
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.]]></parameter>
<check level="warning" class="org.scalastyle.scalariform.SpacesAfterPlusChecker" enabled="true"></check>
<check level="warning" class="org.scalastyle.file.WhitespaceEndOfLineChecker" enabled="true"></check>
<check level="warning" class="org.scalastyle.scalariform.SpacesBeforePlusChecker" enabled="true"></check>
<check level="error" class="org.scalastyle.file.FileLineLengthChecker" enabled="true">
<parameter name="maxLineLength"><![CDATA[120]]></parameter>
<parameter name="tabSize"><![CDATA[2]]></parameter>
<check level="error" class="org.scalastyle.scalariform.ClassNamesChecker" enabled="true">
<parameter name="regex"><![CDATA[[A-Z][A-Za-z0-9]*]]></parameter>
<check level="error" class="org.scalastyle.scalariform.ObjectNamesChecker" enabled="true">
<parameter name="regex"><![CDATA[[A-Z][A-Za-z0-9]*]]></parameter>
<check level="error" class="org.scalastyle.scalariform.PackageObjectNamesChecker" enabled="true">
<parameter name="regex"><![CDATA[^[a-z][A-Za-z0-9]*$]]></parameter>
<check level="warning" class="org.scalastyle.scalariform.EqualsHashCodeChecker" enabled="true"></check>
<check level="warning" class="org.scalastyle.scalariform.IllegalImportsChecker" enabled="true">
<parameter name="illegalImports"><![CDATA[sun._,java.awt._]]></parameter>
<check level="warning" class="org.scalastyle.scalariform.ParameterNumberChecker" enabled="false">
<parameter name="maxParameters"><![CDATA[8]]></parameter>
<check level="info" class="org.scalastyle.scalariform.MagicNumberChecker" enabled="true">
<parameter name="ignore"><![CDATA[-1,0,1,2,3]]></parameter>
<check level="error" class="org.scalastyle.scalariform.NoWhitespaceBeforeLeftBracketChecker" enabled="true"></check>
<check level="error" class="org.scalastyle.scalariform.NoWhitespaceAfterLeftBracketChecker" enabled="true"></check>
<check level="info" class="org.scalastyle.scalariform.ReturnChecker" enabled="true"></check>
<check level="error" class="org.scalastyle.scalariform.NullChecker" enabled="true"></check>
<check level="error" class="org.scalastyle.scalariform.NoCloneChecker" enabled="true"></check>
<check level="error" class="org.scalastyle.scalariform.NoFinalizeChecker" enabled="true"></check>
<check level="error" class="org.scalastyle.scalariform.CovariantEqualsChecker" enabled="true"></check>
<check level="error" class="org.scalastyle.scalariform.StructuralTypeChecker" enabled="true"></check>
<check level="warning" class="org.scalastyle.file.RegexChecker" enabled="false">
<parameter name="regex"><![CDATA[println]]></parameter>
<check level="warning" class="org.scalastyle.scalariform.NumberOfTypesChecker" enabled="false">
<parameter name="maxTypes"><![CDATA[30]]></parameter>
<check level="warning" class="org.scalastyle.scalariform.CyclomaticComplexityChecker" enabled="true">
<parameter name="maximum"><![CDATA[50]]></parameter>
<check level="error" class="org.scalastyle.scalariform.UppercaseLChecker" enabled="true"></check>
<check level="warning" class="org.scalastyle.scalariform.SimplifyBooleanExpressionChecker" enabled="true"></check>
<check level="error" class="org.scalastyle.scalariform.IfBraceChecker" enabled="true">
<parameter name="singleLineAllowed"><![CDATA[true]]></parameter>
<parameter name="doubleLineAllowed"><![CDATA[false]]></parameter>
<check level="warning" class="org.scalastyle.scalariform.MethodLengthChecker" enabled="true">
<parameter name="maxLength"><![CDATA[30]]></parameter>
<check level="error" class="org.scalastyle.scalariform.FieldNamesChecker" enabled="true">
<parameter name="regex"><![CDATA[^[a-z_][A-Za-z0-9]*$]]></parameter>
<parameter name="objectFieldRegex"><![CDATA[^[a-z_][A-Za-z0-9]*$]]></parameter>
<check level="error" class="org.scalastyle.scalariform.MethodNamesChecker" enabled="true">
<parameter name="regex"><![CDATA[^[a-z][A-Za-z0-9]*$]]></parameter>
<parameter name="ignoreRegex"><![CDATA[^[:=<>!?~+-[*]].*$]]></parameter>
<check level="warning" class="org.scalastyle.scalariform.NumberOfMethodsInTypeChecker" enabled="false">
<parameter name="maxMethods"><![CDATA[30]]></parameter>
<check level="warning" class="org.scalastyle.scalariform.PublicMethodsHaveTypeChecker" enabled="false"></check>
<check level="warning" class="org.scalastyle.file.NewLineAtEofChecker" enabled="true"></check>
<check level="warning" class="org.scalastyle.file.NoNewLineAtEofChecker" enabled="false"></check>