The HDL Complexity Tool (HCT)
=============================

SUMMARY
-------

The goal of the HCT is to generate scores that represent the complexity of the constituent 
modules of large IC design projects – i.e. SOCs. The design's complexity scores are useful 
to verification teams so as to efficiently focus resources based on the dynamic complexity 
profile of a design. The scores are a useful tool to guide HDL designer's refactoring efforts. 
This data provides an efficient way to "come up to speed", by pointing you to the most 
important modules of a legacy design. Importantly, the complexity scores allow managers to 
estimate schedules and resources in a more robust and effective way than any one standard 
metric can provide (SLOC for example).

The metrics that compose the score are derived directly from the HDL source code using a 
parser. Metrics that are used are chosen to provide a good cross section of complexity. 
For example, a measure of the Cyclomatic complexity of a module along with the hierarchy of 
modules within a module are taken into account to produce the score. Metrics are based on 
well established and published methods. After computing the metrics of a design, they are 
scaled and then used to create a score by incorporating the user defined weights (yes, there 
is a default). In this way, a set of scores are "tunable" and therefore provide the greatest 
amount of flexibility to the user and at the same time are based on standard measurements of 
the design.

The HDL Complexity Tool is a simple tool to provide measurement data. The driving concept being 
that you cannot control what you cannot measure. We intend to use existing research to develop 
a tool that performs well on a set of real projects.

Actual defect data will be used to test complexity as a technique to identify risky components. 
Real designs will be measured to determine what are the practical uses of hct. In the end, this 
tool should be practically useful to anyone designing and/or verifying a complex hardware project.


INSTALLATION
------------

Please refer to the document called "INSTALL" in the same directory as this README.


DESIGN
------

The HCT is continuously evolving. We are starting with McCabe Cyclomatic Complexity analysis to 
understand branch complexity. Then we are improving this with more sophisticated complexity scores 
that are calibrated with real defect data.

A good background on this is available. Please refer to "Measuring the Complexity of HDL Models" 
by Michael Schafers. Following we have a few excerpts that we use as design criteria for HCT.

There are a few HDL complexity factors that are defined in that paper:

    * size
    * nesting
    * control flow
    * information flow
    * hierarchy
    * locality
    * regularity
    * modularity
    * coupling (of modules or instances)
    * concurrency
    * timing

In that paper, the idea of psychological complexity of HDL is introduced and the common aspects as 
well as differences of the software versus hardware design complexity are analyzed. The point is that 
a good complexity score will adhere to six rules:

    * The measure has to be based on a formal foundation
    * The measure has to be intuitive
    * Models under development have to be measurable
    * A Structured model has to be measured as less complex than an unstructured version
    * Adding new parts to the model has to increase the complexity
    * Replacing one part of the model by a more complex part has to increase complexity

Those are six lofty goals when you start to think about them. The transitivity implied by them is 
going to be tough to achieve. However, we are shooting for this and should use it as a guiding light.

The HCT development teams uses feedback from users like you working on real projects to identify 
shortcomings in our parser as well as to iteratively refine our scoring system and metrics. Iteration 
on a pure and simple generic parsing and computation framework is key to effective iterative design. 
Therefore, we strive to build an elegant software architecture by leveraging the right mix of 
ingredients from of our chosen implementation language – PERL.

The end goal being to properly score the psychological complexity of hardware blocks in any HDL and 
use this to predict defect rates and schedule risks.


HELP
----

Execute: "hct -h"


COPYRIGHT
---------

Copyright 2008-2009 Slade Maurer

HCT is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

HCT is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with HCT.  If not, see <http://www.gnu.org/licenses/>.