CHAPTER FIVE

Handling Black Boxes: Planning Around a Module That Is Not There Yet

By the end of this chapter you will be able to look at a netlist that is missing modules and tell, from attributes alone, which kind of hole each one is; to turn those holes into black boxes that the floorplanner, the shaper and the budgeter all treat as real; to give a black box the one number it cannot do without and the one it must never be given by mistake; to build it a timing model so that paths crossing it stop being unconstrained; to say what its power intent has to declare and why a block's would not do; and to recognise the several ways this can go quietly wrong, none of which produces an error message.

Why this chapter matters in a real project

Design planning almost never starts with a complete netlist. Somebody is late. A licensed block has not arrived, an RTL team is a sprint behind, a derivative design is reusing a module that is still being rewritten, or a wrapper exists as a name in a spreadsheet and nothing else. The schedule, meanwhile, does not move: the floorplan is needed by the same date whether or not every module is in the file you were given.

The choice at that moment is not between planning and waiting. It is between planning with numbers you chose deliberately and planning with numbers the tool made up on your behalf. A black box is the mechanism for the first of those. It lets you say, in a form every downstream command respects, this module will be roughly this big, it will take roughly this long, and it will be powered from here — and then get on with shaping, power planning, pin assignment and budgeting as though the module existed.

What makes this chapter worth reading slowly is the failure mode. Every other chapter in this book so far has had a tool that pushes back: an illegal boundary is rejected, a missing library is reported, a constraint file that does not parse stops the script. A black box with the wrong area is accepted without comment. It shapes, it places, it routes, it budgets, and every report about it looks healthy — because every report is computed from the number you typed. The netlist that would have contradicted you does not exist. You find out eight or ten weeks later, when the real module arrives twenty per cent bigger than the hole reserved for it, and the entire floorplan has to move.

So the discipline this chapter teaches is narrow and specific: know exactly where each number came from, write it down, and check it the day the netlist lands.

Prerequisites

Chapter 1: the area estimate, standard-cell area, macro area, and the internal utilisation that turns placeable area into a block boundary. Chapter 2: units, and the habit of reading a value back out of the tool instead of trusting what you typed. Chapter 3: modes, corners and scenarios; split_constraints and the files it writes; load_block_constraints; and multiply-instantiated blocks. Chapter 4: the die, the core and the core offset, and how each block's boundary area lands in the same core arithmetic.

How to read the numbers and the notation in this chapter

This chapter is arithmetic-heavy, and none of the arithmetic is hard — but it is easy to be tripped up by notation rather than by the engineering. So before anything else, here is every symbol and unit the chapter uses, spelled out. Skip this if it is already familiar; come back to it the moment a number looks odd.

Learning objectives

5.1 The beginner's mental model

Start with a lot that has no building on it

Imagine you are drawing up a site plan for four lots. Three of them have buildings with finished architectural drawings: you know their footprints exactly, so you can place them, run the access roads between them, and work out how much of the site is left. The fourth lot is going to hold a building nobody has designed yet.

You do not stop. You reserve the fourth lot at the area the brief calls for, you note where its doors will be — because the brief fixed those, even though the building did not — and you carry on with the roads, the drains and the electricity supply. When the drawings finally arrive, one of two things happens. Either the building fits the lot you reserved, and nothing changes; or it does not, and you find out that the roads, the drains and the supply were all laid out around the wrong number.

That is a black box, almost exactly, and the whole vocabulary transfers. The reserved area of the lot becomes an attribute called target_boundary_area. How densely the lot may be built on becomes target_utilization. The doors in known places become the module's port interface, which exists in the instantiation even when the module does not. How long a delivery takes to cross the lot becomes a command called create_blackbox_delay, and how long a lorry must wait at the door before it may be unloaded becomes create_blackbox_constraint. Which mains feeds the lot becomes the receiver supply in the power intent. Figure 5.2 lays all seven of those pairs out side by side; do not try to memorise them from this paragraph.

Now the engineering model

A black box is a module that has no netlist, has only a partial netlist, or is not bound to a higher-level module. That definition has three clauses and they are genuinely different situations, which is why Section 5.2.1 spends a page separating them.

Two facts about black boxes bound the whole chapter. The first is a restriction: only physical hierarchies can be black boxes. A logical hierarchy cell must become a physical block before it can be one, and create_blackbox does that conversion for you rather than complaining. The second is the reason the mechanism exists at all: black boxes are supported for both physical and timing purposes, and at all stages of design planning. This is not a stub that lets a script get past a missing file. It is a first-class object that the following operations all handle:

Read that list as a promise and as a warning. The promise is that you lose almost nothing by planning around a missing module. The warning is that all ten of those operations will use your area and your delays without ever being in a position to question them.

The four-step flow, before any detail

The whole chapter is four steps, and they are worth holding in mind while the detail arrives:

Steps 1 and 2 are physical: they give the module a size and a shape so the floorplan can be finished. Steps 3 and 4 are temporal: they give it delays so the timing can be closed. The two halves are independent — a black box with an area and no timing model is perfectly legal, and quite common in the first week — but the second half is the one people skip, and Section 5.4.4 shows exactly what skipping it costs.

Do not confuse these

5.2 The concepts, from first principles

5.2.1 Identifying candidates: the one attribute and the ten

Start with the easy case. If a module has already been made a black box, you can find it by retrieving cells whose black_box attribute is set to true. That is the question “what is already a black box?”, and it is the question you will ask most often once a project is under way.

The harder and more interesting question is the one you ask on the first day: which of the modules in this netlist ought to become black boxes, and what kind of hole is each one? Black boxes classify into five kinds — missing or unbound, empty, partial, feedthrough, and tie-off — and the classification is made by reading attributes on the block. Ten attributes are documented for the purpose. Five of them do almost all the work; the other five matter when a module contains something unusual.

The commands are the ordinary ones. There is no special query for this:

icc2_shell> get_attribute -objects $cells -name is_unbound
true
icc2_shell> get_attribute -objects $cells -name hierarchy_std_cell_count
0
icc2_shell> get_attribute -objects $cells -name hierarchy_has_shadow_netlist
false

That is a missing module: unbound, no cells, no connectivity. Change the first answer to false and leave the other two, and you have an empty module — a module statement with nothing inside it. Both are holes; only one of them was ever written down.

5.2.2 The five patterns, one at a time

The distinguishing signatures are worth learning as patterns rather than as facts to be looked up, because you will read them off a report far more often than you will type them.

Missing modules have no module definition — no module statement in the Verilog netlist — and report is_unbound true, a standard-cell count of zero, and no shadow netlist. This is the cleanest case and the most common one at the start of a project: the file simply does not contain the module the top level instantiates.

Empty modules have a module definition but no content. They report is_unbound false, standard-cell and hard-macro counts of zero, and no shadow netlist. Somebody wrote the interface and stopped, which is exactly what a well-organised RTL team does when a block is scheduled for next month.

Partial modules contain an incomplete set of cells. Their hierarchy counts are above zero — you might see a hard-macro count of a few and a standard-cell count in the hundreds or hundreds of thousands — with a shadow netlist present, hierarchy_has_shadow_netlist_only false, and the pad, physical-only and switch cell counts all zero on an ordinary module. This is the interesting case, and Section 5.2.6 is largely about it.

Feedthrough modules contain net connections between input and output ports and no cells at all. Zero standard cells, zero hard macros, a shadow netlist present, and hierarchy_has_shadow_netlist_only true. Wrapper modules that exist only to carry signals across a hierarchy boundary look exactly like this, and they are common in real netlists.

Tie-off modules have only output ports, tied to a logical value. Zero standard cells, zero hard macros, and no shadow netlist at all — neither the plain form nor the _only form. A module that reports constants is not carrying anything through, so there is nothing for a shadow netlist to hold.

5.2.3 Nimbus-8, six weeks earlier

Everything in this chapter happens on the design this book has been carrying, at a moment earlier than any previous chapter. The netlist Chapter 3 split and Chapter 4 built a floorplan from was not the first netlist. Six weeks before it, at revision A, two of Nimbus-8's five modules were not there to be read.

The image-signal processor, u_isp, was missing outright: the top level instantiated a module called ISP and the netlist contained no such module. The SoC peripheral block, u_soc_periph, was partial: its module statement was there, its four memories were there, and about forty per cent of its standard cells were there. The CPU cluster, the two NPU cores and the DDR PHY were all complete.

And the floorplan of Chapter 4 was built anyway — the same die, the same core, the same offset, the same rows and the same tracks. Figure 5.4 shows how.

That last number deserves a moment. The two black boxes together account for 2.0553 mm² of boundary area, against 8.1486 mm² for all six blocks and macros put together, so 25.22 per cent of the block area on the Chapter 4 floorplan was, at revision A, a pair of numbers somebody chose. As a fraction of the whole core it is 20.07 per cent. Neither figure is unusual. On a derivative design or a first-of-family SoC it is routinely higher.

5.2.4 What create_blackbox actually does

Once you have decided which modules to treat as black boxes, create_blackbox creates the black box physical hierarchy for the cell and updates the cell's reference. Both halves of that sentence matter, and the second half has a reach that surprises people.

When the cell has an unresolved reference, the command creates a new, empty design with the same port interface as the unresolved reference. That is the crucial mechanism and it is worth being explicit about: the ports come from the instantiation, not from the module. A Verilog instantiation names every port it connects, so even when the module body is entirely absent the interface is fully known — which is why a black box can have a meaningful timing model and a meaningful pin assignment. The doors were in the brief.

When the cell is a logical hierarchy cell instead, the command converts it into a physical block and creates a new design holding the content of the original cell's logical hierarchy. Either way, the design that comes out is a black-box-typed design.

Effect two, spelled out because it matters: the reference of the cell you named and of all other cells with the same reference is changed to the new design. So are any other cells in designs linked to this design as child designs, and any designs linked with the same unresolved reference. One command, and every instance of that module in the whole linked hierarchy now points at the black box.

This is almost always what you want — a module is either late or it is not, and it is late in every instance of itself — but it means the command is not local. If you were expecting to convert one of two instances and leave the other alone, that is not what black boxes do, and Section 5.2.8 explains why the answer is not to try.

5.2.5 Finding them again

Two questions, two commands, and they are genuinely different. To find every black box in the design, or to check whether a specific module is one, examine the design_type attribute of the module:

icc2_shell> get_cells -hierarchical -filter ref_block.design_type==black_box
{u_isp u_soc_periph}

icc2_shell> get_attribute [get_cells u_isp] design_type
black_box

The filter expression design_type==black_box is the one to remember for searching, because it works whatever kind of hole the module started as. Two related attributes exist for cases the filter does not cover: is_empty queries empty hierarchies, in the same way is_unbound queries unbound instances; and is_logical_black_box is the attribute for macro-style black boxes, which the next paragraph explains.

create_blackbox -type takes physical or macro, and the default is physical. A physical black box is a physical block and follows the physical-partition design planning flow — this is the one this chapter is about, and the one every other chapter in this book assumes. A logical or macro type black box is created for unbound instances and empty hierarchies, and after creation it is treated as any other macro in the design and is placed by the macro placer. That is a different and simpler life: no shaping, no pin assignment, no budgeting, just a rectangle the macro placer puts somewhere sensible.

5.2.6 The area, and the utilisation

A black box needs a size. There are two ways to give it one, and choosing between them is the single most consequential decision in the chapter.

The first is create_blackbox -target_boundary_area, which specifies the target area of the black box design. It is mutually exclusive with -boundary, which specifies an explicit boundary instead — use that when you already know the shape, not just the size. To modify an area you have already set, set the target_boundary_area attribute directly on the black box cell:

icc2_shell> create_blackbox -target_boundary_area 1716667 u_isp

icc2_shell> set_attribute -objects [get_cells u_isp] \
   -name target_boundary_area -value 1750000
{u_isp}

The second is the target_utilization attribute, and it is specifically for black boxes created from a partial Verilog netlist. It takes a ratio:

icc2_shell> set_attribute -objects [get_cells u_soc_periph] \
   -name target_utilization -value 0.75
{u_soc_periph}

Both attributes are honoured by the shape_blocks command during block shaping. That is the sentence that makes them matter: shaping is a later chapter's subject, but shaping is where these numbers become geometry, and shaping will not ask you whether you meant them.

Work it through on Nimbus-8's peripheral block. Chapter 1 estimated it at 0.36 M standard cells and four SRAM macros. At 0.350 µm² per cell and 0.0320 mm² per macro, that is 0.1260 mm² of cells and 0.1280 mm² of macros: 0.2540 mm² of placeable area, which at the internal utilisation of 0.75 this book has used since Chapter 1 needs a boundary of

0.2540 ÷ 0.75 = 0.338667 mm² = 338,667 µm²

At revision A the netlist held four macros and 144,000 standard cells — forty per cent of them. So what the tool could count was 144,000 × 0.350 µm² = 0.0504 mm² of cells plus the same 0.1280 mm² of macros: 0.1784 mm². Apply a target utilisation of 0.75 to that and the block comes out at

0.1784 ÷ 0.75 = 0.237867 mm² = 237,867 µm²

which is 70.24 per cent of the size it needs. The deficit is 100,800 µm², or 29.76 per cent, and nothing anywhere reports it. The block shapes, the macros place, the cells place comfortably — of course they do, there are only forty per cent of them — and the floorplan looks better than the real one will.

There is an identity here worth carrying away, because it makes the error predictable rather than mysterious. The block comes out short by exactly the fraction of the placeable area that has not yet arrived:

0.1784 ÷ 0.2540 = 0.7024        237,867 ÷ 338,667 = 0.7024

Those are the same number, because the 0.75 divides out of both sides. The utilisation you chose has nothing to do with the size of the error. Choosing 0.65 or 0.85 instead would have produced a differently-sized block that was still 70.24 per cent of the right answer.

Notice also that the shortfall is not forty per cent, even though forty per cent of the cells arrived. The four memories were all there, and they are half the block's placeable area. Macros usually land in a netlist early — they are instantiated wrappers, not synthesised logic — which softens the ratio and makes the error harder to spot by eye. On a block with no macros at all the arithmetic is brutally direct: the boundary comes out at exactly the visible-cell fraction of the size it needs.

5.2.7 Where the number lands

A black box's boundary area is not a private matter between you and that block. It goes into the same core arithmetic Chapter 4 set up, alongside every counted area, and it competes for the same space.

Nimbus-8's core is a square 3.20 mm on each side, so its area is 3.20 × 3.20 = 10.24 mm². The four modules whose netlists were complete at revision A occupy 3.1720 mm² for the CPU cluster, 1.18862 mm² for each of the two NPU cores, and 0.5440 mm² for the DDR PHY — 6.0932 mm² together. Add the two typed numbers and the block boundary total is 8.1486 mm², leaving 2.0914 mm² of channel, or 20.42 per cent of the core.

Now change one number and watch what happens elsewhere. Suppose the ISP had been reserved at 1.90 mm² instead of 1.716667 — a difference of 0.183 mm², about eleven per cent of the block, the kind of margin somebody adds “to be safe”. The block boundary total becomes 8.3319 mm² and the channel drops to 1.9081 mm², 18.63 per cent of the core. The ISP did not get worse; the space between every other block did, by 8.8 per cent of the channel budget, and the first symptom will be top-level congestion in a channel three blocks away.

5.2.8 Multiply-instantiated black boxes

Chapter 3 established that Nimbus-8's two NPU cores are the same module, NPU_CORE, instantiated twice, and that a multiply-instantiated block gets one set of constraints rather than one per instance. Black boxes work the same way, and the mechanism is the one Section 5.2.4 described: create_blackbox retargets every cell with the same reference, so a multiply-instantiated module becomes a multiply-instantiated black box in a single command. Multiply-instantiated black box support is the first item on the list of design planning operations black boxes handle.

The consequence is worth stating plainly, because it is where people try to be clever. There is one black box design, so there is one target_boundary_area, one target_utilization, and one timing model, shared by every instance. If the two instances need different areas, they are not the same module and should not have been written as one. If they need the same area but different timing — because one sits next to the memory controller and the other does not — that difference belongs at the top level, in the budgets and the boundary constraints, not in the black box.

5.3 Inputs, outputs and readiness

Black boxes sit later in a session than the previous two chapters' subjects, and they need less than you might expect. You do not need a complete netlist — that is the point — and you do not need a floorplan, although in practice you will already have one, because the sequence on a real project is: read what netlist you have, create the black boxes, then initialise the floorplan with everything sized.

Preflight checklist

5.4 The guided tool walkthrough

5.4.1 create_blackbox — the module becomes a thing

Purpose. Create a black box design and update the reference for the specified cell. On a cell with an unresolved reference it creates a new empty design with the same port interface; on a logical hierarchy cell it converts the cell into a physical block and creates a design holding that hierarchy's content. Either way the new design is a black-box-typed design.

Syntax in plain English. One positional argument — the cell — and five options, which answer: what shall the design be called, what kind of black box, which library, and how big.

# The ISP: missing entirely, so give it an area outright.
icc2_shell> create_blackbox -target_boundary_area 1716667 u_isp

# The SoC peripheral: partial, so the area from the whole estimate ...
icc2_shell> create_blackbox -target_boundary_area 338667 u_soc_periph

# ... and then the density for the part of it that has arrived.
icc2_shell> set_attribute -objects [get_cells u_soc_periph] \
   -name target_utilization -value 0.75

# A module whose shape is already agreed with the block owner.
icc2_shell> create_blackbox -boundary { {0 0} {1310 0} {1310 1310} \
   {0 1310} } u_isp

# A small IP wrapper you will never open: let the macro placer have it.
icc2_shell> create_blackbox -type macro -target_boundary_area 42000 \
   u_otp_fuse

# A design created in a named reference library, under a chosen name.
icc2_shell> create_blackbox -library nimbus8.dlib -new_name ISP_BB \
   -target_boundary_area 1716667 u_isp

Expected result. A new black-box-typed design; the reference of the named cell and of every other cell with that reference changed to it; and, on a logical hierarchy cell, that cell committed to a physical block.

Verification. Do not rely on the command's return value. Read the attribute instead, which also tells you the area landed:

icc2_shell> get_attribute [get_cells u_isp] design_type
black_box
icc2_shell> get_attribute -objects [get_cells u_isp] \
   -name target_boundary_area
1716667
icc2_shell> get_cells -hierarchical -filter ref_block.design_type==black_box
{u_isp u_soc_periph}

Three answers, and the third is the one that catches a mistake: if that list is longer than you expected, the command retargeted a reference you had not thought about.

Common mistakes. Supplying -target_boundary_area and -boundary together. Giving the area in the wrong unit, which produces a black box a million times too big or too small and no complaint at all. Running the command on a feedthrough wrapper. Assuming -new_name will rename a design created from a bound logical hierarchy cell, where it is ignored. Expecting one instance of a multiply-instantiated module to be converted and the others left alone.

Prerequisites. An open design containing the cell, and — for -library — a library that is a reference library of the one holding the current design. Empty, partial and missing modules can be converted either after reading the netlist or after committing the blocks.

Finding the rest. man create_blackbox, and man get_cells for the filter expression syntax.

5.4.2 The nine commands that describe timing

A black box contains no timing information by default, and the consequence is stark: any path that begins or ends at a black box is unconstrained. Not pessimistic, not approximate — absent. It does not appear in a timing report, it contributes nothing to a budget, and it cannot fail, because nothing is checking it.

The remedy is a timing model, and building one means specifying the model ports, the setup and hold constraints on the inputs, the clock-to-output path delays, and the input-to-output path delays. You can also specify the loads on input ports and the drive strength of output ports. Nine commands do this. They fall into three groups, and the groups have to happen in order.

Group one: say what the ports are. set_blackbox_clock_port takes a list of ports and nothing else. It has to come first, because the network-delay, constraint and delay commands all require their clock ports to have been identified this way already. Alongside it, the electrical description of the edges: create_blackbox_load_type names a load as a buffer or inverter library cell, set_blackbox_port_load attaches it to input ports, create_blackbox_drive_type names a driver the same way, and set_blackbox_port_drive attaches it to output ports.

Group two: say what the numbers are. create_blackbox_clock_network_delay gives the delay from a clock input port into the block. create_blackbox_generated_clock declares a clock the module derives for itself. create_blackbox_constraint gives setup and hold requirements at input ports, referred to a clock edge. create_blackbox_delay gives path delays: clock to output, or input to output.

Group three: commit. One command, Section 5.4.3.

That last row is how the generated clock stops being write-only. get_blackbox_generated_clocks returns the object, and get_attribute on it reads back master_clock, master_source, source_pin, period and the maximum and minimum network delays — which is the only way to confirm that a divided clock came out at the period you expected rather than the one you meant to type.

5.4.3 commit_blackbox_timing, and getting the model back out

Purpose. Save the black box timing information created by the commands above, by creating or updating the abstract view of the current block to include it. Until this runs, the model is inert.

Syntax in plain English. No arguments are needed. One option exists.

Expected result. An abstract view for the current block containing the black box timing data. Black box timing information is stored in the design view, and when an abstract is created from a black box, specially marked cells, nets and connections are created on the fly within the abstract view. That mechanism is what enables timing on an empty or partial netlist, and it is also why newly created feedthroughs can be timed immediately without the models being rebuilt.

Verification. Read has_timing_model on the block, and then time something: a path that was absent from the report before the commit should be in it afterwards, with your numbers on it. If you want the model itself in a readable form, write_blackbox_timing_script writes out the commands that would rebuild it — which is also the best possible review artefact, because a reviewer can read the delays without opening the tool.

Common mistakes. Building the model and never committing it, so that every path across the block stays unconstrained and the timing report looks suspiciously short. Committing over a placement abstract somebody needed, instead of passing -convert_placement_abstract false. Expecting remove_blackbox_timing to undo one command: it removes the model as a whole, which is why the script that built it belongs in revision control.

Prerequisites. Black box timing must have been defined on the current block. For write_blackbox_timing_script, the design must already have black box timing defined.

Finding the rest. man commit_blackbox_timing, whose See Also list is the fastest route to the other eight commands.

5.4.4 What the model buys, and who is allowed to change it

Take one path on Nimbus-8 at revision A: out of the ISP black box on yuv_out, across the top level, into the SoC peripheral black box on cfg_in. Both ends are black boxes. Both have models. The clock is clk_isp at 800 MHz.

The arithmetic is Chapter 3's, with two black box numbers added. A period of 1,250 ps, less Nimbus-8's 45 ps of clock uncertainty and 30 ps setup requirement, gives 1,175 ps of usable period. The ISP's model declares 410 ps from clock to output; the peripheral's declares 260 ps of setup at its input. What is left for the top-level route is

1,175 − 410 − 260 = 505 ps

and the reason that number matters is not its value. It is that there is a number. Before the models existed, this path did not appear in any report; after them, it has a budget, and if the route turns out to need more than 505 ps somebody will be told.

Which raises the question of who may change it. When generating timing budgets, the tool maintains the timing you specified with the black box timing commands. That is the default, and it is a strong one: your 410 ps is a fact the budgeter works around. To allow the budgeter to adjust the black box timing budgets instead, set the application option:

icc2_shell> set_app_options -name plan.budget.bbt_fixed_delay -value false
plan.budget.bbt_fixed_delay false

Suppose global planning later reports that the route this path needs cannot be done in less than 620 ps. With fixed delays, there is nowhere to find the missing 115 ps and the path fails; the black box has an effective veto over a route it knows nothing about. With the option set false, the budgeter may tighten the ISP's model to 410 − 115 = 295 ps, hand that figure to the ISP team as their constraint, and close the path: 1,175 − 295 − 260 = 620 ps.

5.4.5 The power intent

The UPF constraints for black boxes are specified differently from those for normal blocks, and the reason is structural: black boxes act as leaf cells. A block's UPF describes what is inside the block. A black box has no inside, so its UPF describes its context, in terms of the top level — and it must also define the receiver supply information for the block's input ports.

Three consequences follow, and each one is a thing to do or not do.

Do not run split_constraints for it. You would not typically run split_constraints to generate UPF constraints for black boxes or empty modules. Chapter 3 built the whole splitting flow, and this is the one case it is not for: splitting derives a block's constraints from the top-level design's view of it, which requires the block to have content the derivation can follow.

Know what happens when nothing is stated. If a net does not have a real driver, the primary supply for the domain is used. That is a sensible fallback and it is also silent. A black box input port whose receiver supply nobody declared will not produce an error; it will produce a port powered from the domain primary, which may well be wrong and will certainly not be flagged.

Use the override, because here you are allowed to. Black boxes are the only hierarchical cells where set_port_attributes or set_related_supply_net can be used to override the supply information. On any other hierarchical cell that override is not available; on a black box it is the mechanism.

The priority order is worth having in front of you, because it is longer for a black box than for a hard macro. When the tool considers power intent logic insertion outside a hard macro, the receiver supply of an input port is determined in this order: a set_port_attributes -receiver_supply at the HighConn side of the port; then a set_related_supply_net at the HighConn side; then any related_power_port information for the pin from the Liberty file. Three steps, and the third comes from a library.

Outside a black box cell there is no library, so the order has five steps: set_port_attributes -receiver_supply at the HighConn side; set_related_supply_net at the HighConn side; set_port_attributes -receiver_supply at the LowConn side; set_related_supply_net at the LowConn side; and finally the primary supply of the power domain. The two extra steps exist because a black box has an inside you may write constraints for even though it has no content, and the last step is the silent default above.

Rather than write the file by hand, extract it. The UPF for black boxes can be written specifically for the black box or extracted from an existing design with save_upf -for_empty_blackbox:

# Make the black box, move into it, read its intent, resolve, extract.
icc2_shell> create_blackbox I_ISP
icc2_shell> current_design ISP
icc2_shell> load_upf inputs/ISP.upf
icc2_shell> commit_upf
icc2_shell> save_upf -for_empty_blackbox ./split/ISP/top.upf

Note the destination. ./split/ISP/top.upf is the same directory layout Chapter 3 established, and top.upf is the same file name split_constraints writes for an ordinary block. The block owner's flow does not change; only the way the file was produced does. -for_empty_blackbox cannot be combined with -format, -force_reference, -force_no_reference, -include or -exclude.

5.5 The worked example: Nimbus-8 at revision A

One continuous example, from the attribute sweep to a committed model. Every number in it has appeared already; this section is where they are produced rather than quoted.

Step 1 — find out what you are holding

# What did not resolve?
icc2_shell> set cands [get_cells -hierarchical -filter is_hierarchical==true]
icc2_shell> foreach_in_collection c $cands {
   set n [get_object_name $c]
   puts [format "%-16s unbound %-6s std %-8s macro %-4s shadow %-6s only %s" $n \
      [get_attribute -objects $c -name is_unbound] \
      [get_attribute -objects $c -name hierarchy_std_cell_count] \
      [get_attribute -objects $c -name hierarchy_hard_macro_count] \
      [get_attribute -objects $c -name hierarchy_has_shadow_netlist] \
      [get_attribute -objects $c -name hierarchy_has_shadow_netlist_only]]
}

The sweep returns six hierarchical cells. Four of them report cell counts in the millions and need nothing from this chapter. The other two are the subject:

Three readings, three different actions. u_isp and u_soc_periph become black boxes. u_cfg_tie does not: it holds configuration straps at constants, it has no cells, and reserving area for it would take space from every other block for nothing. It is in the table only because the sweep found it, and because the first instinct on seeing a zero cell count is to reach for create_blackbox.

Step 2 — work out the two numbers, on paper, before typing anything

Both come from Chapter 1's estimate and Chapter 1's internal utilisation of 0.75. Neither comes from the netlist, and for the peripheral block that is a deliberate refusal to use newer information.

# The ISP. 1.85 M cells at 0.350 um2, plus 20 SRAM at 0.0320 mm2.
1.85e6 x 0.350 um2 = 647,500 um2 = 0.6475 mm2
20 x 0.0320 mm2                  = 0.6400 mm2
placeable                        = 1.2875 mm2
boundary = 1.2875 / 0.75         = 1.716667 mm2 = 1,716,667 um2

# The SoC peripheral. 0.36 M cells, 4 SRAM. The WHOLE module.
0.36e6 x 0.350 um2 = 126,000 um2 = 0.1260 mm2
4 x 0.0320 mm2                   = 0.1280 mm2
placeable                        = 0.2540 mm2
boundary = 0.2540 / 0.75         = 0.338667 mm2 =   338,667 um2

In words, because a number you can say out loud is a number you can be challenged on: the ISP is 0.6475 mm² of standard cells and 0.6400 mm² of memories, so 1.2875 mm² of placeable area, so a boundary of 1.716667 mm². The peripheral is 0.1260 mm² of cells and 0.1280 mm² of memories, so 0.2540 mm² placeable, so a boundary of 0.338667 mm².

Check each one backwards before it goes anywhere: 1.716667 × 0.75 = 1.2875, and 0.338667 × 0.75 = 0.2540. Both recover the placeable areas they came from, so neither is a typing error.

And check the third number, the one nobody asks for. The two boundary areas together are 2.055334 mm². Chapter 4's core is 10.24 mm², the four complete blocks and the DDR PHY occupy 6.0932 mm², so the block boundary total is 8.1486 mm² and the channel left is 2.0914 mm² — 20.42 per cent of the core. That is comfortable. Had the ISP been reserved at 1.90 mm² “for safety”, the channel would have dropped to 1.9081 mm², 18.63 per cent, and the safety margin would have been paid for out of somebody else's routing space.

Step 3 — create the black boxes

# Missing: an area, and nothing else to say.
icc2_shell> create_blackbox -target_boundary_area 1716667 u_isp

# Partial: the same kind of area, from the whole estimate ...
icc2_shell> create_blackbox -target_boundary_area 338667 u_soc_periph

# ... and then a density for the 40 per cent that is visible.
icc2_shell> set_attribute -objects [get_cells u_soc_periph] \
   -name target_utilization -value 0.75

# Read all three numbers back. Never quote what you typed.
icc2_shell> get_attribute -objects [get_cells u_isp] \
   -name target_boundary_area
1716667
icc2_shell> get_cells -hierarchical \
   -filter ref_block.design_type==black_box
{u_isp u_soc_periph}
icc2_shell> report_app_options plan.budget.bbt_fixed_delay

The second answer is the audit. Two cells, which is two more than before and no more than intended — if u_cfg_tie had appeared in that list, somebody had reached for the command too quickly.

Step 4 — give the ISP a timing model

Nimbus-8's ISP runs on clk_isp at 800 MHz, exactly half the CPU frequency established in Chapter 1, so the period is 1,250 ps against clk_cpu's 625 ps. The design's time unit is 1 ps, which is why every value below is a whole number of hundreds rather than a decimal fraction.

# The mode, corner and scenario grid from Chapter 3, and the clock.
icc2_shell> create_mode func
icc2_shell> create_corner ss_125c
icc2_shell> create_scenario -mode func -corner ss_125c
icc2_shell> create_clock -name clk_isp -period 1250 [get_ports clk_isp_in]

# --- group one: what the ports are, electrically -------------------
icc2_shell> set_blackbox_clock_port [get_ports clk_isp_in]

icc2_shell> create_blackbox_load_type \
   -lib_cell [get_lib_cells stdcell/BUFX8] lt_isp
icc2_shell> create_blackbox_drive_type \
   -lib_cell [get_lib_cells stdcell/BUFX16] \
   -input_transition_rise 12 -input_transition_fall 12 dt_isp

icc2_shell> set_blackbox_port_load -type lt_isp -factor 4 \
   [get_ports pix_in*]
icc2_shell> set_blackbox_port_drive -type dt_isp \
   [get_ports {yuv_out* frame_done px_valid_out}]

# --- group two: the numbers ----------------------------------------
# The clock takes 380 ps to spread inside the block.
icc2_shell> create_blackbox_clock_network_delay -value 380 clk_isp_in

# Setup and hold at the pixel inputs. Two commands, both explicit.
icc2_shell> create_blackbox_constraint -setup -edge rise \
   -from clk_isp_in -to [get_ports pix_in*] -value 260
icc2_shell> create_blackbox_constraint -hold -edge rise \
   -from clk_isp_in -to [get_ports pix_in*] -value 90

# The configuration write is a fraction of the period, not a delay:
# 0.24 x 1250 = 300 ps, and it tracks the clock if the clock changes.
icc2_shell> create_blackbox_constraint -setup -edge rise \
   -from clk_isp_in -to cfg_wr -clock clk_isp -value 0.24

# Clock to output. Late corner first, then the early value.
icc2_shell> create_blackbox_delay -max -from clk_isp_in -to yuv_out \
   -value 410
icc2_shell> create_blackbox_delay -min -from clk_isp_in -to yuv_out \
   -value 180
icc2_shell> create_blackbox_delay -max -rise_from clk_isp_in \
   -to frame_done -value 340

# A combinational bypass, different in each direction.
icc2_shell> create_blackbox_delay -max -rise_from bypass_in \
   -rise_to bypass_out -value 220
icc2_shell> create_blackbox_delay -max -fall_from bypass_in \
   -fall_to bypass_out -value 240

# A clock the ISP makes for itself: 2 x 1250 = 2500 ps, 400 MHz.
icc2_shell> create_blackbox_generated_clock -name clk_px -divide_by 2 \
   -source clk_isp_in -master_clock clk_isp
icc2_shell> create_blackbox_delay -max -from clk_px \
   -to px_valid_out -value 300

# --- group three: make it real -------------------------------------
icc2_shell> commit_blackbox_timing

Two habits in that script are worth naming. Every create_blackbox_delay carries -max or -min and every create_blackbox_constraint carries -setup or -hold, even though both default to applying to everything — because a setup number silently doubling as a hold number is a fictional constraint the budgeter will honour. And no command carries -modes or -corners, which means all of these values apply to every mode and every corner in the design. On a one-corner script that is exactly right. On the full Chapter 3 grid of two modes and two corners it is not: the ISP at ff_m40c is not a 410 ps block. A second line fixes it —

icc2_shell> create_blackbox_delay -max -corners ff_m40c \
   -from clk_isp_in -to yuv_out -value 240

— and the general rule is that a model with one number per path is a first draft, not a deliverable.

Step 5 — check that it landed, and read the budget off it

# Did the commit reach the abstract?
icc2_shell> get_attribute -objects [get_cells u_isp] \
   -name has_timing_model
# Write the model out, and read it as a reviewer would.
icc2_shell> write_blackbox_timing_script isp_bbt_revA.tcl
# And for a signoff tool that wants QTM instead:
icc2_shell> write_blackbox_timing_script -qtm_format \
   -qtm_directory qtm_isp_revA

Now the arithmetic of Section 5.4.4, done on the real numbers. The path leaves the ISP on yuv_out and arrives at the peripheral's cfg_in, which is one of the ports with no block-internal connection in the partial netlist — which is why a black box constraint on it is legal at all.

Step 6 — the power intent, and the abstract

# Extract the black box UPF rather than writing it.
icc2_shell> create_blackbox I_ISP
icc2_shell> current_design ISP
icc2_shell> load_upf inputs/ISP.upf
icc2_shell> commit_upf
icc2_shell> save_upf -for_empty_blackbox ./split/ISP/top.upf

# State the receiver supply, because the fallback is silent.
icc2_shell> set_port_attributes -ports [get_ports pix_in*] \
   -receiver_supply VDD_ISP

# Create abstracts, so the multivoltage check has objects to check.
icc2_shell> create_abstract -blocks {ISP SOC_PERIPH}
icc2_shell> check_mv_design -interface_only

That last pair is the step teams skip, and Section 5.4.5 explained the consequence: without abstracts there are no black box timing cells, so there are no drivers and receivers on the nets, so check_mv_design runs and finds nothing. A clean report from a check that had nothing to look at is the most dangerous artefact in this chapter.

Engineering judgement — the three calls that were not the tool's to make

Refusing the newer number. The peripheral's area came from the first-week estimate rather than from the netlist on the disk. That is the right call, and it is uncomfortable, because the netlist is real and the estimate is not. The test to apply is not “which number is more accurate?” but “which number describes the finished module?” — and only one of them was trying to.

Not black-boxing the tie-off. u_cfg_tie matched a documented black box pattern and was left alone anyway, because the pattern tells you what a module contains, not what to do about it. Reserving area for a module with no cells is a cost with no benefit.

Leaving plan.budget.bbt_fixed_delay at its default. The ISP's 410 ps came from the previous generation of the same block, measured, not guessed. A measured number should not be quietly improved by a budgeter, so the default stands. Had the number been an estimate, the honest setting would have been false — and the tightened figure would have gone to the ISP team as a question.

5.6 Failure modes and how to recognise them

Ten ways this goes wrong. Only two of them produce a message, which is why the “how you notice” column is the important one.

5.7 Hands-on mini lab

Goal. Take the design Eridanus-6 from a netlist two modules short to a floorplan that can be shaped, timed and multivoltage-checked — and quantify, twice, what the wrong sizing choice would have cost.

Given.

Tasks.

Expected observations.

5.8 Interview preparation

Sixteen questions, grouped by level. Answer each one out loud before reading the model answer. Black boxes come up often in interviews for a specific reason: the topic is a fast test of whether a candidate understands that the tool will do exactly what it is told and check none of it.

Beginner

Intermediate

Senior and tradeoff

5.9 Chapter close

Sign-off checklist

Flashcards

Compact glossary

Five-question self-check

1. Two modules both report zero standard cells and zero hard macros. One has is_unbound true and the other false, and neither has a shadow netlist. What kind is each, and does the difference change what you do?
2. A module is estimated at 1.20 M standard cells at 0.300 µm² each, with no macros, and you intend an internal utilisation of 0.80. What target boundary area do you set, in mm² and in µm²?
3. Only 40 % of that module's cells are in the netlist, and instead of the area you set target_utilization 0.80. What size does the block come out at, and what fraction of the right answer is that?
4. A clock has a period of 1,600 ps, with 40 ps of uncertainty and a 20 ps setup requirement. A black box declares 500 ps clock-to-output and the receiving block needs 240 ps of setup. How much is left for the top-level route?
5. The design's time unit is 1 ps and you type create_blackbox_delay ... -value 0.6, meaning 600 ps. What have you actually declared, by what factor is it wrong, and what will the timing report look like?

Answers.

1. is_unbound true with zero cells and no shadow netlist is a missing module — no module statement in the netlist. is_unbound false with the same counts is an empty module — a definition with nothing in it. The difference does not change what you do: both are genuine holes that need an area reserved, and both take a target_boundary_area from the estimate. It changes what you say to whom, which is a real distinction on a project: an empty module means somebody has written the interface and is working, while a missing one means the module is not on anybody's desk yet.

2. 1.20 M × 0.300 µm² = 360,000 µm² = 0.360 mm² of placeable area, and with no macros that is all of it. Divided by 0.80: 0.450 mm² = 450,000 µm². Check backwards: 0.450 × 0.80 = 0.360.

3. Visible content is 0.40 × 1.20 M = 480,000 cells × 0.300 µm² = 144,000 µm² = 0.144 mm². At 0.80 that gives 0.144 ÷ 0.80 = 0.180 mm² = 180,000 µm², which is 180,000 ÷ 450,000 = exactly 40 per cent of the right answer. With no macros in the block the arithmetic is unforgiving: the boundary comes out at precisely the visible-cell fraction of the size it needs, because the utilisation divides out of both sides. A block with memories in it — like Nimbus-8's peripheral — comes out higher than the cell fraction and is therefore harder to spot by eye.

4. Usable period 1600 − 40 − 20 = 1,540 ps. Less the two declared numbers: 1540 − 500 − 240 = 800 ps. Check by adding back: 800 + 500 + 240 = 1540, and 1540 + 40 + 20 = 1600.

5. You have declared 0.6 ps, because the value is a bare float in the design's time unit and that unit is 1 ps. It is wrong by a factor of 1,000, in the direction that makes the black box a thousand times faster than any real logic. The timing report will look excellent: enormous positive slack on every path through the block, no violations, nothing to investigate. That is the entire difficulty with this chapter — the report is not wrong about the model, it is right about a model that describes a module which could not exist. Catch it by reading the committed model back with write_blackbox_timing_script and asking whether the magnitudes are physically possible.

Where the next chapter goes, and why

Every module in the design now has a size, whether it came from a netlist or from an estimate, and the ones that had no timing now have models. The floorplan is complete in the sense that matters: a boundary, a core, rows, tracks, and blocks that all occupy known area.

What is still missing is everything at the edge. The core offset that Chapter 4 reserved is empty — no I/O cells, no power or ground pads, no corner cells, no filler. On a flip-chip design there are no bumps, and nothing connects the pads to them. Chapter 6 fills that strip: validating that the libraries contain what an I/O ring needs, creating I/O rings or guides, building arrays and rows of bump cells, placing bumps in predetermined locations, constraining power and signal I/O placement, assigning pads to bumps both automatically and by matching types, and routing the redistribution layer that joins them.

The link back to this chapter is the same discipline in a different place. An I/O ring is built from library cells whose heights and widths are facts, and from a bump pitch that is a manufacturing constraint — numbers you read rather than choose, as Chapter 4's rows and tracks were. But the assignment of pads to bumps is a choice, made early, that everything downstream is planned around, and it has the same property black box areas have: nothing in the flow will tell you it was the wrong one.