HAL  v4.5.0-283-g3f42a39fa
The Hardware Analyzer - a comprehensive reverse engineering and manipulation framework for gate-level netlists.
upgrade_hgl.cpp
Go to the documentation of this file.
2 
3 #include "rapidjson/filewritestream.h"
4 #include "rapidjson/prettywriter.h"
5 
6 #include <algorithm>
7 #include <cstdio>
8 #include <map>
9 #include <system_error>
10 #include <utility>
11 
12 namespace hal
13 {
14  namespace hgl_upgrade
15  {
16  namespace
17  {
19  const size_t MAX_LUT_INPUTS = 31;
20 
21  const std::map<std::string, std::string> LEGACY_TYPE_RENAMES = {{"buffer", "c_buffer"}, {"carry", "c_carry"}, {"mux", "c_mux"}, {"lut", "c_lut"}};
22 
24  using ParameterSizes = std::vector<std::pair<std::string, u64>>;
25 
26  const rapidjson::Value* find_member(const rapidjson::Value& object, const char* name)
27  {
28  if (!object.IsObject())
29  {
30  return nullptr;
31  }
32  auto it = object.FindMember(name);
33  return (it != object.MemberEnd()) ? &it->value : nullptr;
34  }
35 
36  std::string get_string(const rapidjson::Value& object, const char* name)
37  {
38  const rapidjson::Value* value = find_member(object, name);
39  return (value != nullptr && value->IsString()) ? value->GetString() : "";
40  }
41 
42  u64 get_uint(const rapidjson::Value& object, const char* name)
43  {
44  const rapidjson::Value* value = find_member(object, name);
45  return (value != nullptr && value->IsUint64()) ? value->GetUint64() : 0;
46  }
47 
48  rapidjson::Value make_string(const std::string& str, rapidjson::Document::AllocatorType& allocator)
49  {
50  return rapidjson::Value(str.c_str(), str.length(), allocator);
51  }
52 
53  void collect_pins(const rapidjson::Value& cell, std::vector<std::string>& input_pins, std::vector<std::string>& lut_output_pins)
54  {
55  const rapidjson::Value* pin_groups = find_member(cell, "pin_groups");
56  if (pin_groups == nullptr || !pin_groups->IsArray())
57  {
58  return;
59  }
60 
61  for (const auto& pin_group : pin_groups->GetArray())
62  {
63  const std::string direction = get_string(pin_group, "direction");
64  const rapidjson::Value* pins = find_member(pin_group, "pins");
65  if (pins == nullptr || !pins->IsArray())
66  {
67  continue;
68  }
69 
70  for (const auto& pin : pins->GetArray())
71  {
72  if (direction == "input")
73  {
74  input_pins.push_back(get_string(pin, "name"));
75  }
76  else if (direction == "output" && get_string(pin, "type") == "lut")
77  {
78  lut_output_pins.push_back(get_string(pin, "name"));
79  }
80  }
81  }
82  }
83 
84  void rename_legacy_types(rapidjson::Value& cell, rapidjson::Document::AllocatorType& allocator)
85  {
86  if (!cell.HasMember("types") || !cell["types"].IsArray())
87  {
88  return;
89  }
90 
91  for (auto& type : cell["types"].GetArray())
92  {
93  if (!type.IsString())
94  {
95  continue;
96  }
97  if (auto it = LEGACY_TYPE_RENAMES.find(type.GetString()); it != LEGACY_TYPE_RENAMES.end())
98  {
99  type = make_string(it->second, allocator);
100  }
101  }
102  }
103 
104  bool has_legacy_lut_config(const rapidjson::Value& cell)
105  {
106  const rapidjson::Value* lut_config = find_member(cell, "lut_config");
107  return lut_config != nullptr && lut_config->IsObject() && !lut_config->HasMember("output_pins");
108  }
109 
118  std::string upgrade_lut_config(rapidjson::Value& cell, const std::string& cell_name, rapidjson::Document::AllocatorType& allocator, std::vector<std::string>& warnings)
119  {
120  if (!has_legacy_lut_config(cell))
121  {
122  // already in the new format or nothing to upgrade
123  return "";
124  }
125 
126  rapidjson::Value& lut_config = cell["lut_config"];
127  const rapidjson::Value* data_identifier = find_member(lut_config, "data_identifier");
128  if (data_identifier == nullptr || !data_identifier->IsString())
129  {
130  return "cell '" + cell_name + "': LUT configuration has no data identifier";
131  }
132 
133  std::vector<std::string> input_pins;
134  std::vector<std::string> lut_output_pins;
135  collect_pins(cell, input_pins, lut_output_pins);
136 
137  if (lut_output_pins.empty())
138  {
139  return "cell '" + cell_name + "': no output pin with type 'lut' found";
140  }
141 
142  if (input_pins.empty())
143  {
144  return "cell '" + cell_name + "': no input pins found";
145  }
146 
147  if (input_pins.size() > MAX_LUT_INPUTS)
148  {
149  return "cell '" + cell_name + "': " + std::to_string(input_pins.size()) + " input pins exceed the supported maximum of " + std::to_string(MAX_LUT_INPUTS) + " for a LUT";
150  }
151 
152  if (lut_output_pins.size() > 1)
153  {
154  warnings.push_back("cell '" + cell_name + "': each of its " + std::to_string(lut_output_pins.size())
155  + " LUT output pins was migrated to depend on all input pins and the whole INIT value, as before. If an output uses only part of "
156  "them, e.g., output O5 of a Xilinx LUT6_2, adjust its 'input_pins' and 'bit_count' manually.");
157  }
158 
159  const rapidjson::Value* bit_order = find_member(lut_config, "bit_order");
160  const bool is_ascending = (bit_order == nullptr) || (bit_order->IsString() && std::string(bit_order->GetString()) == "ascending");
161 
162  rapidjson::Value output_pins(rapidjson::kArrayType);
163  for (const auto& lut_output_pin : lut_output_pins)
164  {
165  rapidjson::Value inputs(rapidjson::kArrayType);
166  for (const auto& pin : input_pins)
167  {
168  inputs.PushBack(make_string(pin, allocator), allocator);
169  }
170 
171  rapidjson::Value output_pin(rapidjson::kObjectType);
172  output_pin.AddMember("pin", make_string(lut_output_pin, allocator), allocator);
173  output_pin.AddMember("data_identifier", rapidjson::Value(*data_identifier, allocator), allocator);
174  output_pin.AddMember("bit_offset", 0, allocator);
175  output_pin.AddMember("bit_count", u64(1) << input_pins.size(), allocator);
176  output_pin.AddMember("input_pins", inputs, allocator);
177  output_pin.AddMember("is_ascending", is_ascending, allocator);
178  output_pins.PushBack(output_pin, allocator);
179  }
180 
181  rapidjson::Value new_lut_config(rapidjson::kObjectType);
182  if (bit_order != nullptr)
183  {
184  new_lut_config.AddMember("bit_order", rapidjson::Value(*bit_order, allocator), allocator);
185  }
186  if (const rapidjson::Value* data_category = find_member(lut_config, "data_category"); data_category != nullptr)
187  {
188  new_lut_config.AddMember("data_category", rapidjson::Value(*data_category, allocator), allocator);
189  }
190  new_lut_config.AddMember("output_pins", output_pins, allocator);
191 
192  // assigning keeps the position of 'lut_config' within the cell
193  lut_config = new_lut_config;
194  return "";
195  }
196 
197  u64* find_size(ParameterSizes& sizes, const std::string& identifier)
198  {
199  for (auto& [ident, size] : sizes)
200  {
201  if (ident == identifier)
202  {
203  return &size;
204  }
205  }
206  return nullptr;
207  }
208 
209  void set_size(ParameterSizes& sizes, const std::string& identifier, u64 size)
210  {
211  if (u64* existing = find_size(sizes, identifier); existing != nullptr)
212  {
213  *existing = size;
214  }
215  else
216  {
217  sizes.emplace_back(identifier, size);
218  }
219  }
220 
221  void add_parameters(rapidjson::Value& cell, rapidjson::Document::AllocatorType& allocator)
222  {
223  if (cell.HasMember("parameters"))
224  {
225  return;
226  }
227 
228  ParameterSizes sizes;
229 
230  if (const rapidjson::Value* lut_config = find_member(cell, "lut_config"); lut_config != nullptr)
231  {
232  if (const rapidjson::Value* output_pins = find_member(*lut_config, "output_pins"); output_pins != nullptr && output_pins->IsArray())
233  {
234  for (const auto& output_pin : output_pins->GetArray())
235  {
236  const std::string identifier = get_string(output_pin, "data_identifier");
237  const u64 required = get_uint(output_pin, "bit_offset") + get_uint(output_pin, "bit_count");
238  const u64* existing = find_size(sizes, identifier);
239  set_size(sizes, identifier, (existing != nullptr) ? std::max(*existing, required) : required);
240  }
241  }
242  }
243 
244  // flip-flops and latches hold a single bit per identifier
245  for (const char* config_name : {"ff_config", "latch_config"})
246  {
247  if (const rapidjson::Value* config = find_member(cell, config_name); config != nullptr && config->HasMember("data_identifier"))
248  {
249  const std::string identifier = get_string(*config, "data_identifier");
250  if (find_size(sizes, identifier) == nullptr)
251  {
252  set_size(sizes, identifier, 1);
253  }
254  }
255  }
256 
257  if (const rapidjson::Value* ram_config = find_member(cell, "ram_config"); ram_config != nullptr)
258  {
259  const rapidjson::Value* identifiers = find_member(*ram_config, "data_identifiers");
260  if (identifiers != nullptr && identifiers->IsArray() && !identifiers->Empty() && ram_config->HasMember("bit_size"))
261  {
262  const u64 size = get_uint(*ram_config, "bit_size") / identifiers->Size();
263  for (const auto& identifier : identifiers->GetArray())
264  {
265  set_size(sizes, identifier.IsString() ? identifier.GetString() : "", size);
266  }
267  }
268  }
269 
270  if (sizes.empty())
271  {
272  return;
273  }
274 
275  rapidjson::Value parameters(rapidjson::kArrayType);
276  for (const auto& [identifier, size] : sizes)
277  {
278  rapidjson::Value parameter(rapidjson::kObjectType);
279  parameter.AddMember("name", make_string(identifier, allocator), allocator);
280  parameter.AddMember("type", "bit_vector", allocator);
281  parameter.AddMember("size", size, allocator);
282  parameter.AddMember("default", "0x0", allocator);
283  parameters.PushBack(parameter, allocator);
284  }
285  cell.AddMember("parameters", parameters, allocator);
286  }
287  } // namespace
288 
289  Result<u32> get_version(const rapidjson::Document& document)
290  {
291  if (!document.IsObject())
292  {
293  return ERR("document is not a JSON object");
294  }
295  if (!document.HasMember("version"))
296  {
297  return OK(u32(1));
298  }
299  if (!document["version"].IsUint())
300  {
301  return ERR("invalid version entry");
302  }
303  return OK(document["version"].GetUint());
304  }
305 
306  bool needs_upgrade(const rapidjson::Document& document)
307  {
308  auto version = get_version(document);
309  if (version.is_error())
310  {
311  return false;
312  }
313  if (version.get() < TARGET_VERSION)
314  {
315  return true;
316  }
317  if (version.get() > TARGET_VERSION || !document.HasMember("cells") || !document["cells"].IsArray())
318  {
319  return false;
320  }
321 
322  // earlier upgrades marked files as up to date without migrating all LUT configurations
323  const auto& cells = document["cells"].GetArray();
324  return std::any_of(cells.begin(), cells.end(), [](const rapidjson::Value& cell) { return has_legacy_lut_config(cell); });
325  }
326 
327  Result<std::vector<std::string>> upgrade_document(rapidjson::Document& document)
328  {
329  auto version_res = get_version(document);
330  if (version_res.is_error())
331  {
332  return ERR_APPEND(version_res.get_error(), "could not upgrade HGL document");
333  }
334  const u32 version = version_res.get();
335 
336  std::vector<std::string> warnings;
337  if (!needs_upgrade(document))
338  {
339  return OK(warnings);
340  }
341 
342  if (version < 2)
343  {
344  return ERR("could not upgrade HGL document: version " + std::to_string(version) + " uses a legacy pin format that cannot be upgraded automatically");
345  }
346 
347  rapidjson::Document::AllocatorType& allocator = document.GetAllocator();
348  std::vector<std::string> errors;
349 
350  if (document.HasMember("cells") && document["cells"].IsArray())
351  {
352  for (auto& cell : document["cells"].GetArray())
353  {
354  if (!cell.IsObject())
355  {
356  continue;
357  }
358 
359  const std::string cell_name = cell.HasMember("name") && cell["name"].IsString() ? cell["name"].GetString() : "(unknown)";
360 
361  rename_legacy_types(cell, allocator);
362  if (std::string error = upgrade_lut_config(cell, cell_name, allocator, warnings); !error.empty())
363  {
364  errors.push_back(error);
365  continue;
366  }
367  add_parameters(cell, allocator);
368  }
369  }
370 
371  if (!errors.empty())
372  {
373  // a partially upgraded document must not be marked as up to date, the parser would not notice what is missing
374  std::string message = "could not upgrade HGL document, the following cells have to be migrated manually: ";
375  for (size_t i = 0; i < errors.size(); ++i)
376  {
377  message += (i == 0 ? "" : "; ") + errors[i];
378  }
379  return ERR(message);
380  }
381 
382  if (document.HasMember("version"))
383  {
384  document["version"].SetUint(TARGET_VERSION);
385  }
386  else
387  {
388  document.AddMember("version", TARGET_VERSION, allocator);
389  }
390 
391  return OK(warnings);
392  }
393 
394  std::filesystem::path get_backup_path(const std::filesystem::path& file_path)
395  {
396  std::filesystem::path backup_path = file_path;
397  backup_path.replace_extension(".json");
398 
399  // a file repaired after an earlier upgrade already has a backup, which must not be overwritten
400  std::error_code ec;
401  for (u32 i = 1; std::filesystem::exists(backup_path, ec); ++i)
402  {
403  backup_path = file_path;
404  backup_path.replace_extension("." + std::to_string(i) + ".json");
405  }
406  return backup_path;
407  }
408 
409  Result<std::filesystem::path> replace_file(const rapidjson::Document& document, const std::filesystem::path& file_path)
410  {
411  const std::filesystem::path backup_path = get_backup_path(file_path);
412 
413  std::error_code ec;
414  if (std::filesystem::exists(backup_path, ec))
415  {
416  return ERR("could not upgrade HGL file '" + file_path.string() + "': cannot keep the original as '" + backup_path.string() + "', that file already exists");
417  }
418 
419  std::filesystem::rename(file_path, backup_path, ec);
420  if (ec)
421  {
422  return ERR("could not upgrade HGL file '" + file_path.string() + "': unable to rename it to '" + backup_path.string() + "': " + ec.message());
423  }
424 
425  FILE* fp = fopen(file_path.string().c_str(), "w");
426  bool written = false;
427  if (fp != NULL)
428  {
429  char buffer[65536];
430  rapidjson::FileWriteStream os(fp, buffer, sizeof(buffer));
431  rapidjson::PrettyWriter<rapidjson::FileWriteStream> writer(os);
432  written = document.Accept(writer);
433  os.Flush();
434  written = (fclose(fp) == 0) && written;
435  }
436 
437  if (!written)
438  {
439  // put the original file back, so that nothing changed for the user
440  std::filesystem::remove(file_path, ec);
441  std::filesystem::rename(backup_path, file_path, ec);
442  return ERR("could not upgrade HGL file '" + file_path.string() + "': unable to write the upgraded file");
443  }
444 
445  return OK(backup_path);
446  }
447  } // namespace hgl_upgrade
448 } // namespace hal
u32 size
uint64_t u64
Definition: defines.h:42
uint32_t u32
Definition: defines.h:41
#define ERR(message)
Definition: result.h:60
#define OK(...)
Definition: result.h:56
#define ERR_APPEND(prev_error, message)
Definition: result.h:64
void remove(std::filesystem::path file_path)
bool needs_upgrade(const rapidjson::Document &document)
std::filesystem::path get_backup_path(const std::filesystem::path &file_path)
Result< u32 > get_version(const rapidjson::Document &document)
const u32 TARGET_VERSION
Definition: upgrade_hgl.h:59
Result< std::vector< std::string > > upgrade_document(rapidjson::Document &document)
Result< std::filesystem::path > replace_file(const rapidjson::Document &document, const std::filesystem::path &file_path)
Definition: defines.h:45
std::error_code error_code
Definition: defines.h:46
PinType type
std::vector< PinInformation > pins
PinDirection direction
std::string name
std::string identifier