HAL  v4.5.0-283-g3f42a39fa
The Hardware Analyzer - a comprehensive reverse engineering and manipulation framework for gate-level netlists.
hal::hgl_upgrade Namespace Reference

Functions

bool needs_upgrade (const rapidjson::Document &document)
 
Result< std::vector< std::string > > upgrade_document (rapidjson::Document &document)
 
std::filesystem::path get_backup_path (const std::filesystem::path &file_path)
 
Result< std::filesystem::path > replace_file (const rapidjson::Document &document, const std::filesystem::path &file_path)
 
Result< u32 > get_version (const rapidjson::Document &document)
 

Variables

const u32 TARGET_VERSION = 6
 

Detailed Description

Upgrade of gate library files in HGL format from an older format version to version 6.

What changed in version 6:

  1. The flat LUT configuration {data_identifier, data_category, bit_order} is replaced by an output_pins array, where each entry specifies the output pin, its data_identifier, bit_offset, bit_count, is_ascending and input_pins. The flat configuration made every LUT output pin depend on all input pins and the whole INIT value, so every LUT output pin is migrated to exactly that.
  2. Each cell that carries init data gets a parameters section, so that INIT identifiers can be resolved by name and size: one bit_vector parameter of size 2^n per LUT identifier, of size 1 per flip-flop or latch identifier, and of size bit_size / count per RAM identifier.
  3. Legacy gate type properties without the c_ prefix (buffer, carry, mux, lut) are renamed to their canonical forms.

Function Documentation

◆ get_backup_path()

std::filesystem::path hal::hgl_upgrade::get_backup_path ( const std::filesystem::path &  file_path)

Get the file name the original gate library is kept under after its upgrade.

The .hgl extension is replaced by .json, so that the original file does not get selected as a gate library by accident. If that file exists already, e.g., from an earlier upgrade, a number is added to the name, i.e., <name>.1.json, <name>.2.json, and so on.

Parameters
[in]file_path- The path of the gate library file.
Returns
The path of the backup file.

Definition at line 394 of file upgrade_hgl.cpp.

Referenced by replace_file().

◆ get_version()

Result<u32> hal::hgl_upgrade::get_version ( const rapidjson::Document &  document)

Definition at line 289 of file upgrade_hgl.cpp.

References ERR, and OK.

Referenced by needs_upgrade(), and upgrade_document().

◆ needs_upgrade()

bool hal::hgl_upgrade::needs_upgrade ( const rapidjson::Document &  document)

Check whether a parsed HGL document has to be upgraded.

This is the case for documents below the target version, and for documents at the target version that still contain LUT configurations in the flat format, which earlier upgrades left behind for multi-output LUTs.

Parameters
[in]document- The parsed HGL document.
Returns
true if the document has to be upgraded, false otherwise.

Definition at line 306 of file upgrade_hgl.cpp.

References get_version(), and TARGET_VERSION.

Referenced by upgrade_document().

◆ replace_file()

Result< std::filesystem::path > hal::hgl_upgrade::replace_file ( const rapidjson::Document &  document,
const std::filesystem::path &  file_path 
)

Replace a gate library file by an upgraded document.

The original file is renamed as given by get_backup_path and the document is written under the original name, so that projects referring to the gate library need no changes. If writing fails, the original file is restored.

Parameters
[in]document- The upgraded HGL document.
[in]file_path- The path of the gate library file to replace.
Returns
The path of the backup file on success, an error otherwise.

Definition at line 409 of file upgrade_hgl.cpp.

References ERR, get_backup_path(), OK, and hal::gate_library_manager::remove().

◆ upgrade_document()

Result< std::vector< std::string > > hal::hgl_upgrade::upgrade_document ( rapidjson::Document &  document)

Upgrade a parsed HGL document in place.

A document that does not need an upgrade according to needs_upgrade is left unchanged. The version of the document is only set to the target version if all cells were migrated. If any cell cannot be migrated, an error naming all such cells is returned and the document must be discarded.

Parameters
[in,out]document- The parsed HGL document.
Returns
A list of warnings about cells that were migrated but should be reviewed, or an error if the document cannot be upgraded completely.

Definition at line 327 of file upgrade_hgl.cpp.

References ERR, ERR_APPEND, hal::error, get_version(), needs_upgrade(), OK, and TARGET_VERSION.

Variable Documentation

◆ TARGET_VERSION

const u32 hal::hgl_upgrade::TARGET_VERSION = 6

The format version gate libraries are upgraded to.

Definition at line 59 of file upgrade_hgl.h.

Referenced by needs_upgrade(), and upgrade_document().