Document the (* whitebox *) (and related attribute)

[mithro]

There are many black box modules in the tests, which have the (* whitebox *) attribute. For example:

/*
 * `input wire a` should be detected as a clock because of the `(* CLOCK *)`
 * attribute.
 */
(* whitebox *)
module BLOCK(a, b, o);
	(* CLOCK *)
	input wire a;
	input wire b;
	output wire o;
endmodule

I think the documentation should give a brief explanation on why there is a (* whitebox *) attribute, what is the reason to put this there. Perhaps this could be done on it's own page so that we don't repeat it everywhere (in a separate issue/PR).

(Actually, I myself don't know why is that attribute included.)

Originally posted by @daniellimws in #42 (comment)

[mithro]

The (* whitebox *) attributes means that Yosys should treat the object like a black box but is allow to "look inside" when running queries.

A black box is allowed to be "not fully specified". This means for example the inputs and outputs can be left unconnected and Yosys won't assume it can optimize them away.

[mithro]

We should probably heavily link to the Yosys documentation around these attributes, but I do think we want to make sure to have our own information here.