Black box, empty box, and unknown box
From Verific Design Automation FAQ
In the Verific Netlist Database, a Netlist can be a black box, an empty box, or an unknown box (and of course, a "normal" box).
- An unknown box is a Netlist that is:
- from an instantiation of an undefined Verilog module
- from an instantiation of a VHDL component without binding entity
- A black box is a Netlist that contains no Instances (NumOfInsts() == 0) and no Nets ((NumOfNets() == 0). It can be:
- an unknown box
- a Verific Primitive or Operator
- a Netlist that has errors during RTL elaboration
- set from VeriModule::SetCompileAsBlackbox()
- set from VhdlPrimaryUnit::SetCompileAsBlackbox()
- An empty box is a Netlist that contains no Instances and no port-to-port connections. It can be:
- a black box
- a user-defined module/entity with ports but no contents
- a user-defined module/entity that has no assignments to its outputs
Note that all ports of a Verilog unknown box are assumed to be 'inout' due to the lack of data. VHDL requires a component declaration so port directions are known.
If it is desired to have the user-defined module declarations written out into the Verilog output netlist, including those of black boxes and empty boxes, the runtime flag 'db_verilog_writer_write_blackboxes' can be set to different values to control this behavior:
- value > 1: print all Netlists except Primitives
- value = 1: print all Netlists except Primitives and Netlists with ' unknown_design' attribute
- value = 0: print all Netlists except Primitives, Netlists with ' unknown_design' attribute and 'IsBlackBox()' Netlists
- default value = 0
For more details on how the Verific RTL elaborator handles Instances of unknown boxes, please read How Verific elaborator handles blackboxes/unknown boxes
#include "Set.h"
#include "Message.h"
#include "Strings.h"
#include "veri_file.h"
#include "vhdl_file.h"
#include "VeriModule.h"
#include "VeriWrite.h"
#include "DataBase.h"
#ifdef VERIFIC_NAMESPACE
using namespace Verific ;
#endif
void Accumulate(Netlist *netlist, Set &done) ;
int main() {
vhdl_file::SetDefaultLibraryPath("../vdbs");
if (!vhdl_file::Analyze("fromvhdl.vhd")) return 1 ;
if (!veri_file::Analyze("test.v", veri_file::VERILOG_2K)) return 1 ;
// blackboxing module "willbeblackboxed"
VeriModule *tobeblackboxed = veri_file::GetModule("willbeblackboxed");
tobeblackboxed->SetCompileAsBlackbox();
veri_file::Elaborate("top");
Netlist *top = Netlist::PresentDesign() ;
if (!top) {
Message::PrintLine("cannot find any handle to the top-level netlist") ;
return 1 ;
}
Message::Msg(VERIFIC_INFO, 0, top->Linefile(), "top level design is '%s(%s)'",
top->Owner()->Name(), top->Name()) ;
// Lets accumulate all netlist
Set netlists(POINTER_HASH) ;
Accumulate(top, netlists) ;
// Iterate over all Netlists in the design
Netlist *netlist ;
SetIter si ;
FOREACH_SET_ITEM(&netlists, si, &netlist) {
Message::Msg(VERIFIC_INFO, 0, 0, "*** netlist '%s' of cell '%s'", netlist->Name(), netlist->Owner()->Name()) ;
// What language does it come from?
if (netlist->GetAttValue(" language")) {
Message::Msg(VERIFIC_INFO, 0, 0, " from %s", netlist->GetAttValue(" language"));
} else {
Message::Msg(VERIFIC_INFO, 0, 0, " no language");
}
// Is it a Verific primitive or operator?
if (netlist->IsPrimitive() || netlist->IsOperator()) {
Message::Msg(VERIFIC_INFO, 0, 0, " a primitive/operator");
}
// Check attribute for unknown box
const Att *attr = netlist->GetAtt(" unknown_design"); // note the leading space character
if (attr) {
if (Strings::compare (attr->Value(),"1")) {
// attribute value = "1" : instantiated in a Verilog module
Message::Msg(VERIFIC_INFO, 0, 0, " an unknown box instantiated in a Verilog module");
}
else if (Strings::compare (attr->Value(),"2")) {
// attribute value = "2" : instantiated in a VHDL architecture
Message::Msg(VERIFIC_INFO, 0, 0, " an unknown box instantiated in a VHDL architecture");
}
}
if (netlist->IsBlackBox()) {
Message::Msg(VERIFIC_INFO, 0, 0, " a black box");
}
if (netlist->IsEmptyBox()) {
Message::Msg(VERIFIC_INFO, 0, 0, " an empty box");
}
}
VeriWrite veriWriter;
veriWriter.WriteFile("netlistout.v", top) ;
return 0 ;
}
// This function is recursive in nature, and collects all other
// netlists that the incoming netlist depends on in a container.
void Accumulate(Netlist *netlist, Set &done)
{
if (!netlist) return ; // Ignore NULL netlists
SetItem *item = done.GetItem(netlist) ;
if (item) {
return ; // We've already been here
}
Instance *inst ;
MapIter mi ;
FOREACH_INSTANCE_OF_NETLIST(netlist, mi, inst) {
// Now go into the netlist associated with the instance
Accumulate(inst->View(), done) ;
}
done.Insert(netlist) ;
}
test.v
module nocontents (input a, output o);
endmodule
module willbeblackboxed (input a, b, output o);
assign o = a ^ b;
endmodule
module containserror (input a, b, output o);
assign o = a & b;
assign o = a | b;
endmodule
module emptybox (input a, output o); // no outputs are driven
wire i = a;
endmodule
module normal (input a, b, output o);
assign o = a & b;
endmodule
module top (input i1, i2, i3, i4, i5, i6, i7, i8, i9, ia, ib,
output o1, o2, o3, o4, o5);
nocontents u_nocontents (i1, o1);
willbeblackboxed u_willbeblackboxed (i2, i3, o2);
containserror u_containserror (i4, i5, o3);
emptybox u_emptybox (i9, );
unknownverilog u_unknownverilog (i6, o4);
normal u_normal (i7, i8, o5);
fromvhdl u_fromvhdl (ia, ib, o6);
endmodule
fromvhdl.vhd:
library std;
use std.all;
entity fromvhdl is
port ( a, b: in bit; o: out bit );
end entity;
architecture test of fromvhdl is
component unknownvhdl
port ( a, b : in bit; o : out bit);
end component;
begin
u_unknownvhdl: unknownvhdl port map (a, b, o);
end architecture;
Run:
$ test-linux INFO: The default VHDL library search path is now "/mnt/Verific/extra_tests/vdbs" (VHDL-1504) -- Analyzing VHDL file 'fromvhdl.vhd' (VHDL-1481) -- Restoring VHDL parse-tree 'std.standard' from '/mnt/Verific/extra_tests/vdbs/std/standard.vdb' (VHDL-1493) fromvhdl.vhd(3): INFO: analyzing entity 'fromvhdl' (VHDL-1012) fromvhdl.vhd(6): INFO: analyzing architecture 'test' (VHDL-1010) -- Analyzing Verilog file 'test.v' (VERI-1482) test.v(21): INFO: compiling module 'top' (VERI-1018) test.v(1): INFO: compiling module 'nocontents' (VERI-1018) test.v(4): INFO: compiling module 'willbeblackboxed' (VERI-1018) test.v(8): INFO: compiling module 'containserror' (VERI-1018) test.v(9): ERROR: net 'o' is constantly driven from multiple places (VDB-1000) test.v(10): ERROR: another driver from here (VDB-1001) test.v(8): INFO: module 'containserror' remains a black box, due to errors in its contents (VERI-1073) test.v(13): INFO: compiling module 'emptybox' (VERI-1018) test.v(27): WARNING: instantiating unknown module 'unknownverilog' (VERI-1063) test.v(17): INFO: compiling module 'normal' (VERI-1018) test.v(29): INFO: going to VHDL side to elaborate design unit 'fromvhdl' (VERI-1231) fromvhdl.vhd(3): INFO: executing 'fromvhdl(test)' (VHDL-1067) fromvhdl.vhd(9): WARNING: 'unknownvhdl' remains a black box since it has no binding entity (VHDL-1250) test.v(29): INFO: back to Verilog to continue elaboration (VERI-1232) test.v(21): INFO: top level design is top() INFO: *** netlist '' of cell 'nocontents' INFO: from verilog INFO: an empty box INFO: *** netlist '' of cell 'willbeblackboxed' INFO: from verilog INFO: a black box INFO: an empty box INFO: *** netlist '' of cell 'containserror' INFO: from verilog INFO: a black box INFO: an empty box INFO: *** netlist 'INTERFACE' of cell 'VERIFIC_BUF' INFO: no language INFO: a primitive/operator INFO: a black box INFO: an empty box INFO: *** netlist '' of cell 'emptybox' INFO: from verilog INFO: *** netlist 'OrderedPorts' of cell 'unknownverilog' INFO: no language INFO: an unknown box instantiated in a Verilog module INFO: a black box INFO: an empty box INFO: *** netlist 'INTERFACE' of cell 'VERIFIC_AND' INFO: no language INFO: a primitive/operator INFO: a black box INFO: an empty box INFO: *** netlist '' of cell 'normal' INFO: from verilog INFO: *** netlist '' of cell 'unknownvhdl' INFO: from vhdl INFO: an unknown box instantiated in a VHDL architecture INFO: a black box INFO: an empty box INFO: *** netlist 'test' of cell 'fromvhdl' INFO: from vhdl INFO: *** netlist '' of cell 'top' INFO: from verilog -- Writing netlist 'top' to Verilog file 'netlistout.v' (VDB-1030) $
