From f6f85f475ba2abd186ddda10d0099750e28231ca Mon Sep 17 00:00:00 2001 From: George Rennie Date: Sun, 24 Sep 2023 12:40:41 +0100 Subject: [PATCH 001/496] smt2: Check for constant bool after fully resolving signal * This fixes #3769 --- backends/smt2/smt2.cc | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/backends/smt2/smt2.cc b/backends/smt2/smt2.cc index 5e63e6237..703628b73 100644 --- a/backends/smt2/smt2.cc +++ b/backends/smt2/smt2.cc @@ -329,13 +329,14 @@ struct Smt2Worker { sigmap.apply(bit); + if (bit_driver.count(bit)) { + export_cell(bit_driver.at(bit)); + sigmap.apply(bit); + } + if (bit.wire == nullptr) return bit == RTLIL::State::S1 ? "true" : "false"; - if (bit_driver.count(bit)) - export_cell(bit_driver.at(bit)); - sigmap.apply(bit); - if (fcache.count(bit) == 0) { if (verbose) log("%*s-> external bool: %s\n", 2+2*GetSize(recursive_cells), "", log_signal(bit)); From b16cdaab35050ca51a696b6c8e191ffb19946d0f Mon Sep 17 00:00:00 2001 From: Richard Herveille Date: Wed, 6 Mar 2024 02:43:30 +0100 Subject: [PATCH 002/496] dsp_map for MAX10 --- techlibs/intel/max10/dsp_map.v | 73 ++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 techlibs/intel/max10/dsp_map.v diff --git a/techlibs/intel/max10/dsp_map.v b/techlibs/intel/max10/dsp_map.v new file mode 100644 index 000000000..1c7827b5e --- /dev/null +++ b/techlibs/intel/max10/dsp_map.v @@ -0,0 +1,73 @@ +module \$__MUL18X18 (input [17:0] A, input [17:0] B, output [35:0] Y); + parameter A_SIGNED = 0; + parameter B_SIGNED = 0; + parameter A_WIDTH = 0; + parameter B_WIDTH = 0; + parameter Y_WIDTH = 0; + + wire [A_WIDTH+B_WIDTH-1:0] mult_result; + + fiftyfivenm_mac_mult #( + .dataa_clock ("none"), + .datab_clock ("none"), + .signa_clock ("none"), + .signb_clock ("none"), + .dataa_width (A_WIDTH), + .datab_width (B_WIDTH), + .lpm_type ("fiftyfivenm_mac_mult") + ) _TECHMAP_REPLACE_mac_mult ( + //Data path + .dataa ( A ), + .datab ( B ), + .dataout( mult_result ), + .signa ( A_SIGNED != 0 ? 1'b1 : 1'b0), + .signb ( B_SIGNED != 0 ? 1'b1 : 1'b0) + ); + + fiftyfivenm_mac_out #( + .dataa_width (A_WIDTH + B_WIDTH), + .output_clock ("none"), + .lpm_type ("fiftyfivenm_mac_out") + ) _TECHMAP_REPLACE_mac_out ( + .dataa (mult_result), + .dataout (Y) + ); +endmodule + + +module \$__MUL9X9 (input [8:0] A, input [8:0] B, output [17:0] Y); + parameter A_SIGNED = 0; + parameter B_SIGNED = 0; + parameter A_WIDTH = 0; + parameter B_WIDTH = 0; + parameter Y_WIDTH = 0; + + wire [A_WIDTH+B_WIDTH-1:0] mult_result; + + fiftyfivenm_mac_mult #( + .dataa_clock ("none"), + .datab_clock ("none"), + .signa_clock ("none"), + .signb_clock ("none"), + .dataa_width (A_WIDTH), + .datab_width (B_WIDTH), + .lpm_type ("fiftyfivenm_mac_mult") + ) _TECHMAP_REPLACE_mac_mult ( + //Data path + .dataa ( A ), + .datab ( B ), + .dataout( mult_result ), + .signa ( A_SIGNED != 0 ? 1'b1 : 1'b0), + .signb ( B_SIGNED != 0 ? 1'b1 : 1'b0) + ); + + fiftyfivenm_mac_out #( + .dataa_width (A_WIDTH + B_WIDTH), + .output_clock ("none"), + .lpm_type ("fiftyfivenm_mac_out") + ) _TECHMAP_REPLACE_mac_out ( + .dataa (mult_result), + .dataout (Y) + ); +endmodule + From 2fde482629dd523f196b231c6659609ff768a20f Mon Sep 17 00:00:00 2001 From: Richard Herveille Date: Wed, 6 Mar 2024 02:45:07 +0100 Subject: [PATCH 003/496] Fixed data/address width parameters --- techlibs/intel/common/brams_map_m9k.v | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/techlibs/intel/common/brams_map_m9k.v b/techlibs/intel/common/brams_map_m9k.v index d0f07c1de..c80ebe3f4 100644 --- a/techlibs/intel/common/brams_map_m9k.v +++ b/techlibs/intel/common/brams_map_m9k.v @@ -63,10 +63,10 @@ module \$__M9K_ALTSYNCRAM_SINGLEPORT_FULL (CLK2, CLK3, A1ADDR, A1DATA, A1EN, B1A .width_byteena_a (1), // Forced value .numwords_b ( NUMWORDS ), .numwords_a ( NUMWORDS ), - .widthad_b ( CFG_DBITS ), - .width_b ( CFG_ABITS ), - .widthad_a ( CFG_DBITS ), - .width_a ( CFG_ABITS ) + .widthad_b ( CFG_ABITS ), + .width_b ( CFG_DBITS ), + .widthad_a ( CFG_ABITS ), + .width_a ( CFG_DBITS ) ) _TECHMAP_REPLACE_ ( .data_a(B1DATA), .address_a(B1ADDR), From 58b1522a20ef9a4ec914280bcaf4f4e637f4368e Mon Sep 17 00:00:00 2001 From: Richard Herveille Date: Wed, 6 Mar 2024 02:45:29 +0100 Subject: [PATCH 004/496] Added DSP macros --- techlibs/intel/max10/cells_sim.v | 56 +++++++++++++++++++++++++++++++- 1 file changed, 55 insertions(+), 1 deletion(-) diff --git a/techlibs/intel/max10/cells_sim.v b/techlibs/intel/max10/cells_sim.v index 7705fa27a..d273b47d6 100644 --- a/techlibs/intel/max10/cells_sim.v +++ b/techlibs/intel/max10/cells_sim.v @@ -2,6 +2,7 @@ * yosys -- Yosys Open SYnthesis Suite * * Copyright (C) 2012 Claire Xenia Wolf + * Copyright (C) 2024 Richard Herveille * * Permission to use, copy, modify, and/or distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -289,4 +290,57 @@ module fiftyfivenm_pll output vcooverrange; output vcounderrange; -endmodule // cycloneive_pll +endmodule // max10_pll + + +//rih +/* MAX10 MULT clearbox model */ +(* blackbox *) +module fiftyfivenm_mac_mult ( + dataa, + datab, + dataout, + signa, + signb, + + aclr, + clk, + ena +); + parameter dataa_clock = "none"; + parameter dataa_width = 18; + parameter datab_clock = "none"; + parameter datab_width = 18; + parameter signa_clock = "none"; + parameter signb_clock = "none"; + parameter lpm_type = "fiftyfivenm_mac_mult"; + + input [dataa_width -1:0] dataa; + input [datab_width -1:0] datab; + output [(dataa_width+datab_width)-1:0] dataout; + input signa; + input signb; + input aclr; + input clk; + input ena; +endmodule : fiftyfivenm_mac_mult + +module fiftyfivenm_mac_out ( + dataa, + dataout, + + aclr, + clk, + ena +); + + parameter dataa_width = 38; + parameter output_clock = "none"; + parameter lpm_type = "fiftyfivenm_mac_out"; + + input [dataa_width-1:0] dataa; + output [dataa_width-1:0] dataout; + input aclr; + input clk; + input ena; +endmodule : fiftyfivenm_mac_out From 1723aa251afa492898b4046ff4dc867a1265d6c5 Mon Sep 17 00:00:00 2001 From: Richard Herveille Date: Wed, 6 Mar 2024 02:45:40 +0100 Subject: [PATCH 005/496] Added DSP support and updates for performance --- techlibs/intel/synth_intel.cc | 65 ++++++++++++++++++++++++++++++++--- 1 file changed, 61 insertions(+), 4 deletions(-) diff --git a/techlibs/intel/synth_intel.cc b/techlibs/intel/synth_intel.cc index e9594e6d8..00e5766e9 100644 --- a/techlibs/intel/synth_intel.cc +++ b/techlibs/intel/synth_intel.cc @@ -2,6 +2,7 @@ * yosys -- Yosys Open SYnthesis Suite * * Copyright (C) 2012 Claire Xenia Wolf + * Copyright (C) 2024 Richard Herveille * * Permission to use, copy, modify, and/or distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -62,12 +63,19 @@ struct SynthIntelPass : public ScriptPass { log(" from label is synonymous to 'begin', and empty to label is\n"); log(" synonymous to the end of the command list.\n"); log("\n"); + log(" -dff\n"); + log(" pass DFFs to ABC to perform sequential logic optimisations\n"); + log(" (EXPERIMENTAL)\n"); + log("\n"); log(" -iopads\n"); log(" use IO pad cells in output netlist\n"); log("\n"); log(" -nobram\n"); log(" do not use block RAM cells in output netlist\n"); log("\n"); + log(" -nodsp\n"); + log(" do not map multipliers to MUL18/MUL9 cells\n"); + log("\n"); log(" -noflatten\n"); log(" do not flatten design before synthesis\n"); log("\n"); @@ -80,7 +88,7 @@ struct SynthIntelPass : public ScriptPass { } string top_opt, family_opt, vout_file, blif_file; - bool retime, flatten, nobram, iopads; + bool retime, flatten, nobram, dff, nodsp, iopads; void clear_flags() override { @@ -91,6 +99,8 @@ struct SynthIntelPass : public ScriptPass { retime = false; flatten = true; nobram = false; + dff = false; + nodsp = false; iopads = false; } @@ -130,6 +140,14 @@ struct SynthIntelPass : public ScriptPass { iopads = true; continue; } + if (args[argidx] == "-dff") { + dff = true; + continue; + } + if (args[argidx] == "-nodsp") { + nodsp = true; + continue; + } if (args[argidx] == "-nobram") { nobram = true; continue; @@ -177,16 +195,52 @@ struct SynthIntelPass : public ScriptPass { run("read_verilog -sv -lib +/intel/common/altpll_bb.v"); run(stringf("hierarchy -check %s", help_mode ? "-top " : top_opt.c_str())); } - +/* if (flatten && check_label("flatten", "(unless -noflatten)")) { run("proc"); run("flatten"); run("tribuf -logic"); run("deminout"); } +*/ if (check_label("coarse")) { - run("synth -run coarse"); +// run("synth -run coarse"); + run("proc"); + if (flatten || help_mode) + run("flatten", "(skip if -noflatten)"); + run("tribuf -logic"); + run("deminout"); + run("opt_expr"); + run("opt_clean"); + run("check"); + run("opt -nodffe -nosdff"); + run("fsm"); + run("opt"); + run("wreduce"); + run("peepopt"); + run("opt_clean"); + run("techmap -map +/cmp2lut.v -D LUT_WIDTH=4"); + run("opt_expr"); + run("opt_clean"); + + if (help_mode) { + run("techmap -map +mul2dsp.v [...]", "(unless -nodsp)"); + } else if (!nodsp) { + run("techmap -map +/mul2dsp.v -D DSP_A_MAXWIDTH=18 -D DSP_B_MAXWIDTH=18 -D DSP_A_MINWIDTH=10 -D DSP_B_MINWIDTH=4 -D DSP_NAME=$__MUL18X18"); + run("chtype -set $mul t:$__soft_mul"); + run("techmap -map +/mul2dsp.v -D DSP_A_MAXWIDTH=18 -D DSP_B_MAXWIDTH=18 -D DSP_A_MINWIDTH=4 -D DSP_B_MINWIDTH=10 -D DSP_NAME=$__MUL18X18"); + run("chtype -set $mul t:$__soft_mul"); + run("techmap -map +/mul2dsp.v -D DSP_A_MAXWIDTH=9 -D DSP_B_MAXWIDTH=9 -D DSP_A_MINWIDTH=4 -D DSP_B_MINWIDTH=4 -D DSP_NAME=$__MUL9X9"); + run("chtype -set $mul t:$__soft_mul"); + run("alumacc"); + run(stringf("techmap -map +/intel/%s/dsp_map.v", family_opt.c_str())); + } else { + run("alumacc"); + } + run("opt"); + run("memory -nomap"); + run("opt_clean"); } if (!nobram && check_label("map_bram", "(skip if -nobram)")) { @@ -219,7 +273,10 @@ struct SynthIntelPass : public ScriptPass { } if (check_label("map_luts")) { - run("abc -lut 4" + string(retime ? " -dff" : "")); + run("abc9 -lut 4 -W 300" + string(dff ? " -dff" : "")); + run("clean"); + run("opt -fast"); + run("autoname"); run("clean"); } From 2d11c5e2f8199065039b7ac07e60622f9c2c583d Mon Sep 17 00:00:00 2001 From: Richard Herveille Date: Fri, 15 Mar 2024 01:48:06 +0100 Subject: [PATCH 006/496] removed comment --- techlibs/intel/max10/cells_sim.v | 1 - 1 file changed, 1 deletion(-) diff --git a/techlibs/intel/max10/cells_sim.v b/techlibs/intel/max10/cells_sim.v index d273b47d6..fe8c92b0a 100644 --- a/techlibs/intel/max10/cells_sim.v +++ b/techlibs/intel/max10/cells_sim.v @@ -293,7 +293,6 @@ module fiftyfivenm_pll endmodule // max10_pll -//rih /* MAX10 MULT clearbox model */ (* blackbox *) module fiftyfivenm_mac_mult ( From 7647eb70a6906979a7001c47e9d02c7f64f0d1f5 Mon Sep 17 00:00:00 2001 From: Richard Herveille Date: Fri, 15 Mar 2024 01:48:22 +0100 Subject: [PATCH 007/496] removed commented out code --- techlibs/intel/synth_intel.cc | 9 --------- 1 file changed, 9 deletions(-) diff --git a/techlibs/intel/synth_intel.cc b/techlibs/intel/synth_intel.cc index 00e5766e9..11567ece9 100644 --- a/techlibs/intel/synth_intel.cc +++ b/techlibs/intel/synth_intel.cc @@ -195,17 +195,8 @@ struct SynthIntelPass : public ScriptPass { run("read_verilog -sv -lib +/intel/common/altpll_bb.v"); run(stringf("hierarchy -check %s", help_mode ? "-top " : top_opt.c_str())); } -/* - if (flatten && check_label("flatten", "(unless -noflatten)")) { - run("proc"); - run("flatten"); - run("tribuf -logic"); - run("deminout"); - } -*/ if (check_label("coarse")) { -// run("synth -run coarse"); run("proc"); if (flatten || help_mode) run("flatten", "(skip if -noflatten)"); From 2893938355d786a0188753272cef5d95c3e10ccb Mon Sep 17 00:00:00 2001 From: Richard Herveille Date: Tue, 19 Mar 2024 01:31:36 +0100 Subject: [PATCH 008/496] Removed SystemVerilog module end label --- techlibs/intel/max10/cells_sim.v | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/techlibs/intel/max10/cells_sim.v b/techlibs/intel/max10/cells_sim.v index fe8c92b0a..b163aac40 100644 --- a/techlibs/intel/max10/cells_sim.v +++ b/techlibs/intel/max10/cells_sim.v @@ -322,7 +322,7 @@ module fiftyfivenm_mac_mult ( input aclr; input clk; input ena; -endmodule : fiftyfivenm_mac_mult +endmodule //fiftyfivenm_mac_mult module fiftyfivenm_mac_out ( dataa, @@ -342,4 +342,4 @@ module fiftyfivenm_mac_out ( input aclr; input clk; input ena; -endmodule : fiftyfivenm_mac_out +endmodule //fiftyfivenm_mac_out From 41aaaa153e1921c867a3e82d0f2f71d81c7f0804 Mon Sep 17 00:00:00 2001 From: George Rennie Date: Wed, 12 Jun 2024 14:38:12 +0100 Subject: [PATCH 009/496] peepopt shiftadd: Only match for sufficiently small constant widths This addresses issue #4445 --- passes/pmgen/peepopt_shiftadd.pmg | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/passes/pmgen/peepopt_shiftadd.pmg b/passes/pmgen/peepopt_shiftadd.pmg index e690ff651..47a5ed18f 100644 --- a/passes/pmgen/peepopt_shiftadd.pmg +++ b/passes/pmgen/peepopt_shiftadd.pmg @@ -53,6 +53,11 @@ match add select port(add, constport).is_fully_const() define varport (constport == \A ? \B : \A) + // only optimize for constants up to a fixed width. this prevents cases + // with a blowup in internal term size and prevents larger constants being + // casted to int incorrectly + select (GetSize(port(add, constport)) <= 24) + // if a value of var is able to wrap the output, the transformation might give wrong results // an addition/substraction can at most flip one more bit than the largest operand (the carry bit) // as long as the output can show this bit, no wrap should occur (assuming all signed-ness make sense) From 2cb3b6e9b8f59936524729af591d1cfbcec0e461 Mon Sep 17 00:00:00 2001 From: George Rennie Date: Tue, 6 Aug 2024 16:32:26 +0100 Subject: [PATCH 010/496] peepopt: add formal only peepopt to rewrite latches to ffs in clock gates * this is gated behind the -formalclk flag, which also disables the other synthesis focused optimizations --- passes/pmgen/Makefile.inc | 1 + passes/pmgen/peepopt.cc | 26 +++++++-- passes/pmgen/peepopt_formal_clockgateff.pmg | 59 +++++++++++++++++++++ 3 files changed, 81 insertions(+), 5 deletions(-) create mode 100644 passes/pmgen/peepopt_formal_clockgateff.pmg diff --git a/passes/pmgen/Makefile.inc b/passes/pmgen/Makefile.inc index 84d9ebaf1..6fa7d1fd7 100644 --- a/passes/pmgen/Makefile.inc +++ b/passes/pmgen/Makefile.inc @@ -57,6 +57,7 @@ PEEPOPT_PATTERN = passes/pmgen/peepopt_shiftmul_right.pmg PEEPOPT_PATTERN += passes/pmgen/peepopt_shiftmul_left.pmg PEEPOPT_PATTERN += passes/pmgen/peepopt_shiftadd.pmg PEEPOPT_PATTERN += passes/pmgen/peepopt_muldiv.pmg +PEEPOPT_PATTERN += passes/pmgen/peepopt_formal_clockgateff.pmg passes/pmgen/peepopt_pm.h: passes/pmgen/pmgen.py $(PEEPOPT_PATTERN) $(P) mkdir -p passes/pmgen && $(PYTHON_EXECUTABLE) $< -o $@ -p peepopt $(filter-out $<,$^) diff --git a/passes/pmgen/peepopt.cc b/passes/pmgen/peepopt.cc index 5638ec3c2..5b678ee55 100644 --- a/passes/pmgen/peepopt.cc +++ b/passes/pmgen/peepopt.cc @@ -40,7 +40,7 @@ struct PeepoptPass : public Pass { log("\n"); log("This pass applies a collection of peephole optimizers to the current design.\n"); log("\n"); - log("This pass employs the following rules:\n"); + log("This pass employs the following rules by default:\n"); log("\n"); log(" * muldiv - Replace (A*B)/B with A\n"); log("\n"); @@ -57,14 +57,26 @@ struct PeepoptPass : public Pass { log(" limits the amount of padding to a multiple of the data, \n"); log(" to avoid high resource usage from large temporary MUX trees.\n"); log("\n"); + log("If -formalclk is specified it instead employs the following rules:\n"); + log("\n"); + log(" * clockgateff - Replace latch based clock gating patterns with a flip-flop\n"); + log(" based pattern to prevent combinational paths from the\n"); + log(" output to the enable input after running clk2fflogic.\n"); + log("\n"); } void execute(std::vector args, RTLIL::Design *design) override { log_header(design, "Executing PEEPOPT pass (run peephole optimizers).\n"); + bool formalclk = false; + size_t argidx; for (argidx = 1; argidx < args.size(); argidx++) { + if (args[argidx] == "-formalclk") { + formalclk = true; + continue; + } break; } extra_args(args, argidx, design); @@ -86,10 +98,14 @@ struct PeepoptPass : public Pass { pm.setup(module->selected_cells()); - pm.run_shiftadd(); - pm.run_shiftmul_right(); - pm.run_shiftmul_left(); - pm.run_muldiv(); + if (formalclk) { + pm.run_formal_clockgateff(); + } else { + pm.run_shiftadd(); + pm.run_shiftmul_right(); + pm.run_shiftmul_left(); + pm.run_muldiv(); + } } } } diff --git a/passes/pmgen/peepopt_formal_clockgateff.pmg b/passes/pmgen/peepopt_formal_clockgateff.pmg new file mode 100644 index 000000000..835f68bd8 --- /dev/null +++ b/passes/pmgen/peepopt_formal_clockgateff.pmg @@ -0,0 +1,59 @@ +pattern formal_clockgateff + +// Detects the most common clock gating pattern using a latch and replaces it +// with a functionally equivalent pattern based on a flip-flop. The latch +// based pattern has a combinational path from the enable input to output after +// clk2fflogic, but this is a stable loop and the flip-flop based pattern does +// not exhibit this. +// +// This optimization is suitable for formal to prevent false comb loops, but +// should not be used for synthesis where the latch is an intentional choice +// +// Latch style: +// always @* if (!clk_i) latched_en = en; +// assign gated_clk_o = latched_en & clk_i; +// +// Flip-flop style: +// always @(posedge clk) flopped_en <= en; +// assign gated_clk_o = flopped_en & clk_i; + +state clk en latched_en gated_clk +state latched_en_port_name + +match latch + select latch->type == $dlatch + select param(latch, \WIDTH) == 1 + select param(latch, \EN_POLARITY).as_bool() == false + set clk port(latch, \EN) + set en port(latch, \D) + set latched_en port(latch, \Q) +endmatch + +match and_gate + select and_gate->type.in($and, $logic_and) + select param(and_gate, \A_WIDTH) == 1 + select param(and_gate, \B_WIDTH) == 1 + select param(and_gate, \Y_WIDTH) == 1 + choice clk_port {\A, \B} + define latch_port {clk_port == \A ? \B : \A} + index port(and_gate, clk_port) === clk + index port(and_gate, latch_port) === latched_en + set gated_clk port(and_gate, \Y) + set latched_en_port_name latch_port +endmatch + +code + log("replacing clock gate pattern in %s with ff: latch=%s, and=%s\n", + log_id(module), log_id(latch), log_id(and_gate)); + + // Add a flip-flop and rewire the AND gate to use the output of this flop + // instead of the latch. We don't delete the latch in case its output is + // used to drive other nodes. If it isn't, it will be trivially removed by + // clean + SigSpec flopped_en = module->addWire(NEW_ID); + module->addDff(NEW_ID, clk, en, flopped_en, true, latch->get_src_attribute()); + and_gate->setPort(latched_en_port_name, flopped_en); + did_something = true; + + accept; +endcode From 236c69bed440ca9456c0c9c609e5ee6839322be8 Mon Sep 17 00:00:00 2001 From: George Rennie Date: Wed, 7 Aug 2024 09:59:44 +0100 Subject: [PATCH 011/496] clk2fflogic: run peepopt -formalclk before processing design * this attempts to rewrite clock gating patterns into a form that is less likely to introduce combinational loops with clk2fflogic * can be disabled with -nopeepopt which is useful for testing clk2fflogic --- passes/sat/clk2fflogic.cc | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/passes/sat/clk2fflogic.cc b/passes/sat/clk2fflogic.cc index bcefa7d8f..348bab727 100644 --- a/passes/sat/clk2fflogic.cc +++ b/passes/sat/clk2fflogic.cc @@ -51,6 +51,10 @@ struct Clk2fflogicPass : public Pass { log(" -nolower\n"); log(" Do not automatically run 'chformal -lower' to lower $check cells.\n"); log("\n"); + log(" -nopeepopt\n"); + log(" Do not automatically run 'peepopt -formalclk' to rewrite clock patterns\n"); + log(" to more formal friendly forms.\n"); + log("\n"); } // Active-high sampled and current value of a level-triggered control signal. Initial sampled values is low/non-asserted. SampledSig sample_control(Module *module, SigSpec sig, bool polarity, bool is_fine) { @@ -121,6 +125,7 @@ struct Clk2fflogicPass : public Pass { void execute(std::vector args, RTLIL::Design *design) override { bool flag_nolower = false; + bool flag_nopeepopt = false; log_header(design, "Executing CLK2FFLOGIC pass (convert clocked FFs to generic $ff cells).\n"); @@ -131,10 +136,20 @@ struct Clk2fflogicPass : public Pass { flag_nolower = true; continue; } + if (args[argidx] == "-nopeepopt") { + flag_nopeepopt = true; + continue; + } break; } extra_args(args, argidx, design); + if (!flag_nopeepopt) { + log_push(); + Pass::call(design, "peepopt -formalclk"); + log_pop(); + } + bool have_check_cells = false; for (auto module : design->selected_modules()) From b6ceff2aab27c988b7de8e072eb4bc07d1637e75 Mon Sep 17 00:00:00 2001 From: George Rennie Date: Wed, 7 Aug 2024 09:59:18 +0100 Subject: [PATCH 012/496] peepopt clockgateff: add testcase --- tests/various/peepopt_formal.ys | 45 +++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 tests/various/peepopt_formal.ys diff --git a/tests/various/peepopt_formal.ys b/tests/various/peepopt_formal.ys new file mode 100644 index 000000000..52bf3c67f --- /dev/null +++ b/tests/various/peepopt_formal.ys @@ -0,0 +1,45 @@ +read_verilog -sv < Date: Tue, 24 Sep 2024 14:20:40 +0100 Subject: [PATCH 013/496] opt_demorgan: skip zero width cells --- passes/opt/opt_demorgan.cc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/passes/opt/opt_demorgan.cc b/passes/opt/opt_demorgan.cc index 4db3a8101..1a2c1fe82 100644 --- a/passes/opt/opt_demorgan.cc +++ b/passes/opt/opt_demorgan.cc @@ -39,6 +39,10 @@ void demorgan_worker( return; auto insig = sigmap(cell->getPort(ID::A)); + + if (GetSize(insig) < 1) + return; + log("Inspecting %s cell %s (%d inputs)\n", log_id(cell->type), log_id(cell->name), GetSize(insig)); int num_inverted = 0; for(int i=0; i Date: Wed, 25 Sep 2024 16:10:16 +0100 Subject: [PATCH 014/496] opt_demorgan: add test for zero width cell --- tests/opt/bug4610.ys | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 tests/opt/bug4610.ys diff --git a/tests/opt/bug4610.ys b/tests/opt/bug4610.ys new file mode 100644 index 000000000..fc9f0ae43 --- /dev/null +++ b/tests/opt/bug4610.ys @@ -0,0 +1,15 @@ +read_ilang < Date: Wed, 25 Sep 2024 16:20:29 +0100 Subject: [PATCH 015/496] opt_reduce: keep at least one input to $reduce_or/and cells --- passes/opt/opt_reduce.cc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/passes/opt/opt_reduce.cc b/passes/opt/opt_reduce.cc index c36a38dae..d27878fa7 100644 --- a/passes/opt/opt_reduce.cc +++ b/passes/opt/opt_reduce.cc @@ -89,6 +89,9 @@ struct OptReduceWorker RTLIL::SigSpec new_sig_a(new_sig_a_bits); new_sig_a.sort_and_unify(); + if (GetSize(new_sig_a) == 0) + new_sig_a = (cell->type == ID($reduce_or)) ? State::S0 : State::S1; + if (new_sig_a != sig_a || sig_a.size() != cell->getPort(ID::A).size()) { log(" New input vector for %s cell %s: %s\n", cell->type.c_str(), cell->name.c_str(), log_signal(new_sig_a)); did_something = true; From 0572f8806f25dcf543215a47d08bb0f57a74ba7e Mon Sep 17 00:00:00 2001 From: George Rennie Date: Wed, 25 Sep 2024 16:28:41 +0100 Subject: [PATCH 016/496] opt_reduce: add test for constant $reduce_and/or not being zero width --- tests/opt/opt_reduce_andor.ys | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 tests/opt/opt_reduce_andor.ys diff --git a/tests/opt/opt_reduce_andor.ys b/tests/opt/opt_reduce_andor.ys new file mode 100644 index 000000000..b57036528 --- /dev/null +++ b/tests/opt/opt_reduce_andor.ys @@ -0,0 +1,14 @@ +# Check that opt_reduce doesn't produce zero width $reduce_or/$reduce_and, + +read_verilog < Date: Mon, 30 Sep 2024 14:08:35 +0200 Subject: [PATCH 017/496] Fix: handle VCD variable references with and without whitespace MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Miodrag Milanović Co-authored-by: Roland Coeurjoly --- kernel/fstdata.cc | 10 ++++++- tests/sim/var_reference_with_whitespace.vcd | 28 +++++++++++++++++++ .../sim/var_reference_without_whitespace.vcd | 28 +++++++++++++++++++ tests/sim/vcd_var_reference_whitespace.ys | 3 ++ tests/sim/vector_assign.il | 20 +++++++++++++ 5 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 tests/sim/var_reference_with_whitespace.vcd create mode 100644 tests/sim/var_reference_without_whitespace.vcd create mode 100644 tests/sim/vcd_var_reference_whitespace.ys create mode 100644 tests/sim/vector_assign.il diff --git a/kernel/fstdata.cc b/kernel/fstdata.cc index 65ae3426c..4a5b5a466 100644 --- a/kernel/fstdata.cc +++ b/kernel/fstdata.cc @@ -137,14 +137,22 @@ void FstData::extractVarNames() if (!var.is_alias) handle_to_var[h->u.var.handle] = var; std::string clean_name; + bool has_space = false; for(size_t i=0;iu.var.name);i++) { char c = h->u.var.name[i]; - if(c==' ') break; + if(c==' ') { has_space = true; break; } clean_name += c; } if (clean_name[0]=='\\') clean_name = clean_name.substr(1); + if (!has_space) { + size_t pos = clean_name.find_last_of("["); + std::string index_or_range = clean_name.substr(pos+1); + if (index_or_range.find(":") != std::string::npos) { + clean_name = clean_name.substr(0,pos); + } + } size_t pos = clean_name.find_last_of("<"); if (pos != std::string::npos && clean_name.back() == '>') { std::string mem_cell = clean_name.substr(0, pos); diff --git a/tests/sim/var_reference_with_whitespace.vcd b/tests/sim/var_reference_with_whitespace.vcd new file mode 100644 index 000000000..240610b2c --- /dev/null +++ b/tests/sim/var_reference_with_whitespace.vcd @@ -0,0 +1,28 @@ +$date + Fri Sep 27 11:58:46 2024 +$end +$version + GHDL v0 +$end +$timescale + 1 fs +$end +$scope module standard $end +$upscope $end +$scope module std_logic_1164 $end +$upscope $end +$scope module tb $end +$var reg 4 ! a [3:0] $end +$var reg 4 " b [3:0] $end +$scope module uut $end +$var reg 4 # a [3:0] $end +$var reg 4 $ b [3:0] $end +$upscope $end +$upscope $end +$enddefinitions $end +#0 +b0001 ! +b0001 " +b0001 # +b0001 $ +#10000000 diff --git a/tests/sim/var_reference_without_whitespace.vcd b/tests/sim/var_reference_without_whitespace.vcd new file mode 100644 index 000000000..43b000752 --- /dev/null +++ b/tests/sim/var_reference_without_whitespace.vcd @@ -0,0 +1,28 @@ +$date + Fri Sep 27 11:58:46 2024 +$end +$version + GHDL v0 +$end +$timescale + 1 fs +$end +$scope module standard $end +$upscope $end +$scope module std_logic_1164 $end +$upscope $end +$scope module tb $end +$var reg 4 ! a[3:0] $end +$var reg 4 " b[3:0] $end +$scope module uut $end +$var reg 4 # a[3:0] $end +$var reg 4 $ b[3:0] $end +$upscope $end +$upscope $end +$enddefinitions $end +#0 +b0001 ! +b0001 " +b0001 # +b0001 $ +#10000000 diff --git a/tests/sim/vcd_var_reference_whitespace.ys b/tests/sim/vcd_var_reference_whitespace.ys new file mode 100644 index 000000000..8e17821d2 --- /dev/null +++ b/tests/sim/vcd_var_reference_whitespace.ys @@ -0,0 +1,3 @@ +read_rtlil vector_assign.il +sim -r var_reference_without_whitespace.vcd -scope tb.uut +sim -r var_reference_with_whitespace.vcd -scope tb.uut \ No newline at end of file diff --git a/tests/sim/vector_assign.il b/tests/sim/vector_assign.il new file mode 100644 index 000000000..bc0bc6b6b --- /dev/null +++ b/tests/sim/vector_assign.il @@ -0,0 +1,20 @@ +# Generated by Yosys 0.45+139 (git sha1 e7fc1b0cc, g++ 13.2.0 -fPIC -O3) +autoidx 2 +attribute \architecture "Behavioral" +attribute \library "work" +attribute \hdlname "vector_assign" +attribute \src "tests/verific/vector_assign.vhd:4.8-4.21" +module \vector_assign + attribute \src "tests/verific/vector_assign.vhd:6.9-6.10" + wire width 4 input 2 \a + attribute \src "tests/verific/vector_assign.vhd:7.9-7.10" + wire width 4 output 1 \b + attribute \src "tests/verific/vector_assign.vhd:13.5-13.6" + cell $pos $verific$buf_3$tests/verific/vector_assign.vhd:13$1 + parameter \A_SIGNED 0 + parameter \A_WIDTH 4 + parameter \Y_WIDTH 4 + connect \A \a + connect \Y \b + end +end From 5ea2c6e6e56075b9d6402cf93d3e12da46707db5 Mon Sep 17 00:00:00 2001 From: Roland Coeurjoly Date: Wed, 2 Oct 2024 11:18:19 +0200 Subject: [PATCH 018/496] Assume x values for missing signal data in FST Co-authored-by: Miodrag Milanovic Co-authored-by: Roland Coeurjoly --- kernel/fstdata.cc | 5 +++-- tests/sim/assume_x_first_step.ys | 2 ++ tests/sim/simple_assign.v | 8 ++++++++ tests/sim/simple_assign.vcd | 13 +++++++++++++ 4 files changed, 26 insertions(+), 2 deletions(-) create mode 100644 tests/sim/assume_x_first_step.ys create mode 100644 tests/sim/simple_assign.v create mode 100644 tests/sim/simple_assign.vcd diff --git a/kernel/fstdata.cc b/kernel/fstdata.cc index 65ae3426c..309131e01 100644 --- a/kernel/fstdata.cc +++ b/kernel/fstdata.cc @@ -258,7 +258,8 @@ void FstData::reconstructAllAtTimes(std::vector &signal, uint64_t sta std::string FstData::valueOf(fstHandle signal) { - if (past_data.find(signal) == past_data.end()) - log_error("Signal id %d not found\n", (int)signal); + if (past_data.find(signal) == past_data.end()) { + return std::string(handle_to_var[signal].width, 'x'); + } return past_data[signal]; } diff --git a/tests/sim/assume_x_first_step.ys b/tests/sim/assume_x_first_step.ys new file mode 100644 index 000000000..3922e06f6 --- /dev/null +++ b/tests/sim/assume_x_first_step.ys @@ -0,0 +1,2 @@ +read_verilog simple_assign.v +sim -r simple_assign.vcd -scope simple_assign \ No newline at end of file diff --git a/tests/sim/simple_assign.v b/tests/sim/simple_assign.v new file mode 100644 index 000000000..85f3a8bf5 --- /dev/null +++ b/tests/sim/simple_assign.v @@ -0,0 +1,8 @@ +module simple_assign ( + input wire in, + output wire out +); + + assign out = in; + +endmodule diff --git a/tests/sim/simple_assign.vcd b/tests/sim/simple_assign.vcd new file mode 100644 index 000000000..c4494fadf --- /dev/null +++ b/tests/sim/simple_assign.vcd @@ -0,0 +1,13 @@ +$version Yosys $end +$scope module simple_assign $end +$var wire 1 n2 in $end +$var wire 1 n1 out $end +$upscope $end +$enddefinitions $end +#0 +#5 +b1 n1 +b1 n2 +#10 +b0 n1 +b0 n2 \ No newline at end of file From 268926cb5be57c43cbefd3cd0e67e40770e521a5 Mon Sep 17 00:00:00 2001 From: George Rennie Date: Tue, 8 Oct 2024 14:34:17 +0200 Subject: [PATCH 019/496] write_btor: don't emit undriven bits multiple times * Fixes #4640 --- backends/btor/btor.cc | 1 + 1 file changed, 1 insertion(+) diff --git a/backends/btor/btor.cc b/backends/btor/btor.cc index 9cfd967e5..81402fa49 100644 --- a/backends/btor/btor.cc +++ b/backends/btor/btor.cc @@ -1077,6 +1077,7 @@ struct BtorWorker btorf("%d input %d\n", nid, sid); ywmap_input(s); nid_width[nid] = GetSize(s); + add_nid_sig(nid, s); for (int j = 0; j < GetSize(s); j++) nidbits.push_back(make_pair(nid, j)); From 6ab39319647009def8926da4c82ca340790fa4b9 Mon Sep 17 00:00:00 2001 From: George Rennie Date: Wed, 9 Oct 2024 13:48:26 +0200 Subject: [PATCH 020/496] write_btor: only initialize array with const value when it is fully def * If all addresses of an array have the same initial value, they can be initialized in one go in btor with the constraint that the initial value must be fully const and thus can't have undef bits in --- backends/btor/btor.cc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/backends/btor/btor.cc b/backends/btor/btor.cc index 9cfd967e5..1c2d5132e 100644 --- a/backends/btor/btor.cc +++ b/backends/btor/btor.cc @@ -832,7 +832,10 @@ struct BtorWorker } } - if (constword) + // If not fully defined, undef bits should be able to take a + // different value for each address so we can't initialise from + // one value (and btor2parser doesn't like it) + if (constword && firstword.is_fully_def()) { if (verbose) btorf("; initval = %s\n", log_signal(firstword)); From a6641da73cdc6704166ba484d98d1f0edfa23773 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 9 Apr 2024 12:24:26 +1200 Subject: [PATCH 021/496] Docs: Initial version of cell_ref autogen --- docs/.gitignore | 1 + docs/source/appendix.rst | 1 + docs/source/cell_ref.rst | 12 ++++++++ kernel/register.cc | 60 ++++++++++++++++++++++++++++++++++++++-- 4 files changed, 72 insertions(+), 2 deletions(-) create mode 100644 docs/source/cell_ref.rst diff --git a/docs/.gitignore b/docs/.gitignore index 65bbcdeae..78a1f48e1 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,5 +1,6 @@ /build/ /source/cmd +/source/cell /source/generated /source/_images/**/*.log /source/_images/**/*.aux diff --git a/docs/source/appendix.rst b/docs/source/appendix.rst index 0b0a2d15b..9e8b8be34 100644 --- a/docs/source/appendix.rst +++ b/docs/source/appendix.rst @@ -16,3 +16,4 @@ Appendix :includehidden: cmd_ref + cell_ref diff --git a/docs/source/cell_ref.rst b/docs/source/cell_ref.rst new file mode 100644 index 000000000..ddf66812d --- /dev/null +++ b/docs/source/cell_ref.rst @@ -0,0 +1,12 @@ +.. _cell_ref: + +================================================================================ +Internal cell reference +================================================================================ + +.. toctree:: + :caption: Internal cell reference + :maxdepth: 1 + :glob: + + /cell/* diff --git a/kernel/register.cc b/kernel/register.cc index 80bc44901..17bfb079a 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -771,7 +771,7 @@ struct HelpPass : public Pass { log(" help + .... print verilog code for given cell type\n"); log("\n"); } - void write_rst(std::string cmd, std::string title, std::string text) + void write_cmd_rst(std::string cmd, std::string title, std::string text) { FILE *f = fopen(stringf("docs/source/cmd/%s.rst", cmd.c_str()).c_str(), "wt"); // make header @@ -864,6 +864,57 @@ struct HelpPass : public Pass { } fclose(f); } + void write_cell_rst(std::string cell, std::string help, std::string code) + { + // open + string safe_name = cell.substr(1); + FILE *f = fopen(stringf("docs/source/cell/%s.rst", safe_name.c_str()).c_str(), "wt"); + + // make header + string short_help = ""; + string long_help = ""; + string title_line = cell; + for (auto line : split_tokens(help, "\n")) { + if (short_help == "") { + size_t first_pos = line.find_first_not_of(" \t"); + // skip empty lines + if (first_pos == string::npos) continue; + if (line.find(cell.c_str()) == string::npos) { + // strip leading/trailing space + size_t last_pos = line.find_last_not_of(" \t"); + short_help = line.substr(first_pos, last_pos - first_pos +1); + // skip missing help message + if (short_help == "No help message for this cell type found.") { + long_help += line; + long_help += "\n"; + } else { + title_line = stringf("%s - %s", cell.c_str(), short_help.c_str()); + } + } + } else { + long_help += line; + long_help += "\n"; + } + } + string underline = "\n"; + underline.insert(0, title_line.length(), '='); + fprintf(f, "%s\n", title_line.c_str()); + fprintf(f, "%s\n", underline.c_str()); + + // help text + fprintf(f, "%s\n", long_help.c_str()); + + // source code + fprintf(f, ".. code:: verilog\n\n"); + std::stringstream ss; + ss << code; + for (std::string line; std::getline(ss, line, '\n');) { + fprintf(f, "\t%s\n", line.c_str()); + } + + // close + fclose(f); + } void execute(std::vector args, RTLIL::Design*) override { if (args.size() == 1) { @@ -917,7 +968,12 @@ struct HelpPass : public Pass { log("\n"); } log_streams.pop_back(); - write_rst(it.first, it.second->short_help, buf.str()); + write_cmd_rst(it.first, it.second->short_help, buf.str()); + } + } + else if (args[1] == "-write-rst-cells-manual") { + for (auto &it : cell_help_messages.cell_help) { + write_cell_rst(it.first, it.second, cell_help_messages.cell_code.at(it.first + "+")); } } else if (pass_register.count(args[1])) { From 6bbe763845023c55f66c270cab347d54a989836f Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 9 Apr 2024 15:33:50 +1200 Subject: [PATCH 022/496] Docs: Put cell library help strings into a struct Allows for more expressive code when constructing help messages for cells. Will also move extra logic in parsing help strings into the initial python parse instead of doing it in the C++ at export time. --- kernel/register.cc | 43 +++++++++++++++++++------ techlibs/common/cellhelp.py | 64 +++++++++++++++++++++++++------------ 2 files changed, 78 insertions(+), 29 deletions(-) diff --git a/kernel/register.cc b/kernel/register.cc index 17bfb079a..85d3d4748 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -747,9 +747,25 @@ void Backend::backend_call(RTLIL::Design *design, std::ostream *f, std::string f design->selection_stack.pop_back(); } +struct SimHelper { + string name; + inline string filesafe_name() { + if (name.at(0) == '$') + return name.substr(1); + else + return name; + } + string short_desc; + string ports; + string desc; + string code; + string ver; +}; + static struct CellHelpMessages { - dict cell_help, cell_code; + dict cell_help, cell_code; CellHelpMessages() { + SimHelper tempCell; #include "techlibs/common/simlib_help.inc" #include "techlibs/common/simcells_help.inc" cell_help.sort(); @@ -947,9 +963,8 @@ struct HelpPass : public Pass { else if (args[1] == "-cells") { log("\n"); for (auto &it : cell_help_messages.cell_help) { - string line = split_tokens(it.second, "\n").at(0); - string cell_name = next_token(line); - log(" %-15s %s\n", cell_name.c_str(), line.c_str()); + SimHelper help_cell = it.second; + log(" %-15s %s\n", help_cell.name.c_str(), help_cell.ports.c_str()); } log("\n"); log("Type 'help ' for more information on a cell type.\n"); @@ -973,7 +988,7 @@ struct HelpPass : public Pass { } else if (args[1] == "-write-rst-cells-manual") { for (auto &it : cell_help_messages.cell_help) { - write_cell_rst(it.first, it.second, cell_help_messages.cell_code.at(it.first + "+")); + write_cell_rst(it.first, it.second.desc, it.second.code); } } else if (pass_register.count(args[1])) { @@ -985,13 +1000,23 @@ struct HelpPass : public Pass { } } else if (cell_help_messages.cell_help.count(args[1])) { - log("%s", cell_help_messages.cell_help.at(args[1]).c_str()); - log("Run 'help %s+' to display the Verilog model for this cell type.\n", args[1].c_str()); - log("\n"); + SimHelper help_cell = cell_help_messages.cell_help.at(args[1]); + if (help_cell.ver == "2") { + log("\n %s %s\n", help_cell.name.c_str(), help_cell.ports.c_str()); + log("\n%s\n", help_cell.short_desc.c_str()); + log("%s\n", help_cell.desc.c_str()); + log("Run 'help %s+' to display the Verilog model for this cell type.\n", args[1].c_str()); + log("\n"); + } else { + log("%s\n", help_cell.desc.c_str()); + log("Run 'help %s+' to display the Verilog model for this cell type.\n", args[1].c_str()); + log("\n"); + } } else if (cell_help_messages.cell_code.count(args[1])) { + SimHelper help_cell = cell_help_messages.cell_code.at(args[1]); log("\n"); - log("%s", cell_help_messages.cell_code.at(args[1]).c_str()); + log("%s\n", help_cell.code.c_str()); } else log("No such command or cell type: %s\n", args[1].c_str()); diff --git a/techlibs/common/cellhelp.py b/techlibs/common/cellhelp.py index 5c44cb802..8d0d7d757 100644 --- a/techlibs/common/cellhelp.py +++ b/techlibs/common/cellhelp.py @@ -1,34 +1,58 @@ #!/usr/bin/env python3 +from __future__ import annotations import fileinput import json -current_help_msg = [] -current_module_code = [] -current_module_name = None -current_module_signature = None +class SimHelper: + name: str = "" + short_desc: str = "" + ports: str = "" + desc: list[str] + code: list[str] + ver: str = "1" -def print_current_cell(): - print("cell_help[\"%s\"] = %s;" % (current_module_name, "\n".join([json.dumps(line) for line in current_help_msg]))) - print("cell_code[\"%s+\"] = %s;" % (current_module_name, "\n".join([json.dumps(line) for line in current_module_code]))) + def __init__(self) -> None: + self.desc = [] + + def __str__(self) -> str: + val = "tempCell = {\n" + val += f' {json.dumps(self.name)},\n' + val += f' {json.dumps(self.short_desc)},\n' + val += f' {json.dumps(self.ports)},\n' + val += ' ' + json.dumps("\n".join(self.desc)) + ',\n' + val += ' ' + json.dumps("\n".join(self.code)) + ',\n' + val += f' {json.dumps(self.ver)},\n' + val += "};\n" + val += f'cell_help[{json.dumps(self.name)}] = tempCell;' + val += "\n" + val += f'cell_code[{json.dumps(self.name + "+")}] = tempCell;' + return val + +simHelper = SimHelper() for line in fileinput.input(): + line = line.rstrip() + # special comments if line.startswith("//-"): - current_help_msg.append(line[4:] if len(line) > 4 else "\n") + simHelper.desc.append(line[4:] if len(line) > 4 else "") + elif line.startswith("//* "): + _, key, val = line.split(maxsplit=2) + setattr(simHelper, key, val) + + # code parsing if line.startswith("module "): - current_module_name = line.split()[1].strip("\\") - current_module_signature = " ".join(line.replace("\\", "").replace(";", "").split()[1:]) - current_module_code = [] + clean_line = line[7:].replace("\\", "").replace(";", "") + simHelper.name, simHelper.ports = clean_line.split(maxsplit=1) + simHelper.code = [] elif not line.startswith("endmodule"): line = " " + line - current_module_code.append(line.replace("\t", " ")) + try: + simHelper.code.append(line.replace("\t", " ")) + except AttributeError: + # no module definition, ignore line + pass if line.startswith("endmodule"): - if len(current_help_msg) == 0: - current_help_msg.append("\n") - current_help_msg.append(" %s\n" % current_module_signature) - current_help_msg.append("\n") - current_help_msg.append("No help message for this cell type found.\n") - current_help_msg.append("\n") - print_current_cell() - current_help_msg = [] + print(simHelper) + simHelper = SimHelper() From 600149a824f85808fb8231f187d848321d36bb46 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 9 Apr 2024 16:12:41 +1200 Subject: [PATCH 023/496] Docs: Add back message for empty help --- techlibs/common/cellhelp.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/techlibs/common/cellhelp.py b/techlibs/common/cellhelp.py index 8d0d7d757..4d40b73c0 100644 --- a/techlibs/common/cellhelp.py +++ b/techlibs/common/cellhelp.py @@ -53,6 +53,8 @@ for line in fileinput.input(): # no module definition, ignore line pass if line.startswith("endmodule"): + if not simHelper.desc: + simHelper.desc.append("No help message for this cell type found.\n") print(simHelper) simHelper = SimHelper() From 4662476ec80abec1ec56659bb4c500a1c6adb8d7 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 9 Apr 2024 16:13:10 +1200 Subject: [PATCH 024/496] Docs: Test $alu with v2 help format --- techlibs/common/simlib.v | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/techlibs/common/simlib.v b/techlibs/common/simlib.v index 60f98af28..71bb58c41 100644 --- a/techlibs/common/simlib.v +++ b/techlibs/common/simlib.v @@ -621,15 +621,12 @@ endmodule // -------------------------------------------------------- -// |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| -//- -//- $alu (A, B, CI, BI, X, Y, CO) -//- -//- Arithmetic logic unit. +//* ver 2 +//* short_desc Arithmetic logic unit //- A building block supporting both binary addition/subtraction operations, and //- indirectly, comparison operations. //- Typically created by the `alumacc` pass, which transforms: -//- $add, $sub, $lt, $le, $ge, $gt, $eq, $eqx, $ne, $nex +//- $add, $sub, $lt, $le, $ge, $gt, $eq, $eqx, $ne, $nex //- cells into this $alu cell. //- module \$alu (A, B, CI, BI, X, Y, CO); From 1e5a50ff3a7c4bb2cd0de35838a88f0fcfb66475 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 9 Apr 2024 16:13:37 +1200 Subject: [PATCH 025/496] Docs: Convert write_cell_rst to use SimHelper --- kernel/register.cc | 49 ++++++++++++++++------------------------------ 1 file changed, 17 insertions(+), 32 deletions(-) diff --git a/kernel/register.cc b/kernel/register.cc index 85d3d4748..edf6ea7ba 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -880,54 +880,39 @@ struct HelpPass : public Pass { } fclose(f); } - void write_cell_rst(std::string cell, std::string help, std::string code) + void write_cell_rst(Yosys::SimHelper cell) { // open - string safe_name = cell.substr(1); - FILE *f = fopen(stringf("docs/source/cell/%s.rst", safe_name.c_str()).c_str(), "wt"); + FILE *f = fopen(stringf("docs/source/cell/%s.rst", cell.filesafe_name().c_str()).c_str(), "wt"); // make header - string short_help = ""; - string long_help = ""; - string title_line = cell; - for (auto line : split_tokens(help, "\n")) { - if (short_help == "") { - size_t first_pos = line.find_first_not_of(" \t"); - // skip empty lines - if (first_pos == string::npos) continue; - if (line.find(cell.c_str()) == string::npos) { - // strip leading/trailing space - size_t last_pos = line.find_last_not_of(" \t"); - short_help = line.substr(first_pos, last_pos - first_pos +1); - // skip missing help message - if (short_help == "No help message for this cell type found.") { - long_help += line; - long_help += "\n"; - } else { - title_line = stringf("%s - %s", cell.c_str(), short_help.c_str()); - } - } - } else { - long_help += line; - long_help += "\n"; - } - } + string title_line; + if (cell.short_desc.length()) + title_line = stringf("%s - %s", cell.name.c_str(), cell.short_desc.c_str()); + else title_line = cell.name; string underline = "\n"; underline.insert(0, title_line.length(), '='); fprintf(f, "%s\n", title_line.c_str()); fprintf(f, "%s\n", underline.c_str()); // help text - fprintf(f, "%s\n", long_help.c_str()); + fprintf(f, "%s\n", cell.desc.c_str()); // source code + fprintf(f, "Simulation model (Verilog)\n"); + fprintf(f, "--------------------------\n\n"); fprintf(f, ".. code:: verilog\n\n"); std::stringstream ss; - ss << code; + ss << cell.code; for (std::string line; std::getline(ss, line, '\n');) { - fprintf(f, "\t%s\n", line.c_str()); + fprintf(f, " %s\n", line.c_str()); } + // footer + fprintf(f, "\n.. note::\n\n"); + fprintf(f, " This page was auto-generated from the output of\n"); + fprintf(f, " ``help %s``.\n", cell.name.c_str()); + // close fclose(f); } @@ -988,7 +973,7 @@ struct HelpPass : public Pass { } else if (args[1] == "-write-rst-cells-manual") { for (auto &it : cell_help_messages.cell_help) { - write_cell_rst(it.first, it.second.desc, it.second.code); + write_cell_rst(it.second); } } else if (pass_register.count(args[1])) { From 784292626e9235ba52cc4946dd81e54a58ef5cec Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 11 Apr 2024 11:15:24 +1200 Subject: [PATCH 026/496] cellhelp: Rename short_desc to title --- kernel/register.cc | 8 ++++---- techlibs/common/cellhelp.py | 4 ++-- techlibs/common/simlib.v | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/kernel/register.cc b/kernel/register.cc index edf6ea7ba..fe3495dad 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -755,7 +755,7 @@ struct SimHelper { else return name; } - string short_desc; + string title; string ports; string desc; string code; @@ -887,8 +887,8 @@ struct HelpPass : public Pass { // make header string title_line; - if (cell.short_desc.length()) - title_line = stringf("%s - %s", cell.name.c_str(), cell.short_desc.c_str()); + if (cell.title.length()) + title_line = stringf("%s - %s", cell.name.c_str(), cell.title.c_str()); else title_line = cell.name; string underline = "\n"; underline.insert(0, title_line.length(), '='); @@ -988,7 +988,7 @@ struct HelpPass : public Pass { SimHelper help_cell = cell_help_messages.cell_help.at(args[1]); if (help_cell.ver == "2") { log("\n %s %s\n", help_cell.name.c_str(), help_cell.ports.c_str()); - log("\n%s\n", help_cell.short_desc.c_str()); + log("\n%s\n", help_cell.title.c_str()); log("%s\n", help_cell.desc.c_str()); log("Run 'help %s+' to display the Verilog model for this cell type.\n", args[1].c_str()); log("\n"); diff --git a/techlibs/common/cellhelp.py b/techlibs/common/cellhelp.py index 4d40b73c0..312446ad4 100644 --- a/techlibs/common/cellhelp.py +++ b/techlibs/common/cellhelp.py @@ -6,7 +6,7 @@ import json class SimHelper: name: str = "" - short_desc: str = "" + title: str = "" ports: str = "" desc: list[str] code: list[str] @@ -18,7 +18,7 @@ class SimHelper: def __str__(self) -> str: val = "tempCell = {\n" val += f' {json.dumps(self.name)},\n' - val += f' {json.dumps(self.short_desc)},\n' + val += f' {json.dumps(self.title)},\n' val += f' {json.dumps(self.ports)},\n' val += ' ' + json.dumps("\n".join(self.desc)) + ',\n' val += ' ' + json.dumps("\n".join(self.code)) + ',\n' diff --git a/techlibs/common/simlib.v b/techlibs/common/simlib.v index 71bb58c41..96f143c2a 100644 --- a/techlibs/common/simlib.v +++ b/techlibs/common/simlib.v @@ -622,7 +622,7 @@ endmodule // -------------------------------------------------------- //* ver 2 -//* short_desc Arithmetic logic unit +//* title Arithmetic logic unit //- A building block supporting both binary addition/subtraction operations, and //- indirectly, comparison operations. //- Typically created by the `alumacc` pass, which transforms: From a2b2904ed899f22aae91c9dc033a692622e72fd7 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 12 Apr 2024 13:57:51 +1200 Subject: [PATCH 027/496] cellhelp: Add source line to help Include Source file and line number in SimHelper struct, and use it for verilog code caption in rst dump. Also reformat python string conversion to iterate over a list of fields instead of repeating code for each. --- kernel/register.cc | 4 +++- techlibs/common/cellhelp.py | 21 +++++++++++++++------ 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/kernel/register.cc b/kernel/register.cc index fe3495dad..99225ba51 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -757,6 +757,7 @@ struct SimHelper { } string title; string ports; + string source; string desc; string code; string ver; @@ -901,7 +902,8 @@ struct HelpPass : public Pass { // source code fprintf(f, "Simulation model (Verilog)\n"); fprintf(f, "--------------------------\n\n"); - fprintf(f, ".. code:: verilog\n\n"); + fprintf(f, ".. code-block:: verilog\n"); + fprintf(f, " :caption: %s\n\n", cell.source.c_str()); std::stringstream ss; ss << cell.code; for (std::string line; std::getline(ss, line, '\n');) { diff --git a/techlibs/common/cellhelp.py b/techlibs/common/cellhelp.py index 312446ad4..1d55d17f5 100644 --- a/techlibs/common/cellhelp.py +++ b/techlibs/common/cellhelp.py @@ -3,11 +3,13 @@ from __future__ import annotations import fileinput import json +from pathlib import Path class SimHelper: name: str = "" title: str = "" ports: str = "" + source: str = "" desc: list[str] code: list[str] ver: str = "1" @@ -16,14 +18,19 @@ class SimHelper: self.desc = [] def __str__(self) -> str: + printed_fields = [ + "name", "title", "ports", "source", "desc", "code", "ver", + ] + # generate C++ struct val = "tempCell = {\n" - val += f' {json.dumps(self.name)},\n' - val += f' {json.dumps(self.title)},\n' - val += f' {json.dumps(self.ports)},\n' - val += ' ' + json.dumps("\n".join(self.desc)) + ',\n' - val += ' ' + json.dumps("\n".join(self.code)) + ',\n' - val += f' {json.dumps(self.ver)},\n' + for field in printed_fields: + field_val = getattr(self, field) + if isinstance(field_val, list): + field_val = "\n".join(field_val) + val += f' {json.dumps(field_val)},\n' val += "};\n" + + # map name to struct val += f'cell_help[{json.dumps(self.name)}] = tempCell;' val += "\n" val += f'cell_code[{json.dumps(self.name + "+")}] = tempCell;' @@ -45,6 +52,8 @@ for line in fileinput.input(): clean_line = line[7:].replace("\\", "").replace(";", "") simHelper.name, simHelper.ports = clean_line.split(maxsplit=1) simHelper.code = [] + short_filename = Path(fileinput.filename()).name + simHelper.source = f'{short_filename}:{fileinput.filelineno()}' elif not line.startswith("endmodule"): line = " " + line try: From 57cd8d29db5e0fb32aaa7b813617b91c5ab31792 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 12 Apr 2024 15:48:47 +1200 Subject: [PATCH 028/496] cellhelp: Add default format parse for simcells Since `simcells.v` uses consistent formatting we can handle it specifically to help tidy up sphinx warnings about the truth tables, and instead chuck them in a code block which when printing to rst. Also has the side effect that rst code blocks can be added manually with `//- ::` followed by a blank line. --- kernel/register.cc | 12 ++++++++---- techlibs/common/cellhelp.py | 23 +++++++++++++++++++++++ 2 files changed, 31 insertions(+), 4 deletions(-) diff --git a/kernel/register.cc b/kernel/register.cc index 99225ba51..383450525 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -988,10 +988,14 @@ struct HelpPass : public Pass { } else if (cell_help_messages.cell_help.count(args[1])) { SimHelper help_cell = cell_help_messages.cell_help.at(args[1]); - if (help_cell.ver == "2") { - log("\n %s %s\n", help_cell.name.c_str(), help_cell.ports.c_str()); - log("\n%s\n", help_cell.title.c_str()); - log("%s\n", help_cell.desc.c_str()); + if (help_cell.ver == "2" || help_cell.ver == "2a") { + log("\n %s %s\n\n", help_cell.name.c_str(), help_cell.ports.c_str()); + if (help_cell.title != "") log("%s\n", help_cell.title.c_str()); + std::stringstream ss; + ss << help_cell.desc; + for (std::string line; std::getline(ss, line, '\n');) { + if (line != "::") log("%s\n", line.c_str()); + } log("Run 'help %s+' to display the Verilog model for this cell type.\n", args[1].c_str()); log("\n"); } else { diff --git a/techlibs/common/cellhelp.py b/techlibs/common/cellhelp.py index 1d55d17f5..a975c31e5 100644 --- a/techlibs/common/cellhelp.py +++ b/techlibs/common/cellhelp.py @@ -36,6 +36,24 @@ class SimHelper: val += f'cell_code[{json.dumps(self.name + "+")}] = tempCell;' return val +def simcells_reparse(cell: SimHelper): + # cut manual signature + cell.desc = cell.desc[3:] + + # code-block truth table + new_desc = [] + indent = "" + for line in cell.desc: + if line.startswith("Truth table:"): + indent = " " + new_desc.pop() + new_desc.extend(["::", ""]) + new_desc.append(indent + line) + cell.desc = new_desc + + # set version + cell.ver = "2a" + simHelper = SimHelper() for line in fileinput.input(): @@ -62,7 +80,12 @@ for line in fileinput.input(): # no module definition, ignore line pass if line.startswith("endmodule"): + short_filename = Path(fileinput.filename()).name + if simHelper.ver == "1" and short_filename == "simcells.v": + # default simcells parsing + simcells_reparse(simHelper) if not simHelper.desc: + # no help simHelper.desc.append("No help message for this cell type found.\n") print(simHelper) simHelper = SimHelper() From 1a4ada40fe679a1cf309558f43200dc9af146220 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 15 Apr 2024 10:32:02 +1200 Subject: [PATCH 029/496] Docs: Add cell gen to makefile Generate in a temp directory and use `rsync -rc` to only update rst files that have changed. This prevents sphinx from having to re-generate every cmd/cell page any time the git sha changes. Also change cmd gen to match. --- Makefile | 13 +++++++++++-- docs/Makefile | 2 +- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 86e5064c9..eaf133ff7 100644 --- a/Makefile +++ b/Makefile @@ -981,8 +981,17 @@ endif # also others, but so long as it doesn't fail this is enough to know we tried docs/source/cmd/abc.rst: $(TARGETS) $(EXTRA_TARGETS) - mkdir -p docs/source/cmd - ./$(PROGRAM_PREFIX)yosys -p 'help -write-rst-command-reference-manual' + $(Q) mkdir -p docs/source/cmd + $(Q) mkdir -p temp/docs/source/cmd + $(Q) cd temp && ./../$(PROGRAM_PREFIX)yosys -p 'help -write-rst-command-reference-manual' + $(Q) rsync -rc temp/docs/source/cmd docs/source + $(Q) rm -rf temp +docs/source/cell/add.rst: $(TARGETS) $(EXTRA_TARGETS) + $(Q) mkdir -p docs/source/cell + $(Q) mkdir -p temp/docs/source/cell + $(Q) cd temp && ./../$(PROGRAM_PREFIX)yosys -p 'help -write-rst-cells-manual' + $(Q) rsync -rc temp/docs/source/cell docs/source + $(Q) rm -rf temp PHONY: docs/gen_examples docs/gen_images docs/guidelines docs/usage docs/reqs docs/gen_examples: $(TARGETS) diff --git a/docs/Makefile b/docs/Makefile index 6dbf6f490..9be050d35 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -47,7 +47,7 @@ help: .PHONY: clean clean: clean-examples rm -rf $(BUILDDIR)/* - rm -rf source/cmd util/__pycache__ + rm -rf source/cell source/cmd util/__pycache__ rm -rf source/generated $(MAKE) -C source/_images clean From d629aa6bf1de19c4e63802d2050c0828175bea2e Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 3 May 2024 09:16:55 +1200 Subject: [PATCH 030/496] cellhelp: Split gate-level and word-level cells --- Makefile | 4 ++-- docs/source/cell_gate.rst | 9 +++++++++ docs/source/cell_ref.rst | 9 +++++---- docs/source/cell_word.rst | 9 +++++++++ kernel/register.cc | 5 ++++- 5 files changed, 29 insertions(+), 7 deletions(-) create mode 100644 docs/source/cell_gate.rst create mode 100644 docs/source/cell_word.rst diff --git a/Makefile b/Makefile index eaf133ff7..87e62adb5 100644 --- a/Makefile +++ b/Makefile @@ -986,7 +986,7 @@ docs/source/cmd/abc.rst: $(TARGETS) $(EXTRA_TARGETS) $(Q) cd temp && ./../$(PROGRAM_PREFIX)yosys -p 'help -write-rst-command-reference-manual' $(Q) rsync -rc temp/docs/source/cmd docs/source $(Q) rm -rf temp -docs/source/cell/add.rst: $(TARGETS) $(EXTRA_TARGETS) +docs/source/cell/word_add.rst: $(TARGETS) $(EXTRA_TARGETS) $(Q) mkdir -p docs/source/cell $(Q) mkdir -p temp/docs/source/cell $(Q) cd temp && ./../$(PROGRAM_PREFIX)yosys -p 'help -write-rst-cells-manual' @@ -1034,7 +1034,7 @@ docs/reqs: $(Q) $(MAKE) -C docs reqs .PHONY: docs/prep -docs/prep: docs/source/cmd/abc.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage +docs/prep: docs/source/cmd/abc.rst docs/source/cell/word_add.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage DOC_TARGET ?= html docs: docs/prep diff --git a/docs/source/cell_gate.rst b/docs/source/cell_gate.rst new file mode 100644 index 000000000..74dd57bc7 --- /dev/null +++ b/docs/source/cell_gate.rst @@ -0,0 +1,9 @@ +Gate-level cells +---------------- + +.. toctree:: + :caption: Gate-level cells + :maxdepth: 1 + :glob: + + /cell/gate_* diff --git a/docs/source/cell_ref.rst b/docs/source/cell_ref.rst index ddf66812d..dc143124e 100644 --- a/docs/source/cell_ref.rst +++ b/docs/source/cell_ref.rst @@ -5,8 +5,9 @@ Internal cell reference ================================================================================ .. toctree:: - :caption: Internal cell reference - :maxdepth: 1 - :glob: + :caption: Internal cell reference + :maxdepth: 2 + :glob: - /cell/* + cell_word + cell_gate diff --git a/docs/source/cell_word.rst b/docs/source/cell_word.rst new file mode 100644 index 000000000..f7205e6ee --- /dev/null +++ b/docs/source/cell_word.rst @@ -0,0 +1,9 @@ +Word-level cells +---------------- + +.. toctree:: + :caption: Word-level cells + :maxdepth: 1 + :glob: + + /cell/word_* diff --git a/kernel/register.cc b/kernel/register.cc index 383450525..1d899b320 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -751,7 +751,10 @@ struct SimHelper { string name; inline string filesafe_name() { if (name.at(0) == '$') - return name.substr(1); + if (name.at(1) == '_') + return "gate" + name.substr(1); + else + return "word_" + name.substr(1); else return name; } From c98d13466284800723a40804db0e52dd197dc43c Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 3 May 2024 09:23:54 +1200 Subject: [PATCH 031/496] cellhelp: Extra newline Fix `$macc` page. --- kernel/register.cc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/kernel/register.cc b/kernel/register.cc index 1d899b320..4e54dcca3 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -900,7 +900,7 @@ struct HelpPass : public Pass { fprintf(f, "%s\n", underline.c_str()); // help text - fprintf(f, "%s\n", cell.desc.c_str()); + fprintf(f, "%s\n\n", cell.desc.c_str()); // source code fprintf(f, "Simulation model (Verilog)\n"); From f9b4e04fef158f52974b996dd64a55848e288aab Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 3 May 2024 11:45:17 +1200 Subject: [PATCH 032/496] Docs: Add cell reference Subclass the command reference code in order to support smart references to the internal cells. --- docs/util/cmdref.py | 81 ++++++++++++++++++++++++--------------------- kernel/register.cc | 21 ++++++++---- 2 files changed, 59 insertions(+), 43 deletions(-) diff --git a/docs/util/cmdref.py b/docs/util/cmdref.py index ec146e231..ce010471c 100644 --- a/docs/util/cmdref.py +++ b/docs/util/cmdref.py @@ -1,30 +1,5 @@ # based on https://github.com/ofosos/sphinxrecipes/blob/master/sphinxrecipes/sphinxrecipes.py -# license: -# Copyright 2019 Mark Meyer -# -# Permission is hereby granted, free of charge, to any person obtaining -# a copy of this software and associated documentation files (the -# "Software"), to deal in the Software without restriction, including -# without limitation the rights to use, copy, modify, merge, publish, -# distribute, sublicense, and/or sell copies of the Software, and to -# permit persons to whom the Software is furnished to do so, subject to -# the following conditions: -# -# The above copyright notice and this permission notice shall be -# included in all copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE -# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION -# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION -# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -import docutils -from docutils import nodes -import sphinx -from docutils.parsers import rst from docutils.parsers.rst import directives from sphinx.domains import Domain, Index from sphinx.domains.std import StandardDomain @@ -35,7 +10,8 @@ from sphinx import addnodes class CommandNode(ObjectDescription): """A custom node that describes a command.""" - + + name = 'cmd' required_arguments = 1 option_spec = { @@ -49,24 +25,29 @@ class CommandNode(ObjectDescription): return sig def add_target_and_index(self, name_cls, sig, signode): - signode['ids'].append('cmd' + '-' + sig) + signode['ids'].append(type(self).name + '-' + sig) if 'noindex' not in self.options: - name = "{}.{}.{}".format('cmd', type(self).__name__, sig) - tagmap = self.env.domaindata['cmd']['obj2tag'] + name = "{}.{}.{}".format(self.name, type(self).__name__, sig) + tagmap = self.env.domaindata[type(self).name]['obj2tag'] tagmap[name] = list(self.options.get('tags', '').split(' ')) title = self.options.get('title') - titlemap = self.env.domaindata['cmd']['obj2title'] + titlemap = self.env.domaindata[type(self).name]['obj2title'] titlemap[name] = title - objs = self.env.domaindata['cmd']['objects'] + objs = self.env.domaindata[type(self).name]['objects'] objs.append((name, sig, title, self.env.docname, - 'cmd' + '-' + sig, + type(self).name + '-' + sig, 0)) +class CellNode(CommandNode): + """A custom node that describes an internal cell.""" + + name = 'cell' + class TagIndex(Index): - """A custom directive that creates an tag matrix.""" + """A custom directive that creates a tag matrix.""" name = 'tag' localname = 'Tag Index' @@ -167,7 +148,7 @@ class CommandIndex(Index): in self.domain.get_objects()) items = sorted(items, key=lambda item: item[0]) for name, dispname, typ, docname, anchor in items: - lis = content.setdefault('Command', []) + lis = content.setdefault(self.shortname, []) lis.append(( dispname, 0, docname, anchor, @@ -177,10 +158,14 @@ class CommandIndex(Index): return (re, True) +class CellIndex(CommandIndex): + name = 'cell' + localname = 'Internal cell reference' + shortname = 'Internal cell' class CommandDomain(Domain): name = 'cmd' - label = 'Command Sample' + label = 'Yosys commands' roles = { 'ref': XRefRole() @@ -203,7 +188,7 @@ class CommandDomain(Domain): def get_full_qualified_name(self, node): """Return full qualified name for a given node""" - return "{}.{}.{}".format('cmd', + return "{}.{}.{}".format(type(self).name, type(node).__name__, node.arguments[0]) @@ -229,18 +214,40 @@ class CommandDomain(Domain): else: print(f"Missing ref for {target} in {fromdocname} ") return None + +class CellDomain(CommandDomain): + name = 'cell' + label = 'Yosys internal cells' + + directives = { + 'def': CellNode, + } + + indices = { + CellIndex, + TagIndex + } def setup(app): app.add_domain(CommandDomain) + app.add_domain(CellDomain) StandardDomain.initial_data['labels']['commandindex'] =\ ('cmd-cmd', '', 'Command Reference') StandardDomain.initial_data['labels']['tagindex'] =\ ('cmd-tag', '', 'Tag Index') + StandardDomain.initial_data['labels']['cellindex'] =\ + ('cell-cell', '', 'Internal cell reference') + StandardDomain.initial_data['labels']['tagindex'] =\ + ('cell-tag', '', 'Tag Index') StandardDomain.initial_data['anonlabels']['commandindex'] =\ ('cmd-cmd', '') StandardDomain.initial_data['anonlabels']['tagindex'] =\ ('cmd-tag', '') + StandardDomain.initial_data['anonlabels']['cellindex'] =\ + ('cell-cell', '') + StandardDomain.initial_data['anonlabels']['tagindex'] =\ + ('cell-tag', '') - return {'version': '0.1'} + return {'version': '0.2'} diff --git a/kernel/register.cc b/kernel/register.cc index 4e54dcca3..b16a6f852 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -899,17 +899,26 @@ struct HelpPass : public Pass { fprintf(f, "%s\n", title_line.c_str()); fprintf(f, "%s\n", underline.c_str()); - // help text - fprintf(f, "%s\n\n", cell.desc.c_str()); + // help text, with cell def for links + fprintf(f, ".. cell:def:: %s\n", cell.name.c_str()); + if (cell.title.length()) + fprintf(f, " :title: %s\n\n", cell.title.c_str()); + else + fprintf(f, " :title: %s\n\n", cell.name.c_str()); + std::stringstream ss; + ss << cell.desc; + for (std::string line; std::getline(ss, line, '\n');) { + fprintf(f, " %s\n", line.c_str()); + } // source code - fprintf(f, "Simulation model (Verilog)\n"); + fprintf(f, "\nSimulation model (Verilog)\n"); fprintf(f, "--------------------------\n\n"); fprintf(f, ".. code-block:: verilog\n"); fprintf(f, " :caption: %s\n\n", cell.source.c_str()); - std::stringstream ss; - ss << cell.code; - for (std::string line; std::getline(ss, line, '\n');) { + std::stringstream ss2; + ss2 << cell.code; + for (std::string line; std::getline(ss2, line, '\n');) { fprintf(f, " %s\n", line.c_str()); } From c0f9828b3c23745de26ec9749af0fd856ea06a66 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 3 May 2024 12:55:08 +1200 Subject: [PATCH 033/496] Docs: Add autoref role Use new `autoref` role when using single backticks. Allows automatic mapping to a cmd ref or a cell ref. --- docs/source/conf.py | 3 +++ docs/util/cmdref.py | 11 ++++++++++- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 8e30fcc7c..bfabe60e5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -41,6 +41,9 @@ html_static_path = ['_static', "_images"] pygments_style = 'colorful' highlight_language = 'none' +# default single quotes to attempt auto reference, or fallback to code +default_role = 'autoref' + extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex'] if os.getenv("READTHEDOCS"): diff --git a/docs/util/cmdref.py b/docs/util/cmdref.py index ce010471c..aac899388 100644 --- a/docs/util/cmdref.py +++ b/docs/util/cmdref.py @@ -1,6 +1,8 @@ # based on https://github.com/ofosos/sphinxrecipes/blob/master/sphinxrecipes/sphinxrecipes.py from docutils.parsers.rst import directives +from docutils.parsers.rst.states import Inliner +from sphinx.application import Sphinx from sphinx.domains import Domain, Index from sphinx.domains.std import StandardDomain from sphinx.roles import XRefRole @@ -228,7 +230,12 @@ class CellDomain(CommandDomain): TagIndex } -def setup(app): +def autoref(name, rawtext, text, lineno, inliner: Inliner, + options=None, content=None): + role = 'cell:ref' if text[0] == '$' else 'cmd:ref' + return inliner.interpreted(rawtext, text, role, lineno) + +def setup(app: Sphinx): app.add_domain(CommandDomain) app.add_domain(CellDomain) @@ -249,5 +256,7 @@ def setup(app): ('cell-cell', '') StandardDomain.initial_data['anonlabels']['tagindex'] =\ ('cell-tag', '') + + app.add_role('autoref', autoref) return {'version': '0.2'} From e4ec3717bcceed6e78e646f1afd4ca1e22840ead Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 3 May 2024 13:14:25 +1200 Subject: [PATCH 034/496] Docs: Update internal cells to autoref --- docs/source/getting_started/example_synth.rst | 64 +++--- .../getting_started/scripting_intro.rst | 15 +- .../interactive_investigation.rst | 4 +- .../using_yosys/more_scripting/selections.rst | 12 +- .../using_yosys/synthesis/cell_libs.rst | 4 +- docs/source/using_yosys/synthesis/fsm.rst | 18 +- docs/source/using_yosys/synthesis/memory.rst | 10 +- docs/source/using_yosys/synthesis/opt.rst | 30 +-- .../yosys_internals/flow/verilog_frontend.rst | 4 +- .../yosys_internals/formats/cell_library.rst | 183 +++++++++--------- .../yosys_internals/formats/rtlil_rep.rst | 16 +- docs/source/yosys_internals/techmap.rst | 2 +- 12 files changed, 183 insertions(+), 179 deletions(-) diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst index ae0a9a366..28e74ecc0 100644 --- a/docs/source/getting_started/example_synth.rst +++ b/docs/source/getting_started/example_synth.rst @@ -129,7 +129,7 @@ Our ``addr_gen`` circuit now looks like this: Simple operations like ``addr + 1`` and ``addr == MAX_DATA-1`` can be extracted from our ``always @`` block in :ref:`addr_gen-v`. This gives us the highlighted -``$add`` and ``$eq`` cells we see. But control logic (like the ``if .. else``) +`$add` and `$eq` cells we see. But control logic (like the ``if .. else``) and memory elements (like the ``addr <= 0``) are not so straightforward. These get put into "processes", shown in the schematic as ``PROC``. Note how the second line refers to the line numbers of the start/end of the corresponding @@ -151,8 +151,8 @@ automatic optimizations which would normally happen. ``addr_gen`` module after :yoscrypt:`proc -noopt` There are now a few new cells from our ``always @``, which have been -highlighted. The ``if`` statements are now modeled with ``$mux`` cells, while -the register uses an ``$adff`` cell. If we look at the terminal output we can +highlighted. The ``if`` statements are now modeled with `$mux` cells, while +the register uses an `$adff` cell. If we look at the terminal output we can also see all of the different ``proc_*`` commands being called. We will look at each of these in more detail in :doc:`/using_yosys/synthesis/proc`. @@ -171,7 +171,7 @@ clean`. ``addr_gen`` module after :yoscrypt:`opt_expr; clean` -You may also notice that the highlighted ``$eq`` cell input of ``255`` has +You may also notice that the highlighted `$eq` cell input of ``255`` has changed to ``8'11111111``. Constant values are presented in the format ``'``, with 32-bit values instead using the decimal number. This indicates that the constant input has been reduced from 32-bit wide to @@ -218,7 +218,7 @@ could restart our shell session, but instead let's use two new commands: :end-before: yosys> proc :caption: reloading :file:`fifo.v` and running :yoscrypt:`hierarchy -check -top fifo` -Notice how this time we didn't see any of those `$abstract` modules? That's +Notice how this time we didn't see any of those ``$abstract`` modules? That's because when we ran ``yosys fifo.v``, the first command Yosys called was :yoscrypt:`read_verilog -defer fifo.v`. The ``-defer`` option there tells :cmd:ref:`read_verilog` only read the abstract syntax tree and defer actual @@ -263,10 +263,10 @@ The highlighted ``fifo_reader`` block contains an instance of the instance of the ``addr_gen`` module with the ``MAX_DATA`` parameter set to the given value. -The other highlighted block is a ``$memrd`` cell. At this stage of synthesis we +The other highlighted block is a `$memrd` cell. At this stage of synthesis we don't yet know what type of memory is going to be implemented, but we *do* know that ``rdata <= data[raddr];`` could be implemented as a read from memory. Note -that the ``$memrd`` cell here is asynchronous, with both the clock and enable +that the `$memrd` cell here is asynchronous, with both the clock and enable signal undefined; shown with the ``1'x`` inputs. .. seealso:: Advanced usage docs for @@ -309,7 +309,7 @@ optimizations between modules which would otherwise be missed. Let's run The pieces have moved around a bit, but we can see :ref:`addr_gen_proc` from earlier has replaced the ``fifo_reader`` block in :ref:`rdata_proc`. We can also see that the ``addr`` output has been renamed to :file:`fifo_reader.addr` -and merged with the ``raddr`` wire feeding into the ``$memrd`` cell. This wire +and merged with the ``raddr`` wire feeding into the `$memrd` cell. This wire merging happened during the call to :cmd:ref:`clean` which we can see in the :ref:`flat_clean`. @@ -375,8 +375,8 @@ which are explored in more detail in :doc:`/using_yosys/synthesis/opt` and Up until now, the data path for ``rdata`` has remained the same since :ref:`rdata_flat`. However the next call to :cmd:ref:`opt` does cause a change. Specifically, the call to :cmd:ref:`opt_dff` without the ``-nodffe -nosdff`` -options is able to fold one of the ``$mux`` cells into the ``$adff`` to form an -``$adffe`` cell; highlighted below: +options is able to fold one of the `$mux` cells into the `$adff` to form an +`$adffe` cell; highlighted below: .. literalinclude:: /code_examples/fifo/fifo.out :language: doscon @@ -418,7 +418,7 @@ First up is :doc:`/cmd/wreduce`. If we run this we get the following: Looking at the data path for ``rdata``, the most relevant of these width reductions are the ones affecting ``fifo.$flatten\fifo_reader.$add$fifo.v``. -That is the ``$add`` cell incrementing the fifo_reader address. We can look at +That is the `$add` cell incrementing the fifo_reader address. We can look at the schematic and see the output of that cell has now changed. .. todo:: pending bugfix in :cmd:ref:`wreduce` and/or :cmd:ref:`opt_clean` @@ -451,8 +451,8 @@ Our next command to run is ``rdata`` output after :cmd:ref:`memory_dff` -As the title suggests, :cmd:ref:`memory_dff` has merged the output ``$dff`` into -the ``$memrd`` cell and converted it to a ``$memrd_v2`` (highlighted). This has +As the title suggests, :cmd:ref:`memory_dff` has merged the output `$dff` into +the `$memrd` cell and converted it to a `$memrd_v2` (highlighted). This has also connected the ``CLK`` port to the ``clk`` input as it is now a synchronous memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and ``SRST=1'0``) inputs. @@ -482,12 +482,12 @@ what they do. :name: synth_coarse3 :yoscrypt:`wreduce t:$mul` performs width reduction again, this time targetting -only cells of type ``$mul``. :yoscrypt:`techmap -map +/mul2dsp.v -map +only cells of type `$mul`. :yoscrypt:`techmap -map +/mul2dsp.v -map +/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses :cmd:ref:`techmap` to map -``$mul`` cells to ``$__MUL16X16`` which are, in turn, mapped to the iCE40 +`$mul` cells to ``$__MUL16X16`` which are, in turn, mapped to the iCE40 ``SB_MAC16``. Any multipliers which aren't compatible with conversion to ``$__MUL16X16`` are relabelled to ``$__soft_mul`` before :cmd:ref:`chtype` -changes them back to ``$mul``. +changes them back to `$mul`. During the mul2dsp conversion, some of the intermediate signals are marked with the attribute ``mul2dsp``. By calling :yoscrypt:`select a:mul2dsp` we restrict @@ -522,8 +522,8 @@ That brings us to the fourth and final part for the iCE40 synthesis flow: :caption: ``coarse`` section (part 4) :name: synth_coarse4 -Where before each type of arithmetic operation had its own cell, e.g. ``$add``, -we now want to extract these into ``$alu`` and ``$macc`` cells which can help +Where before each type of arithmetic operation had its own cell, e.g. `$add`, +we now want to extract these into `$alu` and `$macc` cells which can help identify opportunities for reusing logic. We do this by running :cmd:ref:`alumacc`, which we can see produce the following changes in our example design: @@ -542,7 +542,7 @@ example design: Once these cells have been inserted, the call to :cmd:ref:`opt` can combine cells which are now identical but may have been missed due to e.g. the -difference between ``$add`` and ``$sub``. +difference between `$add` and `$sub`. The other new command in this part is :doc:`/cmd/memory`. :cmd:ref:`memory` is another macro command which we examine in more detail in @@ -559,7 +559,7 @@ combines all of the reads and writes for a memory block into a single cell. ``rdata`` output after :cmd:ref:`memory_collect` Looking at the schematic after running :cmd:ref:`memory_collect` we see that our -``$memrd_v2`` cell has been replaced with a ``$mem_v2`` cell named ``data``, the +`$memrd_v2` cell has been replaced with a `$mem_v2` cell named ``data``, the same name that we used in :ref:`fifo-v`. Where before we had a single set of signals for address and enable, we now have one set for reading (``RD_*``) and one for writing (``WR_*``), as well as both ``WR_DATA`` input and ``RD_DATA`` @@ -609,10 +609,10 @@ Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap` and ``rdata`` output after :ref:`map_ram` -The :ref:`map_ram` converts the generic ``$mem_v2`` into the iCE40 +The :ref:`map_ram` converts the generic `$mem_v2` into the iCE40 ``SB_RAM40_4K`` (highlighted). We can also see the memory address has been remapped, and the data bits have been reordered (or swizzled). There is also -now a ``$mux`` cell controlling the value of ``rdata``. In :ref:`fifo-v` we +now a `$mux` cell controlling the value of ``rdata``. In :ref:`fifo-v` we wrote our memory as read-before-write, however the ``SB_RAM40_4K`` has undefined behaviour when reading from and writing to the same address in the same cycle. As a result, extra logic is added so that the generated circuit matches the @@ -655,7 +655,7 @@ into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`. The visual clutter on the ``RDATA`` output port (highlighted) is an unfortunate side effect of :cmd:ref:`opt_clean` on the swizzled data bits. In - connecting the ``$mux`` input port directly to ``RDATA`` to reduce the number + connecting the `$mux` input port directly to ``RDATA`` to reduce the number of wires, the ``$techmap579\data.0.0.RDATA`` wire becomes more visually complex. @@ -668,10 +668,10 @@ Arithmetic ^^^^^^^^^^ Uses :cmd:ref:`techmap` to map basic arithmetic logic to hardware. This sees -somewhat of an explosion in cells as multi-bit ``$mux`` and ``$adffe`` are -replaced with single-bit ``$_MUX_`` and ``$_DFFE_PP0P_`` cells, while the -``$alu`` is replaced with primitive ``$_OR_`` and ``$_NOT_`` gates and a -``$lut`` cell. +somewhat of an explosion in cells as multi-bit :cell:ref:`$mux` and `$adffe` are +replaced with single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the +:cell:ref:`$alu` is replaced with primitive `$_OR_` and `$_NOT_` gates and a +`$lut` cell. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -695,12 +695,12 @@ Flip-flops Convert FFs to the types supported in hardware with :cmd:ref:`dfflegalize`, and then use :cmd:ref:`techmap` to map them. In our example, this converts the -``$_DFFE_PP0P_`` cells to ``SB_DFFER``. +`$_DFFE_PP0P_` cells to ``SB_DFFER``. We also run :cmd:ref:`simplemap` here to convert any remaining cells which could not be mapped to hardware into gate-level primitives. This includes optimizing -``$_MUX_`` cells where one of the inputs is a constant ``1'0``, replacing it -instead with an ``$_AND_`` cell. +`$_MUX_` cells where one of the inputs is a constant ``1'0``, replacing it +instead with an `$_AND_` cell. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -723,7 +723,7 @@ LUTs ^^^^ :cmd:ref:`abc` and :cmd:ref:`techmap` are used to map LUTs; converting primitive -cell types to use ``$lut`` and ``SB_CARRY`` cells. Note that the iCE40 flow +cell types to use `$lut` and ``SB_CARRY`` cells. Note that the iCE40 flow uses :cmd:ref:`abc9` rather than :cmd:ref:`abc`. For more on what these do, and what the difference between these two commands are, refer to :doc:`/using_yosys/synthesis/abc`. @@ -742,7 +742,7 @@ what the difference between these two commands are, refer to ``rdata`` output after :ref:`map_luts` -Finally we use :cmd:ref:`techmap` to map the generic ``$lut`` cells to iCE40 +Finally we use :cmd:ref:`techmap` to map the generic `$lut` cells to iCE40 ``SB_LUT4`` cells. .. literalinclude:: /cmd/synth_ice40.rst diff --git a/docs/source/getting_started/scripting_intro.rst b/docs/source/getting_started/scripting_intro.rst index a6b4cb6bb..1e2ebabff 100644 --- a/docs/source/getting_started/scripting_intro.rst +++ b/docs/source/getting_started/scripting_intro.rst @@ -99,7 +99,7 @@ signifies we are matching on the *cell type*, and the ``*`` means to match anything. For this (very simple) selection, we are trying to find all of the cells, regardless of their type. The active selection is now shown as ``[addr_gen]*``, indicating some sub-selection of the ``addr_gen`` module. This -gives us the ``$add`` and ``$eq`` cells, which we want to highlight for the +gives us the `$add` and `$eq` cells, which we want to highlight for the :ref:`addr_gen_hier` image. .. _select_new_cells: @@ -111,10 +111,11 @@ by referring to it as ``@new_cells``, which we will see later. Then we clear the selection so that the following commands can operate on the full design. While we split that out for this document, we could have done the same thing in a single line by calling :yoscrypt:`select -set new_cells addr_gen/t:*`. If we -know we only have the one module in our design, we can even skip the `addr_gen/` -part. Looking further down :ref:`the fifo.ys code ` we can see this -with :yoscrypt:`select -set new_cells t:$mux t:*dff`. We can also see in that -command that selections don't have to be limited to a single statement. +know we only have the one module in our design, we can even skip the +``addr_gen/`` part. Looking further down :ref:`the fifo.ys code ` we +can see this with :yoscrypt:`select -set new_cells t:$mux t:*dff`. We can also +see in that command that selections don't have to be limited to a single +statement. Many commands also support an optional ``[selection]`` argument which can be used to override the currently selected objects. We could, for example, call @@ -184,8 +185,8 @@ like when we called :yoscrypt:`select -module addr_gen` in :ref:`select_intro`. That last parameter doesn't have to be a module name, it can be any valid selection string. Remember when we :ref:`assigned a name to a selection` and called it ``new_cells``? We saw in the -:yoscrypt:`select -list` output that it contained two cells, an ``$add`` and an -``$eq``. We can call :cmd:ref:`show` on that selection just as easily: +:yoscrypt:`select -list` output that it contained two cells, an `$add` and an +`$eq`. We can call :cmd:ref:`show` on that selection just as easily: .. figure:: /_images/code_examples/fifo/new_cells_show.* :class: width-helper invert-helper diff --git a/docs/source/using_yosys/more_scripting/interactive_investigation.rst b/docs/source/using_yosys/more_scripting/interactive_investigation.rst index 03a1faefa..77d826376 100644 --- a/docs/source/using_yosys/more_scripting/interactive_investigation.rst +++ b/docs/source/using_yosys/more_scripting/interactive_investigation.rst @@ -81,7 +81,7 @@ internal representation of the decision-trees and synchronization events modelled in a Verilog ``always``-block. The label reads ``PROC`` followed by a unique identifier in the first line and contains the source code location of the original ``always``-block in the second line. Note how the multiplexer from the -``?:``-expression is represented as a ``$mux`` cell but the multiplexer from the +``?:``-expression is represented as a `$mux` cell but the multiplexer from the ``if``-statement is yet still hidden within the process. The :cmd:ref:`proc` command transforms the process from the first diagram into a @@ -117,7 +117,7 @@ leads us to the third diagram: Here we see that the :cmd:ref:`opt` command not only has removed the artifacts left behind by :cmd:ref:`proc`, but also determined correctly that it can remove -the first ``$mux`` cell without changing the behavior of the circuit. +the first `$mux` cell without changing the behavior of the circuit. Break-out boxes for signal vectors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/using_yosys/more_scripting/selections.rst b/docs/source/using_yosys/more_scripting/selections.rst index b00283474..9c76b20b7 100644 --- a/docs/source/using_yosys/more_scripting/selections.rst +++ b/docs/source/using_yosys/more_scripting/selections.rst @@ -105,7 +105,7 @@ The :cmd:ref:`select` command is actually much more powerful than it might seem at first glance. When it is called with multiple arguments, each argument is evaluated and pushed separately on a stack. After all arguments have been processed it simply creates the union of all elements on the stack. So -:yoscrypt:`select t:$add a:foo` will select all ``$add`` cells and all objects +:yoscrypt:`select t:$add a:foo` will select all `$add` cells and all objects with the ``foo`` attribute set: .. literalinclude:: /code_examples/selections/foobaraddsub.v @@ -126,7 +126,7 @@ ineffective way of selecting the interesting part of the design. Special arguments can be used to combine the elements on the stack. For example the ``%i`` arguments pops the last two elements from the stack, intersects them, and pushes the result back on the stack. So :yoscrypt:`select t:$add a:foo %i` will -select all ``$add`` cells that have the ``foo`` attribute set: +select all `$add` cells that have the ``foo`` attribute set: .. code-block:: :caption: Output for command ``select t:$add a:foo %i -list`` on :numref:`foobaraddsub` @@ -220,7 +220,7 @@ The following sequence of diagrams demonstrates this step-wise expansion: Output of :yoscrypt:`show prod %ci %ci %ci` on :numref:`sumprod` Notice the subtle difference between :yoscrypt:`show prod %ci` and -:yoscrypt:`show prod %ci %ci`. Both images show the ``$mul`` cell driven by +:yoscrypt:`show prod %ci %ci`. Both images show the `$mul` cell driven by some inputs ``$3_Y`` and ``c``. However it is not until the second image, having called ``%ci`` the second time, that :cmd:ref:`show` is able to distinguish between ``$3_Y`` being a wire and ``c`` being an input. We can see @@ -296,7 +296,7 @@ cones`_ from above, we can use :yoscrypt:`show y %ci2`: Output of :yoscrypt:`show y %ci2` -From this we would learn that ``y`` is driven by a ``$dff cell``, that ``y`` is +From this we would learn that ``y`` is driven by a `$dff` cell, that ``y`` is connected to the output port ``Q``, that the ``clk`` signal goes into the ``CLK`` input port of the cell, and that the data comes from an auto-generated wire into the input ``D`` of the flip-flop cell (indicated by the ``$`` at the @@ -313,7 +313,7 @@ inputs. To add a pattern we add a colon followed by the pattern to the ``%ci`` action. The pattern itself starts with ``-`` or ``+``, indicating if it is an include or exclude pattern, followed by an optional comma separated list of cell types, followed by an optional comma separated list of port names in square -brackets. In this case, we want to exclude the ``S`` port of the ``$mux`` cell +brackets. In this case, we want to exclude the ``S`` port of the `$mux` cell type with :yoscrypt:`show y %ci5:-$mux[S]`: .. figure:: /_images/code_examples/selections/memdemo_03.* @@ -334,7 +334,7 @@ multiplexer select inputs and flip-flop cells: Output of ``show y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff`` Or we could use :yoscrypt:`show y %ci*:-[CLK,S]:+$dff:+$mux` instead, following -the input cone all the way but only following ``$dff`` and ``$mux`` cells, and +the input cone all the way but only following `$dff` and `$mux` cells, and ignoring any ports named ``CLK`` or ``S``: .. TODO:: pending discussion on whether rule ordering is a bug or a feature diff --git a/docs/source/using_yosys/synthesis/cell_libs.rst b/docs/source/using_yosys/synthesis/cell_libs.rst index 4e800bdf2..58b6431a5 100644 --- a/docs/source/using_yosys/synthesis/cell_libs.rst +++ b/docs/source/using_yosys/synthesis/cell_libs.rst @@ -98,8 +98,8 @@ our internal cell library will be mapped to: :name: mycells-lib :caption: :file:`mycells.lib` -Recall that the Yosys built-in logic gate types are ``$_NOT_``, ``$_AND_``, -``$_OR_``, ``$_XOR_``, and ``$_MUX_`` with an assortment of dff memory types. +Recall that the Yosys built-in logic gate types are `$_NOT_`, `$_AND_`, +`$_OR_`, `$_XOR_`, and `$_MUX_` with an assortment of dff memory types. :ref:`mycells-lib` defines our target cells as ``BUF``, ``NOT``, ``NAND``, ``NOR``, and ``DFF``. Mapping between these is performed with the commands :cmd:ref:`dfflibmap` and :cmd:ref:`abc` as follows: diff --git a/docs/source/using_yosys/synthesis/fsm.rst b/docs/source/using_yosys/synthesis/fsm.rst index e1ed55133..3c5a80ad3 100644 --- a/docs/source/using_yosys/synthesis/fsm.rst +++ b/docs/source/using_yosys/synthesis/fsm.rst @@ -24,12 +24,12 @@ following description: - Does not already have the ``\fsm_encoding`` attribute. - Is not an output of the containing module. -- Is driven by single ``$dff`` or ``$adff`` cell. -- The ``\D``-Input of this ``$dff`` or ``$adff`` cell is driven by a +- Is driven by single `$dff` or `$adff` cell. +- The ``\D``-Input of this `$dff` or `$adff` cell is driven by a multiplexer tree that only has constants or the old state value on its leaves. - The state value is only used in the said multiplexer tree or by simple - relational cells that compare the state value to a constant (usually ``$eq`` + relational cells that compare the state value to a constant (usually `$eq` cells). This heuristic has proven to work very well. It is possible to overwrite it by @@ -64,9 +64,11 @@ information is determined: The state registers (and asynchronous reset state, if applicable) is simply determined by identifying the driver for the state signal. -From there the ``$mux-tree`` driving the state register inputs is recursively +.. todo:: Figure out what `$mux-tree` should actually be. + +From there the `$mux-tree` driving the state register inputs is recursively traversed. All select inputs are control signals and the leaves of the -``$mux-tree`` are the states. The algorithm fails if a non-constant leaf that is +`$mux-tree` are the states. The algorithm fails if a non-constant leaf that is not the state signal itself is found. The list of control outputs is initialized with the bits from the state signal. @@ -99,18 +101,18 @@ create a transition table. For each state: 6. If step 4 was successful: Emit transition -Finally a ``$fsm`` cell is created with the generated transition table and added +Finally a `$fsm` cell is created with the generated transition table and added to the module. This new cell is connected to the control signals and the old drivers for the control outputs are disconnected. FSM optimization ~~~~~~~~~~~~~~~~ -The :cmd:ref:`fsm_opt` pass performs basic optimizations on ``$fsm`` cells (not +The :cmd:ref:`fsm_opt` pass performs basic optimizations on `$fsm` cells (not including state recoding). The following optimizations are performed (in this order): -- Unused control outputs are removed from the ``$fsm`` cell. The attribute +- Unused control outputs are removed from the `$fsm` cell. The attribute ``\unused_bits`` (that is usually set by the :cmd:ref:`opt_clean` pass) is used to determine which control outputs are unused. diff --git a/docs/source/using_yosys/synthesis/memory.rst b/docs/source/using_yosys/synthesis/memory.rst index e95a64875..dcbde2ae6 100644 --- a/docs/source/using_yosys/synthesis/memory.rst +++ b/docs/source/using_yosys/synthesis/memory.rst @@ -75,7 +75,7 @@ For example: techmap -map my_memory_map.v memory_map -:cmd:ref:`memory_libmap` attempts to convert memory cells (``$mem_v2`` etc) into +:cmd:ref:`memory_libmap` attempts to convert memory cells (`$mem_v2` etc) into hardware supported memory using a provided library (:file:`my_memory_map.txt` in the example above). Where necessary, emulation logic is added to ensure functional equivalence before and after this conversion. :yoscrypt:`techmap -map @@ -171,10 +171,10 @@ In general, you can expect the automatic selection process to work roughly like This process can be overridden by attaching a ram_style attribute to the memory: -- `(* ram_style = "logic" *)` selects FF RAM -- `(* ram_style = "distributed" *)` selects LUT RAM -- `(* ram_style = "block" *)` selects block RAM -- `(* ram_style = "huge" *)` selects huge RAM +- ``(* ram_style = "logic" *)`` selects FF RAM +- ``(* ram_style = "distributed" *)`` selects LUT RAM +- ``(* ram_style = "block" *)`` selects block RAM +- ``(* ram_style = "huge" *)`` selects huge RAM It is an error if this override cannot be realized for the given target. diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst index 2a06aadd1..cd40f6999 100644 --- a/docs/source/using_yosys/synthesis/opt.rst +++ b/docs/source/using_yosys/synthesis/opt.rst @@ -31,7 +31,7 @@ described in :doc:`/yosys_internals/formats/cell_library`. This means a cell with all constant inputs is replaced with the constant value this cell drives. In some cases this pass can also optimize cells with some constant inputs. -.. table:: Const folding rules for ``$_AND_`` cells as used in :cmd:ref:`opt_expr`. +.. table:: Const folding rules for `$_AND_` cells as used in :cmd:ref:`opt_expr`. :name: tab:opt_expr_and :align: center @@ -54,7 +54,7 @@ In some cases this pass can also optimize cells with some constant inputs. ========= ========= =========== :numref:`Table %s ` shows the replacement rules used for -optimizing an ``$_AND_`` gate. The first three rules implement the obvious const +optimizing an `$_AND_` gate. The first three rules implement the obvious const folding rules. Note that 'any' might include dynamic values calculated by other parts of the circuit. The following three lines propagate undef (X) states. These are the only three cases in which it is allowed to propagate an undef @@ -66,18 +66,18 @@ substitutions are possible they are performed first, in the hope that the 'any' will change to an undef value or a 1 and therefore the output can be set to undef. -The last two lines simply replace an ``$_AND_`` gate with one constant-1 input +The last two lines simply replace an `$_AND_` gate with one constant-1 input with a buffer. Besides this basic const folding the :cmd:ref:`opt_expr` pass can replace 1-bit -wide ``$eq`` and ``$ne`` cells with buffers or not-gates if one input is +wide `$eq` and `$ne` cells with buffers or not-gates if one input is constant. Equality checks may also be reduced in size if there are redundant bits in the arguments (i.e. bits which are constant on both inputs). This can, for example, result in a 32-bit wide constant like ``255`` being reduced to the 8-bit value of ``8'11111111`` if the signal being compared is only 8-bit as in :ref:`addr_gen_clean` of :doc:`/getting_started/example_synth`. -The :cmd:ref:`opt_expr` pass is very conservative regarding optimizing ``$mux`` +The :cmd:ref:`opt_expr` pass is very conservative regarding optimizing `$mux` cells, as these cells are often used to model decision-trees and breaking these trees can interfere with other optimizations. @@ -100,7 +100,7 @@ identifies cells with identical inputs and replaces them with a single instance of the cell. The option ``-nomux`` can be used to disable resource sharing for multiplexer -cells (``$mux`` and ``$pmux``.) This can be useful as it prevents multiplexer +cells (`$mux` and `$pmux`.) This can be useful as it prevents multiplexer trees to be merged, which might prevent :cmd:ref:`opt_muxtree` to identify possible optimizations. @@ -141,16 +141,16 @@ Simplifying large MUXes and AND/OR gates - :cmd:ref:`opt_reduce` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is a simple optimization pass that identifies and consolidates identical -input bits to ``$reduce_and`` and ``$reduce_or`` cells. It also sorts the input -bits to ease identification of shareable ``$reduce_and`` and ``$reduce_or`` +input bits to `$reduce_and` and `$reduce_or` cells. It also sorts the input +bits to ease identification of shareable `$reduce_and` and `$reduce_or` cells in other passes. This pass also identifies and consolidates identical inputs to multiplexer -cells. In this case the new shared select bit is driven using a ``$reduce_or`` +cells. In this case the new shared select bit is driven using a `$reduce_or` cell that combines the original select bits. -Lastly this pass consolidates trees of ``$reduce_and`` cells and trees of -``$reduce_or`` cells to single large ``$reduce_and`` or ``$reduce_or`` cells. +Lastly this pass consolidates trees of `$reduce_and` cells and trees of +`$reduce_or` cells to single large `$reduce_and` or `$reduce_or` cells. These three simple optimizations are performed in a loop until a stable result is produced. @@ -160,7 +160,7 @@ Merging mutually exclusive cells with shared inputs - :cmd:ref:`opt_share` This pass identifies mutually exclusive cells of the same type that: a. share an input signal, and - b. drive the same ``$mux``, ``$_MUX_``, or ``$pmux`` multiplexing cell, + b. drive the same `$mux`, `$_MUX_`, or `$pmux` multiplexing cell, allowing the cell to be merged and the multiplexer to be moved from multiplexing its output to multiplexing the non-shared input signals. @@ -176,14 +176,14 @@ multiplexing its output to multiplexing the non-shared input signals. Before and after :cmd:ref:`opt_share` -When running :cmd:ref:`opt` in full, the original ``$mux`` (labeled ``$3``) is +When running :cmd:ref:`opt` in full, the original `$mux` (labeled ``$3``) is optimized away by :cmd:ref:`opt_expr`. Performing DFF optimizations - :cmd:ref:`opt_dff` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This pass identifies single-bit d-type flip-flops (``$_DFF_``, ``$dff``, and -``$adff`` cells) with a constant data input and replaces them with a constant +This pass identifies single-bit d-type flip-flops (`$_DFF_`, `$dff`, and +`$adff` cells) with a constant data input and replaces them with a constant driver. It can also merge clock enables and synchronous reset multiplexers, removing unused control inputs. diff --git a/docs/source/yosys_internals/flow/verilog_frontend.rst b/docs/source/yosys_internals/flow/verilog_frontend.rst index f2eaeae97..7c8c9d8fb 100644 --- a/docs/source/yosys_internals/flow/verilog_frontend.rst +++ b/docs/source/yosys_internals/flow/verilog_frontend.rst @@ -627,7 +627,7 @@ from a behavioural model to an RTL representation is performed by the asynchronous resets if necessary). - | :cmd:ref:`proc_dff` - | This pass replaces the ``RTLIL::MemWriteAction``\ s with ``$memwr`` cells. + | This pass replaces the ``RTLIL::MemWriteAction``\ s with `$memwr` cells. - | :cmd:ref:`proc_clean` | A final call to :cmd:ref:`proc_clean` removes the now empty @@ -646,7 +646,7 @@ to extend the actual Verilog frontend. .. todo:: Synthesizing Verilog arrays - Add some information on the generation of ``$memrd`` and ``$memwr`` cells and + Add some information on the generation of `$memrd` and `$memwr` cells and how they are processed in the memory pass. diff --git a/docs/source/yosys_internals/formats/cell_library.rst b/docs/source/yosys_internals/formats/cell_library.rst index 2e30ee25c..cd1496e11 100644 --- a/docs/source/yosys_internals/formats/cell_library.rst +++ b/docs/source/yosys_internals/formats/cell_library.rst @@ -73,15 +73,15 @@ also have the following parameters: :verilog:`Y = !A` $logic_not ================== ============ -For the unary cells that output a logical value (``$reduce_and``, -``$reduce_or``, ``$reduce_xor``, ``$reduce_xnor``, ``$reduce_bool``, -``$logic_not``), when the ``\Y_WIDTH`` parameter is greater than 1, the output +For the unary cells that output a logical value (`$reduce_and`, +`$reduce_or`, `$reduce_xor`, `$reduce_xnor`, `$reduce_bool`, +`$logic_not`), when the ``\Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and only the least significant bit varies. -Note that ``$reduce_or`` and ``$reduce_bool`` actually represent the same logic +Note that `$reduce_or` and `$reduce_bool` actually represent the same logic function. But the HDL frontends generate them in different situations. A -``$reduce_or`` cell is generated when the prefix ``|`` operator is being used. A -``$reduce_bool`` cell is generated when a bit vector is used as a condition in +`$reduce_or` cell is generated when the prefix ``|`` operator is being used. A +`$reduce_bool` cell is generated when a bit vector is used as a condition in an ``if``-statement or ``?:``-expression. Binary operators @@ -130,28 +130,28 @@ All binary RTL cells have two input ports ``\A`` and ``\B`` and one output port :verilog:`Y = A ** B` $pow ``N/A`` $modfloor ======================= ============= ======================= ========= -The ``$shl`` and ``$shr`` cells implement logical shifts, whereas the ``$sshl`` -and ``$sshr`` cells implement arithmetic shifts. The ``$shl`` and ``$sshl`` +The `$shl` and `$shr` cells implement logical shifts, whereas the `$sshl` +and `$sshr` cells implement arithmetic shifts. The `$shl` and `$sshl` cells implement the same operation. All four of these cells interpret the second operand as unsigned, and require ``\B_SIGNED`` to be zero. Two additional shift operator cells are available that do not directly -correspond to any operator in Verilog, ``$shift`` and ``$shiftx``. The -``$shift`` cell performs a right logical shift if the second operand is positive -(or unsigned), and a left logical shift if it is negative. The ``$shiftx`` cell -performs the same operation as the ``$shift`` cell, but the vacated bit +correspond to any operator in Verilog, `$shift` and `$shiftx`. The +`$shift` cell performs a right logical shift if the second operand is positive +(or unsigned), and a left logical shift if it is negative. The `$shiftx` cell +performs the same operation as the `$shift` cell, but the vacated bit positions are filled with undef (x) bits, and corresponds to the Verilog indexed part-select expression. -For the binary cells that output a logical value (``$logic_and``, ``$logic_or``, -``$eqx``, ``$nex``, ``$lt``, ``$le``, ``$eq``, ``$ne``, ``$ge``, ``$gt``), when +For the binary cells that output a logical value (`$logic_and`, `$logic_or`, +`$eqx`, `$nex`, `$lt`, `$le`, `$eq`, `$ne`, `$ge`, `$gt`), when the ``\Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and only the least significant bit varies. Division and modulo cells are available in two rounding modes. The original -``$div`` and ``$mod`` cells are based on truncating division, and correspond to -the semantics of the verilog ``/`` and ``%`` operators. The ``$divfloor`` and -``$modfloor`` cells represent flooring division and flooring modulo, the latter +`$div` and `$mod` cells are based on truncating division, and correspond to +the semantics of the verilog ``/`` and ``%`` operators. The `$divfloor` and +`$modfloor` cells represent flooring division and flooring modulo, the latter of which is also known as "remainder" in several languages. See :numref:`tab:CellLib_divmod` for a side-by-side comparison between the different semantics. @@ -180,14 +180,14 @@ Multiplexers are generated by the Verilog HDL frontend for ``?:``-expressions. Multiplexers are also generated by the proc pass to map the decision trees from RTLIL::Process objects to logic. -The simplest multiplexer cell type is ``$mux``. Cells of this type have a +The simplest multiplexer cell type is `$mux`. Cells of this type have a ``\WITDH`` parameter and data inputs ``\A`` and ``\B`` and a data output ``\Y``, all of the specified width. This cell also has a single bit control input ``\S``. If ``\S`` is 0 the value from the input ``\A`` is sent to the output, if -it is 1 the value from the ``\B`` input is sent to the output. So the ``$mux`` +it is 1 the value from the ``\B`` input is sent to the output. So the `$mux` cell implements the function :verilog:`Y = S ? B : A`. -The ``$pmux`` cell is used to multiplex between many inputs using a one-hot +The `$pmux` cell is used to multiplex between many inputs using a one-hot select signal. Cells of this type have a ``\WIDTH`` and a ``\S_WIDTH`` parameter and inputs ``\A``, ``\B``, and ``\S`` and an output ``\Y``. The ``\S`` input is ``\S_WIDTH`` bits wide. The ``\A`` input and the output are both ``\WIDTH`` bits @@ -199,24 +199,24 @@ from ``\S`` is set the output is undefined. Cells of this type are used to model "parallel cases" (defined by using the ``parallel_case`` attribute or detected by an optimization). -The ``$tribuf`` cell is used to implement tristate logic. Cells of this type +The `$tribuf` cell is used to implement tristate logic. Cells of this type have a ``\WIDTH`` parameter and inputs ``\A`` and ``\EN`` and an output ``\Y``. The ``\A`` input and ``\Y`` output are ``\WIDTH`` bits wide, and the ``\EN`` input is one bit wide. When ``\EN`` is 0, the output is not driven. When ``\EN`` is 1, the value from ``\A`` input is sent to the ``\Y`` output. Therefore, the -``$tribuf`` cell implements the function :verilog:`Y = EN ? A : 'bz`. +`$tribuf` cell implements the function :verilog:`Y = EN ? A : 'bz`. Behavioural code with cascaded if-then-else- and case-statements usually results in trees of multiplexer cells. Many passes (from various optimizations to FSM extraction) heavily depend on these multiplexer trees to understand dependencies between signals. Therefore optimizations should not break these multiplexer trees (e.g. by replacing a multiplexer between a calculated signal and a -constant zero with an ``$and`` gate). +constant zero with an `$and` gate). Registers ~~~~~~~~~ -SR-type latches are represented by ``$sr`` cells. These cells have input ports +SR-type latches are represented by `$sr` cells. These cells have input ports ``\SET`` and ``\CLR`` and an output port ``\Q``. They have the following parameters: @@ -232,12 +232,12 @@ parameters: ``1'b1`` and active-low if this parameter is ``1'b0``. Both set and reset inputs have separate bits for every output bit. When both the -set and reset inputs of an ``$sr`` cell are active for a given bit index, the +set and reset inputs of an `$sr` cell are active for a given bit index, the reset input takes precedence. -D-type flip-flops are represented by ``$dff`` cells. These cells have a clock +D-type flip-flops are represented by `$dff` cells. These cells have a clock port ``\CLK``, an input port ``\D`` and an output port ``\Q``. The following -parameters are available for ``$dff`` cells: +parameters are available for `$dff` cells: ``\WIDTH`` The width of input ``\D`` and output ``\Q``. @@ -246,8 +246,8 @@ parameters are available for ``$dff`` cells: Clock is active on the positive edge if this parameter has the value ``1'b1`` and on the negative edge if this parameter is ``1'b0``. -D-type flip-flops with asynchronous reset are represented by ``$adff`` cells. As -the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they +D-type flip-flops with asynchronous reset are represented by `$adff` cells. As +the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they also have a single-bit ``\ARST`` input port for the reset pin and the following additional two parameters: @@ -261,8 +261,8 @@ additional two parameters: Usually these cells are generated by the :cmd:ref:`proc` pass using the information in the designs RTLIL::Process objects. -D-type flip-flops with synchronous reset are represented by ``$sdff`` cells. As -the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they +D-type flip-flops with synchronous reset are represented by `$sdff` cells. As +the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they also have a single-bit ``\SRST`` input port for the reset pin and the following additional two parameters: @@ -273,11 +273,11 @@ additional two parameters: ``\SRST_VALUE`` The state of ``\Q`` will be set to this value when the reset is active. -Note that the ``$adff`` and ``$sdff`` cells can only be used when the reset +Note that the `$adff` and `$sdff` cells can only be used when the reset value is constant. -D-type flip-flops with asynchronous load are represented by ``$aldff`` cells. As -the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they +D-type flip-flops with asynchronous load are represented by `$aldff` cells. As +the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they also have a single-bit ``\ALOAD`` input port for the async load enable pin, a ``\AD`` input port with the same width as data for the async load data, and the following additional parameter: @@ -286,15 +286,15 @@ following additional parameter: The asynchronous load is active-high if this parameter has the value ``1'b1`` and active-low if this parameter is ``1'b0``. -D-type flip-flops with asynchronous set and reset are represented by ``$dffsr`` -cells. As the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In +D-type flip-flops with asynchronous set and reset are represented by `$dffsr` +cells. As the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they also have multi-bit ``\SET`` and ``\CLR`` input ports and the -corresponding polarity parameters, like ``$sr`` cells. +corresponding polarity parameters, like `$sr` cells. -D-type flip-flops with enable are represented by ``$dffe``, ``$adffe``, -``$aldffe``, ``$dffsre``, ``$sdffe``, and ``$sdffce`` cells, which are enhanced -variants of ``$dff``, ``$adff``, ``$aldff``, ``$dffsr``, ``$sdff`` (with reset -over enable) and ``$sdff`` (with enable over reset) cells, respectively. They +D-type flip-flops with enable are represented by `$dffe`, `$adffe`, +`$aldffe`, `$dffsre`, `$sdffe`, and `$sdffce` cells, which are enhanced +variants of `$dff`, `$adff`, `$aldff`, `$dffsr`, `$sdff` (with reset +over enable) and `$sdff` (with enable over reset) cells, respectively. They have the same ports and parameters as their base cell. In addition they also have a single-bit ``\EN`` input port for the enable pin and the following parameter: @@ -303,9 +303,9 @@ parameter: The enable input is active-high if this parameter has the value ``1'b1`` and active-low if this parameter is ``1'b0``. -D-type latches are represented by ``$dlatch`` cells. These cells have an enable +D-type latches are represented by `$dlatch` cells. These cells have an enable port ``\EN``, an input port ``\D``, and an output port ``\Q``. The following -parameters are available for ``$dlatch`` cells: +parameters are available for `$dlatch` cells: ``\WIDTH`` The width of input ``\D`` and output ``\Q``. @@ -316,8 +316,8 @@ parameters are available for ``$dlatch`` cells: The latch is transparent when the ``\EN`` input is active. -D-type latches with reset are represented by ``$adlatch`` cells. In addition to -``$dlatch`` ports and parameters, they also have a single-bit ``\ARST`` input +D-type latches with reset are represented by `$adlatch` cells. In addition to +`$dlatch` ports and parameters, they also have a single-bit ``\ARST`` input port for the reset pin and the following additional parameters: ``\ARST_POLARITY`` @@ -327,9 +327,9 @@ port for the reset pin and the following additional parameters: ``\ARST_VALUE`` The state of ``\Q`` will be set to this value when the reset is active. -D-type latches with set and reset are represented by ``$dlatchsr`` cells. In -addition to ``$dlatch`` ports and parameters, they also have multi-bit ``\SET`` -and ``\CLR`` input ports and the corresponding polarity parameters, like ``$sr`` +D-type latches with set and reset are represented by `$dlatchsr` cells. In +addition to `$dlatch` ports and parameters, they also have multi-bit ``\SET`` +and ``\CLR`` input ports and the corresponding polarity parameters, like `$sr` cells. .. _sec:memcells: @@ -337,20 +337,20 @@ cells. Memories ~~~~~~~~ -Memories are either represented using ``RTLIL::Memory`` objects, ``$memrd_v2``, -``$memwr_v2``, and ``$meminit_v2`` cells, or by ``$mem_v2`` cells alone. +Memories are either represented using ``RTLIL::Memory`` objects, `$memrd_v2`, +`$memwr_v2`, and `$meminit_v2` cells, or by `$mem_v2` cells alone. In the first alternative the ``RTLIL::Memory`` objects hold the general metadata for the memory (bit width, size in number of words, etc.) and for each port a -``$memrd_v2`` (read port) or ``$memwr_v2`` (write port) cell is created. Having +`$memrd_v2` (read port) or `$memwr_v2` (write port) cell is created. Having individual cells for read and write ports has the advantage that they can be consolidated using resource sharing passes. In some cases this drastically reduces the number of required ports on the memory cell. In this alternative, -memory initialization data is represented by ``$meminit_v2`` cells, which allow +memory initialization data is represented by `$meminit_v2` cells, which allow delaying constant folding for initialization addresses and data until after the frontend finishes. -The ``$memrd_v2`` cells have a clock input ``\CLK``, an enable input ``\EN``, an +The `$memrd_v2` cells have a clock input ``\CLK``, an enable input ``\EN``, an address input ``\ADDR``, a data output ``\DATA``, an asynchronous reset input ``\ARST``, and a synchronous reset input ``\SRST``. They also have the following parameters: @@ -411,7 +411,7 @@ parameters: when ``\EN`` is true. Otherwise, ``\SRST`` is recognized regardless of ``\EN``. -The ``$memwr_v2`` cells have a clock input ``\CLK``, an enable input ``\EN`` +The `$memwr_v2` cells have a clock input ``\CLK``, an enable input ``\EN`` (one enable bit for each data bit), an address input ``\ADDR`` and a data input ``\DATA``. They also have the following parameters: @@ -424,7 +424,7 @@ The ``$memwr_v2`` cells have a clock input ``\CLK``, an enable input ``\EN`` ``\WIDTH`` The number of data bits (width of the ``\DATA`` output port). Like with - ``$memrd_v2`` cells, the width is allowed to be any power-of-two + `$memrd_v2` cells, the width is allowed to be any power-of-two multiple of memory width, with the corresponding restriction on address. ``\CLK_ENABLE`` @@ -448,7 +448,7 @@ The ``$memwr_v2`` cells have a clock input ``\CLK``, an enable input ``\EN`` undefined. Priority can only be set between two synchronous ports sharing the same clock domain. -The ``$meminit_v2`` cells have an address input ``\ADDR``, a data input +The `$meminit_v2` cells have an address input ``\ADDR``, a data input ``\DATA``, with the width of the ``\DATA`` port equal to ``\WIDTH`` parameter times ``\WORDS`` parameter, and a bit enable mask input ``\EN`` with width equal to ``\WIDTH`` parameter. All three of the inputs must resolve to a constant for @@ -472,19 +472,19 @@ synthesis to succeed. initialization conflict. The HDL frontend models a memory using ``RTLIL::Memory`` objects and -asynchronous ``$memrd_v2`` and ``$memwr_v2`` cells. The :cmd:ref:`memory` pass -(i.e. its various sub-passes) migrates ``$dff`` cells into the ``$memrd_v2`` and -``$memwr_v2`` cells making them synchronous, then converts them to a single -``$mem_v2`` cell and (optionally) maps this cell type to ``$dff`` cells for the +asynchronous `$memrd_v2` and `$memwr_v2` cells. The :cmd:ref:`memory` pass +(i.e. its various sub-passes) migrates `$dff` cells into the `$memrd_v2` and +`$memwr_v2` cells making them synchronous, then converts them to a single +`$mem_v2` cell and (optionally) maps this cell type to `$dff` cells for the individual words and multiplexer-based address decoders for the read and write -interfaces. When the last step is disabled or not possible, a ``$mem_v2`` cell +interfaces. When the last step is disabled or not possible, a `$mem_v2` cell is left in the design. -The ``$mem_v2`` cell provides the following parameters: +The `$mem_v2` cell provides the following parameters: ``\MEMID`` The name of the original ``RTLIL::Memory`` object that became this - ``$mem_v2`` cell. + `$mem_v2` cell. ``\SIZE`` The number of words in the memory. @@ -519,12 +519,12 @@ The ``$mem_v2`` cell provides the following parameters: ``\RD_TRANSPARENCY_MASK`` This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a concatenation of all ``\TRANSPARENCY_MASK`` values of the original - ``$memrd_v2`` cells. + `$memrd_v2` cells. ``\RD_COLLISION_X_MASK`` This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a concatenation of all ``\COLLISION_X_MASK`` values of the original - ``$memrd_v2`` cells. + `$memrd_v2` cells. ``\RD_CE_OVER_SRST`` This parameter is ``\RD_PORTS`` bits wide, determining relative @@ -560,9 +560,9 @@ The ``$mem_v2`` cell provides the following parameters: ``\WR_PRIORITY_MASK`` This parameter is ``\WR_PORTS*\WR_PORTS`` bits wide, containing a concatenation of all ``\PRIORITY_MASK`` values of the original - ``$memwr_v2`` cells. + `$memwr_v2` cells. -The ``$mem_v2`` cell has the following ports: +The `$mem_v2` cell has the following ports: ``\RD_CLK`` This input is ``\RD_PORTS`` bits wide, containing all clock signals for @@ -605,24 +605,24 @@ The ``$mem_v2`` cell has the following ports: signals for the write ports. The :cmd:ref:`memory_collect` pass can be used to convert discrete -``$memrd_v2``, ``$memwr_v2``, and ``$meminit_v2`` cells belonging to the same -memory to a single ``$mem_v2`` cell, whereas the :cmd:ref:`memory_unpack` pass +`$memrd_v2`, `$memwr_v2`, and `$meminit_v2` cells belonging to the same +memory to a single `$mem_v2` cell, whereas the :cmd:ref:`memory_unpack` pass performs the inverse operation. The :cmd:ref:`memory_dff` pass can combine asynchronous memory ports that are fed by or feeding registers into synchronous memory ports. The :cmd:ref:`memory_bram` pass can be used to recognize -``$mem_v2`` cells that can be implemented with a block RAM resource on an FPGA. -The :cmd:ref:`memory_map` pass can be used to implement ``$mem_v2`` cells as +`$mem_v2` cells that can be implemented with a block RAM resource on an FPGA. +The :cmd:ref:`memory_map` pass can be used to implement `$mem_v2` cells as basic logic: word-wide DFFs and address decoders. Finite state machines ~~~~~~~~~~~~~~~~~~~~~ -Add a brief description of the ``$fsm`` cell type. +Add a brief description of the `$fsm` cell type. Coarse arithmetics ~~~~~~~~~~~~~~~~~~~~~ -The ``$macc`` cell type represents a generalized multiply and accumulate operation. The cell is purely combinational. It outputs the result of summing up a sequence of products and other injected summands. +The `$macc` cell type represents a generalized multiply and accumulate operation. The cell is purely combinational. It outputs the result of summing up a sequence of products and other injected summands. .. code-block:: @@ -708,21 +708,21 @@ in the ``\TABLE`` values. Specify rules ~~~~~~~~~~~~~ -Add information about ``$specify2``, ``$specify3``, and ``$specrule`` cells. +Add information about `$specify2`, `$specify3`, and `$specrule` cells. Formal verification cells ~~~~~~~~~~~~~~~~~~~~~~~~~ -Add information about ``$check``, ``$assert``, ``$assume``, ``$live``, ``$fair``, -``$cover``, ``$equiv``, ``$initstate``, ``$anyconst``, ``$anyseq``, -``$anyinit``, ``$allconst``, ``$allseq`` cells. +Add information about `$check`, `$assert`, `$assume`, `$live`, `$fair`, +`$cover`, `$equiv`, `$initstate`, `$anyconst`, `$anyseq`, +`$anyinit`, `$allconst`, `$allseq` cells. -Add information about ``$ff`` and ``$_FF_`` cells. +Add information about `$ff` and `$_FF_` cells. Debugging cells ~~~~~~~~~~~~~~~ -The ``$print`` cell is used to log the values of signals, akin to (and +The `$print` cell is used to log the values of signals, akin to (and translatable to) the ``$display`` and ``$write`` family of tasks in Verilog. It has the following parameters: @@ -746,13 +746,14 @@ If ``\TRG_ENABLE`` is true, the following parameters also apply: negative-edge triggered. ``\PRIORITY`` - When multiple ``$print`` or ``$$check`` cells fire on the same trigger, they\ + When multiple `$print` or `$check` cells fire on the same trigger, they execute in descending priority order. Ports: ``\TRG`` - The signals that control when this ``$print`` cell is triggered. + The signals that control when this `$print` cell is triggered. + If the width of this port is zero and ``\TRG_ENABLE`` is true, the cell is triggered during initial evaluation (time zero) only. @@ -1040,14 +1041,14 @@ Tables :numref:`%s `, :numref:`%s `, :numref:`%s `, :numref:`%s `, :numref:`%s `, :numref:`%s ` and :numref:`%s ` list all -cell types used for gate level logic. The cell types ``$_BUF_``, ``$_NOT_``, -``$_AND_``, ``$_NAND_``, ``$_ANDNOT_``, ``$_OR_``, ``$_NOR_``, ``$_ORNOT_``, -``$_XOR_``, ``$_XNOR_``, ``$_AOI3_``, ``$_OAI3_``, ``$_AOI4_``, ``$_OAI4_``, -``$_MUX_``, ``$_MUX4_``, ``$_MUX8_``, ``$_MUX16_`` and ``$_NMUX_`` are used to -model combinatorial logic. The cell type ``$_TBUF_`` is used to model tristate +cell types used for gate level logic. The cell types `$_BUF_`, `$_NOT_`, +`$_AND_`, `$_NAND_`, `$_ANDNOT_`, `$_OR_`, `$_NOR_`, `$_ORNOT_`, +`$_XOR_`, `$_XNOR_`, `$_AOI3_`, `$_OAI3_`, `$_AOI4_`, `$_OAI4_`, +`$_MUX_`, `$_MUX4_`, `$_MUX8_`, `$_MUX16_` and `$_NMUX_` are used to +model combinatorial logic. The cell type `$_TBUF_` is used to model tristate logic. -The ``$_MUX4_``, ``$_MUX8_`` and ``$_MUX16_`` cells are used to model wide +The `$_MUX4_`, `$_MUX8_` and `$_MUX16_` cells are used to model wide muxes, and correspond to the following Verilog code: .. code-block:: verilog @@ -1071,7 +1072,7 @@ muxes, and correspond to the following Verilog code: T ? (S ? D : C) : (S ? B : A); -The cell types ``$_DFF_N_`` and ``$_DFF_P_`` represent d-type flip-flops. +The cell types `$_DFF_N_` and `$_DFF_P_` represent d-type flip-flops. The cell types ``$_DFFE_[NP][NP]_`` implement d-type flip-flops with enable. The values in the table for these cell types relate to the following Verilog code @@ -1186,7 +1187,7 @@ is ``posedge`` if ``SET_LVL`` if ``1``, ``negedge`` otherwise. else if (E == EN_LVL) Q <= D; -The cell types ``$_DLATCH_N_`` and ``$_DLATCH_P_`` represent d-type latches. +The cell types `$_DLATCH_N_` and `$_DLATCH_P_` represent d-type latches. The cell types ``$_DLATCH_[NP][NP][01]_`` implement d-type latches with reset. The values in the table for these cell types relate to the following Verilog @@ -1234,8 +1235,8 @@ mapped to physical flip-flop cells from a Liberty file using the dfflibmap pass. The combinatorial logic cells can be mapped to physical cells from a Liberty file via ABC using the abc pass. -.. todo:: Add information about ``$slice`` and ``$concat`` cells. +.. todo:: Add information about `$slice` and `$concat` cells. -.. todo:: Add information about ``$alu``, ``$fa``, and ``$lcu`` cells. +.. todo:: Add information about `$alu`, `$fa`, and `$lcu` cells. .. todo:: Add information about ``$demux`` cell. \ No newline at end of file diff --git a/docs/source/yosys_internals/formats/rtlil_rep.rst b/docs/source/yosys_internals/formats/rtlil_rep.rst index 2737cd4bd..785a2d28b 100644 --- a/docs/source/yosys_internals/formats/rtlil_rep.rst +++ b/docs/source/yosys_internals/formats/rtlil_rep.rst @@ -79,7 +79,7 @@ This has three advantages: example, :cmd:ref:`opt_clean` tries to preserve signals with a user-provided name but doesn't hesitate to delete signals that have auto-generated names when they just duplicate other signals. Note that this can be overridden - with the `-purge` option to also delete internal nets with user-provided + with the ``-purge`` option to also delete internal nets with user-provided names. - Third, the delicate job of finding suitable auto-generated public visible @@ -366,7 +366,7 @@ multiplexer for the enable signal: end Different combinations of passes may yield different results. Note that -``$adff`` and ``$mux`` are internal cell types that still need to be mapped to +`$adff` and `$mux` are internal cell types that still need to be mapped to cell types from the target cell library. Some passes refuse to operate on modules that still contain ``RTLIL::Process`` @@ -389,25 +389,25 @@ A memory object has the following properties: - The width of an addressable word - The size of the memory in number of words -All read accesses to the memory are transformed to ``$memrd`` cells and all -write accesses to ``$memwr`` cells by the language frontend. These cells consist +All read accesses to the memory are transformed to `$memrd` cells and all +write accesses to `$memwr` cells by the language frontend. These cells consist of independent read- and write-ports to the memory. Memory initialization is -transformed to ``$meminit`` cells by the language frontend. The ``\MEMID`` +transformed to `$meminit` cells by the language frontend. The ``\MEMID`` parameter on these cells is used to link them together and to the ``RTLIL::Memory`` object they belong to. The rationale behind using separate cells for the individual ports versus creating a large multiport memory cell right in the language frontend is that -the separate ``$memrd`` and ``$memwr`` cells can be consolidated using resource +the separate `$memrd` and `$memwr` cells can be consolidated using resource sharing. As resource sharing is a non-trivial optimization problem where different synthesis tasks can have different requirements it lends itself to do the optimisation in separate passes and merge the ``RTLIL::Memory`` objects and -``$memrd`` and ``$memwr`` cells to multiport memory blocks after resource +`$memrd` and `$memwr` cells to multiport memory blocks after resource sharing is completed. The memory pass performs this conversion and can (depending on the options passed to it) transform the memories directly to d-type flip-flops and address -logic or yield multiport memory blocks (represented using ``$mem`` cells). +logic or yield multiport memory blocks (represented using `$mem` cells). See :ref:`sec:memcells` for details about the memory cell types. diff --git a/docs/source/yosys_internals/techmap.rst b/docs/source/yosys_internals/techmap.rst index 00fce26bd..e5d6972ee 100644 --- a/docs/source/yosys_internals/techmap.rst +++ b/docs/source/yosys_internals/techmap.rst @@ -3,7 +3,7 @@ Techmap by example As a quick recap, the :cmd:ref:`techmap` command replaces cells in the design with implementations given as Verilog code (called "map files"). It can replace -Yosys' internal cell types (such as ``$or``) as well as user-defined cell types. +Yosys' internal cell types (such as `$or`) as well as user-defined cell types. - Verilog parameters are used extensively to customize the internal cell types. - Additional special parameters are used by techmap to communicate meta-data to From 829e02ec5b2bcdfc5a6ee308c62836bfcea248f9 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 3 May 2024 13:16:48 +1200 Subject: [PATCH 035/496] Docs: Shorten cmd:ref --- docs/source/appendix/auxlibs.rst | 14 +- docs/source/appendix/env_vars.rst | 2 +- docs/source/getting_started/example_synth.rst | 162 +++++++++--------- docs/source/getting_started/installation.rst | 6 +- .../getting_started/scripting_intro.rst | 41 +++-- .../interactive_investigation.rst | 104 +++++------ .../more_scripting/model_checking.rst | 2 +- .../using_yosys/more_scripting/selections.rst | 30 ++-- docs/source/using_yosys/synthesis/abc.rst | 20 +-- .../using_yosys/synthesis/cell_libs.rst | 8 +- docs/source/using_yosys/synthesis/extract.rst | 20 +-- docs/source/using_yosys/synthesis/fsm.rst | 18 +- docs/source/using_yosys/synthesis/index.rst | 12 +- docs/source/using_yosys/synthesis/memory.rst | 24 +-- docs/source/using_yosys/synthesis/opt.rst | 66 +++---- docs/source/using_yosys/synthesis/proc.rst | 10 +- docs/source/using_yosys/synthesis/synth.rst | 2 +- .../extending_yosys/extensions.rst | 6 +- .../yosys_internals/flow/verilog_frontend.rst | 20 +-- .../yosys_internals/formats/cell_library.rst | 14 +- .../yosys_internals/formats/rtlil_rep.rst | 4 +- docs/source/yosys_internals/techmap.rst | 8 +- 22 files changed, 296 insertions(+), 297 deletions(-) diff --git a/docs/source/appendix/auxlibs.rst b/docs/source/appendix/auxlibs.rst index 321cb52c4..8c78ed6b3 100644 --- a/docs/source/appendix/auxlibs.rst +++ b/docs/source/appendix/auxlibs.rst @@ -29,7 +29,7 @@ ezSAT The files in ``libs/ezsat`` provide a library for simplifying generating CNF formulas for SAT solvers. It also contains bindings of MiniSAT. The ezSAT -library is written by C. Wolf. It is used by the :cmd:ref:`sat` pass (see +library is written by C. Wolf. It is used by the `sat` pass (see :doc:`/cmd/sat`). fst @@ -37,22 +37,22 @@ fst ``libfst`` files from `gtkwave`_ are included in ``libs/fst`` to support reading/writing signal traces from/to the GTKWave developed FST format. This is -primarily used in the :cmd:ref:`sim` command. +primarily used in the `sim` command. .. _gtkwave: https://github.com/gtkwave/gtkwave json11 ------ -For reading/writing designs from/to JSON, :cmd:ref:`read_json` and -:cmd:ref:`write_json` should be used. For everything else there is the `json11 +For reading/writing designs from/to JSON, `read_json` and +`write_json` should be used. For everything else there is the `json11 library`_: json11 is a tiny JSON library for C++11, providing JSON parsing and serialization. -This library is used for outputting machine-readable statistics (:cmd:ref:`stat` -with ``-json`` flag), using the RPC frontend (:cmd:ref:`connect_rpc`), and the +This library is used for outputting machine-readable statistics (`stat` +with ``-json`` flag), using the RPC frontend (`connect_rpc`), and the yosys-witness ``yw`` format. .. _json11 library: https://github.com/dropbox/json11 @@ -61,7 +61,7 @@ MiniSAT ------- The files in ``libs/minisat`` provide a high-performance SAT solver, used by the -:cmd:ref:`sat` command. +`sat` command. SHA1 ---- diff --git a/docs/source/appendix/env_vars.rst b/docs/source/appendix/env_vars.rst index 26cc37c81..69e86c922 100644 --- a/docs/source/appendix/env_vars.rst +++ b/docs/source/appendix/env_vars.rst @@ -3,7 +3,7 @@ Yosys environment variables ``HOME`` Yosys command history is stored in :file:`$HOME/.yosys_history`. Graphics - (from :cmd:ref:`show` and :cmd:ref:`viz` commands) will output to this + (from `show` and `viz` commands) will output to this directory by default. This environment variable is also used in some cases for resolving filenames with :file:`~`. diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst index 28e74ecc0..ec1f967ea 100644 --- a/docs/source/getting_started/example_synth.rst +++ b/docs/source/getting_started/example_synth.rst @@ -2,9 +2,9 @@ Synthesis starter ----------------- This page will be a guided walkthrough of the prepackaged iCE40 FPGA synthesis -script - :cmd:ref:`synth_ice40`. We will take a simple design through each +script - `synth_ice40`. We will take a simple design through each step, looking at the commands being called and what they do to the design. While -:cmd:ref:`synth_ice40` is specific to the iCE40 platform, most of the operations +`synth_ice40` is specific to the iCE40 platform, most of the operations we will be discussing are common across the majority of FPGA synthesis scripts. Thus, this document will provide a good foundational understanding of how synthesis in Yosys is performed, regardless of the actual architecture being @@ -59,8 +59,8 @@ can run each of the commands individually for a better sense of how each part contributes to the flow. We will also start with just a single module; ``addr_gen``. -At the bottom of the :cmd:ref:`help` output for -:cmd:ref:`synth_ice40` is the complete list of commands called by this script. +At the bottom of the `help` output for +`synth_ice40` is the complete list of commands called by this script. Let's start with the section labeled ``begin``: .. literalinclude:: /cmd/synth_ice40.rst @@ -105,8 +105,8 @@ Since we're just getting started, let's instead begin with :yoscrypt:`hierarchy .. note:: - :cmd:ref:`hierarchy` should always be the first command after the design has - been read. By specifying the top module, :cmd:ref:`hierarchy` will also set + `hierarchy` should always be the first command after the design has + been read. By specifying the top module, `hierarchy` will also set the ``(* top *)`` attribute on it. This is used by other commands that need to know which module is the top. @@ -125,7 +125,7 @@ Our ``addr_gen`` circuit now looks like this: :class: width-helper invert-helper :name: addr_gen_hier - ``addr_gen`` module after :cmd:ref:`hierarchy` + ``addr_gen`` module after `hierarchy` Simple operations like ``addr + 1`` and ``addr == MAX_DATA-1`` can be extracted from our ``always @`` block in :ref:`addr_gen-v`. This gives us the highlighted @@ -137,9 +137,9 @@ second line refers to the line numbers of the start/end of the corresponding ``PROC`` referring to line 0. To handle these, let us now introduce the next command: :doc:`/cmd/proc`. -:cmd:ref:`proc` is a macro command like :cmd:ref:`synth_ice40`. Rather than +`proc` is a macro command like `synth_ice40`. Rather than modifying the design directly, it instead calls a series of other commands. In -the case of :cmd:ref:`proc`, these sub-commands work to convert the behavioral +the case of `proc`, these sub-commands work to convert the behavioral logic of processes into multiplexers and registers. Let's see what happens when we run it. For now, we will call :yoscrypt:`proc -noopt` to prevent some automatic optimizations which would normally happen. @@ -160,8 +160,8 @@ Notice how in the top left of :ref:`addr_gen_proc` we have a floating wire, generated from the initial assignment of 0 to the ``addr`` wire. However, this initial assignment is not synthesizable, so this will need to be cleaned up before we can generate the physical hardware. We can do this now by calling -:cmd:ref:`clean`. We're also going to call :cmd:ref:`opt_expr` now, which would -normally be called at the end of :cmd:ref:`proc`. We can call both commands at +`clean`. We're also going to call `opt_expr` now, which would +normally be called at the end of `proc`. We can call both commands at the same time by separating them with a colon and space: :yoscrypt:`opt_expr; clean`. @@ -175,7 +175,7 @@ You may also notice that the highlighted `$eq` cell input of ``255`` has changed to ``8'11111111``. Constant values are presented in the format ``'``, with 32-bit values instead using the decimal number. This indicates that the constant input has been reduced from 32-bit wide to -8-bit wide. This is a side-effect of running :cmd:ref:`opt_expr`, which +8-bit wide. This is a side-effect of running `opt_expr`, which performs constant folding and simple expression rewriting. For more on why this happens, refer to :doc:`/using_yosys/synthesis/opt` and the :ref:`section on opt_expr `. @@ -185,7 +185,7 @@ on opt_expr `. :doc:`/cmd/clean` can also be called with two semicolons after any command, for example we could have called :yoscrypt:`opt_expr;;` instead of :yoscrypt:`opt_expr; clean`. You may notice some scripts will end each line - with ``;;``. It is beneficial to run :cmd:ref:`clean` before inspecting + with ``;;``. It is beneficial to run `clean` before inspecting intermediate products to remove disconnected parts of the circuit which have been left over, and in some cases can reduce the processing required in subsequent commands. @@ -202,7 +202,7 @@ The full example Let's now go back and check on our full design by using :yoscrypt:`hierarchy -check -top fifo`. By passing the ``-check`` option there we are also telling -the :cmd:ref:`hierarchy` command that if the design includes any non-blackbox +the `hierarchy` command that if the design includes any non-blackbox modules without an implementation it should return an error. Note that if we tried to run this command now then we would get an error. This @@ -221,15 +221,15 @@ could restart our shell session, but instead let's use two new commands: Notice how this time we didn't see any of those ``$abstract`` modules? That's because when we ran ``yosys fifo.v``, the first command Yosys called was :yoscrypt:`read_verilog -defer fifo.v`. The ``-defer`` option there tells -:cmd:ref:`read_verilog` only read the abstract syntax tree and defer actual -compilation to a later :cmd:ref:`hierarchy` command. This is useful in cases +`read_verilog` only read the abstract syntax tree and defer actual +compilation to a later `hierarchy` command. This is useful in cases where the default parameters of modules yield invalid code which is not synthesizable. This is why Yosys defers compilation automatically and is one of the reasons why hierarchy should always be the first command after loading the design. If we know that our design won't run into this issue, we can skip the ``-defer``. -.. todo:: :cmd:ref:`hierarchy` failure modes +.. todo:: `hierarchy` failure modes .. note:: @@ -243,19 +243,19 @@ design. If we know that our design won't run into this issue, we can skip the interactive terminal. :kbd:`ctrl+c` (i.e. SIGINT) will also end the terminal session but will return an error code rather than exiting gracefully. -We can also run :cmd:ref:`proc` now to finish off the full :ref:`synth_begin`. +We can also run `proc` now to finish off the full :ref:`synth_begin`. Because the design schematic is quite large, we will be showing just the data path for the ``rdata`` output. If you would like to see the entire design for -yourself, you can do so with :doc:`/cmd/show`. Note that the :cmd:ref:`show` +yourself, you can do so with :doc:`/cmd/show`. Note that the `show` command only works with a single module, so you may need to call it with :yoscrypt:`show fifo`. :ref:`show_intro` section in -:doc:`/getting_started/scripting_intro` has more on how to use :cmd:ref:`show`. +:doc:`/getting_started/scripting_intro` has more on how to use `show`. .. figure:: /_images/code_examples/fifo/rdata_proc.* :class: width-helper invert-helper :name: rdata_proc - ``rdata`` output after :cmd:ref:`proc` + ``rdata`` output after `proc` The highlighted ``fifo_reader`` block contains an instance of the :ref:`addr_gen_proc` that we looked at earlier. Notice how the type is shown as @@ -276,7 +276,7 @@ Flattening ~~~~~~~~~~ At this stage of a synthesis flow there are a few other commands we could run. -In :cmd:ref:`synth_ice40` we get these: +In `synth_ice40` we get these: .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -286,7 +286,7 @@ In :cmd:ref:`synth_ice40` we get these: :name: synth_flatten :caption: ``flatten`` section -First off is :cmd:ref:`flatten`. Flattening the design like this can allow for +First off is `flatten`. Flattening the design like this can allow for optimizations between modules which would otherwise be missed. Let's run :yoscrypt:`flatten;;` on our design. @@ -310,19 +310,19 @@ The pieces have moved around a bit, but we can see :ref:`addr_gen_proc` from earlier has replaced the ``fifo_reader`` block in :ref:`rdata_proc`. We can also see that the ``addr`` output has been renamed to :file:`fifo_reader.addr` and merged with the ``raddr`` wire feeding into the `$memrd` cell. This wire -merging happened during the call to :cmd:ref:`clean` which we can see in the +merging happened during the call to `clean` which we can see in the :ref:`flat_clean`. .. note:: - :cmd:ref:`flatten` and :cmd:ref:`clean` would normally be combined into a + `flatten` and `clean` would normally be combined into a single :yoterm:`yosys> flatten;;` output, but they appear separately here as - a side effect of using :cmd:ref:`echo` for generating the terminal style + a side effect of using `echo` for generating the terminal style output. Depending on the target architecture, this stage of synthesis might also see -commands such as :cmd:ref:`tribuf` with the ``-logic`` option and -:cmd:ref:`deminout`. These remove tristate and inout constructs respectively, +commands such as `tribuf` with the ``-logic`` option and +`deminout`. These remove tristate and inout constructs respectively, replacing them with logic suitable for mapping to an FPGA. Since we do not have any such constructs in our example running these commands does not change our design. @@ -342,7 +342,7 @@ optimizations and other transformations done previously. .. note:: - While the iCE40 flow had a :ref:`synth_flatten` and put :cmd:ref:`proc` in + While the iCE40 flow had a :ref:`synth_flatten` and put `proc` in the :ref:`synth_begin`, some synthesis scripts will instead include these in this section. @@ -359,8 +359,8 @@ In the iCE40 flow, we start with the following commands: :caption: ``coarse`` section (part 1) :name: synth_coarse1 -We've already come across :cmd:ref:`opt_expr`, and :cmd:ref:`opt_clean` is the -same as :cmd:ref:`clean` but with more verbose output. The :cmd:ref:`check` +We've already come across `opt_expr`, and `opt_clean` is the +same as `clean` but with more verbose output. The `check` pass identifies a few obvious problems which will cause errors later. Calling it here lets us fail faster rather than wasting time on something we know is impossible. @@ -368,13 +368,13 @@ impossible. Next up is :yoscrypt:`opt -nodffe -nosdff` performing a set of simple optimizations on the design. This command also ensures that only a specific subset of FF types are included, in preparation for the next command: -:doc:`/cmd/fsm`. Both :cmd:ref:`opt` and :cmd:ref:`fsm` are macro commands +:doc:`/cmd/fsm`. Both `opt` and `fsm` are macro commands which are explored in more detail in :doc:`/using_yosys/synthesis/opt` and :doc:`/using_yosys/synthesis/fsm` respectively. Up until now, the data path for ``rdata`` has remained the same since -:ref:`rdata_flat`. However the next call to :cmd:ref:`opt` does cause a change. -Specifically, the call to :cmd:ref:`opt_dff` without the ``-nodffe -nosdff`` +:ref:`rdata_flat`. However the next call to `opt` does cause a change. +Specifically, the call to `opt_dff` without the ``-nodffe -nosdff`` options is able to fold one of the `$mux` cells into the `$adff` to form an `$adffe` cell; highlighted below: @@ -382,13 +382,13 @@ options is able to fold one of the `$mux` cells into the `$adff` to form an :language: doscon :start-at: yosys> opt_dff :end-before: yosys> select - :caption: output of :cmd:ref:`opt_dff` + :caption: output of `opt_dff` .. figure:: /_images/code_examples/fifo/rdata_adffe.* :class: width-helper invert-helper :name: rdata_adffe - ``rdata`` output after :cmd:ref:`opt_dff` + ``rdata`` output after `opt_dff` .. seealso:: Advanced usage docs for @@ -414,26 +414,26 @@ First up is :doc:`/cmd/wreduce`. If we run this we get the following: :language: doscon :start-at: yosys> wreduce :end-before: yosys> select - :caption: output of :cmd:ref:`wreduce` + :caption: output of `wreduce` Looking at the data path for ``rdata``, the most relevant of these width reductions are the ones affecting ``fifo.$flatten\fifo_reader.$add$fifo.v``. That is the `$add` cell incrementing the fifo_reader address. We can look at the schematic and see the output of that cell has now changed. -.. todo:: pending bugfix in :cmd:ref:`wreduce` and/or :cmd:ref:`opt_clean` +.. todo:: pending bugfix in `wreduce` and/or `opt_clean` .. figure:: /_images/code_examples/fifo/rdata_wreduce.* :class: width-helper invert-helper :name: rdata_wreduce - ``rdata`` output after :cmd:ref:`wreduce` + ``rdata`` output after `wreduce` The next two (new) commands are :doc:`/cmd/peepopt` and :doc:`/cmd/share`. Neither of these affect our design, and they're explored in more detail in :doc:`/using_yosys/synthesis/opt`, so let's skip over them. :yoscrypt:`techmap -map +/cmp2lut.v -D LUT_WIDTH=4` optimizes certain comparison operators by -converting them to LUTs instead. The usage of :cmd:ref:`techmap` is explored +converting them to LUTs instead. The usage of `techmap` is explored more in :doc:`/using_yosys/synthesis/techmap_synth`. Our next command to run is @@ -443,15 +443,15 @@ Our next command to run is :language: doscon :start-at: yosys> memory_dff :end-before: yosys> select - :caption: output of :cmd:ref:`memory_dff` + :caption: output of `memory_dff` .. figure:: /_images/code_examples/fifo/rdata_memrdv2.* :class: width-helper invert-helper :name: rdata_memrdv2 - ``rdata`` output after :cmd:ref:`memory_dff` + ``rdata`` output after `memory_dff` -As the title suggests, :cmd:ref:`memory_dff` has merged the output `$dff` into +As the title suggests, `memory_dff` has merged the output `$dff` into the `$memrd` cell and converted it to a `$memrd_v2` (highlighted). This has also connected the ``CLK`` port to the ``clk`` input as it is now a synchronous memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and @@ -466,7 +466,7 @@ memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and Part 3 ^^^^^^ -The third part of the :cmd:ref:`synth_ice40` flow is a series of commands for +The third part of the `synth_ice40` flow is a series of commands for mapping to DSPs. By default, the iCE40 flow will not map to the hardware DSP blocks and will only be performed if called with the ``-dsp`` flag: :yoscrypt:`synth_ice40 -dsp`. While our example has nothing that could be @@ -483,24 +483,24 @@ what they do. :yoscrypt:`wreduce t:$mul` performs width reduction again, this time targetting only cells of type `$mul`. :yoscrypt:`techmap -map +/mul2dsp.v -map -+/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses :cmd:ref:`techmap` to map ++/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses `techmap` to map `$mul` cells to ``$__MUL16X16`` which are, in turn, mapped to the iCE40 ``SB_MAC16``. Any multipliers which aren't compatible with conversion to -``$__MUL16X16`` are relabelled to ``$__soft_mul`` before :cmd:ref:`chtype` +``$__MUL16X16`` are relabelled to ``$__soft_mul`` before `chtype` changes them back to `$mul`. During the mul2dsp conversion, some of the intermediate signals are marked with the attribute ``mul2dsp``. By calling :yoscrypt:`select a:mul2dsp` we restrict the following commands to only operate on the cells and wires used for these -signals. :cmd:ref:`setattr` removes the now unnecessary ``mul2dsp`` attribute. -:cmd:ref:`opt_expr` we've already come across for const folding and simple +signals. `setattr` removes the now unnecessary ``mul2dsp`` attribute. +`opt_expr` we've already come across for const folding and simple expression rewriting, the ``-fine`` option just enables more fine-grain optimizations. Then we perform width reduction a final time and clear the selection. .. todo:: ``ice40_dsp`` is pmgen -Finally we have :cmd:ref:`ice40_dsp`: similar to the :cmd:ref:`memory_dff` +Finally we have `ice40_dsp`: similar to the `memory_dff` command we saw in the previous section, this merges any surrounding registers into the ``SB_MAC16`` cell. This includes not just the input/output registers, but also pipeline registers and even a post-adder where applicable: turning a @@ -525,40 +525,40 @@ That brings us to the fourth and final part for the iCE40 synthesis flow: Where before each type of arithmetic operation had its own cell, e.g. `$add`, we now want to extract these into `$alu` and `$macc` cells which can help identify opportunities for reusing logic. We do this by running -:cmd:ref:`alumacc`, which we can see produce the following changes in our +`alumacc`, which we can see produce the following changes in our example design: .. literalinclude:: /code_examples/fifo/fifo.out :language: doscon :start-at: yosys> alumacc :end-before: yosys> select - :caption: output of :cmd:ref:`alumacc` + :caption: output of `alumacc` .. figure:: /_images/code_examples/fifo/rdata_alumacc.* :class: width-helper invert-helper :name: rdata_alumacc - ``rdata`` output after :cmd:ref:`alumacc` + ``rdata`` output after `alumacc` -Once these cells have been inserted, the call to :cmd:ref:`opt` can combine +Once these cells have been inserted, the call to `opt` can combine cells which are now identical but may have been missed due to e.g. the difference between `$add` and `$sub`. -The other new command in this part is :doc:`/cmd/memory`. :cmd:ref:`memory` is +The other new command in this part is :doc:`/cmd/memory`. `memory` is another macro command which we examine in more detail in :doc:`/using_yosys/synthesis/memory`. For this document, let us focus just on -the step most relevant to our example: :cmd:ref:`memory_collect`. Up until this +the step most relevant to our example: `memory_collect`. Up until this point, our memory reads and our memory writes have been totally disjoint cells; -operating on the same memory only in the abstract. :cmd:ref:`memory_collect` +operating on the same memory only in the abstract. `memory_collect` combines all of the reads and writes for a memory block into a single cell. .. figure:: /_images/code_examples/fifo/rdata_coarse.* :class: width-helper invert-helper :name: rdata_coarse - ``rdata`` output after :cmd:ref:`memory_collect` + ``rdata`` output after `memory_collect` -Looking at the schematic after running :cmd:ref:`memory_collect` we see that our +Looking at the schematic after running `memory_collect` we see that our `$memrd_v2` cell has been replaced with a `$mem_v2` cell named ``data``, the same name that we used in :ref:`fifo-v`. Where before we had a single set of signals for address and enable, we now have one set for reading (``RD_*``) and @@ -592,8 +592,8 @@ If you skipped calling :yoscrypt:`read_verilog -D ICE40_HX -lib -specify Memory blocks ^^^^^^^^^^^^^ -Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap` and -:cmd:ref:`techmap`. +Mapping to hard memory blocks uses a combination of `memory_libmap` and +`techmap`. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -619,7 +619,7 @@ As a result, extra logic is added so that the generated circuit matches the behaviour of the verilog. :ref:`no_rw_check` describes how we could change our verilog to match our hardware instead. -If we run :cmd:ref:`memory_libmap` under the :cmd:ref:`debug` command we can see +If we run `memory_libmap` under the `debug` command we can see candidates which were identified for mapping, along with the costs of each and what logic requires emulation. @@ -628,9 +628,9 @@ what logic requires emulation. :lines: 2, 6- The ``$__ICE40_RAM4K_`` cell is defined in the file |techlibs/ice40/brams.txt|_, -with the mapping to ``SB_RAM40_4K`` done by :cmd:ref:`techmap` using +with the mapping to ``SB_RAM40_4K`` done by `techmap` using |techlibs/ice40/brams_map.v|_. Any leftover memory cells are then converted -into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`. +into flip flops (the ``logic fallback``) with `memory_map`. .. |techlibs/ice40/brams.txt| replace:: :file:`techlibs/ice40/brams.txt` .. _techlibs/ice40/brams.txt: https://github.com/YosysHQ/yosys/tree/main/techlibs/ice40/brams.txt @@ -654,7 +654,7 @@ into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`. .. note:: The visual clutter on the ``RDATA`` output port (highlighted) is an - unfortunate side effect of :cmd:ref:`opt_clean` on the swizzled data bits. In + unfortunate side effect of `opt_clean` on the swizzled data bits. In connecting the `$mux` input port directly to ``RDATA`` to reduce the number of wires, the ``$techmap579\data.0.0.RDATA`` wire becomes more visually complex. @@ -667,7 +667,7 @@ into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`. Arithmetic ^^^^^^^^^^ -Uses :cmd:ref:`techmap` to map basic arithmetic logic to hardware. This sees +Uses `techmap` to map basic arithmetic logic to hardware. This sees somewhat of an explosion in cells as multi-bit :cell:ref:`$mux` and `$adffe` are replaced with single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the :cell:ref:`$alu` is replaced with primitive `$_OR_` and `$_NOT_` gates and a @@ -693,11 +693,11 @@ replaced with single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the Flip-flops ^^^^^^^^^^ -Convert FFs to the types supported in hardware with :cmd:ref:`dfflegalize`, and -then use :cmd:ref:`techmap` to map them. In our example, this converts the +Convert FFs to the types supported in hardware with `dfflegalize`, and +then use `techmap` to map them. In our example, this converts the `$_DFFE_PP0P_` cells to ``SB_DFFER``. -We also run :cmd:ref:`simplemap` here to convert any remaining cells which could +We also run `simplemap` here to convert any remaining cells which could not be mapped to hardware into gate-level primitives. This includes optimizing `$_MUX_` cells where one of the inputs is a constant ``1'0``, replacing it instead with an `$_AND_` cell. @@ -722,9 +722,9 @@ instead with an `$_AND_` cell. LUTs ^^^^ -:cmd:ref:`abc` and :cmd:ref:`techmap` are used to map LUTs; converting primitive +`abc` and `techmap` are used to map LUTs; converting primitive cell types to use `$lut` and ``SB_CARRY`` cells. Note that the iCE40 flow -uses :cmd:ref:`abc9` rather than :cmd:ref:`abc`. For more on what these do, and +uses `abc9` rather than `abc`. For more on what these do, and what the difference between these two commands are, refer to :doc:`/using_yosys/synthesis/abc`. @@ -742,7 +742,7 @@ what the difference between these two commands are, refer to ``rdata`` output after :ref:`map_luts` -Finally we use :cmd:ref:`techmap` to map the generic `$lut` cells to iCE40 +Finally we use `techmap` to map the generic `$lut` cells to iCE40 ``SB_LUT4`` cells. .. literalinclude:: /cmd/synth_ice40.rst @@ -769,12 +769,12 @@ Other cells The following commands may also be used for mapping other cells: -:cmd:ref:`hilomap` +`hilomap` Some architectures require special driver cells for driving a constant hi or lo value. This command replaces simple constants with instances of such driver cells. -:cmd:ref:`iopadmap` +`iopadmap` Top-level input/outputs must usually be implemented using special I/O-pad cells. This command inserts such cells to the design. @@ -801,27 +801,27 @@ The new commands here are: - :doc:`/cmd/stat`, and - :doc:`/cmd/blackbox`. -The output from :cmd:ref:`stat` is useful for checking resource utilization; +The output from `stat` is useful for checking resource utilization; providing a list of cells used in the design and the number of each, as well as the number of other resources used such as wires and processes. For this -design, the final call to :cmd:ref:`stat` should look something like the +design, the final call to `stat` should look something like the following: .. literalinclude:: /code_examples/fifo/fifo.stat :language: doscon :start-at: yosys> stat -top fifo -Note that the :yoscrypt:`-top fifo` here is optional. :cmd:ref:`stat` will +Note that the :yoscrypt:`-top fifo` here is optional. `stat` will automatically use the module with the ``top`` attribute set, which ``fifo`` was -when we called :cmd:ref:`hierarchy`. If no module is marked ``top``, then stats +when we called `hierarchy`. If no module is marked ``top``, then stats will be shown for each module selected. -The :cmd:ref:`stat` output is also useful as a kind of sanity-check: Since we -have already run :cmd:ref:`proc`, we wouldn't expect there to be any processes. +The `stat` output is also useful as a kind of sanity-check: Since we +have already run `proc`, we wouldn't expect there to be any processes. We also expect ``data`` to use hard memory; if instead of an ``SB_RAM40_4K`` saw a high number of flip-flops being used we might suspect something was wrong. -If we instead called :cmd:ref:`stat` immediately after :yoscrypt:`read_verilog +If we instead called `stat` immediately after :yoscrypt:`read_verilog fifo.v` we would see something very different: .. literalinclude:: /code_examples/fifo/fifo.stat @@ -845,7 +845,7 @@ The iCE40 synthesis flow has the following output modes available: As an example, if we called :yoscrypt:`synth_ice40 -top fifo -json fifo.json`, our synthesized ``fifo`` design will be output as :file:`fifo.json`. We can -then read the design back into Yosys with :cmd:ref:`read_json`, but make sure +then read the design back into Yosys with `read_json`, but make sure you use :yoscrypt:`design -reset` or open a new interactive terminal first. The JSON output we get can also be loaded into `nextpnr`_ to do place and route; but that is beyond the scope of this documentation. diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst index 4d1a2f36a..8ed7cebb8 100644 --- a/docs/source/getting_started/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -88,7 +88,7 @@ A C++ compiler with C++17 support is required as well as some standard tools such as GNU Flex, GNU Bison, Make and Python. Some additional tools: readline, libffi, Tcl and zlib; are optional but enabled by default (see :makevar:`ENABLE_*` settings in Makefile). Graphviz and Xdot are used by the -:cmd:ref:`show` command to display schematics. +`show` command to display schematics. Installing all prerequisites for Ubuntu 20.04: @@ -185,8 +185,8 @@ directories: ``passes/`` This directory contains a subdirectory for each pass or group of passes. For example as of this writing the directory :file:`passes/hierarchy/` contains the - code for three passes: :cmd:ref:`hierarchy`, :cmd:ref:`submod`, and - :cmd:ref:`uniquify`. + code for three passes: `hierarchy`, `submod`, and + `uniquify`. ``techlibs/`` This directory contains simulation models and standard implementations for diff --git a/docs/source/getting_started/scripting_intro.rst b/docs/source/getting_started/scripting_intro.rst index 1e2ebabff..ef728e1cf 100644 --- a/docs/source/getting_started/scripting_intro.rst +++ b/docs/source/getting_started/scripting_intro.rst @@ -7,8 +7,7 @@ file format and how you can make your own synthesis scripts. Yosys script files typically use the :file:`.ys` extension and contain a set of commands for Yosys to run sequentially. These commands are the same ones we -were using on the previous page like :cmd:ref:`read_verilog` and -:cmd:ref:`hierarchy`. +were using on the previous page like `read_verilog` and `hierarchy`. Script parsing ~~~~~~~~~~~~~~ @@ -39,9 +38,9 @@ Another special character that can be used in Yosys scripts is the bang ``!``. Anything after the bang will be executed as a shell command. This can only be terminated with a new line. Any semicolons, hashes, or other special characters will be passed to the shell. If an error code is returned from the shell it -will be raised by Yosys. :cmd:ref:`exec` provides a much more flexible way of -executing commands, allowing the output to be logged and more control over when -to generate errors. +will be raised by Yosys. `exec` provides a much more flexible way of executing +commands, allowing the output to be logged and more control over when to +generate errors. The synthesis starter script ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -62,7 +61,7 @@ already, let's take a look at some of those script files now. :caption: A section of :file:`fifo.ys`, generating the images used for :ref:`addr_gen_example` :name: fifo-ys -The first command there, :yoscrypt:`echo on`, uses :cmd:ref:`echo` to enable +The first command there, :yoscrypt:`echo on`, uses `echo` to enable command echoes on. This is how we generated the code listing for :ref:`hierarchy_output`. Turning command echoes on prints the ``yosys> hierarchy -top addr_gen`` line, making the output look the same as if it were an @@ -70,15 +69,15 @@ interactive terminal. :yoscrypt:`hierarchy -top addr_gen` is of course the command we were demonstrating, including the output text and an image of the design schematic after running it. -We briefly touched on :cmd:ref:`select` when it came up in -:cmd:ref:`synth_ice40`, but let's look at it more now. +We briefly touched on `select` when it came up in +`synth_ice40`, but let's look at it more now. .. _select_intro: Selections intro ^^^^^^^^^^^^^^^^ -The :cmd:ref:`select` command is used to modify and view the list of selected +The `select` command is used to modify and view the list of selected objects: .. literalinclude:: /code_examples/fifo/fifo.out @@ -119,7 +118,7 @@ statement. Many commands also support an optional ``[selection]`` argument which can be used to override the currently selected objects. We could, for example, call -:yoscrypt:`clean addr_gen` to have :cmd:ref:`clean` operate on *just* the +:yoscrypt:`clean addr_gen` to have `clean` operate on *just* the ``addr_gen`` module. Detailed documentation of the select framework can be found under @@ -131,9 +130,9 @@ Detailed documentation of the select framework can be found under Displaying schematics ^^^^^^^^^^^^^^^^^^^^^ -While the :cmd:ref:`select` command is very useful, sometimes nothing beats -being able to see a design for yourself. This is where :cmd:ref:`show` comes -in. Note that this document is just an introduction to the :cmd:ref:`show` +While the `select` command is very useful, sometimes nothing beats +being able to see a design for yourself. This is where `show` comes +in. Note that this document is just an introduction to the `show` command, only covering the basics. For more information, including a guide on what the different symbols represent, see :ref:`interactive_show` and the :doc:`/using_yosys/more_scripting/interactive_investigation` page. @@ -142,11 +141,11 @@ what the different symbols represent, see :ref:`interactive_show` and the :class: width-helper invert-helper :name: addr_gen_show - Calling :yoscrypt:`show addr_gen` after :cmd:ref:`hierarchy` + Calling :yoscrypt:`show addr_gen` after `hierarchy` .. note:: - The :cmd:ref:`show` command requires a working installation of `GraphViz`_ + The `show` command requires a working installation of `GraphViz`_ and `xdot`_ for displaying the actual circuit diagrams. .. _GraphViz: http://www.graphviz.org/ @@ -161,7 +160,7 @@ we see the following: :start-at: -prefix addr_gen_show :end-before: yosys> show -Calling :cmd:ref:`show` with :yoscrypt:`-format dot` tells it we want to output +Calling `show` with :yoscrypt:`-format dot` tells it we want to output a :file:`.dot` file rather than opening it for display. The :yoscrypt:`-prefix addr_gen_show` option indicates we want the file to be called :file:`addr_gen_show.{*}`. Remember, we do this in :file:`fifo.ys` because we @@ -186,7 +185,7 @@ That last parameter doesn't have to be a module name, it can be any valid selection string. Remember when we :ref:`assigned a name to a selection` and called it ``new_cells``? We saw in the :yoscrypt:`select -list` output that it contained two cells, an `$add` and an -`$eq`. We can call :cmd:ref:`show` on that selection just as easily: +`$eq`. We can call `show` on that selection just as easily: .. figure:: /_images/code_examples/fifo/new_cells_show.* :class: width-helper invert-helper @@ -208,10 +207,10 @@ the two ``PROC`` blocks. To achieve this highlight, we make use of the Calling :yoscrypt:`show -color maroon3 @new_cells -color cornflowerblue p:* -notitle` -As described in the the :cmd:ref:`help` output for :cmd:ref:`show` (or by -clicking on the :cmd:ref:`show` link), colors are specified as :yoscrypt:`-color +As described in the the `help` output for `show` (or by +clicking on the `show` link), colors are specified as :yoscrypt:`-color `. Color names for the ```` portion can be found on the -`GraphViz color docs`_. Unlike the final :cmd:ref:`show` parameter which can +`GraphViz color docs`_. Unlike the final `show` parameter which can have be any selection string, the ```` part must be a single selection expression or named selection. That means while we can use ``@new_cells``, we couldn't use ``t:$eq t:$add``. In general, if a command lists ``[selection]`` @@ -221,7 +220,7 @@ expression instead. .. _GraphViz color docs: https://graphviz.org/doc/info/colors -For all of the options available to :cmd:ref:`show`, check the command reference +For all of the options available to `show`, check the command reference at :doc:`/cmd/show`. .. seealso:: :ref:`interactive_show` on the diff --git a/docs/source/using_yosys/more_scripting/interactive_investigation.rst b/docs/source/using_yosys/more_scripting/interactive_investigation.rst index 77d826376..f2e3d5219 100644 --- a/docs/source/using_yosys/more_scripting/interactive_investigation.rst +++ b/docs/source/using_yosys/more_scripting/interactive_investigation.rst @@ -13,7 +13,7 @@ A look at the show command .. TODO:: merge into :doc:`/getting_started/scripting_intro` show section -This section explores the :cmd:ref:`show` command and explains the symbols used +This section explores the `show` command and explains the symbols used in the circuit diagrams generated by it. The code used is included in the Yosys code base under |code_examples/show|_. @@ -24,7 +24,7 @@ A simple circuit ^^^^^^^^^^^^^^^^ :ref:`example_v` below provides the Verilog code for a simple circuit which we -will use to demonstrate the usage of :cmd:ref:`show` in a simple setting. +will use to demonstrate the usage of `show` in a simple setting. .. literalinclude:: /code_examples/show/example.v :language: Verilog @@ -32,7 +32,7 @@ will use to demonstrate the usage of :cmd:ref:`show` in a simple setting. :name: example_v The Yosys synthesis script we will be running is included as -:numref:`example_ys`. Note that :cmd:ref:`show` is called with the ``-pause`` +:numref:`example_ys`. Note that `show` is called with the ``-pause`` option, that halts execution of the Yosys script until the user presses the Enter key. Using :yoscrypt:`show -pause` also allows the user to enter an interactive shell to further investigate the circuit before continuing @@ -58,7 +58,7 @@ is shown. .. figure:: /_images/code_examples/show/example_first.* :class: width-helper invert-helper - Output of the first :cmd:ref:`show` command in :numref:`example_ys` + Output of the first `show` command in :numref:`example_ys` The first output shows the design directly after being read by the Verilog front-end. Input and output ports are displayed as octagonal shapes. Cells are @@ -84,39 +84,39 @@ original ``always``-block in the second line. Note how the multiplexer from the ``?:``-expression is represented as a `$mux` cell but the multiplexer from the ``if``-statement is yet still hidden within the process. -The :cmd:ref:`proc` command transforms the process from the first diagram into a +The `proc` command transforms the process from the first diagram into a multiplexer and a d-type flip-flop, which brings us to the second diagram: .. figure:: /_images/code_examples/show/example_second.* :class: width-helper invert-helper - Output of the second :cmd:ref:`show` command in :numref:`example_ys` + Output of the second `show` command in :numref:`example_ys` The Rhombus shape to the right is a dangling wire. (Wire nodes are only shown if they are dangling or have "public" names, for example names assigned from the Verilog input.) Also note that the design now contains two instances of a -``BUF``-node. These are artefacts left behind by the :cmd:ref:`proc` command. It +``BUF``-node. These are artefacts left behind by the `proc` command. It is quite usual to see such artefacts after calling commands that perform changes in the design, as most commands only care about doing the transformation in the least complicated way, not about cleaning up after them. The next call to -:cmd:ref:`clean` (or :cmd:ref:`opt`, which includes :cmd:ref:`clean` as one of +`clean` (or `opt`, which includes `clean` as one of its operations) will clean up these artefacts. This operation is so common in Yosys scripts that it can simply be abbreviated with the ``;;`` token, which doubles as separator for commands. Unless one wants to specifically analyze this artefacts left behind some operations, it is therefore recommended to always -call :cmd:ref:`clean` before calling :cmd:ref:`show`. +call `clean` before calling `show`. -In this script we directly call :cmd:ref:`opt` as the next step, which finally +In this script we directly call `opt` as the next step, which finally leads us to the third diagram: .. figure:: /_images/code_examples/show/example_third.* :class: width-helper invert-helper :name: example_out - Output of the third :cmd:ref:`show` command in :ref:`example_ys` + Output of the third `show` command in :ref:`example_ys` -Here we see that the :cmd:ref:`opt` command not only has removed the artifacts -left behind by :cmd:ref:`proc`, but also determined correctly that it can remove +Here we see that the `opt` command not only has removed the artifacts +left behind by `proc`, but also determined correctly that it can remove the first `$mux` cell without changing the behavior of the circuit. Break-out boxes for signal vectors @@ -129,7 +129,7 @@ accesses. :caption: :file:`splice.v` :name: splice_src -Notice how the output for this circuit from the :cmd:ref:`show` command +Notice how the output for this circuit from the `show` command (:numref:`splice_dia`) appears quite complex. This is an unfortunate side effect of the way Yosys handles signal vectors (aka. multi-bit wires or buses) as native objects. While this provides great advantages when analyzing circuits @@ -169,7 +169,7 @@ mapped to a cell library: :name: first_pitfall A half-adder built from simple CMOS gates, demonstrating common pitfalls when - using :cmd:ref:`show` + using `show` .. literalinclude:: /code_examples/show/cmos.ys :language: yoscrypt @@ -188,7 +188,7 @@ individual bits, resulting in an unnecessary complex diagram. :class: width-helper invert-helper :name: second_pitfall - Effects of :cmd:ref:`splitnets` command and of providing a cell library on + Effects of `splitnets` command and of providing a cell library on design in :numref:`first_pitfall` .. literalinclude:: /code_examples/show/cmos.ys @@ -201,11 +201,11 @@ individual bits, resulting in an unnecessary complex diagram. For :numref:`second_pitfall`, Yosys has been given a description of the cell library as Verilog file containing blackbox modules. There are two ways to load cell descriptions into Yosys: First the Verilog file for the cell library can be -passed directly to the :cmd:ref:`show` command using the ``-lib `` +passed directly to the `show` command using the ``-lib `` option. Secondly it is possible to load cell libraries into the design with the :yoscrypt:`read_verilog -lib ` command. The second method has the great advantage that the library only needs to be loaded once and can then be -used in all subsequent calls to the :cmd:ref:`show` command. +used in all subsequent calls to the `show` command. In addition to that, :numref:`second_pitfall` was generated after :yoscrypt:`splitnet -ports` was run on the design. This command splits all @@ -216,7 +216,7 @@ module ports. Per default the command only operates on interior signals. Miscellaneous notes ^^^^^^^^^^^^^^^^^^^ -Per default the :cmd:ref:`show` command outputs a temporary dot file and +Per default the `show` command outputs a temporary dot file and launches ``xdot`` to display it. The options ``-format``, ``-viewer`` and ``-prefix`` can be used to change format, viewer and filename prefix. Note that the ``pdf`` and ``ps`` format are the only formats that support plotting @@ -225,13 +225,13 @@ modules, however ``xdot`` will raise an error when trying to read them. In densely connected circuits it is sometimes hard to keep track of the individual signal wires. For these cases it can be useful to call -:cmd:ref:`show` with the ``-colors `` argument, which randomly assigns +`show` with the ``-colors `` argument, which randomly assigns colors to the nets. The integer (> 0) is used as seed value for the random color assignments. Sometimes it is necessary it try some values to find an assignment of colors that looks good. The command :yoscrypt:`help show` prints a complete listing of all options -supported by the :cmd:ref:`show` command. +supported by the `show` command. Navigating the design ~~~~~~~~~~~~~~~~~~~~~ @@ -245,9 +245,9 @@ In addition to *what* to display one also needs to carefully decide *when* to display it, with respect to the synthesis flow. In general it is a good idea to troubleshoot a circuit in the earliest state in which a problem can be reproduced. So if, for example, the internal state before calling the -:cmd:ref:`techmap` command already fails to verify, it is better to troubleshoot -the coarse-grain version of the circuit before :cmd:ref:`techmap` than the -gate-level circuit after :cmd:ref:`techmap`. +`techmap` command already fails to verify, it is better to troubleshoot +the coarse-grain version of the circuit before `techmap` than the +gate-level circuit after `techmap`. .. Note:: @@ -260,16 +260,16 @@ Interactive navigation ^^^^^^^^^^^^^^^^^^^^^^ Once the right state within the synthesis flow for debugging the circuit has -been identified, it is recommended to simply add the :cmd:ref:`shell` command to +been identified, it is recommended to simply add the `shell` command to the matching place in the synthesis script. This command will stop the synthesis at the specified moment and go to shell mode, where the user can interactively enter commands. For most cases, the shell will start with the whole design selected (i.e. when the synthesis script does not already narrow the selection). The command -:cmd:ref:`ls` can now be used to create a list of all modules. The command -:cmd:ref:`cd` can be used to switch to one of the modules (type ``cd ..`` to -switch back). Now the :cmd:ref:`ls` command lists the objects within that +`ls` can now be used to create a list of all modules. The command +`cd` can be used to switch to one of the modules (type ``cd ..`` to +switch back). Now the `ls` command lists the objects within that module. This is demonstrated below using :file:`example.v` from `A simple circuit`_: @@ -277,10 +277,10 @@ circuit`_: :language: doscon :start-at: yosys> ls :end-before: yosys [example]> dump - :caption: Output of :cmd:ref:`ls` and :cmd:ref:`cd` after running :file:`yosys example.v` + :caption: Output of `ls` and `cd` after running :file:`yosys example.v` :name: lscd -When a module is selected using the :cmd:ref:`cd` command, all commands (with a +When a module is selected using the `cd` command, all commands (with a few exceptions, such as the ``read_`` and ``write_`` commands) operate only on the selected module. This can also be useful for synthesis scripts where different synthesis strategies should be applied to different modules in the @@ -293,12 +293,12 @@ contains some additional information on the origin of the named object. But in most cases those names can simply be abbreviated using the last part. Usually all interactive work is done with one module selected using the -:cmd:ref:`cd` command. But it is also possible to work from the design-context +`cd` command. But it is also possible to work from the design-context (``cd ..``). In this case all object names must be prefixed with ``/``. For example ``a*/b*`` would refer to all objects whose names start with ``b`` from all modules whose names start with ``a``. -The :cmd:ref:`dump` command can be used to print all information about an +The `dump` command can be used to print all information about an object. For example, calling :yoscrypt:`dump $2` after the :yoscrypt:`cd example` above: @@ -323,10 +323,10 @@ tools). - The selection mechanism, especially patterns such as ``%ci`` and ``%co``, can be used to figure out how parts of the design are connected. -- Commands such as :cmd:ref:`submod`, :cmd:ref:`expose`, and :cmd:ref:`splice` +- Commands such as `submod`, `expose`, and `splice` can be used to transform the design into an equivalent design that is easier to analyse. -- Commands such as :cmd:ref:`eval` and :cmd:ref:`sat` can be used to investigate +- Commands such as `eval` and `sat` can be used to investigate the behavior of the circuit. - :doc:`/cmd/show`. - :doc:`/cmd/dump`. @@ -342,10 +342,10 @@ The code used is included in the Yosys code base under Changing design hierarchy ^^^^^^^^^^^^^^^^^^^^^^^^^ -Commands such as :cmd:ref:`flatten` and :cmd:ref:`submod` can be used to change +Commands such as `flatten` and `submod` can be used to change the design hierarchy, i.e. flatten the hierarchy or moving parts of a module to a submodule. This has applications in synthesis scripts as well as in reverse -engineering and analysis. An example using :cmd:ref:`submod` is shown below for +engineering and analysis. An example using `submod` is shown below for reorganizing a module in Yosys and checking the resulting circuit. .. literalinclude:: /code_examples/scrambler/scrambler.v @@ -388,7 +388,7 @@ Analyzing the resulting circuit with :doc:`/cmd/eval`: Behavioral changes ^^^^^^^^^^^^^^^^^^ -Commands such as :cmd:ref:`techmap` can be used to make behavioral changes to +Commands such as `techmap` can be used to make behavioral changes to the design, for example changing asynchronous resets to synchronous resets. This has applications in design space exploration (evaluation of various architectures for one circuit). @@ -425,7 +425,7 @@ Yosys script for ASIC synthesis of the Amber ARMv2 CPU. endmodule -For more on the :cmd:ref:`techmap` command, see the page on +For more on the `techmap` command, see the page on :doc:`/yosys_internals/techmap`. Advanced investigation techniques @@ -448,12 +448,12 @@ Recall the ``memdemo`` design from :ref:`advanced_logic_cones`: Because this produces a rather large circuit, it can be useful to split it into smaller parts for viewing and working with. :numref:`submod` does exactly that, -utilising the :cmd:ref:`submod` command to split the circuit into three +utilising the `submod` command to split the circuit into three sections: ``outstage``, ``selstage``, and ``scramble``. .. literalinclude:: /code_examples/selections/submod.ys :language: yoscrypt - :caption: Using :cmd:ref:`submod` to break up the circuit from :file:`memdemo.v` + :caption: Using `submod` to break up the circuit from :file:`memdemo.v` :start-after: cd memdemo :end-before: cd .. :name: submod @@ -481,7 +481,7 @@ below. Evaluation of combinatorial circuits ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The :cmd:ref:`eval` command can be used to evaluate combinatorial circuits. As +The `eval` command can be used to evaluate combinatorial circuits. As an example, we will use the ``selstage`` subnet of ``memdemo`` which we found above and is shown in :numref:`selstage`. @@ -526,20 +526,20 @@ The ``-table`` option can be used to create a truth table. For example: Assumed undef (x) value for the following signals: \s2 -Note that the :cmd:ref:`eval` command (as well as the :cmd:ref:`sat` command +Note that the `eval` command (as well as the `sat` command discussed in the next sections) does only operate on flattened modules. It can not analyze signals that are passed through design hierarchy levels. So the -:cmd:ref:`flatten` command must be used on modules that instantiate other +`flatten` command must be used on modules that instantiate other modules before these commands can be applied. Solving combinatorial SAT problems ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Often the opposite of the :cmd:ref:`eval` command is needed, i.e. the circuits +Often the opposite of the `eval` command is needed, i.e. the circuits output is given and we want to find the matching input signals. For small circuits with only a few input bits this can be accomplished by trying all possible input combinations, as it is done by the ``eval -table`` command. For -larger circuits however, Yosys provides the :cmd:ref:`sat` command that uses a +larger circuits however, Yosys provides the `sat` command that uses a `SAT`_ solver, `MiniSAT`_, to solve this kind of problems. .. _SAT: http://en.wikipedia.org/wiki/Circuit_satisfiability @@ -551,7 +551,7 @@ larger circuits however, Yosys provides the :cmd:ref:`sat` command that uses a While it is possible to perform model checking directly in Yosys, it is highly recommended to use SBY or EQY for formal hardware verification. -The :cmd:ref:`sat` command works very similar to the :cmd:ref:`eval` command. +The `sat` command works very similar to the `eval` command. The main difference is that it is now also possible to set output values and find the corresponding input values. For Example: @@ -580,7 +580,7 @@ find the corresponding input values. For Example: \s1 0 0 00 \s2 0 0 00 -Note that the :cmd:ref:`sat` command supports signal names in both arguments to +Note that the `sat` command supports signal names in both arguments to the ``-set`` option. In the above example we used ``-set s1 s2`` to constraint ``s1`` and ``s2`` to be equal. When more complex constraints are needed, a wrapper circuit must be constructed that checks the constraints and signals if @@ -642,7 +642,7 @@ of course be to perform the test in 32 bits, for example by replacing ``p != a*b`` in the miter with ``p != {16'd0,a}b``, or by using a temporary variable for the 32 bit product ``a*b``. But as 31 fits well into 8 bits (and as the purpose of this document is to show off Yosys features) we can also simply force -the upper 8 bits of ``a`` and ``b`` to zero for the :cmd:ref:`sat` call, as is +the upper 8 bits of ``a`` and ``b`` to zero for the `sat` call, as is done below. .. todo:: replace inline code @@ -705,16 +705,16 @@ command: sat -seq 6 -show y -show d -set-init-undef \ -max_undef -set-at 4 y 1 -set-at 5 y 2 -set-at 6 y 3 -The ``-seq 6`` option instructs the :cmd:ref:`sat` command to solve a sequential +The ``-seq 6`` option instructs the `sat` command to solve a sequential problem in 6 time steps. (Experiments with lower number of steps have show that at least 3 cycles are necessary to bring the circuit in a state from which the sequence 1, 2, 3 can be produced.) -The ``-set-init-undef`` option tells the :cmd:ref:`sat` command to initialize +The ``-set-init-undef`` option tells the `sat` command to initialize all registers to the undef (``x``) state. The way the ``x`` state is treated in Verilog will ensure that the solution will work for any initial state. -The ``-max_undef`` option instructs the :cmd:ref:`sat` command to find a +The ``-max_undef`` option instructs the `sat` command to find a solution with a maximum number of undefs. This way we can see clearly which inputs bits are relevant to the solution. @@ -807,7 +807,7 @@ is the only way of setting the ``s1`` and ``s2`` registers to a known value. The input values for the other steps are a bit harder to work out manually, but the SAT solver finds the correct solution in an instant. -There is much more to write about the :cmd:ref:`sat` command. For example, there +There is much more to write about the `sat` command. For example, there is a set of options that can be used to performs sequential proofs using temporal induction :cite:p:`een2003temporal`. The command ``help sat`` can be used to print a list of all options with short descriptions of their functions. diff --git a/docs/source/using_yosys/more_scripting/model_checking.rst b/docs/source/using_yosys/more_scripting/model_checking.rst index 92a9d85ce..88eeb9bcd 100644 --- a/docs/source/using_yosys/more_scripting/model_checking.rst +++ b/docs/source/using_yosys/more_scripting/model_checking.rst @@ -17,7 +17,7 @@ passes in Yosys. Other applications include checking if a module conforms to interface standards. -The :cmd:ref:`sat` command in Yosys can be used to perform Symbolic Model +The `sat` command in Yosys can be used to perform Symbolic Model Checking. Checking techmap diff --git a/docs/source/using_yosys/more_scripting/selections.rst b/docs/source/using_yosys/more_scripting/selections.rst index 9c76b20b7..1f0efb1f3 100644 --- a/docs/source/using_yosys/more_scripting/selections.rst +++ b/docs/source/using_yosys/more_scripting/selections.rst @@ -9,7 +9,7 @@ The selection framework .. todo:: reduce overlap with :doc:`/getting_started/scripting_intro` select section -The :cmd:ref:`select` command can be used to create a selection for subsequent +The `select` command can be used to create a selection for subsequent commands. For example: .. code:: yoscrypt @@ -17,7 +17,7 @@ commands. For example: select foobar # select the module foobar delete # delete selected objects -Normally the :cmd:ref:`select` command overwrites a previous selection. The +Normally the `select` command overwrites a previous selection. The commands :yoscrypt:`select -add` and :yoscrypt:`select -del` can be used to add or remove objects from the current selection. @@ -26,16 +26,16 @@ default, which is a complete selection of everything in the current module. This selection framework can also be used directly in many other commands. Whenever a command has ``[selection]`` as last argument in its usage help, this -means that it will use the engine behind the :cmd:ref:`select` command to +means that it will use the engine behind the `select` command to evaluate additional arguments and use the resulting selection instead of the -selection created by the last :cmd:ref:`select` command. +selection created by the last `select` command. -For example, the command :cmd:ref:`delete` will delete everything in the current +For example, the command `delete` will delete everything in the current selection; while :yoscrypt:`delete foobar` will only delete the module foobar. -If no :cmd:ref:`select` command has been made, then the "current selection" will +If no `select` command has been made, then the "current selection" will be the whole design. -.. note:: Many of the examples on this page make use of the :cmd:ref:`show` +.. note:: Many of the examples on this page make use of the `show` command to visually demonstrate the effect of selections. For a more detailed look at this command, refer to :ref:`interactive_show`. @@ -59,7 +59,7 @@ Module and design context ^^^^^^^^^^^^^^^^^^^^^^^^^ Commands can be executed in *module/* or *design/* context. Until now, all -commands have been executed in design context. The :cmd:ref:`cd` command can be +commands have been executed in design context. The `cd` command can be used to switch to module context. In module context, all commands only effect the active module. Objects in the @@ -101,7 +101,7 @@ Operations on selections Combining selections ^^^^^^^^^^^^^^^^^^^^ -The :cmd:ref:`select` command is actually much more powerful than it might seem +The `select` command is actually much more powerful than it might seem at first glance. When it is called with multiple arguments, each argument is evaluated and pushed separately on a stack. After all arguments have been processed it simply creates the union of all elements on the stack. So @@ -190,7 +190,7 @@ Selecting logic cones :numref:`sumprod_01` shows what is called the ``input cone`` of ``sum``, i.e. all cells and signals that are used to generate the signal ``sum``. The ``%ci`` action can be used to select the input cones of all object in the top selection -in the stack maintained by the :cmd:ref:`select` command. +in the stack maintained by the `select` command. As with the ``%x`` action, these commands broaden the selection by one "step". But this time the operation only works against the direction of data flow. That @@ -222,9 +222,9 @@ The following sequence of diagrams demonstrates this step-wise expansion: Notice the subtle difference between :yoscrypt:`show prod %ci` and :yoscrypt:`show prod %ci %ci`. Both images show the `$mul` cell driven by some inputs ``$3_Y`` and ``c``. However it is not until the second image, -having called ``%ci`` the second time, that :cmd:ref:`show` is able to +having called ``%ci`` the second time, that `show` is able to distinguish between ``$3_Y`` being a wire and ``c`` being an input. We can see -this better with the :cmd:ref:`dump` command instead: +this better with the `dump` command instead: .. literalinclude:: /code_examples/selections/sumprod.out :language: RTLIL @@ -276,7 +276,7 @@ look at the first section: This loads :numref:`memdemo_src` and synthesizes the included module. Note that this code can be copied and run directly in a Yosys command line session, provided :file:`memdemo.v` is in the same directory. We can now change to the -``memdemo`` module with ``cd memdemo``, and call :cmd:ref:`show` to see the +``memdemo`` module with ``cd memdemo``, and call `show` to see the diagram in :numref:`memdemo_00`. .. figure:: /_images/code_examples/selections/memdemo_00.* @@ -387,14 +387,14 @@ Storing and recalling selections The current selection can be stored in memory with the command ``select -set ``. It can later be recalled using ``select @``. In fact, the ``@`` expression pushes the stored selection on the stack maintained by -the :cmd:ref:`select` command. So for example :yoscrypt:`select @foo @bar %i` +the `select` command. So for example :yoscrypt:`select @foo @bar %i` will select the intersection between the stored selections ``foo`` and ``bar``. In larger investigation efforts it is highly recommended to maintain a script that sets up relevant selections, so they can easily be recalled, for example when Yosys needs to be re-run after a design or source code change. -The :cmd:ref:`history` command can be used to list all recent interactive +The `history` command can be used to list all recent interactive commands. This feature can be useful for creating such a script from the commands used in an interactive session. diff --git a/docs/source/using_yosys/synthesis/abc.rst b/docs/source/using_yosys/synthesis/abc.rst index fca9ddec0..0c2e4868a 100644 --- a/docs/source/using_yosys/synthesis/abc.rst +++ b/docs/source/using_yosys/synthesis/abc.rst @@ -10,11 +10,11 @@ fine-grained optimisation and LUT mapping. Yosys has two different commands, which both use this logic toolbox, but use it in different ways. -The :cmd:ref:`abc` pass can be used for both ASIC (e.g. :yoscrypt:`abc +The `abc` pass can be used for both ASIC (e.g. :yoscrypt:`abc -liberty`) and FPGA (:yoscrypt:`abc -lut`) mapping, but this page will focus on FPGA mapping. -The :cmd:ref:`abc9` pass generally provides superior mapping quality due to +The `abc9` pass generally provides superior mapping quality due to being aware of combination boxes and DFF and LUT timings, giving it a more global view of the mapping problem. @@ -23,7 +23,7 @@ global view of the mapping problem. ABC: the unit delay model, simple and efficient ----------------------------------------------- -The :cmd:ref:`abc` pass uses a highly simplified view of an FPGA: +The `abc` pass uses a highly simplified view of an FPGA: - An FPGA is made up of a network of inputs that connect through LUTs to a network of outputs. These inputs may actually be I/O pins, D flip-flops, @@ -126,7 +126,7 @@ guide to the syntax: By convention, all delays in ``specify`` blocks are in integer picoseconds. Files containing ``specify`` blocks should be read with the ``-specify`` option -to :cmd:ref:`read_verilog` so that they aren't skipped. +to `read_verilog` so that they aren't skipped. LUTs ^^^^ @@ -145,9 +145,9 @@ DFFs DFFs should be annotated with an ``(* abc9_flop *)`` attribute, however ABC9 has some specific requirements for this to be valid: - the DFF must initialise to -zero (consider using :cmd:ref:`dfflegalize` to ensure this). - the DFF cannot -have any asynchronous resets/sets (see the simplification idiom and the Boxes -section for what to do here). +zero (consider using `dfflegalize` to ensure this). - the DFF cannot have any +asynchronous resets/sets (see the simplification idiom and the Boxes section for +what to do here). It is worth noting that in pure ``abc9`` mode, only the setup and arrival times are passed to ABC9 (specifically, they are modelled as buffers with the given @@ -158,9 +158,9 @@ Some vendors have universal DFF models which include async sets/resets even when they're unused. Therefore *the simplification idiom* exists to handle this: by using a ``techmap`` file to discover flops which have a constant driver to those asynchronous controls, they can be mapped into an intermediate, simplified flop -which qualifies as an ``(* abc9_flop *)``, ran through :cmd:ref:`abc9`, and then -mapped back to the original flop. This is used in :cmd:ref:`synth_intel_alm` and -:cmd:ref:`synth_quicklogic` for the PolarPro3. +which qualifies as an ``(* abc9_flop *)``, ran through `abc9`, and then mapped +back to the original flop. This is used in `synth_intel_alm` and +`synth_quicklogic` for the PolarPro3. DFFs are usually specified to have setup constraints against the clock on the input signals, and an arrival time for the ``Q`` output. diff --git a/docs/source/using_yosys/synthesis/cell_libs.rst b/docs/source/using_yosys/synthesis/cell_libs.rst index 58b6431a5..c8dbba838 100644 --- a/docs/source/using_yosys/synthesis/cell_libs.rst +++ b/docs/source/using_yosys/synthesis/cell_libs.rst @@ -54,7 +54,7 @@ Our circuit now looks like this: :class: width-helper invert-helper :name: counter-hierarchy - ``counter`` after :cmd:ref:`hierarchy` + ``counter`` after `hierarchy` Coarse-grain representation ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -82,7 +82,7 @@ Logic gate mapping .. figure:: /_images/code_examples/intro/counter_02.* :class: width-helper invert-helper - ``counter`` after :cmd:ref:`techmap` + ``counter`` after `techmap` Mapping to hardware ~~~~~~~~~~~~~~~~~~~ @@ -102,7 +102,7 @@ Recall that the Yosys built-in logic gate types are `$_NOT_`, `$_AND_`, `$_OR_`, `$_XOR_`, and `$_MUX_` with an assortment of dff memory types. :ref:`mycells-lib` defines our target cells as ``BUF``, ``NOT``, ``NAND``, ``NOR``, and ``DFF``. Mapping between these is performed with the commands -:cmd:ref:`dfflibmap` and :cmd:ref:`abc` as follows: +`dfflibmap` and `abc` as follows: .. literalinclude:: /code_examples/intro/counter.ys :language: yoscrypt @@ -117,7 +117,7 @@ The final version of our ``counter`` module looks like this: ``counter`` after hardware cell mapping -Before finally being output as a verilog file with :cmd:ref:`write_verilog`, +Before finally being output as a verilog file with `write_verilog`, which can then be loaded into another tool: .. literalinclude:: /code_examples/intro/counter.ys diff --git a/docs/source/using_yosys/synthesis/extract.rst b/docs/source/using_yosys/synthesis/extract.rst index c9b76840e..176e2ffdd 100644 --- a/docs/source/using_yosys/synthesis/extract.rst +++ b/docs/source/using_yosys/synthesis/extract.rst @@ -1,13 +1,13 @@ The extract pass ---------------- -- Like the :cmd:ref:`techmap` pass, the :cmd:ref:`extract` pass is called with a +- Like the `techmap` pass, the `extract` pass is called with a map file. It compares the circuits inside the modules of the map file with the design and looks for sub-circuits in the design that match any of the modules in the map file. -- If a match is found, the :cmd:ref:`extract` pass will replace the matching +- If a match is found, the `extract` pass will replace the matching subcircuit with an instance of the module from the map file. -- In a way the :cmd:ref:`extract` pass is the inverse of the techmap pass. +- In a way the `extract` pass is the inverse of the techmap pass. .. todo:: add/expand supporting text, also mention custom pattern matching and pmgen @@ -25,7 +25,7 @@ Example code can be found in |code_examples/macc|_. .. figure:: /_images/code_examples/macc/macc_simple_test_00a.* :class: width-helper invert-helper - before :cmd:ref:`extract` + before `extract` .. literalinclude:: /code_examples/macc/macc_simple_test.ys :language: yoscrypt @@ -34,7 +34,7 @@ Example code can be found in |code_examples/macc|_. .. figure:: /_images/code_examples/macc/macc_simple_test_00b.* :class: width-helper invert-helper - after :cmd:ref:`extract` + after `extract` .. literalinclude:: /code_examples/macc/macc_simple_test.v :language: verilog @@ -76,18 +76,18 @@ wrap-extract-unwrap method: wrap Identify candidate-cells in the circuit and wrap them in a cell with a - constant wider bit-width using :cmd:ref:`techmap`. The wrappers use the same + constant wider bit-width using `techmap`. The wrappers use the same parameters as the original cell, so the information about the original width - of the ports is preserved. Then use the :cmd:ref:`connwrappers` command to + of the ports is preserved. Then use the `connwrappers` command to connect up the bit-extended in- and outputs of the wrapper cells. extract Now all operations are encoded using the same bit-width as the coarse grain - element. The :cmd:ref:`extract` command can be used to replace circuits with + element. The `extract` command can be used to replace circuits with cells of the target architecture. unwrap - The remaining wrapper cell can be unwrapped using :cmd:ref:`techmap`. + The remaining wrapper cell can be unwrapped using `techmap`. Example: DSP48_MACC ~~~~~~~~~~~~~~~~~~~ @@ -127,7 +127,7 @@ Extract: :file:`macc_xilinx_xmap.v` :caption: :file:`macc_xilinx_xmap.v` ... simply use the same wrapping commands on this module as on the design to -create a template for the :cmd:ref:`extract` command. +create a template for the `extract` command. Unwrapping multipliers: :file:`macc_xilinx_unwrap_map.v` diff --git a/docs/source/using_yosys/synthesis/fsm.rst b/docs/source/using_yosys/synthesis/fsm.rst index 3c5a80ad3..cb65a298b 100644 --- a/docs/source/using_yosys/synthesis/fsm.rst +++ b/docs/source/using_yosys/synthesis/fsm.rst @@ -1,14 +1,14 @@ FSM handling ============ -The :cmd:ref:`fsm` command identifies, extracts, optimizes (re-encodes), and +The `fsm` command identifies, extracts, optimizes (re-encodes), and re-synthesizes finite state machines. It again is a macro that calls a series of other commands: .. literalinclude:: /code_examples/macro_commands/fsm.ys :language: yoscrypt :start-after: #end: - :caption: Passes called by :cmd:ref:`fsm` + :caption: Passes called by `fsm` See also :doc:`/cmd/fsm`. @@ -18,7 +18,7 @@ general reported technique :cite:p:`fsmextract`. FSM detection ~~~~~~~~~~~~~ -The :cmd:ref:`fsm_detect` pass identifies FSM state registers. It sets the +The `fsm_detect` pass identifies FSM state registers. It sets the ``\fsm_encoding = "auto"`` attribute on any (multi-bit) wire that matches the following description: @@ -44,7 +44,7 @@ results. FSM extraction ~~~~~~~~~~~~~~ -The :cmd:ref:`fsm_extract` pass operates on all state signals marked with the +The `fsm_extract` pass operates on all state signals marked with the (``\fsm_encoding != "none"``) attribute. For each state signal the following information is determined: @@ -87,7 +87,7 @@ given set of result signals using a set of signal-value assignments. It can also be passed a list of stop-signals that abort the ConstEval algorithm if the value of a stop-signal is needed in order to calculate the result signals. -The :cmd:ref:`fsm_extract` pass uses the ConstEval class in the following way to +The `fsm_extract` pass uses the ConstEval class in the following way to create a transition table. For each state: 1. Create a ConstEval object for the module containing the FSM @@ -108,12 +108,12 @@ drivers for the control outputs are disconnected. FSM optimization ~~~~~~~~~~~~~~~~ -The :cmd:ref:`fsm_opt` pass performs basic optimizations on `$fsm` cells (not +The `fsm_opt` pass performs basic optimizations on `$fsm` cells (not including state recoding). The following optimizations are performed (in this order): - Unused control outputs are removed from the `$fsm` cell. The attribute - ``\unused_bits`` (that is usually set by the :cmd:ref:`opt_clean` pass) is + ``\unused_bits`` (that is usually set by the `opt_clean` pass) is used to determine which control outputs are unused. - Control inputs that are connected to the same driver are merged. @@ -134,11 +134,11 @@ order): FSM recoding ~~~~~~~~~~~~ -The :cmd:ref:`fsm_recode` pass assigns new bit pattern to the states. Usually +The `fsm_recode` pass assigns new bit pattern to the states. Usually this also implies a change in the width of the state signal. At the moment of this writing only one-hot encoding with all-zero for the reset state is supported. -The :cmd:ref:`fsm_recode` pass can also write a text file with the changes +The `fsm_recode` pass can also write a text file with the changes performed by it that can be used when verifying designs synthesized by Yosys using Synopsys Formality. diff --git a/docs/source/using_yosys/synthesis/index.rst b/docs/source/using_yosys/synthesis/index.rst index c00a940da..ae6da302a 100644 --- a/docs/source/using_yosys/synthesis/index.rst +++ b/docs/source/using_yosys/synthesis/index.rst @@ -8,17 +8,17 @@ coarse-grain optimizations before being mapped to hard blocks and fine-grain cells. Most commands in Yosys will target either coarse-grain representation or fine-grain representation, with only a select few compatible with both states. -Commands such as :cmd:ref:`proc`, :cmd:ref:`fsm`, and :cmd:ref:`memory` rely on +Commands such as `proc`, `fsm`, and `memory` rely on the additional information in the coarse-grain representation, along with a -number of optimizations such as :cmd:ref:`wreduce`, :cmd:ref:`share`, and -:cmd:ref:`alumacc`. :cmd:ref:`opt` provides optimizations which are useful in -both states, while :cmd:ref:`techmap` is used to convert coarse-grain cells +number of optimizations such as `wreduce`, `share`, and +`alumacc`. `opt` provides optimizations which are useful in +both states, while `techmap` is used to convert coarse-grain cells to the corresponding fine-grain representation. Single-bit cells (logic gates, FFs) as well as LUTs, half-adders, and full-adders make up the bulk of the fine-grain representation and are necessary -for commands such as :cmd:ref:`abc`\ /:cmd:ref:`abc9`, :cmd:ref:`simplemap`, -:cmd:ref:`dfflegalize`, and :cmd:ref:`memory_map`. +for commands such as `abc`\ /`abc9`, `simplemap`, +`dfflegalize`, and `memory_map`. .. toctree:: :maxdepth: 3 diff --git a/docs/source/using_yosys/synthesis/memory.rst b/docs/source/using_yosys/synthesis/memory.rst index dcbde2ae6..ad8b47d78 100644 --- a/docs/source/using_yosys/synthesis/memory.rst +++ b/docs/source/using_yosys/synthesis/memory.rst @@ -1,11 +1,11 @@ Memory handling =============== -The :cmd:ref:`memory` command +The `memory` command ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In the RTL netlist, memory reads and writes are individual cells. This makes -consolidating the number of ports for a memory easier. The :cmd:ref:`memory` +consolidating the number of ports for a memory easier. The `memory` pass transforms memories to an implementation. Per default that is logic for address decoders and registers. It also is a macro command that calls the other common ``memory_*`` passes in a sensible order: @@ -13,19 +13,19 @@ common ``memory_*`` passes in a sensible order: .. literalinclude:: /code_examples/macro_commands/memory.ys :language: yoscrypt :start-after: #end: - :caption: Passes called by :cmd:ref:`memory` + :caption: Passes called by `memory` .. todo:: Make ``memory_*`` notes less quick Some quick notes: -- :cmd:ref:`memory_dff` merges registers into the memory read- and write cells. -- :cmd:ref:`memory_collect` collects all read and write cells for a memory and +- `memory_dff` merges registers into the memory read- and write cells. +- `memory_collect` collects all read and write cells for a memory and transforms them into one multi-port memory cell. -- :cmd:ref:`memory_map` takes the multi-port memory cell and transforms it to +- `memory_map` takes the multi-port memory cell and transforms it to address decoder logic and registers. -For more information about :cmd:ref:`memory`, such as disabling certain sub +For more information about `memory`, such as disabling certain sub commands, see :doc:`/cmd/memory`. Example @@ -75,22 +75,22 @@ For example: techmap -map my_memory_map.v memory_map -:cmd:ref:`memory_libmap` attempts to convert memory cells (`$mem_v2` etc) into +`memory_libmap` attempts to convert memory cells (`$mem_v2` etc) into hardware supported memory using a provided library (:file:`my_memory_map.txt` in the example above). Where necessary, emulation logic is added to ensure functional equivalence before and after this conversion. :yoscrypt:`techmap -map -my_memory_map.v` then uses :cmd:ref:`techmap` to map to hardware primitives. Any +my_memory_map.v` then uses `techmap` to map to hardware primitives. Any leftover memory cells unable to be converted are then picked up by -:cmd:ref:`memory_map` and mapped to DFFs and address decoders. +`memory_map` and mapped to DFFs and address decoders. .. note:: More information about what mapping options are available and associated costs of each can be found by enabling debug outputs. This can be done with - the :cmd:ref:`debug` command, or by using the ``-g`` flag when calling Yosys + the `debug` command, or by using the ``-g`` flag when calling Yosys to globally enable debug messages. -For more on the lib format for :cmd:ref:`memory_libmap`, see +For more on the lib format for `memory_libmap`, see `passes/memory/memlib.md `_ diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst index cd40f6999..db1525a05 100644 --- a/docs/source/using_yosys/synthesis/opt.rst +++ b/docs/source/using_yosys/synthesis/opt.rst @@ -6,10 +6,10 @@ This chapter outlines these optimizations. .. todo:: "outlines these optimizations" or "outlines *some*.."? -The :cmd:ref:`opt` macro command +The `opt` macro command -------------------------------- -The Yosys pass :cmd:ref:`opt` runs a number of simple optimizations. This +The Yosys pass `opt` runs a number of simple optimizations. This includes removing unused signals and cells and const folding. It is recommended to run this pass after each major step in the synthesis script. As listed in :doc:`/cmd/opt`, this macro command calls the following ``opt_*`` commands: @@ -17,11 +17,11 @@ to run this pass after each major step in the synthesis script. As listed in .. literalinclude:: /code_examples/macro_commands/opt.ys :language: yoscrypt :start-after: #end: - :caption: Passes called by :cmd:ref:`opt` + :caption: Passes called by `opt` .. _adv_opt_expr: -Constant folding and simple expression rewriting - :cmd:ref:`opt_expr` +Constant folding and simple expression rewriting - `opt_expr` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. todo:: unsure if this is too much detail and should be in :doc:`/yosys_internals/index` @@ -31,7 +31,7 @@ described in :doc:`/yosys_internals/formats/cell_library`. This means a cell with all constant inputs is replaced with the constant value this cell drives. In some cases this pass can also optimize cells with some constant inputs. -.. table:: Const folding rules for `$_AND_` cells as used in :cmd:ref:`opt_expr`. +.. table:: Const folding rules for `$_AND_` cells as used in `opt_expr`. :name: tab:opt_expr_and :align: center @@ -69,7 +69,7 @@ undef. The last two lines simply replace an `$_AND_` gate with one constant-1 input with a buffer. -Besides this basic const folding the :cmd:ref:`opt_expr` pass can replace 1-bit +Besides this basic const folding the `opt_expr` pass can replace 1-bit wide `$eq` and `$ne` cells with buffers or not-gates if one input is constant. Equality checks may also be reduced in size if there are redundant bits in the arguments (i.e. bits which are constant on both inputs). This can, @@ -77,7 +77,7 @@ for example, result in a 32-bit wide constant like ``255`` being reduced to the 8-bit value of ``8'11111111`` if the signal being compared is only 8-bit as in :ref:`addr_gen_clean` of :doc:`/getting_started/example_synth`. -The :cmd:ref:`opt_expr` pass is very conservative regarding optimizing `$mux` +The `opt_expr` pass is very conservative regarding optimizing `$mux` cells, as these cells are often used to model decision-trees and breaking these trees can interfere with other optimizations. @@ -85,14 +85,14 @@ trees can interfere with other optimizations. :language: Verilog :start-after: read_verilog <fixup_ports()`` after changing the ``port_*`` properties of wires. - You can safely remove cells or change the ``connections`` property of a cell, diff --git a/docs/source/yosys_internals/flow/verilog_frontend.rst b/docs/source/yosys_internals/flow/verilog_frontend.rst index 7c8c9d8fb..fced46e8c 100644 --- a/docs/source/yosys_internals/flow/verilog_frontend.rst +++ b/docs/source/yosys_internals/flow/verilog_frontend.rst @@ -600,15 +600,15 @@ The proc pass The ProcessGenerator converts a behavioural model in AST representation to a behavioural model in ``RTLIL::Process`` representation. The actual conversion from a behavioural model to an RTL representation is performed by the -:cmd:ref:`proc` pass and the passes it launches: +`proc` pass and the passes it launches: -- | :cmd:ref:`proc_clean` and :cmd:ref:`proc_rmdead` +- | `proc_clean` and `proc_rmdead` | These two passes just clean up the ``RTLIL::Process`` structure. The - :cmd:ref:`proc_clean` pass removes empty parts (eg. empty assignments) from - the process and :cmd:ref:`proc_rmdead` detects and removes unreachable + `proc_clean` pass removes empty parts (eg. empty assignments) from + the process and `proc_rmdead` detects and removes unreachable branches from the process's decision trees. -- | :cmd:ref:`proc_arst` +- | `proc_arst` | This pass detects processes that describe d-type flip-flops with asynchronous resets and rewrites the process to better reflect what they are modelling: Before this pass, an asynchronous reset has two @@ -616,21 +616,21 @@ from a behavioural model to an RTL representation is performed by the reset path. After this pass the sync rule for the reset is level-sensitive and the top-level ``RTLIL::SwitchRule`` has been removed. -- | :cmd:ref:`proc_mux` +- | `proc_mux` | This pass converts the ``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule``-tree to a tree of multiplexers per written signal. After this, the ``RTLIL::Process`` structure only contains the ``RTLIL::SyncRule`` s that describe the output registers. -- | :cmd:ref:`proc_dff` +- | `proc_dff` | This pass replaces the ``RTLIL::SyncRule``\ s to d-type flip-flops (with asynchronous resets if necessary). -- | :cmd:ref:`proc_dff` +- | `proc_dff` | This pass replaces the ``RTLIL::MemWriteAction``\ s with `$memwr` cells. -- | :cmd:ref:`proc_clean` - | A final call to :cmd:ref:`proc_clean` removes the now empty +- | `proc_clean` + | A final call to `proc_clean` removes the now empty ``RTLIL::Process`` objects. Performing these last processing steps in passes instead of in the Verilog diff --git a/docs/source/yosys_internals/formats/cell_library.rst b/docs/source/yosys_internals/formats/cell_library.rst index cd1496e11..e9ed4d7f9 100644 --- a/docs/source/yosys_internals/formats/cell_library.rst +++ b/docs/source/yosys_internals/formats/cell_library.rst @@ -258,7 +258,7 @@ additional two parameters: ``\ARST_VALUE`` The state of ``\Q`` will be set to this value when the reset is active. -Usually these cells are generated by the :cmd:ref:`proc` pass using the +Usually these cells are generated by the `proc` pass using the information in the designs RTLIL::Process objects. D-type flip-flops with synchronous reset are represented by `$sdff` cells. As @@ -472,7 +472,7 @@ synthesis to succeed. initialization conflict. The HDL frontend models a memory using ``RTLIL::Memory`` objects and -asynchronous `$memrd_v2` and `$memwr_v2` cells. The :cmd:ref:`memory` pass +asynchronous `$memrd_v2` and `$memwr_v2` cells. The `memory` pass (i.e. its various sub-passes) migrates `$dff` cells into the `$memrd_v2` and `$memwr_v2` cells making them synchronous, then converts them to a single `$mem_v2` cell and (optionally) maps this cell type to `$dff` cells for the @@ -604,14 +604,14 @@ The `$mem_v2` cell has the following ports: This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all data signals for the write ports. -The :cmd:ref:`memory_collect` pass can be used to convert discrete +The `memory_collect` pass can be used to convert discrete `$memrd_v2`, `$memwr_v2`, and `$meminit_v2` cells belonging to the same -memory to a single `$mem_v2` cell, whereas the :cmd:ref:`memory_unpack` pass -performs the inverse operation. The :cmd:ref:`memory_dff` pass can combine +memory to a single `$mem_v2` cell, whereas the `memory_unpack` pass +performs the inverse operation. The `memory_dff` pass can combine asynchronous memory ports that are fed by or feeding registers into synchronous -memory ports. The :cmd:ref:`memory_bram` pass can be used to recognize +memory ports. The `memory_bram` pass can be used to recognize `$mem_v2` cells that can be implemented with a block RAM resource on an FPGA. -The :cmd:ref:`memory_map` pass can be used to implement `$mem_v2` cells as +The `memory_map` pass can be used to implement `$mem_v2` cells as basic logic: word-wide DFFs and address decoders. Finite state machines diff --git a/docs/source/yosys_internals/formats/rtlil_rep.rst b/docs/source/yosys_internals/formats/rtlil_rep.rst index 785a2d28b..fec970532 100644 --- a/docs/source/yosys_internals/formats/rtlil_rep.rst +++ b/docs/source/yosys_internals/formats/rtlil_rep.rst @@ -76,7 +76,7 @@ This has three advantages: - Second, the information about which identifiers were originally provided by the user is always available which can help guide some optimizations. For - example, :cmd:ref:`opt_clean` tries to preserve signals with a user-provided + example, `opt_clean` tries to preserve signals with a user-provided name but doesn't hesitate to delete signals that have auto-generated names when they just duplicate other signals. Note that this can be overridden with the ``-purge`` option to also delete internal nets with user-provided @@ -320,7 +320,7 @@ trees before further processing them. One of the first actions performed on a design in RTLIL representation in most synthesis scripts is identifying asynchronous resets. This is usually done using -the :cmd:ref:`proc_arst` pass. This pass transforms the above example to the +the `proc_arst` pass. This pass transforms the above example to the following ``RTLIL::Process``: .. code:: RTLIL diff --git a/docs/source/yosys_internals/techmap.rst b/docs/source/yosys_internals/techmap.rst index e5d6972ee..f894394bb 100644 --- a/docs/source/yosys_internals/techmap.rst +++ b/docs/source/yosys_internals/techmap.rst @@ -1,7 +1,7 @@ Techmap by example ------------------ -As a quick recap, the :cmd:ref:`techmap` command replaces cells in the design +As a quick recap, the `techmap` command replaces cells in the design with implementations given as Verilog code (called "map files"). It can replace Yosys' internal cell types (such as `$or`) as well as user-defined cell types. @@ -87,14 +87,14 @@ Scripting in map modules - You can even call techmap recursively! - Example use-cases: - - Using always blocks in map module: call :cmd:ref:`proc` - - Perform expensive optimizations (such as :cmd:ref:`freduce`) on cells + - Using always blocks in map module: call `proc` + - Perform expensive optimizations (such as `freduce`) on cells where this is known to work well. - Interacting with custom commands. .. note:: PROTIP: - Commands such as :cmd:ref:`shell`, ``show -pause``, and :cmd:ref:`dump` can + Commands such as `shell`, ``show -pause``, and `dump` can be used in the ``_TECHMAP_DO_*`` scripts for debugging map modules. Example: From 40ba92e956461beb2a6369a638fcec050962a36d Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 3 May 2024 13:38:01 +1200 Subject: [PATCH 036/496] Docs: Reflow line length --- docs/source/getting_started/example_synth.rst | 314 +++++++-------- docs/source/getting_started/installation.rst | 5 +- .../getting_started/scripting_intro.rst | 56 ++- docs/source/introduction.rst | 26 +- .../interactive_investigation.rst | 219 +++++----- .../more_scripting/model_checking.rst | 3 +- .../using_yosys/more_scripting/selections.rst | 74 ++-- docs/source/using_yosys/synthesis/abc.rst | 11 +- .../using_yosys/synthesis/cell_libs.rst | 8 +- docs/source/using_yosys/synthesis/extract.rst | 28 +- docs/source/using_yosys/synthesis/fsm.rst | 31 +- docs/source/using_yosys/synthesis/index.rst | 15 +- docs/source/using_yosys/synthesis/memory.rst | 208 +++++----- docs/source/using_yosys/synthesis/opt.rst | 82 ++-- docs/source/using_yosys/synthesis/proc.rst | 18 +- .../extending_yosys/extensions.rst | 15 +- .../yosys_internals/flow/verilog_frontend.rst | 26 +- .../yosys_internals/formats/cell_library.rst | 373 +++++++++--------- .../yosys_internals/formats/rtlil_rep.rst | 47 ++- docs/source/yosys_internals/techmap.rst | 8 +- 20 files changed, 782 insertions(+), 785 deletions(-) diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst index ec1f967ea..f8530b45b 100644 --- a/docs/source/getting_started/example_synth.rst +++ b/docs/source/getting_started/example_synth.rst @@ -2,13 +2,12 @@ Synthesis starter ----------------- This page will be a guided walkthrough of the prepackaged iCE40 FPGA synthesis -script - `synth_ice40`. We will take a simple design through each -step, looking at the commands being called and what they do to the design. While -`synth_ice40` is specific to the iCE40 platform, most of the operations -we will be discussing are common across the majority of FPGA synthesis scripts. -Thus, this document will provide a good foundational understanding of how -synthesis in Yosys is performed, regardless of the actual architecture being -used. +script - `synth_ice40`. We will take a simple design through each step, looking +at the commands being called and what they do to the design. While `synth_ice40` +is specific to the iCE40 platform, most of the operations we will be discussing +are common across the majority of FPGA synthesis scripts. Thus, this document +will provide a good foundational understanding of how synthesis in Yosys is +performed, regardless of the actual architecture being used. .. seealso:: Advanced usage docs for :doc:`/using_yosys/synthesis/synth` @@ -105,10 +104,10 @@ Since we're just getting started, let's instead begin with :yoscrypt:`hierarchy .. note:: - `hierarchy` should always be the first command after the design has - been read. By specifying the top module, `hierarchy` will also set - the ``(* top *)`` attribute on it. This is used by other commands that need - to know which module is the top. + `hierarchy` should always be the first command after the design has been + read. By specifying the top module, `hierarchy` will also set the ``(* top + *)`` attribute on it. This is used by other commands that need to know which + module is the top. .. use doscon for a console-like display that supports the `yosys> [command]` format. @@ -129,20 +128,20 @@ Our ``addr_gen`` circuit now looks like this: Simple operations like ``addr + 1`` and ``addr == MAX_DATA-1`` can be extracted from our ``always @`` block in :ref:`addr_gen-v`. This gives us the highlighted -`$add` and `$eq` cells we see. But control logic (like the ``if .. else``) -and memory elements (like the ``addr <= 0``) are not so straightforward. These -get put into "processes", shown in the schematic as ``PROC``. Note how the -second line refers to the line numbers of the start/end of the corresponding -``always @`` block. In the case of an ``initial`` block, we instead see the -``PROC`` referring to line 0. +`$add` and `$eq` cells we see. But control logic (like the ``if .. else``) and +memory elements (like the ``addr <= 0``) are not so straightforward. These get +put into "processes", shown in the schematic as ``PROC``. Note how the second +line refers to the line numbers of the start/end of the corresponding ``always +@`` block. In the case of an ``initial`` block, we instead see the ``PROC`` +referring to line 0. -To handle these, let us now introduce the next command: :doc:`/cmd/proc`. -`proc` is a macro command like `synth_ice40`. Rather than -modifying the design directly, it instead calls a series of other commands. In -the case of `proc`, these sub-commands work to convert the behavioral -logic of processes into multiplexers and registers. Let's see what happens when -we run it. For now, we will call :yoscrypt:`proc -noopt` to prevent some -automatic optimizations which would normally happen. +To handle these, let us now introduce the next command: :doc:`/cmd/proc`. `proc` +is a macro command like `synth_ice40`. Rather than modifying the design +directly, it instead calls a series of other commands. In the case of `proc`, +these sub-commands work to convert the behavioral logic of processes into +multiplexers and registers. Let's see what happens when we run it. For now, we +will call :yoscrypt:`proc -noopt` to prevent some automatic optimizations which +would normally happen. .. figure:: /_images/code_examples/fifo/addr_gen_proc.* :class: width-helper invert-helper @@ -151,19 +150,18 @@ automatic optimizations which would normally happen. ``addr_gen`` module after :yoscrypt:`proc -noopt` There are now a few new cells from our ``always @``, which have been -highlighted. The ``if`` statements are now modeled with `$mux` cells, while -the register uses an `$adff` cell. If we look at the terminal output we can -also see all of the different ``proc_*`` commands being called. We will look at -each of these in more detail in :doc:`/using_yosys/synthesis/proc`. +highlighted. The ``if`` statements are now modeled with `$mux` cells, while the +register uses an `$adff` cell. If we look at the terminal output we can also +see all of the different ``proc_*`` commands being called. We will look at each +of these in more detail in :doc:`/using_yosys/synthesis/proc`. Notice how in the top left of :ref:`addr_gen_proc` we have a floating wire, generated from the initial assignment of 0 to the ``addr`` wire. However, this initial assignment is not synthesizable, so this will need to be cleaned up before we can generate the physical hardware. We can do this now by calling -`clean`. We're also going to call `opt_expr` now, which would -normally be called at the end of `proc`. We can call both commands at -the same time by separating them with a colon and space: :yoscrypt:`opt_expr; -clean`. +`clean`. We're also going to call `opt_expr` now, which would normally be +called at the end of `proc`. We can call both commands at the same time by +separating them with a colon and space: :yoscrypt:`opt_expr; clean`. .. figure:: /_images/code_examples/fifo/addr_gen_clean.* :class: width-helper invert-helper @@ -171,24 +169,24 @@ clean`. ``addr_gen`` module after :yoscrypt:`opt_expr; clean` -You may also notice that the highlighted `$eq` cell input of ``255`` has -changed to ``8'11111111``. Constant values are presented in the format +You may also notice that the highlighted `$eq` cell input of ``255`` has changed +to ``8'11111111``. Constant values are presented in the format ``'``, with 32-bit values instead using the decimal number. This indicates that the constant input has been reduced from 32-bit wide to -8-bit wide. This is a side-effect of running `opt_expr`, which -performs constant folding and simple expression rewriting. For more on why -this happens, refer to :doc:`/using_yosys/synthesis/opt` and the :ref:`section -on opt_expr `. +8-bit wide. This is a side-effect of running `opt_expr`, which performs +constant folding and simple expression rewriting. For more on why this +happens, refer to :doc:`/using_yosys/synthesis/opt` and the :ref:`section on +opt_expr `. .. note:: :doc:`/cmd/clean` can also be called with two semicolons after any command, for example we could have called :yoscrypt:`opt_expr;;` instead of :yoscrypt:`opt_expr; clean`. You may notice some scripts will end each line - with ``;;``. It is beneficial to run `clean` before inspecting - intermediate products to remove disconnected parts of the circuit which have - been left over, and in some cases can reduce the processing required in - subsequent commands. + with ``;;``. It is beneficial to run `clean` before inspecting intermediate + products to remove disconnected parts of the circuit which have been left + over, and in some cases can reduce the processing required in subsequent + commands. .. todo:: consider a brief glossary for terms like adff @@ -202,8 +200,8 @@ The full example Let's now go back and check on our full design by using :yoscrypt:`hierarchy -check -top fifo`. By passing the ``-check`` option there we are also telling -the `hierarchy` command that if the design includes any non-blackbox -modules without an implementation it should return an error. +the `hierarchy` command that if the design includes any non-blackbox modules +without an implementation it should return an error. Note that if we tried to run this command now then we would get an error. This is because we already removed all of the modules other than ``addr_gen``. We @@ -221,13 +219,12 @@ could restart our shell session, but instead let's use two new commands: Notice how this time we didn't see any of those ``$abstract`` modules? That's because when we ran ``yosys fifo.v``, the first command Yosys called was :yoscrypt:`read_verilog -defer fifo.v`. The ``-defer`` option there tells -`read_verilog` only read the abstract syntax tree and defer actual -compilation to a later `hierarchy` command. This is useful in cases -where the default parameters of modules yield invalid code which is not -synthesizable. This is why Yosys defers compilation automatically and is one of -the reasons why hierarchy should always be the first command after loading the -design. If we know that our design won't run into this issue, we can skip the -``-defer``. +`read_verilog` only read the abstract syntax tree and defer actual compilation +to a later `hierarchy` command. This is useful in cases where the default +parameters of modules yield invalid code which is not synthesizable. This is why +Yosys defers compilation automatically and is one of the reasons why hierarchy +should always be the first command after loading the design. If we know that +our design won't run into this issue, we can skip the ``-defer``. .. todo:: `hierarchy` failure modes @@ -243,13 +240,13 @@ design. If we know that our design won't run into this issue, we can skip the interactive terminal. :kbd:`ctrl+c` (i.e. SIGINT) will also end the terminal session but will return an error code rather than exiting gracefully. -We can also run `proc` now to finish off the full :ref:`synth_begin`. -Because the design schematic is quite large, we will be showing just the data -path for the ``rdata`` output. If you would like to see the entire design for -yourself, you can do so with :doc:`/cmd/show`. Note that the `show` -command only works with a single module, so you may need to call it with -:yoscrypt:`show fifo`. :ref:`show_intro` section in -:doc:`/getting_started/scripting_intro` has more on how to use `show`. +We can also run `proc` now to finish off the full :ref:`synth_begin`. Because +the design schematic is quite large, we will be showing just the data path for +the ``rdata`` output. If you would like to see the entire design for yourself, +you can do so with :doc:`/cmd/show`. Note that the `show` command only works +with a single module, so you may need to call it with :yoscrypt:`show fifo`. +:ref:`show_intro` section in :doc:`/getting_started/scripting_intro` has more on +how to use `show`. .. figure:: /_images/code_examples/fifo/rdata_proc.* :class: width-helper invert-helper @@ -321,11 +318,10 @@ merging happened during the call to `clean` which we can see in the output. Depending on the target architecture, this stage of synthesis might also see -commands such as `tribuf` with the ``-logic`` option and -`deminout`. These remove tristate and inout constructs respectively, -replacing them with logic suitable for mapping to an FPGA. Since we do not have -any such constructs in our example running these commands does not change our -design. +commands such as `tribuf` with the ``-logic`` option and `deminout`. These +remove tristate and inout constructs respectively, replacing them with logic +suitable for mapping to an FPGA. Since we do not have any such constructs in +our example running these commands does not change our design. The coarse-grain representation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -342,9 +338,9 @@ optimizations and other transformations done previously. .. note:: - While the iCE40 flow had a :ref:`synth_flatten` and put `proc` in - the :ref:`synth_begin`, some synthesis scripts will instead include these in - this section. + While the iCE40 flow had a :ref:`synth_flatten` and put `proc` in the + :ref:`synth_begin`, some synthesis scripts will instead include these in this + section. Part 1 ^^^^^^ @@ -359,24 +355,23 @@ In the iCE40 flow, we start with the following commands: :caption: ``coarse`` section (part 1) :name: synth_coarse1 -We've already come across `opt_expr`, and `opt_clean` is the -same as `clean` but with more verbose output. The `check` -pass identifies a few obvious problems which will cause errors later. Calling -it here lets us fail faster rather than wasting time on something we know is -impossible. +We've already come across `opt_expr`, and `opt_clean` is the same as `clean` but +with more verbose output. The `check` pass identifies a few obvious problems +which will cause errors later. Calling it here lets us fail faster rather than +wasting time on something we know is impossible. Next up is :yoscrypt:`opt -nodffe -nosdff` performing a set of simple optimizations on the design. This command also ensures that only a specific subset of FF types are included, in preparation for the next command: -:doc:`/cmd/fsm`. Both `opt` and `fsm` are macro commands -which are explored in more detail in :doc:`/using_yosys/synthesis/opt` and +:doc:`/cmd/fsm`. Both `opt` and `fsm` are macro commands which are explored in +more detail in :doc:`/using_yosys/synthesis/opt` and :doc:`/using_yosys/synthesis/fsm` respectively. Up until now, the data path for ``rdata`` has remained the same since :ref:`rdata_flat`. However the next call to `opt` does cause a change. -Specifically, the call to `opt_dff` without the ``-nodffe -nosdff`` -options is able to fold one of the `$mux` cells into the `$adff` to form an -`$adffe` cell; highlighted below: +Specifically, the call to `opt_dff` without the ``-nodffe -nosdff`` options is +able to fold one of the `$mux` cells into the `$adff` to form an `$adffe` cell; +highlighted below: .. literalinclude:: /code_examples/fifo/fifo.out :language: doscon @@ -433,8 +428,8 @@ The next two (new) commands are :doc:`/cmd/peepopt` and :doc:`/cmd/share`. Neither of these affect our design, and they're explored in more detail in :doc:`/using_yosys/synthesis/opt`, so let's skip over them. :yoscrypt:`techmap -map +/cmp2lut.v -D LUT_WIDTH=4` optimizes certain comparison operators by -converting them to LUTs instead. The usage of `techmap` is explored -more in :doc:`/using_yosys/synthesis/techmap_synth`. +converting them to LUTs instead. The usage of `techmap` is explored more in +:doc:`/using_yosys/synthesis/techmap_synth`. Our next command to run is :doc:`/cmd/memory_dff`. @@ -451,9 +446,9 @@ Our next command to run is ``rdata`` output after `memory_dff` -As the title suggests, `memory_dff` has merged the output `$dff` into -the `$memrd` cell and converted it to a `$memrd_v2` (highlighted). This has -also connected the ``CLK`` port to the ``clk`` input as it is now a synchronous +As the title suggests, `memory_dff` has merged the output `$dff` into the +`$memrd` cell and converted it to a `$memrd_v2` (highlighted). This has also +connected the ``CLK`` port to the ``clk`` input as it is now a synchronous memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and ``SRST=1'0``) inputs. @@ -466,12 +461,11 @@ memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and Part 3 ^^^^^^ -The third part of the `synth_ice40` flow is a series of commands for -mapping to DSPs. By default, the iCE40 flow will not map to the hardware DSP -blocks and will only be performed if called with the ``-dsp`` flag: -:yoscrypt:`synth_ice40 -dsp`. While our example has nothing that could be -mapped to DSPs we can still take a quick look at the commands here and describe -what they do. +The third part of the `synth_ice40` flow is a series of commands for mapping to +DSPs. By default, the iCE40 flow will not map to the hardware DSP blocks and +will only be performed if called with the ``-dsp`` flag: :yoscrypt:`synth_ice40 +-dsp`. While our example has nothing that could be mapped to DSPs we can still +take a quick look at the commands here and describe what they do. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -483,28 +477,26 @@ what they do. :yoscrypt:`wreduce t:$mul` performs width reduction again, this time targetting only cells of type `$mul`. :yoscrypt:`techmap -map +/mul2dsp.v -map -+/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses `techmap` to map -`$mul` cells to ``$__MUL16X16`` which are, in turn, mapped to the iCE40 -``SB_MAC16``. Any multipliers which aren't compatible with conversion to -``$__MUL16X16`` are relabelled to ``$__soft_mul`` before `chtype` -changes them back to `$mul`. ++/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses `techmap` to map `$mul` +cells to ``$__MUL16X16`` which are, in turn, mapped to the iCE40 ``SB_MAC16``. +Any multipliers which aren't compatible with conversion to ``$__MUL16X16`` are +relabelled to ``$__soft_mul`` before `chtype` changes them back to `$mul`. During the mul2dsp conversion, some of the intermediate signals are marked with the attribute ``mul2dsp``. By calling :yoscrypt:`select a:mul2dsp` we restrict the following commands to only operate on the cells and wires used for these signals. `setattr` removes the now unnecessary ``mul2dsp`` attribute. -`opt_expr` we've already come across for const folding and simple -expression rewriting, the ``-fine`` option just enables more fine-grain -optimizations. Then we perform width reduction a final time and clear the -selection. +`opt_expr` we've already come across for const folding and simple expression +rewriting, the ``-fine`` option just enables more fine-grain optimizations. +Then we perform width reduction a final time and clear the selection. .. todo:: ``ice40_dsp`` is pmgen -Finally we have `ice40_dsp`: similar to the `memory_dff` -command we saw in the previous section, this merges any surrounding registers -into the ``SB_MAC16`` cell. This includes not just the input/output registers, -but also pipeline registers and even a post-adder where applicable: turning a -multiply + add into a single multiply-accumulate. +Finally we have `ice40_dsp`: similar to the `memory_dff` command we saw in the +previous section, this merges any surrounding registers into the ``SB_MAC16`` +cell. This includes not just the input/output registers, but also pipeline +registers and even a post-adder where applicable: turning a multiply + add into +a single multiply-accumulate. .. seealso:: Advanced usage docs for :doc:`/using_yosys/synthesis/techmap_synth` @@ -522,11 +514,10 @@ That brings us to the fourth and final part for the iCE40 synthesis flow: :caption: ``coarse`` section (part 4) :name: synth_coarse4 -Where before each type of arithmetic operation had its own cell, e.g. `$add`, -we now want to extract these into `$alu` and `$macc` cells which can help -identify opportunities for reusing logic. We do this by running -`alumacc`, which we can see produce the following changes in our -example design: +Where before each type of arithmetic operation had its own cell, e.g. `$add`, we +now want to extract these into `$alu` and `$macc` cells which can help identify +opportunities for reusing logic. We do this by running `alumacc`, which we can +see produce the following changes in our example design: .. literalinclude:: /code_examples/fifo/fifo.out :language: doscon @@ -540,17 +531,17 @@ example design: ``rdata`` output after `alumacc` -Once these cells have been inserted, the call to `opt` can combine -cells which are now identical but may have been missed due to e.g. the -difference between `$add` and `$sub`. +Once these cells have been inserted, the call to `opt` can combine cells which +are now identical but may have been missed due to e.g. the difference between +`$add` and `$sub`. -The other new command in this part is :doc:`/cmd/memory`. `memory` is -another macro command which we examine in more detail in +The other new command in this part is :doc:`/cmd/memory`. `memory` is another +macro command which we examine in more detail in :doc:`/using_yosys/synthesis/memory`. For this document, let us focus just on -the step most relevant to our example: `memory_collect`. Up until this -point, our memory reads and our memory writes have been totally disjoint cells; -operating on the same memory only in the abstract. `memory_collect` -combines all of the reads and writes for a memory block into a single cell. +the step most relevant to our example: `memory_collect`. Up until this point, +our memory reads and our memory writes have been totally disjoint cells; +operating on the same memory only in the abstract. `memory_collect` combines all +of the reads and writes for a memory block into a single cell. .. figure:: /_images/code_examples/fifo/rdata_coarse.* :class: width-helper invert-helper @@ -609,19 +600,19 @@ Mapping to hard memory blocks uses a combination of `memory_libmap` and ``rdata`` output after :ref:`map_ram` -The :ref:`map_ram` converts the generic `$mem_v2` into the iCE40 -``SB_RAM40_4K`` (highlighted). We can also see the memory address has been -remapped, and the data bits have been reordered (or swizzled). There is also -now a `$mux` cell controlling the value of ``rdata``. In :ref:`fifo-v` we -wrote our memory as read-before-write, however the ``SB_RAM40_4K`` has undefined -behaviour when reading from and writing to the same address in the same cycle. -As a result, extra logic is added so that the generated circuit matches the -behaviour of the verilog. :ref:`no_rw_check` describes how we could change our -verilog to match our hardware instead. +The :ref:`map_ram` converts the generic `$mem_v2` into the iCE40 ``SB_RAM40_4K`` +(highlighted). We can also see the memory address has been remapped, and the +data bits have been reordered (or swizzled). There is also now a `$mux` cell +controlling the value of ``rdata``. In :ref:`fifo-v` we wrote our memory as +read-before-write, however the ``SB_RAM40_4K`` has undefined behaviour when +reading from and writing to the same address in the same cycle. As a result, +extra logic is added so that the generated circuit matches the behaviour of the +verilog. :ref:`no_rw_check` describes how we could change our verilog to match +our hardware instead. -If we run `memory_libmap` under the `debug` command we can see -candidates which were identified for mapping, along with the costs of each and -what logic requires emulation. +If we run `memory_libmap` under the `debug` command we can see candidates which +were identified for mapping, along with the costs of each and what logic +requires emulation. .. literalinclude:: /code_examples/fifo/fifo.libmap :language: doscon @@ -667,11 +658,10 @@ into flip flops (the ``logic fallback``) with `memory_map`. Arithmetic ^^^^^^^^^^ -Uses `techmap` to map basic arithmetic logic to hardware. This sees -somewhat of an explosion in cells as multi-bit :cell:ref:`$mux` and `$adffe` are -replaced with single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the -:cell:ref:`$alu` is replaced with primitive `$_OR_` and `$_NOT_` gates and a -`$lut` cell. +Uses `techmap` to map basic arithmetic logic to hardware. This sees somewhat of +an explosion in cells as multi-bit `$mux` and `$adffe` are replaced with +single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the `$alu` is replaced with +primitive `$_OR_` and `$_NOT_` gates and a `$lut` cell. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -693,12 +683,12 @@ replaced with single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the Flip-flops ^^^^^^^^^^ -Convert FFs to the types supported in hardware with `dfflegalize`, and -then use `techmap` to map them. In our example, this converts the -`$_DFFE_PP0P_` cells to ``SB_DFFER``. +Convert FFs to the types supported in hardware with `dfflegalize`, and then use +`techmap` to map them. In our example, this converts the `$_DFFE_PP0P_` cells +to ``SB_DFFER``. -We also run `simplemap` here to convert any remaining cells which could -not be mapped to hardware into gate-level primitives. This includes optimizing +We also run `simplemap` here to convert any remaining cells which could not be +mapped to hardware into gate-level primitives. This includes optimizing `$_MUX_` cells where one of the inputs is a constant ``1'0``, replacing it instead with an `$_AND_` cell. @@ -722,11 +712,10 @@ instead with an `$_AND_` cell. LUTs ^^^^ -`abc` and `techmap` are used to map LUTs; converting primitive -cell types to use `$lut` and ``SB_CARRY`` cells. Note that the iCE40 flow -uses `abc9` rather than `abc`. For more on what these do, and -what the difference between these two commands are, refer to -:doc:`/using_yosys/synthesis/abc`. +`abc` and `techmap` are used to map LUTs; converting primitive cell types to use +`$lut` and ``SB_CARRY`` cells. Note that the iCE40 flow uses `abc9` rather than +`abc`. For more on what these do, and what the difference between these two +commands are, refer to :doc:`/using_yosys/synthesis/abc`. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -742,8 +731,8 @@ what the difference between these two commands are, refer to ``rdata`` output after :ref:`map_luts` -Finally we use `techmap` to map the generic `$lut` cells to iCE40 -``SB_LUT4`` cells. +Finally we use `techmap` to map the generic `$lut` cells to iCE40 ``SB_LUT4`` +cells. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -801,28 +790,27 @@ The new commands here are: - :doc:`/cmd/stat`, and - :doc:`/cmd/blackbox`. -The output from `stat` is useful for checking resource utilization; -providing a list of cells used in the design and the number of each, as well as -the number of other resources used such as wires and processes. For this -design, the final call to `stat` should look something like the -following: +The output from `stat` is useful for checking resource utilization; providing a +list of cells used in the design and the number of each, as well as the number +of other resources used such as wires and processes. For this design, the final +call to `stat` should look something like the following: .. literalinclude:: /code_examples/fifo/fifo.stat :language: doscon :start-at: yosys> stat -top fifo -Note that the :yoscrypt:`-top fifo` here is optional. `stat` will -automatically use the module with the ``top`` attribute set, which ``fifo`` was -when we called `hierarchy`. If no module is marked ``top``, then stats -will be shown for each module selected. +Note that the :yoscrypt:`-top fifo` here is optional. `stat` will automatically +use the module with the ``top`` attribute set, which ``fifo`` was when we called +`hierarchy`. If no module is marked ``top``, then stats will be shown for each +module selected. -The `stat` output is also useful as a kind of sanity-check: Since we -have already run `proc`, we wouldn't expect there to be any processes. -We also expect ``data`` to use hard memory; if instead of an ``SB_RAM40_4K`` saw -a high number of flip-flops being used we might suspect something was wrong. +The `stat` output is also useful as a kind of sanity-check: Since we have +already run `proc`, we wouldn't expect there to be any processes. We also expect +``data`` to use hard memory; if instead of an ``SB_RAM40_4K`` saw a high number +of flip-flops being used we might suspect something was wrong. -If we instead called `stat` immediately after :yoscrypt:`read_verilog -fifo.v` we would see something very different: +If we instead called `stat` immediately after :yoscrypt:`read_verilog fifo.v` we +would see something very different: .. literalinclude:: /code_examples/fifo/fifo.stat :language: doscon @@ -845,10 +833,10 @@ The iCE40 synthesis flow has the following output modes available: As an example, if we called :yoscrypt:`synth_ice40 -top fifo -json fifo.json`, our synthesized ``fifo`` design will be output as :file:`fifo.json`. We can -then read the design back into Yosys with `read_json`, but make sure -you use :yoscrypt:`design -reset` or open a new interactive terminal first. The -JSON output we get can also be loaded into `nextpnr`_ to do place and route; but -that is beyond the scope of this documentation. +then read the design back into Yosys with `read_json`, but make sure you use +:yoscrypt:`design -reset` or open a new interactive terminal first. The JSON +output we get can also be loaded into `nextpnr`_ to do place and route; but that +is beyond the scope of this documentation. .. _nextpnr: https://github.com/YosysHQ/nextpnr diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst index 8ed7cebb8..5fed508ed 100644 --- a/docs/source/getting_started/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -184,9 +184,8 @@ directories: ``passes/`` This directory contains a subdirectory for each pass or group of passes. For - example as of this writing the directory :file:`passes/hierarchy/` contains the - code for three passes: `hierarchy`, `submod`, and - `uniquify`. + example as of this writing the directory :file:`passes/hierarchy/` contains + the code for three passes: `hierarchy`, `submod`, and `uniquify`. ``techlibs/`` This directory contains simulation models and standard implementations for diff --git a/docs/source/getting_started/scripting_intro.rst b/docs/source/getting_started/scripting_intro.rst index ef728e1cf..01954c661 100644 --- a/docs/source/getting_started/scripting_intro.rst +++ b/docs/source/getting_started/scripting_intro.rst @@ -61,24 +61,23 @@ already, let's take a look at some of those script files now. :caption: A section of :file:`fifo.ys`, generating the images used for :ref:`addr_gen_example` :name: fifo-ys -The first command there, :yoscrypt:`echo on`, uses `echo` to enable -command echoes on. This is how we generated the code listing for +The first command there, :yoscrypt:`echo on`, uses `echo` to enable command +echoes on. This is how we generated the code listing for :ref:`hierarchy_output`. Turning command echoes on prints the ``yosys> hierarchy -top addr_gen`` line, making the output look the same as if it were an interactive terminal. :yoscrypt:`hierarchy -top addr_gen` is of course the command we were demonstrating, including the output text and an image of the design schematic after running it. -We briefly touched on `select` when it came up in -`synth_ice40`, but let's look at it more now. +We briefly touched on `select` when it came up in `synth_ice40`, but let's look +at it more now. .. _select_intro: Selections intro ^^^^^^^^^^^^^^^^ -The `select` command is used to modify and view the list of selected -objects: +The `select` command is used to modify and view the list of selected objects: .. literalinclude:: /code_examples/fifo/fifo.out :language: doscon @@ -118,8 +117,8 @@ statement. Many commands also support an optional ``[selection]`` argument which can be used to override the currently selected objects. We could, for example, call -:yoscrypt:`clean addr_gen` to have `clean` operate on *just* the -``addr_gen`` module. +:yoscrypt:`clean addr_gen` to have `clean` operate on *just* the ``addr_gen`` +module. Detailed documentation of the select framework can be found under :doc:`/using_yosys/more_scripting/selections` or in the command reference at @@ -130,11 +129,11 @@ Detailed documentation of the select framework can be found under Displaying schematics ^^^^^^^^^^^^^^^^^^^^^ -While the `select` command is very useful, sometimes nothing beats -being able to see a design for yourself. This is where `show` comes -in. Note that this document is just an introduction to the `show` -command, only covering the basics. For more information, including a guide on -what the different symbols represent, see :ref:`interactive_show` and the +While the `select` command is very useful, sometimes nothing beats being able to +see a design for yourself. This is where `show` comes in. Note that this +document is just an introduction to the `show` command, only covering the +basics. For more information, including a guide on what the different symbols +represent, see :ref:`interactive_show` and the :doc:`/using_yosys/more_scripting/interactive_investigation` page. .. figure:: /_images/code_examples/fifo/addr_gen_show.* @@ -145,8 +144,8 @@ what the different symbols represent, see :ref:`interactive_show` and the .. note:: - The `show` command requires a working installation of `GraphViz`_ - and `xdot`_ for displaying the actual circuit diagrams. + The `show` command requires a working installation of `GraphViz`_ and `xdot`_ + for displaying the actual circuit diagrams. .. _GraphViz: http://www.graphviz.org/ .. _xdot: https://github.com/jrfonseca/xdot.py @@ -160,8 +159,8 @@ we see the following: :start-at: -prefix addr_gen_show :end-before: yosys> show -Calling `show` with :yoscrypt:`-format dot` tells it we want to output -a :file:`.dot` file rather than opening it for display. The :yoscrypt:`-prefix +Calling `show` with :yoscrypt:`-format dot` tells it we want to output a +:file:`.dot` file rather than opening it for display. The :yoscrypt:`-prefix addr_gen_show` option indicates we want the file to be called :file:`addr_gen_show.{*}`. Remember, we do this in :file:`fifo.ys` because we need to store the image for displaying in the documentation you're reading. But @@ -207,21 +206,20 @@ the two ``PROC`` blocks. To achieve this highlight, we make use of the Calling :yoscrypt:`show -color maroon3 @new_cells -color cornflowerblue p:* -notitle` -As described in the the `help` output for `show` (or by -clicking on the `show` link), colors are specified as :yoscrypt:`-color - `. Color names for the ```` portion can be found on the -`GraphViz color docs`_. Unlike the final `show` parameter which can -have be any selection string, the ```` part must be a single selection -expression or named selection. That means while we can use ``@new_cells``, we -couldn't use ``t:$eq t:$add``. In general, if a command lists ``[selection]`` -as its final parameter it can be any selection string. Any selections that are -not the final parameter, such as those used in options, must be a single -expression instead. +As described in the the `help` output for `show` (or by clicking on the `show` +link), colors are specified as :yoscrypt:`-color `. Color names +for the ```` portion can be found on the `GraphViz color docs`_. Unlike +the final `show` parameter which can have be any selection string, the +```` part must be a single selection expression or named selection. +That means while we can use ``@new_cells``, we couldn't use ``t:$eq t:$add``. +In general, if a command lists ``[selection]`` as its final parameter it can be +any selection string. Any selections that are not the final parameter, such as +those used in options, must be a single expression instead. .. _GraphViz color docs: https://graphviz.org/doc/info/colors -For all of the options available to `show`, check the command reference -at :doc:`/cmd/show`. +For all of the options available to `show`, check the command reference at +:doc:`/cmd/show`. .. seealso:: :ref:`interactive_show` on the :doc:`/using_yosys/more_scripting/interactive_investigation` page. diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 1d9cd0080..7261d8edb 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -161,9 +161,9 @@ Benefits of open source HDL synthesis - Cost (also applies to ``free as in free beer`` solutions): - Today the cost for a mask set in 180nm technology is far less than - the cost for the design tools needed to design the mask layouts. Open Source - ASIC flows are an important enabler for ASIC-level Open Source Hardware. + Today the cost for a mask set in 180nm technology is far less than the cost + for the design tools needed to design the mask layouts. Open Source ASIC flows + are an important enabler for ASIC-level Open Source Hardware. - Availability and Reproducibility: @@ -171,21 +171,23 @@ Benefits of open source HDL synthesis else can also use. Even if most universities have access to all major commercial tools, you usually do not have easy access to the version that was used in a research project a couple of years ago. With Open Source tools you - can even release the source code of the tool you have used alongside your data. + can even release the source code of the tool you have used alongside your + data. - Framework: - Yosys is not only a tool. It is a framework that can be used as basis for other - developments, so researchers and hackers alike do not need to re-invent the - basic functionality. Extensibility was one of Yosys' design goals. + Yosys is not only a tool. It is a framework that can be used as basis for + other developments, so researchers and hackers alike do not need to re-invent + the basic functionality. Extensibility was one of Yosys' design goals. - All-in-one: - Because of the framework characteristics of Yosys, an increasing number of features - become available in one tool. Yosys not only can be used for circuit synthesis but - also for formal equivalence checking, SAT solving, and for circuit analysis, to - name just a few other application domains. With proprietary software one needs to - learn a new tool for each of these applications. + Because of the framework characteristics of Yosys, an increasing number of + features become available in one tool. Yosys not only can be used for circuit + synthesis but also for formal equivalence checking, SAT solving, and for + circuit analysis, to name just a few other application domains. With + proprietary software one needs to learn a new tool for each of these + applications. - Educational Tool: diff --git a/docs/source/using_yosys/more_scripting/interactive_investigation.rst b/docs/source/using_yosys/more_scripting/interactive_investigation.rst index f2e3d5219..f078ed59e 100644 --- a/docs/source/using_yosys/more_scripting/interactive_investigation.rst +++ b/docs/source/using_yosys/more_scripting/interactive_investigation.rst @@ -13,9 +13,9 @@ A look at the show command .. TODO:: merge into :doc:`/getting_started/scripting_intro` show section -This section explores the `show` command and explains the symbols used -in the circuit diagrams generated by it. The code used is included in the Yosys -code base under |code_examples/show|_. +This section explores the `show` command and explains the symbols used in the +circuit diagrams generated by it. The code used is included in the Yosys code +base under |code_examples/show|_. .. |code_examples/show| replace:: :file:`docs/source/code_examples/show` .. _code_examples/show: https://github.com/YosysHQ/yosys/tree/main/docs/source/code_examples/show @@ -32,11 +32,10 @@ will use to demonstrate the usage of `show` in a simple setting. :name: example_v The Yosys synthesis script we will be running is included as -:numref:`example_ys`. Note that `show` is called with the ``-pause`` -option, that halts execution of the Yosys script until the user presses the -Enter key. Using :yoscrypt:`show -pause` also allows the user to enter an -interactive shell to further investigate the circuit before continuing -synthesis. +:numref:`example_ys`. Note that `show` is called with the ``-pause`` option, +that halts execution of the Yosys script until the user presses the Enter key. +Using :yoscrypt:`show -pause` also allows the user to enter an interactive shell +to further investigate the circuit before continuing synthesis. .. literalinclude:: /code_examples/show/example_show.ys :language: yoscrypt @@ -95,19 +94,19 @@ multiplexer and a d-type flip-flop, which brings us to the second diagram: The Rhombus shape to the right is a dangling wire. (Wire nodes are only shown if they are dangling or have "public" names, for example names assigned from the Verilog input.) Also note that the design now contains two instances of a -``BUF``-node. These are artefacts left behind by the `proc` command. It -is quite usual to see such artefacts after calling commands that perform changes -in the design, as most commands only care about doing the transformation in the -least complicated way, not about cleaning up after them. The next call to -`clean` (or `opt`, which includes `clean` as one of -its operations) will clean up these artefacts. This operation is so common in -Yosys scripts that it can simply be abbreviated with the ``;;`` token, which -doubles as separator for commands. Unless one wants to specifically analyze this -artefacts left behind some operations, it is therefore recommended to always -call `clean` before calling `show`. +``BUF``-node. These are artefacts left behind by the `proc` command. It is quite +usual to see such artefacts after calling commands that perform changes in the +design, as most commands only care about doing the transformation in the least +complicated way, not about cleaning up after them. The next call to `clean` (or +`opt`, which includes `clean` as one of its operations) will clean up these +artefacts. This operation is so common in Yosys scripts that it can simply be +abbreviated with the ``;;`` token, which doubles as separator for commands. +Unless one wants to specifically analyze this artefacts left behind some +operations, it is therefore recommended to always call `clean` before calling +`show`. -In this script we directly call `opt` as the next step, which finally -leads us to the third diagram: +In this script we directly call `opt` as the next step, which finally leads us +to the third diagram: .. figure:: /_images/code_examples/show/example_third.* :class: width-helper invert-helper @@ -115,9 +114,9 @@ leads us to the third diagram: Output of the third `show` command in :ref:`example_ys` -Here we see that the `opt` command not only has removed the artifacts -left behind by `proc`, but also determined correctly that it can remove -the first `$mux` cell without changing the behavior of the circuit. +Here we see that the `opt` command not only has removed the artifacts left +behind by `proc`, but also determined correctly that it can remove the first +`$mux` cell without changing the behavior of the circuit. Break-out boxes for signal vectors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -188,8 +187,8 @@ individual bits, resulting in an unnecessary complex diagram. :class: width-helper invert-helper :name: second_pitfall - Effects of `splitnets` command and of providing a cell library on - design in :numref:`first_pitfall` + Effects of `splitnets` command and of providing a cell library on design in + :numref:`first_pitfall` .. literalinclude:: /code_examples/show/cmos.ys :language: yoscrypt @@ -201,8 +200,8 @@ individual bits, resulting in an unnecessary complex diagram. For :numref:`second_pitfall`, Yosys has been given a description of the cell library as Verilog file containing blackbox modules. There are two ways to load cell descriptions into Yosys: First the Verilog file for the cell library can be -passed directly to the `show` command using the ``-lib `` -option. Secondly it is possible to load cell libraries into the design with the +passed directly to the `show` command using the ``-lib `` option. +Secondly it is possible to load cell libraries into the design with the :yoscrypt:`read_verilog -lib ` command. The second method has the great advantage that the library only needs to be loaded once and can then be used in all subsequent calls to the `show` command. @@ -216,19 +215,19 @@ module ports. Per default the command only operates on interior signals. Miscellaneous notes ^^^^^^^^^^^^^^^^^^^ -Per default the `show` command outputs a temporary dot file and -launches ``xdot`` to display it. The options ``-format``, ``-viewer`` and -``-prefix`` can be used to change format, viewer and filename prefix. Note that -the ``pdf`` and ``ps`` format are the only formats that support plotting -multiple modules in one run. The ``dot`` format can be used to output multiple -modules, however ``xdot`` will raise an error when trying to read them. +Per default the `show` command outputs a temporary dot file and launches +``xdot`` to display it. The options ``-format``, ``-viewer`` and ``-prefix`` can +be used to change format, viewer and filename prefix. Note that the ``pdf`` and +``ps`` format are the only formats that support plotting multiple modules in one +run. The ``dot`` format can be used to output multiple modules, however +``xdot`` will raise an error when trying to read them. In densely connected circuits it is sometimes hard to keep track of the -individual signal wires. For these cases it can be useful to call -`show` with the ``-colors `` argument, which randomly assigns -colors to the nets. The integer (> 0) is used as seed value for the random color -assignments. Sometimes it is necessary it try some values to find an assignment -of colors that looks good. +individual signal wires. For these cases it can be useful to call `show` with +the ``-colors `` argument, which randomly assigns colors to the nets. +The integer (> 0) is used as seed value for the random color assignments. +Sometimes it is necessary it try some values to find an assignment of colors +that looks good. The command :yoscrypt:`help show` prints a complete listing of all options supported by the `show` command. @@ -244,10 +243,10 @@ relevant portions of the circuit. In addition to *what* to display one also needs to carefully decide *when* to display it, with respect to the synthesis flow. In general it is a good idea to troubleshoot a circuit in the earliest state in which a problem can be -reproduced. So if, for example, the internal state before calling the -`techmap` command already fails to verify, it is better to troubleshoot -the coarse-grain version of the circuit before `techmap` than the -gate-level circuit after `techmap`. +reproduced. So if, for example, the internal state before calling the `techmap` +command already fails to verify, it is better to troubleshoot the coarse-grain +version of the circuit before `techmap` than the gate-level circuit after +`techmap`. .. Note:: @@ -260,18 +259,17 @@ Interactive navigation ^^^^^^^^^^^^^^^^^^^^^^ Once the right state within the synthesis flow for debugging the circuit has -been identified, it is recommended to simply add the `shell` command to -the matching place in the synthesis script. This command will stop the synthesis -at the specified moment and go to shell mode, where the user can interactively +been identified, it is recommended to simply add the `shell` command to the +matching place in the synthesis script. This command will stop the synthesis at +the specified moment and go to shell mode, where the user can interactively enter commands. For most cases, the shell will start with the whole design selected (i.e. when -the synthesis script does not already narrow the selection). The command -`ls` can now be used to create a list of all modules. The command -`cd` can be used to switch to one of the modules (type ``cd ..`` to -switch back). Now the `ls` command lists the objects within that -module. This is demonstrated below using :file:`example.v` from `A simple -circuit`_: +the synthesis script does not already narrow the selection). The command `ls` +can now be used to create a list of all modules. The command `cd` can be used to +switch to one of the modules (type ``cd ..`` to switch back). Now the `ls` +command lists the objects within that module. This is demonstrated below using +:file:`example.v` from `A simple circuit`_: .. literalinclude:: /code_examples/show/example.out :language: doscon @@ -280,11 +278,10 @@ circuit`_: :caption: Output of `ls` and `cd` after running :file:`yosys example.v` :name: lscd -When a module is selected using the `cd` command, all commands (with a -few exceptions, such as the ``read_`` and ``write_`` commands) operate only on -the selected module. This can also be useful for synthesis scripts where -different synthesis strategies should be applied to different modules in the -design. +When a module is selected using the `cd` command, all commands (with a few +exceptions, such as the ``read_`` and ``write_`` commands) operate only on the +selected module. This can also be useful for synthesis scripts where different +synthesis strategies should be applied to different modules in the design. We can see that the cell names from :numref:`example_out` are just abbreviations of the actual cell names, namely the part after the last dollar-sign. Most @@ -292,15 +289,14 @@ auto-generated names (the ones starting with a dollar sign) are rather long and contains some additional information on the origin of the named object. But in most cases those names can simply be abbreviated using the last part. -Usually all interactive work is done with one module selected using the -`cd` command. But it is also possible to work from the design-context -(``cd ..``). In this case all object names must be prefixed with -``/``. For example ``a*/b*`` would refer to all objects whose names -start with ``b`` from all modules whose names start with ``a``. +Usually all interactive work is done with one module selected using the `cd` +command. But it is also possible to work from the design-context (``cd ..``). In +this case all object names must be prefixed with ``/``. For example +``a*/b*`` would refer to all objects whose names start with ``b`` from all +modules whose names start with ``a``. -The `dump` command can be used to print all information about an -object. For example, calling :yoscrypt:`dump $2` after the :yoscrypt:`cd -example` above: +The `dump` command can be used to print all information about an object. For +example, calling :yoscrypt:`dump $2` after the :yoscrypt:`cd example` above: .. literalinclude:: /code_examples/show/example.out :language: RTLIL @@ -323,11 +319,10 @@ tools). - The selection mechanism, especially patterns such as ``%ci`` and ``%co``, can be used to figure out how parts of the design are connected. -- Commands such as `submod`, `expose`, and `splice` - can be used to transform the design into an equivalent design that is easier - to analyse. -- Commands such as `eval` and `sat` can be used to investigate - the behavior of the circuit. +- Commands such as `submod`, `expose`, and `splice` can be used to transform the + design into an equivalent design that is easier to analyse. +- Commands such as `eval` and `sat` can be used to investigate the behavior of + the circuit. - :doc:`/cmd/show`. - :doc:`/cmd/dump`. - :doc:`/cmd/add` and :doc:`/cmd/delete` can be used to modify and reorganize a @@ -342,9 +337,9 @@ The code used is included in the Yosys code base under Changing design hierarchy ^^^^^^^^^^^^^^^^^^^^^^^^^ -Commands such as `flatten` and `submod` can be used to change -the design hierarchy, i.e. flatten the hierarchy or moving parts of a module to -a submodule. This has applications in synthesis scripts as well as in reverse +Commands such as `flatten` and `submod` can be used to change the design +hierarchy, i.e. flatten the hierarchy or moving parts of a module to a +submodule. This has applications in synthesis scripts as well as in reverse engineering and analysis. An example using `submod` is shown below for reorganizing a module in Yosys and checking the resulting circuit. @@ -388,10 +383,10 @@ Analyzing the resulting circuit with :doc:`/cmd/eval`: Behavioral changes ^^^^^^^^^^^^^^^^^^ -Commands such as `techmap` can be used to make behavioral changes to -the design, for example changing asynchronous resets to synchronous resets. This -has applications in design space exploration (evaluation of various -architectures for one circuit). +Commands such as `techmap` can be used to make behavioral changes to the design, +for example changing asynchronous resets to synchronous resets. This has +applications in design space exploration (evaluation of various architectures +for one circuit). The following techmap map file replaces all positive-edge async reset flip-flops with positive-edge sync reset flip-flops. The code is taken from the example @@ -448,8 +443,8 @@ Recall the ``memdemo`` design from :ref:`advanced_logic_cones`: Because this produces a rather large circuit, it can be useful to split it into smaller parts for viewing and working with. :numref:`submod` does exactly that, -utilising the `submod` command to split the circuit into three -sections: ``outstage``, ``selstage``, and ``scramble``. +utilising the `submod` command to split the circuit into three sections: +``outstage``, ``selstage``, and ``scramble``. .. literalinclude:: /code_examples/selections/submod.ys :language: yoscrypt @@ -481,9 +476,9 @@ below. Evaluation of combinatorial circuits ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The `eval` command can be used to evaluate combinatorial circuits. As -an example, we will use the ``selstage`` subnet of ``memdemo`` which we found -above and is shown in :numref:`selstage`. +The `eval` command can be used to evaluate combinatorial circuits. As an +example, we will use the ``selstage`` subnet of ``memdemo`` which we found above +and is shown in :numref:`selstage`. .. todo:: replace inline code @@ -526,21 +521,21 @@ The ``-table`` option can be used to create a truth table. For example: Assumed undef (x) value for the following signals: \s2 -Note that the `eval` command (as well as the `sat` command -discussed in the next sections) does only operate on flattened modules. It can -not analyze signals that are passed through design hierarchy levels. So the -`flatten` command must be used on modules that instantiate other -modules before these commands can be applied. +Note that the `eval` command (as well as the `sat` command discussed in the next +sections) does only operate on flattened modules. It can not analyze signals +that are passed through design hierarchy levels. So the `flatten` command must +be used on modules that instantiate other modules before these commands can be +applied. Solving combinatorial SAT problems ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Often the opposite of the `eval` command is needed, i.e. the circuits -output is given and we want to find the matching input signals. For small -circuits with only a few input bits this can be accomplished by trying all -possible input combinations, as it is done by the ``eval -table`` command. For -larger circuits however, Yosys provides the `sat` command that uses a -`SAT`_ solver, `MiniSAT`_, to solve this kind of problems. +Often the opposite of the `eval` command is needed, i.e. the circuits output is +given and we want to find the matching input signals. For small circuits with +only a few input bits this can be accomplished by trying all possible input +combinations, as it is done by the ``eval -table`` command. For larger circuits +however, Yosys provides the `sat` command that uses a `SAT`_ solver, `MiniSAT`_, +to solve this kind of problems. .. _SAT: http://en.wikipedia.org/wiki/Circuit_satisfiability @@ -551,9 +546,9 @@ larger circuits however, Yosys provides the `sat` command that uses a While it is possible to perform model checking directly in Yosys, it is highly recommended to use SBY or EQY for formal hardware verification. -The `sat` command works very similar to the `eval` command. -The main difference is that it is now also possible to set output values and -find the corresponding input values. For Example: +The `sat` command works very similar to the `eval` command. The main difference +is that it is now also possible to set output values and find the corresponding +input values. For Example: .. todo:: replace inline code @@ -580,8 +575,8 @@ find the corresponding input values. For Example: \s1 0 0 00 \s2 0 0 00 -Note that the `sat` command supports signal names in both arguments to -the ``-set`` option. In the above example we used ``-set s1 s2`` to constraint +Note that the `sat` command supports signal names in both arguments to the +``-set`` option. In the above example we used ``-set s1 s2`` to constraint ``s1`` and ``s2`` to be equal. When more complex constraints are needed, a wrapper circuit must be constructed that checks the constraints and signals if the constraint was met using an extra output port, which then can be forced to a @@ -642,8 +637,8 @@ of course be to perform the test in 32 bits, for example by replacing ``p != a*b`` in the miter with ``p != {16'd0,a}b``, or by using a temporary variable for the 32 bit product ``a*b``. But as 31 fits well into 8 bits (and as the purpose of this document is to show off Yosys features) we can also simply force -the upper 8 bits of ``a`` and ``b`` to zero for the `sat` call, as is -done below. +the upper 8 bits of ``a`` and ``b`` to zero for the `sat` call, as is done +below. .. todo:: replace inline code @@ -705,18 +700,18 @@ command: sat -seq 6 -show y -show d -set-init-undef \ -max_undef -set-at 4 y 1 -set-at 5 y 2 -set-at 6 y 3 -The ``-seq 6`` option instructs the `sat` command to solve a sequential -problem in 6 time steps. (Experiments with lower number of steps have show that -at least 3 cycles are necessary to bring the circuit in a state from which the -sequence 1, 2, 3 can be produced.) +The ``-seq 6`` option instructs the `sat` command to solve a sequential problem +in 6 time steps. (Experiments with lower number of steps have show that at least +3 cycles are necessary to bring the circuit in a state from which the sequence +1, 2, 3 can be produced.) -The ``-set-init-undef`` option tells the `sat` command to initialize -all registers to the undef (``x``) state. The way the ``x`` state is treated in +The ``-set-init-undef`` option tells the `sat` command to initialize all +registers to the undef (``x``) state. The way the ``x`` state is treated in Verilog will ensure that the solution will work for any initial state. -The ``-max_undef`` option instructs the `sat` command to find a -solution with a maximum number of undefs. This way we can see clearly which -inputs bits are relevant to the solution. +The ``-max_undef`` option instructs the `sat` command to find a solution with a +maximum number of undefs. This way we can see clearly which inputs bits are +relevant to the solution. Finally the three ``-set-at`` options add constraints for the ``y`` signal to play the 1, 2, 3 sequence, starting with time step 4. @@ -807,7 +802,7 @@ is the only way of setting the ``s1`` and ``s2`` registers to a known value. The input values for the other steps are a bit harder to work out manually, but the SAT solver finds the correct solution in an instant. -There is much more to write about the `sat` command. For example, there -is a set of options that can be used to performs sequential proofs using -temporal induction :cite:p:`een2003temporal`. The command ``help sat`` can be -used to print a list of all options with short descriptions of their functions. +There is much more to write about the `sat` command. For example, there is a set +of options that can be used to performs sequential proofs using temporal +induction :cite:p:`een2003temporal`. The command ``help sat`` can be used to +print a list of all options with short descriptions of their functions. diff --git a/docs/source/using_yosys/more_scripting/model_checking.rst b/docs/source/using_yosys/more_scripting/model_checking.rst index 88eeb9bcd..799c99b6f 100644 --- a/docs/source/using_yosys/more_scripting/model_checking.rst +++ b/docs/source/using_yosys/more_scripting/model_checking.rst @@ -17,8 +17,7 @@ passes in Yosys. Other applications include checking if a module conforms to interface standards. -The `sat` command in Yosys can be used to perform Symbolic Model -Checking. +The `sat` command in Yosys can be used to perform Symbolic Model Checking. Checking techmap ~~~~~~~~~~~~~~~~ diff --git a/docs/source/using_yosys/more_scripting/selections.rst b/docs/source/using_yosys/more_scripting/selections.rst index 1f0efb1f3..e82f23497 100644 --- a/docs/source/using_yosys/more_scripting/selections.rst +++ b/docs/source/using_yosys/more_scripting/selections.rst @@ -9,31 +9,31 @@ The selection framework .. todo:: reduce overlap with :doc:`/getting_started/scripting_intro` select section -The `select` command can be used to create a selection for subsequent -commands. For example: +The `select` command can be used to create a selection for subsequent commands. +For example: .. code:: yoscrypt select foobar # select the module foobar delete # delete selected objects -Normally the `select` command overwrites a previous selection. The -commands :yoscrypt:`select -add` and :yoscrypt:`select -del` can be used to add -or remove objects from the current selection. +Normally the `select` command overwrites a previous selection. The commands +:yoscrypt:`select -add` and :yoscrypt:`select -del` can be used to add or remove +objects from the current selection. The command :yoscrypt:`select -clear` can be used to reset the selection to the default, which is a complete selection of everything in the current module. This selection framework can also be used directly in many other commands. Whenever a command has ``[selection]`` as last argument in its usage help, this -means that it will use the engine behind the `select` command to -evaluate additional arguments and use the resulting selection instead of the -selection created by the last `select` command. +means that it will use the engine behind the `select` command to evaluate +additional arguments and use the resulting selection instead of the selection +created by the last `select` command. For example, the command `delete` will delete everything in the current selection; while :yoscrypt:`delete foobar` will only delete the module foobar. -If no `select` command has been made, then the "current selection" will -be the whole design. +If no `select` command has been made, then the "current selection" will be the +whole design. .. note:: Many of the examples on this page make use of the `show` command to visually demonstrate the effect of selections. For a more @@ -59,8 +59,8 @@ Module and design context ^^^^^^^^^^^^^^^^^^^^^^^^^ Commands can be executed in *module/* or *design/* context. Until now, all -commands have been executed in design context. The `cd` command can be -used to switch to module context. +commands have been executed in design context. The `cd` command can be used to +switch to module context. In module context, all commands only effect the active module. Objects in the module are selected without the ``/`` prefix. For example: @@ -91,7 +91,7 @@ Special patterns can be used to select by object property or type. For example: a:foobar=42` - select all modules with the attribute ``blabla`` set: :yoscrypt:`select A:blabla` -- select all $add cells from the module foo: :yoscrypt:`select foo/t:$add` +- select all `$add` cells from the module foo: :yoscrypt:`select foo/t:$add` A complete list of pattern expressions can be found in :doc:`/cmd/select`. @@ -101,12 +101,12 @@ Operations on selections Combining selections ^^^^^^^^^^^^^^^^^^^^ -The `select` command is actually much more powerful than it might seem -at first glance. When it is called with multiple arguments, each argument is -evaluated and pushed separately on a stack. After all arguments have been -processed it simply creates the union of all elements on the stack. So -:yoscrypt:`select t:$add a:foo` will select all `$add` cells and all objects -with the ``foo`` attribute set: +The `select` command is actually much more powerful than it might seem at first +glance. When it is called with multiple arguments, each argument is evaluated +and pushed separately on a stack. After all arguments have been processed it +simply creates the union of all elements on the stack. So :yoscrypt:`select +t:$add a:foo` will select all `$add` cells and all objects with the ``foo`` +attribute set: .. literalinclude:: /code_examples/selections/foobaraddsub.v :caption: Test module for operations on selections @@ -220,11 +220,11 @@ The following sequence of diagrams demonstrates this step-wise expansion: Output of :yoscrypt:`show prod %ci %ci %ci` on :numref:`sumprod` Notice the subtle difference between :yoscrypt:`show prod %ci` and -:yoscrypt:`show prod %ci %ci`. Both images show the `$mul` cell driven by -some inputs ``$3_Y`` and ``c``. However it is not until the second image, -having called ``%ci`` the second time, that `show` is able to -distinguish between ``$3_Y`` being a wire and ``c`` being an input. We can see -this better with the `dump` command instead: +:yoscrypt:`show prod %ci %ci`. Both images show the `$mul` cell driven by some +inputs ``$3_Y`` and ``c``. However it is not until the second image, having +called ``%ci`` the second time, that `show` is able to distinguish between +``$3_Y`` being a wire and ``c`` being an input. We can see this better with the +`dump` command instead: .. literalinclude:: /code_examples/selections/sumprod.out :language: RTLIL @@ -241,8 +241,8 @@ be a bit dull. So there is a shortcut for that: the number of iterations can be appended to the action. So for example the action ``%ci3`` is identical to performing the ``%ci`` action three times. -The action ``%ci*`` performs the ``%ci`` action over and over again until it -has no effect anymore. +The action ``%ci*`` performs the ``%ci`` action over and over again until it has +no effect anymore. .. _advanced_logic_cones: @@ -264,8 +264,8 @@ source repository. :name: memdemo_src :language: verilog -The script :file:`memdemo.ys` is used to generate the images included here. Let's -look at the first section: +The script :file:`memdemo.ys` is used to generate the images included here. +Let's look at the first section: .. literalinclude:: /code_examples/selections/memdemo.ys :caption: Synthesizing :ref:`memdemo_src` @@ -276,8 +276,8 @@ look at the first section: This loads :numref:`memdemo_src` and synthesizes the included module. Note that this code can be copied and run directly in a Yosys command line session, provided :file:`memdemo.v` is in the same directory. We can now change to the -``memdemo`` module with ``cd memdemo``, and call `show` to see the -diagram in :numref:`memdemo_00`. +``memdemo`` module with ``cd memdemo``, and call `show` to see the diagram in +:numref:`memdemo_00`. .. figure:: /_images/code_examples/selections/memdemo_00.* :class: width-helper invert-helper @@ -371,8 +371,8 @@ selection instead of overwriting it. select -del reg_42 # but not this one select -add state %ci # and add more stuff -Within a select expression the token ``%`` can be used to push the previous selection -on the stack. +Within a select expression the token ``%`` can be used to push the previous +selection on the stack. .. code:: yoscrypt @@ -387,16 +387,16 @@ Storing and recalling selections The current selection can be stored in memory with the command ``select -set ``. It can later be recalled using ``select @``. In fact, the ``@`` expression pushes the stored selection on the stack maintained by -the `select` command. So for example :yoscrypt:`select @foo @bar %i` -will select the intersection between the stored selections ``foo`` and ``bar``. +the `select` command. So for example :yoscrypt:`select @foo @bar %i` will select +the intersection between the stored selections ``foo`` and ``bar``. In larger investigation efforts it is highly recommended to maintain a script that sets up relevant selections, so they can easily be recalled, for example when Yosys needs to be re-run after a design or source code change. -The `history` command can be used to list all recent interactive -commands. This feature can be useful for creating such a script from the -commands used in an interactive session. +The `history` command can be used to list all recent interactive commands. This +feature can be useful for creating such a script from the commands used in an +interactive session. Remember that select expressions can also be used directly as arguments to most commands. Some commands also accept a single select argument to some options. In diff --git a/docs/source/using_yosys/synthesis/abc.rst b/docs/source/using_yosys/synthesis/abc.rst index 0c2e4868a..91de775e6 100644 --- a/docs/source/using_yosys/synthesis/abc.rst +++ b/docs/source/using_yosys/synthesis/abc.rst @@ -10,13 +10,12 @@ fine-grained optimisation and LUT mapping. Yosys has two different commands, which both use this logic toolbox, but use it in different ways. -The `abc` pass can be used for both ASIC (e.g. :yoscrypt:`abc --liberty`) and FPGA (:yoscrypt:`abc -lut`) mapping, but this page will focus on -FPGA mapping. +The `abc` pass can be used for both ASIC (e.g. :yoscrypt:`abc -liberty`) and +FPGA (:yoscrypt:`abc -lut`) mapping, but this page will focus on FPGA mapping. -The `abc9` pass generally provides superior mapping quality due to -being aware of combination boxes and DFF and LUT timings, giving it a more -global view of the mapping problem. +The `abc9` pass generally provides superior mapping quality due to being aware +of combination boxes and DFF and LUT timings, giving it a more global view of +the mapping problem. .. _ABC: https://github.com/berkeley-abc/abc diff --git a/docs/source/using_yosys/synthesis/cell_libs.rst b/docs/source/using_yosys/synthesis/cell_libs.rst index c8dbba838..50811fd1e 100644 --- a/docs/source/using_yosys/synthesis/cell_libs.rst +++ b/docs/source/using_yosys/synthesis/cell_libs.rst @@ -98,8 +98,8 @@ our internal cell library will be mapped to: :name: mycells-lib :caption: :file:`mycells.lib` -Recall that the Yosys built-in logic gate types are `$_NOT_`, `$_AND_`, -`$_OR_`, `$_XOR_`, and `$_MUX_` with an assortment of dff memory types. +Recall that the Yosys built-in logic gate types are `$_NOT_`, `$_AND_`, `$_OR_`, +`$_XOR_`, and `$_MUX_` with an assortment of dff memory types. :ref:`mycells-lib` defines our target cells as ``BUF``, ``NOT``, ``NAND``, ``NOR``, and ``DFF``. Mapping between these is performed with the commands `dfflibmap` and `abc` as follows: @@ -117,8 +117,8 @@ The final version of our ``counter`` module looks like this: ``counter`` after hardware cell mapping -Before finally being output as a verilog file with `write_verilog`, -which can then be loaded into another tool: +Before finally being output as a verilog file with `write_verilog`, which can +then be loaded into another tool: .. literalinclude:: /code_examples/intro/counter.ys :language: yoscrypt diff --git a/docs/source/using_yosys/synthesis/extract.rst b/docs/source/using_yosys/synthesis/extract.rst index 176e2ffdd..73957bb55 100644 --- a/docs/source/using_yosys/synthesis/extract.rst +++ b/docs/source/using_yosys/synthesis/extract.rst @@ -1,12 +1,12 @@ The extract pass ---------------- -- Like the `techmap` pass, the `extract` pass is called with a - map file. It compares the circuits inside the modules of the map file with the - design and looks for sub-circuits in the design that match any of the modules - in the map file. -- If a match is found, the `extract` pass will replace the matching - subcircuit with an instance of the module from the map file. +- Like the `techmap` pass, the `extract` pass is called with a map file. It + compares the circuits inside the modules of the map file with the design and + looks for sub-circuits in the design that match any of the modules in the map + file. +- If a match is found, the `extract` pass will replace the matching subcircuit + with an instance of the module from the map file. - In a way the `extract` pass is the inverse of the techmap pass. .. todo:: add/expand supporting text, also mention custom pattern matching and @@ -68,23 +68,23 @@ The wrap-extract-unwrap method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Often a coarse-grain element has a constant bit-width, but can be used to -implement operations with a smaller bit-width. For example, a 18x25-bit multiplier -can also be used to implement 16x20-bit multiplication. +implement operations with a smaller bit-width. For example, a 18x25-bit +multiplier can also be used to implement 16x20-bit multiplication. A way of mapping such elements in coarse grain synthesis is the wrap-extract-unwrap method: wrap Identify candidate-cells in the circuit and wrap them in a cell with a - constant wider bit-width using `techmap`. The wrappers use the same - parameters as the original cell, so the information about the original width - of the ports is preserved. Then use the `connwrappers` command to - connect up the bit-extended in- and outputs of the wrapper cells. + constant wider bit-width using `techmap`. The wrappers use the same parameters + as the original cell, so the information about the original width of the ports + is preserved. Then use the `connwrappers` command to connect up the + bit-extended in- and outputs of the wrapper cells. extract Now all operations are encoded using the same bit-width as the coarse grain - element. The `extract` command can be used to replace circuits with - cells of the target architecture. + element. The `extract` command can be used to replace circuits with cells of + the target architecture. unwrap The remaining wrapper cell can be unwrapped using `techmap`. diff --git a/docs/source/using_yosys/synthesis/fsm.rst b/docs/source/using_yosys/synthesis/fsm.rst index cb65a298b..cc3d0879d 100644 --- a/docs/source/using_yosys/synthesis/fsm.rst +++ b/docs/source/using_yosys/synthesis/fsm.rst @@ -25,9 +25,8 @@ following description: - Does not already have the ``\fsm_encoding`` attribute. - Is not an output of the containing module. - Is driven by single `$dff` or `$adff` cell. -- The ``\D``-Input of this `$dff` or `$adff` cell is driven by a - multiplexer tree that only has constants or the old state value on its - leaves. +- The ``\D``-Input of this `$dff` or `$adff` cell is driven by a multiplexer + tree that only has constants or the old state value on its leaves. - The state value is only used in the said multiplexer tree or by simple relational cells that compare the state value to a constant (usually `$eq` cells). @@ -87,8 +86,8 @@ given set of result signals using a set of signal-value assignments. It can also be passed a list of stop-signals that abort the ConstEval algorithm if the value of a stop-signal is needed in order to calculate the result signals. -The `fsm_extract` pass uses the ConstEval class in the following way to -create a transition table. For each state: +The `fsm_extract` pass uses the ConstEval class in the following way to create a +transition table. For each state: 1. Create a ConstEval object for the module containing the FSM 2. Add all control inputs to the list of stop signals @@ -108,13 +107,12 @@ drivers for the control outputs are disconnected. FSM optimization ~~~~~~~~~~~~~~~~ -The `fsm_opt` pass performs basic optimizations on `$fsm` cells (not -including state recoding). The following optimizations are performed (in this -order): +The `fsm_opt` pass performs basic optimizations on `$fsm` cells (not including +state recoding). The following optimizations are performed (in this order): - Unused control outputs are removed from the `$fsm` cell. The attribute - ``\unused_bits`` (that is usually set by the `opt_clean` pass) is - used to determine which control outputs are unused. + ``\unused_bits`` (that is usually set by the `opt_clean` pass) is used to + determine which control outputs are unused. - Control inputs that are connected to the same driver are merged. @@ -134,11 +132,10 @@ order): FSM recoding ~~~~~~~~~~~~ -The `fsm_recode` pass assigns new bit pattern to the states. Usually -this also implies a change in the width of the state signal. At the moment of -this writing only one-hot encoding with all-zero for the reset state is -supported. +The `fsm_recode` pass assigns new bit pattern to the states. Usually this also +implies a change in the width of the state signal. At the moment of this writing +only one-hot encoding with all-zero for the reset state is supported. -The `fsm_recode` pass can also write a text file with the changes -performed by it that can be used when verifying designs synthesized by Yosys -using Synopsys Formality. +The `fsm_recode` pass can also write a text file with the changes performed by +it that can be used when verifying designs synthesized by Yosys using Synopsys +Formality. diff --git a/docs/source/using_yosys/synthesis/index.rst b/docs/source/using_yosys/synthesis/index.rst index ae6da302a..60581668f 100644 --- a/docs/source/using_yosys/synthesis/index.rst +++ b/docs/source/using_yosys/synthesis/index.rst @@ -8,17 +8,16 @@ coarse-grain optimizations before being mapped to hard blocks and fine-grain cells. Most commands in Yosys will target either coarse-grain representation or fine-grain representation, with only a select few compatible with both states. -Commands such as `proc`, `fsm`, and `memory` rely on -the additional information in the coarse-grain representation, along with a -number of optimizations such as `wreduce`, `share`, and -`alumacc`. `opt` provides optimizations which are useful in -both states, while `techmap` is used to convert coarse-grain cells -to the corresponding fine-grain representation. +Commands such as `proc`, `fsm`, and `memory` rely on the additional information +in the coarse-grain representation, along with a number of optimizations such as +`wreduce`, `share`, and `alumacc`. `opt` provides optimizations which are +useful in both states, while `techmap` is used to convert coarse-grain cells to +the corresponding fine-grain representation. Single-bit cells (logic gates, FFs) as well as LUTs, half-adders, and full-adders make up the bulk of the fine-grain representation and are necessary -for commands such as `abc`\ /`abc9`, `simplemap`, -`dfflegalize`, and `memory_map`. +for commands such as `abc`\ /`abc9`, `simplemap`, `dfflegalize`, and +`memory_map`. .. toctree:: :maxdepth: 3 diff --git a/docs/source/using_yosys/synthesis/memory.rst b/docs/source/using_yosys/synthesis/memory.rst index ad8b47d78..a8f2280f7 100644 --- a/docs/source/using_yosys/synthesis/memory.rst +++ b/docs/source/using_yosys/synthesis/memory.rst @@ -5,10 +5,10 @@ The `memory` command ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In the RTL netlist, memory reads and writes are individual cells. This makes -consolidating the number of ports for a memory easier. The `memory` -pass transforms memories to an implementation. Per default that is logic for -address decoders and registers. It also is a macro command that calls the other -common ``memory_*`` passes in a sensible order: +consolidating the number of ports for a memory easier. The `memory` pass +transforms memories to an implementation. Per default that is logic for address +decoders and registers. It also is a macro command that calls the other common +``memory_*`` passes in a sensible order: .. literalinclude:: /code_examples/macro_commands/memory.ys :language: yoscrypt @@ -22,11 +22,11 @@ Some quick notes: - `memory_dff` merges registers into the memory read- and write cells. - `memory_collect` collects all read and write cells for a memory and transforms them into one multi-port memory cell. -- `memory_map` takes the multi-port memory cell and transforms it to - address decoder logic and registers. +- `memory_map` takes the multi-port memory cell and transforms it to address + decoder logic and registers. -For more information about `memory`, such as disabling certain sub -commands, see :doc:`/cmd/memory`. +For more information about `memory`, such as disabling certain sub commands, see +:doc:`/cmd/memory`. Example ------- @@ -75,20 +75,20 @@ For example: techmap -map my_memory_map.v memory_map -`memory_libmap` attempts to convert memory cells (`$mem_v2` etc) into -hardware supported memory using a provided library (:file:`my_memory_map.txt` in the +`memory_libmap` attempts to convert memory cells (`$mem_v2` etc) into hardware +supported memory using a provided library (:file:`my_memory_map.txt` in the example above). Where necessary, emulation logic is added to ensure functional equivalence before and after this conversion. :yoscrypt:`techmap -map -my_memory_map.v` then uses `techmap` to map to hardware primitives. Any -leftover memory cells unable to be converted are then picked up by -`memory_map` and mapped to DFFs and address decoders. +my_memory_map.v` then uses `techmap` to map to hardware primitives. Any leftover +memory cells unable to be converted are then picked up by `memory_map` and +mapped to DFFs and address decoders. .. note:: More information about what mapping options are available and associated costs of each can be found by enabling debug outputs. This can be done with - the `debug` command, or by using the ``-g`` flag when calling Yosys - to globally enable debug messages. + the `debug` command, or by using the ``-g`` flag when calling Yosys to + globally enable debug messages. For more on the lib format for `memory_libmap`, see `passes/memory/memlib.md @@ -110,13 +110,15 @@ Notes Memory kind selection ~~~~~~~~~~~~~~~~~~~~~ -The memory inference code will automatically pick target memory primitive based on memory geometry -and features used. Depending on the target, there can be up to four memory primitive classes -available for selection: +The memory inference code will automatically pick target memory primitive based +on memory geometry and features used. Depending on the target, there can be up +to four memory primitive classes available for selection: -- FF RAM (aka logic): no hardware primitive used, memory lowered to a bunch of FFs and multiplexers +- FF RAM (aka logic): no hardware primitive used, memory lowered to a bunch of + FFs and multiplexers - - Can handle arbitrary number of write ports, as long as all write ports are in the same clock domain + - Can handle arbitrary number of write ports, as long as all write ports are + in the same clock domain - Can handle arbitrary number and kind of read ports - LUT RAM (aka distributed RAM): uses LUT storage as RAM @@ -131,7 +133,8 @@ available for selection: - Supported on basically all FPGAs - Supports only synchronous reads - Two ports with separate clocks - - Usually supports true dual port (with notable exception of ice40 that only supports SDP) + - Usually supports true dual port (with notable exception of ice40 that only + supports SDP) - Usually supports asymmetric memories and per-byte write enables - Several kilobits in size @@ -155,19 +158,22 @@ available for selection: - Two ports, both with mutually exclusive synchronous read and write - Single clock - - Will not be automatically selected by memory inference code, needs explicit opt-in via - ram_style attribute + - Will not be automatically selected by memory inference code, needs explicit + opt-in via ram_style attribute -In general, you can expect the automatic selection process to work roughly like this: +In general, you can expect the automatic selection process to work roughly like +this: - If any read port is asynchronous, only LUT RAM (or FF RAM) can be used. -- If there is more than one write port, only block RAM can be used, and this needs to be a - hardware-supported true dual port pattern +- If there is more than one write port, only block RAM can be used, and this + needs to be a hardware-supported true dual port pattern - - … unless all write ports are in the same clock domain, in which case FF RAM can also be used, - but this is generally not what you want for anything but really small memories + - … unless all write ports are in the same clock domain, in which case FF RAM + can also be used, but this is generally not what you want for anything but + really small memories -- Otherwise, either FF RAM, LUT RAM, or block RAM will be used, depending on memory size +- Otherwise, either FF RAM, LUT RAM, or block RAM will be used, depending on + memory size This process can be overridden by attaching a ram_style attribute to the memory: @@ -178,15 +184,17 @@ This process can be overridden by attaching a ram_style attribute to the memory: It is an error if this override cannot be realized for the given target. -Many alternate spellings of the attribute are also accepted, for compatibility with other software. +Many alternate spellings of the attribute are also accepted, for compatibility +with other software. Initial data ~~~~~~~~~~~~ -Most FPGA targets support initializing all kinds of memory to user-provided values. If explicit -initialization is not used the initial memory value is undefined. Initial data can be provided by -either initial statements writing memory cells one by one of ``$readmemh`` or ``$readmemb`` system -tasks. For an example pattern, see `sr_init`_. +Most FPGA targets support initializing all kinds of memory to user-provided +values. If explicit initialization is not used the initial memory value is +undefined. Initial data can be provided by either initial statements writing +memory cells one by one of ``$readmemh`` or ``$readmemb`` system tasks. For an +example pattern, see `sr_init`_. .. _wbe: @@ -194,12 +202,13 @@ Write port with byte enables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Byte enables can be used with any supported pattern -- To ensure that multiple writes will be merged into one port, they need to have disjoint bit - ranges, have the same address, and the same clock -- Any write enable granularity will be accepted (down to per-bit write enables), but using smaller - granularity than natively supported by the target is very likely to be inefficient (eg. using - 4-bit bytes on ECP5 will result in either padding the bytes with 5 dummy bits to native 9-bit - units or splitting the RAM into two block RAMs) +- To ensure that multiple writes will be merged into one port, they need to have + disjoint bit ranges, have the same address, and the same clock +- Any write enable granularity will be accepted (down to per-bit write enables), + but using smaller granularity than natively supported by the target is very + likely to be inefficient (eg. using 4-bit bytes on ECP5 will result in either + padding the bytes with 5 dummy bits to native 9-bit units or splitting the RAM + into two block RAMs) .. code:: verilog @@ -240,7 +249,8 @@ Synchronous SDP with clock domain crossing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Will result in block RAM or LUT RAM depending on size -- No behavior guarantees in case of simultaneous read and write to the same address +- No behavior guarantees in case of simultaneous read and write to the same + address .. code:: verilog @@ -261,9 +271,9 @@ Synchronous SDP read first - The read and write parts can be in the same or different processes. - Will result in block RAM or LUT RAM depending on size -- As long as the same clock is used for both, yosys will ensure read-first behavior. This may - require extra circuitry on some targets for block RAM. If this is not necessary, use one of the - patterns below. +- As long as the same clock is used for both, yosys will ensure read-first + behavior. This may require extra circuitry on some targets for block RAM. If + this is not necessary, use one of the patterns below. .. code:: verilog @@ -281,8 +291,8 @@ Synchronous SDP read first Synchronous SDP with undefined collision behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Like above, but the read value is undefined when read and write ports target the same address in - the same cycle +- Like above, but the read value is undefined when read and write ports target + the same address in the same cycle .. code:: verilog @@ -322,8 +332,8 @@ Synchronous SDP with write-first behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Will result in block RAM or LUT RAM depending on size -- May use additional circuitry for block RAM if write-first is not natively supported. Will always - use additional circuitry for LUT RAM. +- May use additional circuitry for block RAM if write-first is not natively + supported. Will always use additional circuitry for LUT RAM. .. code:: verilog @@ -343,7 +353,8 @@ Synchronous SDP with write-first behavior Synchronous SDP with write-first behavior (alternate pattern) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- This pattern is supported for compatibility, but is much less flexible than the above +- This pattern is supported for compatibility, but is much less flexible than + the above .. code:: verilog @@ -378,8 +389,10 @@ Synchronous single-port RAM with mutually exclusive read/write ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Will result in single-port block RAM or LUT RAM depending on size -- This is the correct pattern to infer ice40 SPRAM (with manual ram_style selection) -- On targets that don't support read/write block RAM ports (eg. ice40), will result in SDP block RAM instead +- This is the correct pattern to infer ice40 SPRAM (with manual ram_style + selection) +- On targets that don't support read/write block RAM ports (eg. ice40), will + result in SDP block RAM instead - For block RAM, will use "NO_CHANGE" mode if available .. code:: verilog @@ -396,12 +409,14 @@ Synchronous single-port RAM with mutually exclusive read/write Synchronous single-port RAM with read-first behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Will only result in single-port block RAM when read-first behavior is natively supported; - otherwise, SDP RAM with additional circuitry will be used -- Many targets (Xilinx, ECP5, …) can only natively support read-first/write-first single-port RAM - (or TDP RAM) where the write_enable signal implies the read_enable signal (ie. can never write - without reading). The memory inference code will run a simple SAT solver on the control signals to - determine if this is the case, and insert emulation circuitry if it cannot be easily proven. +- Will only result in single-port block RAM when read-first behavior is natively + supported; otherwise, SDP RAM with additional circuitry will be used +- Many targets (Xilinx, ECP5, …) can only natively support + read-first/write-first single-port RAM (or TDP RAM) where the write_enable + signal implies the read_enable signal (ie. can never write without reading). + The memory inference code will run a simple SAT solver on the control signals + to determine if this is the case, and insert emulation circuitry if it cannot + be easily proven. .. code:: verilog @@ -418,7 +433,8 @@ Synchronous single-port RAM with write-first behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Will result in single-port block RAM or LUT RAM when supported -- Block RAMs will require extra circuitry if write-first behavior not natively supported +- Block RAMs will require extra circuitry if write-first behavior not natively + supported .. code:: verilog @@ -440,8 +456,8 @@ Synchronous read port with initial value ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Initial read port values can be combined with any other supported pattern -- If block RAM is used and initial read port values are not natively supported by the target, small - emulation circuit will be inserted +- If block RAM is used and initial read port values are not natively supported + by the target, small emulation circuit will be inserted .. code:: verilog @@ -459,10 +475,11 @@ Synchronous read port with initial value Read register reset patterns ---------------------------- -Resets can be combined with any other supported pattern (except that synchronous reset and -asynchronous reset cannot both be used on a single read port). If block RAM is used and the -selected reset (synchronous or asynchronous) is used but not natively supported by the target, small -emulation circuitry will be inserted. +Resets can be combined with any other supported pattern (except that synchronous +reset and asynchronous reset cannot both be used on a single read port). If +block RAM is used and the selected reset (synchronous or asynchronous) is used +but not natively supported by the target, small emulation circuitry will be +inserted. Synchronous reset, reset priority over enable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -520,22 +537,26 @@ Synchronous read port with asynchronous reset Asymmetric memory patterns -------------------------- -To construct an asymmetric memory (memory with read/write ports of differing widths): +To construct an asymmetric memory (memory with read/write ports of differing +widths): - Declare the memory with the width of the narrowest intended port - Split all wide ports into multiple narrow ports - To ensure the wide ports will be correctly merged: - - For the address, use a concatenation of actual address in the high bits and a constant in the - low bits - - Ensure the actual address is identical for all ports belonging to the wide port + - For the address, use a concatenation of actual address in the high bits and + a constant in the low bits + - Ensure the actual address is identical for all ports belonging to the wide + port - Ensure that clock is identical - - For read ports, ensure that enable/reset signals are identical (for write ports, the enable - signal may vary — this will result in using the byte enable functionality) + - For read ports, ensure that enable/reset signals are identical (for write + ports, the enable signal may vary — this will result in using the byte + enable functionality) -Asymmetric memory is supported on all targets, but may require emulation circuitry where not -natively supported. Note that when the memory is larger than the underlying block RAM primitive, -hardware asymmetric memory support is likely not to be used even if present as it is more expensive. +Asymmetric memory is supported on all targets, but may require emulation +circuitry where not natively supported. Note that when the memory is larger +than the underlying block RAM primitive, hardware asymmetric memory support is +likely not to be used even if present as it is more expensive. .. _wide_sr: @@ -615,20 +636,25 @@ Wide write port True dual port (TDP) patterns ----------------------------- -- Many different variations of true dual port memory can be created by combining two single-port RAM - patterns on the same memory -- When TDP memory is used, memory inference code has much less maneuver room to create requested - semantics compared to individual single-port patterns (which can end up lowered to SDP memory - where necessary) — supported patterns depend strongly on the target -- In particular, when both ports have the same clock, it's likely that "undefined collision" mode - needs to be manually selected to enable TDP memory inference -- The examples below are non-exhaustive — many more combinations of port types are possible -- Note: if two write ports are in the same process, this defines a priority relation between them - (if both ports are active in the same clock, the later one wins). On almost all targets, this will - result in a bit of extra circuitry to ensure the priority semantics. If this is not what you want, - put them in separate processes. +- Many different variations of true dual port memory can be created by combining + two single-port RAM patterns on the same memory +- When TDP memory is used, memory inference code has much less maneuver room to + create requested semantics compared to individual single-port patterns (which + can end up lowered to SDP memory where necessary) — supported patterns depend + strongly on the target +- In particular, when both ports have the same clock, it's likely that + "undefined collision" mode needs to be manually selected to enable TDP memory + inference +- The examples below are non-exhaustive — many more combinations of port types + are possible +- Note: if two write ports are in the same process, this defines a priority + relation between them (if both ports are active in the same clock, the later + one wins). On almost all targets, this will result in a bit of extra circuitry + to ensure the priority semantics. If this is not what you want, put them in + separate processes. - - Priority is not supported when using the verific front end and any priority semantics are ignored. + - Priority is not supported when using the verific front end and any priority + semantics are ignored. TDP with different clocks, exclusive read/write ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -654,7 +680,8 @@ TDP with different clocks, exclusive read/write TDP with same clock, read-first behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- This requires hardware inter-port read-first behavior, and will only work on some targets (Xilinx, Nexus) +- This requires hardware inter-port read-first behavior, and will only work on + some targets (Xilinx, Nexus) .. code:: verilog @@ -677,9 +704,10 @@ TDP with same clock, read-first behavior TDP with multiple read ports ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- The combination of a single write port with an arbitrary amount of read ports is supported on all - targets — if a multi-read port primitive is available (like Xilinx RAM64M), it'll be used as - appropriate. Otherwise, the memory will be automatically split into multiple primitives. +- The combination of a single write port with an arbitrary amount of read ports + is supported on all targets — if a multi-read port primitive is available + (like Xilinx RAM64M), it'll be used as appropriate. Otherwise, the memory + will be automatically split into multiple primitives. .. code:: verilog diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst index db1525a05..7af2231c9 100644 --- a/docs/source/using_yosys/synthesis/opt.rst +++ b/docs/source/using_yosys/synthesis/opt.rst @@ -9,9 +9,9 @@ This chapter outlines these optimizations. The `opt` macro command -------------------------------- -The Yosys pass `opt` runs a number of simple optimizations. This -includes removing unused signals and cells and const folding. It is recommended -to run this pass after each major step in the synthesis script. As listed in +The Yosys pass `opt` runs a number of simple optimizations. This includes +removing unused signals and cells and const folding. It is recommended to run +this pass after each major step in the synthesis script. As listed in :doc:`/cmd/opt`, this macro command calls the following ``opt_*`` commands: .. literalinclude:: /code_examples/macro_commands/opt.ys @@ -69,17 +69,17 @@ undef. The last two lines simply replace an `$_AND_` gate with one constant-1 input with a buffer. -Besides this basic const folding the `opt_expr` pass can replace 1-bit -wide `$eq` and `$ne` cells with buffers or not-gates if one input is -constant. Equality checks may also be reduced in size if there are redundant -bits in the arguments (i.e. bits which are constant on both inputs). This can, -for example, result in a 32-bit wide constant like ``255`` being reduced to the -8-bit value of ``8'11111111`` if the signal being compared is only 8-bit as in +Besides this basic const folding the `opt_expr` pass can replace 1-bit wide +`$eq` and `$ne` cells with buffers or not-gates if one input is constant. +Equality checks may also be reduced in size if there are redundant bits in the +arguments (i.e. bits which are constant on both inputs). This can, for example, +result in a 32-bit wide constant like ``255`` being reduced to the 8-bit value +of ``8'11111111`` if the signal being compared is only 8-bit as in :ref:`addr_gen_clean` of :doc:`/getting_started/example_synth`. -The `opt_expr` pass is very conservative regarding optimizing `$mux` -cells, as these cells are often used to model decision-trees and breaking these -trees can interfere with other optimizations. +The `opt_expr` pass is very conservative regarding optimizing `$mux` cells, as +these cells are often used to model decision-trees and breaking these trees can +interfere with other optimizations. .. literalinclude:: /code_examples/opt/opt_expr.ys :language: Verilog @@ -100,9 +100,9 @@ identifies cells with identical inputs and replaces them with a single instance of the cell. The option ``-nomux`` can be used to disable resource sharing for multiplexer -cells (`$mux` and `$pmux`.) This can be useful as it prevents multiplexer -trees to be merged, which might prevent `opt_muxtree` to identify -possible optimizations. +cells (`$mux` and `$pmux`.) This can be useful as it prevents multiplexer trees +to be merged, which might prevent `opt_muxtree` to identify possible +optimizations. .. literalinclude:: /code_examples/opt/opt_merge.ys :language: Verilog @@ -128,9 +128,9 @@ Consider the following simple example: :caption: example verilog for demonstrating `opt_muxtree` The output can never be ``c``, as this would require ``a`` to be 1 for the outer -multiplexer and 0 for the inner multiplexer. The `opt_muxtree` pass -detects this contradiction and replaces the inner multiplexer with a constant 1, -yielding the logic for ``y = a ? b : d``. +multiplexer and 0 for the inner multiplexer. The `opt_muxtree` pass detects this +contradiction and replaces the inner multiplexer with a constant 1, yielding the +logic for ``y = a ? b : d``. .. figure:: /_images/code_examples/opt/opt_muxtree.* :class: width-helper invert-helper @@ -141,9 +141,9 @@ Simplifying large MUXes and AND/OR gates - `opt_reduce` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is a simple optimization pass that identifies and consolidates identical -input bits to `$reduce_and` and `$reduce_or` cells. It also sorts the input -bits to ease identification of shareable `$reduce_and` and `$reduce_or` -cells in other passes. +input bits to `$reduce_and` and `$reduce_or` cells. It also sorts the input bits +to ease identification of shareable `$reduce_and` and `$reduce_or` cells in +other passes. This pass also identifies and consolidates identical inputs to multiplexer cells. In this case the new shared select bit is driven using a `$reduce_or` @@ -162,8 +162,8 @@ This pass identifies mutually exclusive cells of the same type that: a. share an input signal, and b. drive the same `$mux`, `$_MUX_`, or `$pmux` multiplexing cell, -allowing the cell to be merged and the multiplexer to be moved from -multiplexing its output to multiplexing the non-shared input signals. +allowing the cell to be merged and the multiplexer to be moved from multiplexing +its output to multiplexing the non-shared input signals. .. literalinclude:: /code_examples/opt/opt_share.ys :language: Verilog @@ -176,16 +176,16 @@ multiplexing its output to multiplexing the non-shared input signals. Before and after `opt_share` -When running `opt` in full, the original `$mux` (labeled ``$3``) is -optimized away by `opt_expr`. +When running `opt` in full, the original `$mux` (labeled ``$3``) is optimized +away by `opt_expr`. Performing DFF optimizations - `opt_dff` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This pass identifies single-bit d-type flip-flops (`$_DFF_`, `$dff`, and -`$adff` cells) with a constant data input and replaces them with a constant -driver. It can also merge clock enables and synchronous reset multiplexers, -removing unused control inputs. +This pass identifies single-bit d-type flip-flops (`$_DFF_`, `$dff`, and `$adff` +cells) with a constant data input and replaces them with a constant driver. It +can also merge clock enables and synchronous reset multiplexers, removing unused +control inputs. Called with ``-nodffe`` and ``-nosdff``, this pass is used to prepare a design for :doc:`/using_yosys/synthesis/fsm`. @@ -200,20 +200,20 @@ attribute can be used for debugging or by other optimization passes. When to use `opt` or `clean` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Usually it does not hurt to call `opt` after each regular command in -the synthesis script. But it increases the synthesis time, so it is favourable -to only call `opt` when an improvement can be achieved. +Usually it does not hurt to call `opt` after each regular command in the +synthesis script. But it increases the synthesis time, so it is favourable to +only call `opt` when an improvement can be achieved. -It is generally a good idea to call `opt` before inherently expensive -commands such as `sat` or `freduce`, as the possible gain is -much higher in these cases as the possible loss. +It is generally a good idea to call `opt` before inherently expensive commands +such as `sat` or `freduce`, as the possible gain is much higher in these cases +as the possible loss. -The `clean` command, which is an alias for `opt_clean` with -fewer outputs, on the other hand is very fast and many commands leave a mess -(dangling signal wires, etc). For example, most commands do not remove any wires -or cells. They just change the connections and depend on a later call to clean -to get rid of the now unused objects. So the occasional ``;;``, which itself is -an alias for `clean`, is a good idea in every synthesis script, e.g: +The `clean` command, which is an alias for `opt_clean` with fewer outputs, on +the other hand is very fast and many commands leave a mess (dangling signal +wires, etc). For example, most commands do not remove any wires or cells. They +just change the connections and depend on a later call to clean to get rid of +the now unused objects. So the occasional ``;;``, which itself is an alias for +`clean`, is a good idea in every synthesis script, e.g: .. code-block:: yoscrypt diff --git a/docs/source/using_yosys/synthesis/proc.rst b/docs/source/using_yosys/synthesis/proc.rst index cc22fcec7..b7cd348d7 100644 --- a/docs/source/using_yosys/synthesis/proc.rst +++ b/docs/source/using_yosys/synthesis/proc.rst @@ -5,23 +5,23 @@ Converting process blocks :language: yoscrypt The Verilog frontend converts ``always``-blocks to RTL netlists for the -expressions and "processess" for the control- and memory elements. The -`proc` command then transforms these "processess" to netlists of RTL -multiplexer and register cells. It also is a macro command that calls the other -``proc_*`` commands in a sensible order: +expressions and "processess" for the control- and memory elements. The `proc` +command then transforms these "processess" to netlists of RTL multiplexer and +register cells. It also is a macro command that calls the other ``proc_*`` +commands in a sensible order: .. literalinclude:: /code_examples/macro_commands/proc.ys :language: yoscrypt :start-after: #end: :caption: Passes called by `proc` -After all the ``proc_*`` commands, `opt_expr` is called. This can be -disabled by calling :yoscrypt:`proc -noopt`. For more information about -`proc`, such as disabling certain sub commands, see :doc:`/cmd/proc`. +After all the ``proc_*`` commands, `opt_expr` is called. This can be disabled by +calling :yoscrypt:`proc -noopt`. For more information about `proc`, such as +disabling certain sub commands, see :doc:`/cmd/proc`. Many commands can not operate on modules with "processess" in them. Usually a -call to `proc` is the first command in the actual synthesis procedure -after design elaboration. +call to `proc` is the first command in the actual synthesis procedure after +design elaboration. Example ^^^^^^^ diff --git a/docs/source/yosys_internals/extending_yosys/extensions.rst b/docs/source/yosys_internals/extending_yosys/extensions.rst index 2a34c700a..88e001d06 100644 --- a/docs/source/yosys_internals/extending_yosys/extensions.rst +++ b/docs/source/yosys_internals/extending_yosys/extensions.rst @@ -20,8 +20,8 @@ CodingStyle may be of interest. Quick guide ----------- -Code examples from this section are included in the -|code_examples/extensions|_ directory of the Yosys source code. +Code examples from this section are included in the |code_examples/extensions|_ +directory of the Yosys source code. .. |code_examples/extensions| replace:: :file:`docs/source/code_examples/extensions` .. _code_examples/extensions: https://github.com/YosysHQ/yosys/tree/main/docs/source/code_examples/extensions @@ -56,10 +56,9 @@ It is possible to only work on this simpler version: } When trying to understand what a command does, creating a small test case to -look at the output of `dump` and `show` before and after the -command has been executed can be helpful. -:doc:`/using_yosys/more_scripting/selections` has more information on using -these commands. +look at the output of `dump` and `show` before and after the command has been +executed can be helpful. :doc:`/using_yosys/more_scripting/selections` has more +information on using these commands. Creating a command ~~~~~~~~~~~~~~~~~~ @@ -151,8 +150,8 @@ Most commands modify existing modules, not create new ones. When modifying existing modules, stick to the following DOs and DON'Ts: -- Do not remove wires. Simply disconnect them and let a successive - `clean` command worry about removing it. +- Do not remove wires. Simply disconnect them and let a successive `clean` + command worry about removing it. - Use ``module->fixup_ports()`` after changing the ``port_*`` properties of wires. - You can safely remove cells or change the ``connections`` property of a cell, diff --git a/docs/source/yosys_internals/flow/verilog_frontend.rst b/docs/source/yosys_internals/flow/verilog_frontend.rst index fced46e8c..e53466687 100644 --- a/docs/source/yosys_internals/flow/verilog_frontend.rst +++ b/docs/source/yosys_internals/flow/verilog_frontend.rst @@ -599,14 +599,14 @@ The proc pass The ProcessGenerator converts a behavioural model in AST representation to a behavioural model in ``RTLIL::Process`` representation. The actual conversion -from a behavioural model to an RTL representation is performed by the -`proc` pass and the passes it launches: +from a behavioural model to an RTL representation is performed by the `proc` +pass and the passes it launches: - | `proc_clean` and `proc_rmdead` | These two passes just clean up the ``RTLIL::Process`` structure. The - `proc_clean` pass removes empty parts (eg. empty assignments) from - the process and `proc_rmdead` detects and removes unreachable - branches from the process's decision trees. + `proc_clean` pass removes empty parts (eg. empty assignments) from the + process and `proc_rmdead` detects and removes unreachable branches from the + process's decision trees. - | `proc_arst` | This pass detects processes that describe d-type flip-flops with @@ -617,10 +617,10 @@ from a behavioural model to an RTL representation is performed by the and the top-level ``RTLIL::SwitchRule`` has been removed. - | `proc_mux` - | This pass converts the ``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule``-tree to a - tree of multiplexers per written signal. After this, the ``RTLIL::Process`` - structure only contains the ``RTLIL::SyncRule`` s that describe the output - registers. + | This pass converts the ``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule``-tree to + a tree of multiplexers per written signal. After this, the + ``RTLIL::Process`` structure only contains the ``RTLIL::SyncRule`` s that + describe the output registers. - | `proc_dff` | This pass replaces the ``RTLIL::SyncRule``\ s to d-type flip-flops (with @@ -630,8 +630,8 @@ from a behavioural model to an RTL representation is performed by the | This pass replaces the ``RTLIL::MemWriteAction``\ s with `$memwr` cells. - | `proc_clean` - | A final call to `proc_clean` removes the now empty - ``RTLIL::Process`` objects. + | A final call to `proc_clean` removes the now empty ``RTLIL::Process`` + objects. Performing these last processing steps in passes instead of in the Verilog frontend has two important benefits: @@ -646,8 +646,8 @@ to extend the actual Verilog frontend. .. todo:: Synthesizing Verilog arrays - Add some information on the generation of `$memrd` and `$memwr` cells and - how they are processed in the memory pass. + Add some information on the generation of `$memrd` and `$memwr` cells and how + they are processed in the memory pass. .. todo:: Synthesizing parametric designs diff --git a/docs/source/yosys_internals/formats/cell_library.rst b/docs/source/yosys_internals/formats/cell_library.rst index e9ed4d7f9..c17976319 100644 --- a/docs/source/yosys_internals/formats/cell_library.rst +++ b/docs/source/yosys_internals/formats/cell_library.rst @@ -73,16 +73,16 @@ also have the following parameters: :verilog:`Y = !A` $logic_not ================== ============ -For the unary cells that output a logical value (`$reduce_and`, -`$reduce_or`, `$reduce_xor`, `$reduce_xnor`, `$reduce_bool`, -`$logic_not`), when the ``\Y_WIDTH`` parameter is greater than 1, the output -is zero-extended, and only the least significant bit varies. +For the unary cells that output a logical value (`$reduce_and`, `$reduce_or`, +`$reduce_xor`, `$reduce_xnor`, `$reduce_bool`, `$logic_not`), when the +``\Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and only +the least significant bit varies. Note that `$reduce_or` and `$reduce_bool` actually represent the same logic function. But the HDL frontends generate them in different situations. A `$reduce_or` cell is generated when the prefix ``|`` operator is being used. A -`$reduce_bool` cell is generated when a bit vector is used as a condition in -an ``if``-statement or ``?:``-expression. +`$reduce_bool` cell is generated when a bit vector is used as a condition in an +``if``-statement or ``?:``-expression. Binary operators ~~~~~~~~~~~~~~~~ @@ -91,15 +91,15 @@ All binary RTL cells have two input ports ``\A`` and ``\B`` and one output port ``\Y``. They also have the following parameters: ``\A_SIGNED`` - Set to a non-zero value if the input ``\A`` is signed and therefore - should be sign-extended when needed. + Set to a non-zero value if the input ``\A`` is signed and therefore should be + sign-extended when needed. ``\A_WIDTH`` The width of the input port ``\A``. ``\B_SIGNED`` - Set to a non-zero value if the input ``\B`` is signed and therefore - should be sign-extended when needed. + Set to a non-zero value if the input ``\B`` is signed and therefore should be + sign-extended when needed. ``\B_WIDTH`` The width of the input port ``\B``. @@ -130,29 +130,28 @@ All binary RTL cells have two input ports ``\A`` and ``\B`` and one output port :verilog:`Y = A ** B` $pow ``N/A`` $modfloor ======================= ============= ======================= ========= -The `$shl` and `$shr` cells implement logical shifts, whereas the `$sshl` -and `$sshr` cells implement arithmetic shifts. The `$shl` and `$sshl` -cells implement the same operation. All four of these cells interpret the second +The `$shl` and `$shr` cells implement logical shifts, whereas the `$sshl` and +`$sshr` cells implement arithmetic shifts. The `$shl` and `$sshl` cells +implement the same operation. All four of these cells interpret the second operand as unsigned, and require ``\B_SIGNED`` to be zero. Two additional shift operator cells are available that do not directly -correspond to any operator in Verilog, `$shift` and `$shiftx`. The -`$shift` cell performs a right logical shift if the second operand is positive -(or unsigned), and a left logical shift if it is negative. The `$shiftx` cell -performs the same operation as the `$shift` cell, but the vacated bit -positions are filled with undef (x) bits, and corresponds to the Verilog indexed -part-select expression. +correspond to any operator in Verilog, `$shift` and `$shiftx`. The `$shift` cell +performs a right logical shift if the second operand is positive (or unsigned), +and a left logical shift if it is negative. The `$shiftx` cell performs the same +operation as the `$shift` cell, but the vacated bit positions are filled with +undef (x) bits, and corresponds to the Verilog indexed part-select expression. For the binary cells that output a logical value (`$logic_and`, `$logic_or`, -`$eqx`, `$nex`, `$lt`, `$le`, `$eq`, `$ne`, `$ge`, `$gt`), when -the ``\Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and -only the least significant bit varies. +`$eqx`, `$nex`, `$lt`, `$le`, `$eq`, `$ne`, `$ge`, `$gt`), when the ``\Y_WIDTH`` +parameter is greater than 1, the output is zero-extended, and only the least +significant bit varies. Division and modulo cells are available in two rounding modes. The original -`$div` and `$mod` cells are based on truncating division, and correspond to -the semantics of the verilog ``/`` and ``%`` operators. The `$divfloor` and -`$modfloor` cells represent flooring division and flooring modulo, the latter -of which is also known as "remainder" in several languages. See +`$div` and `$mod` cells are based on truncating division, and correspond to the +semantics of the verilog ``/`` and ``%`` operators. The `$divfloor` and +`$modfloor` cells represent flooring division and flooring modulo, the latter of +which is also known as "remainder" in several languages. See :numref:`tab:CellLib_divmod` for a side-by-side comparison between the different semantics. @@ -187,9 +186,9 @@ all of the specified width. This cell also has a single bit control input it is 1 the value from the ``\B`` input is sent to the output. So the `$mux` cell implements the function :verilog:`Y = S ? B : A`. -The `$pmux` cell is used to multiplex between many inputs using a one-hot -select signal. Cells of this type have a ``\WIDTH`` and a ``\S_WIDTH`` parameter -and inputs ``\A``, ``\B``, and ``\S`` and an output ``\Y``. The ``\S`` input is +The `$pmux` cell is used to multiplex between many inputs using a one-hot select +signal. Cells of this type have a ``\WIDTH`` and a ``\S_WIDTH`` parameter and +inputs ``\A``, ``\B``, and ``\S`` and an output ``\Y``. The ``\S`` input is ``\S_WIDTH`` bits wide. The ``\A`` input and the output are both ``\WIDTH`` bits wide and the ``\B`` input is ``\WIDTH*\S_WIDTH`` bits wide. When all bits of ``\S`` are zero, the value from ``\A`` input is sent to the output. If the @@ -199,8 +198,8 @@ from ``\S`` is set the output is undefined. Cells of this type are used to model "parallel cases" (defined by using the ``parallel_case`` attribute or detected by an optimization). -The `$tribuf` cell is used to implement tristate logic. Cells of this type -have a ``\WIDTH`` parameter and inputs ``\A`` and ``\EN`` and an output ``\Y``. The +The `$tribuf` cell is used to implement tristate logic. Cells of this type have +a ``\WIDTH`` parameter and inputs ``\A`` and ``\EN`` and an output ``\Y``. The ``\A`` input and ``\Y`` output are ``\WIDTH`` bits wide, and the ``\EN`` input is one bit wide. When ``\EN`` is 0, the output is not driven. When ``\EN`` is 1, the value from ``\A`` input is sent to the ``\Y`` output. Therefore, the @@ -224,27 +223,27 @@ parameters: The width of inputs ``\SET`` and ``\CLR`` and output ``\Q``. ``\SET_POLARITY`` - The set input bits are active-high if this parameter has the value - ``1'b1`` and active-low if this parameter is ``1'b0``. + The set input bits are active-high if this parameter has the value ``1'b1`` + and active-low if this parameter is ``1'b0``. ``\CLR_POLARITY`` - The reset input bits are active-high if this parameter has the value - ``1'b1`` and active-low if this parameter is ``1'b0``. + The reset input bits are active-high if this parameter has the value ``1'b1`` + and active-low if this parameter is ``1'b0``. Both set and reset inputs have separate bits for every output bit. When both the set and reset inputs of an `$sr` cell are active for a given bit index, the reset input takes precedence. -D-type flip-flops are represented by `$dff` cells. These cells have a clock -port ``\CLK``, an input port ``\D`` and an output port ``\Q``. The following +D-type flip-flops are represented by `$dff` cells. These cells have a clock port +``\CLK``, an input port ``\D`` and an output port ``\Q``. The following parameters are available for `$dff` cells: ``\WIDTH`` The width of input ``\D`` and output ``\Q``. ``\CLK_POLARITY`` - Clock is active on the positive edge if this parameter has the value - ``1'b1`` and on the negative edge if this parameter is ``1'b0``. + Clock is active on the positive edge if this parameter has the value ``1'b1`` + and on the negative edge if this parameter is ``1'b0``. D-type flip-flops with asynchronous reset are represented by `$adff` cells. As the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they @@ -258,8 +257,8 @@ additional two parameters: ``\ARST_VALUE`` The state of ``\Q`` will be set to this value when the reset is active. -Usually these cells are generated by the `proc` pass using the -information in the designs RTLIL::Process objects. +Usually these cells are generated by the `proc` pass using the information in +the designs RTLIL::Process objects. D-type flip-flops with synchronous reset are represented by `$sdff` cells. As the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they @@ -267,14 +266,14 @@ also have a single-bit ``\SRST`` input port for the reset pin and the following additional two parameters: ``\SRST_POLARITY`` - The synchronous reset is active-high if this parameter has the value - ``1'b1`` and active-low if this parameter is ``1'b0``. + The synchronous reset is active-high if this parameter has the value ``1'b1`` + and active-low if this parameter is ``1'b0``. ``\SRST_VALUE`` The state of ``\Q`` will be set to this value when the reset is active. -Note that the `$adff` and `$sdff` cells can only be used when the reset -value is constant. +Note that the `$adff` and `$sdff` cells can only be used when the reset value is +constant. D-type flip-flops with asynchronous load are represented by `$aldff` cells. As the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they @@ -283,25 +282,24 @@ also have a single-bit ``\ALOAD`` input port for the async load enable pin, a following additional parameter: ``\ALOAD_POLARITY`` - The asynchronous load is active-high if this parameter has the value - ``1'b1`` and active-low if this parameter is ``1'b0``. + The asynchronous load is active-high if this parameter has the value ``1'b1`` + and active-low if this parameter is ``1'b0``. D-type flip-flops with asynchronous set and reset are represented by `$dffsr` cells. As the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they also have multi-bit ``\SET`` and ``\CLR`` input ports and the corresponding polarity parameters, like `$sr` cells. -D-type flip-flops with enable are represented by `$dffe`, `$adffe`, -`$aldffe`, `$dffsre`, `$sdffe`, and `$sdffce` cells, which are enhanced -variants of `$dff`, `$adff`, `$aldff`, `$dffsr`, `$sdff` (with reset -over enable) and `$sdff` (with enable over reset) cells, respectively. They -have the same ports and parameters as their base cell. In addition they also -have a single-bit ``\EN`` input port for the enable pin and the following -parameter: +D-type flip-flops with enable are represented by `$dffe`, `$adffe`, `$aldffe`, +`$dffsre`, `$sdffe`, and `$sdffce` cells, which are enhanced variants of `$dff`, +`$adff`, `$aldff`, `$dffsr`, `$sdff` (with reset over enable) and `$sdff` (with +enable over reset) cells, respectively. They have the same ports and parameters +as their base cell. In addition they also have a single-bit ``\EN`` input port +for the enable pin and the following parameter: ``\EN_POLARITY`` - The enable input is active-high if this parameter has the value ``1'b1`` - and active-low if this parameter is ``1'b0``. + The enable input is active-high if this parameter has the value ``1'b1`` and + active-low if this parameter is ``1'b0``. D-type latches are represented by `$dlatch` cells. These cells have an enable port ``\EN``, an input port ``\D``, and an output port ``\Q``. The following @@ -311,14 +309,14 @@ parameters are available for `$dlatch` cells: The width of input ``\D`` and output ``\Q``. ``\EN_POLARITY`` - The enable input is active-high if this parameter has the value ``1'b1`` - and active-low if this parameter is ``1'b0``. + The enable input is active-high if this parameter has the value ``1'b1`` and + active-low if this parameter is ``1'b0``. The latch is transparent when the ``\EN`` input is active. D-type latches with reset are represented by `$adlatch` cells. In addition to -`$dlatch` ports and parameters, they also have a single-bit ``\ARST`` input -port for the reset pin and the following additional parameters: +`$dlatch` ports and parameters, they also have a single-bit ``\ARST`` input port +for the reset pin and the following additional parameters: ``\ARST_POLARITY`` The asynchronous reset is active-high if this parameter has the value @@ -363,56 +361,53 @@ parameters: The number of address bits (width of the ``\ADDR`` input port). ``\WIDTH`` - The number of data bits (width of the ``\DATA`` output port). Note that - this may be a power-of-two multiple of the underlying memory's width -- - such ports are called wide ports and access an aligned group of cells at - once. In this case, the corresponding low bits of ``\ADDR`` must be - tied to 0. + The number of data bits (width of the ``\DATA`` output port). Note that this + may be a power-of-two multiple of the underlying memory's width -- such ports + are called wide ports and access an aligned group of cells at once. In this + case, the corresponding low bits of ``\ADDR`` must be tied to 0. ``\CLK_ENABLE`` - When this parameter is non-zero, the clock is used. Otherwise this read - port is asynchronous and the ``\CLK`` input is not used. + When this parameter is non-zero, the clock is used. Otherwise this read port + is asynchronous and the ``\CLK`` input is not used. ``\CLK_POLARITY`` - Clock is active on the positive edge if this parameter has the value - ``1'b1`` and on the negative edge if this parameter is ``1'b0``. + Clock is active on the positive edge if this parameter has the value ``1'b1`` + and on the negative edge if this parameter is ``1'b0``. ``\TRANSPARENCY_MASK`` - This parameter is a bitmask of write ports that this read port is - transparent with. The bits of this parameter are indexed by the write - port's ``\PORTID`` parameter. Transparency can only be enabled between - synchronous ports sharing a clock domain. When transparency is enabled - for a given port pair, a read and write to the same address in the same - cycle will return the new value. Otherwise the old value is returned. + This parameter is a bitmask of write ports that this read port is transparent + with. The bits of this parameter are indexed by the write port's ``\PORTID`` + parameter. Transparency can only be enabled between synchronous ports sharing + a clock domain. When transparency is enabled for a given port pair, a read + and write to the same address in the same cycle will return the new value. + Otherwise the old value is returned. ``\COLLISION_X_MASK`` This parameter is a bitmask of write ports that have undefined collision - behavior with this port. The bits of this parameter are indexed by the - write port's ``\PORTID`` parameter. This behavior can only be enabled - between synchronous ports sharing a clock domain. When undefined - collision is enabled for a given port pair, a read and write to the same - address in the same cycle will return the undefined (all-X) value.This - option is exclusive (for a given port pair) with the transparency - option. + behavior with this port. The bits of this parameter are indexed by the write + port's ``\PORTID`` parameter. This behavior can only be enabled between + synchronous ports sharing a clock domain. When undefined collision is enabled + for a given port pair, a read and write to the same address in the same cycle + will return the undefined (all-X) value.This option is exclusive (for a given + port pair) with the transparency option. ``\ARST_VALUE`` - Whenever the ``\ARST`` input is asserted, the data output will be reset - to this value. Only used for synchronous ports. + Whenever the ``\ARST`` input is asserted, the data output will be reset to + this value. Only used for synchronous ports. ``\SRST_VALUE`` - Whenever the ``\SRST`` input is synchronously asserted, the data output - will be reset to this value. Only used for synchronous ports. + Whenever the ``\SRST`` input is synchronously asserted, the data output will + be reset to this value. Only used for synchronous ports. ``\INIT_VALUE`` The initial value of the data output, for synchronous ports. ``\CE_OVER_SRST`` - If this parameter is non-zero, the ``\SRST`` input is only recognized - when ``\EN`` is true. Otherwise, ``\SRST`` is recognized regardless of - ``\EN``. + If this parameter is non-zero, the ``\SRST`` input is only recognized when + ``\EN`` is true. Otherwise, ``\SRST`` is recognized regardless of ``\EN``. -The `$memwr_v2` cells have a clock input ``\CLK``, an enable input ``\EN`` -(one enable bit for each data bit), an address input ``\ADDR`` and a data input +The `$memwr_v2` cells have a clock input ``\CLK``, an enable input ``\EN`` (one +enable bit for each data bit), an address input ``\ADDR`` and a data input ``\DATA``. They also have the following parameters: ``\MEMID`` @@ -424,16 +419,16 @@ The `$memwr_v2` cells have a clock input ``\CLK``, an enable input ``\EN`` ``\WIDTH`` The number of data bits (width of the ``\DATA`` output port). Like with - `$memrd_v2` cells, the width is allowed to be any power-of-two - multiple of memory width, with the corresponding restriction on address. + `$memrd_v2` cells, the width is allowed to be any power-of-two multiple of + memory width, with the corresponding restriction on address. ``\CLK_ENABLE`` - When this parameter is non-zero, the clock is used. Otherwise this write - port is asynchronous and the ``\CLK`` input is not used. + When this parameter is non-zero, the clock is used. Otherwise this write port + is asynchronous and the ``\CLK`` input is not used. ``\CLK_POLARITY`` - Clock is active on positive edge if this parameter has the value - ``1'b1`` and on the negative edge if this parameter is ``1'b0``. + Clock is active on positive edge if this parameter has the value ``1'b1`` and + on the negative edge if this parameter is ``1'b0``. ``\PORTID`` An identifier for this write port, used to index write port bit mask @@ -442,16 +437,16 @@ The `$memwr_v2` cells have a clock input ``\CLK``, an enable input ``\EN`` ``\PRIORITY_MASK`` This parameter is a bitmask of write ports that this write port has priority over in case of writing to the same address. The bits of this parameter are - indexed by the other write port's ``\PORTID`` parameter. Write ports can - only have priority over write ports with lower port ID. When two ports write - to the same address and neither has priority over the other, the result is + indexed by the other write port's ``\PORTID`` parameter. Write ports can only + have priority over write ports with lower port ID. When two ports write to + the same address and neither has priority over the other, the result is undefined. Priority can only be set between two synchronous ports sharing the same clock domain. -The `$meminit_v2` cells have an address input ``\ADDR``, a data input -``\DATA``, with the width of the ``\DATA`` port equal to ``\WIDTH`` parameter -times ``\WORDS`` parameter, and a bit enable mask input ``\EN`` with width equal -to ``\WIDTH`` parameter. All three of the inputs must resolve to a constant for +The `$meminit_v2` cells have an address input ``\ADDR``, a data input ``\DATA``, +with the width of the ``\DATA`` port equal to ``\WIDTH`` parameter times +``\WORDS`` parameter, and a bit enable mask input ``\EN`` with width equal to +``\WIDTH`` parameter. All three of the inputs must resolve to a constant for synthesis to succeed. ``\MEMID`` @@ -472,19 +467,18 @@ synthesis to succeed. initialization conflict. The HDL frontend models a memory using ``RTLIL::Memory`` objects and -asynchronous `$memrd_v2` and `$memwr_v2` cells. The `memory` pass -(i.e. its various sub-passes) migrates `$dff` cells into the `$memrd_v2` and -`$memwr_v2` cells making them synchronous, then converts them to a single -`$mem_v2` cell and (optionally) maps this cell type to `$dff` cells for the -individual words and multiplexer-based address decoders for the read and write -interfaces. When the last step is disabled or not possible, a `$mem_v2` cell -is left in the design. +asynchronous `$memrd_v2` and `$memwr_v2` cells. The `memory` pass (i.e. its +various sub-passes) migrates `$dff` cells into the `$memrd_v2` and `$memwr_v2` +cells making them synchronous, then converts them to a single `$mem_v2` cell and +(optionally) maps this cell type to `$dff` cells for the individual words and +multiplexer-based address decoders for the read and write interfaces. When the +last step is disabled or not possible, a `$mem_v2` cell is left in the design. The `$mem_v2` cell provides the following parameters: ``\MEMID`` - The name of the original ``RTLIL::Memory`` object that became this - `$mem_v2` cell. + The name of the original ``RTLIL::Memory`` object that became this `$mem_v2` + cell. ``\SIZE`` The number of words in the memory. @@ -502,19 +496,19 @@ The `$mem_v2` cell provides the following parameters: The number of read ports on this memory cell. ``\RD_WIDE_CONTINUATION`` - This parameter is ``\RD_PORTS`` bits wide, containing a bitmask of - "wide continuation" read ports. Such ports are used to represent the - extra data bits of wide ports in the combined cell, and must have all - control signals identical with the preceding port, except for address, - which must have the proper sub-cell address encoded in the low bits. + This parameter is ``\RD_PORTS`` bits wide, containing a bitmask of "wide + continuation" read ports. Such ports are used to represent the extra data + bits of wide ports in the combined cell, and must have all control signals + identical with the preceding port, except for address, which must have the + proper sub-cell address encoded in the low bits. ``\RD_CLK_ENABLE`` - This parameter is ``\RD_PORTS`` bits wide, containing a clock enable bit - for each read port. + This parameter is ``\RD_PORTS`` bits wide, containing a clock enable bit for + each read port. ``\RD_CLK_POLARITY`` - This parameter is ``\RD_PORTS`` bits wide, containing a clock polarity - bit for each read port. + This parameter is ``\RD_PORTS`` bits wide, containing a clock polarity bit + for each read port. ``\RD_TRANSPARENCY_MASK`` This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a @@ -523,62 +517,62 @@ The `$mem_v2` cell provides the following parameters: ``\RD_COLLISION_X_MASK`` This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a - concatenation of all ``\COLLISION_X_MASK`` values of the original - `$memrd_v2` cells. + concatenation of all ``\COLLISION_X_MASK`` values of the original `$memrd_v2` + cells. ``\RD_CE_OVER_SRST`` - This parameter is ``\RD_PORTS`` bits wide, determining relative - synchronous reset and enable priority for each read port. + This parameter is ``\RD_PORTS`` bits wide, determining relative synchronous + reset and enable priority for each read port. ``\RD_INIT_VALUE`` This parameter is ``\RD_PORTS*\WIDTH`` bits wide, containing the initial value for each synchronous read port. ``\RD_ARST_VALUE`` - This parameter is ``\RD_PORTS*\WIDTH`` bits wide, containing the - asynchronous reset value for each synchronous read port. + This parameter is ``\RD_PORTS*\WIDTH`` bits wide, containing the asynchronous + reset value for each synchronous read port. ``\RD_SRST_VALUE`` - This parameter is ``\RD_PORTS*\WIDTH`` bits wide, containing the - synchronous reset value for each synchronous read port. + This parameter is ``\RD_PORTS*\WIDTH`` bits wide, containing the synchronous + reset value for each synchronous read port. ``\WR_PORTS`` The number of write ports on this memory cell. ``\WR_WIDE_CONTINUATION`` - This parameter is ``\WR_PORTS`` bits wide, containing a bitmask of - "wide continuation" write ports. + This parameter is ``\WR_PORTS`` bits wide, containing a bitmask of "wide + continuation" write ports. ``\WR_CLK_ENABLE`` - This parameter is ``\WR_PORTS`` bits wide, containing a clock enable bit - for each write port. + This parameter is ``\WR_PORTS`` bits wide, containing a clock enable bit for + each write port. ``\WR_CLK_POLARITY`` - This parameter is ``\WR_PORTS`` bits wide, containing a clock polarity - bit for each write port. + This parameter is ``\WR_PORTS`` bits wide, containing a clock polarity bit + for each write port. ``\WR_PRIORITY_MASK`` This parameter is ``\WR_PORTS*\WR_PORTS`` bits wide, containing a - concatenation of all ``\PRIORITY_MASK`` values of the original - `$memwr_v2` cells. + concatenation of all ``\PRIORITY_MASK`` values of the original `$memwr_v2` + cells. The `$mem_v2` cell has the following ports: ``\RD_CLK`` - This input is ``\RD_PORTS`` bits wide, containing all clock signals for - the read ports. + This input is ``\RD_PORTS`` bits wide, containing all clock signals for the + read ports. ``\RD_EN`` - This input is ``\RD_PORTS`` bits wide, containing all enable signals for - the read ports. + This input is ``\RD_PORTS`` bits wide, containing all enable signals for the + read ports. ``\RD_ADDR`` - This input is ``\RD_PORTS*\ABITS`` bits wide, containing all address - signals for the read ports. + This input is ``\RD_PORTS*\ABITS`` bits wide, containing all address signals + for the read ports. ``\RD_DATA`` - This output is ``\RD_PORTS*\WIDTH`` bits wide, containing all data - signals for the read ports. + This output is ``\RD_PORTS*\WIDTH`` bits wide, containing all data signals + for the read ports. ``\RD_ARST`` This input is ``\RD_PORTS`` bits wide, containing all asynchronous reset @@ -593,26 +587,25 @@ The `$mem_v2` cell has the following ports: the write ports. ``\WR_EN`` - This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all enable - signals for the write ports. + This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all enable signals + for the write ports. ``\WR_ADDR`` - This input is ``\WR_PORTS*\ABITS`` bits wide, containing all address - signals for the write ports. + This input is ``\WR_PORTS*\ABITS`` bits wide, containing all address signals + for the write ports. ``\WR_DATA`` - This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all data - signals for the write ports. + This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all data signals for + the write ports. -The `memory_collect` pass can be used to convert discrete -`$memrd_v2`, `$memwr_v2`, and `$meminit_v2` cells belonging to the same -memory to a single `$mem_v2` cell, whereas the `memory_unpack` pass -performs the inverse operation. The `memory_dff` pass can combine -asynchronous memory ports that are fed by or feeding registers into synchronous -memory ports. The `memory_bram` pass can be used to recognize -`$mem_v2` cells that can be implemented with a block RAM resource on an FPGA. -The `memory_map` pass can be used to implement `$mem_v2` cells as -basic logic: word-wide DFFs and address decoders. +The `memory_collect` pass can be used to convert discrete `$memrd_v2`, +`$memwr_v2`, and `$meminit_v2` cells belonging to the same memory to a single +`$mem_v2` cell, whereas the `memory_unpack` pass performs the inverse operation. +The `memory_dff` pass can combine asynchronous memory ports that are fed by or +feeding registers into synchronous memory ports. The `memory_bram` pass can be +used to recognize `$mem_v2` cells that can be implemented with a block RAM +resource on an FPGA. The `memory_map` pass can be used to implement `$mem_v2` +cells as basic logic: word-wide DFFs and address decoders. Finite state machines ~~~~~~~~~~~~~~~~~~~~~ @@ -622,15 +615,17 @@ Add a brief description of the `$fsm` cell type. Coarse arithmetics ~~~~~~~~~~~~~~~~~~~~~ -The `$macc` cell type represents a generalized multiply and accumulate operation. The cell is purely combinational. It outputs the result of summing up a sequence of products and other injected summands. +The `$macc` cell type represents a generalized multiply and accumulate +operation. The cell is purely combinational. It outputs the result of summing up +a sequence of products and other injected summands. .. code-block:: Y = 0 +- a0factor1 * a0factor2 +- a1factor1 * a1factor2 +- ... + B[0] + B[1] + ... -The A port consists of concatenated pairs of multiplier inputs ("factors"). -A zero length factor2 acts as a constant 1, turning factor1 into a simple summand. +The A port consists of concatenated pairs of multiplier inputs ("factors"). A +zero length factor2 acts as a constant 1, turning factor1 into a simple summand. In this pseudocode, ``u(foo)`` means an unsigned int that's foo bits long. @@ -644,8 +639,8 @@ In this pseudocode, ``u(foo)`` means an unsigned int that's foo bits long. ... }; -The cell's ``CONFIG`` parameter determines the layout of cell port ``A``. -The CONFIG parameter carries the following information: +The cell's ``CONFIG`` parameter determines the layout of cell port ``A``. The +CONFIG parameter carries the following information: .. code-block:: @@ -714,8 +709,8 @@ Formal verification cells ~~~~~~~~~~~~~~~~~~~~~~~~~ Add information about `$check`, `$assert`, `$assume`, `$live`, `$fair`, -`$cover`, `$equiv`, `$initstate`, `$anyconst`, `$anyseq`, -`$anyinit`, `$allconst`, `$allseq` cells. +`$cover`, `$equiv`, `$initstate`, `$anyconst`, `$anyseq`, `$anyinit`, +`$allconst`, `$allseq` cells. Add information about `$ff` and `$_FF_` cells. @@ -733,8 +728,8 @@ has the following parameters: The width (in bits) of the signal on the ``\ARGS`` port. ``\TRG_ENABLE`` - True if triggered on specific signals defined in ``\TRG``; false if - triggered whenever ``\ARGS`` or ``\EN`` change and ``\EN`` is 1. + True if triggered on specific signals defined in ``\TRG``; false if triggered + whenever ``\ARGS`` or ``\EN`` change and ``\EN`` is 1. If ``\TRG_ENABLE`` is true, the following parameters also apply: @@ -792,12 +787,13 @@ width\ *?* (optional) The number of characters wide to pad to. base - * ``b`` for base-2 integers (binary) - * ``o`` for base-8 integers (octal) - * ``d`` for base-10 integers (decimal) - * ``h`` for base-16 integers (hexadecimal) - * ``c`` for ASCII characters/strings - * ``t`` and ``r`` for simulation time (corresponding to :verilog:`$time` and :verilog:`$realtime`) + * ``b`` for base-2 integers (binary) + * ``o`` for base-8 integers (octal) + * ``d`` for base-10 integers (decimal) + * ``h`` for base-16 integers (hexadecimal) + * ``c`` for ASCII characters/strings + * ``t`` and ``r`` for simulation time (corresponding to :verilog:`$time` and + :verilog:`$realtime`) For integers, this item may follow: @@ -1042,14 +1038,13 @@ Tables :numref:`%s `, :numref:`%s `, :numref:`%s `, :numref:`%s ` and :numref:`%s ` list all cell types used for gate level logic. The cell types `$_BUF_`, `$_NOT_`, -`$_AND_`, `$_NAND_`, `$_ANDNOT_`, `$_OR_`, `$_NOR_`, `$_ORNOT_`, -`$_XOR_`, `$_XNOR_`, `$_AOI3_`, `$_OAI3_`, `$_AOI4_`, `$_OAI4_`, -`$_MUX_`, `$_MUX4_`, `$_MUX8_`, `$_MUX16_` and `$_NMUX_` are used to -model combinatorial logic. The cell type `$_TBUF_` is used to model tristate -logic. +`$_AND_`, `$_NAND_`, `$_ANDNOT_`, `$_OR_`, `$_NOR_`, `$_ORNOT_`, `$_XOR_`, +`$_XNOR_`, `$_AOI3_`, `$_OAI3_`, `$_AOI4_`, `$_OAI4_`, `$_MUX_`, `$_MUX4_`, +`$_MUX8_`, `$_MUX16_` and `$_NMUX_` are used to model combinatorial logic. The +cell type `$_TBUF_` is used to model tristate logic. -The `$_MUX4_`, `$_MUX8_` and `$_MUX16_` cells are used to model wide -muxes, and correspond to the following Verilog code: +The `$_MUX4_`, `$_MUX8_` and `$_MUX16_` cells are used to model wide muxes, and +correspond to the following Verilog code: .. code-block:: verilog :force: @@ -1114,8 +1109,8 @@ following Verilog code template: The cell types ``$_DFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with asynchronous reset and enable. The values in the table for these cell types -relate to the following Verilog code template, where ``RST_EDGE`` is -``posedge`` if ``RST_LVL`` if ``1``, and ``negedge`` otherwise. +relate to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` +if ``RST_LVL`` if ``1``, and ``negedge`` otherwise. .. code-block:: verilog :force: @@ -1156,8 +1151,8 @@ in the table for these cell types relate to the following Verilog code template: The cell types ``$_DFFSR_[NP][NP][NP]_`` implement d-type flip-flops with asynchronous set and reset. The values in the table for these cell types relate to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` if -``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is ``posedge`` -if ``SET_LVL`` if ``1``, ``negedge`` otherwise. +``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is ``posedge`` if +``SET_LVL`` if ``1``, ``negedge`` otherwise. .. code-block:: verilog :force: @@ -1173,8 +1168,8 @@ if ``SET_LVL`` if ``1``, ``negedge`` otherwise. The cell types ``$_DFFSRE_[NP][NP][NP][NP]_`` implement d-type flip-flops with asynchronous set and reset and enable. The values in the table for these cell types relate to the following Verilog code template, where ``RST_EDGE`` is -``posedge`` if ``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` -is ``posedge`` if ``SET_LVL`` if ``1``, ``negedge`` otherwise. +``posedge`` if ``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is +``posedge`` if ``SET_LVL`` if ``1``, ``negedge`` otherwise. .. code-block:: verilog :force: diff --git a/docs/source/yosys_internals/formats/rtlil_rep.rst b/docs/source/yosys_internals/formats/rtlil_rep.rst index fec970532..b0cbfe3a5 100644 --- a/docs/source/yosys_internals/formats/rtlil_rep.rst +++ b/docs/source/yosys_internals/formats/rtlil_rep.rst @@ -76,11 +76,10 @@ This has three advantages: - Second, the information about which identifiers were originally provided by the user is always available which can help guide some optimizations. For - example, `opt_clean` tries to preserve signals with a user-provided - name but doesn't hesitate to delete signals that have auto-generated names - when they just duplicate other signals. Note that this can be overridden - with the ``-purge`` option to also delete internal nets with user-provided - names. + example, `opt_clean` tries to preserve signals with a user-provided name but + doesn't hesitate to delete signals that have auto-generated names when they + just duplicate other signals. Note that this can be overridden with the + ``-purge`` option to also delete internal nets with user-provided names. - Third, the delicate job of finding suitable auto-generated public visible names is deferred to one central location. Internally auto-generated names @@ -204,8 +203,8 @@ A "signal" is everything that can be applied to a cell port. I.e. - | Concatenations of the above | 1em For example: ``{16'd1337, mywire[15:8]}`` -The ``RTLIL::SigSpec`` data type is used to represent signals. The ``RTLIL::Cell`` -object contains one ``RTLIL::SigSpec`` for each cell port. +The ``RTLIL::SigSpec`` data type is used to represent signals. The +``RTLIL::Cell`` object contains one ``RTLIL::SigSpec`` for each cell port. In addition, connections between wires are represented using a pair of ``RTLIL::SigSpec`` objects. Such pairs are needed in different locations. @@ -234,9 +233,9 @@ control logic of the behavioural code. Let's consider a simple example: q <= d; endmodule -In this example there is no data path and therefore the ``RTLIL::Module`` generated -by the frontend only contains a few ``RTLIL::Wire`` objects and an ``RTLIL::Process`` . -The ``RTLIL::Process`` in RTLIL syntax: +In this example there is no data path and therefore the ``RTLIL::Module`` +generated by the frontend only contains a few ``RTLIL::Wire`` objects and an +``RTLIL::Process``. The ``RTLIL::Process`` in RTLIL syntax: .. code:: RTLIL :number-lines: @@ -320,8 +319,8 @@ trees before further processing them. One of the first actions performed on a design in RTLIL representation in most synthesis scripts is identifying asynchronous resets. This is usually done using -the `proc_arst` pass. This pass transforms the above example to the -following ``RTLIL::Process``: +the `proc_arst` pass. This pass transforms the above example to the following +``RTLIL::Process``: .. code:: RTLIL :number-lines: @@ -340,9 +339,9 @@ following ``RTLIL::Process``: end This pass has transformed the outer ``RTLIL::SwitchRule`` into a modified -``RTLIL::SyncRule`` object for the ``\reset`` signal. Further processing converts the -``RTLIL::Process`` into e.g. a d-type flip-flop with asynchronous reset and a -multiplexer for the enable signal: +``RTLIL::SyncRule`` object for the ``\reset`` signal. Further processing +converts the ``RTLIL::Process`` into e.g. a d-type flip-flop with asynchronous +reset and a multiplexer for the enable signal: .. code:: RTLIL :number-lines: @@ -365,11 +364,11 @@ multiplexer for the enable signal: connect \Y $0\q[0:0] end -Different combinations of passes may yield different results. Note that -`$adff` and `$mux` are internal cell types that still need to be mapped to -cell types from the target cell library. +Different combinations of passes may yield different results. Note that `$adff` +and `$mux` are internal cell types that still need to be mapped to cell types +from the target cell library. -Some passes refuse to operate on modules that still contain ``RTLIL::Process`` +Some passes refuse to operate on modules that still contain ``RTLIL::Process`` objects as the presence of these objects in a module increases the complexity. Therefore the passes to translate processes to a netlist of cells are usually called early in a synthesis script. The proc pass calls a series of other passes @@ -389,9 +388,9 @@ A memory object has the following properties: - The width of an addressable word - The size of the memory in number of words -All read accesses to the memory are transformed to `$memrd` cells and all -write accesses to `$memwr` cells by the language frontend. These cells consist -of independent read- and write-ports to the memory. Memory initialization is +All read accesses to the memory are transformed to `$memrd` cells and all write +accesses to `$memwr` cells by the language frontend. These cells consist of +independent read- and write-ports to the memory. Memory initialization is transformed to `$meminit` cells by the language frontend. The ``\MEMID`` parameter on these cells is used to link them together and to the ``RTLIL::Memory`` object they belong to. @@ -402,8 +401,8 @@ the separate `$memrd` and `$memwr` cells can be consolidated using resource sharing. As resource sharing is a non-trivial optimization problem where different synthesis tasks can have different requirements it lends itself to do the optimisation in separate passes and merge the ``RTLIL::Memory`` objects and -`$memrd` and `$memwr` cells to multiport memory blocks after resource -sharing is completed. +`$memrd` and `$memwr` cells to multiport memory blocks after resource sharing is +completed. The memory pass performs this conversion and can (depending on the options passed to it) transform the memories directly to d-type flip-flops and address diff --git a/docs/source/yosys_internals/techmap.rst b/docs/source/yosys_internals/techmap.rst index f894394bb..21b09c903 100644 --- a/docs/source/yosys_internals/techmap.rst +++ b/docs/source/yosys_internals/techmap.rst @@ -1,8 +1,8 @@ Techmap by example ------------------ -As a quick recap, the `techmap` command replaces cells in the design -with implementations given as Verilog code (called "map files"). It can replace +As a quick recap, the `techmap` command replaces cells in the design with +implementations given as Verilog code (called "map files"). It can replace Yosys' internal cell types (such as `$or`) as well as user-defined cell types. - Verilog parameters are used extensively to customize the internal cell types. @@ -94,8 +94,8 @@ Scripting in map modules .. note:: PROTIP: - Commands such as `shell`, ``show -pause``, and `dump` can - be used in the ``_TECHMAP_DO_*`` scripts for debugging map modules. + Commands such as `shell`, ``show -pause``, and `dump` can be used in the + ``_TECHMAP_DO_*`` scripts for debugging map modules. Example: From 21747c468c20fb743cbec6354e941d8ca18bf532 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 16 May 2024 11:32:14 +1200 Subject: [PATCH 037/496] Docs: Improve cell_help usage - Drop `cell_code` and instead map code lookups to the `cell_help` dict. - Add helper functions to struct for checking and getting the right cell. - Add `CellType` for cell to `write_cell_rst` function declaration in preparation for use in future. - Iterate over `yosys_celltypes.cell_types` when exporting cell rst files, reporting errors for any cells defined in `cell_types` but not `cell_help_messages`. --- kernel/register.cc | 65 +++++++++++++++++++++++-------------- techlibs/common/cellhelp.py | 8 ++--- 2 files changed, 43 insertions(+), 30 deletions(-) diff --git a/kernel/register.cc b/kernel/register.cc index b16a6f852..9fbd59020 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -766,15 +766,23 @@ struct SimHelper { string ver; }; +static bool is_code_getter(string name) { + return *(--(name.end())) == '+'; +} + +static string get_cell_name(string name) { + return is_code_getter(name) ? name.substr(0, name.length()-1) : name; +} + static struct CellHelpMessages { - dict cell_help, cell_code; + dict cell_help; CellHelpMessages() { - SimHelper tempCell; #include "techlibs/common/simlib_help.inc" #include "techlibs/common/simcells_help.inc" cell_help.sort(); - cell_code.sort(); } + bool contains(string name) { return cell_help.count(get_cell_name(name)) > 0; } + SimHelper get(string name) { return cell_help[get_cell_name(name)]; } } cell_help_messages; struct HelpPass : public Pass { @@ -884,7 +892,7 @@ struct HelpPass : public Pass { } fclose(f); } - void write_cell_rst(Yosys::SimHelper cell) + void write_cell_rst(Yosys::SimHelper cell, Yosys::CellType) { // open FILE *f = fopen(stringf("docs/source/cell/%s.rst", cell.filesafe_name().c_str()).c_str(), "wt"); @@ -985,9 +993,20 @@ struct HelpPass : public Pass { write_cmd_rst(it.first, it.second->short_help, buf.str()); } } + // this option is also undocumented as it is for internal use only else if (args[1] == "-write-rst-cells-manual") { - for (auto &it : cell_help_messages.cell_help) { - write_cell_rst(it.second); + bool raise_error = false; + for (auto &it : yosys_celltypes.cell_types) { + auto name = it.first.str(); + if (cell_help_messages.contains(name)) { + write_cell_rst(cell_help_messages.get(name), it.second); + } else { + log("ERROR: Missing cell help for cell '%s'.\n", name.c_str()); + raise_error |= true; + } + } + if (raise_error) { + log_error("One or more cells defined in celltypes.h are missing help documentation.\n"); } } else if (pass_register.count(args[1])) { @@ -998,29 +1017,27 @@ struct HelpPass : public Pass { log("\n"); } } - else if (cell_help_messages.cell_help.count(args[1])) { - SimHelper help_cell = cell_help_messages.cell_help.at(args[1]); - if (help_cell.ver == "2" || help_cell.ver == "2a") { - log("\n %s %s\n\n", help_cell.name.c_str(), help_cell.ports.c_str()); - if (help_cell.title != "") log("%s\n", help_cell.title.c_str()); - std::stringstream ss; - ss << help_cell.desc; - for (std::string line; std::getline(ss, line, '\n');) { - if (line != "::") log("%s\n", line.c_str()); + else if (cell_help_messages.contains(args[1])) { + auto help_cell = cell_help_messages.get(args[1]); + if (is_code_getter(args[1])) { + log("\n"); + log("%s\n", help_cell.code.c_str()); + } else { + if (help_cell.ver == "2" || help_cell.ver == "2a") { + log("\n %s %s\n\n", help_cell.name.c_str(), help_cell.ports.c_str()); + if (help_cell.title != "") log("%s\n", help_cell.title.c_str()); + std::stringstream ss; + ss << help_cell.desc; + for (std::string line; std::getline(ss, line, '\n');) { + if (line != "::") log("%s\n", line.c_str()); + } + } else { + log("%s\n", help_cell.desc.c_str()); } log("Run 'help %s+' to display the Verilog model for this cell type.\n", args[1].c_str()); log("\n"); - } else { - log("%s\n", help_cell.desc.c_str()); - log("Run 'help %s+' to display the Verilog model for this cell type.\n", args[1].c_str()); - log("\n"); } } - else if (cell_help_messages.cell_code.count(args[1])) { - SimHelper help_cell = cell_help_messages.cell_code.at(args[1]); - log("\n"); - log("%s\n", help_cell.code.c_str()); - } else log("No such command or cell type: %s\n", args[1].c_str()); return; diff --git a/techlibs/common/cellhelp.py b/techlibs/common/cellhelp.py index a975c31e5..0cfb2052f 100644 --- a/techlibs/common/cellhelp.py +++ b/techlibs/common/cellhelp.py @@ -22,18 +22,14 @@ class SimHelper: "name", "title", "ports", "source", "desc", "code", "ver", ] # generate C++ struct - val = "tempCell = {\n" + val = f"cell_help[{json.dumps(self.name)}] = " + val += "{\n" for field in printed_fields: field_val = getattr(self, field) if isinstance(field_val, list): field_val = "\n".join(field_val) val += f' {json.dumps(field_val)},\n' val += "};\n" - - # map name to struct - val += f'cell_help[{json.dumps(self.name)}] = tempCell;' - val += "\n" - val += f'cell_code[{json.dumps(self.name + "+")}] = tempCell;' return val def simcells_reparse(cell: SimHelper): From 4c9c4c1419fbddd0333afca44087093cfebcf213 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 16 May 2024 12:15:57 +1200 Subject: [PATCH 038/496] celltypes.h: Add extra properties --- kernel/celltypes.h | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/kernel/celltypes.h b/kernel/celltypes.h index 6aebabc19..3167a9add 100644 --- a/kernel/celltypes.h +++ b/kernel/celltypes.h @@ -29,6 +29,8 @@ struct CellType RTLIL::IdString type; pool inputs, outputs; bool is_evaluable; + bool is_combinatorial; + bool is_synthesizable; }; struct CellTypes @@ -56,9 +58,9 @@ struct CellTypes setup_stdcells_mem(); } - void setup_type(RTLIL::IdString type, const pool &inputs, const pool &outputs, bool is_evaluable = false) + void setup_type(RTLIL::IdString type, const pool &inputs, const pool &outputs, bool is_evaluable = false, bool is_combinatorial = false, bool is_synthesizable = false) { - CellType ct = {type, inputs, outputs, is_evaluable}; + CellType ct = {type, inputs, outputs, is_evaluable, is_combinatorial, is_synthesizable}; cell_types[ct.type] = ct; } From 063a6bc2d71085274810556e4f0d0b1dda70b37b Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 16 May 2024 12:16:24 +1200 Subject: [PATCH 039/496] register.cc: Include properties in docs --- kernel/register.cc | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/kernel/register.cc b/kernel/register.cc index 9fbd59020..4dfa79845 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -892,7 +892,7 @@ struct HelpPass : public Pass { } fclose(f); } - void write_cell_rst(Yosys::SimHelper cell, Yosys::CellType) + void write_cell_rst(Yosys::SimHelper cell, Yosys::CellType ct) { // open FILE *f = fopen(stringf("docs/source/cell/%s.rst", cell.filesafe_name().c_str()).c_str(), "wt"); @@ -919,9 +919,21 @@ struct HelpPass : public Pass { fprintf(f, " %s\n", line.c_str()); } + // properties + fprintf(f, "\nProperties"); + fprintf(f, "\n----------\n\n"); + dict prop_dict = { + {"is_evaluable", ct.is_evaluable}, + {"is_combinatorial", ct.is_combinatorial}, + {"is_synthesizable", ct.is_synthesizable}, + }; + for (auto &it : prop_dict) { + fprintf(f, "- %s: %s\n", it.first.c_str(), it.second ? "true" : "false"); + } + // source code - fprintf(f, "\nSimulation model (Verilog)\n"); - fprintf(f, "--------------------------\n\n"); + fprintf(f, "\nSimulation model (Verilog)"); + fprintf(f, "\n--------------------------\n\n"); fprintf(f, ".. code-block:: verilog\n"); fprintf(f, " :caption: %s\n\n", cell.source.c_str()); std::stringstream ss2; From 06e5e18371bce001710b7c7183f481cabc405b24 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 16 May 2024 12:17:03 +1200 Subject: [PATCH 040/496] simlib.v: Autolink referenced cells in alu --- techlibs/common/simlib.v | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/techlibs/common/simlib.v b/techlibs/common/simlib.v index 96f143c2a..6bcace498 100644 --- a/techlibs/common/simlib.v +++ b/techlibs/common/simlib.v @@ -626,8 +626,8 @@ endmodule //- A building block supporting both binary addition/subtraction operations, and //- indirectly, comparison operations. //- Typically created by the `alumacc` pass, which transforms: -//- $add, $sub, $lt, $le, $ge, $gt, $eq, $eqx, $ne, $nex -//- cells into this $alu cell. +//- `$add`, `$sub`, `$lt`, `$le`, `$ge`, `$gt`, `$eq`, `$eqx`, `$ne`, `$nex` +//- cells into this `$alu` cell. //- module \$alu (A, B, CI, BI, X, Y, CO); From e5f54dd7cd2c449360dbb787ad10dd10df450638 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 17 May 2024 17:54:08 +1200 Subject: [PATCH 041/496] Docs: Cell reference as a custom documenter Use autodocs to perform cell reference docs generation instead of generating rst files directly. e.g. ``` .. autocell:: simlib.v:$alu :source: :linenos: ``` --- docs/source/conf.py | 15 +- docs/util/cellref.py | 367 +++++++++++++++++++++++++++++++++++++++++++ docs/util/cmdref.py | 153 +++++++++++++++++- 3 files changed, 526 insertions(+), 9 deletions(-) create mode 100644 docs/util/cellref.py diff --git a/docs/source/conf.py b/docs/source/conf.py index bfabe60e5..9a22d50d3 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -100,9 +100,14 @@ latex_elements = { sys.path += [os.path.dirname(__file__) + "/../"] extensions.append('util.cmdref') -def setup(sphinx): - from util.RtlilLexer import RtlilLexer - sphinx.add_lexer("RTLIL", RtlilLexer) +# use autodocs +extensions.append('sphinx.ext.autodoc') +extensions.append('util.cellref') - from util.YoscryptLexer import YoscryptLexer - sphinx.add_lexer("yoscrypt", YoscryptLexer) \ No newline at end of file +from sphinx.application import Sphinx +def setup(app: Sphinx) -> None: + from util.RtlilLexer import RtlilLexer + app.add_lexer("RTLIL", RtlilLexer) + + from util.YoscryptLexer import YoscryptLexer + app.add_lexer("yoscrypt", YoscryptLexer) diff --git a/docs/util/cellref.py b/docs/util/cellref.py new file mode 100644 index 000000000..4deda41dd --- /dev/null +++ b/docs/util/cellref.py @@ -0,0 +1,367 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +from pathlib import Path +import re + +from typing import Any +from sphinx.application import Sphinx +from sphinx.ext import autodoc +from sphinx.ext.autodoc import Documenter +from sphinx.util import logging + +logger = logging.getLogger(__name__) + +# cell signature +cell_ext_sig_re = re.compile( + r'''^ (?:([\w._/]+):)? # explicit file name + ([\w$._]+?)? # module and/or class name(s) + (?:\.([\w_]+))? # optional: thing name + (::[\w_]+)? # attribute + \s* $ # and nothing more + ''', re.VERBOSE) + +class SimHelper: + name: str = "" + title: str = "" + ports: str = "" + source: str = "" + desc: list[str] + code: list[str] + group: str = "" + ver: str = "1" + + def __init__(self) -> None: + self.desc = [] + +def simcells_reparse(cell: SimHelper): + # cut manual signature + cell.desc = cell.desc[3:] + + # code-block truth table + new_desc = [] + indent = "" + for line in cell.desc: + if line.startswith("Truth table:"): + indent = " " + new_desc.pop() + new_desc.extend(["::", ""]) + new_desc.append(indent + line) + cell.desc = new_desc + + # set version + cell.ver = "2a" + +def load_cell_lib(file: Path): + simHelpers: dict[str, SimHelper] = {} + simHelper = SimHelper() + with open(file, "r") as f: + lines = f.readlines() + + for lineno, line in enumerate(lines, 1): + line = line.rstrip() + # special comments + if line.startswith("//-"): + simHelper.desc.append(line[4:] if len(line) > 4 else "") + elif line.startswith("//* "): + _, key, val = line.split(maxsplit=2) + setattr(simHelper, key, val) + + # code parsing + if line.startswith("module "): + clean_line = line[7:].replace("\\", "").replace(";", "") + simHelper.name, simHelper.ports = clean_line.split(maxsplit=1) + simHelper.code = [] + simHelper.source = f'{file.name}:{lineno}' + elif not line.startswith("endmodule"): + line = " " + line + try: + simHelper.code.append(line.replace("\t", " ")) + except AttributeError: + # no module definition, ignore line + pass + if line.startswith("endmodule"): + if simHelper.ver == "1" and file.name == "simcells.v": + # default simcells parsing + simcells_reparse(simHelper) + if not simHelper.desc: + # no help + simHelper.desc.append("No help message for this cell type found.\n") + elif simHelper.ver == "1" and file.name == "simlib.v" and simHelper.desc[1].startswith(' '): + simHelper.desc.pop(1) + simHelpers[simHelper.name] = simHelper + simHelper = SimHelper() + return simHelpers + +class YosysCellDocumenter(Documenter): + objtype = 'cell' + parsed_libs: dict[Path, dict[str, SimHelper]] = {} + object: SimHelper + + option_spec = { + 'source': autodoc.bool_option, + 'linenos': autodoc.bool_option, + } + + @classmethod + def can_document_member( + cls, + member: Any, + membername: str, + isattr: bool, + parent: Any + ) -> bool: + sourcename = str(member).split(":")[0] + if not sourcename.endswith(".v"): + return False + if membername == "__source": + return False + + def parse_name(self) -> bool: + try: + matched = cell_ext_sig_re.match(self.name) + path, modname, thing, attribute = matched.groups() + except AttributeError: + logger.warning(('invalid signature for auto%s (%r)') % (self.objtype, self.name), + type='cellref') + return False + + if not path: + return False + + self.modname = modname + self.objpath = [path] + self.attribute = attribute + self.fullname = ((self.modname) + (thing or '')) + + return True + + def import_object(self, raiseerror: bool = False) -> bool: + # find cell lib file + objpath = Path('/'.join(self.objpath)) + if not objpath.exists(): + objpath = Path('source') / 'generated' / objpath + + # load cell lib + try: + parsed_lib = self.parsed_libs[objpath] + except KeyError: + parsed_lib = load_cell_lib(objpath) + self.parsed_libs[objpath] = parsed_lib + + # get cell + try: + self.object = parsed_lib[self.modname] + except KeyError: + return False + + self.real_modname = f'{objpath}:{self.modname}' + return True + + def get_sourcename(self) -> str: + return self.objpath + + def format_name(self) -> str: + return self.object.name + + def format_signature(self, **kwargs: Any) -> str: + return f"{self.object.name} {self.object.ports}" + + def add_directive_header(self, sig: str) -> None: + domain = getattr(self, 'domain', self.objtype) + directive = getattr(self, 'directivetype', 'def') + name = self.format_name() + sourcename = self.get_sourcename() + cell = self.object + + # cell definition + self.add_line(f'.. {domain}:{directive}:: {name}', sourcename) + + # options + opt_attrs = ["title", ] + for attr in opt_attrs: + val = getattr(cell, attr, None) + if val: + self.add_line(f' :{attr}: {val}', sourcename) + + if self.options.noindex: + self.add_line(' :noindex:', sourcename) + + def add_content(self, more_content: Any | None) -> None: + # set sourcename and add content from attribute documentation + sourcename = self.get_sourcename() + startline = int(self.object.source.split(":")[1]) + + for i, line in enumerate(self.object.desc, startline): + self.add_line(line, sourcename, i) + + # add additional content (e.g. from document), if present + if more_content: + for line, src in zip(more_content.data, more_content.items): + self.add_line(line, src[0], src[1]) + + def filter_members( + self, + members: list[tuple[str, Any]], + want_all: bool + ) -> list[tuple[str, Any, bool]]: + return [(x[0], x[1], False) for x in members] + + def get_object_members( + self, + want_all: bool + ) -> tuple[bool, list[tuple[str, Any]]]: + ret: list[tuple[str, str]] = [] + + if self.options.source: + ret.append(('__source', self.real_modname)) + + return False, ret + + def document_members(self, all_members: bool = False) -> None: + want_all = (all_members or + self.options.inherited_members) + # find out which members are documentable + members_check_module, members = self.get_object_members(want_all) + + # document non-skipped members + memberdocumenters: list[tuple[Documenter, bool]] = [] + for (mname, member, isattr) in self.filter_members(members, want_all): + classes = [cls for cls in self.documenters.values() + if cls.can_document_member(member, mname, isattr, self)] + if not classes: + # don't know how to document this member + continue + # prefer the documenter with the highest priority + classes.sort(key=lambda cls: cls.priority) + # give explicitly separated module name, so that members + # of inner classes can be documented + full_mname = self.real_modname + '::' + mname + documenter = classes[-1](self.directive, full_mname, self.indent) + memberdocumenters.append((documenter, isattr)) + + member_order = self.options.member_order or self.config.autodoc_member_order + memberdocumenters = self.sort_members(memberdocumenters, member_order) + + for documenter, isattr in memberdocumenters: + documenter.generate( + all_members=True, real_modname=self.real_modname, + check_module=members_check_module and not isattr) + + def generate( + self, + more_content: Any | None = None, + real_modname: str | None = None, + check_module: bool = False, + all_members: bool = False + ) -> None: + if not self.parse_name(): + # need a cell lib to import from + logger.warning( + f"don't know which cell lib to import for autodocumenting {self.name}", + type = 'cellref' + ) + return + + self.import_object() + + # check __module__ of object (for members not given explicitly) + # if check_module: + # if not self.check_module(): + # return + + sourcename = self.get_sourcename() + self.add_line('', sourcename) + + # format the object's signature, if any + try: + sig = self.format_signature() + except Exception as exc: + logger.warning(('error while formatting signature for %s: %s'), + self.fullname, exc, type='cellref') + return + + # generate the directive header and options, if applicable + self.add_directive_header(sig) + self.add_line('', sourcename) + + # e.g. the module directive doesn't have content + self.indent += self.content_indent + + # add all content (from docstrings, attribute docs etc.) + self.add_content(more_content) + + # document members, if possible + self.document_members(all_members) + +class YosysCellSourceDocumenter(YosysCellDocumenter): + objtype = 'cellsource' + priority = 20 + + @classmethod + def can_document_member( + cls, + member: Any, + membername: str, + isattr: bool, + parent: Any + ) -> bool: + sourcename = str(member).split(":")[0] + if not sourcename.endswith(".v"): + return False + if membername != "__source": + return False + if isinstance(parent, YosysCellDocumenter): + return True + return False + + def add_directive_header(self, sig: str) -> None: + domain = getattr(self, 'domain', 'cell') + directive = getattr(self, 'directivetype', 'source') + name = self.format_name() + sourcename = self.get_sourcename() + cell = self.object + + # cell definition + self.add_line(f'.. {domain}:{directive}:: {name}', sourcename) + + if self.options.linenos: + self.add_line(f' :source: {cell.source.split(":")[0]}', sourcename) + else: + self.add_line(f' :source: {cell.source}', sourcename) + self.add_line(f' :language: verilog', sourcename) + + if self.options.linenos: + startline = int(self.object.source.split(":")[1]) + self.add_line(f' :lineno-start: {startline}', sourcename) + + if self.options.noindex: + self.add_line(' :noindex:', sourcename) + + def add_content(self, more_content: Any | None) -> None: + # set sourcename and add content from attribute documentation + sourcename = self.get_sourcename() + startline = int(self.object.source.split(":")[1]) + + for i, line in enumerate(self.object.code, startline-1): + self.add_line(line, sourcename, i) + + # add additional content (e.g. from document), if present + if more_content: + for line, src in zip(more_content.data, more_content.items): + self.add_line(line, src[0], src[1]) + + def get_object_members( + self, + want_all: bool + ) -> tuple[bool, list[tuple[str, Any]]]: + return False, [] + +def setup(app: Sphinx) -> dict[str, Any]: + app.setup_extension('sphinx.ext.autodoc') + app.add_autodocumenter(YosysCellDocumenter) + app.add_autodocumenter(YosysCellSourceDocumenter) + return { + 'version': '1', + 'parallel_read_safe': True, + } diff --git a/docs/util/cmdref.py b/docs/util/cmdref.py index aac899388..df1f3fb21 100644 --- a/docs/util/cmdref.py +++ b/docs/util/cmdref.py @@ -1,5 +1,9 @@ # based on https://github.com/ofosos/sphinxrecipes/blob/master/sphinxrecipes/sphinxrecipes.py +from __future__ import annotations + +from docutils import nodes +from docutils.nodes import Node, Element from docutils.parsers.rst import directives from docutils.parsers.rst.states import Inliner from sphinx.application import Sphinx @@ -7,24 +11,59 @@ from sphinx.domains import Domain, Index from sphinx.domains.std import StandardDomain from sphinx.roles import XRefRole from sphinx.directives import ObjectDescription +from sphinx.directives.code import container_wrapper from sphinx.util.nodes import make_refnode from sphinx import addnodes -class CommandNode(ObjectDescription): +class TocNode(ObjectDescription): + def _object_hierarchy_parts(self, sig_node: addnodes.desc_signature) -> tuple[str, ...]: + if 'fullname' not in sig_node: + return () + + modname = sig_node.get('module') + fullname = sig_node['fullname'] + + if modname: + return (modname, *fullname.split('::')) + else: + return tuple(fullname.split('::')) + + def _toc_entry_name(self, sig_node: addnodes.desc_signature) -> str: + if not sig_node.get('_toc_parts'): + return '' + + config = self.env.app.config + objtype = sig_node.parent.get('objtype') + if config.add_function_parentheses and objtype in {'function', 'method'}: + parens = '()' + else: + parens = '' + *parents, name = sig_node['_toc_parts'] + if config.toc_object_entries_show_parents == 'domain': + return sig_node.get('fullname', name) + parens + if config.toc_object_entries_show_parents == 'hide': + return name + parens + if config.toc_object_entries_show_parents == 'all': + return '.'.join(parents + [name + parens]) + return '' + +class CommandNode(TocNode): """A custom node that describes a command.""" name = 'cmd' required_arguments = 1 option_spec = { - 'title': directives.unchanged_required, + 'title': directives.unchanged, 'tags': directives.unchanged } def handle_signature(self, sig, signode: addnodes.desc_signature): + fullname = sig + signode['fullname'] = fullname signode += addnodes.desc_addname(text="yosys> help ") signode += addnodes.desc_name(text=sig) - return sig + return fullname def add_target_and_index(self, name_cls, sig, signode): signode['ids'].append(type(self).name + '-' + sig) @@ -32,7 +71,7 @@ class CommandNode(ObjectDescription): name = "{}.{}.{}".format(self.name, type(self).__name__, sig) tagmap = self.env.domaindata[type(self).name]['obj2tag'] tagmap[name] = list(self.options.get('tags', '').split(' ')) - title = self.options.get('title') + title = self.options.get('title', sig) titlemap = self.env.domaindata[type(self).name]['obj2title'] titlemap[name] = title objs = self.env.domaindata[type(self).name]['objects'] @@ -48,6 +87,111 @@ class CellNode(CommandNode): name = 'cell' +class CellSourceNode(TocNode): + """A custom code block for including cell source.""" + + name = 'cellsource' + + option_spec = { + "source": directives.unchanged_required, + "language": directives.unchanged_required, + 'lineno-start': int, + } + + def handle_signature( + self, + sig, + signode: addnodes.desc_signature + ) -> str: + language = self.options.get('language') + fullname = sig + "::" + language + signode['fullname'] = fullname + signode += addnodes.desc_name(text="Simulation model") + signode += addnodes.desc_sig_space() + signode += addnodes.desc_addname(text=f'({language})') + return fullname + + def add_target_and_index( + self, + name: str, + sig: str, + signode: addnodes.desc_signature + ) -> None: + idx = f'{".".join(self.name.split(":"))}.{sig}' + signode['ids'].append(idx) + + def run(self) -> list[Node]: + """Override run to parse content as a code block""" + if ':' in self.name: + self.domain, self.objtype = self.name.split(':', 1) + else: + self.domain, self.objtype = '', self.name + self.indexnode = addnodes.index(entries=[]) + + node = addnodes.desc() + node.document = self.state.document + source, line = self.get_source_info() + if line is not None: + line -= 1 + self.state.document.note_source(source, line) + node['domain'] = self.domain + # 'desctype' is a backwards compatible attribute + node['objtype'] = node['desctype'] = self.objtype + node['noindex'] = noindex = ('noindex' in self.options) + node['noindexentry'] = ('noindexentry' in self.options) + node['nocontentsentry'] = ('nocontentsentry' in self.options) + if self.domain: + node['classes'].append(self.domain) + node['classes'].append(node['objtype']) + + self.names = [] + signatures = self.get_signatures() + for sig in signatures: + # add a signature node for each signature in the current unit + # and add a reference target for it + signode = addnodes.desc_signature(sig, '') + self.set_source_info(signode) + node.append(signode) + try: + # name can also be a tuple, e.g. (classname, objname); + # this is strictly domain-specific (i.e. no assumptions may + # be made in this base class) + name = self.handle_signature(sig, signode) + except ValueError: + # signature parsing failed + signode.clear() + signode += addnodes.desc_name(sig, sig) + continue # we don't want an index entry here + finally: + # Private attributes for ToC generation. Will be modified or removed + # without notice. + if self.env.app.config.toc_object_entries: + signode['_toc_parts'] = self._object_hierarchy_parts(signode) + signode['_toc_name'] = self._toc_entry_name(signode) + else: + signode['_toc_parts'] = () + signode['_toc_name'] = '' + if name not in self.names: + self.names.append(name) + if not noindex: + # only add target and index entry if this is the first + # description of the object with this name in this desc block + self.add_target_and_index(name, sig, signode) + + # handle code + code = '\n'.join(self.content) + literal: Element = nodes.literal_block(code, code) + if 'lineno-start' in self.options: + literal['linenos'] = True + literal['highlight_args'] = { + 'linenostart': self.options['lineno-start'] + } + literal['classes'] += self.options.get('class', []) + literal['language'] = self.options.get('language') + literal = container_wrapper(self, literal, self.options.get('source')) + + return [self.indexnode, node, literal] + class TagIndex(Index): """A custom directive that creates a tag matrix.""" @@ -223,6 +367,7 @@ class CellDomain(CommandDomain): directives = { 'def': CellNode, + 'source': CellSourceNode, } indices = { From a66e94c5da9bd67c44a540a53455ba4f6384d9f9 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 20 May 2024 12:29:23 +1200 Subject: [PATCH 042/496] Docs: Switch to furo-ys --- docs/source/_static/favico.png | Bin 33435 -> 0 bytes docs/source/_static/yosyshq.css | 40 ---------------------------- docs/source/_templates/page.html | 44 ------------------------------- docs/source/conf.py | 30 +++------------------ docs/source/requirements.txt | 2 +- 5 files changed, 4 insertions(+), 112 deletions(-) delete mode 100644 docs/source/_static/favico.png delete mode 100644 docs/source/_static/yosyshq.css delete mode 100644 docs/source/_templates/page.html diff --git a/docs/source/_static/favico.png b/docs/source/_static/favico.png deleted file mode 100644 index 3f5afba76569d0610c2f7efead58417c4c9ab050..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 33435 zcmb4rcRbbY|Nq-TN+OYL#a#%=D0?P~P!uQgWTYq~dmpLDOt!3&RMsg(=823lBZ_R< zdvAWP_i=wdpYOlF9*_IJJJ)<&ukn11>w4c$uWG3sqGqK=5aiJ1ODZ}DLP0?P*}o53 zCQsxw!+$6ol`mi44}ZM&TLdD=apba!(sj4QsUFP`qq{DrMjW}{#vhSlef*C(Vi+US zg*WJ^p|@~H$oD1wApCfGh30B!{k+-ff_6IFj;1{B0+G_Q_QCk+&|~jzx?Abli3)A- z-ZXK$wOoY7`(Yw${-LZg_Y_HcZuMGSUv$w!>0^+^BCjv^V2Q-c;=SS$Z1nmo>ADcN zS=XjxWI){i#~-`r>E!6}o)0&BQqDURA7!zL7YRPKV=>zn+9!|{-2R4$f$rYBXL zKPMito9Ws9Rwbq8A81cnz{3U|AZDvpvvQ+CFH&0}Y(GqXi4urUj<<4HF6#~p)E-$~ z?)OyP4}3`F?RfA1BUCnL)X>N~SIWkx*w=M2@1ocJjm86lup!pLrv1y92m7oFr@lic zhyG~9yn_lKAx?%D#Esw{-@oo@7;)38#*L+KHn&NBt)O{!XKm8bOL(JdZ@$uG`;ObQ z4=-5qEPeX^J#NG7w+Xf=T37&S_@!FlYb6<&W*MtbPanTN|FMEMvw8ms=*kLQw)S1w z`q^G|=ULuBV_AuUJ64=rpqkX_)NSB=wm7-3yD228^(HrWg4YI#E;gP=Ftz0t>^kMa z=^GKB&6k_}ZMyXUR)`us&)D11k{sHgaGLT{VybNIy?W#9S+sj|L{LiO9E3&Rr011t z-u7XnPl;~&Vomsp3QpQ0udB~ibfSSdx@kfF|A@9pX;sRP5=L+k^f*Fn|2lB6{4tga zeSnH^P+NU8b#scu{FpykGun24=anq(#Wp=S!E$4Kf7U)qCYYH2J1^o(oB#RQ5|7M~ zagPFpGaUXix;PMyqQ?EHsdkaTo-BUa( zs$QG=Cy}%lQzz_|J34<%;F`%rmD?c_nVUUqzOQdEVqv?MBf=}jmNi9AF`vKd)^~qC zvPT3FF?7?eztoA+=InVW5OZ9OJY`pw(zom3So>pfh)#?n+h<|H+axtCY0 zaDO46i#OKb;tSgT>`!8-#O%pujq2wUL=`XTv#rvS!&eCxU$s0T7(jH8H-zaI5sWqb}}) zqJAmsIrAw0Qtt;syMuEh86|3w9m~lGuXJgVADk)8CGzxXc$?cr263f zpz$dfRH}EBer#+!S9Fu21Rnt#XxCg)wEghGv%*j&VAK7VrNs%S%xtoy=Q_hyb#NaJ z$Lq6md5s?Pl{b)V5T>3pjs_6tZj}CFn}vDEGgwZ|3B0ADMa?}x z+}I{1Pkut&i?qvfO?=|=Yo}Ov_7?fw-PzaJu;SHwQ_26%*5+_FBetQj?N;#j%-B-N z&}C3dbt^ELVk<{0UkTAq8lza}c#ZPIAzIgPA`+SwH>9f!EkhD)-0j^aZH=YD-L`Oi z&pi1(j+N){eORg*)J_#_Ic)X&?NMNpDJr3HK7fvr``0&Jqx9=7L!K4FT3l61u3;Xx zuV_D6e@r^Qj;P0U-w}EU{9-*2fumo z%^ue_o(e_3>S(zQLT^xrZSTVB_N7}Ai(p8O1=ptU^XGoIUU;XA-NH~Z>Bm^DUmK^< zU%2;rZp>cCW}OU4ttCOib(5p99c6O|KRO}B(;ykGoMF?bCOGM$r^1G*!g^$@2(W&* z3-IfOtXy4=R%}+nf3RPA-}C?lll}wIkap`DF;_Y}pNXfS{!4WLh1Ls8$qVo0Lg*Ky zVf*}t5-K!io2c5Xn2{mG3BycURf&bQ<6<@Gd2^zmV(Na?=^P|wRv*O%hID>AOE*=G zLGbM^JmGZQRhv68-$Fk8+3y~Y3D)o|wjT1&t&e+h1a{Nw7-`zcS$JOtTZvLK#dfIZ zrHcs~)$rvE9}6g)m~OoW^sjgR?#$#dFL9#nt!6&ar;Bso4~X<&^-iE~?)G-dE7z5V zD9PUWMf;A+?U|^iFC{EIe=Vs6&sa&0^;~OW|9fA85rZfeqP|sR|LmkpCG!bkK0?v! zHz{gTR3Em-sBi1yS?-Ytze%2xab7oWm{m7_i){Mm5);f(z@}^I#tq-lvIr?*n_c zw765jV-kfmW!JLSpadaS=Zs2}L=1R)s+}7U;{%Gv=Jd)qk`26s&DpDDuL7?XW$w>R z&E9^4d0iDkf8-@`@FA<3gzvSQOXvpEc{iu+)M{MD*^QD!lmR*a{CLfop7z4-%~#;P zUgz7DPiBX0*^TIH_Fuy}*z#WR#g(=NADPrEBdPvU=WSc%?o%MspHumeB!(D{5{eO|@thLg<72>vf0x zk7b~nr+0y&hSGT6)sGUX^Z|*T37!8^e+|_hoqN|kWnfWnSX9HW+Eb2;Yl(5_Bg$IB zRfrh`scyzLeHmoonG&XCnspXszn(7Ul#D71lNrc|!=hUt$$$8)>TgqO!KRn<0adbm zfG@Zl@D11gj_0sZZB{eiQs5`JWmH|3J0#)O5RT3r8S(Hjzw1c{%ksjq=h?Bn@^)f~w9SYC;S_2=HB zL9(c;#%O9%2>nU`CfF3`MM$+e*-?h#L+YV_S(iRtnj}(Leib*r@7TncnU)8@nt;}m@0lIU zUsr|<3ob?jsx(0$REr<|_hPd;R+7KYL2P6FNnK z;L_0`FXodYOZ*ugLuYEia&s?2wWz8{gFkqaGaO(yOt&ETY`P+Y`^;|sNI=`~q6#zD z)T59e-_Fi*Xj<34BSWzKFWR^7M&7zBqi+^sU%*cY+&|=>6d@wVGNLrjjJhi@4!#Aa zU%di34cC9D>*DC?Yp7&SntQk{w)LP)#c|sH{ZOXgaPf9S$9wXNV?jE&TV90VeILBt zCUbZ?5X7nLc0mOMx9N@qY1^+Knm-As`#qljl7l)P)Ib5!jGmO~3o1v3j=wsZPOMzR z#ahnDC;!Ytm+$9BWfqySI#p)YE9zL!JYcPZTTYz+GGp_^eb!#*4-5D#E2CyR7cta8 zGr#Q(=x%%IzSvaHTunNuHVnE`1|cG^*ijlmtr~;z{S7IY%+Z9i@`N?o4S%IDsM=sm||)`p#0mJ|hLJj=_{R`nufCMFD=uHAy!>LJV&ytie2k>Y7h@q<`i~Bn5LSaMZ7TDBy#Llp z#y9j|pZ4XU_`GxCd4-)Hu_>~GAVs_nngN*GZ(JN_Uux-`8|m#yS-XU6um~-_vhgzlL=qUB*Sh%L*mF_8&-qXe2ZVk699=|+vSxx}-8lMcIdjlandQh~DGwbL8Q)RNlCNBKk{IYP; zc?sXOVP0)@H8KR}j4E#YT@1cMQZATlXS^qrH{H?xoEC05Wc~|hJ#$h~{9y!7*#)p3 zrJvt;)=W>DTt9<2!7}787b~*8Vqh>qix9iBZ&0OOnmu81t!z~BSE1AS-&Twi?0M9^!|A7BU@GpXsmuhUtcDqw&C7+eA6RrdGausr> zLi#`ctEB3q_|>~!oHMeNdfLofe?vvz@cL(I)B^OpfDA8*1vuO94W86wx>Tk+mq4&;}!LUe8wVicZ!>dgw`0q0ZK1I{XC<@A`P$ z(&wTo7%(?|uF!AJrx8_k2;zX?{Jyh8Cbxg5t7ll$xRIjFFT)_MaN!_$M12RkYN-$LDbxJx2!8=__%Fs6ItwS1t%+h zf?jtT-DI|Xerzyc-axiT32E3Kp2<$VZWA^Cq{p!q(yc_Db=1o1S^c*SdmR}j5SQzJ z8SoxZfIpp92bV298bGc^ekIi_X zB%;`y4eEJm_TbHvQUXc%U|n1`;od%*bg`EEEFYHF^vZNm77f#gy0rN_=v^XZo^9$J zX+(p&IaI?F3HfvfkYmAh zBWS&xLNGQr4pDK%h7qa1F(=V1Lbik;g4dD(DZYOXnMYIaB>zPqMsUc#;bzU$kH!rx z(vaSoCKC>pj!T5reex2nK^PlK7A}ixkmYb`PuxT$B}j4?SB|X{HbfOpbNHc)q_P`) ztQ!=sDz)NbLWtG|5QF;Dr1>u?lMpuLzO=Gm!NY`0o4Hu_O~_jHI?zN>)3Jp|Vh|jz z8XTtq!lM^AtOn4tV5QJ%#hVwMWAPyct@M&ylpR6t(liS8SZdPjS`;|0!17uQ@)ukm zV{EDuEv>_EvXVNhmSxLhS$co{kck(8*!qRp1VY(Cjpma-IrFZp+#*AqdQ}SwBgeV< zHZs3utXy)%V{9HLGIPDAK<7)NMJ2TnK$g_kA&JpV#7$73OOa@dzZB^W4!cLZ?)N$A zOS6_&er0Yuj5C+Mfaw-PzlDdztGWwNVac3-zb&ImH4uMmt*pfblxlvg%0oa_>gDT@ z`NCh_M&w8fCF;UxE60w@{<1KC^=_CEE5Hq!u44j7fMQn@#A2R*-%*9nQF{`)wEPNA zw_;qoUVh7><1MhcLxvbwr*%~@u=M7B(fF@vPQxPo_Bz_3bgie+W9C2qq2yNLCsL^g z0(v;mKh#R!f0U&y5*)ob#2sZ&eEa!#ybKOn)@q>}498R+l3M(hMAVLmu z6`x4}keV%OUJ5p>G1}kAh~;n$E?+4^JZvykdUi{RyN=B`*(DX{~ej9U}WDfCp7tb=Zrem{^! zDx~52d(VRL0kE&R5@T z>t_X`I@YSIjNk=CrS~t!*6cStsX^6m22sJC%(0vRNRpq^q1`hog zNRLSn6>c(6bL9!;OxD|w&a@ZHNoZ75T$$}pa0_kj&wfdqcm^uwGel?wSfS%x&PQc> z=B)Jo;8>Ql#)z>0=1-8-lue3m0+(qBrr>cLqB*omun$o* zWZ`&pGB3FJC@{!D@?FM&+gb03#wOIkLxhwX3S4}UUiD8lEE&kYap*$D|KVTP*RkVK zAFfSzUN(-yWb!1`g=<*h)4wzOdN#@nBKTt=w8}~>Ht9S|NtjG>U?HDqw};}a#n+fW z5@bm7XUfh5rW3A@aI7XQjxn)2*hc zRrHd`dno)2m_KDP_JrJx2c%65VzZcfV_eiC9encH9@-mi()AMS0nJS_aC)O%iiKa!OI7=+S)|FC>!Y%0Y8=)o^7}k;>xAFNok5pYsz8GSRacKl3l$ zMk`IDkn;tNrul2dUQja%x4R8T48>$VCI!b+D}IjFdmfyO43VDn@NxVzcHHR_8f1H? z5v^ZFzI<$Ne}ZKwa)9_z7fFpo=|`&5|MUkG zq{yAUSV*j91t%1a$-GFCp-3D#h)6LQjXdh!0xxo!IJ1VY;R@=$wH)LcsX-~y@ek?A zUuDwsm&0nnnIlh?&D{zMIf6m%qm>IQ5Bo!zuh8=NOJPRr{pTiYXZ6t?nQnq>Ck51J z6-fTokTRbFR8unXXPbQp^GGwg^pRhSY+$hu6WpW)l3vm=VugOtB$hwCC;~E%0+j+s z;pv0D2oyiYWS&IT<}upEh*pC4v6KLlf}iKL9@qe(W1v9G$Rt&1hH3;gYH;x)5Nly+ zJP9!upu5jR*W`;R%A}b4Bo0a*pcR0_R_o#l6qAS5(!~^oNxecS3%P##7uZv0oj)tT zzdo|DY2dX>=`jRbgl1WyrL%Yw0+r1VM(krWCXEXS7-oIL`w}54lep-#z~)g&TKDLR z6LU`MW6S#gYC6`~|K3Cc!IQz`D~!;=9d(JhtHnfJx2NTTl@M-3$8%o4&Y%|4AW$EVAAK@F{Lals2)g@8ofk2Q6p<;tVHXS8 zfm1Dd`0=XKb4TES%6>P95a$JCI=@W+2sVKJwD{4j7vgj9AJ!C+2W)M4%RdvM)BXfFaEOooMn%RxVlQ5#~ zcSHFJT}{h_&c8XpsQ&DQpHJ`iXD8e{l`fXWO4;$812UwdmlR#X=1!vQ-Dd!(?xc_u z;0@^AbaX^sD~nzz#^zh=j=)&hJr_Sab0J+n|-T6%WStuSO960^DQ?EHk7DM3)) zGk2e$rZIcy4VO-(%00Sj@s0u^K;Vy5;vLox37&h)gluID9Cn zff*uvC$%>RvfOoWLf5){DSM(t{!?frc34`hI)~S$st_cuvaF$n7t(q%nZfwFp3|_LIo*{??E2QDKDBK*NLca~J6JlxwE` zt$h&ONYzLC4eFwYiP2i5F=o3*vz}*#pDJLxNQSHKsT-2+;iffGf@~&p)0QWZoU-Gi zqzercikGI(!7haFD0%4hAX(N!UCIu2K0*v}M*u6w@?m)OJd&03@`n=6MD&V9qaViR zK*B(OS}O~F-R8+>8$esVX1KrO6-|soMqW8E3>d-OS19%iD%Px7NJ7fH4>_vc1u$K=Kw-@Z~*N|Gz~Bqh3-v68y)nnozg> zoe_J`YWL`p5`+7u47Wqmf8GK>u|xxW(wR}XU$%f-3|ibd%Y>%l)07>UPG3s7=OWT5 zAS6MW9qxGe%xy9z>%8Jzt|H98{gEP2?Y?if4{>TZUUh*FH?W7T^{|@-?4}JRHt}~o zMidCg2S9JOX|k9TV!TkBjmOx$oT_-(i{^k-s)vzOa#GrV%Rz>~sL5BK3+i!v#Z)QW zGH(&}nzc|-ng(|$BbJ!BFNRyJ#-`m*!ST#x7^Qu|ozlC5#<=Pba{m)N4!Av{HO{VB z;dQvS_@M@{wyu--LvgGiWc=TN4=-V}@U!X^ZhT+Oeql{mApWkO%#zVzntVJFjdp390!}c^6LS)VsI7&rFBjN)K`P(E78^Q!;M5&(c4e~DMX1( z{v1(TP(7{4Px3(mAI>QG6(B37WWx2QTtNvXz9UzELy8-WR*3NBGB4>2}mQxzDK z2oY&;tf!&CR7C?K8zcdPQv}9_9_@{744XGY_^jY{!_$1veRuqqtbUy2BaAdqUGKl2 zaLZ%jAVP`lrpmSb6y(H*XdQ%9-Y2q2`Z+`8LhAd=Hhln=NVw887&wF+{D_8b zX{VFO`$M~fJZ`}VYgRSH&k;>esBAA_@RTeTx`uF;_=_{g(ufJX`nNF0AZ{Lbz4Dh5 z8EF8?929&|!3^Y~R||2uRA;^`yCQKiz%{KptN_PL4Iph{`rKkB@ubBSuD3tr_@3kSp?uq33brBG~Px7VW1`h53xIs?KHEwZtK`n00c zuyW4&@vx*yXBI#8jF+XDoSYA^^qEFj zIuZq}mZNY`Nwzyz{G{rb75 zflZoz=eSJliQS11GTlyxZY3!%7%|MU^2o}jHsMEhC~ zJt97|$a9o@w|$lz{|gi>i!r#n`J$gQCF;79H;`a)2ofleJ8bBh<`J7vl*sA-W20qC zb}&Z7(<`$V4Y<212VHPS4^<7stzN?!SI3+C5C_ji6bd;};jIL1sr0TzhF+YReMu~S zc;#TX-$|4hi1+Z-)5HmNDvRC=e$MAiaKs02n}}wh;JnjONmhS7LKBVr(No?Zk09Ak@|%TjC}v_d=hk` zN~J@g%L2WQz)2+%J&sX!oLuYQAJswQSm?A5!RE8M-vixaLj%N@P^O5rKW|@l@+!9G zH>j;%=YQY;i9rj5fc1K?I`iw#*Hb0oKv+xg0^Wa5RTk>vjFry=y+Y4OkW8coNsVQP zaDi^YjDylpRyZ3=oqrKZW&z835E`5nhN;`PBR2o=5zfFVVD9vD%?`L6dT5B~Jp`3) z<|p(j`#E2;GP$ByZxK?#@f9t#+1~(X{SLZQENkv$OJ5zV@WV_#6m`sY+K2x&eB91( zj8^g2Id^L~lPA~L5B_3ysl;MQ;eS%2QD)SihdZw;lhVk(f#yny&wA2|v0yOsPu;yz zvy+9Lc9VR!zFDQGDH?YBxQIGzJuzjyNYlH1^>kjm?B-@n=G}!w*If=PZSKKuY(4{% z3Ofst0gKuc!G#ckB*^CEIUU9`U6P?!MX8(Iz z?TNdkI>!&)7T)!^y|{thl@zUA)VMm5v9qb2TDpyFC%tg>ofkge=>My{s_M9A$a{UJsVJ6f<9`xLKj5F{mOl@s<0P$|MljTL&liwm2Kr!ne;T`tljjE-Mqx^sIPQwzF_xi zMp<&=PL1&Hy27sZ?si}x6+Qj0oa)FD3E$Pr@woiXnx-8;IvXTc`hWKZ`A-?J$ISg? zS`IWHE8c}zpm?_W-8;APE8=3OB1FEQs-YK=myrwm5?p&rQ+{`rrPFBJ)7NuxmXA<8 zlHO*by_;?7JKt5rLGR$gI2R6%|J&;T3PWz`!DxY5xFMyPcN1Ih^QC zbCf<}Cmtp-TRJ7gOK2Jg*wfA#z6QnI(RP(Z-Ge>uDSf+x_6geBYV)sBS-%>5T}|^k zIc%yBYMQ%K+bUA@+IOC+ZOvuF^~`efd3rjYp~-s*0altjmLvVQ+7i9DO}BdbywCPU zMWGp74m`$+cPT?kbEJY5dMipCGMvKBJ76Xg1?{PdYm{A0*8CMVtyj!ue;yyA(yUo4 z`BC21rq5;7IPmvpsrawl>bAa(=%N+ht>D&cMUNu6wl~suJ452+J%vW5I{9<*>b#~Y z^chSgG`*ylzeeWexeYGqtr~?7aSR_N8iIPH^W=wOCQJ8rTQzxCzGl6(bT@>@Y{iVK zJ##Z7`6xm!5<6dR>AoRTkwctF&FfnmzLO(7b$?{6#B!I#@P`VG=-||n;_kj_vf=nG(}HJ&`}Cc~Vk)KyX?Z}Mh3?fHOf~k;!Jd-wc7_}C z{-?|m=-VXaLIc-k#M|G?Y-d*(OJic~H|!V%2)(CM%3@#KuF?B?lO{zt+PCaCD{V7p zv5>1T{Q5XxpI)f1M&Dg#>l zVtvcSQWZaEc{q!}7v4mp-aeH+v zuq;f)rs~Vp`a^knab=Rm&MqFZ+qPedlWq{DEEt;YdS!x-r3KK>9~YJ9q8a@1zRydt z;jM-hyqA+9Hyu7P?Q-J@&bA!GuJWuY$7Mrzh-o ztrWsdJ(ij^YWp!eoxaPFt@OoXlcxriZZEEn_jmcKsi30CFxv9Kr#pBo5G5I+9JN2E2Xuf>7g1he^LmWPo ztVu4*$DRgN-q{Gv5bsxHde>5zihV1pPIqvdxwx>JKR((bV#l99Xm!8mWdS58s>$db zV9VXkE$i|9_g@k{Qk=+75MJqdz1-y5+4`YZGv1Y#J_%1+^qLlx1wJ)t4Xx{}jpUtr zl2SMvQ*}z)hK?G^Ib9a+t>w2&3$?n2VIAV>`cso>m$z|8nTjhu)mjS-3MPKUcv!GU z$go(+SY_1C2kfq8Qn55PtB11L!ke-P5yO>LO03dQD_NJa-}0FY+EacYhcsI-k%4(|Q@GGc9X{GGG;j^W9%=&iXn?HfCfP#?SxAGuG3(NoG_X+;-C{ z<66bq)}$pYyWp)`QcJB0?fTfzx-)Hm8={R_T0q+O6W} z^H!s7E{l?5medUF7^$-grP;nVOdB7Hopko)8vonz{JZ#m$3)pd)HFNwqsuQMk#~ zyRNOeJ2Iuf$3ca&L@ST2Eb5M!$@}7oQ2%jx=}E$Xwl^CyD~gC-Z{Jq5>C?V#PlZs@ zzjjx5Hx!0aWY@R`{UiGXIS%65LwE)+571nM1Hj#&KrY^=gs8lV1~;9Z5`Q!!xl)p9 zeop%#+slQ!?R_EReY;fi+Pj;(GUe;OVH&k$Se6T(`$7+wUv_LfNZ!A$yjmExwLQ?x zbszp!QS9pCv32Z+Mbg0E({L}WoJM?rnG9_*d*4OwftJ_mq`7@&t4%%bs@VS#b%6)= zVGV0a<230&%-2JY5PJIgimmqD@@+PSjh>WkwcTZ3G3$i4A^R~1aY4#2o#>Hv&un6m zMe%FymQ4kVjqk2P`LWP0co<5}8cTaM0W+!DdXW71V5cbXVQw}CG8UvP#)JArvI+VI z8mgi2#|;hqAtCsOvcsk+=W+U1XjA+XqCv$6R!}VViwKWskZIAtH@~QC8L_#JF zi*)BCxdb>`i?&%FcXY-EdQJ2&W<5axEnPJS1e0YFf0p^c-4;AwfI#^qi|ui= z%i!Iw09Z>{itTF_Bqs1k@|WexW(x!*Ct240Tj603R9P%YZyc@$VJ0od_bEe5YC%mp zc@#kYjoi`8a1x~JlHYPSSjNR>(r^3V0SR9!AO9#asQDw>Ewcjc6%&1^F0LKBGh+`Vr-10VLBY?S06^; zC~2N?OW)q$*vRCJw^THk9&NU*|>>2RJH#E+Niel zktl5wau^kW(?wy@UPy6TETx|6PAW-@k){mzWf7u5l5@WoOh(CXVeu9s2s%)~U&jJ{ zn6NBudkm6HfgjL_I6c`TNpI5Fk5mLBvDeWYAi7ClFZ)x+@Uoh z>Ek1$YjUwf!DWvVF4hS^^o6|-P4Kqxcg27It~EA#=n*}MGQ91b1z`;}zKbOKTF9*E zfvNxfRmHrru&)w6r~)b#d8c}|pK|P(lWyD6>b}ZAc_ysp(n=Bfy->?dZFMTXcfOQ* zDt6(2P@Ujt|2hih{j+wDcHP#0Nxc7i@+rI|N0+Q$UjOg%nddZR`I27d_a4P+7C$}= z-D6?pvlT&OxBQM;HO8j%Kns$n-!>+?v8N?)Ra-!nE*7;XqB|eTh3&(yk_4L{LpjsD zluKk)nKeWKC{=(}PIZYuWR-P3i0XL@y{4Cmv@+XL&K@U&D#A>Cu1a4(8>}lyWTuiQ zxUE4hG%4~bfU+aJeCz8Jd}M&McxZ|PgYE@e?Q34ovI71& zeEeqmM9#;liRyc$`|r5vP_lBqjk?Hso_nHq9(YgZf#j=lni+*F>AVQAVIG8$OhhGAd24ZyAzJZtRywD78qR% zZe^Qzokk|G_XXEay`XV{bcvsrdCB#f(oCa!(Id?rm#VeTTYXq1u{v%+Oi{v$|M@>hf#W07?zs+psBZF=0p5ghG z?QtjK_lVt>OQ>^6Ezt?9PnQr^${_FfS$9+!Z3;;=cjM8L@-CoDqQ#c0px%QqGHun` z?wi`k%F8w~8{4agcmgV}K|B5_a7JS2r^h&l=8tjw@_`Ig82E1wHYOCMxd;!Ma$`tr zcM53Jr~0*yKdP%m(qV?bOYM+W;^aOFkbXxFEVU0f$>SOiy-%w9pzDD`ZHo`T+VE2Q z7Z`R?F2D(6l%=gIZYNfC_>5p$z3!lbnuQ)-B5TS*@V&>qShp!?^!RCZk6wc zcTP!6tVG3MbG)`jZ?-$SRjf;ySgifM_Y2w@#;3NcDt{w7`Nt_thqsmo6{3{o5Es460j;@=&5OZ10$LHmNX{9Dxoen?3u~+>vdk$Cwtqcrl}0aXTd>aXvZGF~mhi>(QmZ=Z$28yrCj>bq z5I*=(z<;@)qJu~Fd{F4#ng_oB2>-E^H+aK)KQ{cV#9J3-_#gnmYpwki@NX^_#R_9O zOgQ6fo{IR8z`w3DqmQCENYAKY{m7&3>{r@iHC1l4@)7&QzhN1IHig=V9YtNh)+ zdZ)CSlqYJxu5LxYk;JFfOSyo#kXUT!CQfFP(nRxqS|Y`;FN`rby%41`Aky)kT2one z?`MJZLV_=*gG}-<%BjXkM;hI)(RFQQLg9H5&+*QP7QA0X6#f5>sfG16N;(g>_qGz2 z*lD$i(#J_glv*zTnS1S6+9iG2@4cXIWKyJs&OJ{{;jvQ-)3>W(_@iY|5Q%qY_WT^g zFuvT11|6vyU?73NpR(tw{w>F~b6`47G|;`@dC|Pw!83f2M5E#hFQ#|gt2`N|7ys_? zwa!`FxtC0dsvjZHj{of)Tj&{Idhj}qzYL|?z{1ML+x^|r{t3(XOZYblY}cy-jiP&j zaOD1T9l`RV;sUG()iO7ZlFcQj{erX7t4)ER-O-y-P%M}f3aWho%IjE(m1cg%0VAYM_gie{ircKdqME?4%ETg z2e9U%5^tYK4M&rtktzhkbTJ*wa*GDeC&NnvP=bdB8JXxY9lzxkJ)HT~jQGn?nC>F- z3vyFrna}^WHF?Uuy*K+%Vx=-sdLNK7b`3Q%X1WZ*VM5rq?$oZQWu^a^0U^X6Qjgp3 zV>(0rzQCNh#CpsWV?tWF3$ed;3Xl3Y`})%BUv+qgFbrX29H04N_##%)kni`F%S=ppJtr zB3HRPT*ifX-_t+#T5kt~z2Zj*T< z%&WHq^(X{i{^~4UY|jZ?J5en6hQ8L!u#`T04~XD)6DucZ$udvLm+8bk$Vse0%|^|U zI#Y%sD?!RJ+d$!S?C689(XEC^D(wOTFY2$X8~C$q4->5Kz}6}5)0OM_FJigXDwa4A zzPqy(Zc6=_O$6Ed{{nnmqM*esHKNl}&2@r0hugD(fA*ymS*$W}d?4KI`~#4NO!_LK zcz}nOz-l>bh+#q~Ut_&}mZRfa#U$l1dgKkJnde7xjpG(3c_Pyrqnd_`G0Vp>5E^_{N#Wh_jQdVfZC(=eTvKnX)A2SNeJZ^`x)^|%qbg0`Q z_#yjA?FwBFjOmFK`GNPmNP$T7M+LUR5PUngolut0o4{E0Sr|pwT#9tq)b=S^qT#Ic zl|X)8Rv%A4reDaUF^lt}$YT1|_D#+dF_<1%EoVrxlfUM%&lEVv;IQbaRY!JJShu&* z`Y2iE$zB7j;nK=c{Sw#41Lm>2Ns{w5 zn+}5+Tq?z%4Lx+yrscOSrsTFQy4_a_2b((kPRj*6S*xwsaqr%!o(8Oy2Sm3U(RIvS ziFuM9pktz1Yw}EK^Scy3}>WqBF#`i1ZEK}k5_QS4k29;mW(V@Xah?2U9qqHq3 z_hB$(bdIJjNDp9DGW}iA+TcXTy>SlN1bjQJi<9@Q`{y;KNL*xy zHe0T4&+cp$TN5SAd@_?bXOG4MR}9oe#K1Nqe?7zB5c{8P!bWG*`OB8zh-Tv)Udhnu z-ZhT0i|?-VV}%#LLhv_u?Bokq9=w(WAc1x#gP^=oy+V^Sa{i_a1nWUi*DH@m^{T5> zQq^6HnYp01U*s@)n%zms#mxL${=i4%+%uhqM6JRzF{G|TD2qd*fPS=Z%Rqg+GC0#P zFWvPxuDueR`u1MHB>X~spn2-taoo|B|Em&6xnMfh$fU>X-BMT%1A)4@oNzw!V*sSO zcVff)P&gvGrTdVd@E_FqZ)?}yx6?oN5ANs#66;Qy ziXqn1-%NW?%KXz}DB!PITpF?n}P$0N5Qjyvyb?WSXrAyo6)N`@N+3AYySkKo0NfI~yD z@4IA=DmE-Kl>&XSSJKyZKw3q2&yis|D7xc=4uaw(Ow1d)0+yyK*=`S_c^N~bPD66o zpJVE?V;Hi@IAfA+jDxNq0n0*mI5L8EiG-01RWYw-^+md3E(I9V!WCzX+vp)fq9({=R^MWw~#RrhNz5v5O| zT+ngZpuR)(Yd_g-}Qq?qSaJ>d|KU769+HV$Fjsi8FZ0vX`S1tO+cFg;Ex$=02G zGj2b&w!iUlL0-hi+`~xre1U0iQ114E-Z%^LGtQ0jaD+~=z3p-?*xnCSOoszlMvF3p zwsSXZD|m2ZDk>^nZ4_aC_;a`IGy-%*R|3pv)iYK3tDBmREVsR55TI_z}DJvSKl?1^FLbx6xLCN?YhigmS0-@ zjv?eJ{@gwibF{vnZt>`wsbC22>lTtD$Fn+kAMO`;oxid*Az*7A3TN2onvrovm4u3? zzVHhoGZI@rs35Wasi!XDDc!T6x5B(1tG3ip*=6>6Y7(PpCAbyfi$)lvr83i_&XkfO zX0^5hShc7OV-AYqVVjE5VG&n^d(fnmwTC4-ne3`(8-Kn(&k;gcf2h^3GZ%xvgpn&< zHz6qq3|!qAA^`QbFFCllJ5TD2vuK{eakMT!F6b1G?lz~C9)Bm%7o5@Sl?(2edSi~4 zt9s@T*9!8xkTLUL=3R%3peISIPq>UM^|kN%r~;TLURl*u6|kB8Dhg=I8j}BzO&;#` zu$@*W#Ve_=?Y5ULnEpdC_SUp)9^Pjo0nc;<&*a)}9PU1`A4`Qo<*9&7f4J@NT^dyg zsir!$5H8OrN1pmwr+5vxD3)#|9*TEXbk%x2t48gcMyB!=#5bhvGv}Ia zg`8EI-I_Bt<)n~&h`Pw);nM?T2e4FgC`?6ho188qPt_{#@#TeoGT?Zp`t=nyj*~2k z1qqGS@wn^mtZOQXKvtF`oYnYxYQP0gwI0c}m6Z7i5n7$!bR8_KShSZR{(imWt$$!u zo7k06qIpwP70CURUveTm*k=V=~rPcxR_X8&rvS;;B9oSs)RV zo>>N!Dwzp&qDLU=4qY?aCQ*6!_W8`Z4%+RsyTY>l_^$%^Z;;~Jj_5X*cNs2x`$c8{ zcjAp>n^-mlpx|KmtI`6x++FV1` z=k;od5#byhTAlr>u-wfccy$dDhB^- zyQ*uG^^^H5r_l{^?QVe`txNpf4BVG&au{yVR?f4VWGdOnoC{zz~ zj`%b^Z6&w1l$Lr!b(RdEB2-~xk*m7WcP(J;^9_uMuSh#lnrn${3(3%4^~oifm#K$TXX)&6{8C+a4{)?mxS)M8d^2w-b|OG)(R|yB`2lVDg&Ruv z^Y+na;qrHOvD-r-i{n&Kns^I%0GIHl27t~YsCbzBN5aGX3=I8@VYTQhCi&6JH8 z@P!X9=-I6U%ARzV#(~weT(N8R<>~bqVS`)N^~m{|Hf`ybluqAkXZxP^u$4HV^P9jJ zJA`dxlPQS*IBlK2RhWCY7-nA5E?YN|T^{jF*=$Dl^YZGuFsJZh*F#0cYwPPbx7Bf8 z-tzxf*_Q`G*+maOCQ`gFDQgK)vXzkRt(GE0mJuWZ#o5`ObZ&e(&%5{`=;?``qo^v)_Bp+{@KV-Rr;7aBjl1%YVQ+p?Eg5L#|lC zrI;LGp6=|AA^`>Q*#)%U=} zxK2r~k8L67lZ{Vm&DW|4px)%5rQQdI6(AgHfM&mpAKby50nQ*79{$Ar|WfupfPyUr(B zZT^)9*i9aP^?PQM^J1V{Hn(v_hxtl*(en5^&>#DkpUj^tp9xw~U7o-EyUTq@GP3#E z1|rfu-g9i&&k1D7a0@EnTDKIS^n<8^`QF&g!`GPgy9NAp@n;H5BglVrcUy;XjB>6l z-_|osJ_P(Lhl~}PAhm2_AH!#l{1``e^Y9)%{RDS{+hKM}i!U!XKhVT5wI!E6-%{q^y3YkuFv_12HkUv4|CXfx)+K#@nt44OUl0tc-ewYFwmY(lm7;ds`86yA z+<8XH}9H9%<{nuh@HF?gT4EeQa0+YH7|7bd5$SxQEOekBpbi8 zPk)5TW}KuIEAa4%YK{Fqh$xhQ65qjo9_Kd8A|P_aMSZ-0pH*Xt(WeU>)2J7CsNi=( zQ;Ez7C~f#tO1~AK_$EW2=CX(`)Jzr{c4y1n!z7*hqlXcMqHQ;Be%jJ3N-F#Bm;@S* zACa_c%yKNV^48JRCzxF?%z=*>9F^{f*PnvrziIz+*clzE!0(kvJMJrCy>{kb`QuWHpeyzyDWjRcqIfr=&6WGCLZC_BNGUp`5EQ zRA|4{MyiYMivIf^#6i7HE;U-4406eC$g{gKf@BGEi#3+=4yO`n#cDgO(ZIX4-aA~c zB*ZYP>y4&2p2{WD7e%0If8>)&<8rI5B(#qw_IaS@$_e1rq21j2@{?Oh;ZINJR!kt& zIe8v8dOF0tmMEDzp!aJhe8F_?JU;wMa%Q!e3nRFCwIOD{=@u(RiLW)}moUO9{Kbx2 zVZdzVLf@rxeN56x!C#K7h@-CkcWph~KbEU3NMBEp*QrOJ_=B2%Zy-v3yll9rgaF~c z9d#PIO>d{(lSTm{Oh4Lo`chhj`I>X=zZiqasSOFcGUCjBdMxb*kj#u4QZK^^CHxBZ zG~wi^*q4W77Tg{<5>$KN^T3{_%cT(cO9M5Es2trIP=`md53exKD-;8tgHR$S2Y2V0H=H918iGRqXM)~2HA9oeL^#z1v+pfZ!0tx?x2heW?;lyH%J7IE-RM4DBCu_-YOlDNkyyt58=390+p^1 zYGd&nkN7ki-x@JC7RocDi?Q=3(WD%gxzENM+$GbuAgw_DE;&W^(R?O-or~+wO2Un( z^eA@X-50gXdr$|~yJDAP7spOBNvAbsruuI}y;jv2QRv+4#KuyylajL?sF`4$*@RVY z%<)OKQ<`UN#2`X|rI%P0edYd_C^>Bt^~(=6`ne_ck}@#-tuiM(IF|ff`)u z$1_uWtQcV5_O^oNMl{uzO2dDYgGNfig-;hinS5W}V(=}!GIuwc%%HZZ97T9F`i~c^ zCC+_ok3w8VZm2QJ)IOd`c5{)vaHSB>LCSQjcy>ZD{sar<hpFZ&LaQw!Wa)HK+i2yd@e+!TGopbYXo8y<(OGrf zu~o2?Fb4MdOVqo9zkduSEAC5QylY#6t5))hYLyrGK4qfqwl*^*I5@A@cLSt{?v;YwE7Is&A zd}=qPdI)N!Ae=TVu%;?O4Yu1XqN*UeiiPq{J6A~M<{zW0-yl~ikk+ag$cycQ(M|9&x#5%jQbB!4OfbF+7`@W&f;G3&q zF_9^q>5Upl8%5>ErsVEO&BXm3%&5A+t!Da-c8w5iy|Fj;AMQ#x%WX7Fuw8S-- z&F%~H9p*_Fv}h<62In`>c)lRPb_vBIe?&OjYtcfS*pQ9t^}nRz$J6wfOlL5M#wAs} z$nzC1@7F9bu+hqwAtef!bg1;{GUiSFmXMP_1jw%i99P(uyp$?KESMZ+WRT?`mc>p) z0m#4Tp;ge^ig3xY?L5H;xf2EvrFf*(wb8n^`_-a}^r}_}3ceRbs{g|lFYee5&qb-n zsgP38mup1P`4hgz-t8FR?+!aY0W7t(3b$e-+r4wNwn1$S|6H+<>nI4X1 zKf;a-n*bji7IH;?!^VrUIs@(60|b;JGj;&!g50b_sGix}D(S-lrO*7Xulz8@uX{0W> zJt9HXQWhvmUaVEgK@9d|$8!T##N0k9wTu~tB?j7F#w88@QtM9SMD)IYeEf%;I)dn_ zOLp<1)6z2Jr-+I^^vWu}Czj37k(197W}>sYRmvb*+^GKIfixbECaXfiNJ@gQ@Aw9k z^Z`maq;o+n6~X=QH{S(hJbr`~ucMA%`F^56=x;tjvGhP&_i&=6Y*~r{GeuVUTcC+kg4JeU zIM?H{LJ@T=A~Z8_NsKfW2!~_9X>Bi6i!Kvd{m1Ch)pBqo1>fvnCD;xQ_x@f>T-ps2 zNizCXiJUWM<=jtGB}2S^wi@!B5aB;qLGA`*x}Y>5NCxGxTX7n=%-I5{KUA9ek$=r~EjQGqce!Op-coc>GYuaxL+l{qGY6Tq$i5 zIJC;zDtmAgpUa2+f1N?Z^Es5Zm7L}B;jhPhI`B~vilL0jQVbN$CLVGvf>uTH{Pl6DwX*qqjun4eukWbwpH8>>sqE7uTj{3%tGm}{;5TZ(^O zVoqO6WMT9hZp2GB>LFV|G!32R0bH`68+_(6)R{6@f6vMC#)ljh*9mY~PIzz};$JNl z@5_9^q=Qkq#~679?Lq{(K&=3!!ASwhAL32#>LaCjgziqQD(M+;uWW z#~Fz~_znL0w2ZiO);T-r!O}R3@8_c@j4NS{(#(*sdNO`QDVgJ`d<~gLjt~W zWYa@HF@7Jf$`qsrcR>o&uIV2&nPuAocyqQeWj;mhC%R;^9rfE^V|3}KwbQ1Ir;tSP z0A)@YfU$v^{SSc4m2kIW(g}j6^){ASf6c`QZIH~?MHQvw3kI|cxEZxpvr9|#XF2j5>#GrV z7nztcSwOE&K4DC)fCw9;(_wj#b^+0KgAZggallyVfl+C(xT`ZkQis9fkXQN&ZsmlO z$?!LPtd`oe3vrOmqx~)48dq^qcdl6X;F)W$J>m6%-2s;hrq3RPk&49!e9r?dqAIj0t9X3-Vi_-N~<^fn$&}a$j}>h|LFi|9Os5Vgd72yCMd(i>erubod_BI7s`~AlggFD&e$ZjnX%(3qT<|qg zcEe7_aQe|#Mmww1Vtk#cmduohIM8kDa$yYn|6vW!v;;#5=`WoV9rIp1S(Snai zU^9*xf?oL?+a)rr%oNHXk4G?&Cp}hhdDDW4srPD-*^18OjSoxb&b~>6)FMz3qN2ct zcMW$e^oej0c#|NH5cKeXSWti*)E+ZwkUQ$NSn64s#w@c}0hCT|EJ}X?6n7Xuv~C|Q z>wUIquNY}cWhO8~Sj9(>6BZ+{ohxcRrA6Si!LzSae72&mw`x+XF8z#A(w#{5XO(u1tzI-*RvXMid)_2$-!i7ggy%g*`Ef8n7jE@TTdzeDS5L-q1 zcpX8>ZM}Nqm6@qvgx`KVj#rk*o*si-8;~ar*hu#A^ox?@cyT0v2AY(Ga~5($t;$VF z!z8{OemW(u{HgWV&}^QvdKr5Q=F_S@mR0(`Gd@qLMFfe3RUx^8Ko z@>-%`Ceq%O5_@pw>b?K1tqnPE8iDQ`sLJj$IW|NtBoikj-c@~Hd_G{S>`vg_umxoa z=7)J!GOr~bt$S~jEgEF_43@n6WW;aqs--jnL0a$M|6iOzUR}bM6NB%=4Iim7%ZTeD za_}Vc-Z?Nb7P@CG23Q)!%(YW`zI> zC;b^N*dOgCSPWku3nOb8q3z0kzgy;ChIpxwytJ0s9Dx!Yj|F>b=|kZj zD(pJd$D=4tGO|Q07P07C*Z*DdqifS~?hWWR&9S~neo zPI%U);2r3+mbg0xK}0o#PTNUM_Gp^-T;}-f={u%Ec-K+wOW(QA=zfFUDNJ=tN#)%O zPpwTbTQ^crowa)SJbp-#A0NzBnAqbQHQ~;Fy98M{WiS74K+~MfftykLO5VtMO3g?oC=A6f(BmL1~pvNL1w%F zG9LkjfA9he)U2lta^nSlgQVvOz1@nqrJLOP&{FuVWXTjrAjOzeAcPA}ME z{d!;x(McFhCSg!|O_qz=%Z?AkKgA|=n0Ad7NgVmshMe9<%rc&9P`mq4>LIm#Jn9K# z7MoMQXW6Ci=B;o6SP_j9W(;FaR^34D<@%mux(Q+2Nk%*O`4`J>NE;Y7pk4FBN6g)j zL+W9cY1@uQip%76I4=d0VEpJ)rD{j;w0@H!C@LfG^xHE~0>BY6)k8pHN&{XOq|GI0l=ht9%x zl>rbms~B@x?@MXgy&)3RUN%Ws52;=yyjEh{0Amy;D5*gy@B7fFGAVR- z8(ciOIuDD<%+wH3Fqkyz$p1_q(G#UQio1i z&dt<3TCox708_n@MyW(Dy!Qd(E-Yf3UV05Ka6fkViV0`o(=Q?a2$NyBYWbTz123l8 z*o;XB4ul(Nd{IrRm_7h5UFhKBQtu`QH6{X!BsG~TtVglAu^vZ+IN;4mtLa zz|OlLkQAS0I2Q$+PZepX&4lL($XD28h$8i$(tK2E1JPZ(q(r)m1D!{PmxWj6zFOL> z|CvQ9Ge%x-m+R5#^I^y4Rr8Will=Wi*X_EpYN`Xc9#`%NL?+NvQo0?>U3q(RB&nnW ziiX4f3FXJq(P|x{@YTL6V-14kO{CGT!Oc)DZ$sC^pC5q_DNn*qML!rz={A4+(THsG z6skW%b=LV8qHkHHfbOYbU*}$Cm0sJHOuM%21Aj|o*31#gfgzA@Dx3Vw0;tr^|4n>qW_D zqw--`K;O=IJ2826 z6q%Z+;eSYX?@ynL?ukD29`MBiK%W`$UGH!VVMOLy9lvi<#~5GPi%Tp-CM8`~EL$6A z@a6x-;KzBD1t1!lw<}4Kdi<`m(Eme z{X@h=mLhKe%BViFSom@t{l-Dy>@K=qpiWtr|BwuA_893kn?uC#sRUtYdgS7ro%A7jpF1)B{9mz;?JN zDw_5}aUV>nuL%M1-7*nq7uw$NAoMSw@ts!l;w- zH_yH7n*1n2f!9hXxmD>xm-X`!xezD8_1b5DlsAt347Kj~iBaTo*1d@@@q9GdG~!cc zV6u?!Dg0czkN4dkZC~Q#Q|&97#;VqkTKgM%*%&+%8u1fAoUC z;U5%OP8lDE8{ug#a?mgTKh;IvrVy$@=b4n`CepUQ^fUIzEF1@CW3ofuRzC5Dk2!5S z{AD(2^k=%zMg2VbPEdg55{SGS6Js3kPC`s9fqh;Ev`crqothX2QX{0-XK*~vbdMLg za+6-F^l|vU06=eB7pN|^XwOm*rfX^~T0z9&{Uve>iNIbY?_n^q9OnBCCZH`AmwKea zMQ``uyRnCLYY;5H1Q^Jnx=gw^9xx&e5`V}8RC+5MAJPPOjn-J z2;U#eWxTWebn%_cBI1|HIQd1LuC5rEq7){5c|L6T$jpx+>oeog4RBw<_V~(fBahD$ zS7=s}Q0oAy-1ET>1XYZVU6}2QFRH_1KLH=Dw+ZYLk5w{)U}VjzWLLnT|4F-l8eB@; znwM(yk0%Fjf(IB!GUYP1b2a(543C;`YRN-Hn|Jt+J-ijJvT%D0zKj+Rd{vm zj=IF$28I-cf5EbUZKz#za){5W-W3D)uAiuKifK|E*HDIsIYfX>WbQEJU~}GJEI>|u zfv>BTK_9Xnn+)j@C=}e{$-O43sIt-EjWP0#7KR2^cr(TVsK3{=vbPYKD_`d|G8DABU-4Dx4>c=NCdStRqSxMC?7;@O_h=R z=^JDBwZKkcNGK1)({$;vB9)cCUGsiF$4BH&Ih=9Jdhy$ zj+vKw50q7a!-dp!7;%HZTMKPHFBXavOjdItY}i>d-@0eS?Qu<7>I_(|pt?~Z58-CG zF4Af{YT@uu{aI$=mx!<<$a0x)!!1a(IZYMF?eLW$ja&kOKpt$bxt$QQ4_=o&z#h=l ziCdUkt17R~{q&eqHO$LUMdSO1B%Jj_203vR=^>!WVF08eypW@G6{aU{%a3~=IS z9f~@$z)54(HL_%k_NKOOeC}n}-eEsFyE18q1&rKUse5X9IJ6;DDl;b~ zmzcc-d+$V4W#4~9oJub60Q)vbQ^TnCJ2?xab1;}v^ZKd@jMi6lzgX32gsoQ=K9#<` z>VYMvBZGbkuJSUBqY>ugzNZUmYmUs8S#QtqJ)z2pQH5N1S>Kg)ErYwkdv~o2+2(_~ zm$CWfyv=Yig9XTRv_SumOnZ$qas~+VJcT;5BoGA#)kw2v?B;-HK=&eC@y78SB=;!he%F;mTPTty>;w{K^=@Sv7$-V?EDC2BPpwRHRt1eTJUB8si4boY(0nnS=2Lp-LCIaMOUoPYZjL5F1(o8`9dV z`3)3?2g+Cj;h8$*c0%61Mg}Waljna*mDEC);fU}lSpq?u^fz0>#M_qm$$MY7owWRF zfSV>&6ZYDb_g^5{Y0$XT-uM)6ey%ZGZJ9I*da;rlW5GL3+559tgl4=8T5M$?WRLut z0~Xl4pujQ!DF{%;+yp4Mxj27YZt_q|T#6`NMSJ%?Y)Zy|3z zVQU$T)DNa1sqs#%6_+YTvVRsz$Rh^0xh&_@4A!eb~o0M-YaU) zDueg>YEYf>e6jtm2c~Sp7go1eG)EgdOy&W@O491|vJiIE&*QRi17k$K2f_p%lCd=t zg#&0L{jIOsXW2V#M*pH&VtSwd&{6P8_(rbz;LeH#R&)Y@;AsZ+9&BI!>a&-iksF1F zK&_#$6DWHjT}T@4q@K(A`-K&a*l=PCmRSw>@rGMzD7R`0-h_T;Q!}c}`WT1x+FI~2 z6Ac0Ht#y?SH?k7w$T6RMByW2U9P9D%J-{C$I)K)jAS*6l?s~i*gojNgf%|2t9e|A5 z*m!INVZQ(xfoN-TTdWU9ub02@h$Fy0nG*JOcZz>^$L1(#Wx*zc^?|C?MCzoWpP{G) z*OC=ua2hhqGf58gWv>qSw&jZTH<#c)k_eRAv76IuWDj7~-t7R&dak9*?yAfCdeT)* zE8fCFh^qva&sV)>m{5!tOgwqcMVOuJRUP(vw6thrR0Dz5XG~(6%=C8`94Lq3e(W@*pR)?_R z_rRY44)Nhgp9x_xdUo!OE+x*L9bK}CEMz*^LGo>P=Rv=TdV>MlBM;2~({0vvVYsn{ ziKGJ8kIbLhr}pDFh_Q|GdW^l|symhqSErC0QI|>3;%}ugBMwbq4m)j?>(hD6F)JRp ztHb;|xD&fXIm(D@s1JAA@VX{!CTD_f?X5xkG|eA2;K!MoYTUwACvEn9*pV|rf^$Ny zz+WUqFM!D5%EIYW4bvj>;$VB63K-N4usG($LYoD>Ln|ou%yn9+H%MC=2=_d3$)r*D z9HDn6!O%);LgqyYY};*)VNP)45LQ>Ire(Gg6h3T$9N9Q*o*4;PHUL@|3Cnni+tJao zFGGS7&#{=p+5z#-ldz3~XXVJVaKBFS8ZBPhy<=8PR15~=POT;okA+BMyur}-MlzJv zq0${xdR$GA&~#>@5y0D}-r=^ut~@Rxkk(32F`|74C{9$mg-UEtLP{WbwDI|{WHv?= z2QG`L0XUb@VoX~i)BEg(tguiSFp5oTp=0Br);`8y$9!b~wR+Ex;>%sJOZ#MchN(2E zkBw{!&sUS4m06xyrV4P1Wt>Bj@)Fan33HBicIxaHLoS>70l=DWk;L;wuBHILoEhR> z7D`GTzllJP1VEq&5SSUjj#Ec-r6jRoxs&oxi)W5qhfrh|CwD)wTtXT4l~{HltTWmT zP8CE?PkN_aQQDKS-FhdpnSpkIx3yI`a140_oL~|inUMyYo$B*5+Uo9;n~8QDd8?>! zGd)HL2R||>aDsNPSiR1lw<8F!*BTC^7R-#lo-?;`6*9BXaNf>NG#R&KBExq@ed(+3#M>0m z?Xznq>;ib>P>Z*f-lsNm&5rmazH@$M?OAwHiez!ND!FFqdo}Hjiarm>6<0=M#lS+by$4`3+ut|1#Q9+Ag9-2C-lthu?*(9sUIi;b zzX=`9o-7%WzP@d*=cgo=ia=h8EI^wg(S7C7(WbLYQhles65*r?uF3Sh!f==1Q6OLo ztH4@I3xuU^$EvsLHgct=%Dhf3@;Boa>Med{uRQ+zFe+jdmI>}G_IdEMROTkGlR-VF z6s?5LA9LV9f?yOxrWa3=tw3}!% zeu9bi2Glz3n&+H#j6D1I(Z~7mT5j{W%(3D|7n2b=%UgH#BO91Nz!-0WJbU&XRD#_c z7E`@cL$NUR8&W(pe>OI#t=uDcGZqtrYML8sC=d2sta?ky=rI?V1K09K{{cBT84=}B znCZxy@7jN!1*=8iOZRqt{zpvI+ONrrNUw_JTG*9QWV&l3yzLk!HtiJCQiwZyUa(nC zr4h(Ht_&XJGAh5KG%{yYx%{T7w+4}*)TxmTZdo){g_HVyfPAGDU$OCkQPgIN z!fGph@t+P<1S}c$+x$LNwM&fk?o?mVT(6VkBaGY!;y|tH9(8pDsh!*R&AqjJnRCVE zVH5Gt%0$5OrC;>{3rYKat0+{NR*1-39~E2ulmc!U@H<&};Y%H)7Z5~`XdW;r>mKUN z+SC7=lJV-7*Q43`@`Zt^fR&~R-74G4<*}88lJ_ghiw_Q*DNXOI>P??(p}LA=BspL> zvds_2N3%&Qv-?U`%2%fLO%`u4KYx!aFr$X=Q~0L9fSwCd6pTCvCI}NAy`7db;n>jK z-AH*w5gpg|{CelMd_?d8ld03ixhf_^Xo5J)_xbj;fMUf&$Ih(Ni)YPRx}?fns%_5j z1SV95X0-D=I{q#@kkbOD3f$%Gz_d=Ozgq&9KP`ucmu|8cJ5$jWdSr*0mG(cG!H<9K05R2aW@g|dRSX@OkAB{SPdQ@9xcn3D7;!O)>H>x+z|sp+U@#SVwy z&(fLvnpK)cESQWGz(wVT>zRjII|`j0Y{e!T>{{wGLcq7Ni*{BL1!upoSKOj<^7)hY zw&1CYy#1S$UIcMuuEJ{f0}3eD_dR^|%Cao6yELJ@J$+i(&a^8$m^gLMA;C0EOw@%} zR#bE+dq!!lirf)s4Ua)%RI{C-*}=iJ=d){*OgBx@8&{S~IU3IK1Sb8iT*z;x3(M*~ l3tm&n4F|RVUq4OFUjb=r)7yPCHYlKuN3;wyvk#K4{U6v3*!che diff --git a/docs/source/_static/yosyshq.css b/docs/source/_static/yosyshq.css deleted file mode 100644 index 447c85367..000000000 --- a/docs/source/_static/yosyshq.css +++ /dev/null @@ -1,40 +0,0 @@ -/* Don't hide the right sidebar as we're placing our fixed links there */ -aside.no-toc { - display: block !important; -} - -/* Colorful headings */ -h1 { - color: var(--color-brand-primary); - } - -h2, h3, h4, h5, h6 { - color: var(--color-brand-content); -} - -/* Use a different color for external links */ -a.external { - color: var(--color-brand-primary) !important; -} - -.wy-table-responsive table td { - white-space: normal; -} - -th { - text-align: left; -} - -body[data-theme="dark"] { - .invert-helper { - filter: url("data:image/svg+xml,#f"); - } -} - -@media (prefers-color-scheme: dark) { - body:not([data-theme="light"]) { - .invert-helper { - filter: url("data:image/svg+xml,#f"); - } - } -} \ No newline at end of file diff --git a/docs/source/_templates/page.html b/docs/source/_templates/page.html deleted file mode 100644 index d830124c1..000000000 --- a/docs/source/_templates/page.html +++ /dev/null @@ -1,44 +0,0 @@ -{# - -See https://github.com/pradyunsg/furo/blob/main/src/furo/theme/furo/page.html for the original -block this is overwriting. - -The part that is customized is between the "begin of custom part" and "end of custom part" -comments below. It uses the same styles as the existing right sidebar code. - -#} -{% extends "furo/page.html" %} -{% block right_sidebar %} -
- {# begin of custom part #} -
- - YosysHQ - -
-
-
- -
-
- {# end of custom part #} - {% if not furo_hide_toc %} -
- - {{ _("On this page") }} - -
-
-
- {{ toc }} -
-
- {% endif %} -
-{% endblock %} - \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 9a22d50d3..d63523ab0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -8,37 +8,13 @@ copyright ='2024 YosysHQ GmbH' yosys_ver = "0.46" # select HTML theme -html_theme = 'furo' -templates_path = ["_templates"] -html_logo = '_static/logo.png' -html_favicon = '_static/favico.png' -html_css_files = ['yosyshq.css', 'custom.css'] - -html_theme_options = { - "sidebar_hide_name": True, - - "light_css_variables": { - "color-brand-primary": "#d6368f", - "color-brand-content": "#4b72b8", - "color-api-name": "#8857a3", - "color-api-pre-name": "#4b72b8", - "color-link": "#8857a3", - }, - - "dark_css_variables": { - "color-brand-primary": "#e488bb", - "color-brand-content": "#98bdff", - "color-api-name": "#8857a3", - "color-api-pre-name": "#4b72b8", - "color-link": "#be95d5", - }, -} +html_theme = 'furo-ys' +html_css_files = ['custom.css'] # These folders are copied to the documentation's HTML output html_static_path = ['_static', "_images"] -# code blocks style -pygments_style = 'colorful' +# default to no highlight highlight_language = 'none' # default single quotes to attempt auto reference, or fallback to code diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt index dbba55832..203205169 100644 --- a/docs/source/requirements.txt +++ b/docs/source/requirements.txt @@ -1,3 +1,3 @@ -furo +furo-ys @ git+https://github.com/YosysHQ/furo-ys sphinxcontrib-bibtex rtds-action From 1b0d8633c4ef6a37c9f148363ac0f8bd6807fb65 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 20 May 2024 15:49:49 +1200 Subject: [PATCH 043/496] Docs: Add root to ToC --- docs/source/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/index.rst b/docs/source/index.rst index 106ddbab8..b76b5fe06 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -36,6 +36,7 @@ available, go to :ref:`commandindex`. :maxdepth: 3 :includehidden: + self introduction getting_started/index using_yosys/index From ccd3bace2303ee0a33ce2e04dcb362497e9b9c14 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 20 May 2024 15:50:28 +1200 Subject: [PATCH 044/496] Docs: Add cells loc config value --- docs/source/conf.py | 2 ++ docs/util/cellref.py | 6 ++++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index d63523ab0..e16179cb0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,4 +1,5 @@ #!/usr/bin/env python3 +from pathlib import Path import sys import os @@ -79,6 +80,7 @@ extensions.append('util.cmdref') # use autodocs extensions.append('sphinx.ext.autodoc') extensions.append('util.cellref') +cells_loc = Path(__file__).parent / 'generated' from sphinx.application import Sphinx def setup(app: Sphinx) -> None: diff --git a/docs/util/cellref.py b/docs/util/cellref.py index 4deda41dd..63e6dd543 100644 --- a/docs/util/cellref.py +++ b/docs/util/cellref.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 from __future__ import annotations -from pathlib import Path +from pathlib import Path, PosixPath, WindowsPath import re from typing import Any @@ -140,7 +140,8 @@ class YosysCellDocumenter(Documenter): # find cell lib file objpath = Path('/'.join(self.objpath)) if not objpath.exists(): - objpath = Path('source') / 'generated' / objpath + cells_loc: Path = self.config.cells_loc + objpath = cells_loc / objpath # load cell lib try: @@ -358,6 +359,7 @@ class YosysCellSourceDocumenter(YosysCellDocumenter): return False, [] def setup(app: Sphinx) -> dict[str, Any]: + app.add_config_value('cells_loc', False, 'html', [Path, PosixPath, WindowsPath]) app.setup_extension('sphinx.ext.autodoc') app.add_autodocumenter(YosysCellDocumenter) app.add_autodocumenter(YosysCellSourceDocumenter) From 84f29680315adaf32846c09b9da0489eeacaf341 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 20 May 2024 16:45:23 +1200 Subject: [PATCH 045/496] cellref: Better name checking Fix RTD not including source with warning `WARNING: invalid signature for autocellsource ('/home/docs/checkouts/readthedocs.org/user_builds/yosys/checkouts/manual-rewrite/source/generated/simlib.v:$alu::__source')`. --- docs/util/cellref.py | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/util/cellref.py b/docs/util/cellref.py index 63e6dd543..4b9703101 100644 --- a/docs/util/cellref.py +++ b/docs/util/cellref.py @@ -14,7 +14,7 @@ logger = logging.getLogger(__name__) # cell signature cell_ext_sig_re = re.compile( - r'''^ (?:([\w._/]+):)? # explicit file name + r'''^ (?:([^:\s]+):)? # explicit file name ([\w$._]+?)? # module and/or class name(s) (?:\.([\w_]+))? # optional: thing name (::[\w_]+)? # attribute @@ -147,9 +147,18 @@ class YosysCellDocumenter(Documenter): try: parsed_lib = self.parsed_libs[objpath] except KeyError: - parsed_lib = load_cell_lib(objpath) + try: + parsed_lib = load_cell_lib(objpath) + except FileNotFoundError: + logger.warning( + f"unable to find cell lib at {'/'.join(self.objpath)}", + type = 'cellref', + subtype = 'import_object' + ) + return False self.parsed_libs[objpath] = parsed_lib + # get cell try: self.object = parsed_lib[self.modname] @@ -264,7 +273,12 @@ class YosysCellDocumenter(Documenter): ) return - self.import_object() + if not self.import_object(): + logger.warning( + f"unable to load {self.name}", + type = 'cellref' + ) + return # check __module__ of object (for members not given explicitly) # if check_module: From 7eb33f19333fc23d1b0bcde0bf22abd034287f10 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 20 May 2024 16:49:52 +1200 Subject: [PATCH 046/496] Docs: Testing autocell --- docs/source/appendix.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/source/appendix.rst b/docs/source/appendix.rst index 9e8b8be34..4a8976be0 100644 --- a/docs/source/appendix.rst +++ b/docs/source/appendix.rst @@ -1,6 +1,12 @@ Appendix ======== +.. autocell:: simlib.v:$alu + :source: + :linenos: + +.. autocell:: simlib.v:$lcu + .. toctree:: :maxdepth: 2 :includehidden: From 7c5b10fe504a190c03ed6885e27e33c6430ee310 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 21 May 2024 12:16:32 +1200 Subject: [PATCH 047/496] cellref: Add json dump New `help -dump-cells-json ` to dump cells list. Add 'group' field to SimHelper class/struct with defaults to gate_other and word_other depending on source (simcells or simlib). Add 'unary' group to unary operator cells for testing (based on internal cell library docs page). --- kernel/register.cc | 83 +++++++++++++++++++++++++++++++++++++ techlibs/common/cellhelp.py | 20 ++++++++- techlibs/common/simlib.v | 17 +++++--- 3 files changed, 113 insertions(+), 7 deletions(-) diff --git a/kernel/register.cc b/kernel/register.cc index 4dfa79845..4e8e62741 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -19,6 +19,7 @@ #include "kernel/yosys.h" #include "kernel/satgen.h" +#include "kernel/json.h" #include #include @@ -763,6 +764,7 @@ struct SimHelper { string source; string desc; string code; + string group; string ver; }; @@ -950,6 +952,77 @@ struct HelpPass : public Pass { // close fclose(f); } + bool dump_cells_json(PrettyJson &json) { + // init json + json.begin_object(); + json.entry("version", "Yosys internal cells"); + json.entry("generator", yosys_version_str); + + dict>> groups; + + // iterate over cells + bool raise_error = false; + for (auto &it : yosys_celltypes.cell_types) { + auto name = it.first.str(); + if (cell_help_messages.contains(name)) { + auto cell_help = cell_help_messages.get(name); + dict> *cell_group; + if (groups.count(cell_help.group) != 0) { + cell_group = &groups.at(cell_help.group); + } else { + cell_group = new dict>(); + groups.emplace(cell_help.group, *cell_group); + } + auto cell_pair = pair(cell_help, it.second); + cell_group->emplace(name, cell_pair); + } else { + log("ERROR: Missing cell help for cell '%s'.\n", name.c_str()); + raise_error |= true; + } + } + + // write to json + json.name("groups"); + json.begin_array(); + groups.sort(); + for (auto &it : groups) { + json.begin_object(); + json.name("group"); json.value(it.first.c_str()); + json.name("cells"); json.begin_array(); + for (auto &it2 : it.second) { + auto ch = it2.second.first; + auto ct = it2.second.second; + json.begin_object(); + json.name("cell"); json.value(ch.name); + json.name("title"); json.value(ch.title); + json.name("ports"); json.value(ch.ports); + json.name("source"); json.value(ch.source); + json.name("desc"); json.value(ch.desc); + json.name("code"); json.value(ch.code); + json.name("inputs"); json.begin_array(); + for (auto &input : ct.inputs) + json.value(input.c_str()); + json.end_array(); + json.name("outputs"); json.begin_array(); + for (auto &output : ct.outputs) + json.value(output.c_str()); + json.end_array(); + dict prop_dict = { + {"is_evaluable", ct.is_evaluable}, + {"is_combinatorial", ct.is_combinatorial}, + {"is_synthesizable", ct.is_synthesizable}, + }; + json.name("properties"); json.value(prop_dict); + json.end_object(); + } + json.end_array(); + json.end_object(); + } + json.end_array(); + + json.end_object(); + return raise_error; + } void execute(std::vector args, RTLIL::Design*) override { if (args.size() == 1) { @@ -1053,6 +1126,16 @@ struct HelpPass : public Pass { else log("No such command or cell type: %s\n", args[1].c_str()); return; + } else if (args.size() == 3) { + if (args[1] == "-dump-cells-json") { + PrettyJson json; + if (!json.write_to_file(args[2])) + log_error("Can't open file `%s' for writing: %s\n", args[2].c_str(), strerror(errno)); + if (dump_cells_json(json)) { + log_error("One or more cells defined in celltypes.h are missing help documentation.\n"); + } + } + return; } help(); diff --git a/techlibs/common/cellhelp.py b/techlibs/common/cellhelp.py index 0cfb2052f..299b7affd 100644 --- a/techlibs/common/cellhelp.py +++ b/techlibs/common/cellhelp.py @@ -12,6 +12,7 @@ class SimHelper: source: str = "" desc: list[str] code: list[str] + group: str = "" ver: str = "1" def __init__(self) -> None: @@ -19,7 +20,7 @@ class SimHelper: def __str__(self) -> str: printed_fields = [ - "name", "title", "ports", "source", "desc", "code", "ver", + "name", "title", "ports", "source", "desc", "code", "group", "ver", ] # generate C++ struct val = f"cell_help[{json.dumps(self.name)}] = " @@ -28,6 +29,7 @@ class SimHelper: field_val = getattr(self, field) if isinstance(field_val, list): field_val = "\n".join(field_val) + field_val = field_val.strip() val += f' {json.dumps(field_val)},\n' val += "};\n" return val @@ -80,9 +82,23 @@ for line in fileinput.input(): if simHelper.ver == "1" and short_filename == "simcells.v": # default simcells parsing simcells_reparse(simHelper) + + # check help if not simHelper.desc: - # no help simHelper.desc.append("No help message for this cell type found.\n") + elif simHelper.ver == "1" and short_filename == "simlib.v" and simHelper.desc[1].startswith(' '): + simHelper.desc.pop(1) + + # check group + if not simHelper.group: + if short_filename == 'simcells.v': + simHelper.group = "gate_" + elif short_filename == 'simlib.v': + simHelper.group = "word_" + simHelper.group += "other" + + # dump print(simHelper) + # new simHelper = SimHelper() diff --git a/techlibs/common/simlib.v b/techlibs/common/simlib.v index 6bcace498..b8a754825 100644 --- a/techlibs/common/simlib.v +++ b/techlibs/common/simlib.v @@ -33,11 +33,10 @@ // -------------------------------------------------------- -// |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| -//- -//- $not (A, Y) -//- -//- A bit-wise inverter. This corresponds to the Verilog unary prefix '~' operator. +//* ver 2 +//* title Bit-wise inverter +//* group unary +//- This corresponds to the Verilog unary prefix '~' operator. //- module \$not (A, Y); @@ -63,6 +62,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $pos (A, Y) +//* group unary //- //- A buffer. This corresponds to the Verilog unary prefix '+' operator. //- @@ -111,6 +111,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $neg (A, Y) +//* group unary //- //- An arithmetic inverter. This corresponds to the Verilog unary prefix '-' operator. //- @@ -258,6 +259,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $reduce_and (A, Y) +//* group unary //- //- An AND reduction. This corresponds to the Verilog unary prefix '&' operator. //- @@ -285,6 +287,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $reduce_or (A, Y) +//* group unary //- //- An OR reduction. This corresponds to the Verilog unary prefix '|' operator. //- @@ -312,6 +315,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $reduce_xor (A, Y) +//* group unary //- //- A XOR reduction. This corresponds to the Verilog unary prefix '^' operator. //- @@ -339,6 +343,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $reduce_xnor (A, Y) +//* group unary //- //- A XNOR reduction. This corresponds to the Verilog unary prefix '~^' operator. //- @@ -366,6 +371,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $reduce_bool (A, Y) +//* group unary //- //- An OR reduction. This cell type is used instead of $reduce_or when a signal is //- implicitly converted to a boolean signal, e.g. for operands of '&&' and '||'. @@ -1359,6 +1365,7 @@ endmodule //- //- A logical inverter. This corresponds to the Verilog unary prefix '!' operator. //- +//* group unary module \$logic_not (A, Y); parameter A_SIGNED = 0; From a119d41303aeadd79931e4ac8dbd1892bdcec6a3 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 21 May 2024 12:17:39 +1200 Subject: [PATCH 048/496] Docs: Move appendix toc to main toc Adds an Appendix header to sidebar toc instead of being an (empty) subpage. --- docs/source/appendix.rst | 25 ------------------------- docs/source/index.rst | 23 ++++++++++++++++------- 2 files changed, 16 insertions(+), 32 deletions(-) delete mode 100644 docs/source/appendix.rst diff --git a/docs/source/appendix.rst b/docs/source/appendix.rst deleted file mode 100644 index 4a8976be0..000000000 --- a/docs/source/appendix.rst +++ /dev/null @@ -1,25 +0,0 @@ -Appendix -======== - -.. autocell:: simlib.v:$alu - :source: - :linenos: - -.. autocell:: simlib.v:$lcu - -.. toctree:: - :maxdepth: 2 - :includehidden: - - appendix/primer - appendix/auxlibs - appendix/auxprogs - - bib - -.. toctree:: - :maxdepth: 1 - :includehidden: - - cmd_ref - cell_ref diff --git a/docs/source/index.rst b/docs/source/index.rst index b76b5fe06..ce612f9b0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -27,19 +27,28 @@ available, go to :ref:`commandindex`. .. todolist:: -.. only:: html - - Table of contents - ----------------- - .. toctree:: :maxdepth: 3 :includehidden: - self + Yosys (index) introduction + getting_started/index using_yosys/index yosys_internals/index - appendix +.. toctree:: + :caption: Appendix + :titlesonly: + :includehidden: + + appendix/primer + appendix/auxlibs + appendix/auxprogs + + bib + + cell_word + cell_gate + cmd_ref From 9533cf2916b02aeb9be51ac3b440274b35f1023a Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 21 May 2024 14:04:38 +1200 Subject: [PATCH 049/496] Makefile: Use dump-cells-json for docs --- Makefile | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 87e62adb5..e5ca83aea 100644 --- a/Makefile +++ b/Makefile @@ -993,6 +993,9 @@ docs/source/cell/word_add.rst: $(TARGETS) $(EXTRA_TARGETS) $(Q) rsync -rc temp/docs/source/cell docs/source $(Q) rm -rf temp +docs/source/generated/cells.json: docs/source/generated $(TARGETS) $(EXTRA_TARGETS) + $(Q) ./$(PROGRAM_PREFIX)yosys -p 'help -dump-cells-json $@' + PHONY: docs/gen_examples docs/gen_images docs/guidelines docs/usage docs/reqs docs/gen_examples: $(TARGETS) $(Q) $(MAKE) -C docs examples @@ -1034,7 +1037,7 @@ docs/reqs: $(Q) $(MAKE) -C docs reqs .PHONY: docs/prep -docs/prep: docs/source/cmd/abc.rst docs/source/cell/word_add.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage +docs/prep: docs/source/cmd/abc.rst docs/source/generated/cells.json docs/gen_examples docs/gen_images docs/guidelines docs/usage DOC_TARGET ?= html docs: docs/prep From 37573a6f00a8d8ed9ef5a16b5f1ac718c66b07aa Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 21 May 2024 14:06:08 +1200 Subject: [PATCH 050/496] Docs: Use json for cellref e.g. ``` .. autocell:: $alu :source: :linenos: ``` --- docs/util/cellref.py | 155 +++++++++++++------------------------------ 1 file changed, 45 insertions(+), 110 deletions(-) diff --git a/docs/util/cellref.py b/docs/util/cellref.py index 4b9703101..0d5c9ba56 100644 --- a/docs/util/cellref.py +++ b/docs/util/cellref.py @@ -1,6 +1,8 @@ #!/usr/bin/env python3 from __future__ import annotations +from dataclasses import dataclass +import json from pathlib import Path, PosixPath, WindowsPath import re @@ -15,94 +17,55 @@ logger = logging.getLogger(__name__) # cell signature cell_ext_sig_re = re.compile( r'''^ (?:([^:\s]+):)? # explicit file name - ([\w$._]+?)? # module and/or class name(s) + ([\w$._]+?) # module name (?:\.([\w_]+))? # optional: thing name (::[\w_]+)? # attribute \s* $ # and nothing more ''', re.VERBOSE) -class SimHelper: - name: str = "" - title: str = "" - ports: str = "" - source: str = "" - desc: list[str] - code: list[str] - group: str = "" - ver: str = "1" - - def __init__(self) -> None: - self.desc = [] - -def simcells_reparse(cell: SimHelper): - # cut manual signature - cell.desc = cell.desc[3:] - - # code-block truth table - new_desc = [] - indent = "" - for line in cell.desc: - if line.startswith("Truth table:"): - indent = " " - new_desc.pop() - new_desc.extend(["::", ""]) - new_desc.append(indent + line) - cell.desc = new_desc - - # set version - cell.ver = "2a" - -def load_cell_lib(file: Path): - simHelpers: dict[str, SimHelper] = {} - simHelper = SimHelper() - with open(file, "r") as f: - lines = f.readlines() - - for lineno, line in enumerate(lines, 1): - line = line.rstrip() - # special comments - if line.startswith("//-"): - simHelper.desc.append(line[4:] if len(line) > 4 else "") - elif line.startswith("//* "): - _, key, val = line.split(maxsplit=2) - setattr(simHelper, key, val) - - # code parsing - if line.startswith("module "): - clean_line = line[7:].replace("\\", "").replace(";", "") - simHelper.name, simHelper.ports = clean_line.split(maxsplit=1) - simHelper.code = [] - simHelper.source = f'{file.name}:{lineno}' - elif not line.startswith("endmodule"): - line = " " + line - try: - simHelper.code.append(line.replace("\t", " ")) - except AttributeError: - # no module definition, ignore line - pass - if line.startswith("endmodule"): - if simHelper.ver == "1" and file.name == "simcells.v": - # default simcells parsing - simcells_reparse(simHelper) - if not simHelper.desc: - # no help - simHelper.desc.append("No help message for this cell type found.\n") - elif simHelper.ver == "1" and file.name == "simlib.v" and simHelper.desc[1].startswith(' '): - simHelper.desc.pop(1) - simHelpers[simHelper.name] = simHelper - simHelper = SimHelper() - return simHelpers +@dataclass +class YosysCell: + cell: str + title: str + ports: str + source: str + desc: str + code: str + inputs: list[str] + outputs: list[str] + properties: dict[str, bool] class YosysCellDocumenter(Documenter): objtype = 'cell' - parsed_libs: dict[Path, dict[str, SimHelper]] = {} - object: SimHelper + object: YosysCell option_spec = { 'source': autodoc.bool_option, 'linenos': autodoc.bool_option, } + __cell_lib: dict[str, YosysCell] | None = None + @property + def cell_lib(self) -> dict[str, YosysCell]: + if not self.__cell_lib: + self.__cell_lib = {} + cells_obj: dict[str, list[dict[str, list[dict[str]]]]] + try: + with open(self.config.cells_json, "r") as f: + cells_obj = json.loads(f.read()) + except FileNotFoundError: + logger.warning( + f"unable to find cell lib at {self.config.cells_json}", + type = 'cellref', + subtype = 'cell_lib' + ) + else: + for group in cells_obj.get("groups", []): + for cell in group.get("cells", []): + yosysCell = YosysCell(**cell) + self.__cell_lib[yosysCell.cell] = yosysCell + return self.__cell_lib + @classmethod def can_document_member( cls, @@ -125,9 +88,6 @@ class YosysCellDocumenter(Documenter): logger.warning(('invalid signature for auto%s (%r)') % (self.objtype, self.name), type='cellref') return False - - if not path: - return False self.modname = modname self.objpath = [path] @@ -137,45 +97,23 @@ class YosysCellDocumenter(Documenter): return True def import_object(self, raiseerror: bool = False) -> bool: - # find cell lib file - objpath = Path('/'.join(self.objpath)) - if not objpath.exists(): - cells_loc: Path = self.config.cells_loc - objpath = cells_loc / objpath - - # load cell lib - try: - parsed_lib = self.parsed_libs[objpath] - except KeyError: - try: - parsed_lib = load_cell_lib(objpath) - except FileNotFoundError: - logger.warning( - f"unable to find cell lib at {'/'.join(self.objpath)}", - type = 'cellref', - subtype = 'import_object' - ) - return False - self.parsed_libs[objpath] = parsed_lib - - # get cell try: - self.object = parsed_lib[self.modname] + self.object = self.cell_lib[self.modname] except KeyError: return False - self.real_modname = f'{objpath}:{self.modname}' + self.real_modname = self.modname or '' return True def get_sourcename(self) -> str: - return self.objpath + return self.object.source.split(":")[0] def format_name(self) -> str: - return self.object.name + return self.object.cell def format_signature(self, **kwargs: Any) -> str: - return f"{self.object.name} {self.object.ports}" + return f"{self.object.cell} {self.object.ports}" def add_directive_header(self, sig: str) -> None: domain = getattr(self, 'domain', self.objtype) @@ -202,7 +140,7 @@ class YosysCellDocumenter(Documenter): sourcename = self.get_sourcename() startline = int(self.object.source.split(":")[1]) - for i, line in enumerate(self.object.desc, startline): + for i, line in enumerate(self.object.desc.splitlines(), startline): self.add_line(line, sourcename, i) # add additional content (e.g. from document), if present @@ -321,9 +259,6 @@ class YosysCellSourceDocumenter(YosysCellDocumenter): isattr: bool, parent: Any ) -> bool: - sourcename = str(member).split(":")[0] - if not sourcename.endswith(".v"): - return False if membername != "__source": return False if isinstance(parent, YosysCellDocumenter): @@ -358,7 +293,7 @@ class YosysCellSourceDocumenter(YosysCellDocumenter): sourcename = self.get_sourcename() startline = int(self.object.source.split(":")[1]) - for i, line in enumerate(self.object.code, startline-1): + for i, line in enumerate(self.object.code.splitlines(), startline-1): self.add_line(line, sourcename, i) # add additional content (e.g. from document), if present @@ -373,7 +308,7 @@ class YosysCellSourceDocumenter(YosysCellDocumenter): return False, [] def setup(app: Sphinx) -> dict[str, Any]: - app.add_config_value('cells_loc', False, 'html', [Path, PosixPath, WindowsPath]) + app.add_config_value('cells_json', False, 'html', [Path, PosixPath, WindowsPath]) app.setup_extension('sphinx.ext.autodoc') app.add_autodocumenter(YosysCellDocumenter) app.add_autodocumenter(YosysCellSourceDocumenter) From 65723200e5edbb6f19ad1fb60dd27be86994e2bb Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 21 May 2024 14:06:28 +1200 Subject: [PATCH 051/496] Docs: Delete unused cell_ref.rst --- docs/source/cell_ref.rst | 13 ------------- 1 file changed, 13 deletions(-) delete mode 100644 docs/source/cell_ref.rst diff --git a/docs/source/cell_ref.rst b/docs/source/cell_ref.rst deleted file mode 100644 index dc143124e..000000000 --- a/docs/source/cell_ref.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _cell_ref: - -================================================================================ -Internal cell reference -================================================================================ - -.. toctree:: - :caption: Internal cell reference - :maxdepth: 2 - :glob: - - cell_word - cell_gate From 5a4a4191af072bee5d19008a5708fa9074cb2601 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 21 May 2024 14:06:57 +1200 Subject: [PATCH 052/496] Docs: Update conf.py for cellref --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index e16179cb0..8e504df55 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -80,7 +80,7 @@ extensions.append('util.cmdref') # use autodocs extensions.append('sphinx.ext.autodoc') extensions.append('util.cellref') -cells_loc = Path(__file__).parent / 'generated' +cells_json = Path(__file__).parent / 'generated' / 'cells.json' from sphinx.application import Sphinx def setup(app: Sphinx) -> None: From b127ac07f8e7f1d9316a1cc06e3fa2e216bcbe0d Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 21 May 2024 18:10:20 +1200 Subject: [PATCH 053/496] Docs: Preliminary autocellgroup usage Remove `/source/cell` from .gitignore. Add a few initial cell pages. Add YosysCellGroup documenter and cell:group directive. Update Documenters to use nested json. Better nested tocs for group.module.source layout. --- docs/.gitignore | 1 - docs/source/cell/gate_other.rst | 5 + docs/source/cell/word_other.rst | 5 + docs/source/cell/word_unary.rst | 50 ++++++++ docs/source/cell_gate.rst | 5 +- docs/source/cell_word.rst | 6 +- docs/util/cellref.py | 205 ++++++++++++++++++++++---------- docs/util/cmdref.py | 103 ++++++++++++---- kernel/register.cc | 81 +++++++------ 9 files changed, 331 insertions(+), 130 deletions(-) create mode 100644 docs/source/cell/gate_other.rst create mode 100644 docs/source/cell/word_other.rst create mode 100644 docs/source/cell/word_unary.rst diff --git a/docs/.gitignore b/docs/.gitignore index 78a1f48e1..65bbcdeae 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,6 +1,5 @@ /build/ /source/cmd -/source/cell /source/generated /source/_images/**/*.log /source/_images/**/*.aux diff --git a/docs/source/cell/gate_other.rst b/docs/source/cell/gate_other.rst new file mode 100644 index 000000000..7696ba824 --- /dev/null +++ b/docs/source/cell/gate_other.rst @@ -0,0 +1,5 @@ +.. autocellgroup:: gate_other + :caption: Other gate-level cells + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_other.rst b/docs/source/cell/word_other.rst new file mode 100644 index 000000000..9e5ac2a37 --- /dev/null +++ b/docs/source/cell/word_other.rst @@ -0,0 +1,5 @@ +.. autocellgroup:: word_other + :caption: Other word-level cells + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_unary.rst b/docs/source/cell/word_unary.rst new file mode 100644 index 000000000..59f03397c --- /dev/null +++ b/docs/source/cell/word_unary.rst @@ -0,0 +1,50 @@ +.. role:: verilog(code) + :language: Verilog + +Unary operators +--------------- + +All unary RTL cells have one input port ``A`` and one output port ``Y``. They +also have the following parameters: + +``A_SIGNED`` + Set to a non-zero value if the input ``A`` is signed and therefore should be + sign-extended when needed. + +``A_WIDTH`` + The width of the input port ``A``. + +``Y_WIDTH`` + The width of the output port ``Y``. + +.. table:: Cell types for unary operators with their corresponding Verilog expressions. + + ================== ============== + Verilog Cell Type + ================== ============== + :verilog:`Y = ~A` `$not` + :verilog:`Y = +A` `$pos` + :verilog:`Y = -A` `$neg` + :verilog:`Y = &A` `$reduce_and` + :verilog:`Y = |A` `$reduce_or` + :verilog:`Y = ^A` `$reduce_xor` + :verilog:`Y = ~^A` `$reduce_xnor` + :verilog:`Y = |A` `$reduce_bool` + :verilog:`Y = !A` `$logic_not` + ================== ============== + +For the unary cells that output a logical value (`$reduce_and`, `$reduce_or`, +`$reduce_xor`, `$reduce_xnor`, `$reduce_bool`, `$logic_not`), when the +``Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and only +the least significant bit varies. + +Note that `$reduce_or` and `$reduce_bool` actually represent the same logic +function. But the HDL frontends generate them in different situations. A +`$reduce_or` cell is generated when the prefix ``|`` operator is being used. A +`$reduce_bool` cell is generated when a bit vector is used as a condition in an +``if``-statement or ``?:``-expression. + +.. autocellgroup:: unary + :members: + :source: + :linenos: diff --git a/docs/source/cell_gate.rst b/docs/source/cell_gate.rst index 74dd57bc7..0e977c587 100644 --- a/docs/source/cell_gate.rst +++ b/docs/source/cell_gate.rst @@ -3,7 +3,6 @@ Gate-level cells .. toctree:: :caption: Gate-level cells - :maxdepth: 1 - :glob: + :maxdepth: 2 - /cell/gate_* + /cell/gate_other diff --git a/docs/source/cell_word.rst b/docs/source/cell_word.rst index f7205e6ee..9b7811324 100644 --- a/docs/source/cell_word.rst +++ b/docs/source/cell_word.rst @@ -2,8 +2,8 @@ Word-level cells ---------------- .. toctree:: - :caption: Word-level cells - :maxdepth: 1 + :maxdepth: 2 :glob: - /cell/word_* + /cell/word_unary + /cell/word_other diff --git a/docs/util/cellref.py b/docs/util/cellref.py index 0d5c9ba56..3bba27876 100644 --- a/docs/util/cellref.py +++ b/docs/util/cellref.py @@ -16,7 +16,7 @@ logger = logging.getLogger(__name__) # cell signature cell_ext_sig_re = re.compile( - r'''^ (?:([^:\s]+):)? # explicit file name + r'''^ ([^:\s]+::)? # optional group or file name ([\w$._]+?) # module name (?:\.([\w_]+))? # optional: thing name (::[\w_]+)? # attribute @@ -25,7 +25,7 @@ cell_ext_sig_re = re.compile( @dataclass class YosysCell: - cell: str + name: str title: str ports: str source: str @@ -34,22 +34,26 @@ class YosysCell: inputs: list[str] outputs: list[str] properties: dict[str, bool] - -class YosysCellDocumenter(Documenter): - objtype = 'cell' - object: YosysCell + +class YosysCellGroupDocumenter(Documenter): + objtype = 'cellgroup' + priority = 10 + object: tuple[str, list[str]] + lib_key = 'groups' option_spec = { + 'caption': autodoc.annotation_option, + 'members': autodoc.members_option, 'source': autodoc.bool_option, 'linenos': autodoc.bool_option, } - __cell_lib: dict[str, YosysCell] | None = None + __cell_lib: dict[str, list[str] | dict[str]] | None = None @property - def cell_lib(self) -> dict[str, YosysCell]: + def cell_lib(self) -> dict[str, list[str] | dict[str]]: if not self.__cell_lib: self.__cell_lib = {} - cells_obj: dict[str, list[dict[str, list[dict[str]]]]] + cells_obj: dict[str, dict[str, list[str] | dict[str]]] try: with open(self.config.cells_json, "r") as f: cells_obj = json.loads(f.read()) @@ -60,12 +64,10 @@ class YosysCellDocumenter(Documenter): subtype = 'cell_lib' ) else: - for group in cells_obj.get("groups", []): - for cell in group.get("cells", []): - yosysCell = YosysCell(**cell) - self.__cell_lib[yosysCell.cell] = yosysCell + for (name, obj) in cells_obj.get(self.lib_key, {}).items(): + self.__cell_lib[name] = obj return self.__cell_lib - + @classmethod def can_document_member( cls, @@ -74,75 +76,51 @@ class YosysCellDocumenter(Documenter): isattr: bool, parent: Any ) -> bool: - sourcename = str(member).split(":")[0] - if not sourcename.endswith(".v"): - return False - if membername == "__source": - return False + return False def parse_name(self) -> bool: - try: - matched = cell_ext_sig_re.match(self.name) - path, modname, thing, attribute = matched.groups() - except AttributeError: - logger.warning(('invalid signature for auto%s (%r)') % (self.objtype, self.name), - type='cellref') - return False - - self.modname = modname - self.objpath = [path] - self.attribute = attribute - self.fullname = ((self.modname) + (thing or '')) - + if not self.options.caption: + self.content_indent = '' + self.fullname = self.modname = self.name return True def import_object(self, raiseerror: bool = False) -> bool: # get cell try: - self.object = self.cell_lib[self.modname] + self.object = (self.modname, self.cell_lib[self.modname]) except KeyError: + if raiseerror: + raise return False - self.real_modname = self.modname or '' + self.real_modname = self.modname return True def get_sourcename(self) -> str: - return self.object.source.split(":")[0] + return self.env.doc2path(self.env.docname) def format_name(self) -> str: - return self.object.cell + return self.options.caption or '' def format_signature(self, **kwargs: Any) -> str: - return f"{self.object.cell} {self.object.ports}" + return self.modname def add_directive_header(self, sig: str) -> None: - domain = getattr(self, 'domain', self.objtype) - directive = getattr(self, 'directivetype', 'def') + domain = getattr(self, 'domain', 'cell') + directive = getattr(self, 'directivetype', 'group') name = self.format_name() sourcename = self.get_sourcename() - cell = self.object + cell_list = self.object # cell definition - self.add_line(f'.. {domain}:{directive}:: {name}', sourcename) - - # options - opt_attrs = ["title", ] - for attr in opt_attrs: - val = getattr(cell, attr, None) - if val: - self.add_line(f' :{attr}: {val}', sourcename) + self.add_line(f'.. {domain}:{directive}:: {sig}', sourcename) + self.add_line(f' :caption: {name}', sourcename) if self.options.noindex: self.add_line(' :noindex:', sourcename) def add_content(self, more_content: Any | None) -> None: - # set sourcename and add content from attribute documentation - sourcename = self.get_sourcename() - startline = int(self.object.source.split(":")[1]) - - for i, line in enumerate(self.object.desc.splitlines(), startline): - self.add_line(line, sourcename, i) - + # groups have no native content # add additional content (e.g. from document), if present if more_content: for line, src in zip(more_content.data, more_content.items): @@ -161,14 +139,25 @@ class YosysCellDocumenter(Documenter): ) -> tuple[bool, list[tuple[str, Any]]]: ret: list[tuple[str, str]] = [] - if self.options.source: - ret.append(('__source', self.real_modname)) + if want_all: + for member in self.object[1]: + ret.append((member, self.modname)) + else: + memberlist = self.options.members or [] + for name in memberlist: + if name in self.object: + ret.append((name, self.modname)) + else: + logger.warning(('unknown module mentioned in :members: option: ' + f'group {self.modname}, module {name}'), + type='cellref') return False, ret def document_members(self, all_members: bool = False) -> None: want_all = (all_members or - self.options.inherited_members) + self.options.inherited_members or + self.options.members is autodoc.ALL) # find out which members are documentable members_check_module, members = self.get_object_members(want_all) @@ -184,7 +173,7 @@ class YosysCellDocumenter(Documenter): classes.sort(key=lambda cls: cls.priority) # give explicitly separated module name, so that members # of inner classes can be documented - full_mname = self.real_modname + '::' + mname + full_mname = self.format_signature() + '::' + mname documenter = classes[-1](self.directive, full_mname, self.indent) memberdocumenters.append((documenter, isattr)) @@ -247,6 +236,101 @@ class YosysCellDocumenter(Documenter): # document members, if possible self.document_members(all_members) +class YosysCellDocumenter(YosysCellGroupDocumenter): + objtype = 'cell' + priority = 15 + object: YosysCell + lib_key = 'cells' + + @classmethod + def can_document_member( + cls, + member: Any, + membername: str, + isattr: bool, + parent: Any + ) -> bool: + if membername == "__source": + return False + if not membername.startswith('$'): + return False + return isinstance(parent, YosysCellGroupDocumenter) + + def parse_name(self) -> bool: + try: + matched = cell_ext_sig_re.match(self.name) + group, modname, thing, attribute = matched.groups() + except AttributeError: + logger.warning(('invalid signature for auto%s (%r)') % (self.objtype, self.name), + type='cellref') + return False + + self.modname = modname + self.groupname = group or '' + self.attribute = attribute or '' + self.fullname = ((self.modname) + (thing or '')) + + return True + + def import_object(self, raiseerror: bool = False) -> bool: + if super().import_object(raiseerror): + self.object = YosysCell(self.modname, **self.object[1]) + return True + return False + + def get_sourcename(self) -> str: + return self.object.source.split(":")[0] + + def format_name(self) -> str: + return self.object.name + + def format_signature(self, **kwargs: Any) -> str: + return self.groupname + self.fullname + self.attribute + + def add_directive_header(self, sig: str) -> None: + domain = getattr(self, 'domain', self.objtype) + directive = getattr(self, 'directivetype', 'def') + name = self.format_name() + sourcename = self.get_sourcename() + cell = self.object + + # cell definition + self.add_line(f'.. {domain}:{directive}:: {sig}', sourcename) + + # options + opt_attrs = ["title", ] + for attr in opt_attrs: + val = getattr(cell, attr, None) + if val: + self.add_line(f' :{attr}: {val}', sourcename) + + if self.options.noindex: + self.add_line(' :noindex:', sourcename) + + def add_content(self, more_content: Any | None) -> None: + # set sourcename and add content from attribute documentation + sourcename = self.get_sourcename() + startline = int(self.object.source.split(":")[1]) + + for i, line in enumerate(self.object.desc.splitlines(), startline): + self.add_line(line, sourcename, i) + + # add additional content (e.g. from document), if present + if more_content: + for line, src in zip(more_content.data, more_content.items): + self.add_line(line, src[0], src[1]) + + def get_object_members( + self, + want_all: bool + ) -> tuple[bool, list[tuple[str, Any]]]: + ret: list[tuple[str, str]] = [] + + if self.options.source: + ret.append(('__source', self.real_modname)) + + return False, ret + class YosysCellSourceDocumenter(YosysCellDocumenter): objtype = 'cellsource' priority = 20 @@ -273,7 +357,7 @@ class YosysCellSourceDocumenter(YosysCellDocumenter): cell = self.object # cell definition - self.add_line(f'.. {domain}:{directive}:: {name}', sourcename) + self.add_line(f'.. {domain}:{directive}:: {sig}', sourcename) if self.options.linenos: self.add_line(f' :source: {cell.source.split(":")[0]}', sourcename) @@ -312,6 +396,7 @@ def setup(app: Sphinx) -> dict[str, Any]: app.setup_extension('sphinx.ext.autodoc') app.add_autodocumenter(YosysCellDocumenter) app.add_autodocumenter(YosysCellSourceDocumenter) + app.add_autodocumenter(YosysCellGroupDocumenter) return { 'version': '1', 'parallel_read_safe': True, diff --git a/docs/util/cmdref.py b/docs/util/cmdref.py index df1f3fb21..6fbd81372 100644 --- a/docs/util/cmdref.py +++ b/docs/util/cmdref.py @@ -15,7 +15,16 @@ from sphinx.directives.code import container_wrapper from sphinx.util.nodes import make_refnode from sphinx import addnodes -class TocNode(ObjectDescription): +class TocNode(ObjectDescription): + def add_target_and_index( + self, + name: str, + sig: str, + signode: addnodes.desc_signature + ) -> None: + idx = ".".join(name.split("::")) + signode['ids'].append(idx) + def _object_hierarchy_parts(self, sig_node: addnodes.desc_signature) -> tuple[str, ...]: if 'fullname' not in sig_node: return () @@ -34,17 +43,13 @@ class TocNode(ObjectDescription): config = self.env.app.config objtype = sig_node.parent.get('objtype') - if config.add_function_parentheses and objtype in {'function', 'method'}: - parens = '()' - else: - parens = '' *parents, name = sig_node['_toc_parts'] if config.toc_object_entries_show_parents == 'domain': - return sig_node.get('fullname', name) + parens + return sig_node.get('tocname', name) if config.toc_object_entries_show_parents == 'hide': - return name + parens + return name if config.toc_object_entries_show_parents == 'all': - return '.'.join(parents + [name + parens]) + return '.'.join(parents + [name]) return '' class CommandNode(TocNode): @@ -59,11 +64,10 @@ class CommandNode(TocNode): } def handle_signature(self, sig, signode: addnodes.desc_signature): - fullname = sig - signode['fullname'] = fullname + signode['fullname'] = sig signode += addnodes.desc_addname(text="yosys> help ") signode += addnodes.desc_name(text=sig) - return fullname + return signode['fullname'] def add_target_and_index(self, name_cls, sig, signode): signode['ids'].append(type(self).name + '-' + sig) @@ -82,11 +86,47 @@ class CommandNode(TocNode): type(self).name + '-' + sig, 0)) -class CellNode(CommandNode): +class CellNode(TocNode): """A custom node that describes an internal cell.""" name = 'cell' + option_spec = { + 'title': directives.unchanged, + 'ports': directives.unchanged, + } + + def handle_signature(self, sig: str, signode: addnodes.desc_signature): + signode['fullname'] = sig + signode['tocname'] = tocname = sig.split('::')[-1] + signode += addnodes.desc_addname(text="yosys> help ") + signode += addnodes.desc_name(text=tocname) + return signode['fullname'] + + def add_target_and_index( + self, + name: str, + sig: str, + signode: addnodes.desc_signature + ) -> None: + idx = ".".join(name.split("::")) + signode['ids'].append(idx) + if 'noindex' not in self.options: + tocname: str = signode.get('tocname', name) + tagmap = self.env.domaindata[self.domain]['obj2tag'] + tagmap[name] = list(self.options.get('tags', '').split(' ')) + title: str = self.options.get('title', sig) + titlemap = self.env.domaindata[self.domain]['obj2title'] + titlemap[name] = title + objs = self.env.domaindata[self.domain]['objects'] + # (name, sig, typ, docname, anchor, prio) + objs.append((name, + tocname, + title, + self.env.docname, + idx, + 0)) + class CellSourceNode(TocNode): """A custom code block for including cell source.""" @@ -104,21 +144,12 @@ class CellSourceNode(TocNode): signode: addnodes.desc_signature ) -> str: language = self.options.get('language') - fullname = sig + "::" + language - signode['fullname'] = fullname + signode['fullname'] = sig + signode['tocname'] = f"{sig.split('::')[-2]} {language}" signode += addnodes.desc_name(text="Simulation model") signode += addnodes.desc_sig_space() signode += addnodes.desc_addname(text=f'({language})') - return fullname - - def add_target_and_index( - self, - name: str, - sig: str, - signode: addnodes.desc_signature - ) -> None: - idx = f'{".".join(self.name.split(":"))}.{sig}' - signode['ids'].append(idx) + return signode['fullname'] def run(self) -> list[Node]: """Override run to parse content as a code block""" @@ -192,6 +223,29 @@ class CellSourceNode(TocNode): return [self.indexnode, node, literal] +class CellGroupNode(TocNode): + name = 'cellgroup' + + option_spec = { + 'caption': directives.unchanged, + } + + def add_target_and_index(self, name: str, sig: str, signode: addnodes.desc_signature) -> None: + if self.options.get('caption', ''): + super().add_target_and_index(name, sig, signode) + + def handle_signature( + self, + sig, + signode: addnodes.desc_signature + ) -> str: + signode['fullname'] = fullname = sig + caption = self.options.get("caption", fullname) + if caption: + signode['tocname'] = caption + signode += addnodes.desc_name(text=caption) + return fullname + class TagIndex(Index): """A custom directive that creates a tag matrix.""" @@ -368,6 +422,7 @@ class CellDomain(CommandDomain): directives = { 'def': CellNode, 'source': CellSourceNode, + 'group': CellGroupNode, } indices = { diff --git a/kernel/register.cc b/kernel/register.cc index 4e8e62741..bc49f4cb9 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -958,7 +958,8 @@ struct HelpPass : public Pass { json.entry("version", "Yosys internal cells"); json.entry("generator", yosys_version_str); - dict>> groups; + dict> groups; + dict> cells; // iterate over cells bool raise_error = false; @@ -966,59 +967,61 @@ struct HelpPass : public Pass { auto name = it.first.str(); if (cell_help_messages.contains(name)) { auto cell_help = cell_help_messages.get(name); - dict> *cell_group; if (groups.count(cell_help.group) != 0) { - cell_group = &groups.at(cell_help.group); + auto group_cells = &groups.at(cell_help.group); + group_cells->push_back(name); } else { - cell_group = new dict>(); - groups.emplace(cell_help.group, *cell_group); + auto group_cells = new vector(1, name); + groups.emplace(cell_help.group, *group_cells); } auto cell_pair = pair(cell_help, it.second); - cell_group->emplace(name, cell_pair); + cells.emplace(name, cell_pair); } else { log("ERROR: Missing cell help for cell '%s'.\n", name.c_str()); raise_error |= true; } } + for (auto &it : cell_help_messages.cell_help) { + if (cells.count(it.first) == 0) { + log_warning("Found cell model '%s' without matching cell type.\n", it.first.c_str()); + } + } // write to json - json.name("groups"); - json.begin_array(); + json.name("groups"); json.begin_object(); groups.sort(); for (auto &it : groups) { - json.begin_object(); - json.name("group"); json.value(it.first.c_str()); - json.name("cells"); json.begin_array(); - for (auto &it2 : it.second) { - auto ch = it2.second.first; - auto ct = it2.second.second; - json.begin_object(); - json.name("cell"); json.value(ch.name); - json.name("title"); json.value(ch.title); - json.name("ports"); json.value(ch.ports); - json.name("source"); json.value(ch.source); - json.name("desc"); json.value(ch.desc); - json.name("code"); json.value(ch.code); - json.name("inputs"); json.begin_array(); - for (auto &input : ct.inputs) - json.value(input.c_str()); - json.end_array(); - json.name("outputs"); json.begin_array(); - for (auto &output : ct.outputs) - json.value(output.c_str()); - json.end_array(); - dict prop_dict = { - {"is_evaluable", ct.is_evaluable}, - {"is_combinatorial", ct.is_combinatorial}, - {"is_synthesizable", ct.is_synthesizable}, - }; - json.name("properties"); json.value(prop_dict); - json.end_object(); - } - json.end_array(); + json.name(it.first.c_str()); json.value(it.second); + } + json.end_object(); + + json.name("cells"); json.begin_object(); + cells.sort(); + for (auto &it : cells) { + auto ch = it.second.first; + auto ct = it.second.second; + json.name(ch.name.c_str()); json.begin_object(); + json.name("title"); json.value(ch.title); + json.name("ports"); json.value(ch.ports); + json.name("source"); json.value(ch.source); + json.name("desc"); json.value(ch.desc); + json.name("code"); json.value(ch.code); + vector inputs, outputs; + for (auto &input : ct.inputs) + inputs.push_back(input.str()); + json.name("inputs"); json.value(inputs); + for (auto &output : ct.outputs) + outputs.push_back(output.str()); + json.name("outputs"); json.value(outputs); + dict prop_dict = { + {"is_evaluable", ct.is_evaluable}, + {"is_combinatorial", ct.is_combinatorial}, + {"is_synthesizable", ct.is_synthesizable}, + }; + json.name("properties"); json.value(prop_dict); json.end_object(); } - json.end_array(); + json.end_object(); json.end_object(); return raise_error; From c66252931612020d22258b02091bcff6f1e6b095 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 27 May 2024 12:31:42 +1200 Subject: [PATCH 054/496] Docs: Move binary operators to cell appendix Add binary group tag to relevant cells. Remove content from `cell_library.rst` that is already moved. --- docs/source/cell/word_binary.rst | 91 +++++++++++ docs/source/cell_word.rst | 13 ++ .../yosys_internals/formats/cell_library.rst | 151 ------------------ techlibs/common/simlib.v | 30 +++- 4 files changed, 133 insertions(+), 152 deletions(-) create mode 100644 docs/source/cell/word_binary.rst diff --git a/docs/source/cell/word_binary.rst b/docs/source/cell/word_binary.rst new file mode 100644 index 000000000..47a847ee4 --- /dev/null +++ b/docs/source/cell/word_binary.rst @@ -0,0 +1,91 @@ +.. role:: verilog(code) + :language: Verilog + +Binary operators +~~~~~~~~~~~~~~~~ + +All binary RTL cells have two input ports ``A`` and ``B`` and one output port +``Y``. They also have the following parameters: + +``A_SIGNED`` + Set to a non-zero value if the input ``A`` is signed and therefore should be + sign-extended when needed. + +``A_WIDTH`` + The width of the input port ``A``. + +``B_SIGNED`` + Set to a non-zero value if the input ``B`` is signed and therefore should be + sign-extended when needed. + +``B_WIDTH`` + The width of the input port ``B``. + +``Y_WIDTH`` + The width of the output port ``Y``. + +.. table:: Cell types for binary operators with their corresponding Verilog expressions. + + ======================= =============== ======================= =========== + Verilog Cell Type Verilog Cell Type + ======================= =============== ======================= =========== + :verilog:`Y = A & B` `$and` :verilog:`Y = A ** B` `$pow` + :verilog:`Y = A | B` `$or` :verilog:`Y = A < B` `$lt` + :verilog:`Y = A ^ B` `$xor` :verilog:`Y = A <= B` `$le` + :verilog:`Y = A ~^ B` `$xnor` :verilog:`Y = A == B` `$eq` + :verilog:`Y = A << B` `$shl` :verilog:`Y = A != B` `$ne` + :verilog:`Y = A >> B` `$shr` :verilog:`Y = A >= B` `$ge` + :verilog:`Y = A <<< B` `$sshl` :verilog:`Y = A > B` `$gt` + :verilog:`Y = A >>> B` `$sshr` :verilog:`Y = A + B` `$add` + :verilog:`Y = A && B` `$logic_and` :verilog:`Y = A - B` `$sub` + :verilog:`Y = A || B` `$logic_or` :verilog:`Y = A * B` `$mul` + :verilog:`Y = A === B` `$eqx` :verilog:`Y = A / B` `$div` + :verilog:`Y = A !== B` `$nex` :verilog:`Y = A % B` `$mod` + ``N/A`` `$shift` ``N/A`` `$divfloor` + ``N/A`` `$shiftx` ``N/A`` `$modfloor` + ======================= =============== ======================= =========== + +The `$shl` and `$shr` cells implement logical shifts, whereas the `$sshl` and +`$sshr` cells implement arithmetic shifts. The `$shl` and `$sshl` cells +implement the same operation. All four of these cells interpret the second +operand as unsigned, and require ``B_SIGNED`` to be zero. + +Two additional shift operator cells are available that do not directly +correspond to any operator in Verilog, `$shift` and `$shiftx`. The `$shift` cell +performs a right logical shift if the second operand is positive (or unsigned), +and a left logical shift if it is negative. The `$shiftx` cell performs the same +operation as the `$shift` cell, but the vacated bit positions are filled with +undef (x) bits, and corresponds to the Verilog indexed part-select expression. + +For the binary cells that output a logical value (`$logic_and`, `$logic_or`, +`$eqx`, `$nex`, `$lt`, `$le`, `$eq`, `$ne`, `$ge`, `$gt`), when the ``Y_WIDTH`` +parameter is greater than 1, the output is zero-extended, and only the least +significant bit varies. + +Division and modulo cells are available in two rounding modes. The original +`$div` and `$mod` cells are based on truncating division, and correspond to the +semantics of the verilog ``/`` and ``%`` operators. The `$divfloor` and +`$modfloor` cells represent flooring division and flooring modulo, the latter of +which is also known as "remainder" in several languages. See the following table +for a side-by-side comparison between the different semantics. + +.. table:: Comparison between different rounding modes for division and modulo cells. + + +-----------+--------+-----------+-----------+-----------+-----------+ + | Division | Result | Truncating | Flooring | + +-----------+--------+-----------+-----------+-----------+-----------+ + | | | $div | $mod | $divfloor | $modfloor | + +===========+========+===========+===========+===========+===========+ + | -10 / 3 | -3.3 | -3 | -1 | -4 | 2 | + +-----------+--------+-----------+-----------+-----------+-----------+ + | 10 / -3 | -3.3 | -3 | 1 | -4 | -2 | + +-----------+--------+-----------+-----------+-----------+-----------+ + | -10 / -3 | 3.3 | 3 | -1 | 3 | -1 | + +-----------+--------+-----------+-----------+-----------+-----------+ + | 10 / 3 | 3.3 | 3 | 1 | 3 | 1 | + +-----------+--------+-----------+-----------+-----------+-----------+ + +.. autocellgroup:: binary + :members: + :source: + :linenos: diff --git a/docs/source/cell_word.rst b/docs/source/cell_word.rst index 9b7811324..c23a4e1b1 100644 --- a/docs/source/cell_word.rst +++ b/docs/source/cell_word.rst @@ -1,9 +1,22 @@ Word-level cells ---------------- +Most of the RTL cells closely resemble the operators available in HDLs such as +Verilog or VHDL. Therefore Verilog operators are used in the following sections +to define the behaviour of the RTL cells. + +Note that all RTL cells have parameters indicating the size of inputs and +outputs. When passes modify RTL cells they must always keep the values of these +parameters in sync with the size of the signals connected to the inputs and +outputs. + +Simulation models for the RTL cells can be found in the file +:file:`techlibs/common/simlib.v` in the Yosys source tree. + .. toctree:: :maxdepth: 2 :glob: /cell/word_unary + /cell/word_binary /cell/word_other diff --git a/docs/source/yosys_internals/formats/cell_library.rst b/docs/source/yosys_internals/formats/cell_library.rst index c17976319..73dbc4e69 100644 --- a/docs/source/yosys_internals/formats/cell_library.rst +++ b/docs/source/yosys_internals/formats/cell_library.rst @@ -13,8 +13,6 @@ Most of the passes in Yosys operate on netlists, i.e. they only care about the chapter discusses the cell types used by Yosys to represent a behavioural design internally. -.. TODO:: is this chapter split preserved - This chapter is split in two parts. In the first part the internal RTL cells are covered. These cells are used to represent the design on a coarse grain level. Like in the original HDL code on this level the cells operate on vectors of @@ -23,155 +21,6 @@ gate cells are covered. These cells are used to represent the design on a fine-grain gate-level. All cells from this category operate on single bit signals. -RTL cells ---------- - -Most of the RTL cells closely resemble the operators available in HDLs such as -Verilog or VHDL. Therefore Verilog operators are used in the following sections -to define the behaviour of the RTL cells. - -Note that all RTL cells have parameters indicating the size of inputs and -outputs. When passes modify RTL cells they must always keep the values of these -parameters in sync with the size of the signals connected to the inputs and -outputs. - -Simulation models for the RTL cells can be found in the file -:file:`techlibs/common/simlib.v` in the Yosys source tree. - -Unary operators -~~~~~~~~~~~~~~~ - -All unary RTL cells have one input port ``\A`` and one output port ``\Y``. They -also have the following parameters: - -``\A_SIGNED`` - Set to a non-zero value if the input ``\A`` is signed and therefore should be - sign-extended when needed. - -``\A_WIDTH`` - The width of the input port ``\A``. - -``\Y_WIDTH`` - The width of the output port ``\Y``. - -:numref:`tab:CellLib_unary` lists all cells for unary RTL operators. - -.. table:: Cell types for unary operators with their corresponding Verilog expressions. - :name: tab:CellLib_unary - - ================== ============ - Verilog Cell Type - ================== ============ - :verilog:`Y = ~A` $not - :verilog:`Y = +A` $pos - :verilog:`Y = -A` $neg - :verilog:`Y = &A` $reduce_and - :verilog:`Y = |A` $reduce_or - :verilog:`Y = ^A` $reduce_xor - :verilog:`Y = ~^A` $reduce_xnor - :verilog:`Y = |A` $reduce_bool - :verilog:`Y = !A` $logic_not - ================== ============ - -For the unary cells that output a logical value (`$reduce_and`, `$reduce_or`, -`$reduce_xor`, `$reduce_xnor`, `$reduce_bool`, `$logic_not`), when the -``\Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and only -the least significant bit varies. - -Note that `$reduce_or` and `$reduce_bool` actually represent the same logic -function. But the HDL frontends generate them in different situations. A -`$reduce_or` cell is generated when the prefix ``|`` operator is being used. A -`$reduce_bool` cell is generated when a bit vector is used as a condition in an -``if``-statement or ``?:``-expression. - -Binary operators -~~~~~~~~~~~~~~~~ - -All binary RTL cells have two input ports ``\A`` and ``\B`` and one output port -``\Y``. They also have the following parameters: - -``\A_SIGNED`` - Set to a non-zero value if the input ``\A`` is signed and therefore should be - sign-extended when needed. - -``\A_WIDTH`` - The width of the input port ``\A``. - -``\B_SIGNED`` - Set to a non-zero value if the input ``\B`` is signed and therefore should be - sign-extended when needed. - -``\B_WIDTH`` - The width of the input port ``\B``. - -``\Y_WIDTH`` - The width of the output port ``\Y``. - -:numref:`tab:CellLib_binary` lists all cells for binary RTL operators. - -.. table:: Cell types for binary operators with their corresponding Verilog expressions. - :name: tab:CellLib_binary - - ======================= ============= ======================= ========= - Verilog Cell Type Verilog Cell Type - ======================= ============= ======================= ========= - :verilog:`Y = A & B` $and :verilog:`Y = A < B` $lt - :verilog:`Y = A | B` $or :verilog:`Y = A <= B` $le - :verilog:`Y = A ^ B` $xor :verilog:`Y = A == B` $eq - :verilog:`Y = A ~^ B` $xnor :verilog:`Y = A != B` $ne - :verilog:`Y = A << B` $shl :verilog:`Y = A >= B` $ge - :verilog:`Y = A >> B` $shr :verilog:`Y = A > B` $gt - :verilog:`Y = A <<< B` $sshl :verilog:`Y = A + B` $add - :verilog:`Y = A >>> B` $sshr :verilog:`Y = A - B` $sub - :verilog:`Y = A && B` $logic_and :verilog:`Y = A * B` $mul - :verilog:`Y = A || B` $logic_or :verilog:`Y = A / B` $div - :verilog:`Y = A === B` $eqx :verilog:`Y = A % B` $mod - :verilog:`Y = A !== B` $nex ``N/A`` $divfloor - :verilog:`Y = A ** B` $pow ``N/A`` $modfloor - ======================= ============= ======================= ========= - -The `$shl` and `$shr` cells implement logical shifts, whereas the `$sshl` and -`$sshr` cells implement arithmetic shifts. The `$shl` and `$sshl` cells -implement the same operation. All four of these cells interpret the second -operand as unsigned, and require ``\B_SIGNED`` to be zero. - -Two additional shift operator cells are available that do not directly -correspond to any operator in Verilog, `$shift` and `$shiftx`. The `$shift` cell -performs a right logical shift if the second operand is positive (or unsigned), -and a left logical shift if it is negative. The `$shiftx` cell performs the same -operation as the `$shift` cell, but the vacated bit positions are filled with -undef (x) bits, and corresponds to the Verilog indexed part-select expression. - -For the binary cells that output a logical value (`$logic_and`, `$logic_or`, -`$eqx`, `$nex`, `$lt`, `$le`, `$eq`, `$ne`, `$ge`, `$gt`), when the ``\Y_WIDTH`` -parameter is greater than 1, the output is zero-extended, and only the least -significant bit varies. - -Division and modulo cells are available in two rounding modes. The original -`$div` and `$mod` cells are based on truncating division, and correspond to the -semantics of the verilog ``/`` and ``%`` operators. The `$divfloor` and -`$modfloor` cells represent flooring division and flooring modulo, the latter of -which is also known as "remainder" in several languages. See -:numref:`tab:CellLib_divmod` for a side-by-side comparison between the different -semantics. - -.. table:: Comparison between different rounding modes for division and modulo cells. - :name: tab:CellLib_divmod - - +-----------+--------+-----------+-----------+-----------+-----------+ - | Division | Result | Truncating | Flooring | - +-----------+--------+-----------+-----------+-----------+-----------+ - | | | $div | $mod | $divfloor | $modfloor | - +===========+========+===========+===========+===========+===========+ - | -10 / 3 | -3.3 | -3 | -1 | -4 | 2 | - +-----------+--------+-----------+-----------+-----------+-----------+ - | 10 / -3 | -3.3 | -3 | 1 | -4 | -2 | - +-----------+--------+-----------+-----------+-----------+-----------+ - | -10 / -3 | 3.3 | 3 | -1 | 3 | -1 | - +-----------+--------+-----------+-----------+-----------+-----------+ - | 10 / 3 | 3.3 | 3 | 1 | 3 | 1 | - +-----------+--------+-----------+-----------+-----------+-----------+ - Multiplexers ~~~~~~~~~~~~ diff --git a/techlibs/common/simlib.v b/techlibs/common/simlib.v index b8a754825..fb294b53b 100644 --- a/techlibs/common/simlib.v +++ b/techlibs/common/simlib.v @@ -139,6 +139,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $and (A, B, Y) +//* group binary //- //- A bit-wise AND. This corresponds to the Verilog '&' operator. //- @@ -169,6 +170,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $or (A, B, Y) +//* group binary //- //- A bit-wise OR. This corresponds to the Verilog '|' operator. //- @@ -199,6 +201,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $xor (A, B, Y) +//* group binary //- //- A bit-wise XOR. This corresponds to the Verilog '^' operator. //- @@ -229,6 +232,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $xnor (A, B, Y) +//* group binary //- //- A bit-wise XNOR. This corresponds to the Verilog '~^' operator. //- @@ -400,6 +404,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $shl (A, B, Y) +//* group binary //- //- A logical shift-left operation. This corresponds to the Verilog '<<' operator. //- @@ -430,6 +435,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $shr (A, B, Y) +//* group binary //- //- A logical shift-right operation. This corresponds to the Verilog '>>' operator. //- @@ -460,6 +466,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $sshl (A, B, Y) +//* group binary //- //- An arithmatic shift-left operation. //- This corresponds to the Verilog '<<<' operator. @@ -491,6 +498,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $sshr (A, B, Y) +//* group binary //- //- An arithmatic shift-right operation. //- This corresponds to the Verilog '>>>' operator. @@ -518,6 +526,7 @@ endgenerate endmodule // -------------------------------------------------------- +//* group binary module \$shift (A, B, Y); @@ -550,6 +559,7 @@ endgenerate endmodule // -------------------------------------------------------- +//* group binary module \$shiftx (A, B, Y); @@ -691,6 +701,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $lt (A, B, Y) +//* group binary //- //- A less-than comparison between inputs 'A' and 'B'. //- This corresponds to the Verilog '<' operator. @@ -722,6 +733,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $le (A, B, Y) +//* group binary //- //- A less-than-or-equal-to comparison between inputs 'A' and 'B'. //- This corresponds to the Verilog '<=' operator. @@ -753,6 +765,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $eq (A, B, Y) +//* group binary //- //- An equality comparison between inputs 'A' and 'B'. //- This corresponds to the Verilog '==' operator. @@ -784,6 +797,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $ne (A, B, Y) +//* group binary //- //- An inequality comparison between inputs 'A' and 'B'. //- This corresponds to the Verilog '!=' operator. @@ -815,6 +829,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $eqx (A, B, Y) +//* group binary //- //- An exact equality comparison between inputs 'A' and 'B'. //- This corresponds to the Verilog '===' operator. @@ -848,6 +863,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $nex (A, B, Y) +//* group binary //- //- An exact inequality comparison between inputs 'A' and 'B'. //- This corresponds to the Verilog '!==' operator. @@ -881,6 +897,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $ge (A, B, Y) +//* group binary //- //- A greater-than-or-equal-to comparison between inputs 'A' and 'B'. //- This corresponds to the Verilog '>=' operator. @@ -912,6 +929,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $gt (A, B, Y) +//* group binary //- //- A greater-than comparison between inputs 'A' and 'B'. //- This corresponds to the Verilog '>' operator. @@ -943,6 +961,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $add (A, B, Y) +//* group binary //- //- Addition of inputs 'A' and 'B'. This corresponds to the Verilog '+' operator. //- @@ -973,6 +992,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $sub (A, B, Y) +//* group binary //- //- Subtraction between inputs 'A' and 'B'. //- This corresponds to the Verilog '-' operator. @@ -1004,6 +1024,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $mul (A, B, Y) +//* group binary //- //- Multiplication of inputs 'A' and 'B'. //- This corresponds to the Verilog '*' operator. @@ -1185,6 +1206,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $div (A, B, Y) +//* group binary //- //- Division with truncated result (rounded towards 0). //- @@ -1215,6 +1237,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $mod (A, B, Y) +//* group binary //- //- Modulo/remainder of division with truncated result (rounded towards 0). //- @@ -1247,6 +1270,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $divfloor (A, B, Y) +//* group binary //- //- Division with floored result (rounded towards negative infinity). //- @@ -1284,6 +1308,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $modfloor (A, B, Y) +//* group binary //- //- Modulo/remainder of division with floored result (rounded towards negative infinity). //- @@ -1324,6 +1349,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $pow (A, B, Y) +//* group binary //- //- Exponentiation of an input (Y = A ** B). //- This corresponds to the Verilog '**' operator. @@ -1362,10 +1388,10 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $logic_not (A, Y) +//* group unary //- //- A logical inverter. This corresponds to the Verilog unary prefix '!' operator. //- -//* group unary module \$logic_not (A, Y); parameter A_SIGNED = 0; @@ -1390,6 +1416,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $logic_and (A, B, Y) +//* group binary //- //- A logical AND. This corresponds to the Verilog '&&' operator. //- @@ -1420,6 +1447,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $logic_or (A, B, Y) +//* group binary //- //- A logical OR. This corresponds to the Verilog '||' operator. //- From 04b0ae540d3ea8bf09e4f7caf9bc7991a615f4ec Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 27 May 2024 12:47:47 +1200 Subject: [PATCH 055/496] cellref: Move default help message to register.cc Drop the default help message from rst while still displaying it on the command line. Fix command line formatting for older style help messages. --- kernel/register.cc | 10 ++++++---- techlibs/common/cellhelp.py | 4 +--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/kernel/register.cc b/kernel/register.cc index bc49f4cb9..ce6eb8018 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -1111,18 +1111,20 @@ struct HelpPass : public Pass { log("\n"); log("%s\n", help_cell.code.c_str()); } else { + log("\n %s %s\n\n", help_cell.name.c_str(), help_cell.ports.c_str()); if (help_cell.ver == "2" || help_cell.ver == "2a") { - log("\n %s %s\n\n", help_cell.name.c_str(), help_cell.ports.c_str()); - if (help_cell.title != "") log("%s\n", help_cell.title.c_str()); + if (help_cell.title != "") log("%s:\n", help_cell.title.c_str()); std::stringstream ss; ss << help_cell.desc; for (std::string line; std::getline(ss, line, '\n');) { if (line != "::") log("%s\n", line.c_str()); } - } else { + } else if (help_cell.desc.length()) { log("%s\n", help_cell.desc.c_str()); + } else { + log("No help message for this cell type found.\n"); } - log("Run 'help %s+' to display the Verilog model for this cell type.\n", args[1].c_str()); + log("\nRun 'help %s+' to display the Verilog model for this cell type.\n", args[1].c_str()); log("\n"); } } diff --git a/techlibs/common/cellhelp.py b/techlibs/common/cellhelp.py index 299b7affd..9aa3def93 100644 --- a/techlibs/common/cellhelp.py +++ b/techlibs/common/cellhelp.py @@ -84,9 +84,7 @@ for line in fileinput.input(): simcells_reparse(simHelper) # check help - if not simHelper.desc: - simHelper.desc.append("No help message for this cell type found.\n") - elif simHelper.ver == "1" and short_filename == "simlib.v" and simHelper.desc[1].startswith(' '): + if simHelper.desc and simHelper.ver == "1" and short_filename == "simlib.v" and simHelper.desc[1].startswith(' '): simHelper.desc.pop(1) # check group From 1374fc2e2b3ac0452b6e263a6afb8ea5ae011d07 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 27 May 2024 15:46:43 +1200 Subject: [PATCH 056/496] cellref: Deprecate cell_library.rst Most of the word/coarse level cells have an assigned group and individual page. The gate/fine level cells are all on one page. Fix links to `cell_library.rst`. --- docs/source/cell/word_arith.rst | 93 ++ docs/source/cell/word_debug.rst | 138 +++ docs/source/cell/word_formal.rst | 14 + docs/source/cell/word_fsm.rst | 9 + docs/source/cell/word_mem.rst | 281 +++++ docs/source/cell/word_mux.rst | 47 + docs/source/cell/word_other.rst | 5 - docs/source/cell/word_reg.rst | 124 ++ docs/source/cell/word_spec.rst | 9 + docs/source/cell_gate.rst | 389 ++++++ docs/source/cell_word.rst | 19 +- .../interactive_investigation.rst | 2 +- docs/source/using_yosys/synthesis/opt.rst | 8 +- .../yosys_internals/formats/cell_library.rst | 1086 ----------------- techlibs/common/simlib.v | 52 + 15 files changed, 1180 insertions(+), 1096 deletions(-) create mode 100644 docs/source/cell/word_arith.rst create mode 100644 docs/source/cell/word_debug.rst create mode 100644 docs/source/cell/word_formal.rst create mode 100644 docs/source/cell/word_fsm.rst create mode 100644 docs/source/cell/word_mem.rst create mode 100644 docs/source/cell/word_mux.rst delete mode 100644 docs/source/cell/word_other.rst create mode 100644 docs/source/cell/word_reg.rst create mode 100644 docs/source/cell/word_spec.rst delete mode 100644 docs/source/yosys_internals/formats/cell_library.rst diff --git a/docs/source/cell/word_arith.rst b/docs/source/cell/word_arith.rst new file mode 100644 index 000000000..38111a7d5 --- /dev/null +++ b/docs/source/cell/word_arith.rst @@ -0,0 +1,93 @@ +Coarse arithmetics +------------------ + +Multiply-accumulate +~~~~~~~~~~~~~~~~~~~ + +The `$macc` cell type represents a generalized multiply and accumulate +operation. The cell is purely combinational. It outputs the result of summing up +a sequence of products and other injected summands. + +.. code-block:: + + Y = 0 +- a0factor1 * a0factor2 +- a1factor1 * a1factor2 +- ... + + B[0] + B[1] + ... + +The A port consists of concatenated pairs of multiplier inputs ("factors"). A +zero length factor2 acts as a constant 1, turning factor1 into a simple summand. + +In this pseudocode, ``u(foo)`` means an unsigned int that's foo bits long. + +.. code-block:: + + struct A { + u(CONFIG.mul_info[0].factor1_len) a0factor1; + u(CONFIG.mul_info[0].factor2_len) a0factor2; + u(CONFIG.mul_info[1].factor1_len) a1factor1; + u(CONFIG.mul_info[1].factor2_len) a1factor2; + ... + }; + +The cell's ``CONFIG`` parameter determines the layout of cell port ``A``. The +CONFIG parameter carries the following information: + +.. code-block:: + + struct CONFIG { + u4 num_bits; + struct mul_info { + bool is_signed; + bool is_subtract; + u(num_bits) factor1_len; + u(num_bits) factor2_len; + }[num_ports]; + }; + +B is an array of concatenated 1-bit-wide unsigned integers to also be summed up. + +Arbitrary logic functions +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The `$lut` cell type implements a single-output LUT (lookup table). It +implements an arbitrary logic function with its ``\LUT`` parameter to map input +port ``\A`` to values of ``\Y`` output port values. In psuedocode: ``Y = +\LUT[A]``. ``\A`` has width set by parameter ``\WIDTH`` and ``\Y`` has a width +of 1. Every logic function with a single bit output has a unique `$lut` +representation. + +The `$sop` cell type implements a sum-of-products expression, also known as +disjunctive normal form (DNF). It implements an arbitrary logic function. Its +structure mimics a programmable logic array (PLA). Output port ``\Y`` is the sum +of products of the bits of the input port ``\A`` as defined by parameter +``\TABLE``. ``\A`` is ``\WIDTH`` bits wide. The number of products in the sum is +set by parameter ``\DEPTH``, and each product has two bits for each input bit - +for the presence of the unnegated and negated version of said input bit in the +product. Therefore the ``\TABLE`` parameter holds ``2 * \WIDTH * \DEPTH`` bits. + +For example: + +Let ``\WIDTH`` be 3. We would like to represent ``\Y =~\A[0] + \A[1]~\A[2]``. +There are 2 products to be summed, so ``\DEPTH`` shall be 2. + +.. code-block:: + + ~A[2]-----+ + A[2]----+| + ~A[1]---+|| + A[1]--+||| + ~A[0]-+|||| + A[0]+||||| + |||||| product formula + 010000 ~\A[0] + 001001 \A[1]~\A[2] + +So the value of ``\TABLE`` will become ``010000001001``. + +Any logic function with a single bit output can be represented with ``$sop`` but +may have variously minimized or ordered summands represented in the ``\TABLE`` +values. + +.. autocellgroup:: arith + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_debug.rst b/docs/source/cell/word_debug.rst new file mode 100644 index 000000000..92c753dbe --- /dev/null +++ b/docs/source/cell/word_debug.rst @@ -0,0 +1,138 @@ +.. role:: verilog(code) + :language: Verilog + +Debugging cells +--------------- + +The `$print` cell is used to log the values of signals, akin to (and +translatable to) the ``$display`` and ``$write`` family of tasks in Verilog. It +has the following parameters: + +``FORMAT`` + The internal format string. The syntax is described below. + +``ARGS_WIDTH`` + The width (in bits) of the signal on the ``ARGS`` port. + +``TRG_ENABLE`` + True if triggered on specific signals defined in ``TRG``; false if triggered + whenever ``ARGS`` or ``EN`` change and ``EN`` is 1. + +If ``TRG_ENABLE`` is true, the following parameters also apply: + +``TRG_WIDTH`` + The number of bits in the ``TRG`` port. + +``TRG_POLARITY`` + For each bit in ``TRG``, 1 if that signal is positive-edge triggered, 0 if + negative-edge triggered. + +``PRIORITY`` + When multiple `$print` or `$check` cells fire on the same trigger, they + execute in descending priority order. + +Ports: + +``TRG`` + The signals that control when this `$print` cell is triggered. + + If the width of this port is zero and ``TRG_ENABLE`` is true, the cell is + triggered during initial evaluation (time zero) only. + +``EN`` + Enable signal for the whole cell. + +``ARGS`` + The values to be displayed, in format string order. + +.. autocellgroup:: debug + :members: + :source: + :linenos: + +Format string syntax +~~~~~~~~~~~~~~~~~~~~ + +The format string syntax resembles Python f-strings. Regular text is passed +through unchanged until a format specifier is reached, starting with a ``{``. + +Format specifiers have the following syntax. Unless noted, all items are +required: + +``{`` + Denotes the start of the format specifier. + +size + Signal size in bits; this many bits are consumed from the ``ARGS`` port by + this specifier. + +``:`` + Separates the size from the remaining items. + +justify + ``>`` for right-justified, ``<`` for left-justified. + +padding + ``0`` for zero-padding, or a space for space-padding. + +width\ *?* + (optional) The number of characters wide to pad to. + +base + * ``b`` for base-2 integers (binary) + * ``o`` for base-8 integers (octal) + * ``d`` for base-10 integers (decimal) + * ``h`` for base-16 integers (hexadecimal) + * ``c`` for ASCII characters/strings + * ``t`` and ``r`` for simulation time (corresponding to :verilog:`$time` and + :verilog:`$realtime`) + +For integers, this item may follow: + +``+``\ *?* + (optional, decimals only) Include a leading plus for non-negative numbers. + This can assist with symmetry with negatives in tabulated output. + +signedness + ``u`` for unsigned, ``s`` for signed. This distinction is only respected + when rendering decimals. + +ASCII characters/strings have no special options, but the signal size must be +divisible by 8. + +For simulation time, the signal size must be zero. + +Finally: + +``}`` + Denotes the end of the format specifier. + +Some example format specifiers: + ++ ``{8:>02hu}`` - 8-bit unsigned integer rendered as hexadecimal, + right-justified, zero-padded to 2 characters wide. ++ ``{32:< 15d+s}`` - 32-bit signed integer rendered as decimal, left-justified, + space-padded to 15 characters wide, positive values prefixed with ``+``. ++ ``{16:< 10hu}`` - 16-bit unsigned integer rendered as hexadecimal, + left-justified, space-padded to 10 characters wide. ++ ``{0:>010t}`` - simulation time, right-justified, zero-padded to 10 characters + wide. + +To include literal ``{`` and ``}`` characters in your format string, use ``{{`` +and ``}}`` respectively. + +It is an error for a format string to consume more or less bits from ``ARGS`` +than the port width. + +Values are never truncated, regardless of the specified width. + +Note that further restrictions on allowable combinations of options may apply +depending on the backend used. + +For example, Verilog does not have a format specifier that allows zero-padding a +string (i.e. more than 1 ASCII character), though zero-padding a single +character is permitted. + +Thus, while the RTLIL format specifier ``{8:>02c}`` translates to ``%02c``, +``{16:>02c}`` cannot be represented in Verilog and will fail to emit. In this +case, ``{16:> 02c}`` must be used, which translates to ``%2s``. diff --git a/docs/source/cell/word_formal.rst b/docs/source/cell/word_formal.rst new file mode 100644 index 000000000..81bab8988 --- /dev/null +++ b/docs/source/cell/word_formal.rst @@ -0,0 +1,14 @@ +Formal verification cells +------------------------- + +.. TODO:: Describe formal cells + + `$check`, `$assert`, `$assume`, `$live`, `$fair`, `$cover`, `$equiv`, + `$initstate`, `$anyconst`, `$anyseq`, `$anyinit`, `$allconst`, and `$allseq`. + + Also `$ff` and `$_FF_` cells. + +.. autocellgroup:: formal + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_fsm.rst b/docs/source/cell/word_fsm.rst new file mode 100644 index 000000000..943904b2b --- /dev/null +++ b/docs/source/cell/word_fsm.rst @@ -0,0 +1,9 @@ +Finite state machines +--------------------- + +.. TODO:: Describe `$fsm` cell + +.. autocellgroup:: fsm + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_mem.rst b/docs/source/cell/word_mem.rst new file mode 100644 index 000000000..434ddea3e --- /dev/null +++ b/docs/source/cell/word_mem.rst @@ -0,0 +1,281 @@ +.. role:: verilog(code) + :language: Verilog + +.. _sec:memcells: + +Memories +~~~~~~~~ + +Memories are either represented using ``RTLIL::Memory`` objects, `$memrd_v2`, +`$memwr_v2`, and `$meminit_v2` cells, or by `$mem_v2` cells alone. + +In the first alternative the ``RTLIL::Memory`` objects hold the general metadata +for the memory (bit width, size in number of words, etc.) and for each port a +`$memrd_v2` (read port) or `$memwr_v2` (write port) cell is created. Having +individual cells for read and write ports has the advantage that they can be +consolidated using resource sharing passes. In some cases this drastically +reduces the number of required ports on the memory cell. In this alternative, +memory initialization data is represented by `$meminit_v2` cells, which allow +delaying constant folding for initialization addresses and data until after the +frontend finishes. + +The `$memrd_v2` cells have a clock input ``CLK``, an enable input ``EN``, an +address input ``ADDR``, a data output ``DATA``, an asynchronous reset input +``ARST``, and a synchronous reset input ``SRST``. They also have the following +parameters: + +``MEMID`` + The name of the ``RTLIL::Memory`` object that is associated with this read + port. + +``ABITS`` + The number of address bits (width of the ``ADDR`` input port). + +``WIDTH`` + The number of data bits (width of the ``DATA`` output port). Note that this + may be a power-of-two multiple of the underlying memory's width -- such ports + are called wide ports and access an aligned group of cells at once. In this + case, the corresponding low bits of ``ADDR`` must be tied to 0. + +``CLK_ENABLE`` + When this parameter is non-zero, the clock is used. Otherwise this read port + is asynchronous and the ``CLK`` input is not used. + +``CLK_POLARITY`` + Clock is active on the positive edge if this parameter has the value ``1'b1`` + and on the negative edge if this parameter is ``1'b0``. + +``TRANSPARENCY_MASK`` + This parameter is a bitmask of write ports that this read port is transparent + with. The bits of this parameter are indexed by the write port's ``PORTID`` + parameter. Transparency can only be enabled between synchronous ports sharing + a clock domain. When transparency is enabled for a given port pair, a read + and write to the same address in the same cycle will return the new value. + Otherwise the old value is returned. + +``COLLISION_X_MASK`` + This parameter is a bitmask of write ports that have undefined collision + behavior with this port. The bits of this parameter are indexed by the write + port's ``PORTID`` parameter. This behavior can only be enabled between + synchronous ports sharing a clock domain. When undefined collision is enabled + for a given port pair, a read and write to the same address in the same cycle + will return the undefined (all-X) value.This option is exclusive (for a given + port pair) with the transparency option. + +``ARST_VALUE`` + Whenever the ``ARST`` input is asserted, the data output will be reset to + this value. Only used for synchronous ports. + +``SRST_VALUE`` + Whenever the ``SRST`` input is synchronously asserted, the data output will + be reset to this value. Only used for synchronous ports. + +``INIT_VALUE`` + The initial value of the data output, for synchronous ports. + +``CE_OVER_SRST`` + If this parameter is non-zero, the ``SRST`` input is only recognized when + ``EN`` is true. Otherwise, ``SRST`` is recognized regardless of ``EN``. + +The `$memwr_v2` cells have a clock input ``CLK``, an enable input ``EN`` (one +enable bit for each data bit), an address input ``ADDR`` and a data input +``DATA``. They also have the following parameters: + +``MEMID`` + The name of the ``RTLIL::Memory`` object that is associated with this write + port. + +``ABITS`` + The number of address bits (width of the ``ADDR`` input port). + +``WIDTH`` + The number of data bits (width of the ``DATA`` output port). Like with + `$memrd_v2` cells, the width is allowed to be any power-of-two multiple of + memory width, with the corresponding restriction on address. + +``CLK_ENABLE`` + When this parameter is non-zero, the clock is used. Otherwise this write port + is asynchronous and the ``CLK`` input is not used. + +``CLK_POLARITY`` + Clock is active on positive edge if this parameter has the value ``1'b1`` and + on the negative edge if this parameter is ``1'b0``. + +``PORTID`` + An identifier for this write port, used to index write port bit mask + parameters. + +``PRIORITY_MASK`` + This parameter is a bitmask of write ports that this write port has priority + over in case of writing to the same address. The bits of this parameter are + indexed by the other write port's ``PORTID`` parameter. Write ports can only + have priority over write ports with lower port ID. When two ports write to + the same address and neither has priority over the other, the result is + undefined. Priority can only be set between two synchronous ports sharing + the same clock domain. + +The `$meminit_v2` cells have an address input ``ADDR``, a data input ``DATA``, +with the width of the ``DATA`` port equal to ``WIDTH`` parameter times ``WORDS`` +parameter, and a bit enable mask input ``EN`` with width equal to ``WIDTH`` +parameter. All three of the inputs must resolve to a constant for synthesis to +succeed. + +``MEMID`` + The name of the ``RTLIL::Memory`` object that is associated with this + initialization cell. + +``ABITS`` + The number of address bits (width of the ``ADDR`` input port). + +``WIDTH`` + The number of data bits per memory location. + +``WORDS`` + The number of consecutive memory locations initialized by this cell. + +``PRIORITY`` + The cell with the higher integer value in this parameter wins an + initialization conflict. + +The HDL frontend models a memory using ``RTLIL::Memory`` objects and +asynchronous `$memrd_v2` and `$memwr_v2` cells. The `memory` pass (i.e. its +various sub-passes) migrates `$dff` cells into the `$memrd_v2` and `$memwr_v2` +cells making them synchronous, then converts them to a single `$mem_v2` cell and +(optionally) maps this cell type to `$dff` cells for the individual words and +multiplexer-based address decoders for the read and write interfaces. When the +last step is disabled or not possible, a `$mem_v2` cell is left in the design. + +The `$mem_v2` cell provides the following parameters: + +``MEMID`` + The name of the original ``RTLIL::Memory`` object that became this `$mem_v2` + cell. + +``SIZE`` + The number of words in the memory. + +``ABITS`` + The number of address bits. + +``WIDTH`` + The number of data bits per word. + +``INIT`` + The initial memory contents. + +``RD_PORTS`` + The number of read ports on this memory cell. + +``RD_WIDE_CONTINUATION`` + This parameter is ``RD_PORTS`` bits wide, containing a bitmask of "wide + continuation" read ports. Such ports are used to represent the extra data + bits of wide ports in the combined cell, and must have all control signals + identical with the preceding port, except for address, which must have the + proper sub-cell address encoded in the low bits. + +``RD_CLK_ENABLE`` + This parameter is ``RD_PORTS`` bits wide, containing a clock enable bit for + each read port. + +``RD_CLK_POLARITY`` + This parameter is ``RD_PORTS`` bits wide, containing a clock polarity bit for + each read port. + +``RD_TRANSPARENCY_MASK`` + This parameter is ``RD_PORTS*WR_PORTS`` bits wide, containing a concatenation + of all ``TRANSPARENCY_MASK`` values of the original `$memrd_v2` cells. + +``RD_COLLISION_X_MASK`` + This parameter is ``RD_PORTS*WR_PORTS`` bits wide, containing a concatenation + of all ``COLLISION_X_MASK`` values of the original `$memrd_v2` cells. + +``RD_CE_OVER_SRST`` + This parameter is ``RD_PORTS`` bits wide, determining relative synchronous + reset and enable priority for each read port. + +``RD_INIT_VALUE`` + This parameter is ``RD_PORTS*WIDTH`` bits wide, containing the initial value + for each synchronous read port. + +``RD_ARST_VALUE`` + This parameter is ``RD_PORTS*WIDTH`` bits wide, containing the asynchronous + reset value for each synchronous read port. + +``RD_SRST_VALUE`` + This parameter is ``RD_PORTS*WIDTH`` bits wide, containing the synchronous + reset value for each synchronous read port. + +``WR_PORTS`` + The number of write ports on this memory cell. + +``WR_WIDE_CONTINUATION`` + This parameter is ``WR_PORTS`` bits wide, containing a bitmask of "wide + continuation" write ports. + +``WR_CLK_ENABLE`` + This parameter is ``WR_PORTS`` bits wide, containing a clock enable bit for + each write port. + +``WR_CLK_POLARITY`` + This parameter is ``WR_PORTS`` bits wide, containing a clock polarity bit for + each write port. + +``WR_PRIORITY_MASK`` + This parameter is ``WR_PORTS*WR_PORTS`` bits wide, containing a concatenation + of all ``PRIORITY_MASK`` values of the original `$memwr_v2` cells. + +The `$mem_v2` cell has the following ports: + +``RD_CLK`` + This input is ``RD_PORTS`` bits wide, containing all clock signals for the + read ports. + +``RD_EN`` + This input is ``RD_PORTS`` bits wide, containing all enable signals for the + read ports. + +``RD_ADDR`` + This input is ``RD_PORTS*ABITS`` bits wide, containing all address signals + for the read ports. + +``RD_DATA`` + This output is ``RD_PORTS*WIDTH`` bits wide, containing all data signals for + the read ports. + +``RD_ARST`` + This input is ``RD_PORTS`` bits wide, containing all asynchronous reset + signals for the read ports. + +``RD_SRST`` + This input is ``RD_PORTS`` bits wide, containing all synchronous reset + signals for the read ports. + +``WR_CLK`` + This input is ``WR_PORTS`` bits wide, containing all clock signals for the + write ports. + +``WR_EN`` + This input is ``WR_PORTS*WIDTH`` bits wide, containing all enable signals for + the write ports. + +``WR_ADDR`` + This input is ``WR_PORTS*ABITS`` bits wide, containing all address signals + for the write ports. + +``WR_DATA`` + This input is ``WR_PORTS*WIDTH`` bits wide, containing all data signals for + the write ports. + +The `memory_collect` pass can be used to convert discrete `$memrd_v2`, +`$memwr_v2`, and `$meminit_v2` cells belonging to the same memory to a single +`$mem_v2` cell, whereas the `memory_unpack` pass performs the inverse operation. +The `memory_dff` pass can combine asynchronous memory ports that are fed by or +feeding registers into synchronous memory ports. The `memory_bram` pass can be +used to recognize `$mem_v2` cells that can be implemented with a block RAM +resource on an FPGA. The `memory_map` pass can be used to implement `$mem_v2` +cells as basic logic: word-wide DFFs and address decoders. + +.. autocellgroup:: mem + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_mux.rst b/docs/source/cell/word_mux.rst new file mode 100644 index 000000000..3eca310f3 --- /dev/null +++ b/docs/source/cell/word_mux.rst @@ -0,0 +1,47 @@ +.. role:: verilog(code) + :language: Verilog + +Multiplexers +------------ + +Multiplexers are generated by the Verilog HDL frontend for ``?:``-expressions. +Multiplexers are also generated by the proc pass to map the decision trees from +RTLIL::Process objects to logic. + +The simplest multiplexer cell type is `$mux`. Cells of this type have a +``WITDH`` parameter and data inputs ``A`` and ``B`` and a data output ``Y``, all +of the specified width. This cell also has a single bit control input ``S``. If +``S`` is 0 the value from the input ``A`` is sent to the output, if it is 1 the +value from the ``B`` input is sent to the output. So the `$mux` cell implements +the function :verilog:`Y = S ? B : A`. + +The `$pmux` cell is used to multiplex between many inputs using a one-hot select +signal. Cells of this type have a ``WIDTH`` and a ``S_WIDTH`` parameter and +inputs ``A``, ``B``, and ``S`` and an output ``Y``. The ``S`` input is +``S_WIDTH`` bits wide. The ``A`` input and the output are both ``WIDTH`` bits +wide and the ``B`` input is ``WIDTH*S_WIDTH`` bits wide. When all bits of ``S`` +are zero, the value from ``A`` input is sent to the output. If the :math:`n`\ +'th bit from ``S`` is set, the value :math:`n`\ 'th ``WIDTH`` bits wide slice of +the ``B`` input is sent to the output. When more than one bit from ``S`` is set +the output is undefined. Cells of this type are used to model "parallel cases" +(defined by using the ``parallel_case`` attribute or detected by an +optimization). + +The `$tribuf` cell is used to implement tristate logic. Cells of this type have +a ``WIDTH`` parameter and inputs ``A`` and ``EN`` and an output ``Y``. The ``A`` +input and ``Y`` output are ``WIDTH`` bits wide, and the ``EN`` input is one bit +wide. When ``EN`` is 0, the output is not driven. When ``EN`` is 1, the value +from ``A`` input is sent to the ``Y`` output. Therefore, the `$tribuf` cell +implements the function :verilog:`Y = EN ? A : 'bz`. + +Behavioural code with cascaded if-then-else- and case-statements usually results +in trees of multiplexer cells. Many passes (from various optimizations to FSM +extraction) heavily depend on these multiplexer trees to understand dependencies +between signals. Therefore optimizations should not break these multiplexer +trees (e.g. by replacing a multiplexer between a calculated signal and a +constant zero with an `$and` gate). + +.. autocellgroup:: mux + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_other.rst b/docs/source/cell/word_other.rst deleted file mode 100644 index 9e5ac2a37..000000000 --- a/docs/source/cell/word_other.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. autocellgroup:: word_other - :caption: Other word-level cells - :members: - :source: - :linenos: diff --git a/docs/source/cell/word_reg.rst b/docs/source/cell/word_reg.rst new file mode 100644 index 000000000..25c82b8e6 --- /dev/null +++ b/docs/source/cell/word_reg.rst @@ -0,0 +1,124 @@ +.. role:: verilog(code) + :language: Verilog + +Registers +--------- + +SR-type latches are represented by `$sr` cells. These cells have input ports +``SET`` and ``CLR`` and an output port ``Q``. They have the following +parameters: + +``WIDTH`` + The width of inputs ``SET`` and ``CLR`` and output ``Q``. + +``SET_POLARITY`` + The set input bits are active-high if this parameter has the value ``1'b1`` + and active-low if this parameter is ``1'b0``. + +``CLR_POLARITY`` + The reset input bits are active-high if this parameter has the value ``1'b1`` + and active-low if this parameter is ``1'b0``. + +Both set and reset inputs have separate bits for every output bit. When both the +set and reset inputs of an `$sr` cell are active for a given bit index, the +reset input takes precedence. + +D-type flip-flops are represented by `$dff` cells. These cells have a clock port +``CLK``, an input port ``D`` and an output port ``Q``. The following parameters +are available for `$dff` cells: + +``WIDTH`` + The width of input ``D`` and output ``Q``. + +``CLK_POLARITY`` + Clock is active on the positive edge if this parameter has the value ``1'b1`` + and on the negative edge if this parameter is ``1'b0``. + +D-type flip-flops with asynchronous reset are represented by `$adff` cells. As +the `$dff` cells they have ``CLK``, ``D`` and ``Q`` ports. In addition they also +have a single-bit ``ARST`` input port for the reset pin and the following +additional two parameters: + +``ARST_POLARITY`` + The asynchronous reset is active-high if this parameter has the value + ``1'b1`` and active-low if this parameter is ``1'b0``. + +``ARST_VALUE`` + The state of ``Q`` will be set to this value when the reset is active. + +Usually these cells are generated by the `proc` pass using the information in +the designs RTLIL::Process objects. + +D-type flip-flops with synchronous reset are represented by `$sdff` cells. As +the `$dff` cells they have ``CLK``, ``D`` and ``Q`` ports. In addition they also +have a single-bit ``SRST`` input port for the reset pin and the following +additional two parameters: + +``SRST_POLARITY`` + The synchronous reset is active-high if this parameter has the value ``1'b1`` + and active-low if this parameter is ``1'b0``. + +``SRST_VALUE`` + The state of ``Q`` will be set to this value when the reset is active. + +Note that the `$adff` and `$sdff` cells can only be used when the reset value is +constant. + +D-type flip-flops with asynchronous load are represented by `$aldff` cells. As +the `$dff` cells they have ``CLK``, ``D`` and ``Q`` ports. In addition they also +have a single-bit ``ALOAD`` input port for the async load enable pin, a ``AD`` +input port with the same width as data for the async load data, and the +following additional parameter: + +``ALOAD_POLARITY`` + The asynchronous load is active-high if this parameter has the value ``1'b1`` + and active-low if this parameter is ``1'b0``. + +D-type flip-flops with asynchronous set and reset are represented by `$dffsr` +cells. As the `$dff` cells they have ``CLK``, ``D`` and ``Q`` ports. In addition +they also have multi-bit ``SET`` and ``CLR`` input ports and the corresponding +polarity parameters, like `$sr` cells. + +D-type flip-flops with enable are represented by `$dffe`, `$adffe`, `$aldffe`, +`$dffsre`, `$sdffe`, and `$sdffce` cells, which are enhanced variants of `$dff`, +`$adff`, `$aldff`, `$dffsr`, `$sdff` (with reset over enable) and `$sdff` (with +enable over reset) cells, respectively. They have the same ports and parameters +as their base cell. In addition they also have a single-bit ``EN`` input port +for the enable pin and the following parameter: + +``EN_POLARITY`` + The enable input is active-high if this parameter has the value ``1'b1`` and + active-low if this parameter is ``1'b0``. + +D-type latches are represented by `$dlatch` cells. These cells have an enable +port ``EN``, an input port ``D``, and an output port ``Q``. The following +parameters are available for `$dlatch` cells: + +``WIDTH`` + The width of input ``D`` and output ``Q``. + +``EN_POLARITY`` + The enable input is active-high if this parameter has the value ``1'b1`` and + active-low if this parameter is ``1'b0``. + +The latch is transparent when the ``EN`` input is active. + +D-type latches with reset are represented by `$adlatch` cells. In addition to +`$dlatch` ports and parameters, they also have a single-bit ``ARST`` input port +for the reset pin and the following additional parameters: + +``ARST_POLARITY`` + The asynchronous reset is active-high if this parameter has the value + ``1'b1`` and active-low if this parameter is ``1'b0``. + +``ARST_VALUE`` + The state of ``Q`` will be set to this value when the reset is active. + +D-type latches with set and reset are represented by `$dlatchsr` cells. In +addition to `$dlatch` ports and parameters, they also have multi-bit ``SET`` and +``CLR`` input ports and the corresponding polarity parameters, like `$sr` cells. + +.. autocellgroup:: reg + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_spec.rst b/docs/source/cell/word_spec.rst new file mode 100644 index 000000000..33ef40774 --- /dev/null +++ b/docs/source/cell/word_spec.rst @@ -0,0 +1,9 @@ +Specify rules +------------- + +.. TODO:: `$specify2`, `$specify3`, and `$specrule` cells. + +.. autocellgroup:: spec + :members: + :source: + :linenos: diff --git a/docs/source/cell_gate.rst b/docs/source/cell_gate.rst index 0e977c587..4262fe210 100644 --- a/docs/source/cell_gate.rst +++ b/docs/source/cell_gate.rst @@ -1,6 +1,395 @@ +.. role:: verilog(code) + :language: Verilog + +.. _sec:celllib_gates: + Gate-level cells ---------------- +.. todo:: Split gate-level cells into subpages + + Consider also checking wording to be less academic and consistent. + +For gate level logic networks, fixed function single bit cells are used that do +not provide any parameters. + +Simulation models for these cells can be found in the file +techlibs/common/simcells.v in the Yosys source tree. + +.. table:: Cell types for gate level logic networks (main list) + :name: tab:CellLib_gates + + ======================================= ============= + Verilog Cell Type + ======================================= ============= + :verilog:`Y = A` `$_BUF_` + :verilog:`Y = ~A` `$_NOT_` + :verilog:`Y = A & B` `$_AND_` + :verilog:`Y = ~(A & B)` `$_NAND_` + :verilog:`Y = A & ~B` `$_ANDNOT_` + :verilog:`Y = A | B` `$_OR_` + :verilog:`Y = ~(A | B)` `$_NOR_` + :verilog:`Y = A | ~B` `$_ORNOT_` + :verilog:`Y = A ^ B` `$_XOR_` + :verilog:`Y = ~(A ^ B)` `$_XNOR_` + :verilog:`Y = ~((A & B) | C)` `$_AOI3_` + :verilog:`Y = ~((A | B) & C)` `$_OAI3_` + :verilog:`Y = ~((A & B) | (C & D))` `$_AOI4_` + :verilog:`Y = ~((A | B) & (C | D))` `$_OAI4_` + :verilog:`Y = S ? B : A` `$_MUX_` + :verilog:`Y = ~(S ? B : A)` `$_NMUX_` + (see below) `$_MUX4_` + (see below) `$_MUX8_` + (see below) `$_MUX16_` + :verilog:`Y = EN ? A : 1'bz` `$_TBUF_` + :verilog:`always @(negedge C) Q <= D` `$_DFF_N_` + :verilog:`always @(posedge C) Q <= D` `$_DFF_P_` + :verilog:`always @* if (!E) Q <= D` `$_DLATCH_N_` + :verilog:`always @* if (E) Q <= D` `$_DLATCH_P_` + ======================================= ============= + +.. table:: Cell types for gate level logic networks (FFs with reset) + :name: tab:CellLib_gates_adff + + ================== ============== ============== =========================== + :math:`ClkEdge` :math:`RstLvl` :math:`RstVal` Cell Type + ================== ============== ============== =========================== + :verilog:`negedge` ``0`` ``0`` `$_DFF_NN0_`, `$_SDFF_NN0_` + :verilog:`negedge` ``0`` ``1`` `$_DFF_NN1_`, `$_SDFF_NN1_` + :verilog:`negedge` ``1`` ``0`` `$_DFF_NP0_`, `$_SDFF_NP0_` + :verilog:`negedge` ``1`` ``1`` `$_DFF_NP1_`, `$_SDFF_NP1_` + :verilog:`posedge` ``0`` ``0`` `$_DFF_PN0_`, `$_SDFF_PN0_` + :verilog:`posedge` ``0`` ``1`` `$_DFF_PN1_`, `$_SDFF_PN1_` + :verilog:`posedge` ``1`` ``0`` `$_DFF_PP0_`, `$_SDFF_PP0_` + :verilog:`posedge` ``1`` ``1`` `$_DFF_PP1_`, `$_SDFF_PP1_` + ================== ============== ============== =========================== + + +.. table:: Cell types for gate level logic networks (FFs with enable) + :name: tab:CellLib_gates_dffe + + ================== ============= ============ + :math:`ClkEdge` :math:`EnLvl` Cell Type + ================== ============= ============ + :verilog:`negedge` ``0`` `$_DFFE_NN_` + :verilog:`negedge` ``1`` `$_DFFE_NP_` + :verilog:`posedge` ``0`` `$_DFFE_PN_` + :verilog:`posedge` ``1`` `$_DFFE_PP_` + ================== ============= ============ + + +.. table:: Cell types for gate level logic networks (FFs with reset and enable) + :name: tab:CellLib_gates_adffe + + ================== ============== ============== ============= ================================================= + :math:`ClkEdge` :math:`RstLvl` :math:`RstVal` :math:`EnLvl` Cell Type + ================== ============== ============== ============= ================================================= + :verilog:`negedge` ``0`` ``0`` ``0`` `$_DFFE_NN0N_`, `$_SDFFE_NN0N_`, `$_SDFFCE_NN0N_` + :verilog:`negedge` ``0`` ``0`` ``1`` `$_DFFE_NN0P_`, `$_SDFFE_NN0P_`, `$_SDFFCE_NN0P_` + :verilog:`negedge` ``0`` ``1`` ``0`` `$_DFFE_NN1N_`, `$_SDFFE_NN1N_`, `$_SDFFCE_NN1N_` + :verilog:`negedge` ``0`` ``1`` ``1`` `$_DFFE_NN1P_`, `$_SDFFE_NN1P_`, `$_SDFFCE_NN1P_` + :verilog:`negedge` ``1`` ``0`` ``0`` `$_DFFE_NP0N_`, `$_SDFFE_NP0N_`, `$_SDFFCE_NP0N_` + :verilog:`negedge` ``1`` ``0`` ``1`` `$_DFFE_NP0P_`, `$_SDFFE_NP0P_`, `$_SDFFCE_NP0P_` + :verilog:`negedge` ``1`` ``1`` ``0`` `$_DFFE_NP1N_`, `$_SDFFE_NP1N_`, `$_SDFFCE_NP1N_` + :verilog:`negedge` ``1`` ``1`` ``1`` `$_DFFE_NP1P_`, `$_SDFFE_NP1P_`, `$_SDFFCE_NP1P_` + :verilog:`posedge` ``0`` ``0`` ``0`` `$_DFFE_PN0N_`, `$_SDFFE_PN0N_`, `$_SDFFCE_PN0N_` + :verilog:`posedge` ``0`` ``0`` ``1`` `$_DFFE_PN0P_`, `$_SDFFE_PN0P_`, `$_SDFFCE_PN0P_` + :verilog:`posedge` ``0`` ``1`` ``0`` `$_DFFE_PN1N_`, `$_SDFFE_PN1N_`, `$_SDFFCE_PN1N_` + :verilog:`posedge` ``0`` ``1`` ``1`` `$_DFFE_PN1P_`, `$_SDFFE_PN1P_`, `$_SDFFCE_PN1P_` + :verilog:`posedge` ``1`` ``0`` ``0`` `$_DFFE_PP0N_`, `$_SDFFE_PP0N_`, `$_SDFFCE_PP0N_` + :verilog:`posedge` ``1`` ``0`` ``1`` `$_DFFE_PP0P_`, `$_SDFFE_PP0P_`, `$_SDFFCE_PP0P_` + :verilog:`posedge` ``1`` ``1`` ``0`` `$_DFFE_PP1N_`, `$_SDFFE_PP1N_`, `$_SDFFCE_PP1N_` + :verilog:`posedge` ``1`` ``1`` ``1`` `$_DFFE_PP1P_`, `$_SDFFE_PP1P_`, `$_SDFFCE_PP1P_` + ================== ============== ============== ============= ================================================= + +.. table:: Cell types for gate level logic networks (FFs with set and reset) + :name: tab:CellLib_gates_dffsr + + ================== ============== ============== ============== + :math:`ClkEdge` :math:`SetLvl` :math:`RstLvl` Cell Type + ================== ============== ============== ============== + :verilog:`negedge` ``0`` ``0`` `$_DFFSR_NNN_` + :verilog:`negedge` ``0`` ``1`` `$_DFFSR_NNP_` + :verilog:`negedge` ``1`` ``0`` `$_DFFSR_NPN_` + :verilog:`negedge` ``1`` ``1`` `$_DFFSR_NPP_` + :verilog:`posedge` ``0`` ``0`` `$_DFFSR_PNN_` + :verilog:`posedge` ``0`` ``1`` `$_DFFSR_PNP_` + :verilog:`posedge` ``1`` ``0`` `$_DFFSR_PPN_` + :verilog:`posedge` ``1`` ``1`` `$_DFFSR_PPP_` + ================== ============== ============== ============== + + +.. table:: Cell types for gate level logic networks (FFs with set and reset and enable) + :name: tab:CellLib_gates_dffsre + + ================== ============== ============== ============= ================ + :math:`ClkEdge` :math:`SetLvl` :math:`RstLvl` :math:`EnLvl` Cell Type + ================== ============== ============== ============= ================ + :verilog:`negedge` ``0`` ``0`` ``0`` `$_DFFSRE_NNNN_` + :verilog:`negedge` ``0`` ``0`` ``1`` `$_DFFSRE_NNNP_` + :verilog:`negedge` ``0`` ``1`` ``0`` `$_DFFSRE_NNPN_` + :verilog:`negedge` ``0`` ``1`` ``1`` `$_DFFSRE_NNPP_` + :verilog:`negedge` ``1`` ``0`` ``0`` `$_DFFSRE_NPNN_` + :verilog:`negedge` ``1`` ``0`` ``1`` `$_DFFSRE_NPNP_` + :verilog:`negedge` ``1`` ``1`` ``0`` `$_DFFSRE_NPPN_` + :verilog:`negedge` ``1`` ``1`` ``1`` `$_DFFSRE_NPPP_` + :verilog:`posedge` ``0`` ``0`` ``0`` `$_DFFSRE_PNNN_` + :verilog:`posedge` ``0`` ``0`` ``1`` `$_DFFSRE_PNNP_` + :verilog:`posedge` ``0`` ``1`` ``0`` `$_DFFSRE_PNPN_` + :verilog:`posedge` ``0`` ``1`` ``1`` `$_DFFSRE_PNPP_` + :verilog:`posedge` ``1`` ``0`` ``0`` `$_DFFSRE_PPNN_` + :verilog:`posedge` ``1`` ``0`` ``1`` `$_DFFSRE_PPNP_` + :verilog:`posedge` ``1`` ``1`` ``0`` `$_DFFSRE_PPPN_` + :verilog:`posedge` ``1`` ``1`` ``1`` `$_DFFSRE_PPPP_` + ================== ============== ============== ============= ================ + + +.. table:: Cell types for gate level logic networks (latches with reset) + :name: tab:CellLib_gates_adlatch + + ============= ============== ============== =============== + :math:`EnLvl` :math:`RstLvl` :math:`RstVal` Cell Type + ============= ============== ============== =============== + ``0`` ``0`` ``0`` `$_DLATCH_NN0_` + ``0`` ``0`` ``1`` `$_DLATCH_NN1_` + ``0`` ``1`` ``0`` `$_DLATCH_NP0_` + ``0`` ``1`` ``1`` `$_DLATCH_NP1_` + ``1`` ``0`` ``0`` `$_DLATCH_PN0_` + ``1`` ``0`` ``1`` `$_DLATCH_PN1_` + ``1`` ``1`` ``0`` `$_DLATCH_PP0_` + ``1`` ``1`` ``1`` `$_DLATCH_PP1_` + ============= ============== ============== =============== + + +.. table:: Cell types for gate level logic networks (latches with set and reset) + :name: tab:CellLib_gates_dlatchsr + + ============= ============== ============== ================= + :math:`EnLvl` :math:`SetLvl` :math:`RstLvl` Cell Type + ============= ============== ============== ================= + ``0`` ``0`` ``0`` `$_DLATCHSR_NNN_` + ``0`` ``0`` ``1`` `$_DLATCHSR_NNP_` + ``0`` ``1`` ``0`` `$_DLATCHSR_NPN_` + ``0`` ``1`` ``1`` `$_DLATCHSR_NPP_` + ``1`` ``0`` ``0`` `$_DLATCHSR_PNN_` + ``1`` ``0`` ``1`` `$_DLATCHSR_PNP_` + ``1`` ``1`` ``0`` `$_DLATCHSR_PPN_` + ``1`` ``1`` ``1`` `$_DLATCHSR_PPP_` + ============= ============== ============== ================= + + + +.. table:: Cell types for gate level logic networks (SR latches) + :name: tab:CellLib_gates_sr + + ============== ============== ========== + :math:`SetLvl` :math:`RstLvl` Cell Type + ============== ============== ========== + ``0`` ``0`` `$_SR_NN_` + ``0`` ``1`` `$_SR_NP_` + ``1`` ``0`` `$_SR_PN_` + ``1`` ``1`` `$_SR_PP_` + ============== ============== ========== + + +Tables :numref:`%s `, :numref:`%s `, +:numref:`%s `, :numref:`%s `, +:numref:`%s `, :numref:`%s `, +:numref:`%s `, :numref:`%s +` and :numref:`%s ` list all +cell types used for gate level logic. The cell types `$_BUF_`, `$_NOT_`, +`$_AND_`, `$_NAND_`, `$_ANDNOT_`, `$_OR_`, `$_NOR_`, `$_ORNOT_`, `$_XOR_`, +`$_XNOR_`, `$_AOI3_`, `$_OAI3_`, `$_AOI4_`, `$_OAI4_`, `$_MUX_`, `$_MUX4_`, +`$_MUX8_`, `$_MUX16_` and `$_NMUX_` are used to model combinatorial logic. The +cell type `$_TBUF_` is used to model tristate logic. + +The `$_MUX4_`, `$_MUX8_` and `$_MUX16_` cells are used to model wide muxes, and +correspond to the following Verilog code: + +.. code-block:: verilog + :force: + + // $_MUX4_ + assign Y = T ? (S ? D : C) : + (S ? B : A); + // $_MUX8_ + assign Y = U ? T ? (S ? H : G) : + (S ? F : E) : + T ? (S ? D : C) : + (S ? B : A); + // $_MUX16_ + assign Y = V ? U ? T ? (S ? P : O) : + (S ? N : M) : + T ? (S ? L : K) : + (S ? J : I) : + U ? T ? (S ? H : G) : + (S ? F : E) : + T ? (S ? D : C) : + (S ? B : A); + +The cell types `$_DFF_N_` and `$_DFF_P_` represent d-type flip-flops. + +The cell types ``$_DFFE_[NP][NP]_`` implement d-type flip-flops with enable. The +values in the table for these cell types relate to the following Verilog code +template. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C) + if (EN == EN_LVL) + Q <= D; + +The cell types ``$_DFF_[NP][NP][01]_`` implement d-type flip-flops with +asynchronous reset. The values in the table for these cell types relate to the +following Verilog code template, where ``RST_EDGE`` is ``posedge`` if +``RST_LVL`` if ``1``, and ``negedge`` otherwise. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C, RST_EDGE R) + if (R == RST_LVL) + Q <= RST_VAL; + else + Q <= D; + +The cell types ``$_SDFF_[NP][NP][01]_`` implement d-type flip-flops with +synchronous reset. The values in the table for these cell types relate to the +following Verilog code template: + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C) + if (R == RST_LVL) + Q <= RST_VAL; + else + Q <= D; + +The cell types ``$_DFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with +asynchronous reset and enable. The values in the table for these cell types +relate to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` +if ``RST_LVL`` if ``1``, and ``negedge`` otherwise. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C, RST_EDGE R) + if (R == RST_LVL) + Q <= RST_VAL; + else if (EN == EN_LVL) + Q <= D; + +The cell types ``$_SDFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with +synchronous reset and enable, with reset having priority over enable. The values +in the table for these cell types relate to the following Verilog code template: + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C) + if (R == RST_LVL) + Q <= RST_VAL; + else if (EN == EN_LVL) + Q <= D; + +The cell types ``$_SDFFCE_[NP][NP][01][NP]_`` implement d-type flip-flops with +synchronous reset and enable, with enable having priority over reset. The values +in the table for these cell types relate to the following Verilog code template: + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C) + if (EN == EN_LVL) + if (R == RST_LVL) + Q <= RST_VAL; + else + Q <= D; + +The cell types ``$_DFFSR_[NP][NP][NP]_`` implement d-type flip-flops with +asynchronous set and reset. The values in the table for these cell types relate +to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` if +``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is ``posedge`` if +``SET_LVL`` if ``1``, ``negedge`` otherwise. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S) + if (R == RST_LVL) + Q <= 0; + else if (S == SET_LVL) + Q <= 1; + else + Q <= D; + +The cell types ``$_DFFSRE_[NP][NP][NP][NP]_`` implement d-type flip-flops with +asynchronous set and reset and enable. The values in the table for these cell +types relate to the following Verilog code template, where ``RST_EDGE`` is +``posedge`` if ``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is +``posedge`` if ``SET_LVL`` if ``1``, ``negedge`` otherwise. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S) + if (R == RST_LVL) + Q <= 0; + else if (S == SET_LVL) + Q <= 1; + else if (E == EN_LVL) + Q <= D; + +The cell types `$_DLATCH_N_` and `$_DLATCH_P_` represent d-type latches. + +The cell types ``$_DLATCH_[NP][NP][01]_`` implement d-type latches with reset. +The values in the table for these cell types relate to the following Verilog +code template: + +.. code-block:: verilog + :force: + + always @* + if (R == RST_LVL) + Q <= RST_VAL; + else if (E == EN_LVL) + Q <= D; + +The cell types ``$_DLATCHSR_[NP][NP][NP]_`` implement d-type latches with set +and reset. The values in the table for these cell types relate to the following +Verilog code template: + +.. code-block:: verilog + :force: + + always @* + if (R == RST_LVL) + Q <= 0; + else if (S == SET_LVL) + Q <= 1; + else if (E == EN_LVL) + Q <= D; + +The cell types ``$_SR_[NP][NP]_`` implement sr-type latches. The values in the +table for these cell types relate to the following Verilog code template: + +.. code-block:: verilog + :force: + + always @* + if (R == RST_LVL) + Q <= 0; + else if (S == SET_LVL) + Q <= 1; + +In most cases gate level logic networks are created from RTL networks using the +techmap pass. The flip-flop cells from the gate level logic network can be +mapped to physical flip-flop cells from a Liberty file using the dfflibmap pass. +The combinatorial logic cells can be mapped to physical cells from a Liberty +file via ABC using the abc pass. + .. toctree:: :caption: Gate-level cells :maxdepth: 2 diff --git a/docs/source/cell_word.rst b/docs/source/cell_word.rst index c23a4e1b1..a736801fa 100644 --- a/docs/source/cell_word.rst +++ b/docs/source/cell_word.rst @@ -19,4 +19,21 @@ Simulation models for the RTL cells can be found in the file /cell/word_unary /cell/word_binary - /cell/word_other + /cell/word_mux + /cell/word_reg + /cell/word_mem + /cell/word_fsm + /cell/word_arith + /cell/word_spec + /cell/word_formal + /cell/word_debug + +.. todo:: Add information about `$slice` and `$concat` cells. + +.. todo:: Add information about `$alu`, `$fa`, and `$lcu` cells. + +.. autocellgroup:: word_other + :caption: Other word-level cells + :members: + :source: + :linenos: diff --git a/docs/source/using_yosys/more_scripting/interactive_investigation.rst b/docs/source/using_yosys/more_scripting/interactive_investigation.rst index f078ed59e..68b538076 100644 --- a/docs/source/using_yosys/more_scripting/interactive_investigation.rst +++ b/docs/source/using_yosys/more_scripting/interactive_investigation.rst @@ -65,7 +65,7 @@ displayed as rectangles with inputs on the left and outputs on the right side. The cell labels are two lines long: The first line contains a unique identifier for the cell and the second line contains the cell type. Internal cell types are prefixed with a dollar sign. For more details on the internal cell library, see -:doc:`/yosys_internals/formats/cell_library`. +:doc:`/cell_gate` and :doc:`/cell_word`. Constants are shown as ellipses with the constant value as label. The syntax ``'`` is used for constants that are not 32-bit wide and/or diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst index 7af2231c9..87763dbbe 100644 --- a/docs/source/using_yosys/synthesis/opt.rst +++ b/docs/source/using_yosys/synthesis/opt.rst @@ -27,9 +27,9 @@ Constant folding and simple expression rewriting - `opt_expr` .. todo:: unsure if this is too much detail and should be in :doc:`/yosys_internals/index` This pass performs constant folding on the internal combinational cell types -described in :doc:`/yosys_internals/formats/cell_library`. This means a cell -with all constant inputs is replaced with the constant value this cell drives. -In some cases this pass can also optimize cells with some constant inputs. +described in :doc:`/cell_gate` and :doc:`/cell_word`. This means a cell with all +constant inputs is replaced with the constant value this cell drives. In some +cases this pass can also optimize cells with some constant inputs. .. table:: Const folding rules for `$_AND_` cells as used in `opt_expr`. :name: tab:opt_expr_and @@ -182,6 +182,8 @@ away by `opt_expr`. Performing DFF optimizations - `opt_dff` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. todo:: ``$_DFF_`` isn't a valid cell + This pass identifies single-bit d-type flip-flops (`$_DFF_`, `$dff`, and `$adff` cells) with a constant data input and replaces them with a constant driver. It can also merge clock enables and synchronous reset multiplexers, removing unused diff --git a/docs/source/yosys_internals/formats/cell_library.rst b/docs/source/yosys_internals/formats/cell_library.rst deleted file mode 100644 index 73dbc4e69..000000000 --- a/docs/source/yosys_internals/formats/cell_library.rst +++ /dev/null @@ -1,1086 +0,0 @@ -.. role:: verilog(code) - :language: Verilog - -.. _chapter:celllib: - -Internal cell library -===================== - -.. todo:: less academic, also check formatting consistency - -Most of the passes in Yosys operate on netlists, i.e. they only care about the -``RTLIL::Wire`` and ``RTLIL::Cell`` objects in an ``RTLIL::Module``. This -chapter discusses the cell types used by Yosys to represent a behavioural design -internally. - -This chapter is split in two parts. In the first part the internal RTL cells are -covered. These cells are used to represent the design on a coarse grain level. -Like in the original HDL code on this level the cells operate on vectors of -signals and complex cells like adders exist. In the second part the internal -gate cells are covered. These cells are used to represent the design on a -fine-grain gate-level. All cells from this category operate on single bit -signals. - -Multiplexers -~~~~~~~~~~~~ - -Multiplexers are generated by the Verilog HDL frontend for ``?:``-expressions. -Multiplexers are also generated by the proc pass to map the decision trees from -RTLIL::Process objects to logic. - -The simplest multiplexer cell type is `$mux`. Cells of this type have a -``\WITDH`` parameter and data inputs ``\A`` and ``\B`` and a data output ``\Y``, -all of the specified width. This cell also has a single bit control input -``\S``. If ``\S`` is 0 the value from the input ``\A`` is sent to the output, if -it is 1 the value from the ``\B`` input is sent to the output. So the `$mux` -cell implements the function :verilog:`Y = S ? B : A`. - -The `$pmux` cell is used to multiplex between many inputs using a one-hot select -signal. Cells of this type have a ``\WIDTH`` and a ``\S_WIDTH`` parameter and -inputs ``\A``, ``\B``, and ``\S`` and an output ``\Y``. The ``\S`` input is -``\S_WIDTH`` bits wide. The ``\A`` input and the output are both ``\WIDTH`` bits -wide and the ``\B`` input is ``\WIDTH*\S_WIDTH`` bits wide. When all bits of -``\S`` are zero, the value from ``\A`` input is sent to the output. If the -:math:`n`\ 'th bit from ``\S`` is set, the value :math:`n`\ 'th ``\WIDTH`` bits -wide slice of the ``\B`` input is sent to the output. When more than one bit -from ``\S`` is set the output is undefined. Cells of this type are used to model -"parallel cases" (defined by using the ``parallel_case`` attribute or detected -by an optimization). - -The `$tribuf` cell is used to implement tristate logic. Cells of this type have -a ``\WIDTH`` parameter and inputs ``\A`` and ``\EN`` and an output ``\Y``. The -``\A`` input and ``\Y`` output are ``\WIDTH`` bits wide, and the ``\EN`` input -is one bit wide. When ``\EN`` is 0, the output is not driven. When ``\EN`` is 1, -the value from ``\A`` input is sent to the ``\Y`` output. Therefore, the -`$tribuf` cell implements the function :verilog:`Y = EN ? A : 'bz`. - -Behavioural code with cascaded if-then-else- and case-statements usually results -in trees of multiplexer cells. Many passes (from various optimizations to FSM -extraction) heavily depend on these multiplexer trees to understand dependencies -between signals. Therefore optimizations should not break these multiplexer -trees (e.g. by replacing a multiplexer between a calculated signal and a -constant zero with an `$and` gate). - -Registers -~~~~~~~~~ - -SR-type latches are represented by `$sr` cells. These cells have input ports -``\SET`` and ``\CLR`` and an output port ``\Q``. They have the following -parameters: - -``\WIDTH`` - The width of inputs ``\SET`` and ``\CLR`` and output ``\Q``. - -``\SET_POLARITY`` - The set input bits are active-high if this parameter has the value ``1'b1`` - and active-low if this parameter is ``1'b0``. - -``\CLR_POLARITY`` - The reset input bits are active-high if this parameter has the value ``1'b1`` - and active-low if this parameter is ``1'b0``. - -Both set and reset inputs have separate bits for every output bit. When both the -set and reset inputs of an `$sr` cell are active for a given bit index, the -reset input takes precedence. - -D-type flip-flops are represented by `$dff` cells. These cells have a clock port -``\CLK``, an input port ``\D`` and an output port ``\Q``. The following -parameters are available for `$dff` cells: - -``\WIDTH`` - The width of input ``\D`` and output ``\Q``. - -``\CLK_POLARITY`` - Clock is active on the positive edge if this parameter has the value ``1'b1`` - and on the negative edge if this parameter is ``1'b0``. - -D-type flip-flops with asynchronous reset are represented by `$adff` cells. As -the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they -also have a single-bit ``\ARST`` input port for the reset pin and the following -additional two parameters: - -``\ARST_POLARITY`` - The asynchronous reset is active-high if this parameter has the value - ``1'b1`` and active-low if this parameter is ``1'b0``. - -``\ARST_VALUE`` - The state of ``\Q`` will be set to this value when the reset is active. - -Usually these cells are generated by the `proc` pass using the information in -the designs RTLIL::Process objects. - -D-type flip-flops with synchronous reset are represented by `$sdff` cells. As -the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they -also have a single-bit ``\SRST`` input port for the reset pin and the following -additional two parameters: - -``\SRST_POLARITY`` - The synchronous reset is active-high if this parameter has the value ``1'b1`` - and active-low if this parameter is ``1'b0``. - -``\SRST_VALUE`` - The state of ``\Q`` will be set to this value when the reset is active. - -Note that the `$adff` and `$sdff` cells can only be used when the reset value is -constant. - -D-type flip-flops with asynchronous load are represented by `$aldff` cells. As -the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they -also have a single-bit ``\ALOAD`` input port for the async load enable pin, a -``\AD`` input port with the same width as data for the async load data, and the -following additional parameter: - -``\ALOAD_POLARITY`` - The asynchronous load is active-high if this parameter has the value ``1'b1`` - and active-low if this parameter is ``1'b0``. - -D-type flip-flops with asynchronous set and reset are represented by `$dffsr` -cells. As the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In -addition they also have multi-bit ``\SET`` and ``\CLR`` input ports and the -corresponding polarity parameters, like `$sr` cells. - -D-type flip-flops with enable are represented by `$dffe`, `$adffe`, `$aldffe`, -`$dffsre`, `$sdffe`, and `$sdffce` cells, which are enhanced variants of `$dff`, -`$adff`, `$aldff`, `$dffsr`, `$sdff` (with reset over enable) and `$sdff` (with -enable over reset) cells, respectively. They have the same ports and parameters -as their base cell. In addition they also have a single-bit ``\EN`` input port -for the enable pin and the following parameter: - -``\EN_POLARITY`` - The enable input is active-high if this parameter has the value ``1'b1`` and - active-low if this parameter is ``1'b0``. - -D-type latches are represented by `$dlatch` cells. These cells have an enable -port ``\EN``, an input port ``\D``, and an output port ``\Q``. The following -parameters are available for `$dlatch` cells: - -``\WIDTH`` - The width of input ``\D`` and output ``\Q``. - -``\EN_POLARITY`` - The enable input is active-high if this parameter has the value ``1'b1`` and - active-low if this parameter is ``1'b0``. - -The latch is transparent when the ``\EN`` input is active. - -D-type latches with reset are represented by `$adlatch` cells. In addition to -`$dlatch` ports and parameters, they also have a single-bit ``\ARST`` input port -for the reset pin and the following additional parameters: - -``\ARST_POLARITY`` - The asynchronous reset is active-high if this parameter has the value - ``1'b1`` and active-low if this parameter is ``1'b0``. - -``\ARST_VALUE`` - The state of ``\Q`` will be set to this value when the reset is active. - -D-type latches with set and reset are represented by `$dlatchsr` cells. In -addition to `$dlatch` ports and parameters, they also have multi-bit ``\SET`` -and ``\CLR`` input ports and the corresponding polarity parameters, like `$sr` -cells. - -.. _sec:memcells: - -Memories -~~~~~~~~ - -Memories are either represented using ``RTLIL::Memory`` objects, `$memrd_v2`, -`$memwr_v2`, and `$meminit_v2` cells, or by `$mem_v2` cells alone. - -In the first alternative the ``RTLIL::Memory`` objects hold the general metadata -for the memory (bit width, size in number of words, etc.) and for each port a -`$memrd_v2` (read port) or `$memwr_v2` (write port) cell is created. Having -individual cells for read and write ports has the advantage that they can be -consolidated using resource sharing passes. In some cases this drastically -reduces the number of required ports on the memory cell. In this alternative, -memory initialization data is represented by `$meminit_v2` cells, which allow -delaying constant folding for initialization addresses and data until after the -frontend finishes. - -The `$memrd_v2` cells have a clock input ``\CLK``, an enable input ``\EN``, an -address input ``\ADDR``, a data output ``\DATA``, an asynchronous reset input -``\ARST``, and a synchronous reset input ``\SRST``. They also have the following -parameters: - -``\MEMID`` - The name of the ``RTLIL::Memory`` object that is associated with this read - port. - -``\ABITS`` - The number of address bits (width of the ``\ADDR`` input port). - -``\WIDTH`` - The number of data bits (width of the ``\DATA`` output port). Note that this - may be a power-of-two multiple of the underlying memory's width -- such ports - are called wide ports and access an aligned group of cells at once. In this - case, the corresponding low bits of ``\ADDR`` must be tied to 0. - -``\CLK_ENABLE`` - When this parameter is non-zero, the clock is used. Otherwise this read port - is asynchronous and the ``\CLK`` input is not used. - -``\CLK_POLARITY`` - Clock is active on the positive edge if this parameter has the value ``1'b1`` - and on the negative edge if this parameter is ``1'b0``. - -``\TRANSPARENCY_MASK`` - This parameter is a bitmask of write ports that this read port is transparent - with. The bits of this parameter are indexed by the write port's ``\PORTID`` - parameter. Transparency can only be enabled between synchronous ports sharing - a clock domain. When transparency is enabled for a given port pair, a read - and write to the same address in the same cycle will return the new value. - Otherwise the old value is returned. - -``\COLLISION_X_MASK`` - This parameter is a bitmask of write ports that have undefined collision - behavior with this port. The bits of this parameter are indexed by the write - port's ``\PORTID`` parameter. This behavior can only be enabled between - synchronous ports sharing a clock domain. When undefined collision is enabled - for a given port pair, a read and write to the same address in the same cycle - will return the undefined (all-X) value.This option is exclusive (for a given - port pair) with the transparency option. - -``\ARST_VALUE`` - Whenever the ``\ARST`` input is asserted, the data output will be reset to - this value. Only used for synchronous ports. - -``\SRST_VALUE`` - Whenever the ``\SRST`` input is synchronously asserted, the data output will - be reset to this value. Only used for synchronous ports. - -``\INIT_VALUE`` - The initial value of the data output, for synchronous ports. - -``\CE_OVER_SRST`` - If this parameter is non-zero, the ``\SRST`` input is only recognized when - ``\EN`` is true. Otherwise, ``\SRST`` is recognized regardless of ``\EN``. - -The `$memwr_v2` cells have a clock input ``\CLK``, an enable input ``\EN`` (one -enable bit for each data bit), an address input ``\ADDR`` and a data input -``\DATA``. They also have the following parameters: - -``\MEMID`` - The name of the ``RTLIL::Memory`` object that is associated with this write - port. - -``\ABITS`` - The number of address bits (width of the ``\ADDR`` input port). - -``\WIDTH`` - The number of data bits (width of the ``\DATA`` output port). Like with - `$memrd_v2` cells, the width is allowed to be any power-of-two multiple of - memory width, with the corresponding restriction on address. - -``\CLK_ENABLE`` - When this parameter is non-zero, the clock is used. Otherwise this write port - is asynchronous and the ``\CLK`` input is not used. - -``\CLK_POLARITY`` - Clock is active on positive edge if this parameter has the value ``1'b1`` and - on the negative edge if this parameter is ``1'b0``. - -``\PORTID`` - An identifier for this write port, used to index write port bit mask - parameters. - -``\PRIORITY_MASK`` - This parameter is a bitmask of write ports that this write port has priority - over in case of writing to the same address. The bits of this parameter are - indexed by the other write port's ``\PORTID`` parameter. Write ports can only - have priority over write ports with lower port ID. When two ports write to - the same address and neither has priority over the other, the result is - undefined. Priority can only be set between two synchronous ports sharing - the same clock domain. - -The `$meminit_v2` cells have an address input ``\ADDR``, a data input ``\DATA``, -with the width of the ``\DATA`` port equal to ``\WIDTH`` parameter times -``\WORDS`` parameter, and a bit enable mask input ``\EN`` with width equal to -``\WIDTH`` parameter. All three of the inputs must resolve to a constant for -synthesis to succeed. - -``\MEMID`` - The name of the ``RTLIL::Memory`` object that is associated with this - initialization cell. - -``\ABITS`` - The number of address bits (width of the ``\ADDR`` input port). - -``\WIDTH`` - The number of data bits per memory location. - -``\WORDS`` - The number of consecutive memory locations initialized by this cell. - -``\PRIORITY`` - The cell with the higher integer value in this parameter wins an - initialization conflict. - -The HDL frontend models a memory using ``RTLIL::Memory`` objects and -asynchronous `$memrd_v2` and `$memwr_v2` cells. The `memory` pass (i.e. its -various sub-passes) migrates `$dff` cells into the `$memrd_v2` and `$memwr_v2` -cells making them synchronous, then converts them to a single `$mem_v2` cell and -(optionally) maps this cell type to `$dff` cells for the individual words and -multiplexer-based address decoders for the read and write interfaces. When the -last step is disabled or not possible, a `$mem_v2` cell is left in the design. - -The `$mem_v2` cell provides the following parameters: - -``\MEMID`` - The name of the original ``RTLIL::Memory`` object that became this `$mem_v2` - cell. - -``\SIZE`` - The number of words in the memory. - -``\ABITS`` - The number of address bits. - -``\WIDTH`` - The number of data bits per word. - -``\INIT`` - The initial memory contents. - -``\RD_PORTS`` - The number of read ports on this memory cell. - -``\RD_WIDE_CONTINUATION`` - This parameter is ``\RD_PORTS`` bits wide, containing a bitmask of "wide - continuation" read ports. Such ports are used to represent the extra data - bits of wide ports in the combined cell, and must have all control signals - identical with the preceding port, except for address, which must have the - proper sub-cell address encoded in the low bits. - -``\RD_CLK_ENABLE`` - This parameter is ``\RD_PORTS`` bits wide, containing a clock enable bit for - each read port. - -``\RD_CLK_POLARITY`` - This parameter is ``\RD_PORTS`` bits wide, containing a clock polarity bit - for each read port. - -``\RD_TRANSPARENCY_MASK`` - This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a - concatenation of all ``\TRANSPARENCY_MASK`` values of the original - `$memrd_v2` cells. - -``\RD_COLLISION_X_MASK`` - This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a - concatenation of all ``\COLLISION_X_MASK`` values of the original `$memrd_v2` - cells. - -``\RD_CE_OVER_SRST`` - This parameter is ``\RD_PORTS`` bits wide, determining relative synchronous - reset and enable priority for each read port. - -``\RD_INIT_VALUE`` - This parameter is ``\RD_PORTS*\WIDTH`` bits wide, containing the initial - value for each synchronous read port. - -``\RD_ARST_VALUE`` - This parameter is ``\RD_PORTS*\WIDTH`` bits wide, containing the asynchronous - reset value for each synchronous read port. - -``\RD_SRST_VALUE`` - This parameter is ``\RD_PORTS*\WIDTH`` bits wide, containing the synchronous - reset value for each synchronous read port. - -``\WR_PORTS`` - The number of write ports on this memory cell. - -``\WR_WIDE_CONTINUATION`` - This parameter is ``\WR_PORTS`` bits wide, containing a bitmask of "wide - continuation" write ports. - -``\WR_CLK_ENABLE`` - This parameter is ``\WR_PORTS`` bits wide, containing a clock enable bit for - each write port. - -``\WR_CLK_POLARITY`` - This parameter is ``\WR_PORTS`` bits wide, containing a clock polarity bit - for each write port. - -``\WR_PRIORITY_MASK`` - This parameter is ``\WR_PORTS*\WR_PORTS`` bits wide, containing a - concatenation of all ``\PRIORITY_MASK`` values of the original `$memwr_v2` - cells. - -The `$mem_v2` cell has the following ports: - -``\RD_CLK`` - This input is ``\RD_PORTS`` bits wide, containing all clock signals for the - read ports. - -``\RD_EN`` - This input is ``\RD_PORTS`` bits wide, containing all enable signals for the - read ports. - -``\RD_ADDR`` - This input is ``\RD_PORTS*\ABITS`` bits wide, containing all address signals - for the read ports. - -``\RD_DATA`` - This output is ``\RD_PORTS*\WIDTH`` bits wide, containing all data signals - for the read ports. - -``\RD_ARST`` - This input is ``\RD_PORTS`` bits wide, containing all asynchronous reset - signals for the read ports. - -``\RD_SRST`` - This input is ``\RD_PORTS`` bits wide, containing all synchronous reset - signals for the read ports. - -``\WR_CLK`` - This input is ``\WR_PORTS`` bits wide, containing all clock signals for - the write ports. - -``\WR_EN`` - This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all enable signals - for the write ports. - -``\WR_ADDR`` - This input is ``\WR_PORTS*\ABITS`` bits wide, containing all address signals - for the write ports. - -``\WR_DATA`` - This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all data signals for - the write ports. - -The `memory_collect` pass can be used to convert discrete `$memrd_v2`, -`$memwr_v2`, and `$meminit_v2` cells belonging to the same memory to a single -`$mem_v2` cell, whereas the `memory_unpack` pass performs the inverse operation. -The `memory_dff` pass can combine asynchronous memory ports that are fed by or -feeding registers into synchronous memory ports. The `memory_bram` pass can be -used to recognize `$mem_v2` cells that can be implemented with a block RAM -resource on an FPGA. The `memory_map` pass can be used to implement `$mem_v2` -cells as basic logic: word-wide DFFs and address decoders. - -Finite state machines -~~~~~~~~~~~~~~~~~~~~~ - -Add a brief description of the `$fsm` cell type. - -Coarse arithmetics -~~~~~~~~~~~~~~~~~~~~~ - -The `$macc` cell type represents a generalized multiply and accumulate -operation. The cell is purely combinational. It outputs the result of summing up -a sequence of products and other injected summands. - -.. code-block:: - - Y = 0 +- a0factor1 * a0factor2 +- a1factor1 * a1factor2 +- ... - + B[0] + B[1] + ... - -The A port consists of concatenated pairs of multiplier inputs ("factors"). A -zero length factor2 acts as a constant 1, turning factor1 into a simple summand. - -In this pseudocode, ``u(foo)`` means an unsigned int that's foo bits long. - -.. code-block:: - - struct A { - u(CONFIG.mul_info[0].factor1_len) a0factor1; - u(CONFIG.mul_info[0].factor2_len) a0factor2; - u(CONFIG.mul_info[1].factor1_len) a1factor1; - u(CONFIG.mul_info[1].factor2_len) a1factor2; - ... - }; - -The cell's ``CONFIG`` parameter determines the layout of cell port ``A``. The -CONFIG parameter carries the following information: - -.. code-block:: - - struct CONFIG { - u4 num_bits; - struct mul_info { - bool is_signed; - bool is_subtract; - u(num_bits) factor1_len; - u(num_bits) factor2_len; - }[num_ports]; - }; - -B is an array of concatenated 1-bit-wide unsigned integers to also be summed up. - -Arbitrary logic functions -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``$lut`` cell type implements a single-output LUT (lookup table). -It implements an arbitrary logic function with its ``\LUT`` parameter to map -input port ``\A`` to values of ``\Y`` output port values. -In psuedocode: ``Y = \LUT[A]``. -``\A`` has width set by parameter ``\WIDTH`` and ``\Y`` has a width of 1. -Every logic function with a single bit output has a unique ``$lut`` -representation. - -The ``$sop`` cell type implements a sum-of-products expression, also known -as disjunctive normal form (DNF). It implements an arbitrary logic function. -Its structure mimics a programmable logic array (PLA). -Output port ``\Y`` is the sum of products of the bits of the input port ``\A`` -as defined by parameter ``\TABLE``. ``\A`` is ``\WIDTH`` bits wide. -The number of products in the sum is set by parameter ``\DEPTH``, and each -product has two bits for each input bit - for the presence of the -unnegated and negated version of said input bit in the product. -Therefore the ``\TABLE`` parameter holds ``2 * \WIDTH * \DEPTH`` bits. - -For example: - -Let ``\WIDTH`` be 3. We would like to represent ``\Y =~\A[0] + \A[1]~\A[2]``. -There are 2 products to be summed, so ``\DEPTH`` shall be 2. - -.. code-block:: - - ~A[2]-----+ - A[2]----+| - ~A[1]---+|| - A[1]--+||| - ~A[0]-+|||| - A[0]+||||| - |||||| product formula - 010000 ~\A[0] - 001001 \A[1]~\A[2] - -So the value of ``\TABLE`` will become ``010000001001``. - -Any logic function with a single bit output can be represented with -``$sop`` but may have variously minimized or ordered summands represented -in the ``\TABLE`` values. - -Specify rules -~~~~~~~~~~~~~ - -Add information about `$specify2`, `$specify3`, and `$specrule` cells. - -Formal verification cells -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Add information about `$check`, `$assert`, `$assume`, `$live`, `$fair`, -`$cover`, `$equiv`, `$initstate`, `$anyconst`, `$anyseq`, `$anyinit`, -`$allconst`, `$allseq` cells. - -Add information about `$ff` and `$_FF_` cells. - -Debugging cells -~~~~~~~~~~~~~~~ - -The `$print` cell is used to log the values of signals, akin to (and -translatable to) the ``$display`` and ``$write`` family of tasks in Verilog. It -has the following parameters: - -``\FORMAT`` - The internal format string. The syntax is described below. - -``\ARGS_WIDTH`` - The width (in bits) of the signal on the ``\ARGS`` port. - -``\TRG_ENABLE`` - True if triggered on specific signals defined in ``\TRG``; false if triggered - whenever ``\ARGS`` or ``\EN`` change and ``\EN`` is 1. - -If ``\TRG_ENABLE`` is true, the following parameters also apply: - -``\TRG_WIDTH`` - The number of bits in the ``\TRG`` port. - -``\TRG_POLARITY`` - For each bit in ``\TRG``, 1 if that signal is positive-edge triggered, 0 if - negative-edge triggered. - -``\PRIORITY`` - When multiple `$print` or `$check` cells fire on the same trigger, they - execute in descending priority order. - -Ports: - -``\TRG`` - The signals that control when this `$print` cell is triggered. - - If the width of this port is zero and ``\TRG_ENABLE`` is true, the cell is - triggered during initial evaluation (time zero) only. - -``\EN`` - Enable signal for the whole cell. - -``\ARGS`` - The values to be displayed, in format string order. - -Format string syntax -^^^^^^^^^^^^^^^^^^^^ - -The format string syntax resembles Python f-strings. Regular text is passed -through unchanged until a format specifier is reached, starting with a ``{``. - -Format specifiers have the following syntax. Unless noted, all items are -required: - -``{`` - Denotes the start of the format specifier. - -size - Signal size in bits; this many bits are consumed from the ``\ARGS`` port by - this specifier. - -``:`` - Separates the size from the remaining items. - -justify - ``>`` for right-justified, ``<`` for left-justified. - -padding - ``0`` for zero-padding, or a space for space-padding. - -width\ *?* - (optional) The number of characters wide to pad to. - -base - * ``b`` for base-2 integers (binary) - * ``o`` for base-8 integers (octal) - * ``d`` for base-10 integers (decimal) - * ``h`` for base-16 integers (hexadecimal) - * ``c`` for ASCII characters/strings - * ``t`` and ``r`` for simulation time (corresponding to :verilog:`$time` and - :verilog:`$realtime`) - -For integers, this item may follow: - -``+``\ *?* - (optional, decimals only) Include a leading plus for non-negative numbers. - This can assist with symmetry with negatives in tabulated output. - -signedness - ``u`` for unsigned, ``s`` for signed. This distinction is only respected - when rendering decimals. - -ASCII characters/strings have no special options, but the signal size must be -divisible by 8. - -For simulation time, the signal size must be zero. - -Finally: - -``}`` - Denotes the end of the format specifier. - -Some example format specifiers: - -+ ``{8:>02hu}`` - 8-bit unsigned integer rendered as hexadecimal, - right-justified, zero-padded to 2 characters wide. -+ ``{32:< 15d+s}`` - 32-bit signed integer rendered as decimal, left-justified, - space-padded to 15 characters wide, positive values prefixed with ``+``. -+ ``{16:< 10hu}`` - 16-bit unsigned integer rendered as hexadecimal, - left-justified, space-padded to 10 characters wide. -+ ``{0:>010t}`` - simulation time, right-justified, zero-padded to 10 characters - wide. - -To include literal ``{`` and ``}`` characters in your format string, use ``{{`` -and ``}}`` respectively. - -It is an error for a format string to consume more or less bits from ``\ARGS`` -than the port width. - -Values are never truncated, regardless of the specified width. - -Note that further restrictions on allowable combinations of options may apply -depending on the backend used. - -For example, Verilog does not have a format specifier that allows zero-padding a -string (i.e. more than 1 ASCII character), though zero-padding a single -character is permitted. - -Thus, while the RTLIL format specifier ``{8:>02c}`` translates to ``%02c``, -``{16:>02c}`` cannot be represented in Verilog and will fail to emit. In this -case, ``{16:> 02c}`` must be used, which translates to ``%2s``. - -.. _sec:celllib_gates: - -Gates ------ - -For gate level logic networks, fixed function single bit cells are used that do -not provide any parameters. - -Simulation models for these cells can be found in the file -techlibs/common/simcells.v in the Yosys source tree. - -.. table:: Cell types for gate level logic networks (main list) - :name: tab:CellLib_gates - - ======================================= ============ - Verilog Cell Type - ======================================= ============ - :verilog:`Y = A` $_BUF_ - :verilog:`Y = ~A` $_NOT_ - :verilog:`Y = A & B` $_AND_ - :verilog:`Y = ~(A & B)` $_NAND_ - :verilog:`Y = A & ~B` $_ANDNOT_ - :verilog:`Y = A | B` $_OR_ - :verilog:`Y = ~(A | B)` $_NOR_ - :verilog:`Y = A | ~B` $_ORNOT_ - :verilog:`Y = A ^ B` $_XOR_ - :verilog:`Y = ~(A ^ B)` $_XNOR_ - :verilog:`Y = ~((A & B) | C)` $_AOI3_ - :verilog:`Y = ~((A | B) & C)` $_OAI3_ - :verilog:`Y = ~((A & B) | (C & D))` $_AOI4_ - :verilog:`Y = ~((A | B) & (C | D))` $_OAI4_ - :verilog:`Y = S ? B : A` $_MUX_ - :verilog:`Y = ~(S ? B : A)` $_NMUX_ - (see below) $_MUX4_ - (see below) $_MUX8_ - (see below) $_MUX16_ - :verilog:`Y = EN ? A : 1'bz` $_TBUF_ - :verilog:`always @(negedge C) Q <= D` $_DFF_N_ - :verilog:`always @(posedge C) Q <= D` $_DFF_P_ - :verilog:`always @* if (!E) Q <= D` $_DLATCH_N_ - :verilog:`always @* if (E) Q <= D` $_DLATCH_P_ - ======================================= ============ - -.. table:: Cell types for gate level logic networks (FFs with reset) - :name: tab:CellLib_gates_adff - - ================== ============== ============== ======================= - :math:`ClkEdge` :math:`RstLvl` :math:`RstVal` Cell Type - ================== ============== ============== ======================= - :verilog:`negedge` ``0`` ``0`` $_DFF_NN0_, $_SDFF_NN0_ - :verilog:`negedge` ``0`` ``1`` $_DFF_NN1_, $_SDFF_NN1_ - :verilog:`negedge` ``1`` ``0`` $_DFF_NP0_, $_SDFF_NP0_ - :verilog:`negedge` ``1`` ``1`` $_DFF_NP1_, $_SDFF_NP1_ - :verilog:`posedge` ``0`` ``0`` $_DFF_PN0_, $_SDFF_PN0_ - :verilog:`posedge` ``0`` ``1`` $_DFF_PN1_, $_SDFF_PN1_ - :verilog:`posedge` ``1`` ``0`` $_DFF_PP0_, $_SDFF_PP0_ - :verilog:`posedge` ``1`` ``1`` $_DFF_PP1_, $_SDFF_PP1_ - ================== ============== ============== ======================= - - -.. table:: Cell types for gate level logic networks (FFs with enable) - :name: tab:CellLib_gates_dffe - - ================== ============= =========== - :math:`ClkEdge` :math:`EnLvl` Cell Type - ================== ============= =========== - :verilog:`negedge` ``0`` $_DFFE_NN_ - :verilog:`negedge` ``1`` $_DFFE_NP_ - :verilog:`posedge` ``0`` $_DFFE_PN_ - :verilog:`posedge` ``1`` $_DFFE_PP_ - ================== ============= =========== - - -.. table:: Cell types for gate level logic networks (FFs with reset and enable) - :name: tab:CellLib_gates_adffe - - ================== ============== ============== ============= =========================================== - :math:`ClkEdge` :math:`RstLvl` :math:`RstVal` :math:`EnLvl` Cell Type - ================== ============== ============== ============= =========================================== - :verilog:`negedge` ``0`` ``0`` ``0`` $_DFFE_NN0N_, $_SDFFE_NN0N_, $_SDFFCE_NN0N_ - :verilog:`negedge` ``0`` ``0`` ``1`` $_DFFE_NN0P_, $_SDFFE_NN0P_, $_SDFFCE_NN0P_ - :verilog:`negedge` ``0`` ``1`` ``0`` $_DFFE_NN1N_, $_SDFFE_NN1N_, $_SDFFCE_NN1N_ - :verilog:`negedge` ``0`` ``1`` ``1`` $_DFFE_NN1P_, $_SDFFE_NN1P_, $_SDFFCE_NN1P_ - :verilog:`negedge` ``1`` ``0`` ``0`` $_DFFE_NP0N_, $_SDFFE_NP0N_, $_SDFFCE_NP0N_ - :verilog:`negedge` ``1`` ``0`` ``1`` $_DFFE_NP0P_, $_SDFFE_NP0P_, $_SDFFCE_NP0P_ - :verilog:`negedge` ``1`` ``1`` ``0`` $_DFFE_NP1N_, $_SDFFE_NP1N_, $_SDFFCE_NP1N_ - :verilog:`negedge` ``1`` ``1`` ``1`` $_DFFE_NP1P_, $_SDFFE_NP1P_, $_SDFFCE_NP1P_ - :verilog:`posedge` ``0`` ``0`` ``0`` $_DFFE_PN0N_, $_SDFFE_PN0N_, $_SDFFCE_PN0N_ - :verilog:`posedge` ``0`` ``0`` ``1`` $_DFFE_PN0P_, $_SDFFE_PN0P_, $_SDFFCE_PN0P_ - :verilog:`posedge` ``0`` ``1`` ``0`` $_DFFE_PN1N_, $_SDFFE_PN1N_, $_SDFFCE_PN1N_ - :verilog:`posedge` ``0`` ``1`` ``1`` $_DFFE_PN1P_, $_SDFFE_PN1P_, $_SDFFCE_PN1P_ - :verilog:`posedge` ``1`` ``0`` ``0`` $_DFFE_PP0N_, $_SDFFE_PP0N_, $_SDFFCE_PP0N_ - :verilog:`posedge` ``1`` ``0`` ``1`` $_DFFE_PP0P_, $_SDFFE_PP0P_, $_SDFFCE_PP0P_ - :verilog:`posedge` ``1`` ``1`` ``0`` $_DFFE_PP1N_, $_SDFFE_PP1N_, $_SDFFCE_PP1N_ - :verilog:`posedge` ``1`` ``1`` ``1`` $_DFFE_PP1P_, $_SDFFE_PP1P_, $_SDFFCE_PP1P_ - ================== ============== ============== ============= =========================================== - -.. table:: Cell types for gate level logic networks (FFs with set and reset) - :name: tab:CellLib_gates_dffsr - - ================== ============== ============== ============ - :math:`ClkEdge` :math:`SetLvl` :math:`RstLvl` Cell Type - ================== ============== ============== ============ - :verilog:`negedge` ``0`` ``0`` $_DFFSR_NNN_ - :verilog:`negedge` ``0`` ``1`` $_DFFSR_NNP_ - :verilog:`negedge` ``1`` ``0`` $_DFFSR_NPN_ - :verilog:`negedge` ``1`` ``1`` $_DFFSR_NPP_ - :verilog:`posedge` ``0`` ``0`` $_DFFSR_PNN_ - :verilog:`posedge` ``0`` ``1`` $_DFFSR_PNP_ - :verilog:`posedge` ``1`` ``0`` $_DFFSR_PPN_ - :verilog:`posedge` ``1`` ``1`` $_DFFSR_PPP_ - ================== ============== ============== ============ - - -.. table:: Cell types for gate level logic networks (FFs with set and reset and enable) - :name: tab:CellLib_gates_dffsre - - ================== ============== ============== ============= ============== - :math:`ClkEdge` :math:`SetLvl` :math:`RstLvl` :math:`EnLvl` Cell Type - ================== ============== ============== ============= ============== - :verilog:`negedge` ``0`` ``0`` ``0`` $_DFFSRE_NNNN_ - :verilog:`negedge` ``0`` ``0`` ``1`` $_DFFSRE_NNNP_ - :verilog:`negedge` ``0`` ``1`` ``0`` $_DFFSRE_NNPN_ - :verilog:`negedge` ``0`` ``1`` ``1`` $_DFFSRE_NNPP_ - :verilog:`negedge` ``1`` ``0`` ``0`` $_DFFSRE_NPNN_ - :verilog:`negedge` ``1`` ``0`` ``1`` $_DFFSRE_NPNP_ - :verilog:`negedge` ``1`` ``1`` ``0`` $_DFFSRE_NPPN_ - :verilog:`negedge` ``1`` ``1`` ``1`` $_DFFSRE_NPPP_ - :verilog:`posedge` ``0`` ``0`` ``0`` $_DFFSRE_PNNN_ - :verilog:`posedge` ``0`` ``0`` ``1`` $_DFFSRE_PNNP_ - :verilog:`posedge` ``0`` ``1`` ``0`` $_DFFSRE_PNPN_ - :verilog:`posedge` ``0`` ``1`` ``1`` $_DFFSRE_PNPP_ - :verilog:`posedge` ``1`` ``0`` ``0`` $_DFFSRE_PPNN_ - :verilog:`posedge` ``1`` ``0`` ``1`` $_DFFSRE_PPNP_ - :verilog:`posedge` ``1`` ``1`` ``0`` $_DFFSRE_PPPN_ - :verilog:`posedge` ``1`` ``1`` ``1`` $_DFFSRE_PPPP_ - ================== ============== ============== ============= ============== - - -.. table:: Cell types for gate level logic networks (latches with reset) - :name: tab:CellLib_gates_adlatch - - ============= ============== ============== ============= - :math:`EnLvl` :math:`RstLvl` :math:`RstVal` Cell Type - ============= ============== ============== ============= - ``0`` ``0`` ``0`` $_DLATCH_NN0_ - ``0`` ``0`` ``1`` $_DLATCH_NN1_ - ``0`` ``1`` ``0`` $_DLATCH_NP0_ - ``0`` ``1`` ``1`` $_DLATCH_NP1_ - ``1`` ``0`` ``0`` $_DLATCH_PN0_ - ``1`` ``0`` ``1`` $_DLATCH_PN1_ - ``1`` ``1`` ``0`` $_DLATCH_PP0_ - ``1`` ``1`` ``1`` $_DLATCH_PP1_ - ============= ============== ============== ============= - - -.. table:: Cell types for gate level logic networks (latches with set and reset) - :name: tab:CellLib_gates_dlatchsr - - ============= ============== ============== =============== - :math:`EnLvl` :math:`SetLvl` :math:`RstLvl` Cell Type - ============= ============== ============== =============== - ``0`` ``0`` ``0`` $_DLATCHSR_NNN_ - ``0`` ``0`` ``1`` $_DLATCHSR_NNP_ - ``0`` ``1`` ``0`` $_DLATCHSR_NPN_ - ``0`` ``1`` ``1`` $_DLATCHSR_NPP_ - ``1`` ``0`` ``0`` $_DLATCHSR_PNN_ - ``1`` ``0`` ``1`` $_DLATCHSR_PNP_ - ``1`` ``1`` ``0`` $_DLATCHSR_PPN_ - ``1`` ``1`` ``1`` $_DLATCHSR_PPP_ - ============= ============== ============== =============== - - - -.. table:: Cell types for gate level logic networks (SR latches) - :name: tab:CellLib_gates_sr - - ============== ============== ========= - :math:`SetLvl` :math:`RstLvl` Cell Type - ============== ============== ========= - ``0`` ``0`` $_SR_NN_ - ``0`` ``1`` $_SR_NP_ - ``1`` ``0`` $_SR_PN_ - ``1`` ``1`` $_SR_PP_ - ============== ============== ========= - - -Tables :numref:`%s `, :numref:`%s `, -:numref:`%s `, :numref:`%s `, -:numref:`%s `, :numref:`%s `, -:numref:`%s `, :numref:`%s -` and :numref:`%s ` list all -cell types used for gate level logic. The cell types `$_BUF_`, `$_NOT_`, -`$_AND_`, `$_NAND_`, `$_ANDNOT_`, `$_OR_`, `$_NOR_`, `$_ORNOT_`, `$_XOR_`, -`$_XNOR_`, `$_AOI3_`, `$_OAI3_`, `$_AOI4_`, `$_OAI4_`, `$_MUX_`, `$_MUX4_`, -`$_MUX8_`, `$_MUX16_` and `$_NMUX_` are used to model combinatorial logic. The -cell type `$_TBUF_` is used to model tristate logic. - -The `$_MUX4_`, `$_MUX8_` and `$_MUX16_` cells are used to model wide muxes, and -correspond to the following Verilog code: - -.. code-block:: verilog - :force: - - // $_MUX4_ - assign Y = T ? (S ? D : C) : - (S ? B : A); - // $_MUX8_ - assign Y = U ? T ? (S ? H : G) : - (S ? F : E) : - T ? (S ? D : C) : - (S ? B : A); - // $_MUX16_ - assign Y = V ? U ? T ? (S ? P : O) : - (S ? N : M) : - T ? (S ? L : K) : - (S ? J : I) : - U ? T ? (S ? H : G) : - (S ? F : E) : - T ? (S ? D : C) : - (S ? B : A); - -The cell types `$_DFF_N_` and `$_DFF_P_` represent d-type flip-flops. - -The cell types ``$_DFFE_[NP][NP]_`` implement d-type flip-flops with enable. The -values in the table for these cell types relate to the following Verilog code -template. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C) - if (EN == EN_LVL) - Q <= D; - -The cell types ``$_DFF_[NP][NP][01]_`` implement d-type flip-flops with -asynchronous reset. The values in the table for these cell types relate to the -following Verilog code template, where ``RST_EDGE`` is ``posedge`` if -``RST_LVL`` if ``1``, and ``negedge`` otherwise. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C, RST_EDGE R) - if (R == RST_LVL) - Q <= RST_VAL; - else - Q <= D; - -The cell types ``$_SDFF_[NP][NP][01]_`` implement d-type flip-flops with -synchronous reset. The values in the table for these cell types relate to the -following Verilog code template: - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C) - if (R == RST_LVL) - Q <= RST_VAL; - else - Q <= D; - -The cell types ``$_DFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with -asynchronous reset and enable. The values in the table for these cell types -relate to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` -if ``RST_LVL`` if ``1``, and ``negedge`` otherwise. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C, RST_EDGE R) - if (R == RST_LVL) - Q <= RST_VAL; - else if (EN == EN_LVL) - Q <= D; - -The cell types ``$_SDFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with -synchronous reset and enable, with reset having priority over enable. The values -in the table for these cell types relate to the following Verilog code template: - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C) - if (R == RST_LVL) - Q <= RST_VAL; - else if (EN == EN_LVL) - Q <= D; - -The cell types ``$_SDFFCE_[NP][NP][01][NP]_`` implement d-type flip-flops with -synchronous reset and enable, with enable having priority over reset. The values -in the table for these cell types relate to the following Verilog code template: - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C) - if (EN == EN_LVL) - if (R == RST_LVL) - Q <= RST_VAL; - else - Q <= D; - -The cell types ``$_DFFSR_[NP][NP][NP]_`` implement d-type flip-flops with -asynchronous set and reset. The values in the table for these cell types relate -to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` if -``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is ``posedge`` if -``SET_LVL`` if ``1``, ``negedge`` otherwise. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S) - if (R == RST_LVL) - Q <= 0; - else if (S == SET_LVL) - Q <= 1; - else - Q <= D; - -The cell types ``$_DFFSRE_[NP][NP][NP][NP]_`` implement d-type flip-flops with -asynchronous set and reset and enable. The values in the table for these cell -types relate to the following Verilog code template, where ``RST_EDGE`` is -``posedge`` if ``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is -``posedge`` if ``SET_LVL`` if ``1``, ``negedge`` otherwise. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S) - if (R == RST_LVL) - Q <= 0; - else if (S == SET_LVL) - Q <= 1; - else if (E == EN_LVL) - Q <= D; - -The cell types `$_DLATCH_N_` and `$_DLATCH_P_` represent d-type latches. - -The cell types ``$_DLATCH_[NP][NP][01]_`` implement d-type latches with reset. -The values in the table for these cell types relate to the following Verilog -code template: - -.. code-block:: verilog - :force: - - always @* - if (R == RST_LVL) - Q <= RST_VAL; - else if (E == EN_LVL) - Q <= D; - -The cell types ``$_DLATCHSR_[NP][NP][NP]_`` implement d-type latches with set -and reset. The values in the table for these cell types relate to the following -Verilog code template: - -.. code-block:: verilog - :force: - - always @* - if (R == RST_LVL) - Q <= 0; - else if (S == SET_LVL) - Q <= 1; - else if (E == EN_LVL) - Q <= D; - -The cell types ``$_SR_[NP][NP]_`` implement sr-type latches. The values in the -table for these cell types relate to the following Verilog code template: - -.. code-block:: verilog - :force: - - always @* - if (R == RST_LVL) - Q <= 0; - else if (S == SET_LVL) - Q <= 1; - -In most cases gate level logic networks are created from RTL networks using the -techmap pass. The flip-flop cells from the gate level logic network can be -mapped to physical flip-flop cells from a Liberty file using the dfflibmap pass. -The combinatorial logic cells can be mapped to physical cells from a Liberty -file via ABC using the abc pass. - -.. todo:: Add information about `$slice` and `$concat` cells. - -.. todo:: Add information about `$alu`, `$fa`, and `$lcu` cells. - -.. todo:: Add information about ``$demux`` cell. \ No newline at end of file diff --git a/techlibs/common/simlib.v b/techlibs/common/simlib.v index fb294b53b..d567b7b0b 100644 --- a/techlibs/common/simlib.v +++ b/techlibs/common/simlib.v @@ -601,6 +601,7 @@ assign Y = t1 ^ C, X = (t2 | t3) ^ (Y ^ Y); endmodule // -------------------------------------------------------- +//* group arith // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- @@ -639,6 +640,7 @@ endmodule //* ver 2 //* title Arithmetic logic unit +//* group arith //- A building block supporting both binary addition/subtraction operations, and //- indirectly, comparison operations. //- Typically created by the `alumacc` pass, which transforms: @@ -1055,6 +1057,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $macc (A, B, Y) +//* group arith //- //- Multiply and accumulate. //- A building block for summing any number of negated and unnegated signals @@ -1510,6 +1513,7 @@ assign Y = {B, A}; endmodule // -------------------------------------------------------- +//* group mux // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- @@ -1530,6 +1534,7 @@ assign Y = S ? B : A; endmodule // -------------------------------------------------------- +//* group mux module \$bmux (A, S, Y); @@ -1557,6 +1562,7 @@ endgenerate endmodule // -------------------------------------------------------- +//* group mux module \$pmux (A, B, S, Y); @@ -1591,6 +1597,7 @@ end endmodule // -------------------------------------------------------- +//* group mux // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- @@ -1662,6 +1669,7 @@ end endmodule // -------------------------------------------------------- +//* group mux // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- @@ -1684,6 +1692,7 @@ assign Y = EN ? A : 'bz; endmodule // -------------------------------------------------------- +//* group spec module \$specify2 (EN, SRC, DST); @@ -1722,6 +1731,7 @@ endspecify endmodule // -------------------------------------------------------- +//* group spec module \$specify3 (EN, SRC, DST, DAT); @@ -1830,6 +1840,7 @@ endspecify endmodule // -------------------------------------------------------- +//* group spec module \$specrule (EN_SRC, EN_DST, SRC, DST); @@ -1896,6 +1907,7 @@ endgenerate endmodule // -------------------------------------------------------- +//* group formal module \$assert (A, EN); @@ -1913,6 +1925,7 @@ end endmodule // -------------------------------------------------------- +//* group formal module \$assume (A, EN); @@ -1930,6 +1943,7 @@ end endmodule // -------------------------------------------------------- +//* group formal module \$live (A, EN); @@ -1938,6 +1952,7 @@ input A, EN; endmodule // -------------------------------------------------------- +//* group formal module \$fair (A, EN); @@ -1946,6 +1961,7 @@ input A, EN; endmodule // -------------------------------------------------------- +//* group formal module \$cover (A, EN); @@ -1954,6 +1970,7 @@ input A, EN; endmodule // -------------------------------------------------------- +//* group formal module \$initstate (Y); @@ -1971,6 +1988,7 @@ end endmodule // -------------------------------------------------------- +//* group formal module \$anyconst (Y); @@ -1983,6 +2001,7 @@ assign Y = 'bx; endmodule // -------------------------------------------------------- +//* group formal module \$anyseq (Y); @@ -1999,6 +2018,7 @@ endmodule `ifndef SIMLIB_GLOBAL_CLOCK `define SIMLIB_GLOBAL_CLOCK $global_clk `endif +//* group formal module \$anyinit (D, Q); parameter WIDTH = 0; @@ -2015,6 +2035,7 @@ end endmodule `endif // -------------------------------------------------------- +//* group formal module \$allconst (Y); @@ -2027,6 +2048,7 @@ assign Y = 'bx; endmodule // -------------------------------------------------------- +//* group formal module \$allseq (Y); @@ -2039,6 +2061,7 @@ assign Y = 'bx; endmodule // -------------------------------------------------------- +//* group formal module \$equiv (A, B, Y); @@ -2059,6 +2082,7 @@ end endmodule // -------------------------------------------------------- +//* group debug module \$print (EN, TRG, ARGS); @@ -2078,6 +2102,7 @@ input [ARGS_WIDTH-1:0] ARGS; endmodule // -------------------------------------------------------- +//* group debug module \$check (A, EN, TRG, ARGS); @@ -2100,6 +2125,7 @@ endmodule // -------------------------------------------------------- `ifndef SIMLIB_NOSR +//* group reg module \$sr (SET, CLR, Q); @@ -2132,6 +2158,7 @@ endmodule `ifndef SIMLIB_GLOBAL_CLOCK `define SIMLIB_GLOBAL_CLOCK $global_clk `endif +//* group formal module \$ff (D, Q); @@ -2148,6 +2175,7 @@ endmodule `endif // -------------------------------------------------------- +//* group reg module \$dff (CLK, D, Q); @@ -2166,6 +2194,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$dffe (CLK, EN, D, Q); @@ -2186,6 +2215,7 @@ endmodule // -------------------------------------------------------- `ifndef SIMLIB_NOSR +//* group reg module \$dffsr (CLK, SET, CLR, D, Q); @@ -2218,6 +2248,7 @@ endgenerate endmodule // -------------------------------------------------------- +//* group reg module \$dffsre (CLK, SET, CLR, EN, D, Q); @@ -2252,6 +2283,7 @@ endmodule `endif // -------------------------------------------------------- +//* group reg module \$adff (CLK, ARST, D, Q); @@ -2276,6 +2308,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$aldff (CLK, ALOAD, AD, D, Q); @@ -2300,6 +2333,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$sdff (CLK, SRST, D, Q); @@ -2324,6 +2358,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$adffe (CLK, ARST, EN, D, Q); @@ -2349,6 +2384,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$aldffe (CLK, ALOAD, AD, EN, D, Q); @@ -2374,6 +2410,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$sdffe (CLK, SRST, EN, D, Q); @@ -2399,6 +2436,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$sdffce (CLK, SRST, EN, D, Q); @@ -2426,6 +2464,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$dlatch (EN, D, Q); @@ -2444,6 +2483,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$adlatch (EN, ARST, D, Q); @@ -2467,6 +2507,7 @@ endmodule // -------------------------------------------------------- `ifndef SIMLIB_NOSR +//* group reg module \$dlatchsr (EN, SET, CLR, D, Q); @@ -2500,6 +2541,7 @@ endmodule `endif // -------------------------------------------------------- +//* group fsm module \$fsm (CLK, ARST, CTRL_IN, CTRL_OUT); @@ -2594,6 +2636,7 @@ endmodule // -------------------------------------------------------- `ifndef SIMLIB_NOMEM +//* group mem module \$memrd (CLK, EN, ADDR, DATA); @@ -2618,6 +2661,8 @@ end endmodule +//* group mem + module \$memrd_v2 (CLK, EN, ARST, SRST, ADDR, DATA); parameter MEMID = ""; @@ -2647,6 +2692,7 @@ end endmodule // -------------------------------------------------------- +//* group mem module \$memwr (CLK, EN, ADDR, DATA); @@ -2672,6 +2718,7 @@ end endmodule +//* group mem module \$memwr_v2 (CLK, EN, ADDR, DATA); parameter MEMID = ""; @@ -2698,6 +2745,7 @@ end endmodule // -------------------------------------------------------- +//* group mem module \$meminit (ADDR, DATA); @@ -2721,6 +2769,7 @@ end endmodule // -------------------------------------------------------- +//* group mem module \$meminit_v2 (ADDR, DATA, EN); @@ -2745,6 +2794,7 @@ end endmodule // -------------------------------------------------------- +//* group mem module \$mem (RD_CLK, RD_EN, RD_ADDR, RD_DATA, WR_CLK, WR_EN, WR_ADDR, WR_DATA); @@ -2833,6 +2883,8 @@ end endmodule +//* group mem + module \$mem_v2 (RD_CLK, RD_EN, RD_ARST, RD_SRST, RD_ADDR, RD_DATA, WR_CLK, WR_EN, WR_ADDR, WR_DATA); parameter MEMID = ""; From 46580cebb34ff8b5020c94237be8359c0423196a Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 27 May 2024 15:47:15 +1200 Subject: [PATCH 057/496] Docs: Move rtlil_text (back) to appendix --- .../formats => appendix}/rtlil_text.rst | 4 +- docs/source/index.rst | 1 + docs/source/yosys_internals/flow/overview.rst | 2 +- docs/source/yosys_internals/formats/index.rst | 58 +++++++++++++++++-- .../yosys_internals/formats/overview.rst | 53 ----------------- 5 files changed, 56 insertions(+), 62 deletions(-) rename docs/source/{yosys_internals/formats => appendix}/rtlil_text.rst (98%) delete mode 100644 docs/source/yosys_internals/formats/overview.rst diff --git a/docs/source/yosys_internals/formats/rtlil_text.rst b/docs/source/appendix/rtlil_text.rst similarity index 98% rename from docs/source/yosys_internals/formats/rtlil_text.rst rename to docs/source/appendix/rtlil_text.rst index 8b5c10681..7febae2ed 100644 --- a/docs/source/yosys_internals/formats/rtlil_text.rst +++ b/docs/source/appendix/rtlil_text.rst @@ -223,8 +223,8 @@ Cells Declares a cell, with zero or more attributes, with the given identifier and type in the enclosing module. -Cells perform functions on input signals. See -:doc:`/yosys_internals/formats/cell_library` for a detailed list of cell types. +Cells perform functions on input signals. See :doc:`/cell_gate` and +:doc:`/cell_word` for a detailed list of cell types. .. code:: BNF diff --git a/docs/source/index.rst b/docs/source/index.rst index ce612f9b0..fbdd5ac6f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -44,6 +44,7 @@ available, go to :ref:`commandindex`. :includehidden: appendix/primer + appendix/rtlil_text appendix/auxlibs appendix/auxprogs diff --git a/docs/source/yosys_internals/flow/overview.rst b/docs/source/yosys_internals/flow/overview.rst index b357e5b50..3effe462b 100644 --- a/docs/source/yosys_internals/flow/overview.rst +++ b/docs/source/yosys_internals/flow/overview.rst @@ -20,7 +20,7 @@ given in :doc:`/yosys_internals/formats/rtlil_rep`. There is also a text representation of the RTLIL data structure that can be parsed using the RTLIL Frontend which is described in -:doc:`/yosys_internals/formats/rtlil_text`. +:doc:`/appendix/rtlil_text`. The design data may then be transformed using a series of passes that all operate on the RTLIL representation of the design. diff --git a/docs/source/yosys_internals/formats/index.rst b/docs/source/yosys_internals/formats/index.rst index c187a8238..611370ebc 100644 --- a/docs/source/yosys_internals/formats/index.rst +++ b/docs/source/yosys_internals/formats/index.rst @@ -1,13 +1,59 @@ Internal formats ================ -.. todo:: brief overview for the internal formats index +Yosys uses two different internal formats. The first is used to store an +abstract syntax tree (AST) of a Verilog input file. This format is simply called +AST and is generated by the Verilog Frontend. This data structure is consumed by +a subsystem called AST Frontend [1]_. This AST Frontend then generates a design +in Yosys' main internal format, the +Register-Transfer-Level-Intermediate-Language (RTLIL) representation. It does +that by first performing a number of simplifications within the AST +representation and then generating RTLIL from the simplified AST data structure. + +The RTLIL representation is used by all passes as input and outputs. This has +the following advantages over using different representational formats between +different passes: + +- The passes can be rearranged in a different order and passes can be removed + or inserted. + +- Passes can simply pass-thru the parts of the design they don't change without + the need to convert between formats. In fact Yosys passes output the same + data structure they received as input and performs all changes in place. + +- All passes use the same interface, thus reducing the effort required to + understand a pass when reading the Yosys source code, e.g. when adding + additional features. + +The RTLIL representation is basically a netlist representation with the +following additional features: + +- An internal cell library with fixed-function cells to represent RTL datapath + and register cells as well as logical gate-level cells (single-bit gates and + registers). + +- Support for multi-bit values that can use individual bits from wires as well + as constant bits to represent coarse-grain netlists. + +- Support for basic behavioural constructs (if-then-else structures and + multi-case switches with a sensitivity list for updating the outputs). + +- Support for multi-port memories. + +The use of RTLIL also has the disadvantage of having a very powerful format +between all passes, even when doing gate-level synthesis where the more advanced +features are not needed. In order to reduce complexity for passes that operate +on a low-level representation, these passes check the features used in the input +RTLIL and fail to run when unsupported high-level constructs are used. In such +cases a pass that transforms the higher-level constructs to lower-level +constructs must be called from the synthesis script first. .. toctree:: - :maxdepth: 3 + :maxdepth: 3 - overview - rtlil_rep - rtlil_text - cell_library + rtlil_rep + +.. [1] + In Yosys the term pass is only used to refer to commands that operate on the + RTLIL data structure. diff --git a/docs/source/yosys_internals/formats/overview.rst b/docs/source/yosys_internals/formats/overview.rst deleted file mode 100644 index cbf5369bc..000000000 --- a/docs/source/yosys_internals/formats/overview.rst +++ /dev/null @@ -1,53 +0,0 @@ -Format overview -=============== - -Yosys uses two different internal formats. The first is used to store an -abstract syntax tree (AST) of a Verilog input file. This format is simply called -AST and is generated by the Verilog Frontend. This data structure is consumed by -a subsystem called AST Frontend [1]_. This AST Frontend then generates a design -in Yosys' main internal format, the -Register-Transfer-Level-Intermediate-Language (RTLIL) representation. It does -that by first performing a number of simplifications within the AST -representation and then generating RTLIL from the simplified AST data structure. - -The RTLIL representation is used by all passes as input and outputs. This has -the following advantages over using different representational formats between -different passes: - -- The passes can be rearranged in a different order and passes can be removed - or inserted. - -- Passes can simply pass-thru the parts of the design they don't change without - the need to convert between formats. In fact Yosys passes output the same - data structure they received as input and performs all changes in place. - -- All passes use the same interface, thus reducing the effort required to - understand a pass when reading the Yosys source code, e.g. when adding - additional features. - -The RTLIL representation is basically a netlist representation with the -following additional features: - -- An internal cell library with fixed-function cells to represent RTL datapath - and register cells as well as logical gate-level cells (single-bit gates and - registers). - -- Support for multi-bit values that can use individual bits from wires as well - as constant bits to represent coarse-grain netlists. - -- Support for basic behavioural constructs (if-then-else structures and - multi-case switches with a sensitivity list for updating the outputs). - -- Support for multi-port memories. - -The use of RTLIL also has the disadvantage of having a very powerful format -between all passes, even when doing gate-level synthesis where the more advanced -features are not needed. In order to reduce complexity for passes that operate -on a low-level representation, these passes check the features used in the input -RTLIL and fail to run when unsupported high-level constructs are used. In such -cases a pass that transforms the higher-level constructs to lower-level -constructs must be called from the synthesis script first. - -.. [1] - In Yosys the term pass is only used to refer to commands that operate on the - RTLIL data structure. \ No newline at end of file From 2b4a4cb536edcbb03af9ac2277a8db53eae19a4c Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 27 May 2024 15:48:00 +1200 Subject: [PATCH 058/496] Docs: Fix fsm.rst `$mux-tree` should be `$mux`-tree. --- docs/source/using_yosys/synthesis/fsm.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/source/using_yosys/synthesis/fsm.rst b/docs/source/using_yosys/synthesis/fsm.rst index cc3d0879d..9a0e045cc 100644 --- a/docs/source/using_yosys/synthesis/fsm.rst +++ b/docs/source/using_yosys/synthesis/fsm.rst @@ -63,12 +63,10 @@ information is determined: The state registers (and asynchronous reset state, if applicable) is simply determined by identifying the driver for the state signal. -.. todo:: Figure out what `$mux-tree` should actually be. - -From there the `$mux-tree` driving the state register inputs is recursively -traversed. All select inputs are control signals and the leaves of the -`$mux-tree` are the states. The algorithm fails if a non-constant leaf that is -not the state signal itself is found. +From there the `$mux`\ -tree driving the state register inputs is recursively +traversed. All select inputs are control signals and the leaves of the `$mux`\ +-tree are the states. The algorithm fails if a non-constant leaf that is not the +state signal itself is found. The list of control outputs is initialized with the bits from the state signal. It is then extended by adding all values that are calculated by cells that From be5572ca0e3640c6d3365b64daab3ffec0c5e08c Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 27 May 2024 16:02:17 +1200 Subject: [PATCH 059/496] Docs: Less leading backslashes --- docs/source/using_yosys/synthesis/fsm.rst | 16 ++++++++-------- docs/source/using_yosys/synthesis/opt.rst | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/source/using_yosys/synthesis/fsm.rst b/docs/source/using_yosys/synthesis/fsm.rst index 9a0e045cc..6fad81d54 100644 --- a/docs/source/using_yosys/synthesis/fsm.rst +++ b/docs/source/using_yosys/synthesis/fsm.rst @@ -19,24 +19,24 @@ FSM detection ~~~~~~~~~~~~~ The `fsm_detect` pass identifies FSM state registers. It sets the -``\fsm_encoding = "auto"`` attribute on any (multi-bit) wire that matches the +``fsm_encoding = "auto"`` attribute on any (multi-bit) wire that matches the following description: -- Does not already have the ``\fsm_encoding`` attribute. +- Does not already have the ``fsm_encoding`` attribute. - Is not an output of the containing module. - Is driven by single `$dff` or `$adff` cell. -- The ``\D``-Input of this `$dff` or `$adff` cell is driven by a multiplexer +- The ``D``-Input of this `$dff` or `$adff` cell is driven by a multiplexer tree that only has constants or the old state value on its leaves. - The state value is only used in the said multiplexer tree or by simple relational cells that compare the state value to a constant (usually `$eq` cells). This heuristic has proven to work very well. It is possible to overwrite it by -setting ``\fsm_encoding = "auto"`` on registers that should be considered FSM -state registers and setting ``\fsm_encoding = "none"`` on registers that match +setting ``fsm_encoding = "auto"`` on registers that should be considered FSM +state registers and setting ``fsm_encoding = "none"`` on registers that match the above criteria but should not be considered FSM state registers. -Note however that marking state registers with ``\fsm_encoding`` that are not +Note however that marking state registers with ``fsm_encoding`` that are not suitable for FSM recoding can cause synthesis to fail or produce invalid results. @@ -44,7 +44,7 @@ FSM extraction ~~~~~~~~~~~~~~ The `fsm_extract` pass operates on all state signals marked with the -(``\fsm_encoding != "none"``) attribute. For each state signal the following +(``fsm_encoding != "none"``) attribute. For each state signal the following information is determined: - The state registers @@ -109,7 +109,7 @@ The `fsm_opt` pass performs basic optimizations on `$fsm` cells (not including state recoding). The following optimizations are performed (in this order): - Unused control outputs are removed from the `$fsm` cell. The attribute - ``\unused_bits`` (that is usually set by the `opt_clean` pass) is used to + ``unused_bits`` (that is usually set by the `opt_clean` pass) is used to determine which control outputs are unused. - Control inputs that are connected to the same driver are merged. diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst index 87763dbbe..d79a66a75 100644 --- a/docs/source/using_yosys/synthesis/opt.rst +++ b/docs/source/using_yosys/synthesis/opt.rst @@ -196,7 +196,7 @@ Removing unused cells and wires - `opt_clean` pass ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This pass identifies unused signals and cells and removes them from the design. -It also creates an ``\unused_bits`` attribute on wires with unused bits. This +It also creates an ``unused_bits`` attribute on wires with unused bits. This attribute can be used for debugging or by other optimization passes. When to use `opt` or `clean` From 6aceb6a29786426f0ee60551496d98e1c1b918a3 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 27 May 2024 16:32:45 +1200 Subject: [PATCH 060/496] cmdref.py: Support autoref for 'help ' --- docs/util/cmdref.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/util/cmdref.py b/docs/util/cmdref.py index 6fbd81372..c7bb4e241 100644 --- a/docs/util/cmdref.py +++ b/docs/util/cmdref.py @@ -430,9 +430,12 @@ class CellDomain(CommandDomain): TagIndex } -def autoref(name, rawtext, text, lineno, inliner: Inliner, +def autoref(name, rawtext: str, text: str, lineno, inliner: Inliner, options=None, content=None): role = 'cell:ref' if text[0] == '$' else 'cmd:ref' + if text.startswith("help ") and text.count(' ') == 1: + _, cmd = text.split(' ', 1) + text = f'{text} <{cmd}>' return inliner.interpreted(rawtext, text, role, lineno) def setup(app: Sphinx): From e78841ba45b53e0b2370583ba57d22d6828383a3 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 27 May 2024 16:33:00 +1200 Subject: [PATCH 061/496] Docs: Fix invalid autorefs --- docs/source/getting_started/installation.rst | 4 ++-- docs/source/using_yosys/synthesis/techmap_synth.rst | 4 ++-- docs/source/yosys_internals/extending_yosys/extensions.rst | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst index 5fed508ed..57ae53036 100644 --- a/docs/source/getting_started/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -109,7 +109,7 @@ Installing all prerequisites for macOS 11 (with Homebrew): Running the build system ^^^^^^^^^^^^^^^^^^^^^^^^ -From the root `yosys` directory, call the following commands: +From the root ``yosys`` directory, call the following commands: .. code:: console @@ -117,7 +117,7 @@ From the root `yosys` directory, call the following commands: sudo make install This will build and then install Yosys, making it available on the command line -as `yosys`. Note that this also downloads, builds, and installs `ABC`_ (using +as ``yosys``. Note that this also downloads, builds, and installs `ABC`_ (using :program:`yosys-abc` as the executable name). .. _ABC: https://github.com/berkeley-abc/abc diff --git a/docs/source/using_yosys/synthesis/techmap_synth.rst b/docs/source/using_yosys/synthesis/techmap_synth.rst index dc9d8b195..9e9d42df5 100644 --- a/docs/source/using_yosys/synthesis/techmap_synth.rst +++ b/docs/source/using_yosys/synthesis/techmap_synth.rst @@ -29,8 +29,8 @@ provided implementation. When no map file is provided, techmap uses a built-in map file that maps the Yosys RTL cell types to the internal gate library used by Yosys. The curious -reader may find this map file as `techlibs/common/techmap.v` in the Yosys source -tree. +reader may find this map file as :file:`techlibs/common/techmap.v` in the Yosys +source tree. Additional features have been added to techmap to allow for conditional mapping of cells (see :doc:`/cmd/techmap`). This can for example be useful if the target diff --git a/docs/source/yosys_internals/extending_yosys/extensions.rst b/docs/source/yosys_internals/extending_yosys/extensions.rst index 88e001d06..4063641d4 100644 --- a/docs/source/yosys_internals/extending_yosys/extensions.rst +++ b/docs/source/yosys_internals/extending_yosys/extensions.rst @@ -11,9 +11,9 @@ Writing extensions This chapter contains some bits and pieces of information about programming yosys extensions. Don't be afraid to ask questions on the YosysHQ Slack. -The `guidelines/` directory of the Yosys source code contains notes on various -aspects of Yosys development. In particular, the files GettingStarted and -CodingStyle may be of interest. +The :file:`guidelines/` directory of the Yosys source code contains notes on +various aspects of Yosys development. In particular, the files GettingStarted +and CodingStyle may be of interest. .. todo:: what's in guidelines/GettingStarted that's missing from the manual? From 11d2cbced24b14690bb73abe57ca95b9cb894361 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 27 May 2024 16:42:06 +1200 Subject: [PATCH 062/496] Docs: Don't delete source/cell on make clean --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index 9be050d35..6dbf6f490 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -47,7 +47,7 @@ help: .PHONY: clean clean: clean-examples rm -rf $(BUILDDIR)/* - rm -rf source/cell source/cmd util/__pycache__ + rm -rf source/cmd util/__pycache__ rm -rf source/generated $(MAKE) -C source/_images clean From c6414e08ebf6368c10dd17ab57e065c35b58503a Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Sat, 8 Jun 2024 15:41:52 +1200 Subject: [PATCH 063/496] Docs: Switch to furo-ys for YoscryptLexer --- docs/source/conf.py | 2 +- docs/util/YoscryptLexer.py | 73 -------------------------------------- 2 files changed, 1 insertion(+), 74 deletions(-) delete mode 100644 docs/util/YoscryptLexer.py diff --git a/docs/source/conf.py b/docs/source/conf.py index 8e504df55..babbc9b53 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -87,5 +87,5 @@ def setup(app: Sphinx) -> None: from util.RtlilLexer import RtlilLexer app.add_lexer("RTLIL", RtlilLexer) - from util.YoscryptLexer import YoscryptLexer + from furo_ys.lexers.YoscryptLexer import YoscryptLexer app.add_lexer("yoscrypt", YoscryptLexer) diff --git a/docs/util/YoscryptLexer.py b/docs/util/YoscryptLexer.py deleted file mode 100644 index 8cb31c81a..000000000 --- a/docs/util/YoscryptLexer.py +++ /dev/null @@ -1,73 +0,0 @@ -from pygments.lexer import RegexLexer, bygroups, include -from pygments.token import (Comment, Error, Keyword, Name, Number, Operator, - String, Whitespace) - -__all__ = ['YoscryptLexer'] - -class YoscryptLexer(RegexLexer): - name = 'Yosys Script' - aliases = ['yoscrypt'] - filenames = ['*.ys'] - - - - tokens = { - 'common': [ - (r'\s+', Whitespace), - (r'#.*', Comment.Single), - (r'"', String, 'string'), - (r'(\d+)(\')([bdho]? ?\w+)', bygroups(Number, Operator, Number)), - (r'(\d+\.\d+)', Number.Float), - (r'(\d+)', Number), - (r'(\$[A-Za-z_0-9]*)', Name.Builtin), - (r'([A-Za-z_][A-Za-z_0-9\.\\/:-]*)', Name), - (r'(\[)(-\S*)(\])', # optional command - bygroups(Operator, Name.Attribute, Operator)), - (r'([\[<]\w*[\]>])', Name), # arguments - (r'[\{\}\|=\[\],]', Operator), - (r'.', Comment), - ], - 'root': [ - (r'([A-Za-z_][A-Za-z_0-9]*)', Keyword, 'command'), - (r'(-[A-Za-z_][A-Za-z_0-9]*)', Name.Attribute, 'command'), # shortcut for options - include('common'), - ], - 'command': [ - (r'(-[A-Za-z_][A-Za-z_0-9]*)', Name.Attribute), - (r'\+/[^\s]+', Name.Class), - (r'$', Whitespace, '#pop'), - (r';(?=\s)', Operator, '#pop'), - (r';{2,3}(?=\s)', Name.Class, '#pop'), - (r';{1,3}', Error, '#pop'), - (r'([ANwismctparn]:)', Keyword.Type, 'pattern'), - (r'@', Keyword.Type), - (r'%(x|ci|co)e?', Keyword.Type, 'expansion'), - (r'%[%nuidDcasmMCR]?', Keyword.Type), - (r'/', Operator), - include('common'), - ], - 'pattern': [ - (r'<<', Name), # Not an operator - (r'(=|<|<=|>|>=)', Operator), - (r':', Keyword.Type), - (r'$', Whitespace, '#pop:2'), - (r'\s+', Whitespace, '#pop'), - include('common'), - ], - 'expansion': [ - (r'$', Name.Class, '#pop:2'), - (r';(?=\s)', Operator, '#pop:2'), - (r';{2,3}(?=\s)', Name.Class, '#pop:2'), - (r'\s', Whitespace, '#pop'), - (r'[0-9\*]{1,3}', Number), - (r'[:+-,\[\]]', Operator), - include('common'), - ], - 'string': [ - (r'"', String, '#pop'), - (r'\\([\\abfnrtv"\']|x[a-fA-F0-9]{2,4}|[0-7]{1,3})', String.Escape), - (r'[^\\"\n]+', String), # all other characters - (r'(\\)(\n)', bygroups(String.Escape, Whitespace)), # line continuation - (r'\\', String), # stray backslash - ] - } From 78b9dbd4eab8b3ac5c35590e78649c5eb44d0b13 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 27 Aug 2024 10:48:28 +1200 Subject: [PATCH 064/496] Docs: Assign remaining word cells to groups Move todos to correct place. Add todo for x-prop cells. --- docs/source/cell/word_arith.rst | 2 ++ docs/source/cell/word_binary.rst | 2 ++ docs/source/cell/word_formal.rst | 8 ++++++++ docs/source/cell/word_wire.rst | 9 +++++++++ docs/source/cell_word.rst | 6 +++--- techlibs/common/simlib.v | 22 +++++++++++----------- 6 files changed, 35 insertions(+), 14 deletions(-) create mode 100644 docs/source/cell/word_wire.rst diff --git a/docs/source/cell/word_arith.rst b/docs/source/cell/word_arith.rst index 38111a7d5..eb1bfdada 100644 --- a/docs/source/cell/word_arith.rst +++ b/docs/source/cell/word_arith.rst @@ -1,6 +1,8 @@ Coarse arithmetics ------------------ +.. todo:: Add information about `$alu`, `$fa`, and `$lcu` cells. + Multiply-accumulate ~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/cell/word_binary.rst b/docs/source/cell/word_binary.rst index 47a847ee4..68bc5a3aa 100644 --- a/docs/source/cell/word_binary.rst +++ b/docs/source/cell/word_binary.rst @@ -4,6 +4,8 @@ Binary operators ~~~~~~~~~~~~~~~~ +.. todo:: Add detail on ``$*x`` cells, `$eqx`, `$nex`, `$bweqx`, `$shiftx` + All binary RTL cells have two input ports ``A`` and ``B`` and one output port ``Y``. They also have the following parameters: diff --git a/docs/source/cell/word_formal.rst b/docs/source/cell/word_formal.rst index 81bab8988..ae0f56025 100644 --- a/docs/source/cell/word_formal.rst +++ b/docs/source/cell/word_formal.rst @@ -12,3 +12,11 @@ Formal verification cells :members: :source: :linenos: + +Formal support cells +~~~~~~~~~~~~~~~~~~~~ + +.. autocellgroup:: formal_tag + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_wire.rst b/docs/source/cell/word_wire.rst new file mode 100644 index 000000000..0434cceae --- /dev/null +++ b/docs/source/cell/word_wire.rst @@ -0,0 +1,9 @@ +Wire cells +------------------------- + +.. todo:: Add information about `$slice` and `$concat` cells. + +.. autocellgroup:: wire + :members: + :source: + :linenos: diff --git a/docs/source/cell_word.rst b/docs/source/cell_word.rst index a736801fa..3c87d9913 100644 --- a/docs/source/cell_word.rst +++ b/docs/source/cell_word.rst @@ -27,10 +27,10 @@ Simulation models for the RTL cells can be found in the file /cell/word_spec /cell/word_formal /cell/word_debug + /cell/word_wire -.. todo:: Add information about `$slice` and `$concat` cells. - -.. todo:: Add information about `$alu`, `$fa`, and `$lcu` cells. +.. this should raise a warning, otherwise there are word-level cells without a + 'group' tag .. autocellgroup:: word_other :caption: Other word-level cells diff --git a/techlibs/common/simlib.v b/techlibs/common/simlib.v index d567b7b0b..a954b64ec 100644 --- a/techlibs/common/simlib.v +++ b/techlibs/common/simlib.v @@ -585,7 +585,7 @@ endgenerate endmodule // -------------------------------------------------------- - +//* group arith module \$fa (A, B, C, X, Y); parameter WIDTH = 1; @@ -1477,7 +1477,7 @@ endgenerate endmodule // -------------------------------------------------------- - +//* group wire module \$slice (A, Y); parameter OFFSET = 0; @@ -1492,10 +1492,10 @@ assign Y = A >> OFFSET; endmodule // -------------------------------------------------------- - // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $concat (A, B, Y) +//* group wire //- //- Concatenation of inputs into a single output ( Y = {B, A} ). //- @@ -1870,7 +1870,7 @@ endspecify endmodule // -------------------------------------------------------- - +//* group binary module \$bweqx (A, B, Y); parameter WIDTH = 0; @@ -1888,7 +1888,7 @@ endgenerate endmodule // -------------------------------------------------------- - +//* group mux module \$bwmux (A, B, S, Y); parameter WIDTH = 0; @@ -3004,7 +3004,7 @@ endmodule `endif // -------------------------------------------------------- - +//* group formal_tag module \$set_tag (A, SET, CLR, Y); parameter TAG = ""; @@ -3020,7 +3020,7 @@ assign Y = A; endmodule // -------------------------------------------------------- - +//* group formal_tag module \$get_tag (A, Y); parameter TAG = ""; @@ -3034,7 +3034,7 @@ assign Y = A; endmodule // -------------------------------------------------------- - +//* group formal_tag module \$overwrite_tag (A, SET, CLR); parameter TAG = ""; @@ -3047,7 +3047,7 @@ input [WIDTH-1:0] CLR; endmodule // -------------------------------------------------------- - +//* group formal_tag module \$original_tag (A, Y); parameter TAG = ""; @@ -3061,7 +3061,7 @@ assign Y = A; endmodule // -------------------------------------------------------- - +//* group formal_tag module \$future_ff (A, Y); parameter WIDTH = 0; @@ -3074,7 +3074,7 @@ assign Y = A; endmodule // -------------------------------------------------------- - +//* group debug (* noblackbox *) module \$scopeinfo (); From 596d914eada3c0402061d8231417cc6e4b60a78b Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 29 Aug 2024 10:43:25 +1200 Subject: [PATCH 065/496] simcells: Apply group tags --- techlibs/common/gen_fine_ffs.py | 16 ++++ techlibs/common/simcells.v | 148 ++++++++++++++++++++++++++++++++ 2 files changed, 164 insertions(+) diff --git a/techlibs/common/gen_fine_ffs.py b/techlibs/common/gen_fine_ffs.py index 25c6ef171..9d4314ffa 100644 --- a/techlibs/common/gen_fine_ffs.py +++ b/techlibs/common/gen_fine_ffs.py @@ -3,6 +3,7 @@ TEMPLATES = [ // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SR_{S:N|P}{R:N|P}_ (S, R, Q) +//* group reg_latch //- //- A set-reset latch with {S:negative|positive} polarity SET and {R:negative|positive} polarity RESET. //- @@ -28,6 +29,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_FF_ (D, Q) +//* group reg_ff //- //- A D-type flip-flop that is clocked from the implicit global clock. (This cell //- type is usually only used in netlists for formal verification.) @@ -45,6 +47,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFF_{C:N|P}_ (D, C, Q) +//* group reg_ff //- //- A {C:negative|positive} edge D-type flip-flop. //- @@ -65,6 +68,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_{C:N|P}{E:N|P}_ (D, C, E, Q) +//* group reg_ff //- //- A {C:negative|positive} edge D-type flip-flop with {E:negative|positive} polarity enable. //- @@ -85,6 +89,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFF_{C:N|P}{R:N|P}{V:0|1}_ (D, C, R, Q) +//* group reg_ff //- //- A {C:negative|positive} edge D-type flip-flop with {R:negative|positive} polarity {V:reset|set}. //- @@ -109,6 +114,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_{C:N|P}{R:N|P}{V:0|1}{E:N|P}_ (D, C, R, E, Q) +//* group reg_ff //- //- A {C:negative|positive} edge D-type flip-flop with {R:negative|positive} polarity {V:reset|set} and {E:negative|positive} //- polarity clock enable. @@ -134,6 +140,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ALDFF_{C:N|P}{L:N|P}_ (D, C, L, AD, Q) +//* group reg_ff //- //- A {C:negative|positive} edge D-type flip-flop with {L:negative|positive} polarity async load. //- @@ -158,6 +165,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ALDFFE_{C:N|P}{L:N|P}{E:N|P}_ (D, C, L, AD, E, Q) +//* group reg_ff //- //- A {C:negative|positive} edge D-type flip-flop with {L:negative|positive} polarity async load and {E:negative|positive} //- polarity clock enable. @@ -183,6 +191,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSR_{C:N|P}{S:N|P}{R:N|P}_ (C, S, R, D, Q) +//* group reg_ff //- //- A {C:negative|positive} edge D-type flip-flop with {S:negative|positive} polarity set and {R:negative|positive} //- polarity reset. @@ -211,6 +220,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_{C:N|P}{S:N|P}{R:N|P}{E:N|P}_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A {C:negative|positive} edge D-type flip-flop with {S:negative|positive} polarity set, {R:negative|positive} //- polarity reset and {E:negative|positive} polarity clock enable. @@ -239,6 +249,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFF_{C:N|P}{R:N|P}{V:0|1}_ (D, C, R, Q) +//* group reg_ff //- //- A {C:negative|positive} edge D-type flip-flop with {R:negative|positive} polarity synchronous {V:reset|set}. //- @@ -263,6 +274,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_{C:N|P}{R:N|P}{V:0|1}{E:N|P}_ (D, C, R, E, Q) +//* group reg_ff //- //- A {C:negative|positive} edge D-type flip-flop with {R:negative|positive} polarity synchronous {V:reset|set} and {E:negative|positive} //- polarity clock enable (with {V:reset|set} having priority). @@ -288,6 +300,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_{C:N|P}{R:N|P}{V:0|1}{E:N|P}_ (D, C, R, E, Q) +//* group reg_ff //- //- A {C:negative|positive} edge D-type flip-flop with {R:negative|positive} polarity synchronous {V:reset|set} and {E:negative|positive} //- polarity clock enable (with clock enable having priority). @@ -315,6 +328,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCH_{E:N|P}_ (E, D, Q) +//* group reg_latch //- //- A {E:negative|positive} enable D-type latch. //- @@ -336,6 +350,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCH_{E:N|P}{R:N|P}{V:0|1}_ (E, R, D, Q) +//* group reg_latch //- //- A {E:negative|positive} enable D-type latch with {R:negative|positive} polarity {V:reset|set}. //- @@ -360,6 +375,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCHSR_{E:N|P}{S:N|P}{R:N|P}_ (E, S, R, D, Q) +//* group reg_latch //- //- A {E:negative|positive} enable D-type latch with {S:negative|positive} polarity set and {R:negative|positive} //- polarity reset. diff --git a/techlibs/common/simcells.v b/techlibs/common/simcells.v index ad1fdc817..104022079 100644 --- a/techlibs/common/simcells.v +++ b/techlibs/common/simcells.v @@ -28,6 +28,7 @@ // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_BUF_ (A, Y) +//* group comb_simple //- //- A buffer. This cell type is always optimized away by the opt_clean pass. //- @@ -45,6 +46,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_NOT_ (A, Y) +//* group comb_simple //- //- An inverter gate. //- @@ -62,6 +64,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_AND_ (A, B, Y) +//* group comb_simple //- //- A 2-input AND gate. //- @@ -81,6 +84,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_NAND_ (A, B, Y) +//* group comb_simple //- //- A 2-input NAND gate. //- @@ -100,6 +104,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_OR_ (A, B, Y) +//* group comb_simple //- //- A 2-input OR gate. //- @@ -119,6 +124,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_NOR_ (A, B, Y) +//* group comb_simple //- //- A 2-input NOR gate. //- @@ -138,6 +144,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_XOR_ (A, B, Y) +//* group comb_simple //- //- A 2-input XOR gate. //- @@ -157,6 +164,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_XNOR_ (A, B, Y) +//* group comb_simple //- //- A 2-input XNOR gate. //- @@ -176,6 +184,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ANDNOT_ (A, B, Y) +//* group comb_combined //- //- A 2-input AND-NOT gate. //- @@ -195,6 +204,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ORNOT_ (A, B, Y) +//* group comb_combined //- //- A 2-input OR-NOT gate. //- @@ -214,6 +224,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_MUX_ (A, B, S, Y) +//* group comb_simple //- //- A 2-input MUX gate. //- @@ -233,6 +244,7 @@ endmodule //- $_NMUX_ (A, B, S, Y) //- //- A 2-input inverting MUX gate. +//* group comb_combined //- //- Truth table: A B S | Y //- -------+--- @@ -250,6 +262,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_MUX4_ (A, B, C, D, S, T, Y) +//* group comb_combined //- //- A 4-input MUX gate. //- @@ -270,6 +283,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_MUX8_ (A, B, C, D, E, F, G, H, S, T, U, Y) +//* group comb_combined //- //- An 8-input MUX gate. //- @@ -296,6 +310,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_MUX16_ (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, S, T, U, V, Y) +//* group comb_combined //- //- A 16-input MUX gate. //- @@ -334,6 +349,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_AOI3_ (A, B, C, Y) +//* group comb_combined //- //- A 3-input And-Or-Invert gate. //- @@ -357,6 +373,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_OAI3_ (A, B, C, Y) +//* group comb_combined //- //- A 3-input Or-And-Invert gate. //- @@ -380,6 +397,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_AOI4_ (A, B, C, Y) +//* group comb_combined //- //- A 4-input And-Or-Invert gate. //- @@ -411,6 +429,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_OAI4_ (A, B, C, Y) +//* group comb_combined //- //- A 4-input Or-And-Invert gate. //- @@ -464,6 +483,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SR_NN_ (S, R, Q) +//* group reg_latch //- //- A set-reset latch with negative polarity SET and negative polarity RESET. //- @@ -487,6 +507,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SR_NP_ (S, R, Q) +//* group reg_latch //- //- A set-reset latch with negative polarity SET and positive polarity RESET. //- @@ -510,6 +531,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SR_PN_ (S, R, Q) +//* group reg_latch //- //- A set-reset latch with positive polarity SET and negative polarity RESET. //- @@ -533,6 +555,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SR_PP_ (S, R, Q) +//* group reg_latch //- //- A set-reset latch with positive polarity SET and positive polarity RESET. //- @@ -557,6 +580,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_FF_ (D, Q) +//* group reg_ff //- //- A D-type flip-flop that is clocked from the implicit global clock. (This cell //- type is usually only used in netlists for formal verification.) @@ -573,6 +597,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFF_N_ (D, C, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop. //- @@ -592,6 +617,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFF_P_ (D, C, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop. //- @@ -611,6 +637,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_NN_ (D, C, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity enable. //- @@ -630,6 +657,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_NP_ (D, C, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity enable. //- @@ -649,6 +677,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_PN_ (D, C, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity enable. //- @@ -668,6 +697,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_PP_ (D, C, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity enable. //- @@ -687,6 +717,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFF_NN0_ (D, C, R, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity reset. //- @@ -710,6 +741,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFF_NN1_ (D, C, R, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity set. //- @@ -733,6 +765,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFF_NP0_ (D, C, R, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity reset. //- @@ -756,6 +789,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFF_NP1_ (D, C, R, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity set. //- @@ -779,6 +813,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFF_PN0_ (D, C, R, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity reset. //- @@ -802,6 +837,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFF_PN1_ (D, C, R, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity set. //- @@ -825,6 +861,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFF_PP0_ (D, C, R, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity reset. //- @@ -848,6 +885,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFF_PP1_ (D, C, R, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity set. //- @@ -871,6 +909,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_NN0N_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity reset and negative //- polarity clock enable. @@ -895,6 +934,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_NN0P_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity reset and positive //- polarity clock enable. @@ -919,6 +959,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_NN1N_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity set and negative //- polarity clock enable. @@ -943,6 +984,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_NN1P_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity set and positive //- polarity clock enable. @@ -967,6 +1009,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_NP0N_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity reset and negative //- polarity clock enable. @@ -991,6 +1034,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_NP0P_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity reset and positive //- polarity clock enable. @@ -1015,6 +1059,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_NP1N_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity set and negative //- polarity clock enable. @@ -1039,6 +1084,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_NP1P_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity set and positive //- polarity clock enable. @@ -1063,6 +1109,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_PN0N_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity reset and negative //- polarity clock enable. @@ -1087,6 +1134,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_PN0P_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity reset and positive //- polarity clock enable. @@ -1111,6 +1159,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_PN1N_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity set and negative //- polarity clock enable. @@ -1135,6 +1184,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_PN1P_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity set and positive //- polarity clock enable. @@ -1159,6 +1209,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_PP0N_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity reset and negative //- polarity clock enable. @@ -1183,6 +1234,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_PP0P_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity reset and positive //- polarity clock enable. @@ -1207,6 +1259,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_PP1N_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity set and negative //- polarity clock enable. @@ -1231,6 +1284,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFE_PP1P_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity set and positive //- polarity clock enable. @@ -1255,6 +1309,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ALDFF_NN_ (D, C, L, AD, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity async load. //- @@ -1278,6 +1333,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ALDFF_NP_ (D, C, L, AD, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity async load. //- @@ -1301,6 +1357,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ALDFF_PN_ (D, C, L, AD, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity async load. //- @@ -1324,6 +1381,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ALDFF_PP_ (D, C, L, AD, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity async load. //- @@ -1347,6 +1405,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ALDFFE_NNN_ (D, C, L, AD, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity async load and negative //- polarity clock enable. @@ -1371,6 +1430,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ALDFFE_NNP_ (D, C, L, AD, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity async load and positive //- polarity clock enable. @@ -1395,6 +1455,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ALDFFE_NPN_ (D, C, L, AD, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity async load and negative //- polarity clock enable. @@ -1419,6 +1480,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ALDFFE_NPP_ (D, C, L, AD, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity async load and positive //- polarity clock enable. @@ -1443,6 +1505,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ALDFFE_PNN_ (D, C, L, AD, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity async load and negative //- polarity clock enable. @@ -1467,6 +1530,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ALDFFE_PNP_ (D, C, L, AD, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity async load and positive //- polarity clock enable. @@ -1491,6 +1555,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ALDFFE_PPN_ (D, C, L, AD, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity async load and negative //- polarity clock enable. @@ -1515,6 +1580,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_ALDFFE_PPP_ (D, C, L, AD, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity async load and positive //- polarity clock enable. @@ -1539,6 +1605,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSR_NNN_ (C, S, R, D, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity set and negative //- polarity reset. @@ -1566,6 +1633,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSR_NNP_ (C, S, R, D, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity set and positive //- polarity reset. @@ -1593,6 +1661,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSR_NPN_ (C, S, R, D, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity set and negative //- polarity reset. @@ -1620,6 +1689,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSR_NPP_ (C, S, R, D, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity set and positive //- polarity reset. @@ -1647,6 +1717,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSR_PNN_ (C, S, R, D, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity set and negative //- polarity reset. @@ -1674,6 +1745,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSR_PNP_ (C, S, R, D, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity set and positive //- polarity reset. @@ -1701,6 +1773,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSR_PPN_ (C, S, R, D, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity set and negative //- polarity reset. @@ -1728,6 +1801,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSR_PPP_ (C, S, R, D, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity set and positive //- polarity reset. @@ -1755,6 +1829,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_NNNN_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity set, negative //- polarity reset and negative polarity clock enable. @@ -1782,6 +1857,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_NNNP_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity set, negative //- polarity reset and positive polarity clock enable. @@ -1809,6 +1885,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_NNPN_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity set, positive //- polarity reset and negative polarity clock enable. @@ -1836,6 +1913,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_NNPP_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity set, positive //- polarity reset and positive polarity clock enable. @@ -1863,6 +1941,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_NPNN_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity set, negative //- polarity reset and negative polarity clock enable. @@ -1890,6 +1969,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_NPNP_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity set, negative //- polarity reset and positive polarity clock enable. @@ -1917,6 +1997,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_NPPN_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity set, positive //- polarity reset and negative polarity clock enable. @@ -1944,6 +2025,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_NPPP_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity set, positive //- polarity reset and positive polarity clock enable. @@ -1971,6 +2053,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_PNNN_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity set, negative //- polarity reset and negative polarity clock enable. @@ -1998,6 +2081,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_PNNP_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity set, negative //- polarity reset and positive polarity clock enable. @@ -2025,6 +2109,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_PNPN_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity set, positive //- polarity reset and negative polarity clock enable. @@ -2052,6 +2137,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_PNPP_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity set, positive //- polarity reset and positive polarity clock enable. @@ -2079,6 +2165,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_PPNN_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity set, negative //- polarity reset and negative polarity clock enable. @@ -2106,6 +2193,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_PPNP_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity set, negative //- polarity reset and positive polarity clock enable. @@ -2133,6 +2221,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_PPPN_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity set, positive //- polarity reset and negative polarity clock enable. @@ -2160,6 +2249,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DFFSRE_PPPP_ (C, S, R, E, D, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity set, positive //- polarity reset and positive polarity clock enable. @@ -2187,6 +2277,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFF_NN0_ (D, C, R, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity synchronous reset. //- @@ -2210,6 +2301,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFF_NN1_ (D, C, R, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity synchronous set. //- @@ -2233,6 +2325,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFF_NP0_ (D, C, R, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity synchronous reset. //- @@ -2256,6 +2349,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFF_NP1_ (D, C, R, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity synchronous set. //- @@ -2279,6 +2373,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFF_PN0_ (D, C, R, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity synchronous reset. //- @@ -2302,6 +2397,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFF_PN1_ (D, C, R, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity synchronous set. //- @@ -2325,6 +2421,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFF_PP0_ (D, C, R, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity synchronous reset. //- @@ -2348,6 +2445,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFF_PP1_ (D, C, R, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity synchronous set. //- @@ -2371,6 +2469,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_NN0N_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity synchronous reset and negative //- polarity clock enable (with reset having priority). @@ -2395,6 +2494,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_NN0P_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity synchronous reset and positive //- polarity clock enable (with reset having priority). @@ -2419,6 +2519,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_NN1N_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity synchronous set and negative //- polarity clock enable (with set having priority). @@ -2443,6 +2544,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_NN1P_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity synchronous set and positive //- polarity clock enable (with set having priority). @@ -2467,6 +2569,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_NP0N_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity synchronous reset and negative //- polarity clock enable (with reset having priority). @@ -2491,6 +2594,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_NP0P_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity synchronous reset and positive //- polarity clock enable (with reset having priority). @@ -2515,6 +2619,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_NP1N_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity synchronous set and negative //- polarity clock enable (with set having priority). @@ -2539,6 +2644,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_NP1P_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity synchronous set and positive //- polarity clock enable (with set having priority). @@ -2563,6 +2669,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_PN0N_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity synchronous reset and negative //- polarity clock enable (with reset having priority). @@ -2587,6 +2694,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_PN0P_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity synchronous reset and positive //- polarity clock enable (with reset having priority). @@ -2611,6 +2719,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_PN1N_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity synchronous set and negative //- polarity clock enable (with set having priority). @@ -2635,6 +2744,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_PN1P_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity synchronous set and positive //- polarity clock enable (with set having priority). @@ -2659,6 +2769,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_PP0N_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity synchronous reset and negative //- polarity clock enable (with reset having priority). @@ -2683,6 +2794,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_PP0P_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity synchronous reset and positive //- polarity clock enable (with reset having priority). @@ -2707,6 +2819,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_PP1N_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity synchronous set and negative //- polarity clock enable (with set having priority). @@ -2731,6 +2844,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFE_PP1P_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity synchronous set and positive //- polarity clock enable (with set having priority). @@ -2755,6 +2869,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_NN0N_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity synchronous reset and negative //- polarity clock enable (with clock enable having priority). @@ -2781,6 +2896,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_NN0P_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity synchronous reset and positive //- polarity clock enable (with clock enable having priority). @@ -2807,6 +2923,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_NN1N_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity synchronous set and negative //- polarity clock enable (with clock enable having priority). @@ -2833,6 +2950,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_NN1P_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with negative polarity synchronous set and positive //- polarity clock enable (with clock enable having priority). @@ -2859,6 +2977,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_NP0N_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity synchronous reset and negative //- polarity clock enable (with clock enable having priority). @@ -2885,6 +3004,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_NP0P_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity synchronous reset and positive //- polarity clock enable (with clock enable having priority). @@ -2911,6 +3031,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_NP1N_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity synchronous set and negative //- polarity clock enable (with clock enable having priority). @@ -2937,6 +3058,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_NP1P_ (D, C, R, E, Q) +//* group reg_ff //- //- A negative edge D-type flip-flop with positive polarity synchronous set and positive //- polarity clock enable (with clock enable having priority). @@ -2963,6 +3085,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_PN0N_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity synchronous reset and negative //- polarity clock enable (with clock enable having priority). @@ -2989,6 +3112,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_PN0P_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity synchronous reset and positive //- polarity clock enable (with clock enable having priority). @@ -3015,6 +3139,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_PN1N_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity synchronous set and negative //- polarity clock enable (with clock enable having priority). @@ -3041,6 +3166,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_PN1P_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with negative polarity synchronous set and positive //- polarity clock enable (with clock enable having priority). @@ -3067,6 +3193,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_PP0N_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity synchronous reset and negative //- polarity clock enable (with clock enable having priority). @@ -3093,6 +3220,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_PP0P_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity synchronous reset and positive //- polarity clock enable (with clock enable having priority). @@ -3119,6 +3247,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_PP1N_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity synchronous set and negative //- polarity clock enable (with clock enable having priority). @@ -3145,6 +3274,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_SDFFCE_PP1P_ (D, C, R, E, Q) +//* group reg_ff //- //- A positive edge D-type flip-flop with positive polarity synchronous set and positive //- polarity clock enable (with clock enable having priority). @@ -3171,6 +3301,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCH_N_ (E, D, Q) +//* group reg_latch //- //- A negative enable D-type latch. //- @@ -3191,6 +3322,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCH_P_ (E, D, Q) +//* group reg_latch //- //- A positive enable D-type latch. //- @@ -3211,6 +3343,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCH_NN0_ (E, R, D, Q) +//* group reg_latch //- //- A negative enable D-type latch with negative polarity reset. //- @@ -3234,6 +3367,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCH_NN1_ (E, R, D, Q) +//* group reg_latch //- //- A negative enable D-type latch with negative polarity set. //- @@ -3257,6 +3391,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCH_NP0_ (E, R, D, Q) +//* group reg_latch //- //- A negative enable D-type latch with positive polarity reset. //- @@ -3280,6 +3415,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCH_NP1_ (E, R, D, Q) +//* group reg_latch //- //- A negative enable D-type latch with positive polarity set. //- @@ -3303,6 +3439,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCH_PN0_ (E, R, D, Q) +//* group reg_latch //- //- A positive enable D-type latch with negative polarity reset. //- @@ -3326,6 +3463,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCH_PN1_ (E, R, D, Q) +//* group reg_latch //- //- A positive enable D-type latch with negative polarity set. //- @@ -3349,6 +3487,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCH_PP0_ (E, R, D, Q) +//* group reg_latch //- //- A positive enable D-type latch with positive polarity reset. //- @@ -3372,6 +3511,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCH_PP1_ (E, R, D, Q) +//* group reg_latch //- //- A positive enable D-type latch with positive polarity set. //- @@ -3395,6 +3535,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCHSR_NNN_ (E, S, R, D, Q) +//* group reg_latch //- //- A negative enable D-type latch with negative polarity set and negative //- polarity reset. @@ -3422,6 +3563,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCHSR_NNP_ (E, S, R, D, Q) +//* group reg_latch //- //- A negative enable D-type latch with negative polarity set and positive //- polarity reset. @@ -3449,6 +3591,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCHSR_NPN_ (E, S, R, D, Q) +//* group reg_latch //- //- A negative enable D-type latch with positive polarity set and negative //- polarity reset. @@ -3476,6 +3619,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCHSR_NPP_ (E, S, R, D, Q) +//* group reg_latch //- //- A negative enable D-type latch with positive polarity set and positive //- polarity reset. @@ -3503,6 +3647,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCHSR_PNN_ (E, S, R, D, Q) +//* group reg_latch //- //- A positive enable D-type latch with negative polarity set and negative //- polarity reset. @@ -3530,6 +3675,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCHSR_PNP_ (E, S, R, D, Q) +//* group reg_latch //- //- A positive enable D-type latch with negative polarity set and positive //- polarity reset. @@ -3557,6 +3703,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCHSR_PPN_ (E, S, R, D, Q) +//* group reg_latch //- //- A positive enable D-type latch with positive polarity set and negative //- polarity reset. @@ -3584,6 +3731,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_DLATCHSR_PPP_ (E, S, R, D, Q) +//* group reg_latch //- //- A positive enable D-type latch with positive polarity set and positive //- polarity reset. From b0bc29e215157f910a5fe5aa8d8ed3ab2b9ee46b Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 29 Aug 2024 10:43:46 +1200 Subject: [PATCH 066/496] Docs: Add todo for $check --- docs/source/cell/word_formal.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/cell/word_formal.rst b/docs/source/cell/word_formal.rst index ae0f56025..8c52422a8 100644 --- a/docs/source/cell/word_formal.rst +++ b/docs/source/cell/word_formal.rst @@ -1,6 +1,10 @@ Formal verification cells ------------------------- +.. TODO:: note on `$check` + + If only I remembered what the note was... + .. TODO:: Describe formal cells `$check`, `$assert`, `$assume`, `$live`, `$fair`, `$cover`, `$equiv`, From 5473b60aeccf4aa43464c66e1cbf127351a324a1 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 29 Aug 2024 10:44:07 +1200 Subject: [PATCH 067/496] Docs: Split gate-level cells into subpages --- docs/source/cell/gate_comb_combined.rst | 53 ++++ docs/source/cell/gate_comb_simple.rst | 26 ++ docs/source/cell/gate_other.rst | 5 - docs/source/cell/gate_reg_ff.rst | 231 ++++++++++++++ docs/source/cell/gate_reg_latch.rst | 105 +++++++ docs/source/cell_gate.rst | 393 +----------------------- 6 files changed, 431 insertions(+), 382 deletions(-) create mode 100644 docs/source/cell/gate_comb_combined.rst create mode 100644 docs/source/cell/gate_comb_simple.rst delete mode 100644 docs/source/cell/gate_other.rst create mode 100644 docs/source/cell/gate_reg_ff.rst create mode 100644 docs/source/cell/gate_reg_latch.rst diff --git a/docs/source/cell/gate_comb_combined.rst b/docs/source/cell/gate_comb_combined.rst new file mode 100644 index 000000000..1a1f548cc --- /dev/null +++ b/docs/source/cell/gate_comb_combined.rst @@ -0,0 +1,53 @@ +.. role:: verilog(code) + :language: Verilog + +Combinatorial cells (combined) +------------------------------ + +These cells combine two or more combinatorial cells (simple) into a single cell. + +.. table:: Cell types for gate level combinatorial cells (combined) + + ======================================= ============= + Verilog Cell Type + ======================================= ============= + :verilog:`Y = A & ~B` `$_ANDNOT_` + :verilog:`Y = A | ~B` `$_ORNOT_` + :verilog:`Y = ~((A & B) | C)` `$_AOI3_` + :verilog:`Y = ~((A | B) & C)` `$_OAI3_` + :verilog:`Y = ~((A & B) | (C & D))` `$_AOI4_` + :verilog:`Y = ~((A | B) & (C | D))` `$_OAI4_` + :verilog:`Y = ~(S ? B : A)` `$_NMUX_` + (see below) `$_MUX4_` + (see below) `$_MUX8_` + (see below) `$_MUX16_` + ======================================= ============= + +The `$_MUX4_`, `$_MUX8_` and `$_MUX16_` cells are used to model wide muxes, and +correspond to the following Verilog code: + +.. code-block:: verilog + :force: + + // $_MUX4_ + assign Y = T ? (S ? D : C) : + (S ? B : A); + // $_MUX8_ + assign Y = U ? T ? (S ? H : G) : + (S ? F : E) : + T ? (S ? D : C) : + (S ? B : A); + // $_MUX16_ + assign Y = V ? U ? T ? (S ? P : O) : + (S ? N : M) : + T ? (S ? L : K) : + (S ? J : I) : + U ? T ? (S ? H : G) : + (S ? F : E) : + T ? (S ? D : C) : + (S ? B : A); + +.. autocellgroup:: comb_combined + :members: + :source: + :linenos: diff --git a/docs/source/cell/gate_comb_simple.rst b/docs/source/cell/gate_comb_simple.rst new file mode 100644 index 000000000..f45e64496 --- /dev/null +++ b/docs/source/cell/gate_comb_simple.rst @@ -0,0 +1,26 @@ +.. role:: verilog(code) + :language: Verilog + +Combinatorial cells (simple) +---------------------------- + +.. table:: Cell types for gate level combinatorial cells (simple) + + ======================================= ============= + Verilog Cell Type + ======================================= ============= + :verilog:`Y = A` `$_BUF_` + :verilog:`Y = ~A` `$_NOT_` + :verilog:`Y = A & B` `$_AND_` + :verilog:`Y = ~(A & B)` `$_NAND_` + :verilog:`Y = A | B` `$_OR_` + :verilog:`Y = ~(A | B)` `$_NOR_` + :verilog:`Y = A ^ B` `$_XOR_` + :verilog:`Y = ~(A ^ B)` `$_XNOR_` + :verilog:`Y = S ? B : A` `$_MUX_` + ======================================= ============= + +.. autocellgroup:: comb_simple + :members: + :source: + :linenos: diff --git a/docs/source/cell/gate_other.rst b/docs/source/cell/gate_other.rst deleted file mode 100644 index 7696ba824..000000000 --- a/docs/source/cell/gate_other.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. autocellgroup:: gate_other - :caption: Other gate-level cells - :members: - :source: - :linenos: diff --git a/docs/source/cell/gate_reg_ff.rst b/docs/source/cell/gate_reg_ff.rst new file mode 100644 index 000000000..2a31a3f09 --- /dev/null +++ b/docs/source/cell/gate_reg_ff.rst @@ -0,0 +1,231 @@ +.. role:: verilog(code) + :language: Verilog + +Flip-flop cells +--------------- + +The cell types `$_DFF_N_` and `$_DFF_P_` represent d-type flip-flops. + +.. table:: Cell types for basic flip-flops + + ======================================= ============= + Verilog Cell Type + ======================================= ============= + :verilog:`always @(negedge C) Q <= D` `$_DFF_N_` + :verilog:`always @(posedge C) Q <= D` `$_DFF_P_` + ======================================= ============= + +The cell types ``$_DFFE_[NP][NP]_`` implement d-type flip-flops with enable. The +values in the table for these cell types relate to the following Verilog code +template. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C) + if (EN == EN_LVL) + Q <= D; + + +.. table:: Cell types for gate level logic networks (FFs with enable) + :name: tab:CellLib_gates_dffe + + ================== ============= ============ + :math:`ClkEdge` :math:`EnLvl` Cell Type + ================== ============= ============ + :verilog:`negedge` ``0`` `$_DFFE_NN_` + :verilog:`negedge` ``1`` `$_DFFE_NP_` + :verilog:`posedge` ``0`` `$_DFFE_PN_` + :verilog:`posedge` ``1`` `$_DFFE_PP_` + ================== ============= ============ + +The cell types ``$_DFF_[NP][NP][01]_`` implement d-type flip-flops with +asynchronous reset. The values in the table for these cell types relate to the +following Verilog code template, where ``RST_EDGE`` is ``posedge`` if +``RST_LVL`` if ``1``, and ``negedge`` otherwise. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C, RST_EDGE R) + if (R == RST_LVL) + Q <= RST_VAL; + else + Q <= D; + +The cell types ``$_SDFF_[NP][NP][01]_`` implement d-type flip-flops with +synchronous reset. The values in the table for these cell types relate to the +following Verilog code template: + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C) + if (R == RST_LVL) + Q <= RST_VAL; + else + Q <= D; + +.. table:: Cell types for gate level logic networks (FFs with reset) + :name: tab:CellLib_gates_adff + + ================== ============== ============== =========================== + :math:`ClkEdge` :math:`RstLvl` :math:`RstVal` Cell Type + ================== ============== ============== =========================== + :verilog:`negedge` ``0`` ``0`` `$_DFF_NN0_`, `$_SDFF_NN0_` + :verilog:`negedge` ``0`` ``1`` `$_DFF_NN1_`, `$_SDFF_NN1_` + :verilog:`negedge` ``1`` ``0`` `$_DFF_NP0_`, `$_SDFF_NP0_` + :verilog:`negedge` ``1`` ``1`` `$_DFF_NP1_`, `$_SDFF_NP1_` + :verilog:`posedge` ``0`` ``0`` `$_DFF_PN0_`, `$_SDFF_PN0_` + :verilog:`posedge` ``0`` ``1`` `$_DFF_PN1_`, `$_SDFF_PN1_` + :verilog:`posedge` ``1`` ``0`` `$_DFF_PP0_`, `$_SDFF_PP0_` + :verilog:`posedge` ``1`` ``1`` `$_DFF_PP1_`, `$_SDFF_PP1_` + ================== ============== ============== =========================== + +The cell types ``$_DFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with +asynchronous reset and enable. The values in the table for these cell types +relate to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` +if ``RST_LVL`` if ``1``, and ``negedge`` otherwise. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C, RST_EDGE R) + if (R == RST_LVL) + Q <= RST_VAL; + else if (EN == EN_LVL) + Q <= D; + +The cell types ``$_SDFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with +synchronous reset and enable, with reset having priority over enable. The values +in the table for these cell types relate to the following Verilog code template: + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C) + if (R == RST_LVL) + Q <= RST_VAL; + else if (EN == EN_LVL) + Q <= D; + +The cell types ``$_SDFFCE_[NP][NP][01][NP]_`` implement d-type flip-flops with +synchronous reset and enable, with enable having priority over reset. The values +in the table for these cell types relate to the following Verilog code template: + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C) + if (EN == EN_LVL) + if (R == RST_LVL) + Q <= RST_VAL; + else + Q <= D; + + +.. table:: Cell types for gate level logic networks (FFs with reset and enable) + :name: tab:CellLib_gates_adffe + + ================== ============== ============== ============= ================================================= + :math:`ClkEdge` :math:`RstLvl` :math:`RstVal` :math:`EnLvl` Cell Type + ================== ============== ============== ============= ================================================= + :verilog:`negedge` ``0`` ``0`` ``0`` `$_DFFE_NN0N_`, `$_SDFFE_NN0N_`, `$_SDFFCE_NN0N_` + :verilog:`negedge` ``0`` ``0`` ``1`` `$_DFFE_NN0P_`, `$_SDFFE_NN0P_`, `$_SDFFCE_NN0P_` + :verilog:`negedge` ``0`` ``1`` ``0`` `$_DFFE_NN1N_`, `$_SDFFE_NN1N_`, `$_SDFFCE_NN1N_` + :verilog:`negedge` ``0`` ``1`` ``1`` `$_DFFE_NN1P_`, `$_SDFFE_NN1P_`, `$_SDFFCE_NN1P_` + :verilog:`negedge` ``1`` ``0`` ``0`` `$_DFFE_NP0N_`, `$_SDFFE_NP0N_`, `$_SDFFCE_NP0N_` + :verilog:`negedge` ``1`` ``0`` ``1`` `$_DFFE_NP0P_`, `$_SDFFE_NP0P_`, `$_SDFFCE_NP0P_` + :verilog:`negedge` ``1`` ``1`` ``0`` `$_DFFE_NP1N_`, `$_SDFFE_NP1N_`, `$_SDFFCE_NP1N_` + :verilog:`negedge` ``1`` ``1`` ``1`` `$_DFFE_NP1P_`, `$_SDFFE_NP1P_`, `$_SDFFCE_NP1P_` + :verilog:`posedge` ``0`` ``0`` ``0`` `$_DFFE_PN0N_`, `$_SDFFE_PN0N_`, `$_SDFFCE_PN0N_` + :verilog:`posedge` ``0`` ``0`` ``1`` `$_DFFE_PN0P_`, `$_SDFFE_PN0P_`, `$_SDFFCE_PN0P_` + :verilog:`posedge` ``0`` ``1`` ``0`` `$_DFFE_PN1N_`, `$_SDFFE_PN1N_`, `$_SDFFCE_PN1N_` + :verilog:`posedge` ``0`` ``1`` ``1`` `$_DFFE_PN1P_`, `$_SDFFE_PN1P_`, `$_SDFFCE_PN1P_` + :verilog:`posedge` ``1`` ``0`` ``0`` `$_DFFE_PP0N_`, `$_SDFFE_PP0N_`, `$_SDFFCE_PP0N_` + :verilog:`posedge` ``1`` ``0`` ``1`` `$_DFFE_PP0P_`, `$_SDFFE_PP0P_`, `$_SDFFCE_PP0P_` + :verilog:`posedge` ``1`` ``1`` ``0`` `$_DFFE_PP1N_`, `$_SDFFE_PP1N_`, `$_SDFFCE_PP1N_` + :verilog:`posedge` ``1`` ``1`` ``1`` `$_DFFE_PP1P_`, `$_SDFFE_PP1P_`, `$_SDFFCE_PP1P_` + ================== ============== ============== ============= ================================================= + +The cell types ``$_DFFSR_[NP][NP][NP]_`` implement d-type flip-flops with +asynchronous set and reset. The values in the table for these cell types relate +to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` if +``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is ``posedge`` if +``SET_LVL`` if ``1``, ``negedge`` otherwise. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S) + if (R == RST_LVL) + Q <= 0; + else if (S == SET_LVL) + Q <= 1; + else + Q <= D; + +.. table:: Cell types for gate level logic networks (FFs with set and reset) + :name: tab:CellLib_gates_dffsr + + ================== ============== ============== ============== + :math:`ClkEdge` :math:`SetLvl` :math:`RstLvl` Cell Type + ================== ============== ============== ============== + :verilog:`negedge` ``0`` ``0`` `$_DFFSR_NNN_` + :verilog:`negedge` ``0`` ``1`` `$_DFFSR_NNP_` + :verilog:`negedge` ``1`` ``0`` `$_DFFSR_NPN_` + :verilog:`negedge` ``1`` ``1`` `$_DFFSR_NPP_` + :verilog:`posedge` ``0`` ``0`` `$_DFFSR_PNN_` + :verilog:`posedge` ``0`` ``1`` `$_DFFSR_PNP_` + :verilog:`posedge` ``1`` ``0`` `$_DFFSR_PPN_` + :verilog:`posedge` ``1`` ``1`` `$_DFFSR_PPP_` + ================== ============== ============== ============== + +The cell types ``$_DFFSRE_[NP][NP][NP][NP]_`` implement d-type flip-flops with +asynchronous set and reset and enable. The values in the table for these cell +types relate to the following Verilog code template, where ``RST_EDGE`` is +``posedge`` if ``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is +``posedge`` if ``SET_LVL`` if ``1``, ``negedge`` otherwise. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S) + if (R == RST_LVL) + Q <= 0; + else if (S == SET_LVL) + Q <= 1; + else if (E == EN_LVL) + Q <= D; + + +.. table:: Cell types for gate level logic networks (FFs with set and reset and enable) + :name: tab:CellLib_gates_dffsre + + ================== ============== ============== ============= ================ + :math:`ClkEdge` :math:`SetLvl` :math:`RstLvl` :math:`EnLvl` Cell Type + ================== ============== ============== ============= ================ + :verilog:`negedge` ``0`` ``0`` ``0`` `$_DFFSRE_NNNN_` + :verilog:`negedge` ``0`` ``0`` ``1`` `$_DFFSRE_NNNP_` + :verilog:`negedge` ``0`` ``1`` ``0`` `$_DFFSRE_NNPN_` + :verilog:`negedge` ``0`` ``1`` ``1`` `$_DFFSRE_NNPP_` + :verilog:`negedge` ``1`` ``0`` ``0`` `$_DFFSRE_NPNN_` + :verilog:`negedge` ``1`` ``0`` ``1`` `$_DFFSRE_NPNP_` + :verilog:`negedge` ``1`` ``1`` ``0`` `$_DFFSRE_NPPN_` + :verilog:`negedge` ``1`` ``1`` ``1`` `$_DFFSRE_NPPP_` + :verilog:`posedge` ``0`` ``0`` ``0`` `$_DFFSRE_PNNN_` + :verilog:`posedge` ``0`` ``0`` ``1`` `$_DFFSRE_PNNP_` + :verilog:`posedge` ``0`` ``1`` ``0`` `$_DFFSRE_PNPN_` + :verilog:`posedge` ``0`` ``1`` ``1`` `$_DFFSRE_PNPP_` + :verilog:`posedge` ``1`` ``0`` ``0`` `$_DFFSRE_PPNN_` + :verilog:`posedge` ``1`` ``0`` ``1`` `$_DFFSRE_PPNP_` + :verilog:`posedge` ``1`` ``1`` ``0`` `$_DFFSRE_PPPN_` + :verilog:`posedge` ``1`` ``1`` ``1`` `$_DFFSRE_PPPP_` + ================== ============== ============== ============= ================ + +.. todo:: flip-flops with async load, ``$_ALDFFE?_[NP]{2,3}_`` + +.. autocellgroup:: reg_ff + :members: + :source: + :linenos: diff --git a/docs/source/cell/gate_reg_latch.rst b/docs/source/cell/gate_reg_latch.rst new file mode 100644 index 000000000..bb01bc74c --- /dev/null +++ b/docs/source/cell/gate_reg_latch.rst @@ -0,0 +1,105 @@ +.. role:: verilog(code) + :language: Verilog + +Latch cells +----------- + +The cell types `$_DLATCH_N_` and `$_DLATCH_P_` represent d-type latches. + +.. table:: Cell types for basic latches + + ======================================= ============= + Verilog Cell Type + ======================================= ============= + :verilog:`always @* if (!E) Q <= D` `$_DLATCH_N_` + :verilog:`always @* if (E) Q <= D` `$_DLATCH_P_` + ======================================= ============= + +The cell types ``$_DLATCH_[NP][NP][01]_`` implement d-type latches with reset. +The values in the table for these cell types relate to the following Verilog +code template: + +.. code-block:: verilog + :force: + + always @* + if (R == RST_LVL) + Q <= RST_VAL; + else if (E == EN_LVL) + Q <= D; + +.. table:: Cell types for gate level logic networks (latches with reset) + :name: tab:CellLib_gates_adlatch + + ============= ============== ============== =============== + :math:`EnLvl` :math:`RstLvl` :math:`RstVal` Cell Type + ============= ============== ============== =============== + ``0`` ``0`` ``0`` `$_DLATCH_NN0_` + ``0`` ``0`` ``1`` `$_DLATCH_NN1_` + ``0`` ``1`` ``0`` `$_DLATCH_NP0_` + ``0`` ``1`` ``1`` `$_DLATCH_NP1_` + ``1`` ``0`` ``0`` `$_DLATCH_PN0_` + ``1`` ``0`` ``1`` `$_DLATCH_PN1_` + ``1`` ``1`` ``0`` `$_DLATCH_PP0_` + ``1`` ``1`` ``1`` `$_DLATCH_PP1_` + ============= ============== ============== =============== + +The cell types ``$_DLATCHSR_[NP][NP][NP]_`` implement d-type latches with set +and reset. The values in the table for these cell types relate to the following +Verilog code template: + +.. code-block:: verilog + :force: + + always @* + if (R == RST_LVL) + Q <= 0; + else if (S == SET_LVL) + Q <= 1; + else if (E == EN_LVL) + Q <= D; + +.. table:: Cell types for gate level logic networks (latches with set and reset) + :name: tab:CellLib_gates_dlatchsr + + ============= ============== ============== ================= + :math:`EnLvl` :math:`SetLvl` :math:`RstLvl` Cell Type + ============= ============== ============== ================= + ``0`` ``0`` ``0`` `$_DLATCHSR_NNN_` + ``0`` ``0`` ``1`` `$_DLATCHSR_NNP_` + ``0`` ``1`` ``0`` `$_DLATCHSR_NPN_` + ``0`` ``1`` ``1`` `$_DLATCHSR_NPP_` + ``1`` ``0`` ``0`` `$_DLATCHSR_PNN_` + ``1`` ``0`` ``1`` `$_DLATCHSR_PNP_` + ``1`` ``1`` ``0`` `$_DLATCHSR_PPN_` + ``1`` ``1`` ``1`` `$_DLATCHSR_PPP_` + ============= ============== ============== ================= + +The cell types ``$_SR_[NP][NP]_`` implement sr-type latches. The values in the +table for these cell types relate to the following Verilog code template: + +.. code-block:: verilog + :force: + + always @* + if (R == RST_LVL) + Q <= 0; + else if (S == SET_LVL) + Q <= 1; + +.. table:: Cell types for gate level logic networks (SR latches) + :name: tab:CellLib_gates_sr + + ============== ============== ========== + :math:`SetLvl` :math:`RstLvl` Cell Type + ============== ============== ========== + ``0`` ``0`` `$_SR_NN_` + ``0`` ``1`` `$_SR_NP_` + ``1`` ``0`` `$_SR_PN_` + ``1`` ``1`` `$_SR_PP_` + ============== ============== ========== + +.. autocellgroup:: reg_latch + :members: + :source: + :linenos: diff --git a/docs/source/cell_gate.rst b/docs/source/cell_gate.rst index 4262fe210..e6fab4c1f 100644 --- a/docs/source/cell_gate.rst +++ b/docs/source/cell_gate.rst @@ -1,388 +1,13 @@ -.. role:: verilog(code) - :language: Verilog - .. _sec:celllib_gates: Gate-level cells ---------------- -.. todo:: Split gate-level cells into subpages - - Consider also checking wording to be less academic and consistent. - For gate level logic networks, fixed function single bit cells are used that do not provide any parameters. Simulation models for these cells can be found in the file -techlibs/common/simcells.v in the Yosys source tree. - -.. table:: Cell types for gate level logic networks (main list) - :name: tab:CellLib_gates - - ======================================= ============= - Verilog Cell Type - ======================================= ============= - :verilog:`Y = A` `$_BUF_` - :verilog:`Y = ~A` `$_NOT_` - :verilog:`Y = A & B` `$_AND_` - :verilog:`Y = ~(A & B)` `$_NAND_` - :verilog:`Y = A & ~B` `$_ANDNOT_` - :verilog:`Y = A | B` `$_OR_` - :verilog:`Y = ~(A | B)` `$_NOR_` - :verilog:`Y = A | ~B` `$_ORNOT_` - :verilog:`Y = A ^ B` `$_XOR_` - :verilog:`Y = ~(A ^ B)` `$_XNOR_` - :verilog:`Y = ~((A & B) | C)` `$_AOI3_` - :verilog:`Y = ~((A | B) & C)` `$_OAI3_` - :verilog:`Y = ~((A & B) | (C & D))` `$_AOI4_` - :verilog:`Y = ~((A | B) & (C | D))` `$_OAI4_` - :verilog:`Y = S ? B : A` `$_MUX_` - :verilog:`Y = ~(S ? B : A)` `$_NMUX_` - (see below) `$_MUX4_` - (see below) `$_MUX8_` - (see below) `$_MUX16_` - :verilog:`Y = EN ? A : 1'bz` `$_TBUF_` - :verilog:`always @(negedge C) Q <= D` `$_DFF_N_` - :verilog:`always @(posedge C) Q <= D` `$_DFF_P_` - :verilog:`always @* if (!E) Q <= D` `$_DLATCH_N_` - :verilog:`always @* if (E) Q <= D` `$_DLATCH_P_` - ======================================= ============= - -.. table:: Cell types for gate level logic networks (FFs with reset) - :name: tab:CellLib_gates_adff - - ================== ============== ============== =========================== - :math:`ClkEdge` :math:`RstLvl` :math:`RstVal` Cell Type - ================== ============== ============== =========================== - :verilog:`negedge` ``0`` ``0`` `$_DFF_NN0_`, `$_SDFF_NN0_` - :verilog:`negedge` ``0`` ``1`` `$_DFF_NN1_`, `$_SDFF_NN1_` - :verilog:`negedge` ``1`` ``0`` `$_DFF_NP0_`, `$_SDFF_NP0_` - :verilog:`negedge` ``1`` ``1`` `$_DFF_NP1_`, `$_SDFF_NP1_` - :verilog:`posedge` ``0`` ``0`` `$_DFF_PN0_`, `$_SDFF_PN0_` - :verilog:`posedge` ``0`` ``1`` `$_DFF_PN1_`, `$_SDFF_PN1_` - :verilog:`posedge` ``1`` ``0`` `$_DFF_PP0_`, `$_SDFF_PP0_` - :verilog:`posedge` ``1`` ``1`` `$_DFF_PP1_`, `$_SDFF_PP1_` - ================== ============== ============== =========================== - - -.. table:: Cell types for gate level logic networks (FFs with enable) - :name: tab:CellLib_gates_dffe - - ================== ============= ============ - :math:`ClkEdge` :math:`EnLvl` Cell Type - ================== ============= ============ - :verilog:`negedge` ``0`` `$_DFFE_NN_` - :verilog:`negedge` ``1`` `$_DFFE_NP_` - :verilog:`posedge` ``0`` `$_DFFE_PN_` - :verilog:`posedge` ``1`` `$_DFFE_PP_` - ================== ============= ============ - - -.. table:: Cell types for gate level logic networks (FFs with reset and enable) - :name: tab:CellLib_gates_adffe - - ================== ============== ============== ============= ================================================= - :math:`ClkEdge` :math:`RstLvl` :math:`RstVal` :math:`EnLvl` Cell Type - ================== ============== ============== ============= ================================================= - :verilog:`negedge` ``0`` ``0`` ``0`` `$_DFFE_NN0N_`, `$_SDFFE_NN0N_`, `$_SDFFCE_NN0N_` - :verilog:`negedge` ``0`` ``0`` ``1`` `$_DFFE_NN0P_`, `$_SDFFE_NN0P_`, `$_SDFFCE_NN0P_` - :verilog:`negedge` ``0`` ``1`` ``0`` `$_DFFE_NN1N_`, `$_SDFFE_NN1N_`, `$_SDFFCE_NN1N_` - :verilog:`negedge` ``0`` ``1`` ``1`` `$_DFFE_NN1P_`, `$_SDFFE_NN1P_`, `$_SDFFCE_NN1P_` - :verilog:`negedge` ``1`` ``0`` ``0`` `$_DFFE_NP0N_`, `$_SDFFE_NP0N_`, `$_SDFFCE_NP0N_` - :verilog:`negedge` ``1`` ``0`` ``1`` `$_DFFE_NP0P_`, `$_SDFFE_NP0P_`, `$_SDFFCE_NP0P_` - :verilog:`negedge` ``1`` ``1`` ``0`` `$_DFFE_NP1N_`, `$_SDFFE_NP1N_`, `$_SDFFCE_NP1N_` - :verilog:`negedge` ``1`` ``1`` ``1`` `$_DFFE_NP1P_`, `$_SDFFE_NP1P_`, `$_SDFFCE_NP1P_` - :verilog:`posedge` ``0`` ``0`` ``0`` `$_DFFE_PN0N_`, `$_SDFFE_PN0N_`, `$_SDFFCE_PN0N_` - :verilog:`posedge` ``0`` ``0`` ``1`` `$_DFFE_PN0P_`, `$_SDFFE_PN0P_`, `$_SDFFCE_PN0P_` - :verilog:`posedge` ``0`` ``1`` ``0`` `$_DFFE_PN1N_`, `$_SDFFE_PN1N_`, `$_SDFFCE_PN1N_` - :verilog:`posedge` ``0`` ``1`` ``1`` `$_DFFE_PN1P_`, `$_SDFFE_PN1P_`, `$_SDFFCE_PN1P_` - :verilog:`posedge` ``1`` ``0`` ``0`` `$_DFFE_PP0N_`, `$_SDFFE_PP0N_`, `$_SDFFCE_PP0N_` - :verilog:`posedge` ``1`` ``0`` ``1`` `$_DFFE_PP0P_`, `$_SDFFE_PP0P_`, `$_SDFFCE_PP0P_` - :verilog:`posedge` ``1`` ``1`` ``0`` `$_DFFE_PP1N_`, `$_SDFFE_PP1N_`, `$_SDFFCE_PP1N_` - :verilog:`posedge` ``1`` ``1`` ``1`` `$_DFFE_PP1P_`, `$_SDFFE_PP1P_`, `$_SDFFCE_PP1P_` - ================== ============== ============== ============= ================================================= - -.. table:: Cell types for gate level logic networks (FFs with set and reset) - :name: tab:CellLib_gates_dffsr - - ================== ============== ============== ============== - :math:`ClkEdge` :math:`SetLvl` :math:`RstLvl` Cell Type - ================== ============== ============== ============== - :verilog:`negedge` ``0`` ``0`` `$_DFFSR_NNN_` - :verilog:`negedge` ``0`` ``1`` `$_DFFSR_NNP_` - :verilog:`negedge` ``1`` ``0`` `$_DFFSR_NPN_` - :verilog:`negedge` ``1`` ``1`` `$_DFFSR_NPP_` - :verilog:`posedge` ``0`` ``0`` `$_DFFSR_PNN_` - :verilog:`posedge` ``0`` ``1`` `$_DFFSR_PNP_` - :verilog:`posedge` ``1`` ``0`` `$_DFFSR_PPN_` - :verilog:`posedge` ``1`` ``1`` `$_DFFSR_PPP_` - ================== ============== ============== ============== - - -.. table:: Cell types for gate level logic networks (FFs with set and reset and enable) - :name: tab:CellLib_gates_dffsre - - ================== ============== ============== ============= ================ - :math:`ClkEdge` :math:`SetLvl` :math:`RstLvl` :math:`EnLvl` Cell Type - ================== ============== ============== ============= ================ - :verilog:`negedge` ``0`` ``0`` ``0`` `$_DFFSRE_NNNN_` - :verilog:`negedge` ``0`` ``0`` ``1`` `$_DFFSRE_NNNP_` - :verilog:`negedge` ``0`` ``1`` ``0`` `$_DFFSRE_NNPN_` - :verilog:`negedge` ``0`` ``1`` ``1`` `$_DFFSRE_NNPP_` - :verilog:`negedge` ``1`` ``0`` ``0`` `$_DFFSRE_NPNN_` - :verilog:`negedge` ``1`` ``0`` ``1`` `$_DFFSRE_NPNP_` - :verilog:`negedge` ``1`` ``1`` ``0`` `$_DFFSRE_NPPN_` - :verilog:`negedge` ``1`` ``1`` ``1`` `$_DFFSRE_NPPP_` - :verilog:`posedge` ``0`` ``0`` ``0`` `$_DFFSRE_PNNN_` - :verilog:`posedge` ``0`` ``0`` ``1`` `$_DFFSRE_PNNP_` - :verilog:`posedge` ``0`` ``1`` ``0`` `$_DFFSRE_PNPN_` - :verilog:`posedge` ``0`` ``1`` ``1`` `$_DFFSRE_PNPP_` - :verilog:`posedge` ``1`` ``0`` ``0`` `$_DFFSRE_PPNN_` - :verilog:`posedge` ``1`` ``0`` ``1`` `$_DFFSRE_PPNP_` - :verilog:`posedge` ``1`` ``1`` ``0`` `$_DFFSRE_PPPN_` - :verilog:`posedge` ``1`` ``1`` ``1`` `$_DFFSRE_PPPP_` - ================== ============== ============== ============= ================ - - -.. table:: Cell types for gate level logic networks (latches with reset) - :name: tab:CellLib_gates_adlatch - - ============= ============== ============== =============== - :math:`EnLvl` :math:`RstLvl` :math:`RstVal` Cell Type - ============= ============== ============== =============== - ``0`` ``0`` ``0`` `$_DLATCH_NN0_` - ``0`` ``0`` ``1`` `$_DLATCH_NN1_` - ``0`` ``1`` ``0`` `$_DLATCH_NP0_` - ``0`` ``1`` ``1`` `$_DLATCH_NP1_` - ``1`` ``0`` ``0`` `$_DLATCH_PN0_` - ``1`` ``0`` ``1`` `$_DLATCH_PN1_` - ``1`` ``1`` ``0`` `$_DLATCH_PP0_` - ``1`` ``1`` ``1`` `$_DLATCH_PP1_` - ============= ============== ============== =============== - - -.. table:: Cell types for gate level logic networks (latches with set and reset) - :name: tab:CellLib_gates_dlatchsr - - ============= ============== ============== ================= - :math:`EnLvl` :math:`SetLvl` :math:`RstLvl` Cell Type - ============= ============== ============== ================= - ``0`` ``0`` ``0`` `$_DLATCHSR_NNN_` - ``0`` ``0`` ``1`` `$_DLATCHSR_NNP_` - ``0`` ``1`` ``0`` `$_DLATCHSR_NPN_` - ``0`` ``1`` ``1`` `$_DLATCHSR_NPP_` - ``1`` ``0`` ``0`` `$_DLATCHSR_PNN_` - ``1`` ``0`` ``1`` `$_DLATCHSR_PNP_` - ``1`` ``1`` ``0`` `$_DLATCHSR_PPN_` - ``1`` ``1`` ``1`` `$_DLATCHSR_PPP_` - ============= ============== ============== ================= - - - -.. table:: Cell types for gate level logic networks (SR latches) - :name: tab:CellLib_gates_sr - - ============== ============== ========== - :math:`SetLvl` :math:`RstLvl` Cell Type - ============== ============== ========== - ``0`` ``0`` `$_SR_NN_` - ``0`` ``1`` `$_SR_NP_` - ``1`` ``0`` `$_SR_PN_` - ``1`` ``1`` `$_SR_PP_` - ============== ============== ========== - - -Tables :numref:`%s `, :numref:`%s `, -:numref:`%s `, :numref:`%s `, -:numref:`%s `, :numref:`%s `, -:numref:`%s `, :numref:`%s -` and :numref:`%s ` list all -cell types used for gate level logic. The cell types `$_BUF_`, `$_NOT_`, -`$_AND_`, `$_NAND_`, `$_ANDNOT_`, `$_OR_`, `$_NOR_`, `$_ORNOT_`, `$_XOR_`, -`$_XNOR_`, `$_AOI3_`, `$_OAI3_`, `$_AOI4_`, `$_OAI4_`, `$_MUX_`, `$_MUX4_`, -`$_MUX8_`, `$_MUX16_` and `$_NMUX_` are used to model combinatorial logic. The -cell type `$_TBUF_` is used to model tristate logic. - -The `$_MUX4_`, `$_MUX8_` and `$_MUX16_` cells are used to model wide muxes, and -correspond to the following Verilog code: - -.. code-block:: verilog - :force: - - // $_MUX4_ - assign Y = T ? (S ? D : C) : - (S ? B : A); - // $_MUX8_ - assign Y = U ? T ? (S ? H : G) : - (S ? F : E) : - T ? (S ? D : C) : - (S ? B : A); - // $_MUX16_ - assign Y = V ? U ? T ? (S ? P : O) : - (S ? N : M) : - T ? (S ? L : K) : - (S ? J : I) : - U ? T ? (S ? H : G) : - (S ? F : E) : - T ? (S ? D : C) : - (S ? B : A); - -The cell types `$_DFF_N_` and `$_DFF_P_` represent d-type flip-flops. - -The cell types ``$_DFFE_[NP][NP]_`` implement d-type flip-flops with enable. The -values in the table for these cell types relate to the following Verilog code -template. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C) - if (EN == EN_LVL) - Q <= D; - -The cell types ``$_DFF_[NP][NP][01]_`` implement d-type flip-flops with -asynchronous reset. The values in the table for these cell types relate to the -following Verilog code template, where ``RST_EDGE`` is ``posedge`` if -``RST_LVL`` if ``1``, and ``negedge`` otherwise. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C, RST_EDGE R) - if (R == RST_LVL) - Q <= RST_VAL; - else - Q <= D; - -The cell types ``$_SDFF_[NP][NP][01]_`` implement d-type flip-flops with -synchronous reset. The values in the table for these cell types relate to the -following Verilog code template: - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C) - if (R == RST_LVL) - Q <= RST_VAL; - else - Q <= D; - -The cell types ``$_DFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with -asynchronous reset and enable. The values in the table for these cell types -relate to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` -if ``RST_LVL`` if ``1``, and ``negedge`` otherwise. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C, RST_EDGE R) - if (R == RST_LVL) - Q <= RST_VAL; - else if (EN == EN_LVL) - Q <= D; - -The cell types ``$_SDFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with -synchronous reset and enable, with reset having priority over enable. The values -in the table for these cell types relate to the following Verilog code template: - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C) - if (R == RST_LVL) - Q <= RST_VAL; - else if (EN == EN_LVL) - Q <= D; - -The cell types ``$_SDFFCE_[NP][NP][01][NP]_`` implement d-type flip-flops with -synchronous reset and enable, with enable having priority over reset. The values -in the table for these cell types relate to the following Verilog code template: - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C) - if (EN == EN_LVL) - if (R == RST_LVL) - Q <= RST_VAL; - else - Q <= D; - -The cell types ``$_DFFSR_[NP][NP][NP]_`` implement d-type flip-flops with -asynchronous set and reset. The values in the table for these cell types relate -to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` if -``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is ``posedge`` if -``SET_LVL`` if ``1``, ``negedge`` otherwise. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S) - if (R == RST_LVL) - Q <= 0; - else if (S == SET_LVL) - Q <= 1; - else - Q <= D; - -The cell types ``$_DFFSRE_[NP][NP][NP][NP]_`` implement d-type flip-flops with -asynchronous set and reset and enable. The values in the table for these cell -types relate to the following Verilog code template, where ``RST_EDGE`` is -``posedge`` if ``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is -``posedge`` if ``SET_LVL`` if ``1``, ``negedge`` otherwise. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S) - if (R == RST_LVL) - Q <= 0; - else if (S == SET_LVL) - Q <= 1; - else if (E == EN_LVL) - Q <= D; - -The cell types `$_DLATCH_N_` and `$_DLATCH_P_` represent d-type latches. - -The cell types ``$_DLATCH_[NP][NP][01]_`` implement d-type latches with reset. -The values in the table for these cell types relate to the following Verilog -code template: - -.. code-block:: verilog - :force: - - always @* - if (R == RST_LVL) - Q <= RST_VAL; - else if (E == EN_LVL) - Q <= D; - -The cell types ``$_DLATCHSR_[NP][NP][NP]_`` implement d-type latches with set -and reset. The values in the table for these cell types relate to the following -Verilog code template: - -.. code-block:: verilog - :force: - - always @* - if (R == RST_LVL) - Q <= 0; - else if (S == SET_LVL) - Q <= 1; - else if (E == EN_LVL) - Q <= D; - -The cell types ``$_SR_[NP][NP]_`` implement sr-type latches. The values in the -table for these cell types relate to the following Verilog code template: - -.. code-block:: verilog - :force: - - always @* - if (R == RST_LVL) - Q <= 0; - else if (S == SET_LVL) - Q <= 1; +:file:`techlibs/common/simcells.v` in the Yosys source tree. In most cases gate level logic networks are created from RTL networks using the techmap pass. The flip-flop cells from the gate level logic network can be @@ -394,4 +19,18 @@ file via ABC using the abc pass. :caption: Gate-level cells :maxdepth: 2 - /cell/gate_other + /cell/gate_comb_simple + /cell/gate_comb_combined + /cell/gate_reg_ff + /cell/gate_reg_latch + +.. TODO:: Find a home for `$_TBUF_` + +.. this should raise a warning, otherwise there are gate-level cells without a + 'group' tag + +.. autocellgroup:: gate_other + :caption: Other gate-level cells + :members: + :source: + :linenos: From 00050833ef2d7f83f9e01c40fee5697a7fafdc61 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 3 Sep 2024 12:03:57 +1200 Subject: [PATCH 068/496] Docs: Add gate_other page Drop word_other block since it raises a warning, which will cause the RTDs build to fail. --- docs/source/cell/gate_other.rst | 8 ++++++++ docs/source/cell_gate.rst | 12 +----------- docs/source/cell_word.rst | 9 +-------- 3 files changed, 10 insertions(+), 19 deletions(-) create mode 100644 docs/source/cell/gate_other.rst diff --git a/docs/source/cell/gate_other.rst b/docs/source/cell/gate_other.rst new file mode 100644 index 000000000..bac26094e --- /dev/null +++ b/docs/source/cell/gate_other.rst @@ -0,0 +1,8 @@ +Other gate-level cells +---------------------- + +.. autocellgroup:: gate_other + :caption: Other gate-level cells + :members: + :source: + :linenos: diff --git a/docs/source/cell_gate.rst b/docs/source/cell_gate.rst index e6fab4c1f..4ff38ec5e 100644 --- a/docs/source/cell_gate.rst +++ b/docs/source/cell_gate.rst @@ -23,14 +23,4 @@ file via ABC using the abc pass. /cell/gate_comb_combined /cell/gate_reg_ff /cell/gate_reg_latch - -.. TODO:: Find a home for `$_TBUF_` - -.. this should raise a warning, otherwise there are gate-level cells without a - 'group' tag - -.. autocellgroup:: gate_other - :caption: Other gate-level cells - :members: - :source: - :linenos: + /cell/gate_other diff --git a/docs/source/cell_word.rst b/docs/source/cell_word.rst index 3c87d9913..bfb14f510 100644 --- a/docs/source/cell_word.rst +++ b/docs/source/cell_word.rst @@ -29,11 +29,4 @@ Simulation models for the RTL cells can be found in the file /cell/word_debug /cell/word_wire -.. this should raise a warning, otherwise there are word-level cells without a - 'group' tag - -.. autocellgroup:: word_other - :caption: Other word-level cells - :members: - :source: - :linenos: +.. todo:: Add check for unexpected ``word_other`` cells From 217c2a15dd1af93835ce5afbe060b84663bb9e5c Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 3 Sep 2024 12:13:52 +1200 Subject: [PATCH 069/496] Docs: Add todos from JF --- docs/source/cell/word_binary.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/source/cell/word_binary.rst b/docs/source/cell/word_binary.rst index 68bc5a3aa..5c802294c 100644 --- a/docs/source/cell/word_binary.rst +++ b/docs/source/cell/word_binary.rst @@ -4,7 +4,17 @@ Binary operators ~~~~~~~~~~~~~~~~ -.. todo:: Add detail on ``$*x`` cells, `$eqx`, `$nex`, `$bweqx`, `$shiftx` +.. todo:: 'x' aware warning + + some passes will treat cell as the non 'x' aware cell, i.e. synthesis; `$eqx` + `$nex` `$bweqx` + +.. todo:: 'x' output + + shiftx, div, mod, pmux (less-so) can produce 'x' output even if all inputs + are defined + +.. todo:: `$eqx` is the case equality operator All binary RTL cells have two input ports ``A`` and ``B`` and one output port ``Y``. They also have the following parameters: From 5c4f7b4debfd7c7ae0dab6af4729b1244545f500 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 5 Sep 2024 16:10:28 +1200 Subject: [PATCH 070/496] Docs: $eqx aka case equality --- docs/source/cell/word_binary.rst | 2 -- techlibs/common/simlib.v | 9 +++++---- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/source/cell/word_binary.rst b/docs/source/cell/word_binary.rst index 5c802294c..87d558eda 100644 --- a/docs/source/cell/word_binary.rst +++ b/docs/source/cell/word_binary.rst @@ -14,8 +14,6 @@ Binary operators shiftx, div, mod, pmux (less-so) can produce 'x' output even if all inputs are defined -.. todo:: `$eqx` is the case equality operator - All binary RTL cells have two input ports ``A`` and ``B`` and one output port ``Y``. They also have the following parameters: diff --git a/techlibs/common/simlib.v b/techlibs/common/simlib.v index a954b64ec..bf30443c5 100644 --- a/techlibs/common/simlib.v +++ b/techlibs/common/simlib.v @@ -833,10 +833,11 @@ endmodule //- $eqx (A, B, Y) //* group binary //- -//- An exact equality comparison between inputs 'A' and 'B'. -//- This corresponds to the Verilog '===' operator. -//- Unlike equality comparison that can give 'x' as output, -//- an exact equality comparison will strictly give '0' or '1' as output. +//- An exact equality comparison between inputs 'A' and 'B'. Also known as the +//- case equality operator. This corresponds to the Verilog '===' operator. +//- Unlike equality comparison that can give 'x' as output, an exact equality +//- comparison will strictly give '0' or '1' as output, even if input includes +//- 'x' or 'z' values. //- module \$eqx (A, B, Y); From f70a66f5b3bf8e66e5ffc49ce9050c8609a3ba64 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 5 Sep 2024 16:20:13 +1200 Subject: [PATCH 071/496] Docs: Assert cell has group Explicitly assign $_TBUF_ to `gate_other` and remove catch if a cell has no group. --- docs/source/cell_word.rst | 2 -- techlibs/common/cellhelp.py | 7 +------ techlibs/common/simcells.v | 1 + 3 files changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/source/cell_word.rst b/docs/source/cell_word.rst index bfb14f510..d52c4c934 100644 --- a/docs/source/cell_word.rst +++ b/docs/source/cell_word.rst @@ -28,5 +28,3 @@ Simulation models for the RTL cells can be found in the file /cell/word_formal /cell/word_debug /cell/word_wire - -.. todo:: Add check for unexpected ``word_other`` cells diff --git a/techlibs/common/cellhelp.py b/techlibs/common/cellhelp.py index 9aa3def93..a6b2ce88a 100644 --- a/techlibs/common/cellhelp.py +++ b/techlibs/common/cellhelp.py @@ -88,12 +88,7 @@ for line in fileinput.input(): simHelper.desc.pop(1) # check group - if not simHelper.group: - if short_filename == 'simcells.v': - simHelper.group = "gate_" - elif short_filename == 'simlib.v': - simHelper.group = "word_" - simHelper.group += "other" + assert simHelper.group, f"techlibs/common/{simHelper.source}: {simHelper.name} cell missing group" # dump print(simHelper) diff --git a/techlibs/common/simcells.v b/techlibs/common/simcells.v index 104022079..1a113447e 100644 --- a/techlibs/common/simcells.v +++ b/techlibs/common/simcells.v @@ -461,6 +461,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $_TBUF_ (A, E, Y) +//* group gate_other //- //- A tri-state buffer. //- From 9ce69521316d320c1078089f0b7cf63127950621 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 5 Sep 2024 16:22:16 +1200 Subject: [PATCH 072/496] Docs: TODOs block, todos don't --- docs/source/cell/word_formal.rst | 2 +- docs/source/cell/word_fsm.rst | 2 +- docs/source/cell/word_spec.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/cell/word_formal.rst b/docs/source/cell/word_formal.rst index 8c52422a8..df78eb0b2 100644 --- a/docs/source/cell/word_formal.rst +++ b/docs/source/cell/word_formal.rst @@ -5,7 +5,7 @@ Formal verification cells If only I remembered what the note was... -.. TODO:: Describe formal cells +.. todo:: Describe formal cells `$check`, `$assert`, `$assume`, `$live`, `$fair`, `$cover`, `$equiv`, `$initstate`, `$anyconst`, `$anyseq`, `$anyinit`, `$allconst`, and `$allseq`. diff --git a/docs/source/cell/word_fsm.rst b/docs/source/cell/word_fsm.rst index 943904b2b..e6301bf3b 100644 --- a/docs/source/cell/word_fsm.rst +++ b/docs/source/cell/word_fsm.rst @@ -1,7 +1,7 @@ Finite state machines --------------------- -.. TODO:: Describe `$fsm` cell +.. todo:: Describe `$fsm` cell .. autocellgroup:: fsm :members: diff --git a/docs/source/cell/word_spec.rst b/docs/source/cell/word_spec.rst index 33ef40774..b5ce967d0 100644 --- a/docs/source/cell/word_spec.rst +++ b/docs/source/cell/word_spec.rst @@ -1,7 +1,7 @@ Specify rules ------------- -.. TODO:: `$specify2`, `$specify3`, and `$specrule` cells. +.. todo:: `$specify2`, `$specify3`, and `$specrule` cells. .. autocellgroup:: spec :members: From b1025dbaa6f81454486fb33778b8950a25045646 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 5 Sep 2024 16:51:26 +1200 Subject: [PATCH 073/496] cellhelp.py: Cells can have tags Tags are added to the list of properties when exporting to `cells.json`. --- kernel/register.cc | 21 +++++++++++++++------ techlibs/common/cellhelp.py | 3 +++ 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/kernel/register.cc b/kernel/register.cc index ce6eb8018..311c92961 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -766,6 +766,7 @@ struct SimHelper { string code; string group; string ver; + string tags; }; static bool is_code_getter(string name) { @@ -1013,12 +1014,20 @@ struct HelpPass : public Pass { for (auto &output : ct.outputs) outputs.push_back(output.str()); json.name("outputs"); json.value(outputs); - dict prop_dict = { - {"is_evaluable", ct.is_evaluable}, - {"is_combinatorial", ct.is_combinatorial}, - {"is_synthesizable", ct.is_synthesizable}, - }; - json.name("properties"); json.value(prop_dict); + vector properties; + // CellType properties + if (ct.is_evaluable) properties.push_back("is_evaluable"); + if (ct.is_combinatorial) properties.push_back("is_combinatorial"); + if (ct.is_synthesizable) properties.push_back("is_synthesizable"); + // SimHelper properties + size_t last = 0; size_t next = 0; + while ((next = ch.tags.find(", ", last)) != string::npos) { + properties.push_back(ch.tags.substr(last, next-last)); + last = next + 2; + } + auto final_tag = ch.tags.substr(last); + if (final_tag.size()) properties.push_back(final_tag); + json.name("properties"); json.value(properties); json.end_object(); } json.end_object(); diff --git a/techlibs/common/cellhelp.py b/techlibs/common/cellhelp.py index a6b2ce88a..741558730 100644 --- a/techlibs/common/cellhelp.py +++ b/techlibs/common/cellhelp.py @@ -14,13 +14,16 @@ class SimHelper: code: list[str] group: str = "" ver: str = "1" + tags: list[str] def __init__(self) -> None: self.desc = [] + self.tags = [] def __str__(self) -> str: printed_fields = [ "name", "title", "ports", "source", "desc", "code", "group", "ver", + "tags", ] # generate C++ struct val = f"cell_help[{json.dumps(self.name)}] = " From ed923742638a94f3f87137e3b928cdb0bafc2bb8 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 5 Sep 2024 17:46:46 +1200 Subject: [PATCH 074/496] simlib.v: Update case equality operators to v2 Also tag as x-aware cells and add titles. --- techlibs/common/simlib.v | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/techlibs/common/simlib.v b/techlibs/common/simlib.v index bf30443c5..959ba1419 100644 --- a/techlibs/common/simlib.v +++ b/techlibs/common/simlib.v @@ -828,11 +828,10 @@ endmodule // -------------------------------------------------------- -// |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| -//- -//- $eqx (A, B, Y) +//* ver 2 +//* title Case equality //* group binary -//- +//* tags x-aware //- An exact equality comparison between inputs 'A' and 'B'. Also known as the //- case equality operator. This corresponds to the Verilog '===' operator. //- Unlike equality comparison that can give 'x' as output, an exact equality @@ -863,15 +862,13 @@ endmodule // -------------------------------------------------------- -// |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| -//- -//- $nex (A, B, Y) +//* ver 2 +//* title Case inequality //* group binary -//- -//- An exact inequality comparison between inputs 'A' and 'B'. +//* tags x-aware //- This corresponds to the Verilog '!==' operator. -//- Unlike inequality comparison that can give 'x' as output, -//- an exact inequality comparison will strictly give '0' or '1' as output. +//- +//- Refer to `$eqx` for more details. //- module \$nex (A, B, Y); @@ -1871,7 +1868,13 @@ endspecify endmodule // -------------------------------------------------------- + +//* ver 2 +//* title Bit-wise case equality //* group binary +//* tags x-aware +//- A bit-wise version of `$eqx`. +//- module \$bweqx (A, B, Y); parameter WIDTH = 0; From 1a2401816a7b6395ac48f092f94369712bafa814 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 5 Sep 2024 17:47:36 +1200 Subject: [PATCH 075/496] Docs: Add cell title TODO --- docs/source/cell/word_binary.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/cell/word_binary.rst b/docs/source/cell/word_binary.rst index 87d558eda..70b54004e 100644 --- a/docs/source/cell/word_binary.rst +++ b/docs/source/cell/word_binary.rst @@ -4,6 +4,8 @@ Binary operators ~~~~~~~~~~~~~~~~ +.. TODO:: display cell titles + .. todo:: 'x' aware warning some passes will treat cell as the non 'x' aware cell, i.e. synthesis; `$eqx` From e3d939b7190c20551ec8dbe0ba0c460af06b2d92 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 5 Sep 2024 17:50:32 +1200 Subject: [PATCH 076/496] Docs: Drop fifo.out and fifo.stat These two files can now be safely .gitignore'd. --- docs/source/code_examples/fifo/.gitignore | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 docs/source/code_examples/fifo/.gitignore diff --git a/docs/source/code_examples/fifo/.gitignore b/docs/source/code_examples/fifo/.gitignore new file mode 100644 index 000000000..b858bebc6 --- /dev/null +++ b/docs/source/code_examples/fifo/.gitignore @@ -0,0 +1,2 @@ +*.out +*.stat From ce6a7fe4fc9949787f768b8e743b38ae017fe0ea Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 6 Sep 2024 15:17:51 +1200 Subject: [PATCH 077/496] docs/util: Cells now have properties Properties are both an option: ``` .. cell:def:: $add :properties: is_evaluable ``` and a field: ``` .. cell:def:: $eqx :property x-aware: :property is_evaluable: ``` Properties as an option appear in the property index: linking a given property to all cells with that property; while properties as a field display with the cell. --- docs/util/cellref.py | 15 +++- docs/util/cmdref.py | 190 ++++++++++++++++++++++++++++++++++++++----- 2 files changed, 184 insertions(+), 21 deletions(-) diff --git a/docs/util/cellref.py b/docs/util/cellref.py index 3bba27876..71e8eecd1 100644 --- a/docs/util/cellref.py +++ b/docs/util/cellref.py @@ -33,7 +33,7 @@ class YosysCell: code: str inputs: list[str] outputs: list[str] - properties: dict[str, bool] + properties: list[str] class YosysCellGroupDocumenter(Documenter): objtype = 'cellgroup' @@ -298,11 +298,22 @@ class YosysCellDocumenter(YosysCellGroupDocumenter): self.add_line(f'.. {domain}:{directive}:: {sig}', sourcename) # options - opt_attrs = ["title", ] + opt_attrs = ["title", "properties", ] for attr in opt_attrs: val = getattr(cell, attr, None) + if isinstance(val, list): + val = ' '.join(val) if val: self.add_line(f' :{attr}: {val}', sourcename) + + self.add_line('\n', sourcename) + + # fields + field_attrs = ["properties", ] + for field in field_attrs: + attr = getattr(cell, field, []) + for val in attr: + self.add_line(f' :{field} {val}:', sourcename) if self.options.noindex: self.add_line(' :noindex:', sourcename) diff --git a/docs/util/cmdref.py b/docs/util/cmdref.py index c7bb4e241..c177fdfa6 100644 --- a/docs/util/cmdref.py +++ b/docs/util/cmdref.py @@ -2,17 +2,22 @@ from __future__ import annotations +import re +from typing import cast + from docutils import nodes -from docutils.nodes import Node, Element +from docutils.nodes import Node, Element, system_message from docutils.parsers.rst import directives from docutils.parsers.rst.states import Inliner from sphinx.application import Sphinx from sphinx.domains import Domain, Index from sphinx.domains.std import StandardDomain +from sphinx.environment import BuildEnvironment from sphinx.roles import XRefRole from sphinx.directives import ObjectDescription from sphinx.directives.code import container_wrapper from sphinx.util.nodes import make_refnode +from sphinx.util.docfields import Field from sphinx import addnodes class TocNode(ObjectDescription): @@ -70,7 +75,8 @@ class CommandNode(TocNode): return signode['fullname'] def add_target_and_index(self, name_cls, sig, signode): - signode['ids'].append(type(self).name + '-' + sig) + idx = type(self).name + '-' + sig + signode['ids'].append(idx) if 'noindex' not in self.options: name = "{}.{}.{}".format(self.name, type(self).__name__, sig) tagmap = self.env.domaindata[type(self).name]['obj2tag'] @@ -79,13 +85,81 @@ class CommandNode(TocNode): titlemap = self.env.domaindata[type(self).name]['obj2title'] titlemap[name] = title objs = self.env.domaindata[type(self).name]['objects'] + # (name, sig, typ, docname, anchor, prio) objs.append((name, sig, - title, + type(self).name, self.env.docname, - type(self).name + '-' + sig, + idx, 0)) +class PropNode(TocNode): + name = 'prop' + fieldname = 'props' + + def handle_signature(self, sig: str, signode: addnodes.desc_signature): + signode['fullname'] = sig + signode['tocname'] = tocname = sig.split('::')[-1] + signode += addnodes.desc_name(text=tocname) + return signode['fullname'] + + def add_target_and_index( + self, + name: str, + sig: str, + signode: addnodes.desc_signature + ) -> None: + idx = ".".join(name.split("::")) + signode['ids'].append(idx) + if 'noindex' not in self.options: + tocname: str = signode.get('tocname', name) + objs = self.env.domaindata[self.domain]['objects'] + # (name, sig, typ, docname, anchor, prio) + objs.append((name, + tocname, + type(self).name, + self.env.docname, + idx, + 1)) + +class CellGroupedField(Field): + """Custom version of GroupedField which doesn't require content.""" + is_grouped = True + list_type = nodes.bullet_list + + def __init__(self, name: str, names: tuple[str, ...] = (), label: str = None, + rolename: str = None, can_collapse: bool = False) -> None: + super().__init__(name, names, label, True, rolename) + self.can_collapse = can_collapse + + def make_field(self, types: dict[str, list[Node]], domain: str, + items: tuple, env: BuildEnvironment = None, + inliner: Inliner = None, location: Node = None) -> nodes.field: + fieldname = nodes.field_name('', self.label) + listnode = self.list_type() + for fieldarg, content in items: + par = nodes.paragraph() + if fieldarg: + par.extend(self.make_xrefs(self.rolename, domain, + fieldarg, nodes.Text, + env=env, inliner=inliner, location=location)) + + if len(content) == 1 and ( + isinstance(content[0], nodes.Text) or + (isinstance(content[0], nodes.inline) and len(content[0]) == 1 and + isinstance(content[0][0], nodes.Text))): + par += nodes.Text(' -- ') + par += content + listnode += nodes.list_item('', par) + + if len(items) == 1 and self.can_collapse: + list_item = cast(nodes.list_item, listnode[0]) + fieldbody = nodes.field_body('', list_item[0]) + return nodes.field('', fieldname, fieldbody) + + fieldbody = nodes.field_body('', listnode) + return nodes.field('', fieldname, fieldbody) + class CellNode(TocNode): """A custom node that describes an internal cell.""" @@ -94,8 +168,15 @@ class CellNode(TocNode): option_spec = { 'title': directives.unchanged, 'ports': directives.unchanged, + 'properties': directives.unchanged, } + doc_field_types = [ + CellGroupedField('props', label='Properties', rolename='prop', + names=('properties', 'property', 'tag', 'tags'), + can_collapse=True), + ] + def handle_signature(self, sig: str, signode: addnodes.desc_signature): signode['fullname'] = sig signode['tocname'] = tocname = sig.split('::')[-1] @@ -113,16 +194,18 @@ class CellNode(TocNode): signode['ids'].append(idx) if 'noindex' not in self.options: tocname: str = signode.get('tocname', name) - tagmap = self.env.domaindata[self.domain]['obj2tag'] - tagmap[name] = list(self.options.get('tags', '').split(' ')) title: str = self.options.get('title', sig) titlemap = self.env.domaindata[self.domain]['obj2title'] titlemap[name] = title + props = self.options.get('properties', '') + if props: + propmap = self.env.domaindata[self.domain]['obj2prop'] + propmap[name] = props.split(' ') objs = self.env.domaindata[self.domain]['objects'] # (name, sig, typ, docname, anchor, prio) objs.append((name, tocname, - title, + type(self).name, self.env.docname, idx, 0)) @@ -288,7 +371,7 @@ class TagIndex(Index): in self.domain.get_objects()} tmap = {} - tags = self.domain.data['obj2tag'] + tags = self.domain.data[f'obj2{self.name}'] for name, tags in tags.items(): for tag in tags: tmap.setdefault(tag,[]) @@ -304,10 +387,9 @@ class TagIndex(Index): anchor, docname, '', typ )) - re = [(k, v) for k, v in sorted(content.items())] - - return (re, True) + ret = [(k, v) for k, v in sorted(content.items())] + return (ret, True) class CommandIndex(Index): name = 'cmd' @@ -345,7 +427,8 @@ class CommandIndex(Index): content = {} items = ((name, dispname, typ, docname, anchor) for name, dispname, typ, docname, anchor, prio - in self.domain.get_objects()) + in self.domain.get_objects() + if typ == self.name) items = sorted(items, key=lambda item: item[0]) for name, dispname, typ, docname, anchor in items: lis = content.setdefault(self.shortname, []) @@ -354,15 +437,68 @@ class CommandIndex(Index): anchor, '', '', typ )) - re = [(k, v) for k, v in sorted(content.items())] + ret = [(k, v) for k, v in sorted(content.items())] - return (re, True) + return (ret, True) class CellIndex(CommandIndex): name = 'cell' localname = 'Internal cell reference' shortname = 'Internal cell' +class PropIndex(TagIndex): + """A custom directive that creates a properties matrix.""" + + name = 'prop' + localname = 'Property Index' + shortname = 'Prop' + fieldname = 'props' + + def generate(self, docnames=None): + content = {} + + cells = {name: (dispname, docname, anchor) + for name, dispname, typ, docname, anchor, _ + in self.domain.get_objects() + if typ == 'cell'} + props = {name: (dispname, docname, anchor) + for name, dispname, typ, docname, anchor, _ + in self.domain.get_objects() + if typ == 'prop'} + + tmap: dict[str, list[str]] = {} + tags: dict[str, list[str]] = self.domain.data[f'obj2{self.name}'] + for name, tags in tags.items(): + for tag in tags: + tmap.setdefault(tag,[]) + tmap[tag].append(name) + + for tag in sorted(tmap.keys()): + test = re.match(r'^(\w+[_-])', tag) + tag_prefix = test.group(1) + lis = content.setdefault(tag_prefix, []) + try: + dispname, docname, anchor = props[tag] + except KeyError: + dispname = tag + docname = anchor = '' + lis.append(( + dispname, 1, docname, + anchor, + '', '', docname or 'unavailable' + )) + objlis = tmap[tag] + for objname in sorted(objlis): + dispname, docname, anchor = cells[objname] + lis.append(( + dispname, 2, docname, + anchor, + '', '', docname + )) + ret = [(k, v) for k, v in sorted(content.items())] + + return (ret, True) + class CommandDomain(Domain): name = 'cmd' label = 'Yosys commands' @@ -419,17 +555,33 @@ class CellDomain(CommandDomain): name = 'cell' label = 'Yosys internal cells' + roles = CommandDomain.roles.copy() + roles.update({ + 'prop': XRefRole() + }) + directives = { 'def': CellNode, + 'defprop': PropNode, 'source': CellSourceNode, 'group': CellGroupNode, } indices = { CellIndex, - TagIndex + PropIndex } + initial_data = { + 'objects': [], # object list + 'obj2prop': {}, # name -> properties + 'obj2title': {}, # name -> title + } + + def get_objects(self): + for obj in self.data['objects']: + yield(obj) + def autoref(name, rawtext: str, text: str, lineno, inliner: Inliner, options=None, content=None): role = 'cell:ref' if text[0] == '$' else 'cmd:ref' @@ -448,8 +600,8 @@ def setup(app: Sphinx): ('cmd-tag', '', 'Tag Index') StandardDomain.initial_data['labels']['cellindex'] =\ ('cell-cell', '', 'Internal cell reference') - StandardDomain.initial_data['labels']['tagindex'] =\ - ('cell-tag', '', 'Tag Index') + StandardDomain.initial_data['labels']['propindex'] =\ + ('cell-prop', '', 'Property Index') StandardDomain.initial_data['anonlabels']['commandindex'] =\ ('cmd-cmd', '') @@ -457,8 +609,8 @@ def setup(app: Sphinx): ('cmd-tag', '') StandardDomain.initial_data['anonlabels']['cellindex'] =\ ('cell-cell', '') - StandardDomain.initial_data['anonlabels']['tagindex'] =\ - ('cell-tag', '') + StandardDomain.initial_data['anonlabels']['propindex'] =\ + ('cell-prop', '') app.add_role('autoref', autoref) From 4d84d7e69f68143296e46999387d17f525df976d Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 6 Sep 2024 15:36:42 +1200 Subject: [PATCH 078/496] simlib.v: Add x-output tag Also a few extra cell help texts. --- techlibs/common/simlib.v | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/techlibs/common/simlib.v b/techlibs/common/simlib.v index 959ba1419..6da22dac0 100644 --- a/techlibs/common/simlib.v +++ b/techlibs/common/simlib.v @@ -526,7 +526,13 @@ endgenerate endmodule // -------------------------------------------------------- + +//* ver 2 +//* title Indexed part-select //* group binary +//* tags x-output +//- Same as the `$shift` cell, but fills with 'x'. +//- module \$shift (A, B, Y); @@ -559,7 +565,13 @@ endgenerate endmodule // -------------------------------------------------------- + +//* ver 2 +//* title Variable shifter //* group binary +//- Performs a right logical shift if the second operand is positive (or +//- unsigned), and a left logical shift if it is negative. +//- module \$shiftx (A, B, Y); @@ -1204,12 +1216,12 @@ endmodule // -------------------------------------------------------- -// |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| -//- -//- $div (A, B, Y) +//* ver 2 +//* title Divider //* group binary -//- -//- Division with truncated result (rounded towards 0). +//* tags x-output +//- This corresponds to the Verilog '/' operator, performing division and +//- truncating the result (rounding towards 0). //- module \$div (A, B, Y); @@ -1235,12 +1247,12 @@ endmodule // -------------------------------------------------------- -// |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| -//- -//- $mod (A, B, Y) +//* ver 2 +//* title Modulo //* group binary -//- -//- Modulo/remainder of division with truncated result (rounded towards 0). +//* tags x-output +//- This corresponds to the Verilog '%' operator, giving the module (or +//- remainder) of division and truncating the result (rounding towards 0). //- //- Invariant: $div(A, B) * B + $mod(A, B) == A //- @@ -1561,6 +1573,7 @@ endmodule // -------------------------------------------------------- //* group mux +//* tags x-output module \$pmux (A, B, S, Y); From e40134c856260d610b3ab2f242234e21f4f58ccd Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 6 Sep 2024 15:40:22 +1200 Subject: [PATCH 079/496] Docs: Update for properties Add properties page, move cell_gate and cell_word under a singular cell_index along with properties. Fix links accordingly. Also drop x-aware and x-output todos since they are resolved. --- docs/source/appendix/rtlil_text.rst | 4 ++-- .../{cell_gate.rst => cell/index_gate.rst} | 1 - .../{cell_word.rst => cell/index_word.rst} | 1 - docs/source/cell/properties.rst | 18 ++++++++++++++++++ docs/source/cell/word_binary.rst | 10 ---------- docs/source/cell_index.rst | 11 +++++++++++ docs/source/index.rst | 3 +-- .../interactive_investigation.rst | 2 +- docs/source/using_yosys/synthesis/opt.rst | 2 +- 9 files changed, 34 insertions(+), 18 deletions(-) rename docs/source/{cell_gate.rst => cell/index_gate.rst} (96%) rename docs/source/{cell_word.rst => cell/index_word.rst} (98%) create mode 100644 docs/source/cell/properties.rst create mode 100644 docs/source/cell_index.rst diff --git a/docs/source/appendix/rtlil_text.rst b/docs/source/appendix/rtlil_text.rst index 7febae2ed..2c7a82d19 100644 --- a/docs/source/appendix/rtlil_text.rst +++ b/docs/source/appendix/rtlil_text.rst @@ -223,8 +223,8 @@ Cells Declares a cell, with zero or more attributes, with the given identifier and type in the enclosing module. -Cells perform functions on input signals. See :doc:`/cell_gate` and -:doc:`/cell_word` for a detailed list of cell types. +Cells perform functions on input signals. See :doc:`/cell_index` for a detailed +list of cell types. .. code:: BNF diff --git a/docs/source/cell_gate.rst b/docs/source/cell/index_gate.rst similarity index 96% rename from docs/source/cell_gate.rst rename to docs/source/cell/index_gate.rst index 4ff38ec5e..c9decc045 100644 --- a/docs/source/cell_gate.rst +++ b/docs/source/cell/index_gate.rst @@ -16,7 +16,6 @@ The combinatorial logic cells can be mapped to physical cells from a Liberty file via ABC using the abc pass. .. toctree:: - :caption: Gate-level cells :maxdepth: 2 /cell/gate_comb_simple diff --git a/docs/source/cell_word.rst b/docs/source/cell/index_word.rst similarity index 98% rename from docs/source/cell_word.rst rename to docs/source/cell/index_word.rst index d52c4c934..cb81c6991 100644 --- a/docs/source/cell_word.rst +++ b/docs/source/cell/index_word.rst @@ -15,7 +15,6 @@ Simulation models for the RTL cells can be found in the file .. toctree:: :maxdepth: 2 - :glob: /cell/word_unary /cell/word_binary diff --git a/docs/source/cell/properties.rst b/docs/source/cell/properties.rst new file mode 100644 index 000000000..72ea76112 --- /dev/null +++ b/docs/source/cell/properties.rst @@ -0,0 +1,18 @@ +Cell properties +--------------- + +.. TODO:: Fill :cell:ref:`is_evaluable` + +.. cell:defprop:: is_evaluable + +.. cell:defprop:: x-aware + + Some passes will treat these cells as the non 'x' aware cell. For example, + during synthesis `$eqx` will typically be treated as `$eq`. + +.. cell:defprop:: x-output + + These cells can produce 'x' output even if all inputs are defined. For + example, a `$div` cell with ``B=0`` has undefined output. + +Refer to the :ref:`propindex` for the list of cells with a given property. diff --git a/docs/source/cell/word_binary.rst b/docs/source/cell/word_binary.rst index 70b54004e..b0287f2d1 100644 --- a/docs/source/cell/word_binary.rst +++ b/docs/source/cell/word_binary.rst @@ -6,16 +6,6 @@ Binary operators .. TODO:: display cell titles -.. todo:: 'x' aware warning - - some passes will treat cell as the non 'x' aware cell, i.e. synthesis; `$eqx` - `$nex` `$bweqx` - -.. todo:: 'x' output - - shiftx, div, mod, pmux (less-so) can produce 'x' output even if all inputs - are defined - All binary RTL cells have two input ports ``A`` and ``B`` and one output port ``Y``. They also have the following parameters: diff --git a/docs/source/cell_index.rst b/docs/source/cell_index.rst new file mode 100644 index 000000000..dcfd38a76 --- /dev/null +++ b/docs/source/cell_index.rst @@ -0,0 +1,11 @@ +Internal cell library +===================== + +.. todo:: brief overview of internal cell library + +.. toctree:: + :maxdepth: 2 + + /cell/index_word + /cell/index_gate + /cell/properties diff --git a/docs/source/index.rst b/docs/source/index.rst index fbdd5ac6f..8b9cff869 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -50,6 +50,5 @@ available, go to :ref:`commandindex`. bib - cell_word - cell_gate + cell_index cmd_ref diff --git a/docs/source/using_yosys/more_scripting/interactive_investigation.rst b/docs/source/using_yosys/more_scripting/interactive_investigation.rst index 68b538076..c6180306d 100644 --- a/docs/source/using_yosys/more_scripting/interactive_investigation.rst +++ b/docs/source/using_yosys/more_scripting/interactive_investigation.rst @@ -65,7 +65,7 @@ displayed as rectangles with inputs on the left and outputs on the right side. The cell labels are two lines long: The first line contains a unique identifier for the cell and the second line contains the cell type. Internal cell types are prefixed with a dollar sign. For more details on the internal cell library, see -:doc:`/cell_gate` and :doc:`/cell_word`. +:doc:`/cell_index`. Constants are shown as ellipses with the constant value as label. The syntax ``'`` is used for constants that are not 32-bit wide and/or diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst index d79a66a75..743b24997 100644 --- a/docs/source/using_yosys/synthesis/opt.rst +++ b/docs/source/using_yosys/synthesis/opt.rst @@ -27,7 +27,7 @@ Constant folding and simple expression rewriting - `opt_expr` .. todo:: unsure if this is too much detail and should be in :doc:`/yosys_internals/index` This pass performs constant folding on the internal combinational cell types -described in :doc:`/cell_gate` and :doc:`/cell_word`. This means a cell with all +described in :doc:`/cell_index`. This means a cell with all constant inputs is replaced with the constant value this cell drives. In some cases this pass can also optimize cells with some constant inputs. From 9d808caba6f5a8b26954137618dc61dad0f57681 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 16 Sep 2024 13:02:54 +1200 Subject: [PATCH 080/496] Docs: Add note on $check --- docs/source/cell/word_formal.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/source/cell/word_formal.rst b/docs/source/cell/word_formal.rst index df78eb0b2..6bfa19656 100644 --- a/docs/source/cell/word_formal.rst +++ b/docs/source/cell/word_formal.rst @@ -1,9 +1,14 @@ Formal verification cells ------------------------- -.. TODO:: note on `$check` +.. role:: yoscrypt(code) + :language: yoscrypt - If only I remembered what the note was... +.. note:: + + Some front-ends may not support the generic `$check` cell, in such cases + calling :yoscrypt:`chformal -lower` will convert each `$check` cell into it's + equivalent. See `chformal` for more. .. todo:: Describe formal cells From 7216f076916f3bddf271d3a6a3ea2fd612abcd44 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 16 Sep 2024 13:11:31 +1200 Subject: [PATCH 081/496] Docs: Define is_evaluable --- docs/source/cell/properties.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/cell/properties.rst b/docs/source/cell/properties.rst index 72ea76112..e853ea50a 100644 --- a/docs/source/cell/properties.rst +++ b/docs/source/cell/properties.rst @@ -1,10 +1,12 @@ Cell properties --------------- -.. TODO:: Fill :cell:ref:`is_evaluable` - .. cell:defprop:: is_evaluable + These cells are able to be used in conjunction with the `eval` command. Some + passes, such as `opt_expr`, may also be able to perform additional + optimizations on cells which are evaluable. + .. cell:defprop:: x-aware Some passes will treat these cells as the non 'x' aware cell. For example, From 927dc445ddd99feb7373eb046e365f48897ff38d Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 16 Sep 2024 14:11:01 +1200 Subject: [PATCH 082/496] Docs: Render cell titles Also put property lists *after* cell description. --- docs/source/cell/word_binary.rst | 2 -- docs/util/cellref.py | 17 +++++++++-------- docs/util/cmdref.py | 8 ++++++++ 3 files changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/source/cell/word_binary.rst b/docs/source/cell/word_binary.rst index b0287f2d1..47a847ee4 100644 --- a/docs/source/cell/word_binary.rst +++ b/docs/source/cell/word_binary.rst @@ -4,8 +4,6 @@ Binary operators ~~~~~~~~~~~~~~~~ -.. TODO:: display cell titles - All binary RTL cells have two input ports ``A`` and ``B`` and one output port ``Y``. They also have the following parameters: diff --git a/docs/util/cellref.py b/docs/util/cellref.py index 71e8eecd1..58e65c2ea 100644 --- a/docs/util/cellref.py +++ b/docs/util/cellref.py @@ -305,15 +305,8 @@ class YosysCellDocumenter(YosysCellGroupDocumenter): val = ' '.join(val) if val: self.add_line(f' :{attr}: {val}', sourcename) - - self.add_line('\n', sourcename) - # fields - field_attrs = ["properties", ] - for field in field_attrs: - attr = getattr(cell, field, []) - for val in attr: - self.add_line(f' :{field} {val}:', sourcename) + self.add_line('\n', sourcename) if self.options.noindex: self.add_line(' :noindex:', sourcename) @@ -331,6 +324,14 @@ class YosysCellDocumenter(YosysCellGroupDocumenter): for line, src in zip(more_content.data, more_content.items): self.add_line(line, src[0], src[1]) + # fields + self.add_line('\n', sourcename) + field_attrs = ["properties", ] + for field in field_attrs: + attr = getattr(self.object, field, []) + for val in attr: + self.add_line(f':{field} {val}:', sourcename) + def get_object_members( self, want_all: bool diff --git a/docs/util/cmdref.py b/docs/util/cmdref.py index c177fdfa6..a31b08e0d 100644 --- a/docs/util/cmdref.py +++ b/docs/util/cmdref.py @@ -209,6 +209,14 @@ class CellNode(TocNode): self.env.docname, idx, 0)) + + def transform_content(self, contentnode: addnodes.desc_content) -> None: + # Add the cell title to the body + if 'title' in self.options: + titlenode = nodes.paragraph() + titlenode += nodes.strong() + titlenode[-1] += nodes.Text(self.options['title']) + contentnode.insert(0, titlenode) class CellSourceNode(TocNode): """A custom code block for including cell source.""" From dfe803b5c6921a56cbc80c1255c772d7d80d4f8e Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 16 Sep 2024 20:38:37 +1200 Subject: [PATCH 083/496] Docs: Comments from @jix - Unswap shift/shiftx - Add brief overview to cell lib - Clarify $div cell B input - Clarify unary operators - What is $modfloor --- docs/source/cell/properties.rst | 3 ++- docs/source/cell/word_binary.rst | 4 ++-- docs/source/cell/word_unary.rst | 10 +++++----- docs/source/cell_index.rst | 6 +++++- techlibs/common/simlib.v | 12 ++++++------ 5 files changed, 20 insertions(+), 15 deletions(-) diff --git a/docs/source/cell/properties.rst b/docs/source/cell/properties.rst index e853ea50a..30c58ee51 100644 --- a/docs/source/cell/properties.rst +++ b/docs/source/cell/properties.rst @@ -15,6 +15,7 @@ Cell properties .. cell:defprop:: x-output These cells can produce 'x' output even if all inputs are defined. For - example, a `$div` cell with ``B=0`` has undefined output. + example, a `$div` cell with divisor (``B``) equal to zero has undefined + output. Refer to the :ref:`propindex` for the list of cells with a given property. diff --git a/docs/source/cell/word_binary.rst b/docs/source/cell/word_binary.rst index 47a847ee4..5e1e6cd19 100644 --- a/docs/source/cell/word_binary.rst +++ b/docs/source/cell/word_binary.rst @@ -66,8 +66,8 @@ Division and modulo cells are available in two rounding modes. The original `$div` and `$mod` cells are based on truncating division, and correspond to the semantics of the verilog ``/`` and ``%`` operators. The `$divfloor` and `$modfloor` cells represent flooring division and flooring modulo, the latter of -which is also known as "remainder" in several languages. See the following table -for a side-by-side comparison between the different semantics. +which corresponds to the ``%`` operator in Python. See the following table for a +side-by-side comparison between the different semantics. .. table:: Comparison between different rounding modes for division and modulo cells. diff --git a/docs/source/cell/word_unary.rst b/docs/source/cell/word_unary.rst index 59f03397c..1243ef60c 100644 --- a/docs/source/cell/word_unary.rst +++ b/docs/source/cell/word_unary.rst @@ -38,11 +38,11 @@ For the unary cells that output a logical value (`$reduce_and`, `$reduce_or`, ``Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and only the least significant bit varies. -Note that `$reduce_or` and `$reduce_bool` actually represent the same logic -function. But the HDL frontends generate them in different situations. A -`$reduce_or` cell is generated when the prefix ``|`` operator is being used. A -`$reduce_bool` cell is generated when a bit vector is used as a condition in an -``if``-statement or ``?:``-expression. +Note that `$reduce_or` and `$reduce_bool` generally represent the same logic +function. But the `read_verilog` frontend will generate them in different +situations. A `$reduce_or` cell is generated when the prefix ``|`` operator is +being used. A `$reduce_bool` cell is generated when a bit vector is used as a +condition in an ``if``-statement or ``?:``-expression. .. autocellgroup:: unary :members: diff --git a/docs/source/cell_index.rst b/docs/source/cell_index.rst index dcfd38a76..2d64db95e 100644 --- a/docs/source/cell_index.rst +++ b/docs/source/cell_index.rst @@ -1,7 +1,11 @@ Internal cell library ===================== -.. todo:: brief overview of internal cell library +The intermediate language used by Yosys (RTLIL) represents logic and memory with +a series of cells. This section provides details for those cells, breaking them +down into two major categories: coarse-grain word-level cells; and fine-grain +gate-level cells. An additional section contains a list of properties which may +be shared across multiple cells. .. toctree:: :maxdepth: 2 diff --git a/techlibs/common/simlib.v b/techlibs/common/simlib.v index 6da22dac0..19cb2f7a1 100644 --- a/techlibs/common/simlib.v +++ b/techlibs/common/simlib.v @@ -528,10 +528,10 @@ endmodule // -------------------------------------------------------- //* ver 2 -//* title Indexed part-select +//* title Variable shifter //* group binary -//* tags x-output -//- Same as the `$shift` cell, but fills with 'x'. +//- Performs a right logical shift if the second operand is positive (or +//- unsigned), and a left logical shift if it is negative. //- module \$shift (A, B, Y); @@ -567,10 +567,10 @@ endmodule // -------------------------------------------------------- //* ver 2 -//* title Variable shifter +//* title Indexed part-select //* group binary -//- Performs a right logical shift if the second operand is positive (or -//- unsigned), and a left logical shift if it is negative. +//* tags x-output +//- Same as the `$shift` cell, but fills with 'x'. //- module \$shiftx (A, B, Y); From 1513366f215536c8e8376e6160ec4393c0223648 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 15 Oct 2024 07:11:56 +1300 Subject: [PATCH 084/496] Docs: Adding mux cell descriptions Also making ver2 cell descriptions consistently spaced. --- techlibs/common/simlib.v | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/techlibs/common/simlib.v b/techlibs/common/simlib.v index 19cb2f7a1..3c429d757 100644 --- a/techlibs/common/simlib.v +++ b/techlibs/common/simlib.v @@ -32,7 +32,6 @@ */ // -------------------------------------------------------- - //* ver 2 //* title Bit-wise inverter //* group unary @@ -526,14 +525,12 @@ endgenerate endmodule // -------------------------------------------------------- - //* ver 2 //* title Variable shifter //* group binary //- Performs a right logical shift if the second operand is positive (or //- unsigned), and a left logical shift if it is negative. //- - module \$shift (A, B, Y); parameter A_SIGNED = 0; @@ -565,14 +562,12 @@ endgenerate endmodule // -------------------------------------------------------- - //* ver 2 //* title Indexed part-select //* group binary //* tags x-output //- Same as the `$shift` cell, but fills with 'x'. //- - module \$shiftx (A, B, Y); parameter A_SIGNED = 0; @@ -649,7 +644,6 @@ end endmodule // -------------------------------------------------------- - //* ver 2 //* title Arithmetic logic unit //* group arith @@ -839,7 +833,6 @@ endgenerate endmodule // -------------------------------------------------------- - //* ver 2 //* title Case equality //* group binary @@ -873,7 +866,6 @@ endgenerate endmodule // -------------------------------------------------------- - //* ver 2 //* title Case inequality //* group binary @@ -1215,7 +1207,6 @@ end endmodule // -------------------------------------------------------- - //* ver 2 //* title Divider //* group binary @@ -1246,7 +1237,6 @@ endgenerate endmodule // -------------------------------------------------------- - //* ver 2 //* title Modulo //* group binary @@ -1544,8 +1534,12 @@ assign Y = S ? B : A; endmodule // -------------------------------------------------------- +//* ver 2 +//* title Binary-encoded multiplexer //* group mux - +//- Selects between 'slices' of A where each value of S corresponds to a unique +//- slice. +//- module \$bmux (A, S, Y); parameter WIDTH = 0; @@ -1572,9 +1566,13 @@ endgenerate endmodule // -------------------------------------------------------- +//* ver 2 +//* title Priority-encoded multiplexer //* group mux //* tags x-output - +//- Selects between 'slices' of B where each slice corresponds to a single bit +//- of S. Outputs A when all bits of S are low. +//- module \$pmux (A, B, S, Y); parameter WIDTH = 0; @@ -1881,7 +1879,6 @@ endspecify endmodule // -------------------------------------------------------- - //* ver 2 //* title Bit-wise case equality //* group binary @@ -1905,7 +1902,11 @@ endgenerate endmodule // -------------------------------------------------------- +//* ver 2 +//* title Bit-wise multiplexer //* group mux +//- Equivalent to a series of 1-bit wide `$mux` cells. +//- module \$bwmux (A, B, S, Y); parameter WIDTH = 0; From 27b8b4e81e169cc008ed16c1390790b19a883420 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 15 Oct 2024 11:08:30 +1300 Subject: [PATCH 085/496] Docs: Fix missing groups $lut and $sop were missed in the rebase, and $buf is new to main since the last rebase. --- techlibs/common/simlib.v | 3 +++ 1 file changed, 3 insertions(+) diff --git a/techlibs/common/simlib.v b/techlibs/common/simlib.v index 3c429d757..df9e1feb1 100644 --- a/techlibs/common/simlib.v +++ b/techlibs/common/simlib.v @@ -89,6 +89,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $buf (A, Y) +//* group unary //- //- A simple coarse-grain buffer cell type for the experimental buffered-normalized //- mode. Note this cell does't get removed by 'opt_clean' and is not recommended @@ -1635,6 +1636,7 @@ endmodule // -------------------------------------------------------- `ifndef SIMLIB_NOLUT +//* group logic module \$lut (A, Y); @@ -1650,6 +1652,7 @@ endmodule `endif // -------------------------------------------------------- +//* group logic module \$sop (A, Y); From c93fd54e43e5628e5a02c1fc0943515ab59bb287 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 15 Oct 2024 11:37:52 +1300 Subject: [PATCH 086/496] ci: Install docs/reqs (namely, furo-ys) --- .github/workflows/prepare-docs.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/prepare-docs.yml b/.github/workflows/prepare-docs.yml index e0388c7a3..79dfb7912 100644 --- a/.github/workflows/prepare-docs.yml +++ b/.github/workflows/prepare-docs.yml @@ -64,6 +64,11 @@ jobs: docs/source/_images docs/source/code_examples + - name: Install doc prereqs + shell: bash + run: | + make docs/reqs + - name: Test build docs shell: bash run: | From bc77575c224d1f7d61474216416f66f75e5f175f Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 15 Oct 2024 11:46:21 +1300 Subject: [PATCH 087/496] Docs: Fix word_logic.rst It somehow got lost in the rebase. --- docs/source/cell/index_word.rst | 1 + docs/source/cell/word_arith.rst | 45 -------------------------------- docs/source/cell/word_logic.rst | 46 +++++++++++++++++++++++++++++++++ 3 files changed, 47 insertions(+), 45 deletions(-) create mode 100644 docs/source/cell/word_logic.rst diff --git a/docs/source/cell/index_word.rst b/docs/source/cell/index_word.rst index cb81c6991..409e20d26 100644 --- a/docs/source/cell/index_word.rst +++ b/docs/source/cell/index_word.rst @@ -23,6 +23,7 @@ Simulation models for the RTL cells can be found in the file /cell/word_mem /cell/word_fsm /cell/word_arith + /cell/word_logic /cell/word_spec /cell/word_formal /cell/word_debug diff --git a/docs/source/cell/word_arith.rst b/docs/source/cell/word_arith.rst index eb1bfdada..49070814a 100644 --- a/docs/source/cell/word_arith.rst +++ b/docs/source/cell/word_arith.rst @@ -3,9 +3,6 @@ Coarse arithmetics .. todo:: Add information about `$alu`, `$fa`, and `$lcu` cells. -Multiply-accumulate -~~~~~~~~~~~~~~~~~~~ - The `$macc` cell type represents a generalized multiply and accumulate operation. The cell is purely combinational. It outputs the result of summing up a sequence of products and other injected summands. @@ -47,48 +44,6 @@ CONFIG parameter carries the following information: B is an array of concatenated 1-bit-wide unsigned integers to also be summed up. -Arbitrary logic functions -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The `$lut` cell type implements a single-output LUT (lookup table). It -implements an arbitrary logic function with its ``\LUT`` parameter to map input -port ``\A`` to values of ``\Y`` output port values. In psuedocode: ``Y = -\LUT[A]``. ``\A`` has width set by parameter ``\WIDTH`` and ``\Y`` has a width -of 1. Every logic function with a single bit output has a unique `$lut` -representation. - -The `$sop` cell type implements a sum-of-products expression, also known as -disjunctive normal form (DNF). It implements an arbitrary logic function. Its -structure mimics a programmable logic array (PLA). Output port ``\Y`` is the sum -of products of the bits of the input port ``\A`` as defined by parameter -``\TABLE``. ``\A`` is ``\WIDTH`` bits wide. The number of products in the sum is -set by parameter ``\DEPTH``, and each product has two bits for each input bit - -for the presence of the unnegated and negated version of said input bit in the -product. Therefore the ``\TABLE`` parameter holds ``2 * \WIDTH * \DEPTH`` bits. - -For example: - -Let ``\WIDTH`` be 3. We would like to represent ``\Y =~\A[0] + \A[1]~\A[2]``. -There are 2 products to be summed, so ``\DEPTH`` shall be 2. - -.. code-block:: - - ~A[2]-----+ - A[2]----+| - ~A[1]---+|| - A[1]--+||| - ~A[0]-+|||| - A[0]+||||| - |||||| product formula - 010000 ~\A[0] - 001001 \A[1]~\A[2] - -So the value of ``\TABLE`` will become ``010000001001``. - -Any logic function with a single bit output can be represented with ``$sop`` but -may have variously minimized or ordered summands represented in the ``\TABLE`` -values. - .. autocellgroup:: arith :members: :source: diff --git a/docs/source/cell/word_logic.rst b/docs/source/cell/word_logic.rst new file mode 100644 index 000000000..32945d560 --- /dev/null +++ b/docs/source/cell/word_logic.rst @@ -0,0 +1,46 @@ +Arbitrary logic functions +------------------------- + +The `$lut` cell type implements a single-output LUT (lookup table). It +implements an arbitrary logic function with its ``\LUT`` parameter to map input +port ``\A`` to values of ``\Y`` output port values. In psuedocode: ``Y = +\LUT[A]``. ``\A`` has width set by parameter ``\WIDTH`` and ``\Y`` has a width +of 1. Every logic function with a single bit output has a unique `$lut` +representation. + +The `$sop` cell type implements a sum-of-products expression, also known as +disjunctive normal form (DNF). It implements an arbitrary logic function. Its +structure mimics a programmable logic array (PLA). Output port ``\Y`` is the sum +of products of the bits of the input port ``\A`` as defined by parameter +``\TABLE``. ``\A`` is ``\WIDTH`` bits wide. The number of products in the sum is +set by parameter ``\DEPTH``, and each product has two bits for each input bit - +for the presence of the unnegated and negated version of said input bit in the +product. Therefore the ``\TABLE`` parameter holds ``2 * \WIDTH * \DEPTH`` bits. + +For example: + +Let ``\WIDTH`` be 3. We would like to represent ``\Y =~\A[0] + \A[1]~\A[2]``. +There are 2 products to be summed, so ``\DEPTH`` shall be 2. + +.. code-block:: + + ~A[2]-----+ + A[2]----+| + ~A[1]---+|| + A[1]--+||| + ~A[0]-+|||| + A[0]+||||| + |||||| product formula + 010000 ~\A[0] + 001001 \A[1]~\A[2] + +So the value of ``\TABLE`` will become ``010000001001``. + +Any logic function with a single bit output can be represented with ``$sop`` but +may have variously minimized or ordered summands represented in the ``\TABLE`` +values. + +.. autocellgroup:: logic + :members: + :source: + :linenos: \ No newline at end of file From f75b1e838cac3a4e15a5eb835a2c84b935b93af9 Mon Sep 17 00:00:00 2001 From: Jason Thorpe Date: Mon, 14 Oct 2024 16:06:34 -0700 Subject: [PATCH 088/496] misc/yosys-config.in: don't use the non-portable '==' operator with test(1). --- misc/yosys-config.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc/yosys-config.in b/misc/yosys-config.in index dd42b7c87..2d9c35e4d 100755 --- a/misc/yosys-config.in +++ b/misc/yosys-config.in @@ -44,7 +44,7 @@ if [ $# -eq 0 ]; then help fi -if [ "$1" == "--build" ]; then +if [ "$1" = "--build" ]; then modname="$2"; shift 2 set -- --exec --cxx --cxxflags --ldflags -o "$modname" -shared "$@" --libs fi From 09be0351ce3dcb142b035dcad5f9725b8ee54bd1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Povi=C5=A1er?= Date: Wed, 2 Oct 2024 11:25:12 +0200 Subject: [PATCH 089/496] select: Add new `t:@` syntax --- passes/cmds/select.cc | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/passes/cmds/select.cc b/passes/cmds/select.cc index e455baf7c..ff72724ae 100644 --- a/passes/cmds/select.cc +++ b/passes/cmds/select.cc @@ -876,9 +876,20 @@ static void select_stmt(RTLIL::Design *design, std::string arg, bool disable_emp sel.selected_members[mod->name].insert(cell->name); } else if (arg_memb.compare(0, 2, "t:") == 0) { - for (auto cell : mod->cells()) - if (match_ids(cell->type, arg_memb.substr(2))) - sel.selected_members[mod->name].insert(cell->name); + if (arg_memb.compare(2, 1, "@") == 0) { + std::string set_name = RTLIL::escape_id(arg_memb.substr(3)); + if (!design->selection_vars.count(set_name)) + log_cmd_error("Selection @%s is not defined!\n", RTLIL::unescape_id(set_name).c_str()); + + auto &muster = design->selection_vars[set_name]; + for (auto cell : mod->cells()) + if (muster.selected_modules.count(cell->type)) + sel.selected_members[mod->name].insert(cell->name); + } else { + for (auto cell : mod->cells()) + if (match_ids(cell->type, arg_memb.substr(2))) + sel.selected_members[mod->name].insert(cell->name); + } } else if (arg_memb.compare(0, 2, "p:") == 0) { for (auto &it : mod->processes) @@ -1164,6 +1175,9 @@ struct SelectPass : public Pass { log(" t:\n"); log(" all cells with a type matching the given pattern\n"); log("\n"); + log(" t:@\n"); + log(" all cells with a type matching a module in the saved selection \n"); + log("\n"); log(" p:\n"); log(" all processes with a name matching the given pattern\n"); log("\n"); From f9f509bc25cb8d2937e88bb73b14e588ab179c2c Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Tue, 15 Oct 2024 21:06:06 +0200 Subject: [PATCH 090/496] select: add t:@ test --- tests/select/mod-attribute.ys | 52 +++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 tests/select/mod-attribute.ys diff --git a/tests/select/mod-attribute.ys b/tests/select/mod-attribute.ys new file mode 100644 index 000000000..4d3704378 --- /dev/null +++ b/tests/select/mod-attribute.ys @@ -0,0 +1,52 @@ +read_rtlil < Date: Thu, 17 Oct 2024 04:40:21 +1300 Subject: [PATCH 091/496] Docs: Make code_examples/extensions parallel safe --- docs/source/code_examples/extensions/Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/code_examples/extensions/Makefile b/docs/source/code_examples/extensions/Makefile index 2e621d70b..74b547a20 100644 --- a/docs/source/code_examples/extensions/Makefile +++ b/docs/source/code_examples/extensions/Makefile @@ -4,8 +4,8 @@ YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys .PHONY: all dots examples all: dots examples -dots: test1.dot -examples: test0.log test1.log test2.log +dots: test1.dot my_cmd.so +examples: test0.log test1.log test2.log my_cmd.so CXXFLAGS=$(shell $(YOSYS)-config --cxxflags) DATDIR=$(shell $(YOSYS)-config --datdir) From 4ea6119734fbf83493d1c4e48f86a342fe80c775 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 19 Jul 2024 14:23:31 +1200 Subject: [PATCH 092/496] cmdref: Move html only section inside cmd:def Fixes missing links in body and `??` in tag/command index. Update synth.rst to match. --- docs/source/index.rst | 2 +- docs/source/using_yosys/synthesis/synth.rst | 2 +- kernel/register.cc | 23 ++++++++++----------- 3 files changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 8b9cff869..ab1742424 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,7 +23,7 @@ available, go to :ref:`commandindex`. - Search bar with live drop down suggestions for matching on title / autocompleting commands - Scroll the left sidebar to the current location on page load - - Also the formatting/linking in pdf is broken + - Also the formatting in pdf uses link formatting instead of code formatting .. todolist:: diff --git a/docs/source/using_yosys/synthesis/synth.rst b/docs/source/using_yosys/synthesis/synth.rst index 9014a9247..e3d82931b 100644 --- a/docs/source/using_yosys/synthesis/synth.rst +++ b/docs/source/using_yosys/synthesis/synth.rst @@ -42,7 +42,7 @@ The following commands are executed by the `prep` command: .. literalinclude:: /cmd/prep.rst :start-at: begin: - :end-before: .. raw:: latex + :end-before: .. only:: latex :dedent: :doc:`/getting_started/example_synth` covers most of these commands and what diff --git a/kernel/register.cc b/kernel/register.cc index 311c92961..d6e765ce4 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -812,11 +812,11 @@ struct HelpPass : public Pass { fprintf(f, "%s", title_line.c_str()); fprintf(f, "%s - %s\n", cmd.c_str(), title.c_str()); fprintf(f, "%s\n", title_line.c_str()); - fprintf(f, ".. raw:: latex\n\n \\begin{comment}\n\n"); // render html fprintf(f, ".. cmd:def:: %s\n", cmd.c_str()); - fprintf(f, " :title: %s\n\n", title.c_str()); + fprintf(f, " :title: %s\n\n", title.c_str()); + fprintf(f, " .. only:: html\n\n"); std::stringstream ss; std::string textcp = text; ss << text; @@ -852,32 +852,32 @@ struct HelpPass : public Pass { if (IsUsage) { if (stripped_line.compare(0, 4, "See ") == 0) { // description refers to another function - fprintf(f, "\n %s\n", stripped_line.c_str()); + fprintf(f, "\n %s\n", stripped_line.c_str()); } else { // usage should be the first line of help output - fprintf(f, "\n .. code:: yoscrypt\n\n %s\n\n ", stripped_line.c_str()); + fprintf(f, "\n .. code:: yoscrypt\n\n %s\n\n ", stripped_line.c_str()); WasDefinition = true; } IsUsage = false; } else if (IsIndent && NewUsage && (blank_count >= 2 || WasDefinition)) { // another usage block - fprintf(f, "\n .. code:: yoscrypt\n\n %s\n\n ", stripped_line.c_str()); + fprintf(f, "\n .. code:: yoscrypt\n\n %s\n\n ", stripped_line.c_str()); WasDefinition = true; def_strip_count = 0; } else if (IsIndent && IsDefinition && (blank_count || WasDefinition)) { // format definition term - fprintf(f, "\n\n .. code:: yoscrypt\n\n %s\n\n ", stripped_line.c_str()); + fprintf(f, "\n\n .. code:: yoscrypt\n\n %s\n\n ", stripped_line.c_str()); WasDefinition = true; def_strip_count = first_pos; } else { if (IsDedent) { - fprintf(f, "\n\n ::\n"); + fprintf(f, "\n\n ::\n"); def_strip_count = first_pos; } else if (WasDefinition) { - fprintf(f, " ::\n"); + fprintf(f, "::\n"); WasDefinition = false; } - fprintf(f, "\n %s", line.substr(def_strip_count, std::string::npos).c_str()); + fprintf(f, "\n %s", line.substr(def_strip_count, std::string::npos).c_str()); } blank_count = 0; @@ -885,13 +885,12 @@ struct HelpPass : public Pass { fputc('\n', f); // render latex - fprintf(f, ".. raw:: latex\n\n \\end{comment}\n\n"); fprintf(f, ".. only:: latex\n\n"); - fprintf(f, " ::\n\n"); + fprintf(f, " ::\n\n"); std::stringstream ss2; ss2 << textcp; for (std::string line; std::getline(ss2, line, '\n');) { - fprintf(f, " %s\n", line.c_str()); + fprintf(f, " %s\n", line.c_str()); } fclose(f); } From 5d14c3017e724f3693fb5e331952f76817924a41 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 19 Jul 2024 14:23:31 +1200 Subject: [PATCH 093/496] test-build.yml: Add test-docs-build Try use self hosted linux runner to build html and latexpdf to check for errors. Trying to use the build artifact didn't seem to work, so just run it on its own. Upload docs/build folder as artifact to enable review without having to build locally. Note: doesn't include verific, so will differ slightly from final published docs. --- .github/workflows/test-build.yml | 37 ++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/.github/workflows/test-build.yml b/.github/workflows/test-build.yml index e5aed6af3..4ac77a765 100644 --- a/.github/workflows/test-build.yml +++ b/.github/workflows/test-build.yml @@ -189,3 +189,40 @@ jobs: shell: bash run: | make -C docs test -j${{ env.procs }} + + test-docs-build: + name: Try build docs + runs-on: [self-hosted, linux, x64] + needs: [pre_docs_job] + if: needs.pre_docs_job.outputs.should_skip != 'true' + strategy: + matrix: + docs-target: [html, latexpdf] + fail-fast: false + steps: + - name: Checkout Yosys + uses: actions/checkout@v4 + with: + submodules: true + + - name: Runtime environment + run: | + echo "procs=$(nproc)" >> $GITHUB_ENV + + - name: Build Yosys + run: | + make config-clang + echo "ENABLE_CCACHE := 1" >> Makefile.conf + make -j${{ env.procs }} + + - name: Build docs + shell: bash + run: | + make docs DOC_TARGET=${{ matrix.docs-target }} -j${{ env.procs }} + + - name: Store docs build artifact + uses: actions/upload-artifact@v4 + with: + name: docs-build-${{ matrix.docs-target }} + path: docs/build/ + retention-days: 7 From 2edb9397c317cb3ef3e4d29741069e0cd900eadb Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 17 Oct 2024 07:05:23 +1300 Subject: [PATCH 094/496] libs/fst: Update from upstream Add shell script (based on minisat lib) to clone and copy relevant files. Unclear if there are any changes lost that we need to patch back in. --- libs/fst/00_UPDATE.sh | 13 + libs/fst/fastlz.cc | 721 +-- libs/fst/fst_win_unistd.h | 52 + libs/fst/fstapi.cc | 9532 ++++++++++++++++++++----------------- libs/fst/fstapi.h | 678 ++- libs/fst/lz4.cc | 3488 +++++++++----- libs/fst/lz4.h | 1095 +++-- 7 files changed, 8983 insertions(+), 6596 deletions(-) create mode 100755 libs/fst/00_UPDATE.sh create mode 100644 libs/fst/fst_win_unistd.h diff --git a/libs/fst/00_UPDATE.sh b/libs/fst/00_UPDATE.sh new file mode 100755 index 000000000..684e16a1d --- /dev/null +++ b/libs/fst/00_UPDATE.sh @@ -0,0 +1,13 @@ +#!/bin/bash + +mv config.h config.h.bak +rm -f *.txt *.cc *.h +git clone --depth 1 https://github.com/gtkwave/gtkwave fst_upstream +rm fst_upstream/lib/libfst/CMakeLists.txt +mv fst_upstream/lib/libfst/*.{h,c,txt} . +rm -rf fst_upstream + +for src in *.c; do + mv -- "$src" "${src%.c}.cc" +done +mv config.h.bak config.h diff --git a/libs/fst/fastlz.cc b/libs/fst/fastlz.cc index 68bda3346..b52a799b9 100644 --- a/libs/fst/fastlz.cc +++ b/libs/fst/fastlz.cc @@ -36,15 +36,16 @@ */ #define FASTLZ_SAFE + /* * Give hints to the compiler for branch prediction optimization. */ #if defined(__GNUC__) && (__GNUC__ > 2) -#define FASTLZ_EXPECT_CONDITIONAL(c) (__builtin_expect((c), 1)) -#define FASTLZ_UNEXPECT_CONDITIONAL(c) (__builtin_expect((c), 0)) +#define FASTLZ_EXPECT_CONDITIONAL(c) (__builtin_expect((c), 1)) +#define FASTLZ_UNEXPECT_CONDITIONAL(c) (__builtin_expect((c), 0)) #else -#define FASTLZ_EXPECT_CONDITIONAL(c) (c) -#define FASTLZ_UNEXPECT_CONDITIONAL(c) (c) +#define FASTLZ_EXPECT_CONDITIONAL(c) (c) +#define FASTLZ_UNEXPECT_CONDITIONAL(c) (c) #endif /* @@ -63,7 +64,7 @@ */ #if !defined(FASTLZ_STRICT_ALIGN) #define FASTLZ_STRICT_ALIGN -#if defined(__i386__) || defined(__386) /* GNU C, Sun Studio */ +#if defined(__i386__) || defined(__386) /* GNU C, Sun Studio */ #undef FASTLZ_STRICT_ALIGN #elif defined(__i486__) || defined(__i586__) || defined(__i686__) || defined(__amd64) /* GNU C */ #undef FASTLZ_STRICT_ALIGN @@ -79,29 +80,24 @@ #endif /* prototypes */ -int fastlz_compress(const void *input, int length, void *output); -int fastlz_compress_level(int level, const void *input, int length, void *output); -int fastlz_decompress(const void *input, int length, void *output, int maxout); +int fastlz_compress(const void* input, int length, void* output); +int fastlz_compress_level(int level, const void* input, int length, void* output); +int fastlz_decompress(const void* input, int length, void* output, int maxout); -#define MAX_COPY 32 -#define MAX_LEN 264 /* 256 + 8 */ +#define MAX_COPY 32 +#define MAX_LEN 264 /* 256 + 8 */ #define MAX_DISTANCE 8192 #if !defined(FASTLZ_STRICT_ALIGN) -#define FASTLZ_READU16(p) *((const flzuint16 *)(p)) +#define FASTLZ_READU16(p) *((const flzuint16*)(p)) #else -#define FASTLZ_READU16(p) ((p)[0] | (p)[1] << 8) +#define FASTLZ_READU16(p) ((p)[0] | (p)[1]<<8) #endif -#define HASH_LOG 13 -#define HASH_SIZE (1 << HASH_LOG) -#define HASH_MASK (HASH_SIZE - 1) -#define HASH_FUNCTION(v, p) \ - { \ - v = FASTLZ_READU16(p); \ - v ^= FASTLZ_READU16(p + 1) ^ (v >> (16 - HASH_LOG)); \ - v &= HASH_MASK; \ - } +#define HASH_LOG 13 +#define HASH_SIZE (1<< HASH_LOG) +#define HASH_MASK (HASH_SIZE-1) +#define HASH_FUNCTION(v,p) { v = FASTLZ_READU16(p); v ^= FASTLZ_READU16(p+1)^(v>>(16-HASH_LOG));v &= HASH_MASK; } #undef FASTLZ_LEVEL #define FASTLZ_LEVEL 1 @@ -110,419 +106,444 @@ int fastlz_decompress(const void *input, int length, void *output, int maxout); #undef FASTLZ_DECOMPRESSOR #define FASTLZ_COMPRESSOR fastlz1_compress #define FASTLZ_DECOMPRESSOR fastlz1_decompress -static FASTLZ_INLINE int FASTLZ_COMPRESSOR(const void *input, int length, void *output); -static FASTLZ_INLINE int FASTLZ_DECOMPRESSOR(const void *input, int length, void *output, int maxout); -#include "fastlz.cc" +static FASTLZ_INLINE int FASTLZ_COMPRESSOR(const void* input, int length, void* output); +static FASTLZ_INLINE int FASTLZ_DECOMPRESSOR(const void* input, int length, void* output, int maxout); +#include "fastlz.c" #undef FASTLZ_LEVEL #define FASTLZ_LEVEL 2 #undef MAX_DISTANCE #define MAX_DISTANCE 8191 -#define MAX_FARDISTANCE (65535 + MAX_DISTANCE - 1) +#define MAX_FARDISTANCE (65535+MAX_DISTANCE-1) #undef FASTLZ_COMPRESSOR #undef FASTLZ_DECOMPRESSOR #define FASTLZ_COMPRESSOR fastlz2_compress #define FASTLZ_DECOMPRESSOR fastlz2_decompress -static FASTLZ_INLINE int FASTLZ_COMPRESSOR(const void *input, int length, void *output); -static FASTLZ_INLINE int FASTLZ_DECOMPRESSOR(const void *input, int length, void *output, int maxout); -#include "fastlz.cc" +static FASTLZ_INLINE int FASTLZ_COMPRESSOR(const void* input, int length, void* output); +static FASTLZ_INLINE int FASTLZ_DECOMPRESSOR(const void* input, int length, void* output, int maxout); +#include "fastlz.c" -int fastlz_compress(const void *input, int length, void *output) +int fastlz_compress(const void* input, int length, void* output) { - /* for short block, choose fastlz1 */ - if (length < 65536) - return fastlz1_compress(input, length, output); + /* for short block, choose fastlz1 */ + if(length < 65536) + return fastlz1_compress(input, length, output); - /* else... */ + /* else... */ + return fastlz2_compress(input, length, output); +} + +int fastlz_decompress(const void* input, int length, void* output, int maxout) +{ + /* magic identifier for compression level */ + int level = ((*(const flzuint8*)input) >> 5) + 1; + + if(level == 1) + return fastlz1_decompress(input, length, output, maxout); + if(level == 2) + return fastlz2_decompress(input, length, output, maxout); + + /* unknown level, trigger error */ + return 0; +} + +int fastlz_compress_level(int level, const void* input, int length, void* output) +{ + if(level == 1) + return fastlz1_compress(input, length, output); + if(level == 2) return fastlz2_compress(input, length, output); -} -int fastlz_decompress(const void *input, int length, void *output, int maxout) -{ - /* magic identifier for compression level */ - int level = ((*(const flzuint8 *)input) >> 5) + 1; - - if (level == 1) - return fastlz1_decompress(input, length, output, maxout); - if (level == 2) - return fastlz2_decompress(input, length, output, maxout); - - /* unknown level, trigger error */ - return 0; -} - -int fastlz_compress_level(int level, const void *input, int length, void *output) -{ - if (level == 1) - return fastlz1_compress(input, length, output); - if (level == 2) - return fastlz2_compress(input, length, output); - - return 0; + return 0; } #else /* !defined(FASTLZ_COMPRESSOR) && !defined(FASTLZ_DECOMPRESSOR) */ -static FASTLZ_INLINE int FASTLZ_COMPRESSOR(const void *input, int length, void *output) +static FASTLZ_INLINE int FASTLZ_COMPRESSOR(const void* input, int length, void* output) { - const flzuint8 *ip = (const flzuint8 *)input; - const flzuint8 *ip_bound = ip + length - 2; - const flzuint8 *ip_limit = ip + length - 12; - flzuint8 *op = (flzuint8 *)output; + const flzuint8* ip = (const flzuint8*) input; + const flzuint8* ip_bound = ip + length - 2; + const flzuint8* ip_limit = ip + length - 12; + flzuint8* op = (flzuint8*) output; - const flzuint8 *htab[HASH_SIZE]; - const flzuint8 **hslot; - flzuint32 hval; + const flzuint8* htab[HASH_SIZE]; + const flzuint8** hslot; + flzuint32 hval; - flzuint32 copy; + flzuint32 copy; - /* sanity check */ - if (FASTLZ_UNEXPECT_CONDITIONAL(length < 4)) { - if (length) { - /* create literal copy only */ - *op++ = length - 1; - ip_bound++; - while (ip <= ip_bound) - *op++ = *ip++; - return length + 1; - } else - return 0; + /* sanity check */ + if(FASTLZ_UNEXPECT_CONDITIONAL(length < 4)) + { + if(length) + { + /* create literal copy only */ + *op++ = length-1; + ip_bound++; + while(ip <= ip_bound) + *op++ = *ip++; + return length+1; } + else + return 0; + } - /* initializes hash table */ - for (hslot = htab; hslot < htab + HASH_SIZE; hslot++) - *hslot = ip; + /* initializes hash table */ + for (hslot = htab; hslot < htab + HASH_SIZE; hslot++) + *hslot = ip; - /* we start with literal copy */ - copy = 2; - *op++ = MAX_COPY - 1; - *op++ = *ip++; - *op++ = *ip++; + /* we start with literal copy */ + copy = 2; + *op++ = MAX_COPY-1; + *op++ = *ip++; + *op++ = *ip++; - /* main loop */ - while (FASTLZ_EXPECT_CONDITIONAL(ip < ip_limit)) { - const flzuint8 *ref; - flzuint32 distance; + /* main loop */ + while(FASTLZ_EXPECT_CONDITIONAL(ip < ip_limit)) + { + const flzuint8* ref; + flzuint32 distance; - /* minimum match length */ - flzuint32 len = 3; + /* minimum match length */ + flzuint32 len = 3; - /* comparison starting-point */ - const flzuint8 *anchor = ip; + /* comparison starting-point */ + const flzuint8* anchor = ip; - /* check for a run */ -#if FASTLZ_LEVEL == 2 - if (ip[0] == ip[-1] && FASTLZ_READU16(ip - 1) == FASTLZ_READU16(ip + 1)) { - distance = 1; - /* ip += 3; */ /* scan-build, never used */ - ref = anchor - 1 + 3; - goto match; - } + /* check for a run */ +#if FASTLZ_LEVEL==2 + if(ip[0] == ip[-1] && FASTLZ_READU16(ip-1)==FASTLZ_READU16(ip+1)) + { + distance = 1; + /* ip += 3; */ /* scan-build, never used */ + ref = anchor - 1 + 3; + goto match; + } #endif - /* find potential match */ - HASH_FUNCTION(hval, ip); - hslot = htab + hval; - ref = htab[hval]; + /* find potential match */ + HASH_FUNCTION(hval,ip); + hslot = htab + hval; + ref = htab[hval]; - /* calculate distance to the match */ - distance = anchor - ref; + /* calculate distance to the match */ + distance = anchor - ref; - /* update hash table */ - *hslot = anchor; + /* update hash table */ + *hslot = anchor; - /* is this a match? check the first 3 bytes */ - if (distance == 0 || -#if FASTLZ_LEVEL == 1 - (distance >= MAX_DISTANCE) || + /* is this a match? check the first 3 bytes */ + if(distance==0 || +#if FASTLZ_LEVEL==1 + (distance >= MAX_DISTANCE) || #else - (distance >= MAX_FARDISTANCE) || + (distance >= MAX_FARDISTANCE) || #endif - *ref++ != *ip++ || *ref++ != *ip++ || *ref++ != *ip++) - goto literal; + *ref++ != *ip++ || *ref++!=*ip++ || *ref++!=*ip++) + goto literal; -#if FASTLZ_LEVEL == 2 - /* far, needs at least 5-byte match */ - if (distance >= MAX_DISTANCE) { - if (*ip++ != *ref++ || *ip++ != *ref++) - goto literal; - len += 2; - } +#if FASTLZ_LEVEL==2 + /* far, needs at least 5-byte match */ + if(distance >= MAX_DISTANCE) + { + if(*ip++ != *ref++ || *ip++!= *ref++) + goto literal; + len += 2; + } match: #endif - /* last matched byte */ - ip = anchor + len; + /* last matched byte */ + ip = anchor + len; - /* distance is biased */ - distance--; + /* distance is biased */ + distance--; - if (!distance) { - /* zero distance means a run */ - flzuint8 x = ip[-1]; - while (ip < ip_bound) - if (*ref++ != x) - break; - else - ip++; - } else - for (;;) { - /* safe because the outer check against ip limit */ - if (*ref++ != *ip++) - break; - if (*ref++ != *ip++) - break; - if (*ref++ != *ip++) - break; - if (*ref++ != *ip++) - break; - if (*ref++ != *ip++) - break; - if (*ref++ != *ip++) - break; - if (*ref++ != *ip++) - break; - if (*ref++ != *ip++) - break; - while (ip < ip_bound) - if (*ref++ != *ip++) - break; - break; - } + if(!distance) + { + /* zero distance means a run */ + flzuint8 x = ip[-1]; + while(ip < ip_bound) + if(*ref++ != x) break; else ip++; + } + else + for(;;) + { + /* safe because the outer check against ip limit */ + if(*ref++ != *ip++) break; + if(*ref++ != *ip++) break; + if(*ref++ != *ip++) break; + if(*ref++ != *ip++) break; + if(*ref++ != *ip++) break; + if(*ref++ != *ip++) break; + if(*ref++ != *ip++) break; + if(*ref++ != *ip++) break; + while(ip < ip_bound) + if(*ref++ != *ip++) break; + break; + } - /* if we have copied something, adjust the copy count */ - if (copy) - /* copy is biased, '0' means 1 byte copy */ - *(op - copy - 1) = copy - 1; - else - /* back, to overwrite the copy count */ - op--; + /* if we have copied something, adjust the copy count */ + if(copy) + /* copy is biased, '0' means 1 byte copy */ + *(op-copy-1) = copy-1; + else + /* back, to overwrite the copy count */ + op--; - /* reset literal counter */ - copy = 0; + /* reset literal counter */ + copy = 0; - /* length is biased, '1' means a match of 3 bytes */ - ip -= 3; - len = ip - anchor; + /* length is biased, '1' means a match of 3 bytes */ + ip -= 3; + len = ip - anchor; - /* encode the match */ -#if FASTLZ_LEVEL == 2 - if (distance < MAX_DISTANCE) { - if (len < 7) { - *op++ = (len << 5) + (distance >> 8); - *op++ = (distance & 255); - } else { - *op++ = (7 << 5) + (distance >> 8); - for (len -= 7; len >= 255; len -= 255) - *op++ = 255; - *op++ = len; - *op++ = (distance & 255); - } - } else { - /* far away, but not yet in the another galaxy... */ - if (len < 7) { - distance -= MAX_DISTANCE; - *op++ = (len << 5) + 31; - *op++ = 255; - *op++ = distance >> 8; - *op++ = distance & 255; - } else { - distance -= MAX_DISTANCE; - *op++ = (7 << 5) + 31; - for (len -= 7; len >= 255; len -= 255) - *op++ = 255; - *op++ = len; - *op++ = 255; - *op++ = distance >> 8; - *op++ = distance & 255; - } - } + /* encode the match */ +#if FASTLZ_LEVEL==2 + if(distance < MAX_DISTANCE) + { + if(len < 7) + { + *op++ = (len << 5) + (distance >> 8); + *op++ = (distance & 255); + } + else + { + *op++ = (7 << 5) + (distance >> 8); + for(len-=7; len >= 255; len-= 255) + *op++ = 255; + *op++ = len; + *op++ = (distance & 255); + } + } + else + { + /* far away, but not yet in the another galaxy... */ + if(len < 7) + { + distance -= MAX_DISTANCE; + *op++ = (len << 5) + 31; + *op++ = 255; + *op++ = distance >> 8; + *op++ = distance & 255; + } + else + { + distance -= MAX_DISTANCE; + *op++ = (7 << 5) + 31; + for(len-=7; len >= 255; len-= 255) + *op++ = 255; + *op++ = len; + *op++ = 255; + *op++ = distance >> 8; + *op++ = distance & 255; + } + } #else - if (FASTLZ_UNEXPECT_CONDITIONAL(len > MAX_LEN - 2)) - while (len > MAX_LEN - 2) { - *op++ = (7 << 5) + (distance >> 8); - *op++ = MAX_LEN - 2 - 7 - 2; - *op++ = (distance & 255); - len -= MAX_LEN - 2; - } + if(FASTLZ_UNEXPECT_CONDITIONAL(len > MAX_LEN-2)) + while(len > MAX_LEN-2) + { + *op++ = (7 << 5) + (distance >> 8); + *op++ = MAX_LEN - 2 - 7 -2; + *op++ = (distance & 255); + len -= MAX_LEN-2; + } - if (len < 7) { - *op++ = (len << 5) + (distance >> 8); - *op++ = (distance & 255); - } else { - *op++ = (7 << 5) + (distance >> 8); - *op++ = len - 7; - *op++ = (distance & 255); - } + if(len < 7) + { + *op++ = (len << 5) + (distance >> 8); + *op++ = (distance & 255); + } + else + { + *op++ = (7 << 5) + (distance >> 8); + *op++ = len - 7; + *op++ = (distance & 255); + } #endif - /* update the hash at match boundary */ - HASH_FUNCTION(hval, ip); - htab[hval] = ip++; - HASH_FUNCTION(hval, ip); - htab[hval] = ip++; + /* update the hash at match boundary */ + HASH_FUNCTION(hval,ip); + htab[hval] = ip++; + HASH_FUNCTION(hval,ip); + htab[hval] = ip++; - /* assuming literal copy */ - *op++ = MAX_COPY - 1; + /* assuming literal copy */ + *op++ = MAX_COPY-1; - continue; + continue; literal: - *op++ = *anchor++; - ip = anchor; - copy++; - if (FASTLZ_UNEXPECT_CONDITIONAL(copy == MAX_COPY)) { - copy = 0; - *op++ = MAX_COPY - 1; - } + *op++ = *anchor++; + ip = anchor; + copy++; + if(FASTLZ_UNEXPECT_CONDITIONAL(copy == MAX_COPY)) + { + copy = 0; + *op++ = MAX_COPY-1; + } + } + + /* left-over as literal copy */ + ip_bound++; + while(ip <= ip_bound) + { + *op++ = *ip++; + copy++; + if(copy == MAX_COPY) + { + copy = 0; + *op++ = MAX_COPY-1; } + } - /* left-over as literal copy */ - ip_bound++; - while (ip <= ip_bound) { - *op++ = *ip++; - copy++; - if (copy == MAX_COPY) { - copy = 0; - *op++ = MAX_COPY - 1; - } - } + /* if we have copied something, adjust the copy length */ + if(copy) + *(op-copy-1) = copy-1; + else + op--; - /* if we have copied something, adjust the copy length */ - if (copy) - *(op - copy - 1) = copy - 1; - else - op--; - -#if FASTLZ_LEVEL == 2 - /* marker for fastlz2 */ - *(flzuint8 *)output |= (1 << 5); +#if FASTLZ_LEVEL==2 + /* marker for fastlz2 */ + *(flzuint8*)output |= (1 << 5); #endif - return op - (flzuint8 *)output; + return op - (flzuint8*)output; } -static FASTLZ_INLINE int FASTLZ_DECOMPRESSOR(const void *input, int length, void *output, int maxout) +static FASTLZ_INLINE int FASTLZ_DECOMPRESSOR(const void* input, int length, void* output, int maxout) { - const flzuint8 *ip = (const flzuint8 *)input; - const flzuint8 *ip_limit = ip + length; - flzuint8 *op = (flzuint8 *)output; - flzuint8 *op_limit = op + maxout; - flzuint32 ctrl = (*ip++) & 31; - int loop = 1; + const flzuint8* ip = (const flzuint8*) input; + const flzuint8* ip_limit = ip + length; + flzuint8* op = (flzuint8*) output; + flzuint8* op_limit = op + maxout; + flzuint32 ctrl = (*ip++) & 31; + int loop = 1; - do { - const flzuint8 *ref = op; - flzuint32 len = ctrl >> 5; - flzuint32 ofs = (ctrl & 31) << 8; + do + { + const flzuint8* ref = op; + flzuint32 len = ctrl >> 5; + flzuint32 ofs = (ctrl & 31) << 8; - if (ctrl >= 32) { -#if FASTLZ_LEVEL == 2 - flzuint8 code; + if(ctrl >= 32) + { +#if FASTLZ_LEVEL==2 + flzuint8 code; #endif - len--; - ref -= ofs; - if (len == 7 - 1) -#if FASTLZ_LEVEL == 1 - len += *ip++; - ref -= *ip++; + len--; + ref -= ofs; + if (len == 7-1) +#if FASTLZ_LEVEL==1 + len += *ip++; + ref -= *ip++; #else - do { - code = *ip++; - len += code; - } while (code == 255); - code = *ip++; - ref -= code; + do + { + code = *ip++; + len += code; + } while (code==255); + code = *ip++; + ref -= code; - /* match from 16-bit distance */ - if (FASTLZ_UNEXPECT_CONDITIONAL(code == 255)) - if (FASTLZ_EXPECT_CONDITIONAL(ofs == (31 << 8))) { - ofs = (*ip++) << 8; - ofs += *ip++; - ref = op - ofs - MAX_DISTANCE; - } + /* match from 16-bit distance */ + if(FASTLZ_UNEXPECT_CONDITIONAL(code==255)) + if(FASTLZ_EXPECT_CONDITIONAL(ofs==(31 << 8))) + { + ofs = (*ip++) << 8; + ofs += *ip++; + ref = op - ofs - MAX_DISTANCE; + } #endif #ifdef FASTLZ_SAFE - if (FASTLZ_UNEXPECT_CONDITIONAL(op + len + 3 > op_limit)) - return 0; + if (FASTLZ_UNEXPECT_CONDITIONAL(op + len + 3 > op_limit)) + return 0; - if (FASTLZ_UNEXPECT_CONDITIONAL(ref - 1 < (flzuint8 *)output)) - return 0; + if (FASTLZ_UNEXPECT_CONDITIONAL(ref-1 < (flzuint8 *)output)) + return 0; #endif - if (FASTLZ_EXPECT_CONDITIONAL(ip < ip_limit)) - ctrl = *ip++; - else - loop = 0; + if(FASTLZ_EXPECT_CONDITIONAL(ip < ip_limit)) + ctrl = *ip++; + else + loop = 0; - if (ref == op) { - /* optimize copy for a run */ - flzuint8 b = ref[-1]; - *op++ = b; - *op++ = b; - *op++ = b; - for (; len; --len) - *op++ = b; - } else { + if(ref == op) + { + /* optimize copy for a run */ + flzuint8 b = ref[-1]; + *op++ = b; + *op++ = b; + *op++ = b; + for(; len; --len) + *op++ = b; + } + else + { #if !defined(FASTLZ_STRICT_ALIGN) - const flzuint16 *p; - flzuint16 *q; + const flzuint16* p; + flzuint16* q; #endif - /* copy from reference */ - ref--; - *op++ = *ref++; - *op++ = *ref++; - *op++ = *ref++; + /* copy from reference */ + ref--; + *op++ = *ref++; + *op++ = *ref++; + *op++ = *ref++; #if !defined(FASTLZ_STRICT_ALIGN) - /* copy a byte, so that now it's word aligned */ - if (len & 1) { - *op++ = *ref++; - len--; - } - - /* copy 16-bit at once */ - q = (flzuint16 *)op; - op += len; - p = (const flzuint16 *)ref; - for (len >>= 1; len > 4; len -= 4) { - *q++ = *p++; - *q++ = *p++; - *q++ = *p++; - *q++ = *p++; - } - for (; len; --len) - *q++ = *p++; -#else - for (; len; --len) - *op++ = *ref++; -#endif - } - } else { - ctrl++; -#ifdef FASTLZ_SAFE - if (FASTLZ_UNEXPECT_CONDITIONAL(op + ctrl > op_limit)) - return 0; - if (FASTLZ_UNEXPECT_CONDITIONAL(ip + ctrl > ip_limit)) - return 0; -#endif - - *op++ = *ip++; - for (--ctrl; ctrl; ctrl--) - *op++ = *ip++; - - loop = FASTLZ_EXPECT_CONDITIONAL(ip < ip_limit); - if (loop) - ctrl = *ip++; + /* copy a byte, so that now it's word aligned */ + if(len & 1) + { + *op++ = *ref++; + len--; } - } while (FASTLZ_EXPECT_CONDITIONAL(loop)); - return op - (flzuint8 *)output; + /* copy 16-bit at once */ + q = (flzuint16*) op; + op += len; + p = (const flzuint16*) ref; + for(len>>=1; len > 4; len-=4) + { + *q++ = *p++; + *q++ = *p++; + *q++ = *p++; + *q++ = *p++; + } + for(; len; --len) + *q++ = *p++; +#else + for(; len; --len) + *op++ = *ref++; +#endif + } + } + else + { + ctrl++; +#ifdef FASTLZ_SAFE + if (FASTLZ_UNEXPECT_CONDITIONAL(op + ctrl > op_limit)) + return 0; + if (FASTLZ_UNEXPECT_CONDITIONAL(ip + ctrl > ip_limit)) + return 0; +#endif + + *op++ = *ip++; + for(--ctrl; ctrl; ctrl--) + *op++ = *ip++; + + loop = FASTLZ_EXPECT_CONDITIONAL(ip < ip_limit); + if(loop) + ctrl = *ip++; + } + } + while(FASTLZ_EXPECT_CONDITIONAL(loop)); + + return op - (flzuint8*)output; } #endif /* !defined(FASTLZ_COMPRESSOR) && !defined(FASTLZ_DECOMPRESSOR) */ diff --git a/libs/fst/fst_win_unistd.h b/libs/fst/fst_win_unistd.h new file mode 100644 index 000000000..15ab2c1fc --- /dev/null +++ b/libs/fst/fst_win_unistd.h @@ -0,0 +1,52 @@ +/* + * Copyright (c) 2009-2018 Tony Bybell. + * + * Permission is hereby granted, free of charge, to any person obtaining a + * copy of this software and associated documentation files (the "Software"), + * to deal in the Software without restriction, including without limitation + * the rights to use, copy, modify, merge, publish, distribute, sublicense, + * and/or sell copies of the Software, and to permit persons to whom the + * Software is furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + * DEALINGS IN THE SOFTWARE. + * + * SPDX-License-Identifier: MIT + */ + +#ifndef WIN_UNISTD_H +#define WIN_UNISTD_H + +#include +#ifdef _WIN64 +#include +#else +#include +#endif + +#include + +#define ftruncate _chsize_s +#define unlink _unlink +#define fileno _fileno +#define lseek _lseeki64 + +#ifdef _WIN64 +#define ssize_t __int64 +#define SSIZE_MAX 9223372036854775807i64 +#else +#define ssize_t long +#define SSIZE_MAX 2147483647L +#endif + +#include "stdint.h" + +#endif //WIN_UNISTD_H diff --git a/libs/fst/fstapi.cc b/libs/fst/fstapi.cc index bd70d7250..7bc7fd821 100644 --- a/libs/fst/fstapi.cc +++ b/libs/fst/fstapi.cc @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009-2018 Tony Bybell. + * Copyright (c) 2009-2023 Tony Bybell. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), @@ -34,13 +34,12 @@ * FST_DEBUG : not for production use, only enable for development * FST_REMOVE_DUPLICATE_VC : glitch removal (has writer performance impact) * HAVE_LIBPTHREAD -> FST_WRITER_PARALLEL : enables inclusion of parallel writer code - * FST_DO_MISALIGNED_OPS (defined automatically for x86 and some others) : CPU architecture can handle misaligned - * loads/stores _WAVE_HAVE_JUDY : use Judy arrays instead of Jenkins (undefine if LGPL is not acceptable) + * _WAVE_HAVE_JUDY : use Judy arrays instead of Jenkins (undefine if LGPL is not acceptable) * */ #ifndef FST_CONFIG_INCLUDE -#define FST_CONFIG_INCLUDE "config.h" +# define FST_CONFIG_INCLUDE #endif #include FST_CONFIG_INCLUDE @@ -58,6 +57,7 @@ #endif #ifdef __MINGW32__ +#define WIN32_LEAN_AND_MEAN #include #endif @@ -93,51 +93,54 @@ typedef off_t fst_off_t; #include #else /* should be more than enough for fstWriterSetSourceStem() */ -#define FST_PATH_HASHMASK ((1UL << 16) - 1) +#define FST_PATH_HASHMASK ((1UL << 16) - 1) typedef const void *Pcvoid_t; typedef void *Pvoid_t; typedef void **PPvoid_t; -#define JudyHSIns(a, b, c, d) JenkinsIns((a), (b), (c), (hashmask)) -#define JudyHSFreeArray(a, b) JenkinsFree((a), (hashmask)) +#define JudyHSIns(a,b,c,d) JenkinsIns((a),(b),(c),(hashmask)) +#define JudyHSFreeArray(a,b) JenkinsFree((a),(hashmask)) void JenkinsFree(void *base_i, uint32_t hashmask); void **JenkinsIns(void *base_i, const unsigned char *mem, uint32_t length, uint32_t hashmask); #endif + #ifndef FST_WRITEX_DISABLE -#define FST_WRITEX_MAX (64 * 1024) +#define FST_WRITEX_MAX (64 * 1024) #else -#define fstWritex(a, b, c) fstFwrite((b), (c), 1, fv) +#define fstWritex(a,b,c) fstFwrite((b), (c), 1, fv) #endif + /* these defines have a large impact on writer speed when a model has a */ /* huge number of symbols. as a default, use 128MB and increment when */ /* every 1M signals are defined. */ -#define FST_BREAK_SIZE (1UL << 27) -#define FST_BREAK_ADD_SIZE (1UL << 22) -#define FST_BREAK_SIZE_MAX (1UL << 31) -#define FST_ACTIVATE_HUGE_BREAK (1000000) -#define FST_ACTIVATE_HUGE_INC (1000000) +#define FST_BREAK_SIZE (1UL << 27) +#define FST_BREAK_ADD_SIZE (1UL << 22) +#define FST_BREAK_SIZE_MAX (1UL << 31) +#define FST_ACTIVATE_HUGE_BREAK (1000000) +#define FST_ACTIVATE_HUGE_INC (1000000) -#define FST_WRITER_STR "fstWriter" -#define FST_ID_NAM_SIZ (512) -#define FST_ID_NAM_ATTR_SIZ (65536 + 4096) -#define FST_DOUBLE_ENDTEST (2.7182818284590452354) -#define FST_HDR_SIM_VERSION_SIZE (128) -#define FST_HDR_DATE_SIZE (119) -#define FST_HDR_FILETYPE_SIZE (1) -#define FST_HDR_TIMEZERO_SIZE (8) -#define FST_GZIO_LEN (32768) -#define FST_HDR_FOURPACK_DUO_SIZE (4 * 1024 * 1024) - -#if defined(__i386__) || defined(__x86_64__) || defined(_AIX) -#define FST_DO_MISALIGNED_OPS -#endif +#define FST_WRITER_STR "fstWriter" +#define FST_ID_NAM_SIZ (512) +#define FST_ID_NAM_ATTR_SIZ (65536+4096) +#define FST_DOUBLE_ENDTEST (2.7182818284590452354) +#define FST_HDR_SIM_VERSION_SIZE (128) +#define FST_HDR_DATE_SIZE (119) +#define FST_HDR_FILETYPE_SIZE (1) +#define FST_HDR_TIMEZERO_SIZE (8) +#define FST_GZIO_LEN (32768) +#define FST_HDR_FOURPACK_DUO_SIZE (4*1024*1024) +#define FST_ZWRAPPER_HDR_SIZE (1+8+8) #if defined(__APPLE__) && defined(__MACH__) #define FST_MACOSX #include #endif +#if defined(FST_MACOSX) || defined(__MINGW32__) || defined(__OpenBSD__) || defined(__FreeBSD__) || defined(__NetBSD__) +#define FST_UNBUFFERED_IO +#endif + #ifdef __GNUC__ /* Boolean expression more often true than false */ #define FST_LIKELY(x) __builtin_expect(!!(x), 1) @@ -156,7 +159,7 @@ void **JenkinsIns(void *base_i, const unsigned char *mem, uint32_t length, uint3 /*** ***/ /***********************/ -#if defined(__MINGW32__) || defined(_MSC_VER) +#ifdef __MINGW32__ #include #ifndef HAVE_FSEEKO #define ftello _ftelli64 @@ -172,108 +175,137 @@ void **JenkinsIns(void *base_i, const unsigned char *mem, uint32_t length, uint3 * this is currently not implemented so that the branchless decode is: * uint32_t shcnt = 2 << (vli & 1); tdelta = vli >> shcnt; */ -#define FST_RCV_X (1 | (0 << 1)) -#define FST_RCV_Z (1 | (1 << 1)) -#define FST_RCV_H (1 | (2 << 1)) -#define FST_RCV_U (1 | (3 << 1)) -#define FST_RCV_W (1 | (4 << 1)) -#define FST_RCV_L (1 | (5 << 1)) -#define FST_RCV_D (1 | (6 << 1)) -#define FST_RCV_Q (1 | (7 << 1)) +#define FST_RCV_X (1 | (0<<1)) +#define FST_RCV_Z (1 | (1<<1)) +#define FST_RCV_H (1 | (2<<1)) +#define FST_RCV_U (1 | (3<<1)) +#define FST_RCV_W (1 | (4<<1)) +#define FST_RCV_L (1 | (5<<1)) +#define FST_RCV_D (1 | (6<<1)) +#define FST_RCV_Q (1 | (7<<1)) #define FST_RCV_STR "xzhuwl-?" /* 01234567 */ + +/* + * report abort messages + */ +static void chk_report_abort(const char *s) +{ +fprintf(stderr,"Triggered %s security check, exiting.\n", s); +abort(); +} + + /* * prevent old file overwrite when currently being read */ static FILE *unlink_fopen(const char *nam, const char *mode) { - unlink(nam); - return (fopen(nam, mode)); +unlink(nam); +return(fopen(nam, mode)); } + /* * system-specific temp file handling */ #ifdef __MINGW32__ -static FILE *tmpfile_open(char **nam) +static FILE* tmpfile_open(char **nam) { - char *fname = NULL; - TCHAR szTempFileName[MAX_PATH]; - TCHAR lpTempPathBuffer[MAX_PATH]; - DWORD dwRetVal = 0; - UINT uRetVal = 0; - FILE *fh = NULL; +char *fname = NULL; +TCHAR szTempFileName[MAX_PATH]; +TCHAR lpTempPathBuffer[MAX_PATH]; +DWORD dwRetVal = 0; +UINT uRetVal = 0; +FILE *fh = NULL; - if (nam) /* cppcheck warning fix: nam is always defined, so this is not needed */ - { +if(nam) /* cppcheck warning fix: nam is always defined, so this is not needed */ + { dwRetVal = GetTempPath(MAX_PATH, lpTempPathBuffer); - if ((dwRetVal > MAX_PATH) || (dwRetVal == 0)) { - fprintf(stderr, FST_APIMESS "GetTempPath() failed in " __FILE__ " line %d, exiting.\n", __LINE__); - exit(255); - } else { - uRetVal = GetTempFileName(lpTempPathBuffer, TEXT("FSTW"), 0, szTempFileName); - if (uRetVal == 0) { - fprintf(stderr, FST_APIMESS "GetTempFileName() failed in " __FILE__ " line %d, exiting.\n", __LINE__); + if((dwRetVal > MAX_PATH) || (dwRetVal == 0)) + { + fprintf(stderr, FST_APIMESS "GetTempPath() failed in " __FILE__ " line %d, exiting.\n", __LINE__); exit(255); - } else { - fname = strdup(szTempFileName); - } + } + else + { + uRetVal = GetTempFileName(lpTempPathBuffer, TEXT("FSTW"), 0, szTempFileName); + if (uRetVal == 0) + { + fprintf(stderr, FST_APIMESS "GetTempFileName() failed in " __FILE__ " line %d, exiting.\n", __LINE__); + exit(255); + } + else + { + fname = strdup(szTempFileName); + } + } + + if(fname) + { + *nam = fname; + fh = unlink_fopen(fname, "w+b"); + } } - if (fname) { - *nam = fname; - fh = unlink_fopen(fname, "w+b"); - } - } - - return (fh); +return(fh); } #else -static FILE *tmpfile_open(char **nam) +static FILE* tmpfile_open(char **nam) { - FILE *f = tmpfile(); /* replace with mkstemp() + fopen(), etc if this is not good enough */ - if (nam) { - *nam = NULL; - } - return (f); +FILE *f = tmpfile(); /* replace with mkstemp() + fopen(), etc if this is not good enough */ +if(nam) { *nam = NULL; } +return(f); } #endif + static void tmpfile_close(FILE **f, char **nam) { - if (f) { - if (*f) { - fclose(*f); - *f = NULL; +if(f) + { + if(*f) { fclose(*f); *f = NULL; } } - } - if (nam) { - if (*nam) { - unlink(*nam); - free(*nam); - *nam = NULL; +if(nam) + { + if(*nam) + { + unlink(*nam); + free(*nam); + *nam = NULL; + } } - } } /*****************************************/ + /* * to remove warn_unused_result compile time messages * (in the future there needs to be results checking) */ -static size_t fstFread(void *buf, size_t siz, size_t cnt, FILE *fp) { return (fread(buf, siz, cnt, fp)); } +static size_t fstFread(void *buf, size_t siz, size_t cnt, FILE *fp) +{ +return(fread(buf, siz, cnt, fp)); +} -static size_t fstFwrite(const void *buf, size_t siz, size_t cnt, FILE *fp) { return (fwrite(buf, siz, cnt, fp)); } +static size_t fstFwrite(const void *buf, size_t siz, size_t cnt, FILE *fp) +{ +return(fwrite(buf, siz, cnt, fp)); +} + +static int fstFtruncate(int fd, fst_off_t length) +{ +return(ftruncate(fd, length)); +} -static int fstFtruncate(int fd, fst_off_t length) { return (ftruncate(fd, length)); } /* * realpath compatibility @@ -282,49 +314,50 @@ static char *fstRealpath(const char *path, char *resolved_path) { #if defined __USE_BSD || defined __USE_XOPEN_EXTENDED || defined __CYGWIN__ || defined HAVE_REALPATH #if (defined(__MACH__) && defined(__APPLE__)) - if (!resolved_path) { - resolved_path = (char *)malloc(PATH_MAX + 1); /* fixes bug on Leopard when resolved_path == NULL */ - } +if(!resolved_path) + { + resolved_path = (char *)malloc(PATH_MAX+1); /* fixes bug on Leopard when resolved_path == NULL */ + } #endif - return (realpath(path, resolved_path)); +return(realpath(path, resolved_path)); #else #ifdef __MINGW32__ - if (!resolved_path) { - resolved_path = (char *)malloc(PATH_MAX + 1); - } - return (_fullpath(resolved_path, path, PATH_MAX)); +if(!resolved_path) + { + resolved_path = (char *)malloc(PATH_MAX+1); + } +return(_fullpath(resolved_path, path, PATH_MAX)); #else - (void)path; - (void)resolved_path; - return (NULL); +(void)path; +(void)resolved_path; +return(NULL); #endif #endif } + /* * mmap compatibility */ -#if defined __CYGWIN__ || defined __MINGW32__ || defined _MSC_VER +#if defined __MINGW32__ #include -#define fstMmap(__addr, __len, __prot, __flags, __fd, __off) fstMmap2((__len), (__fd), (__off)) -#define fstMunmap(__addr, __len) free(__addr) +#define fstMmap(__addr,__len,__prot,__flags,__fd,__off) fstMmap2((__len), (__fd), (__off)) +#define fstMunmap(__addr,__len) UnmapViewOfFile((LPCVOID)__addr) static void *fstMmap2(size_t __len, int __fd, fst_off_t __off) { - (void)__off; +DWORD64 len64 = __len; /* Must be 64-bit for shift below */ +HANDLE handle = CreateFileMapping((HANDLE)_get_osfhandle(__fd), NULL, + PAGE_READWRITE, (DWORD)(len64 >> 32), + (DWORD)__len, NULL); +if (!handle) { return NULL; } - unsigned char *pnt = (unsigned char *)malloc(__len); - fst_off_t cur_offs = lseek(__fd, 0, SEEK_CUR); - size_t i; - - lseek(__fd, 0, SEEK_SET); - for (i = 0; i < __len; i += SSIZE_MAX) { - read(__fd, pnt + i, ((__len - i) >= SSIZE_MAX) ? SSIZE_MAX : (__len - i)); - } - lseek(__fd, cur_offs, SEEK_SET); - return (pnt); +void *ptr = MapViewOfFileEx(handle, FILE_MAP_READ | FILE_MAP_WRITE, + 0, (DWORD)__off, (SIZE_T)__len, (LPVOID)NULL); +CloseHandle(handle); +return ptr; } #else #include @@ -333,324 +366,363 @@ static void *fstMmap2(size_t __len, int __fd, fst_off_t __off) #else #define FST_CADDR_T_CAST #endif -#define fstMmap(__addr, __len, __prot, __flags, __fd, __off) \ - (void *)mmap(FST_CADDR_T_CAST(__addr), (__len), (__prot), (__flags), (__fd), (__off)) -#define fstMunmap(__addr, __len) \ - { \ - if (__addr) \ - munmap(FST_CADDR_T_CAST(__addr), (__len)); \ - } +#define fstMmap(__addr,__len,__prot,__flags,__fd,__off) (void*)mmap(FST_CADDR_T_CAST (__addr),(__len),(__prot),(__flags),(__fd),(__off)) +#define fstMunmap(__addr,__len) { if(__addr) munmap(FST_CADDR_T_CAST (__addr),(__len)); } #endif + /* * regular and variable-length integer access functions */ -#ifdef FST_DO_MISALIGNED_OPS -#define fstGetUint32(x) (*(uint32_t *)(x)) -#else -static inline uint32_t fstGetUint32(unsigned char *mem) +static uint32_t fstGetUint32(unsigned char *mem) { - union { - uint8_t u8[sizeof(uint32_t)]; - uint32_t u32; - } u; +uint32_t u32; +unsigned char *buf = (unsigned char *)(&u32); - for (size_t i=0; i < sizeof(u.u8); i++) - u.u8[i] = mem[i]; +memcpy(buf, mem, sizeof(uint32_t)); - return u.u32; +return(*(uint32_t *)buf); } -#endif + static int fstWriterUint64(FILE *handle, uint64_t v) { - unsigned char buf[8]; - int i; +unsigned char buf[8]; +int i; - for (i = 7; i >= 0; i--) { +for(i=7;i>=0;i--) + { buf[i] = v & 0xff; v >>= 8; - } + } - fstFwrite(buf, 8, 1, handle); - return (8); +fstFwrite(buf, 8, 1, handle); +return(8); } + static uint64_t fstReaderUint64(FILE *f) { - uint64_t val = 0; - unsigned char buf[sizeof(uint64_t)]; - unsigned int i; +uint64_t val = 0; +unsigned char buf[sizeof(uint64_t)]; +unsigned int i; - fstFread(buf, sizeof(uint64_t), 1, f); - for (i = 0; i < sizeof(uint64_t); i++) { +fstFread(buf, sizeof(uint64_t), 1, f); +for(i=0;i> 7)) /* determine len to avoid temp buffer copying to cut down on load-hit-store */ - { +while((nxt = nxt>>7)) /* determine len to avoid temp buffer copying to cut down on load-hit-store */ + { cnt++; - } + } - pnt -= cnt; - spnt = pnt; - cnt--; +pnt -= cnt; +spnt = pnt; +cnt--; - for (i = 0; i < cnt; i++) /* now generate left to right as normal */ - { - nxt = v >> 7; +for(i=0;i>7; *(spnt++) = ((unsigned char)v) | 0x80; v = nxt; - } - *spnt = (unsigned char)v; + } +*spnt = (unsigned char)v; - return (pnt); +return(pnt); } + static unsigned char *fstCopyVarint64ToRight(unsigned char *pnt, uint64_t v) { - uint64_t nxt; +uint64_t nxt; - while ((nxt = v >> 7)) { +while((nxt = v>>7)) + { *(pnt++) = ((unsigned char)v) | 0x80; v = nxt; - } - *(pnt++) = (unsigned char)v; + } +*(pnt++) = (unsigned char)v; - return (pnt); +return(pnt); } + static uint64_t fstGetVarint64(unsigned char *mem, int *skiplen) { - unsigned char *mem_orig = mem; - uint64_t rc = 0; - while (*mem & 0x80) { +unsigned char *mem_orig = mem; +uint64_t rc = 0; +while(*mem & 0x80) + { mem++; - } + } - *skiplen = mem - mem_orig + 1; - for (;;) { +*skiplen = mem - mem_orig + 1; +for(;;) + { rc <<= 7; rc |= (uint64_t)(*mem & 0x7f); - if (mem == mem_orig) { - break; - } + if(mem == mem_orig) + { + break; + } mem--; - } + } - return (rc); +return(rc); } + static uint32_t fstReaderVarint32(FILE *f) { - unsigned char buf[5]; - unsigned char *mem = buf; - uint32_t rc = 0; - int ch; +int chk_len = 5; /* TALOS-2023-1783 */ +unsigned char buf[chk_len]; +unsigned char *mem = buf; +uint32_t rc = 0; +int ch; - do { +do + { ch = fgetc(f); *(mem++) = ch; - } while (ch & 0x80); - mem--; + } while((ch & 0x80) && (--chk_len)); - for (;;) { +if(ch & 0x80) chk_report_abort("TALOS-2023-1783"); +mem--; + +for(;;) + { rc <<= 7; rc |= (uint32_t)(*mem & 0x7f); - if (mem == buf) { - break; - } + if(mem == buf) + { + break; + } mem--; - } + } - return (rc); +return(rc); } + static uint32_t fstReaderVarint32WithSkip(FILE *f, uint32_t *skiplen) { - unsigned char buf[5]; - unsigned char *mem = buf; - uint32_t rc = 0; - int ch; +int chk_len = 5; /* TALOS-2023-1783 */ +unsigned char buf[chk_len]; +unsigned char *mem = buf; +uint32_t rc = 0; +int ch; - do { +do + { ch = fgetc(f); *(mem++) = ch; - } while (ch & 0x80); - *skiplen = mem - buf; - mem--; + } while((ch & 0x80) && (--chk_len)); - for (;;) { +if(ch & 0x80) chk_report_abort("TALOS-2023-1783"); +*skiplen = mem - buf; +mem--; + +for(;;) + { rc <<= 7; rc |= (uint32_t)(*mem & 0x7f); - if (mem == buf) { - break; - } + if(mem == buf) + { + break; + } mem--; - } + } - return (rc); +return(rc); } + static uint64_t fstReaderVarint64(FILE *f) { - unsigned char buf[16]; - unsigned char *mem = buf; - uint64_t rc = 0; - int ch; +int chk_len = 16; /* TALOS-2023-1783 */ +unsigned char buf[chk_len]; +unsigned char *mem = buf; +uint64_t rc = 0; +int ch; - do { +do + { ch = fgetc(f); *(mem++) = ch; - } while (ch & 0x80); - mem--; + } while((ch & 0x80) && (--chk_len)); - for (;;) { +if(ch & 0x80) chk_report_abort("TALOS-2023-1783"); +mem--; + + +for(;;) + { rc <<= 7; rc |= (uint64_t)(*mem & 0x7f); - if (mem == buf) { - break; - } + if(mem == buf) + { + break; + } mem--; - } + } - return (rc); +return(rc); } + static int fstWriterVarint(FILE *handle, uint64_t v) { - uint64_t nxt; - unsigned char buf[10]; /* ceil(64/7) = 10 */ - unsigned char *pnt = buf; - int len; +uint64_t nxt; +unsigned char buf[10]; /* ceil(64/7) = 10 */ +unsigned char *pnt = buf; +int len; - while ((nxt = v >> 7)) { +while((nxt = v>>7)) + { *(pnt++) = ((unsigned char)v) | 0x80; v = nxt; - } - *(pnt++) = (unsigned char)v; + } +*(pnt++) = (unsigned char)v; - len = pnt - buf; - fstFwrite(buf, len, 1, handle); - return (len); +len = pnt-buf; +fstFwrite(buf, len, 1, handle); +return(len); } + /* signed integer read/write routines are currently unused */ static int64_t fstGetSVarint64(unsigned char *mem, int *skiplen) { - unsigned char *mem_orig = mem; - int64_t rc = 0; - const int64_t one = 1; - const int siz = sizeof(int64_t) * 8; - int shift = 0; - unsigned char byt; +unsigned char *mem_orig = mem; +int64_t rc = 0; +const int64_t one = 1; +const int siz = sizeof(int64_t) * 8; +int shift = 0; +unsigned char byt; - do { +do { byt = *(mem++); rc |= ((int64_t)(byt & 0x7f)) << shift; shift += 7; - } while (byt & 0x80); + } while(byt & 0x80); - if ((shift < siz) && (byt & 0x40)) { +if((shift>= 7; - if (((!v) && (!(byt & 0x40))) || ((v == -1) && (byt & 0x40))) { - more = 0; - byt &= 0x7f; - } + if (((!v) && (!(byt & 0x40))) || ((v == -1) && (byt & 0x40))) + { + more = 0; + byt &= 0x7f; + } *(pnt++) = byt; - } while (more); + } while(more); - len = pnt - buf; - fstFwrite(buf, len, 1, handle); - return (len); +len = pnt-buf; +fstFwrite(buf, len, 1, handle); +return(len); } #endif + /***********************/ /*** ***/ /*** writer function ***/ @@ -662,337 +734,330 @@ static int fstWriterSVarint(FILE *handle, int64_t v) */ struct fstBlackoutChain { - struct fstBlackoutChain *next; - uint64_t tim; - unsigned active : 1; +struct fstBlackoutChain *next; +uint64_t tim; +unsigned active : 1; }; + struct fstWriterContext { - FILE *handle; - FILE *hier_handle; - FILE *geom_handle; - FILE *valpos_handle; - FILE *curval_handle; - FILE *tchn_handle; +FILE *handle; +FILE *hier_handle; +FILE *geom_handle; +FILE *valpos_handle; +FILE *curval_handle; +FILE *tchn_handle; - unsigned char *vchg_mem; +unsigned char *vchg_mem; - fst_off_t hier_file_len; +fst_off_t hier_file_len; - uint32_t *valpos_mem; - unsigned char *curval_mem; +uint32_t *valpos_mem; +unsigned char *curval_mem; - unsigned char *outval_mem; /* for two-state / Verilator-style value changes */ - uint32_t outval_alloc_siz; +unsigned char *outval_mem; /* for two-state / Verilator-style value changes */ +uint32_t outval_alloc_siz; - char *filename; +char *filename; - fstHandle maxhandle; - fstHandle numsigs; - uint32_t maxvalpos; +fstHandle maxhandle; +fstHandle numsigs; +uint32_t maxvalpos; - unsigned vc_emitted : 1; - unsigned is_initial_time : 1; - unsigned fourpack : 1; - unsigned fastpack : 1; +unsigned vc_emitted : 1; +unsigned is_initial_time : 1; +unsigned fourpack : 1; +unsigned fastpack : 1; - int64_t timezero; - fst_off_t section_header_truncpos; - uint32_t tchn_cnt, tchn_idx; - uint64_t curtime; - uint64_t firsttime; - uint32_t vchg_siz; - uint32_t vchg_alloc_siz; +int64_t timezero; +fst_off_t section_header_truncpos; +uint32_t tchn_cnt, tchn_idx; +uint64_t curtime; +uint64_t firsttime; +uint32_t vchg_siz; +uint32_t vchg_alloc_siz; - uint32_t secnum; - fst_off_t section_start; +uint32_t secnum; +fst_off_t section_start; - uint32_t numscopes; - double nan; /* nan value for uninitialized doubles */ +uint32_t numscopes; +double nan; /* nan value for uninitialized doubles */ - struct fstBlackoutChain *blackout_head; - struct fstBlackoutChain *blackout_curr; - uint32_t num_blackouts; +struct fstBlackoutChain *blackout_head; +struct fstBlackoutChain *blackout_curr; +uint32_t num_blackouts; - uint64_t dump_size_limit; +uint64_t dump_size_limit; - unsigned char filetype; /* default is 0, FST_FT_VERILOG */ +unsigned char filetype; /* default is 0, FST_FT_VERILOG */ - unsigned compress_hier : 1; - unsigned repack_on_close : 1; - unsigned skip_writing_section_hdr : 1; - unsigned size_limit_locked : 1; - unsigned section_header_only : 1; - unsigned flush_context_pending : 1; - unsigned parallel_enabled : 1; - unsigned parallel_was_enabled : 1; +unsigned compress_hier : 1; +unsigned repack_on_close : 1; +unsigned skip_writing_section_hdr : 1; +unsigned size_limit_locked : 1; +unsigned section_header_only : 1; +unsigned flush_context_pending : 1; +unsigned parallel_enabled : 1; +unsigned parallel_was_enabled : 1; - /* should really be semaphores, but are bytes to cut down on read-modify-write window size */ - unsigned char already_in_flush; /* in case control-c handlers interrupt */ - unsigned char already_in_close; /* in case control-c handlers interrupt */ +/* should really be semaphores, but are bytes to cut down on read-modify-write window size */ +unsigned char already_in_flush; /* in case control-c handlers interrupt */ +unsigned char already_in_close; /* in case control-c handlers interrupt */ #ifdef FST_WRITER_PARALLEL - pthread_mutex_t mutex; - pthread_t thread; - pthread_attr_t thread_attr; - struct fstWriterContext *xc_parent; +pthread_mutex_t mutex; +pthread_t thread; +pthread_attr_t thread_attr; +struct fstWriterContext *xc_parent; #endif - unsigned in_pthread : 1; +unsigned in_pthread : 1; - size_t fst_orig_break_size; - size_t fst_orig_break_add_size; +size_t fst_orig_break_size; +size_t fst_orig_break_add_size; - size_t fst_break_size; - size_t fst_break_add_size; +size_t fst_break_size; +size_t fst_break_add_size; - size_t fst_huge_break_size; +size_t fst_huge_break_size; - fstHandle next_huge_break; +fstHandle next_huge_break; - Pvoid_t path_array; - uint32_t path_array_count; +Pvoid_t path_array; +uint32_t path_array_count; - unsigned fseek_failed : 1; +unsigned fseek_failed : 1; - char *geom_handle_nam; - char *valpos_handle_nam; - char *curval_handle_nam; - char *tchn_handle_nam; +char *geom_handle_nam; +char *valpos_handle_nam; +char *curval_handle_nam; +char *tchn_handle_nam; - fstEnumHandle max_enumhandle; +fstEnumHandle max_enumhandle; }; + static int fstWriterFseeko(struct fstWriterContext *xc, FILE *stream, fst_off_t offset, int whence) { - int rc = fseeko(stream, offset, whence); +int rc = fseeko(stream, offset, whence); - if (rc < 0) { +if(rc<0) + { xc->fseek_failed = 1; #ifdef FST_DEBUG fprintf(stderr, FST_APIMESS "Seek to #%" PRId64 " (whence = %d) failed!\n", offset, whence); perror("Why"); #endif - } + } - return (rc); +return(rc); } -static uint32_t fstWriterUint32WithVarint32(struct fstWriterContext *xc, uint32_t *u, uint32_t v, const void *dbuf, - uint32_t siz) + +static uint32_t fstWriterUint32WithVarint32(struct fstWriterContext *xc, uint32_t *u, uint32_t v, const void *dbuf, uint32_t siz) { - unsigned char *buf = xc->vchg_mem + xc->vchg_siz; - unsigned char *pnt = buf; - uint32_t nxt; - uint32_t len; +unsigned char *buf = xc->vchg_mem + xc->vchg_siz; +unsigned char *pnt = buf; +uint32_t nxt; +uint32_t len; -#ifdef FST_DO_MISALIGNED_OPS - (*(uint32_t *)(pnt)) = (*(uint32_t *)(u)); -#else - memcpy(pnt, u, sizeof(uint32_t)); -#endif - pnt += 4; +memcpy(pnt, u, sizeof(uint32_t)); +pnt += 4; - while ((nxt = v >> 7)) { +while((nxt = v>>7)) + { *(pnt++) = ((unsigned char)v) | 0x80; v = nxt; - } - *(pnt++) = (unsigned char)v; - memcpy(pnt, dbuf, siz); + } +*(pnt++) = (unsigned char)v; +memcpy(pnt, dbuf, siz); - len = pnt - buf + siz; - return (len); +len = pnt-buf + siz; +return(len); } -static uint32_t fstWriterUint32WithVarint32AndLength(struct fstWriterContext *xc, uint32_t *u, uint32_t v, - const void *dbuf, uint32_t siz) + +static uint32_t fstWriterUint32WithVarint32AndLength(struct fstWriterContext *xc, uint32_t *u, uint32_t v, const void *dbuf, uint32_t siz) { - unsigned char *buf = xc->vchg_mem + xc->vchg_siz; - unsigned char *pnt = buf; - uint32_t nxt; - uint32_t len; +unsigned char *buf = xc->vchg_mem + xc->vchg_siz; +unsigned char *pnt = buf; +uint32_t nxt; +uint32_t len; -#ifdef FST_DO_MISALIGNED_OPS - (*(uint32_t *)(pnt)) = (*(uint32_t *)(u)); -#else - memcpy(pnt, u, sizeof(uint32_t)); -#endif - pnt += 4; +memcpy(pnt, u, sizeof(uint32_t)); +pnt += 4; - while ((nxt = v >> 7)) { +while((nxt = v>>7)) + { *(pnt++) = ((unsigned char)v) | 0x80; v = nxt; - } - *(pnt++) = (unsigned char)v; + } +*(pnt++) = (unsigned char)v; - v = siz; - while ((nxt = v >> 7)) { +v = siz; +while((nxt = v>>7)) + { *(pnt++) = ((unsigned char)v) | 0x80; v = nxt; - } - *(pnt++) = (unsigned char)v; + } +*(pnt++) = (unsigned char)v; - memcpy(pnt, dbuf, siz); +memcpy(pnt, dbuf, siz); - len = pnt - buf + siz; - return (len); +len = pnt-buf + siz; +return(len); } + /* * header bytes, write here so defines are set up before anything else * that needs to use them */ static void fstWriterEmitHdrBytes(struct fstWriterContext *xc) { - char vbuf[FST_HDR_SIM_VERSION_SIZE]; - char dbuf[FST_HDR_DATE_SIZE]; - double endtest = FST_DOUBLE_ENDTEST; - time_t walltime; +char vbuf[FST_HDR_SIM_VERSION_SIZE]; +char dbuf[FST_HDR_DATE_SIZE]; +double endtest = FST_DOUBLE_ENDTEST; +time_t walltime; -#define FST_HDR_OFFS_TAG (0) - fputc(FST_BL_HDR, xc->handle); /* +0 tag */ +#define FST_HDR_OFFS_TAG (0) +fputc(FST_BL_HDR, xc->handle); /* +0 tag */ -#define FST_HDR_OFFS_SECLEN (FST_HDR_OFFS_TAG + 1) - fstWriterUint64(xc->handle, 329); /* +1 section length */ +#define FST_HDR_OFFS_SECLEN (FST_HDR_OFFS_TAG + 1) +fstWriterUint64(xc->handle, 329); /* +1 section length */ -#define FST_HDR_OFFS_START_TIME (FST_HDR_OFFS_SECLEN + 8) - fstWriterUint64(xc->handle, 0); /* +9 start time */ +#define FST_HDR_OFFS_START_TIME (FST_HDR_OFFS_SECLEN + 8) +fstWriterUint64(xc->handle, 0); /* +9 start time */ -#define FST_HDR_OFFS_END_TIME (FST_HDR_OFFS_START_TIME + 8) - fstWriterUint64(xc->handle, 0); /* +17 end time */ +#define FST_HDR_OFFS_END_TIME (FST_HDR_OFFS_START_TIME + 8) +fstWriterUint64(xc->handle, 0); /* +17 end time */ -#define FST_HDR_OFFS_ENDIAN_TEST (FST_HDR_OFFS_END_TIME + 8) - fstFwrite(&endtest, 8, 1, xc->handle); /* +25 endian test for reals */ +#define FST_HDR_OFFS_ENDIAN_TEST (FST_HDR_OFFS_END_TIME + 8) +fstFwrite(&endtest, 8, 1, xc->handle); /* +25 endian test for reals */ -#define FST_HDR_OFFS_MEM_USED (FST_HDR_OFFS_ENDIAN_TEST + 8) - fstWriterUint64(xc->handle, xc->fst_break_size); /* +33 memory used by writer */ +#define FST_HDR_OFFS_MEM_USED (FST_HDR_OFFS_ENDIAN_TEST + 8) +fstWriterUint64(xc->handle, xc->fst_break_size);/* +33 memory used by writer */ -#define FST_HDR_OFFS_NUM_SCOPES (FST_HDR_OFFS_MEM_USED + 8) - fstWriterUint64(xc->handle, 0); /* +41 scope creation count */ +#define FST_HDR_OFFS_NUM_SCOPES (FST_HDR_OFFS_MEM_USED + 8) +fstWriterUint64(xc->handle, 0); /* +41 scope creation count */ -#define FST_HDR_OFFS_NUM_VARS (FST_HDR_OFFS_NUM_SCOPES + 8) - fstWriterUint64(xc->handle, 0); /* +49 var creation count */ +#define FST_HDR_OFFS_NUM_VARS (FST_HDR_OFFS_NUM_SCOPES + 8) +fstWriterUint64(xc->handle, 0); /* +49 var creation count */ -#define FST_HDR_OFFS_MAXHANDLE (FST_HDR_OFFS_NUM_VARS + 8) - fstWriterUint64(xc->handle, 0); /* +57 max var idcode */ +#define FST_HDR_OFFS_MAXHANDLE (FST_HDR_OFFS_NUM_VARS + 8) +fstWriterUint64(xc->handle, 0); /* +57 max var idcode */ -#define FST_HDR_OFFS_SECTION_CNT (FST_HDR_OFFS_MAXHANDLE + 8) - fstWriterUint64(xc->handle, 0); /* +65 vc section count */ +#define FST_HDR_OFFS_SECTION_CNT (FST_HDR_OFFS_MAXHANDLE + 8) +fstWriterUint64(xc->handle, 0); /* +65 vc section count */ -#define FST_HDR_OFFS_TIMESCALE (FST_HDR_OFFS_SECTION_CNT + 8) - fputc((-9) & 255, xc->handle); /* +73 timescale 1ns */ +#define FST_HDR_OFFS_TIMESCALE (FST_HDR_OFFS_SECTION_CNT + 8) +fputc((-9)&255, xc->handle); /* +73 timescale 1ns */ -#define FST_HDR_OFFS_SIM_VERSION (FST_HDR_OFFS_TIMESCALE + 1) - memset(vbuf, 0, FST_HDR_SIM_VERSION_SIZE); - strcpy(vbuf, FST_WRITER_STR); - fstFwrite(vbuf, FST_HDR_SIM_VERSION_SIZE, 1, xc->handle); /* +74 version */ +#define FST_HDR_OFFS_SIM_VERSION (FST_HDR_OFFS_TIMESCALE + 1) +memset(vbuf, 0, FST_HDR_SIM_VERSION_SIZE); +strcpy(vbuf, FST_WRITER_STR); +fstFwrite(vbuf, FST_HDR_SIM_VERSION_SIZE, 1, xc->handle); /* +74 version */ -#define FST_HDR_OFFS_DATE (FST_HDR_OFFS_SIM_VERSION + FST_HDR_SIM_VERSION_SIZE) - memset(dbuf, 0, FST_HDR_DATE_SIZE); - time(&walltime); - strcpy(dbuf, asctime(localtime(&walltime))); - fstFwrite(dbuf, FST_HDR_DATE_SIZE, 1, xc->handle); /* +202 date */ +#define FST_HDR_OFFS_DATE (FST_HDR_OFFS_SIM_VERSION + FST_HDR_SIM_VERSION_SIZE) +memset(dbuf, 0, FST_HDR_DATE_SIZE); +time(&walltime); +strcpy(dbuf, asctime(localtime(&walltime))); +fstFwrite(dbuf, FST_HDR_DATE_SIZE, 1, xc->handle); /* +202 date */ - /* date size is deliberately overspecified at 119 bytes (originally 128) in order to provide backfill for new args - */ +/* date size is deliberately overspecified at 119 bytes (originally 128) in order to provide backfill for new args */ -#define FST_HDR_OFFS_FILETYPE (FST_HDR_OFFS_DATE + FST_HDR_DATE_SIZE) - fputc(xc->filetype, xc->handle); /* +321 filetype */ +#define FST_HDR_OFFS_FILETYPE (FST_HDR_OFFS_DATE + FST_HDR_DATE_SIZE) +fputc(xc->filetype, xc->handle); /* +321 filetype */ -#define FST_HDR_OFFS_TIMEZERO (FST_HDR_OFFS_FILETYPE + FST_HDR_FILETYPE_SIZE) - fstWriterUint64(xc->handle, xc->timezero); /* +322 timezero */ +#define FST_HDR_OFFS_TIMEZERO (FST_HDR_OFFS_FILETYPE + FST_HDR_FILETYPE_SIZE) +fstWriterUint64(xc->handle, xc->timezero); /* +322 timezero */ -#define FST_HDR_LENGTH (FST_HDR_OFFS_TIMEZERO + FST_HDR_TIMEZERO_SIZE) - /* +330 next section starts here */ - fflush(xc->handle); +#define FST_HDR_LENGTH (FST_HDR_OFFS_TIMEZERO + FST_HDR_TIMEZERO_SIZE) + /* +330 next section starts here */ +fflush(xc->handle); } + /* * mmap functions */ static void fstWriterMmapSanity(void *pnt, const char *file, int line, const char *usage) { -#if !defined(__CYGWIN__) && !defined(__MINGW32__) && !defined(_MSC_VER) - if (pnt == MAP_FAILED) { - fprintf(stderr, "fstMmap() assigned to %s failed: errno: %d, file %s, line %d.\n", usage, errno, file, line); - perror("Why"); - pnt = NULL; - } +if(pnt == NULL +#ifdef MAP_FAILED + || pnt == MAP_FAILED #endif + ) + { + fprintf(stderr, "fstMmap() assigned to %s failed: errno: %d, file %s, line %d.\n", usage, errno, file, line); +#if !defined(__MINGW32__) + perror("Why"); +#else + LPSTR mbuf = NULL; + FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM + | FORMAT_MESSAGE_IGNORE_INSERTS, NULL, GetLastError(), + MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), + (LPSTR)&mbuf, 0, NULL); + fprintf(stderr, "%s", mbuf); + LocalFree(mbuf); +#endif + pnt = NULL; + } } + static void fstWriterCreateMmaps(struct fstWriterContext *xc) { - fst_off_t curpos = ftello(xc->handle); +fst_off_t curpos = ftello(xc->handle); - fflush(xc->hier_handle); +fflush(xc->hier_handle); - /* write out intermediate header */ - fstWriterFseeko(xc, xc->handle, FST_HDR_OFFS_START_TIME, SEEK_SET); - fstWriterUint64(xc->handle, xc->firsttime); - fstWriterUint64(xc->handle, xc->curtime); - fstWriterFseeko(xc, xc->handle, FST_HDR_OFFS_NUM_SCOPES, SEEK_SET); - fstWriterUint64(xc->handle, xc->numscopes); - fstWriterUint64(xc->handle, xc->numsigs); - fstWriterUint64(xc->handle, xc->maxhandle); - fstWriterUint64(xc->handle, xc->secnum); - fstWriterFseeko(xc, xc->handle, curpos, SEEK_SET); - fflush(xc->handle); +/* write out intermediate header */ +fstWriterFseeko(xc, xc->handle, FST_HDR_OFFS_START_TIME, SEEK_SET); +fstWriterUint64(xc->handle, xc->firsttime); +fstWriterUint64(xc->handle, xc->curtime); +fstWriterFseeko(xc, xc->handle, FST_HDR_OFFS_NUM_SCOPES, SEEK_SET); +fstWriterUint64(xc->handle, xc->numscopes); +fstWriterUint64(xc->handle, xc->numsigs); +fstWriterUint64(xc->handle, xc->maxhandle); +fstWriterUint64(xc->handle, xc->secnum); +fstWriterFseeko(xc, xc->handle, curpos, SEEK_SET); +fflush(xc->handle); - /* do mappings */ - if (!xc->valpos_mem) { +/* do mappings */ +if(!xc->valpos_mem) + { fflush(xc->valpos_handle); - errno = 0; - if (xc->maxhandle) { - fstWriterMmapSanity(xc->valpos_mem = (uint32_t *)fstMmap(NULL, xc->maxhandle * 4 * sizeof(uint32_t), - PROT_READ | PROT_WRITE, MAP_SHARED, - fileno(xc->valpos_handle), 0), - __FILE__, __LINE__, "xc->valpos_mem"); + errno = 0; + if(xc->maxhandle) + { + fstWriterMmapSanity(xc->valpos_mem = (uint32_t *)fstMmap(NULL, xc->maxhandle * 4 * sizeof(uint32_t), PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->valpos_handle), 0), __FILE__, __LINE__, "xc->valpos_mem"); + } } - } - if (!xc->curval_mem) { +if(!xc->curval_mem) + { fflush(xc->curval_handle); - errno = 0; - if (xc->maxvalpos) { - fstWriterMmapSanity(xc->curval_mem = (unsigned char *)fstMmap(NULL, xc->maxvalpos, PROT_READ | PROT_WRITE, - MAP_SHARED, fileno(xc->curval_handle), 0), - __FILE__, __LINE__, "xc->curval_handle"); + errno = 0; + if(xc->maxvalpos) + { + fstWriterMmapSanity(xc->curval_mem = (unsigned char *)fstMmap(NULL, xc->maxvalpos, PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->curval_handle), 0), __FILE__, __LINE__, "xc->curval_handle"); + } } - } } + static void fstDestroyMmaps(struct fstWriterContext *xc, int is_closing) { -#if !defined __CYGWIN__ && !defined __MINGW32__ - (void)is_closing; -#endif +(void)is_closing; - fstMunmap(xc->valpos_mem, xc->maxhandle * 4 * sizeof(uint32_t)); - xc->valpos_mem = NULL; +fstMunmap(xc->valpos_mem, xc->maxhandle * 4 * sizeof(uint32_t)); +xc->valpos_mem = NULL; -#if defined __CYGWIN__ || defined __MINGW32__ - if (xc->curval_mem) { - if (!is_closing) /* need to flush out for next emulated mmap() read */ - { - unsigned char *pnt = xc->curval_mem; - int __fd = fileno(xc->curval_handle); - fst_off_t cur_offs = lseek(__fd, 0, SEEK_CUR); - size_t i; - size_t __len = xc->maxvalpos; - - lseek(__fd, 0, SEEK_SET); - for (i = 0; i < __len; i += SSIZE_MAX) { - write(__fd, pnt + i, ((__len - i) >= SSIZE_MAX) ? SSIZE_MAX : (__len - i)); - } - lseek(__fd, cur_offs, SEEK_SET); - } - } -#endif - - fstMunmap(xc->curval_mem, xc->maxvalpos); - xc->curval_mem = NULL; +fstMunmap(xc->curval_mem, xc->maxvalpos); +xc->curval_mem = NULL; } + /* * set up large and small memory usages * crossover point in model is FST_ACTIVATE_HUGE_BREAK number of signals @@ -1000,89 +1065,105 @@ static void fstDestroyMmaps(struct fstWriterContext *xc, int is_closing) static void fstDetermineBreakSize(struct fstWriterContext *xc) { #if defined(__linux__) || defined(FST_MACOSX) - int was_set = 0; +int was_set = 0; #ifdef __linux__ - FILE *f = fopen("/proc/meminfo", "rb"); +FILE *f = fopen("/proc/meminfo", "rb"); - if (f) { +if(f) + { char buf[257]; char *s; - while (!feof(f)) { - buf[0] = 0; - s = fgets(buf, 256, f); - if (s && *s) { - if (!strncmp(s, "MemTotal:", 9)) { - size_t v = atol(s + 10); - v *= 1024; /* convert to bytes */ - v /= 8; /* chop down to 1/8 physical memory */ - if (v > FST_BREAK_SIZE) { - if (v > FST_BREAK_SIZE_MAX) { - v = FST_BREAK_SIZE_MAX; - } + while(!feof(f)) + { + buf[0] = 0; + s = fgets(buf, 256, f); + if(s && *s) + { + if(!strncmp(s, "MemTotal:", 9)) + { + size_t v = atol(s+10); + v *= 1024; /* convert to bytes */ + v /= 8; /* chop down to 1/8 physical memory */ + if(v > FST_BREAK_SIZE) + { + if(v > FST_BREAK_SIZE_MAX) + { + v = FST_BREAK_SIZE_MAX; + } - xc->fst_huge_break_size = v; - was_set = 1; - break; - } + xc->fst_huge_break_size = v; + was_set = 1; + break; + } + } + } } - } - } fclose(f); - } + } - if (!was_set) { +if(!was_set) + { xc->fst_huge_break_size = FST_BREAK_SIZE; - } + } #else - int mib[2]; - int64_t v; - size_t length; +int mib[2]; +int64_t v; +size_t length; - mib[0] = CTL_HW; - mib[1] = HW_MEMSIZE; - length = sizeof(int64_t); - if (!sysctl(mib, 2, &v, &length, NULL, 0)) { +mib[0] = CTL_HW; +mib[1] = HW_MEMSIZE; +length = sizeof(int64_t); +if(!sysctl(mib, 2, &v, &length, NULL, 0)) + { v /= 8; - if (v > (int64_t)FST_BREAK_SIZE) { - if (v > (int64_t)FST_BREAK_SIZE_MAX) { - v = FST_BREAK_SIZE_MAX; - } + if(v > (int64_t)FST_BREAK_SIZE) + { + if(v > (int64_t)FST_BREAK_SIZE_MAX) + { + v = FST_BREAK_SIZE_MAX; + } - xc->fst_huge_break_size = v; - was_set = 1; + xc->fst_huge_break_size = v; + was_set = 1; + } } - } - if (!was_set) { +if(!was_set) + { xc->fst_huge_break_size = FST_BREAK_SIZE; - } + } #endif #else - xc->fst_huge_break_size = FST_BREAK_SIZE; +xc->fst_huge_break_size = FST_BREAK_SIZE; #endif - xc->fst_break_size = xc->fst_orig_break_size = FST_BREAK_SIZE; - xc->fst_break_add_size = xc->fst_orig_break_add_size = FST_BREAK_ADD_SIZE; - xc->next_huge_break = FST_ACTIVATE_HUGE_BREAK; +xc->fst_break_size = xc->fst_orig_break_size = FST_BREAK_SIZE; +xc->fst_break_add_size = xc->fst_orig_break_add_size = FST_BREAK_ADD_SIZE; +xc->next_huge_break = FST_ACTIVATE_HUGE_BREAK; } + /* * file creation and close */ void *fstWriterCreate(const char *nam, int use_compressed_hier) { - struct fstWriterContext *xc = (struct fstWriterContext *)calloc(1, sizeof(struct fstWriterContext)); +struct fstWriterContext *xc = (struct fstWriterContext *)calloc(1, sizeof(struct fstWriterContext)); - xc->compress_hier = use_compressed_hier; - fstDetermineBreakSize(xc); +xc->compress_hier = use_compressed_hier; +fstDetermineBreakSize(xc); - if ((!nam) || (!(xc->handle = unlink_fopen(nam, "w+b")))) { +if((!nam)|| + (!(xc->handle=unlink_fopen(nam, "w+b")))) + { free(xc); - xc = NULL; - } else { + xc=NULL; + } + else + { int flen = strlen(nam); char *hf = (char *)calloc(1, flen + 6); @@ -1090,96 +1171,99 @@ void *fstWriterCreate(const char *nam, int use_compressed_hier) strcpy(hf + flen, ".hier"); xc->hier_handle = unlink_fopen(hf, "w+b"); - xc->geom_handle = tmpfile_open(&xc->geom_handle_nam); /* .geom */ - xc->valpos_handle = tmpfile_open(&xc->valpos_handle_nam); /* .offs */ - xc->curval_handle = tmpfile_open(&xc->curval_handle_nam); /* .bits */ - xc->tchn_handle = tmpfile_open(&xc->tchn_handle_nam); /* .tchn */ + xc->geom_handle = tmpfile_open(&xc->geom_handle_nam); /* .geom */ + xc->valpos_handle = tmpfile_open(&xc->valpos_handle_nam); /* .offs */ + xc->curval_handle = tmpfile_open(&xc->curval_handle_nam); /* .bits */ + xc->tchn_handle = tmpfile_open(&xc->tchn_handle_nam); /* .tchn */ xc->vchg_alloc_siz = xc->fst_break_size + xc->fst_break_add_size; xc->vchg_mem = (unsigned char *)malloc(xc->vchg_alloc_siz); - if (xc->hier_handle && xc->geom_handle && xc->valpos_handle && xc->curval_handle && xc->vchg_mem && - xc->tchn_handle) { - xc->filename = strdup(nam); - xc->is_initial_time = 1; + if(xc->hier_handle && xc->geom_handle && xc->valpos_handle && xc->curval_handle && xc->vchg_mem && xc->tchn_handle) + { + xc->filename = strdup(nam); + xc->is_initial_time = 1; - fstWriterEmitHdrBytes(xc); - xc->nan = strtod("NaN", NULL); + fstWriterEmitHdrBytes(xc); + xc->nan = strtod("NaN", NULL); #ifdef FST_WRITER_PARALLEL - pthread_mutex_init(&xc->mutex, NULL); - pthread_attr_init(&xc->thread_attr); - pthread_attr_setdetachstate(&xc->thread_attr, PTHREAD_CREATE_DETACHED); + pthread_mutex_init(&xc->mutex, NULL); + pthread_attr_init(&xc->thread_attr); + pthread_attr_setdetachstate(&xc->thread_attr, PTHREAD_CREATE_DETACHED); #endif - } else { - fclose(xc->handle); - if (xc->hier_handle) { - fclose(xc->hier_handle); - unlink(hf); - } - tmpfile_close(&xc->geom_handle, &xc->geom_handle_nam); - tmpfile_close(&xc->valpos_handle, &xc->valpos_handle_nam); - tmpfile_close(&xc->curval_handle, &xc->curval_handle_nam); - tmpfile_close(&xc->tchn_handle, &xc->tchn_handle_nam); - free(xc->vchg_mem); - free(xc); - xc = NULL; - } + } + else + { + fclose(xc->handle); + if(xc->hier_handle) { fclose(xc->hier_handle); unlink(hf); } + tmpfile_close(&xc->geom_handle, &xc->geom_handle_nam); + tmpfile_close(&xc->valpos_handle, &xc->valpos_handle_nam); + tmpfile_close(&xc->curval_handle, &xc->curval_handle_nam); + tmpfile_close(&xc->tchn_handle, &xc->tchn_handle_nam); + free(xc->vchg_mem); + free(xc); + xc=NULL; + } free(hf); - } + } - return (xc); +return(xc); } + /* * generation and writing out of value change data sections */ static void fstWriterEmitSectionHeader(void *ctx) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { +if(xc) + { unsigned long destlen; unsigned char *dmem; int rc; destlen = xc->maxvalpos; dmem = (unsigned char *)malloc(compressBound(destlen)); - rc = compress2(dmem, &destlen, xc->curval_mem, xc->maxvalpos, - 4); /* was 9...which caused performance drag on traces with many signals */ + rc = compress2(dmem, &destlen, xc->curval_mem, xc->maxvalpos, 4); /* was 9...which caused performance drag on traces with many signals */ - fputc(FST_BL_SKIP, xc->handle); /* temporarily tag the section, use FST_BL_VCDATA on finalize */ + fputc(FST_BL_SKIP, xc->handle); /* temporarily tag the section, use FST_BL_VCDATA on finalize */ xc->section_start = ftello(xc->handle); #ifdef FST_WRITER_PARALLEL - if (xc->xc_parent) - xc->xc_parent->section_start = xc->section_start; + if(xc->xc_parent) xc->xc_parent->section_start = xc->section_start; #endif - xc->section_header_only = 1; /* indicates truncate might be needed */ - fstWriterUint64(xc->handle, 0); /* placeholder = section length */ - fstWriterUint64(xc->handle, xc->is_initial_time ? xc->firsttime : xc->curtime); /* begin time of section */ - fstWriterUint64(xc->handle, xc->curtime); /* end time of section (placeholder) */ - fstWriterUint64(xc->handle, - 0); /* placeholder = amount of buffer memory required in reader for full vc traversal */ - fstWriterVarint(xc->handle, xc->maxvalpos); /* maxvalpos = length of uncompressed data */ + xc->section_header_only = 1; /* indicates truncate might be needed */ + fstWriterUint64(xc->handle, 0); /* placeholder = section length */ + fstWriterUint64(xc->handle, xc->is_initial_time ? xc->firsttime : xc->curtime); /* begin time of section */ + fstWriterUint64(xc->handle, xc->curtime); /* end time of section (placeholder) */ + fstWriterUint64(xc->handle, 0); /* placeholder = amount of buffer memory required in reader for full vc traversal */ + fstWriterVarint(xc->handle, xc->maxvalpos); /* maxvalpos = length of uncompressed data */ - if ((rc == Z_OK) && (destlen < xc->maxvalpos)) { - fstWriterVarint(xc->handle, destlen); /* length of compressed data */ - } else { - fstWriterVarint(xc->handle, xc->maxvalpos); /* length of (unable to be) compressed data */ - } - fstWriterVarint(xc->handle, - xc->maxhandle); /* max handle associated with this data (in case of dynamic facility adds) */ + if((rc == Z_OK) && (destlen < xc->maxvalpos)) + { + fstWriterVarint(xc->handle, destlen); /* length of compressed data */ + } + else + { + fstWriterVarint(xc->handle, xc->maxvalpos); /* length of (unable to be) compressed data */ + } + fstWriterVarint(xc->handle, xc->maxhandle); /* max handle associated with this data (in case of dynamic facility adds) */ - if ((rc == Z_OK) && (destlen < xc->maxvalpos)) { - fstFwrite(dmem, destlen, 1, xc->handle); - } else /* comparison between compressed / decompressed len tells if compressed */ - { - fstFwrite(xc->curval_mem, xc->maxvalpos, 1, xc->handle); - } + if((rc == Z_OK) && (destlen < xc->maxvalpos)) + { + fstFwrite(dmem, destlen, 1, xc->handle); + } + else /* comparison between compressed / decompressed len tells if compressed */ + { + fstFwrite(xc->curval_mem, xc->maxvalpos, 1, xc->handle); + } free(dmem); - } + } } + /* * only to be called directly by fst code...otherwise must * be synced up with time changes @@ -1191,517 +1275,566 @@ static void fstWriterFlushContextPrivate(void *ctx) #endif { #ifdef FST_DEBUG - int cnt = 0; +int cnt = 0; #endif - unsigned int i; - unsigned char *vchg_mem; - FILE *f; - fst_off_t fpos, indxpos, endpos; - uint32_t prevpos; - int zerocnt; - unsigned char *scratchpad; - unsigned char *scratchpnt; - unsigned char *tmem; - fst_off_t tlen; - fst_off_t unc_memreq = 0; /* for reader */ - unsigned char *packmem; - unsigned int packmemlen; - uint32_t *vm4ip; - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +unsigned int i; +unsigned char *vchg_mem; +FILE *f; +fst_off_t fpos, indxpos, endpos; +uint32_t prevpos; +int zerocnt; +unsigned char *scratchpad; +unsigned char *scratchpnt; +unsigned char *tmem; +fst_off_t tlen; +fst_off_t unc_memreq = 0; /* for reader */ +unsigned char *packmem; +unsigned int packmemlen; +uint32_t *vm4ip; +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; #ifdef FST_WRITER_PARALLEL - struct fstWriterContext *xc2 = xc->xc_parent; +struct fstWriterContext *xc2 = xc->xc_parent; #else - struct fstWriterContext *xc2 = xc; +struct fstWriterContext *xc2 = xc; #endif #ifndef FST_DYNAMIC_ALIAS_DISABLE - Pvoid_t PJHSArray = (Pvoid_t)NULL; +Pvoid_t PJHSArray = (Pvoid_t) NULL; #ifndef _WAVE_HAVE_JUDY - uint32_t hashmask = xc->maxhandle; - hashmask |= hashmask >> 1; - hashmask |= hashmask >> 2; - hashmask |= hashmask >> 4; - hashmask |= hashmask >> 8; - hashmask |= hashmask >> 16; +uint32_t hashmask = xc->maxhandle; +hashmask |= hashmask >> 1; +hashmask |= hashmask >> 2; +hashmask |= hashmask >> 4; +hashmask |= hashmask >> 8; +hashmask |= hashmask >> 16; #endif #endif - if ((xc->vchg_siz <= 1) || (xc->already_in_flush)) - return; - xc->already_in_flush = 1; /* should really do this with a semaphore */ +if((xc->vchg_siz <= 1)||(xc->already_in_flush)) return; +xc->already_in_flush = 1; /* should really do this with a semaphore */ - xc->section_header_only = 0; - scratchpad = (unsigned char *)malloc(xc->vchg_siz); +xc->section_header_only = 0; +scratchpad = (unsigned char *)malloc(xc->vchg_siz); - vchg_mem = xc->vchg_mem; +vchg_mem = xc->vchg_mem; - f = xc->handle; - fstWriterVarint(f, xc->maxhandle); /* emit current number of handles */ - fputc(xc->fourpack ? '4' : (xc->fastpack ? 'F' : 'Z'), f); - fpos = 1; +f = xc->handle; +fstWriterVarint(f, xc->maxhandle); /* emit current number of handles */ +fputc(xc->fourpack ? '4' : (xc->fastpack ? 'F' : 'Z'), f); +fpos = 1; - packmemlen = 1024; /* maintain a running "longest" allocation to */ - packmem = (unsigned char *)malloc(packmemlen); /* prevent continual malloc...free every loop iter */ +packmemlen = 1024; /* maintain a running "longest" allocation to */ +packmem = (unsigned char *)malloc(packmemlen); /* prevent continual malloc...free every loop iter */ - for (i = 0; i < xc->maxhandle; i++) { - vm4ip = &(xc->valpos_mem[4 * i]); +for(i=0;imaxhandle;i++) + { + vm4ip = &(xc->valpos_mem[4*i]); - if (vm4ip[2]) { - uint32_t offs = vm4ip[2]; - uint32_t next_offs; - unsigned int wrlen; + if(vm4ip[2]) + { + uint32_t offs = vm4ip[2]; + uint32_t next_offs; + unsigned int wrlen; - vm4ip[2] = fpos; + vm4ip[2] = fpos; - scratchpnt = scratchpad + xc->vchg_siz; /* build this buffer backwards */ - if (vm4ip[1] <= 1) { - if (vm4ip[1] == 1) { - wrlen = fstGetVarint32Length(vchg_mem + offs + 4); /* used to advance and determine wrlen */ + scratchpnt = scratchpad + xc->vchg_siz; /* build this buffer backwards */ + if(vm4ip[1] <= 1) + { + if(vm4ip[1] == 1) + { + wrlen = fstGetVarint32Length(vchg_mem + offs + 4); /* used to advance and determine wrlen */ #ifndef FST_REMOVE_DUPLICATE_VC - xc->curval_mem[vm4ip[0]] = vchg_mem[offs + 4 + wrlen]; /* checkpoint variable */ + xc->curval_mem[vm4ip[0]] = vchg_mem[offs + 4 + wrlen]; /* checkpoint variable */ #endif - while (offs) { - unsigned char val; - uint32_t time_delta, rcv; - next_offs = fstGetUint32(vchg_mem + offs); - offs += 4; + while(offs) + { + unsigned char val; + uint32_t time_delta, rcv; + next_offs = fstGetUint32(vchg_mem + offs); + offs += 4; - time_delta = fstGetVarint32(vchg_mem + offs, (int *)&wrlen); - val = vchg_mem[offs + wrlen]; - offs = next_offs; + time_delta = fstGetVarint32(vchg_mem + offs, (int *)&wrlen); + val = vchg_mem[offs+wrlen]; + offs = next_offs; - switch (val) { - case '0': - case '1': - rcv = ((val & 1) << 1) | (time_delta << 2); - break; /* pack more delta bits in for 0/1 vchs */ + switch(val) + { + case '0': + case '1': rcv = ((val&1)<<1) | (time_delta<<2); + break; /* pack more delta bits in for 0/1 vchs */ - case 'x': - case 'X': - rcv = FST_RCV_X | (time_delta << 4); - break; - case 'z': - case 'Z': - rcv = FST_RCV_Z | (time_delta << 4); - break; - case 'h': - case 'H': - rcv = FST_RCV_H | (time_delta << 4); - break; - case 'u': - case 'U': - rcv = FST_RCV_U | (time_delta << 4); - break; - case 'w': - case 'W': - rcv = FST_RCV_W | (time_delta << 4); - break; - case 'l': - case 'L': - rcv = FST_RCV_L | (time_delta << 4); - break; - default: - rcv = FST_RCV_D | (time_delta << 4); - break; + case 'x': case 'X': rcv = FST_RCV_X | (time_delta<<4); break; + case 'z': case 'Z': rcv = FST_RCV_Z | (time_delta<<4); break; + case 'h': case 'H': rcv = FST_RCV_H | (time_delta<<4); break; + case 'u': case 'U': rcv = FST_RCV_U | (time_delta<<4); break; + case 'w': case 'W': rcv = FST_RCV_W | (time_delta<<4); break; + case 'l': case 'L': rcv = FST_RCV_L | (time_delta<<4); break; + default: rcv = FST_RCV_D | (time_delta<<4); break; + } + + scratchpnt = fstCopyVarint32ToLeft(scratchpnt, rcv); + } + } + else + { + /* variable length */ + /* fstGetUint32 (next_offs) + fstGetVarint32 (time_delta) + fstGetVarint32 (len) + payload */ + unsigned char *pnt; + uint32_t record_len; + uint32_t time_delta; + + while(offs) + { + next_offs = fstGetUint32(vchg_mem + offs); + offs += 4; + pnt = vchg_mem + offs; + offs = next_offs; + time_delta = fstGetVarint32(pnt, (int *)&wrlen); + pnt += wrlen; + record_len = fstGetVarint32(pnt, (int *)&wrlen); + pnt += wrlen; + + scratchpnt -= record_len; + memcpy(scratchpnt, pnt, record_len); + + scratchpnt = fstCopyVarint32ToLeft(scratchpnt, record_len); + scratchpnt = fstCopyVarint32ToLeft(scratchpnt, (time_delta << 1)); /* reserve | 1 case for future expansion */ + } + } } - - scratchpnt = fstCopyVarint32ToLeft(scratchpnt, rcv); - } - } else { - /* variable length */ - /* fstGetUint32 (next_offs) + fstGetVarint32 (time_delta) + fstGetVarint32 (len) + payload */ - unsigned char *pnt; - uint32_t record_len; - uint32_t time_delta; - - while (offs) { - next_offs = fstGetUint32(vchg_mem + offs); - offs += 4; - pnt = vchg_mem + offs; - offs = next_offs; - time_delta = fstGetVarint32(pnt, (int *)&wrlen); - pnt += wrlen; - record_len = fstGetVarint32(pnt, (int *)&wrlen); - pnt += wrlen; - - scratchpnt -= record_len; - memcpy(scratchpnt, pnt, record_len); - - scratchpnt = fstCopyVarint32ToLeft(scratchpnt, record_len); - scratchpnt = fstCopyVarint32ToLeft( - scratchpnt, (time_delta << 1)); /* reserve | 1 case for future expansion */ - } - } - } else { - wrlen = fstGetVarint32Length(vchg_mem + offs + 4); /* used to advance and determine wrlen */ + else + { + wrlen = fstGetVarint32Length(vchg_mem + offs + 4); /* used to advance and determine wrlen */ #ifndef FST_REMOVE_DUPLICATE_VC - memcpy(xc->curval_mem + vm4ip[0], vchg_mem + offs + 4 + wrlen, vm4ip[1]); /* checkpoint variable */ + memcpy(xc->curval_mem + vm4ip[0], vchg_mem + offs + 4 + wrlen, vm4ip[1]); /* checkpoint variable */ #endif - while (offs) { - unsigned int idx; - char is_binary = 1; - unsigned char *pnt; - uint32_t time_delta; + while(offs) + { + unsigned int idx; + char is_binary = 1; + unsigned char *pnt; + uint32_t time_delta; - next_offs = fstGetUint32(vchg_mem + offs); - offs += 4; + next_offs = fstGetUint32(vchg_mem + offs); + offs += 4; - time_delta = fstGetVarint32(vchg_mem + offs, (int *)&wrlen); + time_delta = fstGetVarint32(vchg_mem + offs, (int *)&wrlen); - pnt = vchg_mem + offs + wrlen; - offs = next_offs; + pnt = vchg_mem+offs+wrlen; + offs = next_offs; - for (idx = 0; idx < vm4ip[1]; idx++) { - if ((pnt[idx] == '0') || (pnt[idx] == '1')) { - continue; - } else { - is_binary = 0; - break; - } - } + for(idx=0;idxvchg_siz - scratchpnt; + unc_memreq += wrlen; + if(wrlen > 32) + { + unsigned long destlen = wrlen; + unsigned char *dmem; + unsigned int rc; - scratchpnt = fstCopyVarint32ToLeft(scratchpnt, (time_delta << 1) | 1); - } - } - } + if(!xc->fastpack) + { + if(wrlen <= packmemlen) + { + dmem = packmem; + } + else + { + free(packmem); + dmem = packmem = (unsigned char *)malloc(compressBound(packmemlen = wrlen)); + } - wrlen = scratchpad + xc->vchg_siz - scratchpnt; - unc_memreq += wrlen; - if (wrlen > 32) { - unsigned long destlen = wrlen; - unsigned char *dmem; - unsigned int rc; - - if (!xc->fastpack) { - if (wrlen <= packmemlen) { - dmem = packmem; - } else { - free(packmem); - dmem = packmem = (unsigned char *)malloc(compressBound(packmemlen = wrlen)); - } - - rc = compress2(dmem, &destlen, scratchpnt, wrlen, 4); - if (rc == Z_OK) { + rc = compress2(dmem, &destlen, scratchpnt, wrlen, 4); + if(rc == Z_OK) + { #ifndef FST_DYNAMIC_ALIAS_DISABLE - PPvoid_t pv = JudyHSIns(&PJHSArray, dmem, destlen, NULL); - if (*pv) { - uint32_t pvi = (intptr_t)(*pv); - vm4ip[2] = -pvi; - } else { - *pv = (void *)(intptr_t)(i + 1); + PPvoid_t pv = JudyHSIns(&PJHSArray, dmem, destlen, NULL); + if(*pv) + { + uint32_t pvi = (intptr_t)(*pv); + vm4ip[2] = -pvi; + } + else + { + *pv = (void *)(intptr_t)(i+1); #endif - fpos += fstWriterVarint(f, wrlen); - fpos += destlen; - fstFwrite(dmem, destlen, 1, f); + fpos += fstWriterVarint(f, wrlen); + fpos += destlen; + fstFwrite(dmem, destlen, 1, f); #ifndef FST_DYNAMIC_ALIAS_DISABLE - } + } #endif - } else { + } + else + { +#ifndef FST_DYNAMIC_ALIAS_DISABLE + PPvoid_t pv = JudyHSIns(&PJHSArray, scratchpnt, wrlen, NULL); + if(*pv) + { + uint32_t pvi = (intptr_t)(*pv); + vm4ip[2] = -pvi; + } + else + { + *pv = (void *)(intptr_t)(i+1); +#endif + fpos += fstWriterVarint(f, 0); + fpos += wrlen; + fstFwrite(scratchpnt, wrlen, 1, f); +#ifndef FST_DYNAMIC_ALIAS_DISABLE + } +#endif + } + } + else + { + /* this is extremely conservative: fastlz needs +5% for worst case, lz4 needs siz+(siz/255)+16 */ + if(((wrlen * 2) + 2) <= packmemlen) + { + dmem = packmem; + } + else + { + free(packmem); + dmem = packmem = (unsigned char *)malloc(packmemlen = (wrlen * 2) + 2); + } + + rc = (xc->fourpack) ? LZ4_compress_default((char *)scratchpnt, (char *)dmem, wrlen, packmemlen) : fastlz_compress(scratchpnt, wrlen, dmem); + if(rc < destlen) + { +#ifndef FST_DYNAMIC_ALIAS_DISABLE + PPvoid_t pv = JudyHSIns(&PJHSArray, dmem, rc, NULL); + if(*pv) + { + uint32_t pvi = (intptr_t)(*pv); + vm4ip[2] = -pvi; + } + else + { + *pv = (void *)(intptr_t)(i+1); +#endif + fpos += fstWriterVarint(f, wrlen); + fpos += rc; + fstFwrite(dmem, rc, 1, f); +#ifndef FST_DYNAMIC_ALIAS_DISABLE + } +#endif + } + else + { +#ifndef FST_DYNAMIC_ALIAS_DISABLE + PPvoid_t pv = JudyHSIns(&PJHSArray, scratchpnt, wrlen, NULL); + if(*pv) + { + uint32_t pvi = (intptr_t)(*pv); + vm4ip[2] = -pvi; + } + else + { + *pv = (void *)(intptr_t)(i+1); +#endif + fpos += fstWriterVarint(f, 0); + fpos += wrlen; + fstFwrite(scratchpnt, wrlen, 1, f); +#ifndef FST_DYNAMIC_ALIAS_DISABLE + } +#endif + } + } + } + else + { #ifndef FST_DYNAMIC_ALIAS_DISABLE PPvoid_t pv = JudyHSIns(&PJHSArray, scratchpnt, wrlen, NULL); - if (*pv) { - uint32_t pvi = (intptr_t)(*pv); - vm4ip[2] = -pvi; - } else { - *pv = (void *)(intptr_t)(i + 1); + if(*pv) + { + uint32_t pvi = (intptr_t)(*pv); + vm4ip[2] = -pvi; + } + else + { + *pv = (void *)(intptr_t)(i+1); #endif - fpos += fstWriterVarint(f, 0); - fpos += wrlen; - fstFwrite(scratchpnt, wrlen, 1, f); + fpos += fstWriterVarint(f, 0); + fpos += wrlen; + fstFwrite(scratchpnt, wrlen, 1, f); #ifndef FST_DYNAMIC_ALIAS_DISABLE - } + } #endif - } - } else { - /* this is extremely conservative: fastlz needs +5% for worst case, lz4 needs siz+(siz/255)+16 */ - if (((wrlen * 2) + 2) <= packmemlen) { - dmem = packmem; - } else { - free(packmem); - dmem = packmem = (unsigned char *)malloc(packmemlen = (wrlen * 2) + 2); - } + } - rc = (xc->fourpack) ? LZ4_compress((char *)scratchpnt, (char *)dmem, wrlen) - : fastlz_compress(scratchpnt, wrlen, dmem); - if (rc < destlen) { -#ifndef FST_DYNAMIC_ALIAS_DISABLE - PPvoid_t pv = JudyHSIns(&PJHSArray, dmem, rc, NULL); - if (*pv) { - uint32_t pvi = (intptr_t)(*pv); - vm4ip[2] = -pvi; - } else { - *pv = (void *)(intptr_t)(i + 1); -#endif - fpos += fstWriterVarint(f, wrlen); - fpos += rc; - fstFwrite(dmem, rc, 1, f); -#ifndef FST_DYNAMIC_ALIAS_DISABLE - } -#endif - } else { -#ifndef FST_DYNAMIC_ALIAS_DISABLE - PPvoid_t pv = JudyHSIns(&PJHSArray, scratchpnt, wrlen, NULL); - if (*pv) { - uint32_t pvi = (intptr_t)(*pv); - vm4ip[2] = -pvi; - } else { - *pv = (void *)(intptr_t)(i + 1); -#endif - fpos += fstWriterVarint(f, 0); - fpos += wrlen; - fstFwrite(scratchpnt, wrlen, 1, f); -#ifndef FST_DYNAMIC_ALIAS_DISABLE - } -#endif - } - } - } else { -#ifndef FST_DYNAMIC_ALIAS_DISABLE - PPvoid_t pv = JudyHSIns(&PJHSArray, scratchpnt, wrlen, NULL); - if (*pv) { - uint32_t pvi = (intptr_t)(*pv); - vm4ip[2] = -pvi; - } else { - *pv = (void *)(intptr_t)(i + 1); -#endif - fpos += fstWriterVarint(f, 0); - fpos += wrlen; - fstFwrite(scratchpnt, wrlen, 1, f); -#ifndef FST_DYNAMIC_ALIAS_DISABLE - } -#endif - } - - /* vm4ip[3] = 0; ...redundant with clearing below */ + /* vm4ip[3] = 0; ...redundant with clearing below */ #ifdef FST_DEBUG - cnt++; + cnt++; #endif + } } - } #ifndef FST_DYNAMIC_ALIAS_DISABLE - JudyHSFreeArray(&PJHSArray, NULL); +JudyHSFreeArray(&PJHSArray, NULL); #endif - free(packmem); - packmem = NULL; /* packmemlen = 0; */ /* scan-build */ +free(packmem); packmem = NULL; /* packmemlen = 0; */ /* scan-build */ - prevpos = 0; - zerocnt = 0; - free(scratchpad); - scratchpad = NULL; +prevpos = 0; zerocnt = 0; +free(scratchpad); scratchpad = NULL; - indxpos = ftello(f); - xc->secnum++; +indxpos = ftello(f); +xc->secnum++; #ifndef FST_DYNAMIC_ALIAS2_DISABLE - if (1) { +if(1) + { uint32_t prev_alias = 0; - for (i = 0; i < xc->maxhandle; i++) { - vm4ip = &(xc->valpos_mem[4 * i]); + for(i=0;imaxhandle;i++) + { + vm4ip = &(xc->valpos_mem[4*i]); - if (vm4ip[2]) { - if (zerocnt) { - fpos += fstWriterVarint(f, (zerocnt << 1)); - zerocnt = 0; - } + if(vm4ip[2]) + { + if(zerocnt) + { + fpos += fstWriterVarint(f, (zerocnt << 1)); + zerocnt = 0; + } - if (vm4ip[2] & 0x80000000) { - if (vm4ip[2] != prev_alias) { - fpos += fstWriterSVarint(f, (((int64_t)((int32_t)(prev_alias = vm4ip[2]))) << 1) | 1); - } else { - fpos += fstWriterSVarint(f, (0 << 1) | 1); - } - } else { - fpos += fstWriterSVarint(f, ((vm4ip[2] - prevpos) << 1) | 1); - prevpos = vm4ip[2]; + if(vm4ip[2] & 0x80000000) + { + if(vm4ip[2] != prev_alias) + { + int32_t t_i32 = ((int32_t)(prev_alias = vm4ip[2])); /* vm4ip is generic unsigned data */ + int64_t t_i64 = (int64_t)t_i32; /* convert to signed */ + uint64_t t_u64 = (uint64_t)t_i64; /* sign extend through 64b */ + + fpos += fstWriterSVarint(f, (int64_t)((t_u64 << 1) | 1)); /* all in this block was: fpos += fstWriterSVarint(f, (((int64_t)((int32_t)(prev_alias = vm4ip[2]))) << 1) | 1); */ + } + else + { + fpos += fstWriterSVarint(f, (0 << 1) | 1); + } + } + else + { + fpos += fstWriterSVarint(f, ((vm4ip[2] - prevpos) << 1) | 1); + prevpos = vm4ip[2]; + } + vm4ip[2] = 0; + vm4ip[3] = 0; /* clear out tchn idx */ + } + else + { + zerocnt++; + } } - vm4ip[2] = 0; - vm4ip[3] = 0; /* clear out tchn idx */ - } else { - zerocnt++; - } } - } else + else #endif - { - for (i = 0; i < xc->maxhandle; i++) { - vm4ip = &(xc->valpos_mem[4 * i]); + { + for(i=0;imaxhandle;i++) + { + vm4ip = &(xc->valpos_mem[4*i]); - if (vm4ip[2]) { - if (zerocnt) { - fpos += fstWriterVarint(f, (zerocnt << 1)); - zerocnt = 0; - } + if(vm4ip[2]) + { + if(zerocnt) + { + fpos += fstWriterVarint(f, (zerocnt << 1)); + zerocnt = 0; + } - if (vm4ip[2] & 0x80000000) { - fpos += fstWriterVarint(f, 0); /* signal, note that using a *signed* varint would be more efficient - than this byte escape! */ - fpos += fstWriterVarint(f, (-(int32_t)vm4ip[2])); - } else { - fpos += fstWriterVarint(f, ((vm4ip[2] - prevpos) << 1) | 1); - prevpos = vm4ip[2]; + if(vm4ip[2] & 0x80000000) + { + fpos += fstWriterVarint(f, 0); /* signal, note that using a *signed* varint would be more efficient than this byte escape! */ + fpos += fstWriterVarint(f, (-(int32_t)vm4ip[2])); + } + else + { + fpos += fstWriterVarint(f, ((vm4ip[2] - prevpos) << 1) | 1); + prevpos = vm4ip[2]; + } + vm4ip[2] = 0; + vm4ip[3] = 0; /* clear out tchn idx */ + } + else + { + zerocnt++; + } } - vm4ip[2] = 0; - vm4ip[3] = 0; /* clear out tchn idx */ - } else { - zerocnt++; - } } - } - if (zerocnt) { +if(zerocnt) + { /* fpos += */ fstWriterVarint(f, (zerocnt << 1)); /* scan-build */ - } + } #ifdef FST_DEBUG - fprintf(stderr, FST_APIMESS "value chains: %d\n", cnt); +fprintf(stderr, FST_APIMESS "value chains: %d\n", cnt); #endif - xc->vchg_mem[0] = '!'; - xc->vchg_siz = 1; +xc->vchg_mem[0] = '!'; +xc->vchg_siz = 1; - endpos = ftello(xc->handle); - fstWriterUint64(xc->handle, endpos - indxpos); /* write delta index position at very end of block */ +endpos = ftello(xc->handle); +fstWriterUint64(xc->handle, endpos-indxpos); /* write delta index position at very end of block */ - /*emit time changes for block */ - fflush(xc->tchn_handle); - tlen = ftello(xc->tchn_handle); - fstWriterFseeko(xc, xc->tchn_handle, 0, SEEK_SET); +/*emit time changes for block */ +fflush(xc->tchn_handle); +tlen = ftello(xc->tchn_handle); +fstWriterFseeko(xc, xc->tchn_handle, 0, SEEK_SET); - errno = 0; - fstWriterMmapSanity( - tmem = (unsigned char *)fstMmap(NULL, tlen, PROT_READ | PROT_WRITE, MAP_SHARED, fileno(xc->tchn_handle), 0), - __FILE__, __LINE__, "tmem"); - if (tmem) { +errno = 0; +fstWriterMmapSanity(tmem = (unsigned char *)fstMmap(NULL, tlen, PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->tchn_handle), 0), __FILE__, __LINE__, "tmem"); +if(tmem) + { unsigned long destlen = tlen; unsigned char *dmem = (unsigned char *)malloc(compressBound(destlen)); int rc = compress2(dmem, &destlen, tmem, tlen, 9); - if ((rc == Z_OK) && (((fst_off_t)destlen) < tlen)) { - fstFwrite(dmem, destlen, 1, xc->handle); - } else /* comparison between compressed / decompressed len tells if compressed */ - { - fstFwrite(tmem, tlen, 1, xc->handle); - destlen = tlen; - } + if((rc == Z_OK) && (((fst_off_t)destlen) < tlen)) + { + fstFwrite(dmem, destlen, 1, xc->handle); + } + else /* comparison between compressed / decompressed len tells if compressed */ + { + fstFwrite(tmem, tlen, 1, xc->handle); + destlen = tlen; + } free(dmem); fstMunmap(tmem, tlen); - fstWriterUint64(xc->handle, tlen); /* uncompressed */ - fstWriterUint64(xc->handle, destlen); /* compressed */ - fstWriterUint64(xc->handle, xc->tchn_cnt); /* number of time items */ - } + fstWriterUint64(xc->handle, tlen); /* uncompressed */ + fstWriterUint64(xc->handle, destlen); /* compressed */ + fstWriterUint64(xc->handle, xc->tchn_cnt); /* number of time items */ + } - xc->tchn_cnt = xc->tchn_idx = 0; - fstWriterFseeko(xc, xc->tchn_handle, 0, SEEK_SET); - fstFtruncate(fileno(xc->tchn_handle), 0); +xc->tchn_cnt = xc->tchn_idx = 0; +fstWriterFseeko(xc, xc->tchn_handle, 0, SEEK_SET); +fstFtruncate(fileno(xc->tchn_handle), 0); - /* write block trailer */ - endpos = ftello(xc->handle); - fstWriterFseeko(xc, xc->handle, xc->section_start, SEEK_SET); - fstWriterUint64(xc->handle, endpos - xc->section_start); /* write block length */ - fstWriterFseeko(xc, xc->handle, 8, SEEK_CUR); /* skip begin time */ - fstWriterUint64(xc->handle, xc->curtime); /* write end time for section */ - fstWriterUint64(xc->handle, unc_memreq); /* amount of buffer memory required in reader for full traversal */ - fflush(xc->handle); +/* write block trailer */ +endpos = ftello(xc->handle); +fstWriterFseeko(xc, xc->handle, xc->section_start, SEEK_SET); +fstWriterUint64(xc->handle, endpos - xc->section_start); /* write block length */ +fstWriterFseeko(xc, xc->handle, 8, SEEK_CUR); /* skip begin time */ +fstWriterUint64(xc->handle, xc->curtime); /* write end time for section */ +fstWriterUint64(xc->handle, unc_memreq); /* amount of buffer memory required in reader for full traversal */ +fflush(xc->handle); - fstWriterFseeko(xc, xc->handle, xc->section_start - 1, SEEK_SET); /* write out FST_BL_VCDATA over FST_BL_SKIP */ +fstWriterFseeko(xc, xc->handle, xc->section_start-1, SEEK_SET); /* write out FST_BL_VCDATA over FST_BL_SKIP */ #ifndef FST_DYNAMIC_ALIAS_DISABLE #ifndef FST_DYNAMIC_ALIAS2_DISABLE - fputc(FST_BL_VCDATA_DYN_ALIAS2, xc->handle); +fputc(FST_BL_VCDATA_DYN_ALIAS2, xc->handle); #else - fputc(FST_BL_VCDATA_DYN_ALIAS, xc->handle); +fputc(FST_BL_VCDATA_DYN_ALIAS, xc->handle); #endif #else - fputc(FST_BL_VCDATA, xc->handle); +fputc(FST_BL_VCDATA, xc->handle); #endif - fflush(xc->handle); +fflush(xc->handle); - fstWriterFseeko(xc, xc->handle, endpos, SEEK_SET); /* seek to end of file */ +fstWriterFseeko(xc, xc->handle, endpos, SEEK_SET); /* seek to end of file */ - xc2->section_header_truncpos = endpos; /* cache in case of need to truncate */ - if (xc->dump_size_limit) { - if (endpos >= ((fst_off_t)xc->dump_size_limit)) { - xc2->skip_writing_section_hdr = 1; - xc2->size_limit_locked = 1; - xc2->is_initial_time = 1; /* to trick emit value and emit time change */ +xc2->section_header_truncpos = endpos; /* cache in case of need to truncate */ +if(xc->dump_size_limit) + { + if(endpos >= ((fst_off_t)xc->dump_size_limit)) + { + xc2->skip_writing_section_hdr = 1; + xc2->size_limit_locked = 1; + xc2->is_initial_time = 1; /* to trick emit value and emit time change */ #ifdef FST_DEBUG - fprintf(stderr, FST_APIMESS "<< dump file size limit reached, stopping dumping >>\n"); + fprintf(stderr, FST_APIMESS "<< dump file size limit reached, stopping dumping >>\n"); #endif + } } - } - if (!xc2->skip_writing_section_hdr) { - fstWriterEmitSectionHeader(xc); /* emit next section header */ - } - fflush(xc->handle); +if(!xc2->skip_writing_section_hdr) + { + fstWriterEmitSectionHeader(xc); /* emit next section header */ + } +fflush(xc->handle); - xc->already_in_flush = 0; +xc->already_in_flush = 0; } + #ifdef FST_WRITER_PARALLEL static void *fstWriterFlushContextPrivate1(void *ctx) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - struct fstWriterContext *xc_parent; +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +struct fstWriterContext *xc_parent; - pthread_mutex_lock(&(xc->xc_parent->mutex)); - fstWriterFlushContextPrivate2(xc); +pthread_mutex_lock(&(xc->xc_parent->mutex)); +fstWriterFlushContextPrivate2(xc); #ifdef FST_REMOVE_DUPLICATE_VC - free(xc->curval_mem); +free(xc->curval_mem); #endif - free(xc->valpos_mem); - free(xc->vchg_mem); - tmpfile_close(&xc->tchn_handle, &xc->tchn_handle_nam); - xc_parent = xc->xc_parent; - free(xc); +free(xc->valpos_mem); +free(xc->vchg_mem); +tmpfile_close(&xc->tchn_handle, &xc->tchn_handle_nam); +xc_parent = xc->xc_parent; +free(xc); - xc_parent->in_pthread = 0; - pthread_mutex_unlock(&(xc_parent->mutex)); +xc_parent->in_pthread = 0; +pthread_mutex_unlock(&(xc_parent->mutex)); - return (NULL); +return(NULL); } + static void fstWriterFlushContextPrivate(void *ctx) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc->parallel_enabled) { +if(xc->parallel_enabled) + { struct fstWriterContext *xc2 = (struct fstWriterContext *)malloc(sizeof(struct fstWriterContext)); unsigned int i; @@ -1711,6 +1844,14 @@ static void fstWriterFlushContextPrivate(void *ctx) xc->xc_parent = xc; memcpy(xc2, xc, sizeof(struct fstWriterContext)); + if(sizeof(size_t) < sizeof(uint64_t)) + { + /* TALOS-2023-1777 for 32b overflow */ + uint64_t chk_64 = xc->maxhandle * 4 * sizeof(uint32_t); + size_t chk_32 = xc->maxhandle * 4 * sizeof(uint32_t); + if(chk_64 != chk_32) chk_report_abort("TALOS-2023-1777"); + } + xc2->valpos_mem = (uint32_t *)malloc(xc->maxhandle * 4 * sizeof(uint32_t)); memcpy(xc2->valpos_mem, xc->valpos_mem, xc->maxhandle * 4 * sizeof(uint32_t)); @@ -1724,11 +1865,12 @@ static void fstWriterFlushContextPrivate(void *ctx) xc->vchg_mem[0] = '!'; xc->vchg_siz = 1; - for (i = 0; i < xc->maxhandle; i++) { - uint32_t *vm4ip = &(xc->valpos_mem[4 * i]); - vm4ip[2] = 0; /* zero out offset val */ - vm4ip[3] = 0; /* zero out last time change val */ - } + for(i=0;imaxhandle;i++) + { + uint32_t *vm4ip = &(xc->valpos_mem[4*i]); + vm4ip[2] = 0; /* zero out offset val */ + vm4ip[3] = 0; /* zero out last time change val */ + } xc->tchn_cnt = xc->tchn_idx = 0; xc->tchn_handle = tmpfile_open(&xc->tchn_handle_nam); /* child thread will deallocate file/name */ @@ -1738,265 +1880,288 @@ static void fstWriterFlushContextPrivate(void *ctx) xc->section_header_only = 0; xc->secnum++; - while (xc->in_pthread) { - pthread_mutex_lock(&xc->mutex); - pthread_mutex_unlock(&xc->mutex); - }; + while (xc->in_pthread) + { + pthread_mutex_lock(&xc->mutex); + pthread_mutex_unlock(&xc->mutex); + }; pthread_mutex_lock(&xc->mutex); - xc->in_pthread = 1; + xc->in_pthread = 1; pthread_mutex_unlock(&xc->mutex); pthread_create(&xc->thread, &xc->thread_attr, fstWriterFlushContextPrivate1, xc2); - } else { - if (xc->parallel_was_enabled) /* conservatively block */ - { - pthread_mutex_lock(&xc->mutex); - pthread_mutex_unlock(&xc->mutex); } + else + { + if(xc->parallel_was_enabled) /* conservatively block */ + { + pthread_mutex_lock(&xc->mutex); + pthread_mutex_unlock(&xc->mutex); + } xc->xc_parent = xc; fstWriterFlushContextPrivate2(xc); - } + } } #endif + /* * queues up a flush context operation */ void fstWriterFlushContext(void *ctx) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { - if (xc->tchn_idx > 1) { - xc->flush_context_pending = 1; +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc) + { + if(xc->tchn_idx > 1) + { + xc->flush_context_pending = 1; + } } - } } + /* * close out FST file */ void fstWriterClose(void *ctx) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; #ifdef FST_WRITER_PARALLEL - if (xc) { +if(xc) + { pthread_mutex_lock(&xc->mutex); pthread_mutex_unlock(&xc->mutex); - } + } #endif - if (xc && !xc->already_in_close && !xc->already_in_flush) { +if(xc && !xc->already_in_close && !xc->already_in_flush) + { unsigned char *tmem = NULL; fst_off_t fixup_offs, tlen, hlen; xc->already_in_close = 1; /* never need to zero this out as it is freed at bottom */ - if (xc->section_header_only && xc->section_header_truncpos && (xc->vchg_siz <= 1) && (!xc->is_initial_time)) { - fstFtruncate(fileno(xc->handle), xc->section_header_truncpos); - fstWriterFseeko(xc, xc->handle, xc->section_header_truncpos, SEEK_SET); - xc->section_header_only = 0; - } else { - xc->skip_writing_section_hdr = 1; - if (!xc->size_limit_locked) { - if (FST_UNLIKELY(xc->is_initial_time)) /* simulation time never advanced so mock up the changes as time - zero ones */ + if(xc->section_header_only && xc->section_header_truncpos && (xc->vchg_siz <= 1) && (!xc->is_initial_time)) { - fstHandle dupe_idx; - - fstWriterEmitTimeChange(xc, 0); /* emit some time change just to have one */ - for (dupe_idx = 0; dupe_idx < xc->maxhandle; dupe_idx++) /* now clone the values */ - { - fstWriterEmitValueChange(xc, dupe_idx + 1, xc->curval_mem + xc->valpos_mem[4 * dupe_idx]); - } + fstFtruncate(fileno(xc->handle), xc->section_header_truncpos); + fstWriterFseeko(xc, xc->handle, xc->section_header_truncpos, SEEK_SET); + xc->section_header_only = 0; } - fstWriterFlushContextPrivate(xc); -#ifdef FST_WRITER_PARALLEL - pthread_mutex_lock(&xc->mutex); - pthread_mutex_unlock(&xc->mutex); + else + { + xc->skip_writing_section_hdr = 1; + if(!xc->size_limit_locked) + { + if(FST_UNLIKELY(xc->is_initial_time)) /* simulation time never advanced so mock up the changes as time zero ones */ + { + fstHandle dupe_idx; - while (xc->in_pthread) { - pthread_mutex_lock(&xc->mutex); - pthread_mutex_unlock(&xc->mutex); - }; + fstWriterEmitTimeChange(xc, 0); /* emit some time change just to have one */ + for(dupe_idx = 0; dupe_idx < xc->maxhandle; dupe_idx++) /* now clone the values */ + { + fstWriterEmitValueChange(xc, dupe_idx+1, xc->curval_mem + xc->valpos_mem[4*dupe_idx]); + } + } + fstWriterFlushContextPrivate(xc); +#ifdef FST_WRITER_PARALLEL + pthread_mutex_lock(&xc->mutex); + pthread_mutex_unlock(&xc->mutex); + + while (xc->in_pthread) + { + pthread_mutex_lock(&xc->mutex); + pthread_mutex_unlock(&xc->mutex); + }; #endif - } - } + } + } fstDestroyMmaps(xc, 1); - if (xc->outval_mem) { - free(xc->outval_mem); - xc->outval_mem = NULL; - xc->outval_alloc_siz = 0; - } + if(xc->outval_mem) + { + free(xc->outval_mem); xc->outval_mem = NULL; + xc->outval_alloc_siz = 0; + } /* write out geom section */ fflush(xc->geom_handle); tlen = ftello(xc->geom_handle); - errno = 0; - if (tlen) { - fstWriterMmapSanity(tmem = (unsigned char *)fstMmap(NULL, tlen, PROT_READ | PROT_WRITE, MAP_SHARED, - fileno(xc->geom_handle), 0), - __FILE__, __LINE__, "tmem"); - } + errno = 0; + if(tlen) + { + fstWriterMmapSanity(tmem = (unsigned char *)fstMmap(NULL, tlen, PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->geom_handle), 0), __FILE__, __LINE__, "tmem"); + } - if (tmem) { - unsigned long destlen = tlen; - unsigned char *dmem = (unsigned char *)malloc(compressBound(destlen)); - int rc = compress2(dmem, &destlen, tmem, tlen, 9); - - if ((rc != Z_OK) || (((fst_off_t)destlen) > tlen)) { - destlen = tlen; - } - - fixup_offs = ftello(xc->handle); - fputc(FST_BL_SKIP, xc->handle); /* temporary tag */ - fstWriterUint64(xc->handle, destlen + 24); /* section length */ - fstWriterUint64(xc->handle, tlen); /* uncompressed */ - /* compressed len is section length - 24 */ - fstWriterUint64(xc->handle, xc->maxhandle); /* maxhandle */ - fstFwrite((((fst_off_t)destlen) != tlen) ? dmem : tmem, destlen, 1, xc->handle); - fflush(xc->handle); - - fstWriterFseeko(xc, xc->handle, fixup_offs, SEEK_SET); - fputc(FST_BL_GEOM, xc->handle); /* actual tag */ - - fstWriterFseeko(xc, xc->handle, 0, SEEK_END); /* move file pointer to end for any section adds */ - fflush(xc->handle); - - free(dmem); - fstMunmap(tmem, tlen); - } - - if (xc->num_blackouts) { - uint64_t cur_bl = 0; - fst_off_t bpos, eos; - uint32_t i; - - fixup_offs = ftello(xc->handle); - fputc(FST_BL_SKIP, xc->handle); /* temporary tag */ - bpos = fixup_offs + 1; - fstWriterUint64(xc->handle, 0); /* section length */ - fstWriterVarint(xc->handle, xc->num_blackouts); - - for (i = 0; i < xc->num_blackouts; i++) { - fputc(xc->blackout_head->active, xc->handle); - fstWriterVarint(xc->handle, xc->blackout_head->tim - cur_bl); - cur_bl = xc->blackout_head->tim; - xc->blackout_curr = xc->blackout_head->next; - free(xc->blackout_head); - xc->blackout_head = xc->blackout_curr; - } - - eos = ftello(xc->handle); - fstWriterFseeko(xc, xc->handle, bpos, SEEK_SET); - fstWriterUint64(xc->handle, eos - bpos); - fflush(xc->handle); - - fstWriterFseeko(xc, xc->handle, fixup_offs, SEEK_SET); - fputc(FST_BL_BLACKOUT, xc->handle); /* actual tag */ - - fstWriterFseeko(xc, xc->handle, 0, SEEK_END); /* move file pointer to end for any section adds */ - fflush(xc->handle); - } - - if (xc->compress_hier) { - fst_off_t hl, eos; - gzFile zhandle; - int zfd; - int fourpack_duo = 0; -#ifndef __MINGW32__ - auto fnam_size = strlen(xc->filename) + 5 + 1; - char *fnam = (char *)malloc(fnam_size); -#endif - - fixup_offs = ftello(xc->handle); - fputc(FST_BL_SKIP, xc->handle); /* temporary tag */ - hlen = ftello(xc->handle); - fstWriterUint64(xc->handle, 0); /* section length */ - fstWriterUint64(xc->handle, xc->hier_file_len); /* uncompressed length */ - - if (!xc->fourpack) { - unsigned char *mem = (unsigned char *)malloc(FST_GZIO_LEN); - zfd = dup(fileno(xc->handle)); - fflush(xc->handle); - zhandle = gzdopen(zfd, "wb4"); - if (zhandle) { - fstWriterFseeko(xc, xc->hier_handle, 0, SEEK_SET); - for (hl = 0; hl < xc->hier_file_len; hl += FST_GZIO_LEN) { - unsigned len = - ((xc->hier_file_len - hl) > FST_GZIO_LEN) ? FST_GZIO_LEN : (xc->hier_file_len - hl); - fstFread(mem, len, 1, xc->hier_handle); - gzwrite(zhandle, mem, len); - } - gzclose(zhandle); - } else { - close(zfd); - } - free(mem); - } else { - int lz4_maxlen; - unsigned char *mem; - unsigned char *hmem = NULL; - int packed_len; - - fflush(xc->handle); - - lz4_maxlen = LZ4_compressBound(xc->hier_file_len); - mem = (unsigned char *)malloc(lz4_maxlen); - errno = 0; - if (xc->hier_file_len) { - fstWriterMmapSanity(hmem = (unsigned char *)fstMmap(NULL, xc->hier_file_len, PROT_READ | PROT_WRITE, - MAP_SHARED, fileno(xc->hier_handle), 0), - __FILE__, __LINE__, "hmem"); - } - packed_len = LZ4_compress((char *)hmem, (char *)mem, xc->hier_file_len); - fstMunmap(hmem, xc->hier_file_len); - - fourpack_duo = - (!xc->repack_on_close) && - (xc->hier_file_len > FST_HDR_FOURPACK_DUO_SIZE); /* double pack when hierarchy is large */ - - if (fourpack_duo) /* double packing with LZ4 is faster than gzip */ + if(tmem) { - unsigned char *mem_duo; - int lz4_maxlen_duo; - int packed_len_duo; + unsigned long destlen = tlen; + unsigned char *dmem = (unsigned char *)malloc(compressBound(destlen)); + int rc = compress2(dmem, &destlen, tmem, tlen, 9); - lz4_maxlen_duo = LZ4_compressBound(packed_len); - mem_duo = (unsigned char *)malloc(lz4_maxlen_duo); - packed_len_duo = LZ4_compress((char *)mem, (char *)mem_duo, packed_len); + if((rc != Z_OK) || (((fst_off_t)destlen) > tlen)) + { + destlen = tlen; + } - fstWriterVarint(xc->handle, packed_len); /* 1st round compressed length */ - fstFwrite(mem_duo, packed_len_duo, 1, xc->handle); - free(mem_duo); - } else { - fstFwrite(mem, packed_len, 1, xc->handle); + fixup_offs = ftello(xc->handle); + fputc(FST_BL_SKIP, xc->handle); /* temporary tag */ + fstWriterUint64(xc->handle, destlen + 24); /* section length */ + fstWriterUint64(xc->handle, tlen); /* uncompressed */ + /* compressed len is section length - 24 */ + fstWriterUint64(xc->handle, xc->maxhandle); /* maxhandle */ + fstFwrite((((fst_off_t)destlen) != tlen) ? dmem : tmem, destlen, 1, xc->handle); + fflush(xc->handle); + + fstWriterFseeko(xc, xc->handle, fixup_offs, SEEK_SET); + fputc(FST_BL_GEOM, xc->handle); /* actual tag */ + + fstWriterFseeko(xc, xc->handle, 0, SEEK_END); /* move file pointer to end for any section adds */ + fflush(xc->handle); + + free(dmem); + fstMunmap(tmem, tlen); } - free(mem); - } + if(xc->num_blackouts) + { + uint64_t cur_bl = 0; + fst_off_t bpos, eos; + uint32_t i; - fstWriterFseeko(xc, xc->handle, 0, SEEK_END); - eos = ftello(xc->handle); - fstWriterFseeko(xc, xc->handle, hlen, SEEK_SET); - fstWriterUint64(xc->handle, eos - hlen); - fflush(xc->handle); + fixup_offs = ftello(xc->handle); + fputc(FST_BL_SKIP, xc->handle); /* temporary tag */ + bpos = fixup_offs + 1; + fstWriterUint64(xc->handle, 0); /* section length */ + fstWriterVarint(xc->handle, xc->num_blackouts); - fstWriterFseeko(xc, xc->handle, fixup_offs, SEEK_SET); - fputc(xc->fourpack ? (fourpack_duo ? FST_BL_HIER_LZ4DUO : FST_BL_HIER_LZ4) : FST_BL_HIER, - xc->handle); /* actual tag now also == compression type */ + for(i=0;inum_blackouts;i++) + { + fputc(xc->blackout_head->active, xc->handle); + fstWriterVarint(xc->handle, xc->blackout_head->tim - cur_bl); + cur_bl = xc->blackout_head->tim; + xc->blackout_curr = xc->blackout_head->next; + free(xc->blackout_head); + xc->blackout_head = xc->blackout_curr; + } - fstWriterFseeko(xc, xc->handle, 0, SEEK_END); /* move file pointer to end for any section adds */ - fflush(xc->handle); + eos = ftello(xc->handle); + fstWriterFseeko(xc, xc->handle, bpos, SEEK_SET); + fstWriterUint64(xc->handle, eos - bpos); + fflush(xc->handle); + + fstWriterFseeko(xc, xc->handle, fixup_offs, SEEK_SET); + fputc(FST_BL_BLACKOUT, xc->handle); /* actual tag */ + + fstWriterFseeko(xc, xc->handle, 0, SEEK_END); /* move file pointer to end for any section adds */ + fflush(xc->handle); + } + + if(xc->compress_hier) + { + fst_off_t hl, eos; + gzFile zhandle; + int zfd; + int fourpack_duo = 0; +#ifndef __MINGW32__ + int fnam_len = strlen(xc->filename) + 5 + 1; + char *fnam = (char *)malloc(fnam_len); +#endif + + fixup_offs = ftello(xc->handle); + fputc(FST_BL_SKIP, xc->handle); /* temporary tag */ + hlen = ftello(xc->handle); + fstWriterUint64(xc->handle, 0); /* section length */ + fstWriterUint64(xc->handle, xc->hier_file_len); /* uncompressed length */ + + if(!xc->fourpack) + { + unsigned char *mem = (unsigned char *)malloc(FST_GZIO_LEN); + zfd = dup(fileno(xc->handle)); + fflush(xc->handle); + zhandle = gzdopen(zfd, "wb4"); + if(zhandle) + { + fstWriterFseeko(xc, xc->hier_handle, 0, SEEK_SET); + for(hl = 0; hl < xc->hier_file_len; hl += FST_GZIO_LEN) + { + unsigned len = ((xc->hier_file_len - hl) > FST_GZIO_LEN) ? FST_GZIO_LEN : (xc->hier_file_len - hl); + fstFread(mem, len, 1, xc->hier_handle); + gzwrite(zhandle, mem, len); + } + gzclose(zhandle); + } + else + { + close(zfd); + } + free(mem); + } + else + { + int lz4_maxlen; + unsigned char *mem; + unsigned char *hmem = NULL; + int packed_len; + + fflush(xc->handle); + + lz4_maxlen = LZ4_compressBound(xc->hier_file_len); + mem = (unsigned char *)malloc(lz4_maxlen); + errno = 0; + if(xc->hier_file_len) + { + fstWriterMmapSanity(hmem = (unsigned char *)fstMmap(NULL, xc->hier_file_len, PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->hier_handle), 0), __FILE__, __LINE__, "hmem"); + } + packed_len = LZ4_compress_default((char *)hmem, (char *)mem, xc->hier_file_len, lz4_maxlen); + fstMunmap(hmem, xc->hier_file_len); + + fourpack_duo = (!xc->repack_on_close) && (xc->hier_file_len > FST_HDR_FOURPACK_DUO_SIZE); /* double pack when hierarchy is large */ + + if(fourpack_duo) /* double packing with LZ4 is faster than gzip */ + { + unsigned char *mem_duo; + int lz4_maxlen_duo; + int packed_len_duo; + + lz4_maxlen_duo = LZ4_compressBound(packed_len); + mem_duo = (unsigned char *)malloc(lz4_maxlen_duo); + packed_len_duo = LZ4_compress_default((char *)mem, (char *)mem_duo, packed_len, lz4_maxlen_duo); + + fstWriterVarint(xc->handle, packed_len); /* 1st round compressed length */ + fstFwrite(mem_duo, packed_len_duo, 1, xc->handle); + free(mem_duo); + } + else + { + fstFwrite(mem, packed_len, 1, xc->handle); + } + + free(mem); + } + + fstWriterFseeko(xc, xc->handle, 0, SEEK_END); + eos = ftello(xc->handle); + fstWriterFseeko(xc, xc->handle, hlen, SEEK_SET); + fstWriterUint64(xc->handle, eos - hlen); + fflush(xc->handle); + + fstWriterFseeko(xc, xc->handle, fixup_offs, SEEK_SET); + fputc(xc->fourpack ? + ( fourpack_duo ? FST_BL_HIER_LZ4DUO : FST_BL_HIER_LZ4) : + FST_BL_HIER, xc->handle); /* actual tag now also == compression type */ + + fstWriterFseeko(xc, xc->handle, 0, SEEK_END); /* move file pointer to end for any section adds */ + fflush(xc->handle); #ifndef __MINGW32__ - snprintf(fnam, fnam_size, "%s.hier", xc->filename); - unlink(fnam); - free(fnam); + snprintf(fnam, fnam_len, "%s.hier", xc->filename); + unlink(fnam); + free(fnam); #endif - } + } /* finalize out header */ fstWriterFseeko(xc, xc->handle, FST_HDR_OFFS_START_TIME, SEEK_SET); @@ -2010,87 +2175,92 @@ void fstWriterClose(void *ctx) fflush(xc->handle); tmpfile_close(&xc->tchn_handle, &xc->tchn_handle_nam); - free(xc->vchg_mem); - xc->vchg_mem = NULL; + free(xc->vchg_mem); xc->vchg_mem = NULL; tmpfile_close(&xc->curval_handle, &xc->curval_handle_nam); tmpfile_close(&xc->valpos_handle, &xc->valpos_handle_nam); tmpfile_close(&xc->geom_handle, &xc->geom_handle_nam); - if (xc->hier_handle) { - fclose(xc->hier_handle); - xc->hier_handle = NULL; - } - if (xc->handle) { - if (xc->repack_on_close) { - FILE *fp; - fst_off_t offpnt, uclen; - int flen = strlen(xc->filename); - char *hf = (char *)calloc(1, flen + 5); + if(xc->hier_handle) { fclose(xc->hier_handle); xc->hier_handle = NULL; } + if(xc->handle) + { + if(xc->repack_on_close) + { + FILE *fp; + fst_off_t offpnt, uclen; + int flen = strlen(xc->filename); + char *hf = (char *)calloc(1, flen + 5); - strcpy(hf, xc->filename); - strcpy(hf + flen, ".pak"); - fp = fopen(hf, "wb"); + strcpy(hf, xc->filename); + strcpy(hf+flen, ".pak"); + fp = fopen(hf, "wb"); - if (fp) { - gzFile dsth; - int zfd; - char gz_membuf[FST_GZIO_LEN]; + if(fp) + { + gzFile dsth; + int zfd; + char gz_membuf[FST_GZIO_LEN]; - fstWriterFseeko(xc, xc->handle, 0, SEEK_END); - uclen = ftello(xc->handle); + fstWriterFseeko(xc, xc->handle, 0, SEEK_END); + uclen = ftello(xc->handle); - fputc(FST_BL_ZWRAPPER, fp); - fstWriterUint64(fp, 0); - fstWriterUint64(fp, uclen); - fflush(fp); + fputc(FST_BL_ZWRAPPER, fp); + fstWriterUint64(fp, 0); + fstWriterUint64(fp, uclen); + fflush(fp); - fstWriterFseeko(xc, xc->handle, 0, SEEK_SET); - zfd = dup(fileno(fp)); - dsth = gzdopen(zfd, "wb4"); - if (dsth) { - for (offpnt = 0; offpnt < uclen; offpnt += FST_GZIO_LEN) { - size_t this_len = ((uclen - offpnt) > FST_GZIO_LEN) ? FST_GZIO_LEN : (uclen - offpnt); - fstFread(gz_membuf, this_len, 1, xc->handle); - gzwrite(dsth, gz_membuf, this_len); + fstWriterFseeko(xc, xc->handle, 0, SEEK_SET); + zfd = dup(fileno(fp)); + dsth = gzdopen(zfd, "wb4"); + if(dsth) + { + for(offpnt = 0; offpnt < uclen; offpnt += FST_GZIO_LEN) + { + size_t this_len = ((uclen - offpnt) > FST_GZIO_LEN) ? FST_GZIO_LEN : (uclen - offpnt); + fstFread(gz_membuf, this_len, 1, xc->handle); + gzwrite(dsth, gz_membuf, this_len); + } + gzclose(dsth); + } + else + { + close(zfd); + } + fstWriterFseeko(xc, fp, 0, SEEK_END); + offpnt = ftello(fp); + fstWriterFseeko(xc, fp, 1, SEEK_SET); + fstWriterUint64(fp, offpnt - 1); + fclose(fp); + fclose(xc->handle); xc->handle = NULL; + + unlink(xc->filename); + rename(hf, xc->filename); + } + else + { + xc->repack_on_close = 0; + fclose(xc->handle); xc->handle = NULL; + } + + free(hf); + } + else + { + fclose(xc->handle); xc->handle = NULL; } - gzclose(dsth); - } else { - close(zfd); - } - fstWriterFseeko(xc, fp, 0, SEEK_END); - offpnt = ftello(fp); - fstWriterFseeko(xc, fp, 1, SEEK_SET); - fstWriterUint64(fp, offpnt - 1); - fclose(fp); - fclose(xc->handle); - xc->handle = NULL; - - unlink(xc->filename); - rename(hf, xc->filename); - } else { - xc->repack_on_close = 0; - fclose(xc->handle); - xc->handle = NULL; } - free(hf); - } else { - fclose(xc->handle); - xc->handle = NULL; - } - } - #ifdef __MINGW32__ { - int flen = strlen(xc->filename); - char *hf = (char *)calloc(1, flen + 6); - strcpy(hf, xc->filename); + int flen = strlen(xc->filename); + char *hf = (char *)calloc(1, flen + 6); + strcpy(hf, xc->filename); - if (xc->compress_hier) { + if(xc->compress_hier) + { strcpy(hf + flen, ".hier"); unlink(hf); /* no longer needed as a section now exists for this */ - } + } - free(hf); + free(hf); } #endif @@ -2099,26 +2269,28 @@ void fstWriterClose(void *ctx) pthread_attr_destroy(&xc->thread_attr); #endif - if (xc->path_array) { + if(xc->path_array) + { #ifndef _WAVE_HAVE_JUDY - const uint32_t hashmask = FST_PATH_HASHMASK; + const uint32_t hashmask = FST_PATH_HASHMASK; #endif - JudyHSFreeArray(&(xc->path_array), NULL); - } + JudyHSFreeArray(&(xc->path_array), NULL); + } - free(xc->filename); - xc->filename = NULL; + free(xc->filename); xc->filename = NULL; free(xc); - } + } } + /* * functions to set miscellaneous header/block information */ void fstWriterSetDate(void *ctx, const char *dat) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc) + { char s[FST_HDR_DATE_SIZE]; fst_off_t fpos = ftello(xc->handle); int len = strlen(dat); @@ -2129,13 +2301,15 @@ void fstWriterSetDate(void *ctx, const char *dat) fstFwrite(s, FST_HDR_DATE_SIZE, 1, xc->handle); fflush(xc->handle); fstWriterFseeko(xc, xc->handle, fpos, SEEK_SET); - } + } } + void fstWriterSetVersion(void *ctx, const char *vers) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc && vers) { +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc && vers) + { char s[FST_HDR_SIM_VERSION_SIZE]; fst_off_t fpos = ftello(xc->handle); int len = strlen(vers); @@ -2146,867 +2320,972 @@ void fstWriterSetVersion(void *ctx, const char *vers) fstFwrite(s, FST_HDR_SIM_VERSION_SIZE, 1, xc->handle); fflush(xc->handle); fstWriterFseeko(xc, xc->handle, fpos, SEEK_SET); - } + } } + void fstWriterSetFileType(void *ctx, enum fstFileType filetype) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { - if (/*(filetype >= FST_FT_MIN) &&*/ (filetype <= FST_FT_MAX)) { - fst_off_t fpos = ftello(xc->handle); +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc) + { + if(/*(filetype >= FST_FT_MIN) &&*/ (filetype <= FST_FT_MAX)) + { + fst_off_t fpos = ftello(xc->handle); - xc->filetype = filetype; + xc->filetype = filetype; - fstWriterFseeko(xc, xc->handle, FST_HDR_OFFS_FILETYPE, SEEK_SET); - fputc(xc->filetype, xc->handle); - fflush(xc->handle); - fstWriterFseeko(xc, xc->handle, fpos, SEEK_SET); + fstWriterFseeko(xc, xc->handle, FST_HDR_OFFS_FILETYPE, SEEK_SET); + fputc(xc->filetype, xc->handle); + fflush(xc->handle); + fstWriterFseeko(xc, xc->handle, fpos, SEEK_SET); + } } - } } + static void fstWriterSetAttrDoubleArgGeneric(void *ctx, int typ, uint64_t arg1, uint64_t arg2) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc) + { unsigned char buf[11]; /* ceil(64/7) = 10 + null term */ unsigned char *pnt = fstCopyVarint64ToRight(buf, arg1); - if (arg1) { - *pnt = 0; /* this converts any *nonzero* arg1 when made a varint into a null-term string */ - } + if(arg1) + { + *pnt = 0; /* this converts any *nonzero* arg1 when made a varint into a null-term string */ + } fstWriterSetAttrBegin(xc, FST_AT_MISC, typ, (char *)buf, arg2); - } + } } + static void fstWriterSetAttrGeneric(void *ctx, const char *comm, int typ, uint64_t arg) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc && comm) { +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc && comm) + { char *s = strdup(comm); char *sf = s; - while (*s) { - if ((*s == '\n') || (*s == '\r')) - *s = ' '; - s++; - } + while(*s) + { + if((*s == '\n') || (*s == '\r')) *s = ' '; + s++; + } fstWriterSetAttrBegin(xc, FST_AT_MISC, typ, sf, arg); free(sf); - } + } } + static void fstWriterSetSourceStem_2(void *ctx, const char *path, unsigned int line, unsigned int use_realpath, int typ) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc && path && path[0]) { +if(xc && path && path[0]) + { uint64_t sidx = 0; int slen = strlen(path); #ifndef _WAVE_HAVE_JUDY const uint32_t hashmask = FST_PATH_HASHMASK; const unsigned char *path2 = (const unsigned char *)path; - PPvoid_t pv; + PPvoid_t pv; #else char *path2 = (char *)alloca(slen + 1); /* judy lacks const qualifier in its JudyHSIns definition */ - PPvoid_t pv; + PPvoid_t pv; strcpy(path2, path); #endif pv = JudyHSIns(&(xc->path_array), path2, slen, NULL); - if (*pv) { - sidx = (intptr_t)(*pv); - } else { - char *rp = NULL; + if(*pv) + { + sidx = (intptr_t)(*pv); + } + else + { + char *rp = NULL; - sidx = ++xc->path_array_count; - *pv = (void *)(intptr_t)(xc->path_array_count); + sidx = ++xc->path_array_count; + *pv = (void *)(intptr_t)(xc->path_array_count); - if (use_realpath) { - rp = fstRealpath( + if(use_realpath) + { + rp = fstRealpath( +#ifndef _WAVE_HAVE_JUDY + (const char *) +#endif + path2, NULL); + } + + fstWriterSetAttrGeneric(xc, rp ? rp : #ifndef _WAVE_HAVE_JUDY (const char *) #endif - path2, - NULL); - } + path2, FST_MT_PATHNAME, sidx); - fstWriterSetAttrGeneric(xc, - rp ? rp : -#ifndef _WAVE_HAVE_JUDY - (const char *) -#endif - path2, - FST_MT_PATHNAME, sidx); - - if (rp) { - free(rp); - } - } + if(rp) + { + free(rp); + } + } fstWriterSetAttrDoubleArgGeneric(xc, typ, sidx, line); - } + } } + void fstWriterSetSourceStem(void *ctx, const char *path, unsigned int line, unsigned int use_realpath) { - fstWriterSetSourceStem_2(ctx, path, line, use_realpath, FST_MT_SOURCESTEM); +fstWriterSetSourceStem_2(ctx, path, line, use_realpath, FST_MT_SOURCESTEM); } + void fstWriterSetSourceInstantiationStem(void *ctx, const char *path, unsigned int line, unsigned int use_realpath) { - fstWriterSetSourceStem_2(ctx, path, line, use_realpath, FST_MT_SOURCEISTEM); +fstWriterSetSourceStem_2(ctx, path, line, use_realpath, FST_MT_SOURCEISTEM); } -void fstWriterSetComment(void *ctx, const char *comm) { fstWriterSetAttrGeneric(ctx, comm, FST_MT_COMMENT, 0); } -void fstWriterSetValueList(void *ctx, const char *vl) { fstWriterSetAttrGeneric(ctx, vl, FST_MT_VALUELIST, 0); } +void fstWriterSetComment(void *ctx, const char *comm) +{ +fstWriterSetAttrGeneric(ctx, comm, FST_MT_COMMENT, 0); +} + + +void fstWriterSetValueList(void *ctx, const char *vl) +{ +fstWriterSetAttrGeneric(ctx, vl, FST_MT_VALUELIST, 0); +} + + +void fstWriterSetEnvVar(void *ctx, const char *envvar) +{ +fstWriterSetAttrGeneric(ctx, envvar, FST_MT_ENVVAR, 0); +} -void fstWriterSetEnvVar(void *ctx, const char *envvar) { fstWriterSetAttrGeneric(ctx, envvar, FST_MT_ENVVAR, 0); } void fstWriterSetTimescale(void *ctx, int ts) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc) + { fst_off_t fpos = ftello(xc->handle); fstWriterFseeko(xc, xc->handle, FST_HDR_OFFS_TIMESCALE, SEEK_SET); fputc(ts & 255, xc->handle); fflush(xc->handle); fstWriterFseeko(xc, xc->handle, fpos, SEEK_SET); - } + } } + void fstWriterSetTimescaleFromString(void *ctx, const char *s) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc && s) { +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc && s) + { int mat = 0; int seconds_exp = -9; int tv = atoi(s); const char *pnt = s; - while (*pnt) { - switch (*pnt) { - case 'm': - seconds_exp = -3; - mat = 1; - break; - case 'u': - seconds_exp = -6; - mat = 1; - break; - case 'n': - seconds_exp = -9; - mat = 1; - break; - case 'p': - seconds_exp = -12; - mat = 1; - break; - case 'f': - seconds_exp = -15; - mat = 1; - break; - case 'a': - seconds_exp = -18; - mat = 1; - break; - case 'z': - seconds_exp = -21; - mat = 1; - break; - case 's': - seconds_exp = 0; - mat = 1; - break; - default: - break; - } + while(*pnt) + { + switch(*pnt) + { + case 'm': seconds_exp = -3; mat = 1; break; + case 'u': seconds_exp = -6; mat = 1; break; + case 'n': seconds_exp = -9; mat = 1; break; + case 'p': seconds_exp = -12; mat = 1; break; + case 'f': seconds_exp = -15; mat = 1; break; + case 'a': seconds_exp = -18; mat = 1; break; + case 'z': seconds_exp = -21; mat = 1; break; + case 's': seconds_exp = 0; mat = 1; break; + default: break; + } - if (mat) - break; - pnt++; - } + if(mat) break; + pnt++; + } - if (tv == 10) { - seconds_exp++; - } else if (tv == 100) { - seconds_exp += 2; - } + if(tv == 10) + { + seconds_exp++; + } + else + if(tv == 100) + { + seconds_exp+=2; + } fstWriterSetTimescale(ctx, seconds_exp); - } + } } + void fstWriterSetTimezero(void *ctx, int64_t tim) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc) + { fst_off_t fpos = ftello(xc->handle); fstWriterFseeko(xc, xc->handle, FST_HDR_OFFS_TIMEZERO, SEEK_SET); fstWriterUint64(xc->handle, (xc->timezero = tim)); fflush(xc->handle); fstWriterFseeko(xc, xc->handle, fpos, SEEK_SET); - } + } } + void fstWriterSetPackType(void *ctx, enum fstWriterPackType typ) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { - xc->fastpack = (typ != FST_WR_PT_ZLIB); - xc->fourpack = (typ == FST_WR_PT_LZ4); - } +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc) + { + xc->fastpack = (typ != FST_WR_PT_ZLIB); + xc->fourpack = (typ == FST_WR_PT_LZ4); + } } + void fstWriterSetRepackOnClose(void *ctx, int enable) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc) + { xc->repack_on_close = (enable != 0); - } + } } + void fstWriterSetParallelMode(void *ctx, int enable) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc) + { xc->parallel_was_enabled |= xc->parallel_enabled; /* make sticky */ xc->parallel_enabled = (enable != 0); #ifndef FST_WRITER_PARALLEL - if (xc->parallel_enabled) { - fprintf(stderr, FST_APIMESS - "fstWriterSetParallelMode(), FST_WRITER_PARALLEL not enabled during compile, exiting.\n"); - exit(255); - } + if(xc->parallel_enabled) + { + fprintf(stderr, FST_APIMESS "fstWriterSetParallelMode(), FST_WRITER_PARALLEL not enabled during compile, exiting.\n"); + exit(255); + } #endif - } + } } + void fstWriterSetDumpSizeLimit(void *ctx, uint64_t numbytes) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc) + { xc->dump_size_limit = numbytes; - } + } } + int fstWriterGetDumpSizeLimitReached(void *ctx) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { - return (xc->size_limit_locked != 0); - } +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc) + { + return(xc->size_limit_locked != 0); + } - return (0); +return(0); } + int fstWriterGetFseekFailed(void *ctx) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { - return (xc->fseek_failed != 0); - } +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc) + { + return(xc->fseek_failed != 0); + } - return (0); +return(0); } + /* * writer attr/scope/var creation: * fstWriterCreateVar2() is used to dump VHDL or other languages, but the * underlying variable needs to map to Verilog/SV via the proper fstVarType vt */ -fstHandle fstWriterCreateVar2(void *ctx, enum fstVarType vt, enum fstVarDir vd, uint32_t len, const char *nam, - fstHandle aliasHandle, const char *type, enum fstSupplementalVarType svt, - enum fstSupplementalDataType sdt) +fstHandle fstWriterCreateVar2(void *ctx, enum fstVarType vt, enum fstVarDir vd, + uint32_t len, const char *nam, fstHandle aliasHandle, + const char *type, enum fstSupplementalVarType svt, enum fstSupplementalDataType sdt) { - fstWriterSetAttrGeneric(ctx, type ? type : "", FST_MT_SUPVAR, - (svt << FST_SDT_SVT_SHIFT_COUNT) | (sdt & FST_SDT_ABS_MAX)); - return (fstWriterCreateVar(ctx, vt, vd, len, nam, aliasHandle)); +fstWriterSetAttrGeneric(ctx, type ? type : "", FST_MT_SUPVAR, (svt<valpos_mem) { - fstDestroyMmaps(xc, 0); - } +fstHandle fstWriterCreateVar(void *ctx, enum fstVarType vt, enum fstVarDir vd, + uint32_t len, const char *nam, fstHandle aliasHandle) +{ +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +unsigned int i; +int nlen, is_real; + +if(xc && nam) + { + if(xc->valpos_mem) + { + fstDestroyMmaps(xc, 0); + } fputc(vt, xc->hier_handle); fputc(vd, xc->hier_handle); nlen = strlen(nam); fstFwrite(nam, nlen, 1, xc->hier_handle); fputc(0, xc->hier_handle); - xc->hier_file_len += (nlen + 3); + xc->hier_file_len += (nlen+3); - if ((vt == FST_VT_VCD_REAL) || (vt == FST_VT_VCD_REAL_PARAMETER) || (vt == FST_VT_VCD_REALTIME) || - (vt == FST_VT_SV_SHORTREAL)) { - is_real = 1; - len = 8; /* recast number of bytes to that of what a double is */ - } else { - is_real = 0; - if (vt == FST_VT_GEN_STRING) { - len = 0; - } - } + if((vt == FST_VT_VCD_REAL) || (vt == FST_VT_VCD_REAL_PARAMETER) || (vt == FST_VT_VCD_REALTIME) || (vt == FST_VT_SV_SHORTREAL)) + { + is_real = 1; + len = 8; /* recast number of bytes to that of what a double is */ + } + else + { + is_real = 0; + if(vt == FST_VT_GEN_STRING) + { + len = 0; + } + } xc->hier_file_len += fstWriterVarint(xc->hier_handle, len); - if (aliasHandle > xc->maxhandle) - aliasHandle = 0; + if(aliasHandle > xc->maxhandle) aliasHandle = 0; xc->hier_file_len += fstWriterVarint(xc->hier_handle, aliasHandle); xc->numsigs++; - if (xc->numsigs == xc->next_huge_break) { - if (xc->fst_break_size < xc->fst_huge_break_size) { - xc->next_huge_break += FST_ACTIVATE_HUGE_INC; - xc->fst_break_size += xc->fst_orig_break_size; - xc->fst_break_add_size += xc->fst_orig_break_add_size; + if(xc->numsigs == xc->next_huge_break) + { + if(xc->fst_break_size < xc->fst_huge_break_size) + { + xc->next_huge_break += FST_ACTIVATE_HUGE_INC; + xc->fst_break_size += xc->fst_orig_break_size; + xc->fst_break_add_size += xc->fst_orig_break_add_size; - xc->vchg_alloc_siz = xc->fst_break_size + xc->fst_break_add_size; - if (xc->vchg_mem) { - xc->vchg_mem = (unsigned char *)realloc(xc->vchg_mem, xc->vchg_alloc_siz); + xc->vchg_alloc_siz = xc->fst_break_size + xc->fst_break_add_size; + if(xc->vchg_mem) + { + xc->vchg_mem = (unsigned char *)realloc(xc->vchg_mem, xc->vchg_alloc_siz); + } + } + } + + if(!aliasHandle) + { + uint32_t zero = 0; + + if(len) + { + fstWriterVarint(xc->geom_handle, !is_real ? len : 0); /* geom section encodes reals as zero byte */ + } + else + { + fstWriterVarint(xc->geom_handle, 0xFFFFFFFF); /* geom section encodes zero len as 32b -1 */ + } + + fstFwrite(&xc->maxvalpos, sizeof(uint32_t), 1, xc->valpos_handle); + fstFwrite(&len, sizeof(uint32_t), 1, xc->valpos_handle); + fstFwrite(&zero, sizeof(uint32_t), 1, xc->valpos_handle); + fstFwrite(&zero, sizeof(uint32_t), 1, xc->valpos_handle); + + if(!is_real) + { + for(i=0;icurval_handle); + } + } + else + { + fstFwrite(&xc->nan, 8, 1, xc->curval_handle); /* initialize doubles to NaN rather than x */ + } + + xc->maxvalpos+=len; + xc->maxhandle++; + return(xc->maxhandle); + } + else + { + return(aliasHandle); } - } } - if (!aliasHandle) { - uint32_t zero = 0; - - if (len) { - fstWriterVarint(xc->geom_handle, !is_real ? len : 0); /* geom section encodes reals as zero byte */ - } else { - fstWriterVarint(xc->geom_handle, 0xFFFFFFFF); /* geom section encodes zero len as 32b -1 */ - } - - fstFwrite(&xc->maxvalpos, sizeof(uint32_t), 1, xc->valpos_handle); - fstFwrite(&len, sizeof(uint32_t), 1, xc->valpos_handle); - fstFwrite(&zero, sizeof(uint32_t), 1, xc->valpos_handle); - fstFwrite(&zero, sizeof(uint32_t), 1, xc->valpos_handle); - - if (!is_real) { - for (i = 0; i < len; i++) { - fputc('x', xc->curval_handle); - } - } else { - fstFwrite(&xc->nan, 8, 1, xc->curval_handle); /* initialize doubles to NaN rather than x */ - } - - xc->maxvalpos += len; - xc->maxhandle++; - return (xc->maxhandle); - } else { - return (aliasHandle); - } - } - - return (0); +return(0); } -void fstWriterSetScope(void *ctx, enum fstScopeType scopetype, const char *scopename, const char *scopecomp) + +void fstWriterSetScope(void *ctx, enum fstScopeType scopetype, + const char *scopename, const char *scopecomp) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { +if(xc) + { fputc(FST_ST_VCD_SCOPE, xc->hier_handle); - if (/*(scopetype < FST_ST_VCD_MODULE) ||*/ (scopetype > FST_ST_MAX)) { - scopetype = FST_ST_VCD_MODULE; - } + if(/*(scopetype < FST_ST_VCD_MODULE) ||*/ (scopetype > FST_ST_MAX)) { scopetype = FST_ST_VCD_MODULE; } fputc(scopetype, xc->hier_handle); - fprintf(xc->hier_handle, "%s%c%s%c", scopename ? scopename : "", 0, scopecomp ? scopecomp : "", 0); + fprintf(xc->hier_handle, "%s%c%s%c", + scopename ? scopename : "", 0, + scopecomp ? scopecomp : "", 0); - if (scopename) { - xc->hier_file_len += strlen(scopename); - } - if (scopecomp) { - xc->hier_file_len += strlen(scopecomp); - } + if(scopename) + { + xc->hier_file_len += strlen(scopename); + } + if(scopecomp) + { + xc->hier_file_len += strlen(scopecomp); + } xc->hier_file_len += 4; /* FST_ST_VCD_SCOPE + scopetype + two string terminating zeros */ xc->numscopes++; - } + } } + void fstWriterSetUpscope(void *ctx) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { +if(xc) + { fputc(FST_ST_VCD_UPSCOPE, xc->hier_handle); xc->hier_file_len++; - } + } } -void fstWriterSetAttrBegin(void *ctx, enum fstAttrType attrtype, int subtype, const char *attrname, uint64_t arg) -{ - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { +void fstWriterSetAttrBegin(void *ctx, enum fstAttrType attrtype, int subtype, + const char *attrname, uint64_t arg) +{ +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; + +if(xc) + { fputc(FST_ST_GEN_ATTRBEGIN, xc->hier_handle); - if (/*(attrtype < FST_AT_MISC) ||*/ (attrtype > FST_AT_MAX)) { - attrtype = FST_AT_MISC; - subtype = FST_MT_UNKNOWN; - } + if(/*(attrtype < FST_AT_MISC) ||*/ (attrtype > FST_AT_MAX)) { attrtype = FST_AT_MISC; subtype = FST_MT_UNKNOWN; } fputc(attrtype, xc->hier_handle); - switch (attrtype) { - case FST_AT_ARRAY: - if ((subtype < FST_AR_NONE) || (subtype > FST_AR_MAX)) - subtype = FST_AR_NONE; - break; - case FST_AT_ENUM: - if ((subtype < FST_EV_SV_INTEGER) || (subtype > FST_EV_MAX)) - subtype = FST_EV_SV_INTEGER; - break; - case FST_AT_PACK: - if ((subtype < FST_PT_NONE) || (subtype > FST_PT_MAX)) - subtype = FST_PT_NONE; - break; + switch(attrtype) + { + case FST_AT_ARRAY: if((subtype < FST_AR_NONE) || (subtype > FST_AR_MAX)) subtype = FST_AR_NONE; break; + case FST_AT_ENUM: if((subtype < FST_EV_SV_INTEGER) || (subtype > FST_EV_MAX)) subtype = FST_EV_SV_INTEGER; break; + case FST_AT_PACK: if((subtype < FST_PT_NONE) || (subtype > FST_PT_MAX)) subtype = FST_PT_NONE; break; - case FST_AT_MISC: - default: - break; - } + case FST_AT_MISC: + default: break; + } fputc(subtype, xc->hier_handle); - fprintf(xc->hier_handle, "%s%c", attrname ? attrname : "", 0); + fprintf(xc->hier_handle, "%s%c", + attrname ? attrname : "", 0); - if (attrname) { - xc->hier_file_len += strlen(attrname); - } + if(attrname) + { + xc->hier_file_len += strlen(attrname); + } xc->hier_file_len += 4; /* FST_ST_GEN_ATTRBEGIN + type + subtype + string terminating zero */ xc->hier_file_len += fstWriterVarint(xc->hier_handle, arg); - } + } } + void fstWriterSetAttrEnd(void *ctx) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { +if(xc) + { fputc(FST_ST_GEN_ATTREND, xc->hier_handle); xc->hier_file_len++; - } + } } -fstEnumHandle fstWriterCreateEnumTable(void *ctx, const char *name, uint32_t elem_count, unsigned int min_valbits, - const char **literal_arr, const char **val_arr) + +fstEnumHandle fstWriterCreateEnumTable(void *ctx, const char *name, uint32_t elem_count, unsigned int min_valbits, const char **literal_arr, const char **val_arr) { - fstEnumHandle handle = 0; - unsigned int *literal_lens = NULL; - unsigned int *val_lens = NULL; - int lit_len_tot = 0; - int val_len_tot = 0; - int name_len; - char elem_count_buf[16]; - int elem_count_len; - int total_len; - int pos = 0; - char *attr_str = NULL; +fstEnumHandle handle = 0; +unsigned int *literal_lens = NULL; +unsigned int *val_lens = NULL; +int lit_len_tot = 0; +int val_len_tot = 0; +int name_len; +char elem_count_buf[16]; +int elem_count_len; +int total_len; +int pos = 0; +char *attr_str = NULL; - if (ctx && name && literal_arr && val_arr && (elem_count != 0)) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(ctx && name && literal_arr && val_arr && (elem_count != 0)) + { + struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - uint32_t i; + uint32_t i; - name_len = strlen(name); - elem_count_len = snprintf(elem_count_buf, sizeof(elem_count_buf), "%" PRIu32, elem_count); + name_len = strlen(name); + elem_count_len = snprintf(elem_count_buf, 16, "%" PRIu32, elem_count); - literal_lens = (unsigned int *)calloc(elem_count, sizeof(unsigned int)); - val_lens = (unsigned int *)calloc(elem_count, sizeof(unsigned int)); + literal_lens = (unsigned int *)calloc(elem_count, sizeof(unsigned int)); + val_lens = (unsigned int *)calloc(elem_count, sizeof(unsigned int)); - for (i = 0; i < elem_count; i++) { - literal_lens[i] = strlen(literal_arr[i]); - lit_len_tot += fstUtilityBinToEscConvertedLen((unsigned char *)literal_arr[i], literal_lens[i]); + for(i=0;i 0) { - if (val_lens[i] < min_valbits) { - val_len_tot += (min_valbits - val_lens[i]); /* additional converted len is same for '0' character */ - } - } - } + if(min_valbits > 0) + { + if(val_lens[i] < min_valbits) + { + val_len_tot += (min_valbits - val_lens[i]); /* additional converted len is same for '0' character */ + } + } + } - total_len = name_len + 1 + elem_count_len + 1 + lit_len_tot + elem_count + val_len_tot + elem_count; + total_len = name_len + 1 + elem_count_len + 1 + lit_len_tot + elem_count + val_len_tot + elem_count; - attr_str = (char *)malloc(total_len); - pos = 0; + attr_str = (char*)malloc(total_len); + pos = 0; - memcpy(attr_str + pos, name, name_len); - pos += name_len; - attr_str[pos++] = ' '; + memcpy(attr_str+pos, name, name_len); + pos += name_len; + attr_str[pos++] = ' '; - memcpy(attr_str + pos, elem_count_buf, elem_count_len); - pos += elem_count_len; - attr_str[pos++] = ' '; + memcpy(attr_str+pos, elem_count_buf, elem_count_len); + pos += elem_count_len; + attr_str[pos++] = ' '; - for (i = 0; i < elem_count; i++) { - pos += fstUtilityBinToEsc((unsigned char *)attr_str + pos, (unsigned char *)literal_arr[i], - literal_lens[i]); - attr_str[pos++] = ' '; - } + for(i=0;i 0) { - if (val_lens[i] < min_valbits) { - memset(attr_str + pos, '0', min_valbits - val_lens[i]); - pos += (min_valbits - val_lens[i]); - } - } + for(i=0;i 0) + { + if(val_lens[i] < min_valbits) + { + memset(attr_str+pos, '0', min_valbits - val_lens[i]); + pos += (min_valbits - val_lens[i]); + } + } - pos += fstUtilityBinToEsc((unsigned char *)attr_str + pos, (unsigned char *)val_arr[i], val_lens[i]); - attr_str[pos++] = ' '; - } + pos += fstUtilityBinToEsc((unsigned char*)attr_str+pos, (unsigned char*)val_arr[i], val_lens[i]); + attr_str[pos++] = ' '; + } - attr_str[pos - 1] = 0; + attr_str[pos-1] = 0; #ifdef FST_DEBUG - fprintf(stderr, FST_APIMESS "fstWriterCreateEnumTable() total_len: %d, pos: %d\n", total_len, pos); - fprintf(stderr, FST_APIMESS "*%s*\n", attr_str); + fprintf(stderr, FST_APIMESS "fstWriterCreateEnumTable() total_len: %d, pos: %d\n", total_len, pos); + fprintf(stderr, FST_APIMESS "*%s*\n", attr_str); #endif - fstWriterSetAttrBegin(xc, FST_AT_MISC, FST_MT_ENUMTABLE, attr_str, handle = ++xc->max_enumhandle); + fstWriterSetAttrBegin(xc, FST_AT_MISC, FST_MT_ENUMTABLE, attr_str, handle = ++xc->max_enumhandle); - free(attr_str); - free(val_lens); - free(literal_lens); - } + free(attr_str); + free(val_lens); + free(literal_lens); + } - return (handle); +return(handle); } + void fstWriterEmitEnumTableRef(void *ctx, fstEnumHandle handle) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc && handle) { - fstWriterSetAttrBegin(xc, FST_AT_MISC, FST_MT_ENUMTABLE, NULL, handle); - } +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +if(xc && handle) + { + fstWriterSetAttrBegin(xc, FST_AT_MISC, FST_MT_ENUMTABLE, NULL, handle); + } } + /* * value and time change emission */ void fstWriterEmitValueChange(void *ctx, fstHandle handle, const void *val) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - const unsigned char *buf = (const unsigned char *)val; - uint32_t offs; - int len; +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +const unsigned char *buf = (const unsigned char *)val; +uint32_t offs; +int len; - if (FST_LIKELY((xc) && (handle <= xc->maxhandle))) { +if(FST_LIKELY((xc) && (handle <= xc->maxhandle))) + { uint32_t fpos; uint32_t *vm4ip; - if (FST_UNLIKELY(!xc->valpos_mem)) { - xc->vc_emitted = 1; - fstWriterCreateMmaps(xc); - } + if(FST_UNLIKELY(!xc->valpos_mem)) + { + xc->vc_emitted = 1; + fstWriterCreateMmaps(xc); + } handle--; /* move starting at 1 index to starting at 0 */ - vm4ip = &(xc->valpos_mem[4 * handle]); + vm4ip = &(xc->valpos_mem[4*handle]); - len = vm4ip[1]; - if (FST_LIKELY(len)) /* len of zero = variable length, use fstWriterEmitVariableLengthValueChange */ - { - if (FST_LIKELY(!xc->is_initial_time)) { - fpos = xc->vchg_siz; + len = vm4ip[1]; + if(FST_LIKELY(len)) /* len of zero = variable length, use fstWriterEmitVariableLengthValueChange */ + { + if(FST_LIKELY(!xc->is_initial_time)) + { + fpos = xc->vchg_siz; - if (FST_UNLIKELY((fpos + len + 10) > xc->vchg_alloc_siz)) { - xc->vchg_alloc_siz += - (xc->fst_break_add_size + - len); /* +len added in the case of extremely long vectors and small break add sizes */ - xc->vchg_mem = (unsigned char *)realloc(xc->vchg_mem, xc->vchg_alloc_siz); - if (FST_UNLIKELY(!xc->vchg_mem)) { - fprintf(stderr, FST_APIMESS "Could not realloc() in fstWriterEmitValueChange, exiting.\n"); - exit(255); - } - } -#ifdef FST_REMOVE_DUPLICATE_VC - offs = vm4ip[0]; - - if (len != 1) { - if ((vm4ip[3] == xc->tchn_idx) && (vm4ip[2])) { - unsigned char *old_value = xc->vchg_mem + vm4ip[2] + 4; /* the +4 skips old vm4ip[2] value */ - while (*(old_value++) & 0x80) { /* skips over varint encoded "xc->tchn_idx - vm4ip[3]" */ - } - memcpy(old_value, buf, len); /* overlay new value */ - - memcpy(xc->curval_mem + offs, buf, len); - return; - } else { - if (!memcmp(xc->curval_mem + offs, buf, len)) { - if (!xc->curtime) { - int i; - for (i = 0; i < len; i++) { - if (buf[i] != 'x') - break; + if(FST_UNLIKELY((fpos + len + 10) > xc->vchg_alloc_siz)) + { + xc->vchg_alloc_siz += (xc->fst_break_add_size + len); /* +len added in the case of extremely long vectors and small break add sizes */ + xc->vchg_mem = (unsigned char *)realloc(xc->vchg_mem, xc->vchg_alloc_siz); + if(FST_UNLIKELY(!xc->vchg_mem)) + { + fprintf(stderr, FST_APIMESS "Could not realloc() in fstWriterEmitValueChange, exiting.\n"); + exit(255); + } } +#ifdef FST_REMOVE_DUPLICATE_VC + offs = vm4ip[0]; - if (i < len) - return; - } else { - return; - } - } - } + if(len != 1) + { + if((vm4ip[3]==xc->tchn_idx)&&(vm4ip[2])) + { + unsigned char *old_value = xc->vchg_mem + vm4ip[2] + 4; /* the +4 skips old vm4ip[2] value */ + while(*(old_value++) & 0x80) { /* skips over varint encoded "xc->tchn_idx - vm4ip[3]" */ } + memcpy(old_value, buf, len); /* overlay new value */ - memcpy(xc->curval_mem + offs, buf, len); - } else { - if ((vm4ip[3] == xc->tchn_idx) && (vm4ip[2])) { - unsigned char *old_value = xc->vchg_mem + vm4ip[2] + 4; /* the +4 skips old vm4ip[2] value */ - while (*(old_value++) & 0x80) { /* skips over varint encoded "xc->tchn_idx - vm4ip[3]" */ - } - *old_value = *buf; /* overlay new value */ + memcpy(xc->curval_mem + offs, buf, len); + return; + } + else + { + if(!memcmp(xc->curval_mem + offs, buf, len)) + { + if(!xc->curtime) + { + int i; + for(i=0;icurval_mem + offs) = *buf; - return; - } else { - if ((*(xc->curval_mem + offs)) == (*buf)) { - if (!xc->curtime) { - if (*buf != 'x') - return; - } else { - return; - } - } - } + if(icurval_mem + offs) = *buf; - } + memcpy(xc->curval_mem + offs, buf, len); + } + else + { + if((vm4ip[3]==xc->tchn_idx)&&(vm4ip[2])) + { + unsigned char *old_value = xc->vchg_mem + vm4ip[2] + 4; /* the +4 skips old vm4ip[2] value */ + while(*(old_value++) & 0x80) { /* skips over varint encoded "xc->tchn_idx - vm4ip[3]" */ } + *old_value = *buf; /* overlay new value */ + + *(xc->curval_mem + offs) = *buf; + return; + } + else + { + if((*(xc->curval_mem + offs)) == (*buf)) + { + if(!xc->curtime) + { + if(*buf != 'x') return; + } + else + { + return; + } + } + } + + *(xc->curval_mem + offs) = *buf; + } #endif - xc->vchg_siz += fstWriterUint32WithVarint32(xc, &vm4ip[2], xc->tchn_idx - vm4ip[3], buf, - len); /* do one fwrite op only */ - vm4ip[3] = xc->tchn_idx; - vm4ip[2] = fpos; - } else { - offs = vm4ip[0]; - memcpy(xc->curval_mem + offs, buf, len); - } + xc->vchg_siz += fstWriterUint32WithVarint32(xc, &vm4ip[2], xc->tchn_idx - vm4ip[3], buf, len); /* do one fwrite op only */ + vm4ip[3] = xc->tchn_idx; + vm4ip[2] = fpos; + } + else + { + offs = vm4ip[0]; + memcpy(xc->curval_mem + offs, buf, len); + } + } } - } } -void fstWriterEmitValueChange32(void *ctx, fstHandle handle, uint32_t bits, uint32_t val) -{ - char buf[32]; - char *s = buf; - uint32_t i; - for (i = 0; i < bits; ++i) { - *s++ = '0' + ((val >> (bits - i - 1)) & 1); - } - fstWriterEmitValueChange(ctx, handle, buf); -} -void fstWriterEmitValueChange64(void *ctx, fstHandle handle, uint32_t bits, uint64_t val) -{ - char buf[64]; - char *s = buf; - uint32_t i; - for (i = 0; i < bits; ++i) { - *s++ = '0' + ((val >> (bits - i - 1)) & 1); - } - fstWriterEmitValueChange(ctx, handle, buf); -} -void fstWriterEmitValueChangeVec32(void *ctx, fstHandle handle, uint32_t bits, const uint32_t *val) -{ - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (FST_UNLIKELY(bits <= 32)) { - fstWriterEmitValueChange32(ctx, handle, bits, val[0]); - } else if (FST_LIKELY(xc)) { - int bq = bits / 32; - int br = bits & 31; - int i; - int w; - uint32_t v; - unsigned char *s; - if (FST_UNLIKELY(bits > xc->outval_alloc_siz)) { - xc->outval_alloc_siz = bits * 2 + 1; - xc->outval_mem = (unsigned char *)realloc(xc->outval_mem, xc->outval_alloc_siz); - if (FST_UNLIKELY(!xc->outval_mem)) { - fprintf(stderr, FST_APIMESS "Could not realloc() in fstWriterEmitValueChangeVec32, exiting.\n"); - exit(255); - } - } - s = xc->outval_mem; +void fstWriterEmitValueChange32(void *ctx, fstHandle handle, + uint32_t bits, uint32_t val) { + char buf[32]; + char *s = buf; + uint32_t i; + for (i = 0; i < bits; ++i) { - w = bq; - v = val[w]; - for (i = 0; i < br; ++i) { - *s++ = '0' + ((v >> (br - i - 1)) & 1); - } + *s++ = '0' + ((val >> (bits - i - 1)) & 1); } - for (w = bq - 1; w >= 0; --w) { - v = val[w]; - for (i = (32 - 4); i >= 0; i -= 4) { - s[0] = '0' + ((v >> (i + 3)) & 1); - s[1] = '0' + ((v >> (i + 2)) & 1); - s[2] = '0' + ((v >> (i + 1)) & 1); - s[3] = '0' + ((v >> (i + 0)) & 1); - s += 4; - } - } - fstWriterEmitValueChange(ctx, handle, xc->outval_mem); - } + fstWriterEmitValueChange(ctx, handle, buf); } -void fstWriterEmitValueChangeVec64(void *ctx, fstHandle handle, uint32_t bits, const uint64_t *val) -{ - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (FST_UNLIKELY(bits <= 64)) { - fstWriterEmitValueChange64(ctx, handle, bits, val[0]); - } else if (FST_LIKELY(xc)) { - int bq = bits / 64; - int br = bits & 63; - int i; - int w; - uint32_t v; - unsigned char *s; - if (FST_UNLIKELY(bits > xc->outval_alloc_siz)) { - xc->outval_alloc_siz = bits * 2 + 1; - xc->outval_mem = (unsigned char *)realloc(xc->outval_mem, xc->outval_alloc_siz); - if (FST_UNLIKELY(!xc->outval_mem)) { - fprintf(stderr, FST_APIMESS "Could not realloc() in fstWriterEmitValueChangeVec64, exiting.\n"); - exit(255); - } - } - s = xc->outval_mem; +void fstWriterEmitValueChange64(void *ctx, fstHandle handle, + uint32_t bits, uint64_t val) { + char buf[64]; + char *s = buf; + uint32_t i; + for (i = 0; i < bits; ++i) { - w = bq; - v = val[w]; - for (i = 0; i < br; ++i) { - *s++ = '0' + ((v >> (br - i - 1)) & 1); - } + *s++ = '0' + ((val >> (bits - i - 1)) & 1); } - for (w = bq - 1; w >= 0; --w) { - v = val[w]; - for (i = (64 - 4); i >= 0; i -= 4) { - s[0] = '0' + ((v >> (i + 3)) & 1); - s[1] = '0' + ((v >> (i + 2)) & 1); - s[2] = '0' + ((v >> (i + 1)) & 1); - s[3] = '0' + ((v >> (i + 0)) & 1); - s += 4; - } - } - fstWriterEmitValueChange(ctx, handle, xc->outval_mem); - } + fstWriterEmitValueChange(ctx, handle, buf); } +void fstWriterEmitValueChangeVec32(void *ctx, fstHandle handle, + uint32_t bits, const uint32_t *val) { + struct fstWriterContext *xc = (struct fstWriterContext *)ctx; + if (FST_UNLIKELY(bits <= 32)) + { + fstWriterEmitValueChange32(ctx, handle, bits, val[0]); + } + else if(FST_LIKELY(xc)) + { + int bq = bits / 32; + int br = bits & 31; + int i; + int w; + uint32_t v; + unsigned char* s; + if (FST_UNLIKELY(bits > xc->outval_alloc_siz)) + { + xc->outval_alloc_siz = bits*2 + 1; + xc->outval_mem = (unsigned char*)realloc(xc->outval_mem, xc->outval_alloc_siz); + if (FST_UNLIKELY(!xc->outval_mem)) + { + fprintf(stderr, + FST_APIMESS "Could not realloc() in fstWriterEmitValueChangeVec32, exiting.\n"); + exit(255); + } + } + s = xc->outval_mem; + { + w = bq; + v = val[w]; + for (i = 0; i < br; ++i) + { + *s++ = '0' + ((v >> (br - i - 1)) & 1); + } + } + for (w = bq - 1; w >= 0; --w) + { + v = val[w]; + for (i = (32 - 4); i >= 0; i -= 4) { + s[0] = '0' + ((v >> (i + 3)) & 1); + s[1] = '0' + ((v >> (i + 2)) & 1); + s[2] = '0' + ((v >> (i + 1)) & 1); + s[3] = '0' + ((v >> (i + 0)) & 1); + s += 4; + } + } + fstWriterEmitValueChange(ctx, handle, xc->outval_mem); + } +} +void fstWriterEmitValueChangeVec64(void *ctx, fstHandle handle, + uint32_t bits, const uint64_t *val) { + struct fstWriterContext *xc = (struct fstWriterContext *)ctx; + if (FST_UNLIKELY(bits <= 64)) + { + fstWriterEmitValueChange64(ctx, handle, bits, val[0]); + } + else if(FST_LIKELY(xc)) + { + int bq = bits / 64; + int br = bits & 63; + int i; + int w; + uint32_t v; + unsigned char* s; + if (FST_UNLIKELY(bits > xc->outval_alloc_siz)) + { + xc->outval_alloc_siz = bits*2 + 1; + xc->outval_mem = (unsigned char*)realloc(xc->outval_mem, xc->outval_alloc_siz); + if (FST_UNLIKELY(!xc->outval_mem)) + { + fprintf(stderr, + FST_APIMESS "Could not realloc() in fstWriterEmitValueChangeVec64, exiting.\n"); + exit(255); + } + } + s = xc->outval_mem; + { + w = bq; + v = val[w]; + for (i = 0; i < br; ++i) + { + *s++ = '0' + ((v >> (br - i - 1)) & 1); + } + } + for (w = bq - 1; w >= 0; --w) { + v = val[w]; + for (i = (64 - 4); i >= 0; i -= 4) + { + s[0] = '0' + ((v >> (i + 3)) & 1); + s[1] = '0' + ((v >> (i + 2)) & 1); + s[2] = '0' + ((v >> (i + 1)) & 1); + s[3] = '0' + ((v >> (i + 0)) & 1); + s += 4; + } + } + fstWriterEmitValueChange(ctx, handle, xc->outval_mem); + } +} + void fstWriterEmitVariableLengthValueChange(void *ctx, fstHandle handle, const void *val, uint32_t len) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - const unsigned char *buf = (const unsigned char *)val; +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +const unsigned char *buf = (const unsigned char *)val; - if (FST_LIKELY((xc) && (handle <= xc->maxhandle))) { +if(FST_LIKELY((xc) && (handle <= xc->maxhandle))) + { uint32_t fpos; uint32_t *vm4ip; - if (FST_UNLIKELY(!xc->valpos_mem)) { - xc->vc_emitted = 1; - fstWriterCreateMmaps(xc); - } + if(FST_UNLIKELY(!xc->valpos_mem)) + { + xc->vc_emitted = 1; + fstWriterCreateMmaps(xc); + } handle--; /* move starting at 1 index to starting at 0 */ - vm4ip = &(xc->valpos_mem[4 * handle]); + vm4ip = &(xc->valpos_mem[4*handle]); /* there is no initial time dump for variable length value changes */ - if (FST_LIKELY(!vm4ip[1])) /* len of zero = variable length */ - { - fpos = xc->vchg_siz; + if(FST_LIKELY(!vm4ip[1])) /* len of zero = variable length */ + { + fpos = xc->vchg_siz; - if (FST_UNLIKELY((fpos + len + 10 + 5) > xc->vchg_alloc_siz)) { - xc->vchg_alloc_siz += - (xc->fst_break_add_size + len + - 5); /* +len added in the case of extremely long vectors and small break add sizes */ - xc->vchg_mem = (unsigned char *)realloc(xc->vchg_mem, xc->vchg_alloc_siz); - if (FST_UNLIKELY(!xc->vchg_mem)) { - fprintf(stderr, - FST_APIMESS "Could not realloc() in fstWriterEmitVariableLengthValueChange, exiting.\n"); - exit(255); + if(FST_UNLIKELY((fpos + len + 10 + 5) > xc->vchg_alloc_siz)) + { + xc->vchg_alloc_siz += (xc->fst_break_add_size + len + 5); /* +len added in the case of extremely long vectors and small break add sizes */ + xc->vchg_mem = (unsigned char *)realloc(xc->vchg_mem, xc->vchg_alloc_siz); + if(FST_UNLIKELY(!xc->vchg_mem)) + { + fprintf(stderr, FST_APIMESS "Could not realloc() in fstWriterEmitVariableLengthValueChange, exiting.\n"); + exit(255); + } + } + + xc->vchg_siz += fstWriterUint32WithVarint32AndLength(xc, &vm4ip[2], xc->tchn_idx - vm4ip[3], buf, len); /* do one fwrite op only */ + vm4ip[3] = xc->tchn_idx; + vm4ip[2] = fpos; } - } - - xc->vchg_siz += fstWriterUint32WithVarint32AndLength(xc, &vm4ip[2], xc->tchn_idx - vm4ip[3], buf, - len); /* do one fwrite op only */ - vm4ip[3] = xc->tchn_idx; - vm4ip[2] = fpos; } - } } + void fstWriterEmitTimeChange(void *ctx, uint64_t tim) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - unsigned int i; - int skip = 0; - if (xc) { - if (FST_UNLIKELY(xc->is_initial_time)) { - if (xc->size_limit_locked) /* this resets xc->is_initial_time to one */ - { - return; - } +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +unsigned int i; +int skip = 0; +if(xc) + { + if(FST_UNLIKELY(xc->is_initial_time)) + { + if(xc->size_limit_locked) /* this resets xc->is_initial_time to one */ + { + return; + } - if (!xc->valpos_mem) { - fstWriterCreateMmaps(xc); - } + if(!xc->valpos_mem) + { + fstWriterCreateMmaps(xc); + } - skip = 1; + skip = 1; - xc->firsttime = (xc->vc_emitted) ? 0 : tim; - xc->curtime = 0; - xc->vchg_mem[0] = '!'; - xc->vchg_siz = 1; - fstWriterEmitSectionHeader(xc); - for (i = 0; i < xc->maxhandle; i++) { - xc->valpos_mem[4 * i + 2] = 0; /* zero out offset val */ - xc->valpos_mem[4 * i + 3] = 0; /* zero out last time change val */ - } - xc->is_initial_time = 0; - } else { - if ((xc->vchg_siz >= xc->fst_break_size) || (xc->flush_context_pending)) { - xc->flush_context_pending = 0; - fstWriterFlushContextPrivate(xc); - xc->tchn_cnt++; - fstWriterVarint(xc->tchn_handle, xc->curtime); - } - } + xc->firsttime = (xc->vc_emitted) ? 0: tim; + xc->curtime = 0; + xc->vchg_mem[0] = '!'; + xc->vchg_siz = 1; + fstWriterEmitSectionHeader(xc); + for(i=0;imaxhandle;i++) + { + xc->valpos_mem[4*i+2] = 0; /* zero out offset val */ + xc->valpos_mem[4*i+3] = 0; /* zero out last time change val */ + } + xc->is_initial_time = 0; + } + else + { + if((xc->vchg_siz >= xc->fst_break_size) || (xc->flush_context_pending)) + { + xc->flush_context_pending = 0; + fstWriterFlushContextPrivate(xc); + xc->tchn_cnt++; + fstWriterVarint(xc->tchn_handle, xc->curtime); + } + } - if (!skip) { - xc->tchn_idx++; - } + if(!skip) + { + xc->tchn_idx++; + } fstWriterVarint(xc->tchn_handle, tim - xc->curtime); xc->tchn_cnt++; xc->curtime = tim; - } + } } + void fstWriterEmitDumpActive(void *ctx, int enable) { - struct fstWriterContext *xc = (struct fstWriterContext *)ctx; +struct fstWriterContext *xc = (struct fstWriterContext *)ctx; - if (xc) { +if(xc) + { struct fstBlackoutChain *b = (struct fstBlackoutChain *)calloc(1, sizeof(struct fstBlackoutChain)); b->tim = xc->curtime; b->active = (enable != 0); xc->num_blackouts++; - if (xc->blackout_curr) { - xc->blackout_curr->next = b; - xc->blackout_curr = b; - } else { - xc->blackout_head = b; - xc->blackout_curr = b; + if(xc->blackout_curr) + { + xc->blackout_curr->next = b; + xc->blackout_curr = b; + } + else + { + xc->blackout_head = b; + xc->blackout_curr = b; + } } - } } + /***********************/ /*** ***/ /*** reader function ***/ @@ -3016,531 +3295,592 @@ void fstWriterEmitDumpActive(void *ctx, int enable) /* * private structs */ -static const char *vartypes[] = {"event", "integer", "parameter", "real", "real_parameter", "reg", "supply0", - "supply1", "time", "tri", "triand", "trior", "trireg", "tri0", - "tri1", "wand", "wire", "wor", "port", "sparray", "realtime", - "string", "bit", "logic", "int", "shortint", "longint", "byte", - "enum", "shortreal"}; +static const char *vartypes[] = { + "event", "integer", "parameter", "real", "real_parameter", + "reg", "supply0", "supply1", "time", "tri", + "triand", "trior", "trireg", "tri0", "tri1", + "wand", "wire", "wor", "port", "sparray", "realtime", + "string", + "bit", "logic", "int", "shortint", "longint", "byte", "enum", "shortreal" + }; -static const char *modtypes[] = {"module", - "task", - "function", - "begin", - "fork", - "generate", - "struct", - "union", - "class", - "interface", - "package", - "program", - "vhdl_architecture", - "vhdl_procedure", - "vhdl_function", - "vhdl_record", - "vhdl_process", - "vhdl_block", - "vhdl_for_generate", - "vhdl_if_generate", - "vhdl_generate", - "vhdl_package"}; +static const char *modtypes[] = { + "module", "task", "function", "begin", "fork", "generate", "struct", "union", "class", "interface", "package", "program", + "vhdl_architecture", "vhdl_procedure", "vhdl_function", "vhdl_record", "vhdl_process", "vhdl_block", "vhdl_for_generate", "vhdl_if_generate", "vhdl_generate", "vhdl_package" + }; -static const char *attrtypes[] = {"misc", "array", "enum", "class"}; +static const char *attrtypes[] = { + "misc", "array", "enum", "class" + }; -static const char *arraytypes[] = {"none", "unpacked", "packed", "sparse"}; +static const char *arraytypes[] = { + "none", "unpacked", "packed", "sparse" + }; -static const char *enumvaluetypes[] = {"integer", - "bit", - "logic", - "int", - "shortint", - "longint", - "byte", - "unsigned_integer", - "unsigned_bit", - "unsigned_logic", - "unsigned_int", - "unsigned_shortint", - "unsigned_longint", - "unsigned_byte"}; +static const char *enumvaluetypes[] = { + "integer", "bit", "logic", "int", "shortint", "longint", "byte", + "unsigned_integer", "unsigned_bit", "unsigned_logic", "unsigned_int", "unsigned_shortint", "unsigned_longint", "unsigned_byte" + }; + +static const char *packtypes[] = { + "none", "unpacked", "packed", "tagged_packed" + }; -static const char *packtypes[] = {"none", "unpacked", "packed", "tagged_packed"}; struct fstCurrHier { - struct fstCurrHier *prev; - void *user_info; - int len; +struct fstCurrHier *prev; +void *user_info; +int len; }; + struct fstReaderContext { - /* common entries */ +/* common entries */ - FILE *f, *fh; +FILE *f, *fh; - uint64_t start_time, end_time; - uint64_t mem_used_by_writer; - uint64_t scope_count; - uint64_t var_count; - fstHandle maxhandle; - uint64_t num_alias; - uint64_t vc_section_count; +uint64_t start_time, end_time; +uint64_t mem_used_by_writer; +uint64_t scope_count; +uint64_t var_count; +fstHandle maxhandle; +uint64_t num_alias; +uint64_t vc_section_count; - uint32_t *signal_lens; /* maxhandle sized */ - unsigned char *signal_typs; /* maxhandle sized */ - unsigned char *process_mask; /* maxhandle-based, bitwise sized */ - uint32_t longest_signal_value_len; /* longest len value encountered */ - unsigned char *temp_signal_value_buf; /* malloced for len in longest_signal_value_len */ +uint32_t *signal_lens; /* maxhandle sized */ +unsigned char *signal_typs; /* maxhandle sized */ +unsigned char *process_mask; /* maxhandle-based, bitwise sized */ +uint32_t longest_signal_value_len; /* longest len value encountered */ +unsigned char *temp_signal_value_buf; /* malloced for len in longest_signal_value_len */ - signed char timescale; - unsigned char filetype; +signed char timescale; +unsigned char filetype; - unsigned use_vcd_extensions : 1; - unsigned double_endian_match : 1; - unsigned native_doubles_for_cb : 1; - unsigned contains_geom_section : 1; - unsigned contains_hier_section : 1; /* valid for hier_pos */ - unsigned contains_hier_section_lz4duo : 1; /* valid for hier_pos (contains_hier_section_lz4 always also set) */ - unsigned contains_hier_section_lz4 : 1; /* valid for hier_pos */ - unsigned limit_range_valid : 1; /* valid for limit_range_start, limit_range_end */ +unsigned use_vcd_extensions : 1; +unsigned double_endian_match : 1; +unsigned native_doubles_for_cb : 1; +unsigned contains_geom_section : 1; +unsigned contains_hier_section : 1; /* valid for hier_pos */ +unsigned contains_hier_section_lz4duo : 1; /* valid for hier_pos (contains_hier_section_lz4 always also set) */ +unsigned contains_hier_section_lz4 : 1; /* valid for hier_pos */ +unsigned limit_range_valid : 1; /* valid for limit_range_start, limit_range_end */ - char version[FST_HDR_SIM_VERSION_SIZE + 1]; - char date[FST_HDR_DATE_SIZE + 1]; - int64_t timezero; +char version[FST_HDR_SIM_VERSION_SIZE + 1]; +char date[FST_HDR_DATE_SIZE + 1]; +int64_t timezero; - char *filename, *filename_unpacked; - fst_off_t hier_pos; +char *filename, *filename_unpacked; +fst_off_t hier_pos; - uint32_t num_blackouts; - uint64_t *blackout_times; - unsigned char *blackout_activity; +uint32_t num_blackouts; +uint64_t *blackout_times; +unsigned char *blackout_activity; - uint64_t limit_range_start, limit_range_end; +uint64_t limit_range_start, limit_range_end; - /* entries specific to read value at time functions */ +/* entries specific to read value at time functions */ - unsigned rvat_data_valid : 1; - uint64_t *rvat_time_table; - uint64_t rvat_beg_tim, rvat_end_tim; - unsigned char *rvat_frame_data; - uint64_t rvat_frame_maxhandle; - fst_off_t *rvat_chain_table; - uint32_t *rvat_chain_table_lengths; - uint64_t rvat_vc_maxhandle; - fst_off_t rvat_vc_start; - uint32_t *rvat_sig_offs; - int rvat_packtype; +unsigned rvat_data_valid : 1; +uint64_t *rvat_time_table; +uint64_t rvat_beg_tim, rvat_end_tim; +unsigned char *rvat_frame_data; +uint64_t rvat_frame_maxhandle; +fst_off_t *rvat_chain_table; +uint32_t *rvat_chain_table_lengths; +uint64_t rvat_vc_maxhandle; +fst_off_t rvat_vc_start; +uint32_t *rvat_sig_offs; +int rvat_packtype; - uint32_t rvat_chain_len; - unsigned char *rvat_chain_mem; - fstHandle rvat_chain_facidx; +uint32_t rvat_chain_len; +unsigned char *rvat_chain_mem; +fstHandle rvat_chain_facidx; - uint32_t rvat_chain_pos_tidx; - uint32_t rvat_chain_pos_idx; - uint64_t rvat_chain_pos_time; - unsigned rvat_chain_pos_valid : 1; +uint32_t rvat_chain_pos_tidx; +uint32_t rvat_chain_pos_idx; +uint64_t rvat_chain_pos_time; +unsigned rvat_chain_pos_valid : 1; - /* entries specific to hierarchy traversal */ +/* entries specific to hierarchy traversal */ - struct fstHier hier; - struct fstCurrHier *curr_hier; - fstHandle current_handle; - char *curr_flat_hier_nam; - int flat_hier_alloc_len; - unsigned do_rewind : 1; - char str_scope_nam[FST_ID_NAM_SIZ + 1]; - char str_scope_comp[FST_ID_NAM_SIZ + 1]; +struct fstHier hier; +struct fstCurrHier *curr_hier; +fstHandle current_handle; +char *curr_flat_hier_nam; +int flat_hier_alloc_len; +unsigned do_rewind : 1; +char str_scope_nam[FST_ID_NAM_SIZ+1]; +char str_scope_comp[FST_ID_NAM_SIZ+1]; +char *str_scope_attr; - unsigned fseek_failed : 1; +unsigned fseek_failed : 1; - /* self-buffered I/O for writes */ +/* self-buffered I/O for writes */ #ifndef FST_WRITEX_DISABLE - int writex_pos; - int writex_fd; - unsigned char writex_buf[FST_WRITEX_MAX]; +int writex_pos; +int writex_fd; +unsigned char writex_buf[FST_WRITEX_MAX]; #endif - char *f_nam; - char *fh_nam; +char *f_nam; +char *fh_nam; }; + int fstReaderFseeko(struct fstReaderContext *xc, FILE *stream, fst_off_t offset, int whence) { - int rc = fseeko(stream, offset, whence); +int rc = fseeko(stream, offset, whence); - if (rc < 0) { +if(rc<0) + { xc->fseek_failed = 1; #ifdef FST_DEBUG fprintf(stderr, FST_APIMESS "Seek to #%" PRId64 " (whence = %d) failed!\n", offset, whence); perror("Why"); #endif - } + } - return (rc); +return(rc); } + #ifndef FST_WRITEX_DISABLE -static void fstWritex(struct fstReaderContext *xc, void *v, int len) +static void fstWritex(struct fstReaderContext *xc, void *v, uint32_t len) /* TALOS-2023-1793: change len to unsigned */ { - unsigned char *s = (unsigned char *)v; +unsigned char *s = (unsigned char *)v; - if (len) { - if (len < FST_WRITEX_MAX) { - if (xc->writex_pos + len >= FST_WRITEX_MAX) { +if(len) + { + if(len < FST_WRITEX_MAX) + { + if(xc->writex_pos + len >= FST_WRITEX_MAX) + { + fstWritex(xc, NULL, 0); + } + + memcpy(xc->writex_buf + xc->writex_pos, s, len); + xc->writex_pos += len; + } + else + { fstWritex(xc, NULL, 0); - } - - memcpy(xc->writex_buf + xc->writex_pos, s, len); - xc->writex_pos += len; - } else { - fstWritex(xc, NULL, 0); - if (write(xc->writex_fd, s, len)) { - }; + if (write(xc->writex_fd, s, len)) { }; + } } - } else { - if (xc->writex_pos) { - if (write(xc->writex_fd, xc->writex_buf, xc->writex_pos)) { - }; - xc->writex_pos = 0; + else + { + if(xc->writex_pos) + { + if(write(xc->writex_fd, xc->writex_buf, xc->writex_pos)) { }; + xc->writex_pos = 0; + } } - } } #endif + /* * scope -> flat name handling */ static void fstReaderDeallocateScopeData(struct fstReaderContext *xc) { - struct fstCurrHier *chp; +struct fstCurrHier *chp; - free(xc->curr_flat_hier_nam); - xc->curr_flat_hier_nam = NULL; - while (xc->curr_hier) { +free(xc->curr_flat_hier_nam); xc->curr_flat_hier_nam = NULL; +while(xc->curr_hier) + { chp = xc->curr_hier->prev; free(xc->curr_hier); xc->curr_hier = chp; - } + } } + const char *fstReaderGetCurrentFlatScope(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc) { - return (xc->curr_flat_hier_nam ? xc->curr_flat_hier_nam : ""); - } else { - return (NULL); - } +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +if(xc) + { + return(xc->curr_flat_hier_nam ? xc->curr_flat_hier_nam : ""); + } + else + { + return(NULL); + } } + void *fstReaderGetCurrentScopeUserInfo(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc) { - return (xc->curr_hier ? xc->curr_hier->user_info : NULL); - } else { - return (NULL); - } +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +if(xc) + { + return(xc->curr_hier ? xc->curr_hier->user_info : NULL); + } + else + { + return(NULL); + } } + const char *fstReaderPopScope(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc && xc->curr_hier) { +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +if(xc && xc->curr_hier) + { struct fstCurrHier *ch = xc->curr_hier; - if (xc->curr_hier->prev) { - xc->curr_flat_hier_nam[xc->curr_hier->prev->len] = 0; - } else { - *xc->curr_flat_hier_nam = 0; - } + if(xc->curr_hier->prev) + { + xc->curr_flat_hier_nam[xc->curr_hier->prev->len] = 0; + } + else + { + *xc->curr_flat_hier_nam = 0; + } xc->curr_hier = xc->curr_hier->prev; free(ch); - return (xc->curr_flat_hier_nam ? xc->curr_flat_hier_nam : ""); - } + return(xc->curr_flat_hier_nam ? xc->curr_flat_hier_nam : ""); + } - return (NULL); +return(NULL); } + void fstReaderResetScope(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc) { - while (fstReaderPopScope(xc)) - ; /* remove any already-built scoping info */ - } +if(xc) + { + while(fstReaderPopScope(xc)); /* remove any already-built scoping info */ + } } + const char *fstReaderPushScope(void *ctx, const char *nam, void *user_info) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc) { +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +if(xc) + { struct fstCurrHier *ch = (struct fstCurrHier *)malloc(sizeof(struct fstCurrHier)); int chl = xc->curr_hier ? xc->curr_hier->len : 0; int len = chl + 1 + strlen(nam); - if (len >= xc->flat_hier_alloc_len) { - xc->curr_flat_hier_nam = - xc->curr_flat_hier_nam ? (char *)realloc(xc->curr_flat_hier_nam, len + 1) : (char *)malloc(len + 1); - } + if(len >= xc->flat_hier_alloc_len) + { + xc->curr_flat_hier_nam = xc->curr_flat_hier_nam ? (char *)realloc(xc->curr_flat_hier_nam, len+1) : (char *)malloc(len+1); + } - if (chl) { - xc->curr_flat_hier_nam[chl] = '.'; - strcpy(xc->curr_flat_hier_nam + chl + 1, nam); - } else { - strcpy(xc->curr_flat_hier_nam, nam); - len--; - } + if(chl) + { + xc->curr_flat_hier_nam[chl] = '.'; + strcpy(xc->curr_flat_hier_nam + chl + 1, nam); + } + else + { + strcpy(xc->curr_flat_hier_nam, nam); + len--; + } ch->len = len; ch->prev = xc->curr_hier; ch->user_info = user_info; xc->curr_hier = ch; - return (xc->curr_flat_hier_nam); - } + return(xc->curr_flat_hier_nam); + } - return (NULL); +return(NULL); } + int fstReaderGetCurrentScopeLen(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc && xc->curr_hier) { - return (xc->curr_hier->len); - } +if(xc && xc->curr_hier) + { + return(xc->curr_hier->len); + } - return (0); +return(0); } + int fstReaderGetFseekFailed(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc) { - return (xc->fseek_failed != 0); - } +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +if(xc) + { + return(xc->fseek_failed != 0); + } - return (0); +return(0); } + /* * iter mask manipulation util functions */ int fstReaderGetFacProcessMask(void *ctx, fstHandle facidx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc) { +if(xc) + { facidx--; - if (facidx < xc->maxhandle) { - int process_idx = facidx / 8; - int process_bit = facidx & 7; + if(facidxmaxhandle) + { + int process_idx = facidx/8; + int process_bit = facidx&7; - return ((xc->process_mask[process_idx] & (1 << process_bit)) != 0); + return( (xc->process_mask[process_idx]&(1<maxhandle) { - int idx = facidx / 8; - int bitpos = facidx & 7; + if(facidxmaxhandle) + { + int idx = facidx/8; + int bitpos = facidx&7; - xc->process_mask[idx] |= (1 << bitpos); + xc->process_mask[idx] |= (1<maxhandle) { - int idx = facidx / 8; - int bitpos = facidx & 7; + if(facidxmaxhandle) + { + int idx = facidx/8; + int bitpos = facidx&7; - xc->process_mask[idx] &= (~(1 << bitpos)); + xc->process_mask[idx] &= (~(1<process_mask, 0xff, (xc->maxhandle + 7) / 8); - } +if(xc) + { + memset(xc->process_mask, 0xff, (xc->maxhandle+7)/8); + } } + void fstReaderClrFacProcessMaskAll(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc) { - memset(xc->process_mask, 0x00, (xc->maxhandle + 7) / 8); - } +if(xc) + { + memset(xc->process_mask, 0x00, (xc->maxhandle+7)/8); + } } + /* * various utility read/write functions */ signed char fstReaderGetTimescale(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? xc->timescale : 0); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? xc->timescale : 0); } + uint64_t fstReaderGetStartTime(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? xc->start_time : 0); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? xc->start_time : 0); } + uint64_t fstReaderGetEndTime(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? xc->end_time : 0); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? xc->end_time : 0); } + uint64_t fstReaderGetMemoryUsedByWriter(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? xc->mem_used_by_writer : 0); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? xc->mem_used_by_writer : 0); } + uint64_t fstReaderGetScopeCount(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? xc->scope_count : 0); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? xc->scope_count : 0); } + uint64_t fstReaderGetVarCount(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? xc->var_count : 0); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? xc->var_count : 0); } + fstHandle fstReaderGetMaxHandle(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? xc->maxhandle : 0); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? xc->maxhandle : 0); } + uint64_t fstReaderGetAliasCount(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? xc->num_alias : 0); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? xc->num_alias : 0); } + uint64_t fstReaderGetValueChangeSectionCount(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? xc->vc_section_count : 0); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? xc->vc_section_count : 0); } + int fstReaderGetDoubleEndianMatchState(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? xc->double_endian_match : 0); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? xc->double_endian_match : 0); } + const char *fstReaderGetVersionString(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? xc->version : NULL); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? xc->version : NULL); } + const char *fstReaderGetDateString(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? xc->date : NULL); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? xc->date : NULL); } + int fstReaderGetFileType(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? (int)xc->filetype : (int)FST_FT_VERILOG); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? (int)xc->filetype : (int)FST_FT_VERILOG); } + int64_t fstReaderGetTimezero(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? xc->timezero : 0); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? xc->timezero : 0); } + uint32_t fstReaderGetNumberDumpActivityChanges(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - return (xc ? xc->num_blackouts : 0); +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +return(xc ? xc->num_blackouts : 0); } + uint64_t fstReaderGetDumpActivityChangeTime(void *ctx, uint32_t idx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc && (idx < xc->num_blackouts) && (xc->blackout_times)) { - return (xc->blackout_times[idx]); - } else { - return (0); - } +if(xc && (idx < xc->num_blackouts) && (xc->blackout_times)) + { + return(xc->blackout_times[idx]); + } + else + { + return(0); + } } + unsigned char fstReaderGetDumpActivityChangeValue(void *ctx, uint32_t idx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc && (idx < xc->num_blackouts) && (xc->blackout_activity)) { - return (xc->blackout_activity[idx]); - } else { - return (0); - } +if(xc && (idx < xc->num_blackouts) && (xc->blackout_activity)) + { + return(xc->blackout_activity[idx]); + } + else + { + return(0); + } } + void fstReaderSetLimitTimeRange(void *ctx, uint64_t start_time, uint64_t end_time) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc) { +if(xc) + { xc->limit_range_valid = 1; xc->limit_range_start = start_time; xc->limit_range_end = end_time; - } + } } + void fstReaderSetUnlimitedTimeRange(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc) { +if(xc) + { xc->limit_range_valid = 0; - } + } } + void fstReaderSetVcdExtensions(void *ctx, int enable) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc) { +if(xc) + { xc->use_vcd_extensions = (enable != 0); - } + } } + void fstReaderIterBlocksSetNativeDoublesOnCallback(void *ctx, int enable) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc) { +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +if(xc) + { xc->native_doubles_for_cb = (enable != 0); - } + } } /* @@ -3548,40 +3888,44 @@ void fstReaderIterBlocksSetNativeDoublesOnCallback(void *ctx, int enable) */ static void fstVcdID(char *buf, unsigned int value) { - char *pnt = buf; +char *pnt = buf; - /* zero is illegal for a value...it is assumed they start at one */ - while (value) { +/* zero is illegal for a value...it is assumed they start at one */ +while (value) + { value--; *(pnt++) = (char)('!' + value % 94); value = value / 94; - } + } - *pnt = 0; +*pnt = 0; } static int fstVcdIDForFwrite(char *buf, unsigned int value) { - char *pnt = buf; +char *pnt = buf; - /* zero is illegal for a value...it is assumed they start at one */ - while (value) { +/* zero is illegal for a value...it is assumed they start at one */ +while (value) + { value--; *(pnt++) = (char)('!' + value % 94); value = value / 94; - } + } - return (pnt - buf); +return(pnt - buf); } + static int fstReaderRecreateHierFile(struct fstReaderContext *xc) { - int pass_status = 1; +int pass_status = 1; - if (!xc->fh) { +if(!xc->fh) + { fst_off_t offs_cache = ftello(xc->f); - auto fnam_size = strlen(xc->filename) + 6 + 16 + 32 + 1; - char *fnam = (char *)malloc(fnam_size); + int fnam_len = strlen(xc->filename) + 6 + 16 + 32 + 1; + char *fnam = (char *)malloc(fnam_len); unsigned char *mem = (unsigned char *)malloc(FST_GZIO_LEN); fst_off_t hl, uclen; fst_off_t clen = 0; @@ -3590,643 +3934,666 @@ static int fstReaderRecreateHierFile(struct fstReaderContext *xc) int htyp = FST_BL_SKIP; /* can't handle both set at once should never happen in a real file */ - if (!xc->contains_hier_section_lz4 && xc->contains_hier_section) { - htyp = FST_BL_HIER; - } else if (xc->contains_hier_section_lz4 && !xc->contains_hier_section) { - htyp = xc->contains_hier_section_lz4duo ? FST_BL_HIER_LZ4DUO : FST_BL_HIER_LZ4; - } + if(!xc->contains_hier_section_lz4 && xc->contains_hier_section) + { + htyp = FST_BL_HIER; + } + else + if(xc->contains_hier_section_lz4 && !xc->contains_hier_section) + { + htyp = xc->contains_hier_section_lz4duo ? FST_BL_HIER_LZ4DUO : FST_BL_HIER_LZ4; + } - snprintf(fnam, fnam_size, "%s.hier_%d_%p", xc->filename, getpid(), (void *)xc); + snprintf(fnam, fnam_len, "%s.hier_%d_%p", xc->filename, getpid(), (void *)xc); fstReaderFseeko(xc, xc->f, xc->hier_pos, SEEK_SET); uclen = fstReaderUint64(xc->f); #ifndef __MINGW32__ fflush(xc->f); #endif - if (htyp == FST_BL_HIER) { - fstReaderFseeko(xc, xc->f, xc->hier_pos, SEEK_SET); - uclen = fstReaderUint64(xc->f); + if(htyp == FST_BL_HIER) + { + fstReaderFseeko(xc, xc->f, xc->hier_pos, SEEK_SET); + uclen = fstReaderUint64(xc->f); #ifndef __MINGW32__ - fflush(xc->f); + fflush(xc->f); #endif - zfd = dup(fileno(xc->f)); - lseek(zfd, ftell(xc->f), SEEK_SET); - zhandle = gzdopen(zfd, "rb"); - if (!zhandle) { - close(zfd); - free(mem); - free(fnam); - return (0); - } - } else if ((htyp == FST_BL_HIER_LZ4) || (htyp == FST_BL_HIER_LZ4DUO)) { - fstReaderFseeko(xc, xc->f, xc->hier_pos - 8, SEEK_SET); /* get section len */ - clen = fstReaderUint64(xc->f) - 16; - uclen = fstReaderUint64(xc->f); + zfd = dup(fileno(xc->f)); + zhandle = gzdopen(zfd, "rb"); + if(!zhandle) + { + close(zfd); + free(mem); + free(fnam); + return(0); + } + } + else + if((htyp == FST_BL_HIER_LZ4) || (htyp == FST_BL_HIER_LZ4DUO)) + { + fstReaderFseeko(xc, xc->f, xc->hier_pos - 8, SEEK_SET); /* get section len */ + clen = fstReaderUint64(xc->f) - 16; + uclen = fstReaderUint64(xc->f); #ifndef __MINGW32__ - fflush(xc->f); + fflush(xc->f); #endif - } + } #ifndef __MINGW32__ xc->fh = fopen(fnam, "w+b"); - if (!xc->fh) + if(!xc->fh) #endif - { - xc->fh = tmpfile_open(&xc->fh_nam); - free(fnam); - fnam = NULL; - if (!xc->fh) { - tmpfile_close(&xc->fh, &xc->fh_nam); - free(mem); - return (0); - } - } + { + xc->fh = tmpfile_open(&xc->fh_nam); + free(fnam); fnam = NULL; + if(!xc->fh) + { + tmpfile_close(&xc->fh, &xc->fh_nam); + free(mem); + return(0); + } + } #ifndef __MINGW32__ - if (fnam) - unlink(fnam); + if(fnam) unlink(fnam); #endif - if (htyp == FST_BL_HIER) { - for (hl = 0; hl < uclen; hl += FST_GZIO_LEN) { - size_t len = ((uclen - hl) > FST_GZIO_LEN) ? FST_GZIO_LEN : (uclen - hl); - size_t gzreadlen = gzread(zhandle, mem, len); /* rc should equal len... */ - size_t fwlen; + if(htyp == FST_BL_HIER) + { + for(hl = 0; hl < uclen; hl += FST_GZIO_LEN) + { + size_t len = ((uclen - hl) > FST_GZIO_LEN) ? FST_GZIO_LEN : (uclen - hl); + size_t gzreadlen = gzread(zhandle, mem, len); /* rc should equal len... */ + size_t fwlen; - if (gzreadlen != len) { - pass_status = 0; - break; + if(gzreadlen != len) + { + pass_status = 0; + break; + } + + fwlen = fstFwrite(mem, len, 1, xc->fh); + if(fwlen != 1) + { + pass_status = 0; + break; + } + } + gzclose(zhandle); } + else + if(htyp == FST_BL_HIER_LZ4DUO) + { + unsigned char *lz4_cmem = (unsigned char *)malloc(clen); + unsigned char *lz4_ucmem = (unsigned char *)malloc(uclen); + unsigned char *lz4_ucmem2; + uint64_t uclen2; + int skiplen2 = 0; - fwlen = fstFwrite(mem, len, 1, xc->fh); - if (fwlen != 1) { - pass_status = 0; - break; + fstFread(lz4_cmem, clen, 1, xc->f); + + uclen2 = fstGetVarint64(lz4_cmem, &skiplen2); + lz4_ucmem2 = (unsigned char *)malloc(uclen2); + pass_status = (uclen2 == (uint64_t)LZ4_decompress_safe_partial ((char *)lz4_cmem + skiplen2, (char *)lz4_ucmem2, clen - skiplen2, uclen2, uclen2)); + if(pass_status) + { + pass_status = (uclen == LZ4_decompress_safe_partial ((char *)lz4_ucmem2, (char *)lz4_ucmem, uclen2, uclen, uclen)); + + if(fstFwrite(lz4_ucmem, uclen, 1, xc->fh) != 1) + { + pass_status = 0; + } + } + + free(lz4_ucmem2); + free(lz4_ucmem); + free(lz4_cmem); } - } - gzclose(zhandle); - } else if (htyp == FST_BL_HIER_LZ4DUO) { - unsigned char *lz4_cmem = (unsigned char *)malloc(clen); - unsigned char *lz4_ucmem = (unsigned char *)malloc(uclen); - unsigned char *lz4_ucmem2; - uint64_t uclen2; - int skiplen2 = 0; + else + if(htyp == FST_BL_HIER_LZ4) + { + unsigned char *lz4_cmem = (unsigned char *)malloc(clen); + unsigned char *lz4_ucmem = (unsigned char *)malloc(uclen); - fstFread(lz4_cmem, clen, 1, xc->f); + fstFread(lz4_cmem, clen, 1, xc->f); + pass_status = (uclen == LZ4_decompress_safe_partial ((char *)lz4_cmem, (char *)lz4_ucmem, clen, uclen, uclen)); - uclen2 = fstGetVarint64(lz4_cmem, &skiplen2); - lz4_ucmem2 = (unsigned char *)malloc(uclen2); - pass_status = - (uclen2 == (uint64_t)LZ4_decompress_safe_partial((char *)lz4_cmem + skiplen2, (char *)lz4_ucmem2, - clen - skiplen2, uclen2, uclen2)); - if (pass_status) { - pass_status = (uclen == LZ4_decompress_safe_partial((char *)lz4_ucmem2, (char *)lz4_ucmem, uclen2, - uclen, uclen)); + if(fstFwrite(lz4_ucmem, uclen, 1, xc->fh) != 1) + { + pass_status = 0; + } - if (fstFwrite(lz4_ucmem, uclen, 1, xc->fh) != 1) { - pass_status = 0; + free(lz4_ucmem); + free(lz4_cmem); } - } - - free(lz4_ucmem2); - free(lz4_ucmem); - free(lz4_cmem); - } else if (htyp == FST_BL_HIER_LZ4) { - unsigned char *lz4_cmem = (unsigned char *)malloc(clen); - unsigned char *lz4_ucmem = (unsigned char *)malloc(uclen); - - fstFread(lz4_cmem, clen, 1, xc->f); - pass_status = - (uclen == LZ4_decompress_safe_partial((char *)lz4_cmem, (char *)lz4_ucmem, clen, uclen, uclen)); - - if (fstFwrite(lz4_ucmem, uclen, 1, xc->fh) != 1) { + else /* FST_BL_SKIP */ + { pass_status = 0; - } - - free(lz4_ucmem); - free(lz4_cmem); - } else /* FST_BL_SKIP */ - { - pass_status = 0; - if (xc->fh) { - fclose(xc->fh); - xc->fh = NULL; /* needed in case .hier file is missing and there are no hier sections */ - } - } + if(xc->fh) + { + fclose(xc->fh); xc->fh = NULL; /* needed in case .hier file is missing and there are no hier sections */ + } + } free(mem); free(fnam); fstReaderFseeko(xc, xc->f, offs_cache, SEEK_SET); - } + } - return (pass_status); +return(pass_status); } + int fstReaderIterateHierRewind(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - int pass_status = 0; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +int pass_status = 0; - if (xc) { +if(xc) + { pass_status = 1; - if (!xc->fh) { - pass_status = fstReaderRecreateHierFile(xc); - } + if(!xc->fh) + { + pass_status = fstReaderRecreateHierFile(xc); + } xc->do_rewind = 1; - } + } - return (pass_status); +return(pass_status); } + struct fstHier *fstReaderIterateHier(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - int isfeof; - fstHandle alias; - char *pnt; - int ch; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +int isfeof; +fstHandle alias; +char *pnt; +int ch; - if (!xc) - return (NULL); +if(!xc) return(NULL); - if (!xc->fh) { - if (!fstReaderRecreateHierFile(xc)) { - return (NULL); +if(!xc->fh) + { + if(!fstReaderRecreateHierFile(xc)) + { + return(NULL); + } } - } - if (xc->do_rewind) { +if(xc->do_rewind) + { xc->do_rewind = 0; xc->current_handle = 0; fstReaderFseeko(xc, xc->fh, 0, SEEK_SET); clearerr(xc->fh); - } - - if (!(isfeof = feof(xc->fh))) { - int tag = fgetc(xc->fh); - switch (tag) { - case FST_ST_VCD_SCOPE: - xc->hier.htyp = FST_HT_SCOPE; - xc->hier.u.scope.typ = fgetc(xc->fh); - xc->hier.u.scope.name = pnt = xc->str_scope_nam; - while ((ch = fgetc(xc->fh))) { - *(pnt++) = ch; - }; /* scopename */ - *pnt = 0; - xc->hier.u.scope.name_length = pnt - xc->hier.u.scope.name; - - xc->hier.u.scope.component = pnt = xc->str_scope_comp; - while ((ch = fgetc(xc->fh))) { - *(pnt++) = ch; - }; /* scopecomp */ - *pnt = 0; - xc->hier.u.scope.component_length = pnt - xc->hier.u.scope.component; - break; - - case FST_ST_VCD_UPSCOPE: - xc->hier.htyp = FST_HT_UPSCOPE; - break; - - case FST_ST_GEN_ATTRBEGIN: - xc->hier.htyp = FST_HT_ATTRBEGIN; - xc->hier.u.attr.typ = fgetc(xc->fh); - xc->hier.u.attr.subtype = fgetc(xc->fh); - xc->hier.u.attr.name = pnt = xc->str_scope_nam; - while ((ch = fgetc(xc->fh))) { - *(pnt++) = ch; - }; /* scopename */ - *pnt = 0; - xc->hier.u.attr.name_length = pnt - xc->hier.u.scope.name; - - xc->hier.u.attr.arg = fstReaderVarint64(xc->fh); - - if (xc->hier.u.attr.typ == FST_AT_MISC) { - if ((xc->hier.u.attr.subtype == FST_MT_SOURCESTEM) || (xc->hier.u.attr.subtype == FST_MT_SOURCEISTEM)) { - int sidx_skiplen_dummy = 0; - xc->hier.u.attr.arg_from_name = - fstGetVarint64((unsigned char *)xc->str_scope_nam, &sidx_skiplen_dummy); - } - } - break; - - case FST_ST_GEN_ATTREND: - xc->hier.htyp = FST_HT_ATTREND; - break; - - case FST_VT_VCD_EVENT: - case FST_VT_VCD_INTEGER: - case FST_VT_VCD_PARAMETER: - case FST_VT_VCD_REAL: - case FST_VT_VCD_REAL_PARAMETER: - case FST_VT_VCD_REG: - case FST_VT_VCD_SUPPLY0: - case FST_VT_VCD_SUPPLY1: - case FST_VT_VCD_TIME: - case FST_VT_VCD_TRI: - case FST_VT_VCD_TRIAND: - case FST_VT_VCD_TRIOR: - case FST_VT_VCD_TRIREG: - case FST_VT_VCD_TRI0: - case FST_VT_VCD_TRI1: - case FST_VT_VCD_WAND: - case FST_VT_VCD_WIRE: - case FST_VT_VCD_WOR: - case FST_VT_VCD_PORT: - case FST_VT_VCD_SPARRAY: - case FST_VT_VCD_REALTIME: - case FST_VT_GEN_STRING: - case FST_VT_SV_BIT: - case FST_VT_SV_LOGIC: - case FST_VT_SV_INT: - case FST_VT_SV_SHORTINT: - case FST_VT_SV_LONGINT: - case FST_VT_SV_BYTE: - case FST_VT_SV_ENUM: - case FST_VT_SV_SHORTREAL: - xc->hier.htyp = FST_HT_VAR; - xc->hier.u.var.svt_workspace = FST_SVT_NONE; - xc->hier.u.var.sdt_workspace = FST_SDT_NONE; - xc->hier.u.var.sxt_workspace = 0; - xc->hier.u.var.typ = tag; - xc->hier.u.var.direction = fgetc(xc->fh); - xc->hier.u.var.name = pnt = xc->str_scope_nam; - while ((ch = fgetc(xc->fh))) { - *(pnt++) = ch; - }; /* varname */ - *pnt = 0; - xc->hier.u.var.name_length = pnt - xc->hier.u.var.name; - xc->hier.u.var.length = fstReaderVarint32(xc->fh); - if (tag == FST_VT_VCD_PORT) { - xc->hier.u.var.length -= 2; /* removal of delimiting spaces */ - xc->hier.u.var.length /= 3; /* port -> signal size adjust */ - } - - alias = fstReaderVarint32(xc->fh); - - if (!alias) { - xc->current_handle++; - xc->hier.u.var.handle = xc->current_handle; - xc->hier.u.var.is_alias = 0; - } else { - xc->hier.u.var.handle = alias; - xc->hier.u.var.is_alias = 1; - } - - break; - - default: - isfeof = 1; - break; } - } - return (!isfeof ? &xc->hier : NULL); +if(!(isfeof=feof(xc->fh))) + { + int tag = fgetc(xc->fh); + int cl; + switch(tag) + { + case FST_ST_VCD_SCOPE: + xc->hier.htyp = FST_HT_SCOPE; + xc->hier.u.scope.typ = fgetc(xc->fh); + xc->hier.u.scope.name = pnt = xc->str_scope_nam; + cl = 0; + while((ch = fgetc(xc->fh))) + { + if(cl < FST_ID_NAM_SIZ) + { + pnt[cl++] = ch; + } + }; /* scopename */ + pnt[cl] = 0; + xc->hier.u.scope.name_length = cl; + + xc->hier.u.scope.component = pnt = xc->str_scope_comp; + cl = 0; + while((ch = fgetc(xc->fh))) + { + if(cl < FST_ID_NAM_SIZ) + { + pnt[cl++] = ch; + } + }; /* scopecomp */ + pnt[cl] = 0; + xc->hier.u.scope.component_length = cl; + break; + + case FST_ST_VCD_UPSCOPE: + xc->hier.htyp = FST_HT_UPSCOPE; + break; + + case FST_ST_GEN_ATTRBEGIN: + xc->hier.htyp = FST_HT_ATTRBEGIN; + xc->hier.u.attr.typ = fgetc(xc->fh); + xc->hier.u.attr.subtype = fgetc(xc->fh); + if(!xc->str_scope_attr) + { + xc->str_scope_attr = (char *)calloc(1, FST_ID_NAM_ATTR_SIZ+1); + } + xc->hier.u.attr.name = pnt = xc->str_scope_attr; + cl = 0; + while((ch = fgetc(xc->fh))) + { + if(cl < FST_ID_NAM_ATTR_SIZ) + { + pnt[cl++] = ch; + } + }; /* attrname */ + pnt[cl] = 0; + xc->hier.u.attr.name_length = cl; + + xc->hier.u.attr.arg = fstReaderVarint64(xc->fh); + + if(xc->hier.u.attr.typ == FST_AT_MISC) + { + if((xc->hier.u.attr.subtype == FST_MT_SOURCESTEM)||(xc->hier.u.attr.subtype == FST_MT_SOURCEISTEM)) + { + int sidx_skiplen_dummy = 0; + xc->hier.u.attr.arg_from_name = fstGetVarint64((unsigned char *)xc->str_scope_attr, &sidx_skiplen_dummy); + } + } + break; + + case FST_ST_GEN_ATTREND: + xc->hier.htyp = FST_HT_ATTREND; + break; + + case FST_VT_VCD_EVENT: + case FST_VT_VCD_INTEGER: + case FST_VT_VCD_PARAMETER: + case FST_VT_VCD_REAL: + case FST_VT_VCD_REAL_PARAMETER: + case FST_VT_VCD_REG: + case FST_VT_VCD_SUPPLY0: + case FST_VT_VCD_SUPPLY1: + case FST_VT_VCD_TIME: + case FST_VT_VCD_TRI: + case FST_VT_VCD_TRIAND: + case FST_VT_VCD_TRIOR: + case FST_VT_VCD_TRIREG: + case FST_VT_VCD_TRI0: + case FST_VT_VCD_TRI1: + case FST_VT_VCD_WAND: + case FST_VT_VCD_WIRE: + case FST_VT_VCD_WOR: + case FST_VT_VCD_PORT: + case FST_VT_VCD_SPARRAY: + case FST_VT_VCD_REALTIME: + case FST_VT_GEN_STRING: + case FST_VT_SV_BIT: + case FST_VT_SV_LOGIC: + case FST_VT_SV_INT: + case FST_VT_SV_SHORTINT: + case FST_VT_SV_LONGINT: + case FST_VT_SV_BYTE: + case FST_VT_SV_ENUM: + case FST_VT_SV_SHORTREAL: + xc->hier.htyp = FST_HT_VAR; + xc->hier.u.var.svt_workspace = FST_SVT_NONE; + xc->hier.u.var.sdt_workspace = FST_SDT_NONE; + xc->hier.u.var.sxt_workspace = 0; + xc->hier.u.var.typ = tag; + xc->hier.u.var.direction = fgetc(xc->fh); + xc->hier.u.var.name = pnt = xc->str_scope_nam; + cl = 0; + while((ch = fgetc(xc->fh))) + { + if(cl < FST_ID_NAM_SIZ) + { + pnt[cl++] = ch; + } + }; /* varname */ + pnt[cl] = 0; + xc->hier.u.var.name_length = cl; + xc->hier.u.var.length = fstReaderVarint32(xc->fh); + if(tag == FST_VT_VCD_PORT) + { + xc->hier.u.var.length -= 2; /* removal of delimiting spaces */ + xc->hier.u.var.length /= 3; /* port -> signal size adjust */ + } + + alias = fstReaderVarint32(xc->fh); + + if(!alias) + { + xc->current_handle++; + xc->hier.u.var.handle = xc->current_handle; + xc->hier.u.var.is_alias = 0; + } + else + { + xc->hier.u.var.handle = alias; + xc->hier.u.var.is_alias = 1; + } + + break; + + default: + isfeof = 1; + break; + } + } + +return(!isfeof ? &xc->hier : NULL); } + int fstReaderProcessHier(void *ctx, FILE *fv) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - char *str; - char *pnt; - int ch, scopetype; - int vartype; - uint32_t len, alias; - /* uint32_t maxvalpos=0; */ - unsigned int num_signal_dyn = 65536; - int attrtype, subtype; - uint64_t attrarg; - fstHandle maxhandle_scanbuild; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +char *str; +char *pnt; +int ch, scopetype; +int vartype; +uint32_t len, alias; +/* uint32_t maxvalpos=0; */ +unsigned int num_signal_dyn = 65536; +int attrtype, subtype; +uint64_t attrarg; +fstHandle maxhandle_scanbuild; +int cl; - if (!xc) - return (0); +if(!xc) return(0); - xc->longest_signal_value_len = 32; /* arbitrarily set at 32...this is much longer than an expanded double */ +xc->longest_signal_value_len = 32; /* arbitrarily set at 32...this is much longer than an expanded double */ - if (!xc->fh) { - if (!fstReaderRecreateHierFile(xc)) { - return (0); +if(!xc->fh) + { + if(!fstReaderRecreateHierFile(xc)) + { + return(0); + } } - } - str = (char *)malloc(FST_ID_NAM_ATTR_SIZ + 1); +str = (char *)malloc(FST_ID_NAM_ATTR_SIZ+1); - if (fv) { +if(fv) + { char time_dimension[2] = {0, 0}; int time_scale = 1; fprintf(fv, "$date\n\t%s\n$end\n", xc->date); fprintf(fv, "$version\n\t%s\n$end\n", xc->version); - if (xc->timezero) - fprintf(fv, "$timezero\n\t%" PRId64 "\n$end\n", xc->timezero); + if(xc->timezero) fprintf(fv, "$timezero\n\t%" PRId64 "\n$end\n", xc->timezero); - switch (xc->timescale) { - case 2: - time_scale = 100; - time_dimension[0] = 0; - break; - case 1: - time_scale = 10; /* fallthrough */ - case 0: - time_dimension[0] = 0; - break; + switch(xc->timescale) + { + case 2: time_scale = 100; time_dimension[0] = 0; break; + case 1: time_scale = 10; /* fallthrough */ + case 0: time_dimension[0] = 0; break; - case -1: - time_scale = 100; - time_dimension[0] = 'm'; - break; - case -2: - time_scale = 10; /* fallthrough */ - case -3: - time_dimension[0] = 'm'; - break; + case -1: time_scale = 100; time_dimension[0] = 'm'; break; + case -2: time_scale = 10; /* fallthrough */ + case -3: time_dimension[0] = 'm'; break; - case -4: - time_scale = 100; - time_dimension[0] = 'u'; - break; - case -5: - time_scale = 10; /* fallthrough */ - case -6: - time_dimension[0] = 'u'; - break; + case -4: time_scale = 100; time_dimension[0] = 'u'; break; + case -5: time_scale = 10; /* fallthrough */ + case -6: time_dimension[0] = 'u'; break; - case -10: - time_scale = 100; - time_dimension[0] = 'p'; - break; - case -11: - time_scale = 10; /* fallthrough */ - case -12: - time_dimension[0] = 'p'; - break; + case -10: time_scale = 100; time_dimension[0] = 'p'; break; + case -11: time_scale = 10; /* fallthrough */ + case -12: time_dimension[0] = 'p'; break; - case -13: - time_scale = 100; - time_dimension[0] = 'f'; - break; - case -14: - time_scale = 10; /* fallthrough */ - case -15: - time_dimension[0] = 'f'; - break; + case -13: time_scale = 100; time_dimension[0] = 'f'; break; + case -14: time_scale = 10; /* fallthrough */ + case -15: time_dimension[0] = 'f'; break; - case -16: - time_scale = 100; - time_dimension[0] = 'a'; - break; - case -17: - time_scale = 10; /* fallthrough */ - case -18: - time_dimension[0] = 'a'; - break; + case -16: time_scale = 100; time_dimension[0] = 'a'; break; + case -17: time_scale = 10; /* fallthrough */ + case -18: time_dimension[0] = 'a'; break; - case -19: - time_scale = 100; - time_dimension[0] = 'z'; - break; - case -20: - time_scale = 10; /* fallthrough */ - case -21: - time_dimension[0] = 'z'; - break; + case -19: time_scale = 100; time_dimension[0] = 'z'; break; + case -20: time_scale = 10; /* fallthrough */ + case -21: time_dimension[0] = 'z'; break; - case -7: - time_scale = 100; - time_dimension[0] = 'n'; - break; - case -8: - time_scale = 10; /* fallthrough */ - case -9: - default: - time_dimension[0] = 'n'; - break; + case -7: time_scale = 100; time_dimension[0] = 'n'; break; + case -8: time_scale = 10; /* fallthrough */ + case -9: + default: time_dimension[0] = 'n'; break; + } + + if(fv) fprintf(fv, "$timescale\n\t%d%ss\n$end\n", time_scale, time_dimension); } - if (fv) - fprintf(fv, "$timescale\n\t%d%ss\n$end\n", time_scale, time_dimension); - } +xc->maxhandle = 0; +xc->num_alias = 0; - xc->maxhandle = 0; - xc->num_alias = 0; +free(xc->signal_lens); +xc->signal_lens = (uint32_t *)malloc(num_signal_dyn*sizeof(uint32_t)); - free(xc->signal_lens); - xc->signal_lens = (uint32_t *)malloc(num_signal_dyn * sizeof(uint32_t)); +free(xc->signal_typs); +xc->signal_typs = (unsigned char *)malloc(num_signal_dyn*sizeof(unsigned char)); - free(xc->signal_typs); - xc->signal_typs = (unsigned char *)malloc(num_signal_dyn * sizeof(unsigned char)); - - fstReaderFseeko(xc, xc->fh, 0, SEEK_SET); - while (!feof(xc->fh)) { +fstReaderFseeko(xc, xc->fh, 0, SEEK_SET); +while(!feof(xc->fh)) + { int tag = fgetc(xc->fh); - switch (tag) { - case FST_ST_VCD_SCOPE: - scopetype = fgetc(xc->fh); - if ((scopetype < FST_ST_MIN) || (scopetype > FST_ST_MAX)) - scopetype = FST_ST_VCD_MODULE; - pnt = str; - while ((ch = fgetc(xc->fh))) { - *(pnt++) = ch; - }; /* scopename */ - *pnt = 0; - while (fgetc(xc->fh)) { - }; /* scopecomp */ + switch(tag) + { + case FST_ST_VCD_SCOPE: + scopetype = fgetc(xc->fh); + if((scopetype < FST_ST_MIN) || (scopetype > FST_ST_MAX)) scopetype = FST_ST_VCD_MODULE; + pnt = str; + cl = 0; + while((ch = fgetc(xc->fh))) + { + if(cl < FST_ID_NAM_ATTR_SIZ) + { + pnt[cl++] = ch; + } + }; /* scopename */ + pnt[cl] = 0; + while(fgetc(xc->fh)) { }; /* scopecomp */ - if (fv) - fprintf(fv, "$scope %s %s $end\n", modtypes[scopetype], str); - break; + if(fv) fprintf(fv, "$scope %s %s $end\n", modtypes[scopetype], str); + break; - case FST_ST_VCD_UPSCOPE: - if (fv) - fprintf(fv, "$upscope $end\n"); - break; + case FST_ST_VCD_UPSCOPE: + if(fv) fprintf(fv, "$upscope $end\n"); + break; - case FST_ST_GEN_ATTRBEGIN: - attrtype = fgetc(xc->fh); - subtype = fgetc(xc->fh); - pnt = str; - while ((ch = fgetc(xc->fh))) { - *(pnt++) = ch; - }; /* attrname */ - *pnt = 0; + case FST_ST_GEN_ATTRBEGIN: + attrtype = fgetc(xc->fh); + subtype = fgetc(xc->fh); + pnt = str; + cl = 0; + while((ch = fgetc(xc->fh))) + { + if(cl < FST_ID_NAM_ATTR_SIZ) + { + pnt[cl++] = ch; + } + }; /* attrname */ + pnt[cl] = 0; - if (!str[0]) { - strcpy(str, "\"\""); - } + if(!str[0]) { strcpy(str, "\"\""); } - attrarg = fstReaderVarint64(xc->fh); + attrarg = fstReaderVarint64(xc->fh); + + if(fv && xc->use_vcd_extensions) + { + switch(attrtype) + { + case FST_AT_ARRAY: if((subtype < FST_AR_NONE) || (subtype > FST_AR_MAX)) subtype = FST_AR_NONE; + fprintf(fv, "$attrbegin %s %s %s %" PRId64 " $end\n", attrtypes[attrtype], arraytypes[subtype], str, attrarg); + break; + case FST_AT_ENUM: if((subtype < FST_EV_SV_INTEGER) || (subtype > FST_EV_MAX)) subtype = FST_EV_SV_INTEGER; + fprintf(fv, "$attrbegin %s %s %s %" PRId64 " $end\n", attrtypes[attrtype], enumvaluetypes[subtype], str, attrarg); + break; + case FST_AT_PACK: if((subtype < FST_PT_NONE) || (subtype > FST_PT_MAX)) subtype = FST_PT_NONE; + fprintf(fv, "$attrbegin %s %s %s %" PRId64 " $end\n", attrtypes[attrtype], packtypes[subtype], str, attrarg); + break; + case FST_AT_MISC: + default: attrtype = FST_AT_MISC; + if(subtype == FST_MT_COMMENT) + { + fprintf(fv, "$comment\n\t%s\n$end\n", str); + } + else + { + if((subtype == FST_MT_SOURCESTEM)||(subtype == FST_MT_SOURCEISTEM)) + { + int sidx_skiplen_dummy = 0; + uint64_t sidx = fstGetVarint64((unsigned char *)str, &sidx_skiplen_dummy); + + fprintf(fv, "$attrbegin %s %02x %" PRId64 " %" PRId64 " $end\n", attrtypes[attrtype], subtype, sidx, attrarg); + } + else + { + fprintf(fv, "$attrbegin %s %02x %s %" PRId64 " $end\n", attrtypes[attrtype], subtype, str, attrarg); + } + } + break; + } + } + break; + + case FST_ST_GEN_ATTREND: + if(fv && xc->use_vcd_extensions) fprintf(fv, "$attrend $end\n"); + break; + + case FST_VT_VCD_EVENT: + case FST_VT_VCD_INTEGER: + case FST_VT_VCD_PARAMETER: + case FST_VT_VCD_REAL: + case FST_VT_VCD_REAL_PARAMETER: + case FST_VT_VCD_REG: + case FST_VT_VCD_SUPPLY0: + case FST_VT_VCD_SUPPLY1: + case FST_VT_VCD_TIME: + case FST_VT_VCD_TRI: + case FST_VT_VCD_TRIAND: + case FST_VT_VCD_TRIOR: + case FST_VT_VCD_TRIREG: + case FST_VT_VCD_TRI0: + case FST_VT_VCD_TRI1: + case FST_VT_VCD_WAND: + case FST_VT_VCD_WIRE: + case FST_VT_VCD_WOR: + case FST_VT_VCD_PORT: + case FST_VT_VCD_SPARRAY: + case FST_VT_VCD_REALTIME: + case FST_VT_GEN_STRING: + case FST_VT_SV_BIT: + case FST_VT_SV_LOGIC: + case FST_VT_SV_INT: + case FST_VT_SV_SHORTINT: + case FST_VT_SV_LONGINT: + case FST_VT_SV_BYTE: + case FST_VT_SV_ENUM: + case FST_VT_SV_SHORTREAL: + vartype = tag; + /* vardir = */ fgetc(xc->fh); /* unused in VCD reader, but need to advance read pointer */ + pnt = str; + cl = 0; + while((ch = fgetc(xc->fh))) + { + if(cl < FST_ID_NAM_ATTR_SIZ) + { + pnt[cl++] = ch; + } + }; /* varname */ + pnt[cl] = 0; + len = fstReaderVarint32(xc->fh); + alias = fstReaderVarint32(xc->fh); + + if(!alias) + { + if(xc->maxhandle == num_signal_dyn) + { + num_signal_dyn *= 2; + xc->signal_lens = (uint32_t *)realloc(xc->signal_lens, num_signal_dyn*sizeof(uint32_t)); + xc->signal_typs = (unsigned char *)realloc(xc->signal_typs, num_signal_dyn*sizeof(unsigned char)); + } + xc->signal_lens[xc->maxhandle] = len; + xc->signal_typs[xc->maxhandle] = vartype; + + /* maxvalpos+=len; */ + if(len > xc->longest_signal_value_len) + { + xc->longest_signal_value_len = len; + } + + if((vartype == FST_VT_VCD_REAL) || (vartype == FST_VT_VCD_REAL_PARAMETER) || (vartype == FST_VT_VCD_REALTIME) || (vartype == FST_VT_SV_SHORTREAL)) + { + len = (vartype != FST_VT_SV_SHORTREAL) ? 64 : 32; + xc->signal_typs[xc->maxhandle] = FST_VT_VCD_REAL; + } + if(fv) + { + char vcdid_buf[16]; + uint32_t modlen = (vartype != FST_VT_VCD_PORT) ? len : ((len - 2) / 3); + fstVcdID(vcdid_buf, xc->maxhandle+1); + fprintf(fv, "$var %s %" PRIu32 " %s %s $end\n", vartypes[vartype], modlen, vcdid_buf, str); + } + xc->maxhandle++; + } + else + { + if((vartype == FST_VT_VCD_REAL) || (vartype == FST_VT_VCD_REAL_PARAMETER) || (vartype == FST_VT_VCD_REALTIME) || (vartype == FST_VT_SV_SHORTREAL)) + { + len = (vartype != FST_VT_SV_SHORTREAL) ? 64 : 32; + xc->signal_typs[xc->maxhandle] = FST_VT_VCD_REAL; + } + if(fv) + { + char vcdid_buf[16]; + uint32_t modlen = (vartype != FST_VT_VCD_PORT) ? len : ((len - 2) / 3); + fstVcdID(vcdid_buf, alias); + fprintf(fv, "$var %s %" PRIu32 " %s %s $end\n", vartypes[vartype], modlen, vcdid_buf, str); + } + xc->num_alias++; + } + + break; - if (fv && xc->use_vcd_extensions) { - switch (attrtype) { - case FST_AT_ARRAY: - if ((subtype < FST_AR_NONE) || (subtype > FST_AR_MAX)) - subtype = FST_AR_NONE; - fprintf(fv, "$attrbegin %s %s %s %" PRId64 " $end\n", attrtypes[attrtype], arraytypes[subtype], str, - attrarg); - break; - case FST_AT_ENUM: - if ((subtype < FST_EV_SV_INTEGER) || (subtype > FST_EV_MAX)) - subtype = FST_EV_SV_INTEGER; - fprintf(fv, "$attrbegin %s %s %s %" PRId64 " $end\n", attrtypes[attrtype], enumvaluetypes[subtype], - str, attrarg); - break; - case FST_AT_PACK: - if ((subtype < FST_PT_NONE) || (subtype > FST_PT_MAX)) - subtype = FST_PT_NONE; - fprintf(fv, "$attrbegin %s %s %s %" PRId64 " $end\n", attrtypes[attrtype], packtypes[subtype], str, - attrarg); - break; - case FST_AT_MISC: default: - attrtype = FST_AT_MISC; - if (subtype == FST_MT_COMMENT) { - fprintf(fv, "$comment\n\t%s\n$end\n", str); - } else { - if ((subtype == FST_MT_SOURCESTEM) || (subtype == FST_MT_SOURCEISTEM)) { - int sidx_skiplen_dummy = 0; - uint64_t sidx = fstGetVarint64((unsigned char *)str, &sidx_skiplen_dummy); - - fprintf(fv, "$attrbegin %s %02x %" PRId64 " %" PRId64 " $end\n", attrtypes[attrtype], - subtype, sidx, attrarg); - } else { - fprintf(fv, "$attrbegin %s %02x %s %" PRId64 " $end\n", attrtypes[attrtype], subtype, str, - attrarg); - } - } - break; + break; } - } - break; - - case FST_ST_GEN_ATTREND: - if (fv && xc->use_vcd_extensions) - fprintf(fv, "$attrend $end\n"); - break; - - case FST_VT_VCD_EVENT: - case FST_VT_VCD_INTEGER: - case FST_VT_VCD_PARAMETER: - case FST_VT_VCD_REAL: - case FST_VT_VCD_REAL_PARAMETER: - case FST_VT_VCD_REG: - case FST_VT_VCD_SUPPLY0: - case FST_VT_VCD_SUPPLY1: - case FST_VT_VCD_TIME: - case FST_VT_VCD_TRI: - case FST_VT_VCD_TRIAND: - case FST_VT_VCD_TRIOR: - case FST_VT_VCD_TRIREG: - case FST_VT_VCD_TRI0: - case FST_VT_VCD_TRI1: - case FST_VT_VCD_WAND: - case FST_VT_VCD_WIRE: - case FST_VT_VCD_WOR: - case FST_VT_VCD_PORT: - case FST_VT_VCD_SPARRAY: - case FST_VT_VCD_REALTIME: - case FST_VT_GEN_STRING: - case FST_VT_SV_BIT: - case FST_VT_SV_LOGIC: - case FST_VT_SV_INT: - case FST_VT_SV_SHORTINT: - case FST_VT_SV_LONGINT: - case FST_VT_SV_BYTE: - case FST_VT_SV_ENUM: - case FST_VT_SV_SHORTREAL: - vartype = tag; - /* vardir = */ fgetc(xc->fh); /* unused in VCD reader, but need to advance read pointer */ - pnt = str; - while ((ch = fgetc(xc->fh))) { - *(pnt++) = ch; - }; /* varname */ - *pnt = 0; - len = fstReaderVarint32(xc->fh); - alias = fstReaderVarint32(xc->fh); - - if (!alias) { - if (xc->maxhandle == num_signal_dyn) { - num_signal_dyn *= 2; - xc->signal_lens = (uint32_t *)realloc(xc->signal_lens, num_signal_dyn * sizeof(uint32_t)); - xc->signal_typs = (unsigned char *)realloc(xc->signal_typs, num_signal_dyn * sizeof(unsigned char)); - } - xc->signal_lens[xc->maxhandle] = len; - xc->signal_typs[xc->maxhandle] = vartype; - - /* maxvalpos+=len; */ - if (len > xc->longest_signal_value_len) { - xc->longest_signal_value_len = len; - } - - if ((vartype == FST_VT_VCD_REAL) || (vartype == FST_VT_VCD_REAL_PARAMETER) || - (vartype == FST_VT_VCD_REALTIME) || (vartype == FST_VT_SV_SHORTREAL)) { - len = (vartype != FST_VT_SV_SHORTREAL) ? 64 : 32; - xc->signal_typs[xc->maxhandle] = FST_VT_VCD_REAL; - } - if (fv) { - char vcdid_buf[16]; - uint32_t modlen = (vartype != FST_VT_VCD_PORT) ? len : ((len - 2) / 3); - fstVcdID(vcdid_buf, xc->maxhandle + 1); - fprintf(fv, "$var %s %" PRIu32 " %s %s $end\n", vartypes[vartype], modlen, vcdid_buf, str); - } - xc->maxhandle++; - } else { - if ((vartype == FST_VT_VCD_REAL) || (vartype == FST_VT_VCD_REAL_PARAMETER) || - (vartype == FST_VT_VCD_REALTIME) || (vartype == FST_VT_SV_SHORTREAL)) { - len = (vartype != FST_VT_SV_SHORTREAL) ? 64 : 32; - xc->signal_typs[xc->maxhandle] = FST_VT_VCD_REAL; - } - if (fv) { - char vcdid_buf[16]; - uint32_t modlen = (vartype != FST_VT_VCD_PORT) ? len : ((len - 2) / 3); - fstVcdID(vcdid_buf, alias); - fprintf(fv, "$var %s %" PRIu32 " %s %s $end\n", vartypes[vartype], modlen, vcdid_buf, str); - } - xc->num_alias++; - } - - break; - - default: - break; } - } - if (fv) - fprintf(fv, "$enddefinitions $end\n"); +if(fv) fprintf(fv, "$enddefinitions $end\n"); - maxhandle_scanbuild = xc->maxhandle ? xc->maxhandle - : 1; /*scan-build warning suppression, in reality we have at least one signal */ +maxhandle_scanbuild = xc->maxhandle ? xc->maxhandle : 1; /*scan-build warning suppression, in reality we have at least one signal */ - xc->signal_lens = (uint32_t *)realloc(xc->signal_lens, maxhandle_scanbuild * sizeof(uint32_t)); - xc->signal_typs = (unsigned char *)realloc(xc->signal_typs, maxhandle_scanbuild * sizeof(unsigned char)); +xc->signal_lens = (uint32_t *)realloc(xc->signal_lens, maxhandle_scanbuild*sizeof(uint32_t)); +xc->signal_typs = (unsigned char *)realloc(xc->signal_typs, maxhandle_scanbuild*sizeof(unsigned char)); - free(xc->process_mask); - xc->process_mask = (unsigned char *)calloc(1, (maxhandle_scanbuild + 7) / 8); +free(xc->process_mask); +xc->process_mask = (unsigned char *)calloc(1, (maxhandle_scanbuild+7)/8); - free(xc->temp_signal_value_buf); - xc->temp_signal_value_buf = (unsigned char *)malloc(xc->longest_signal_value_len + 1); +free(xc->temp_signal_value_buf); +xc->temp_signal_value_buf = (unsigned char *)malloc(xc->longest_signal_value_len + 1); - xc->var_count = xc->maxhandle + xc->num_alias; +xc->var_count = xc->maxhandle + xc->num_alias; - free(str); - return (1); +free(str); +return(1); } + /* * reader file open/close functions */ int fstReaderInit(struct fstReaderContext *xc) { - fst_off_t blkpos = 0; - fst_off_t endfile; - uint64_t seclen; - int sectype; - uint64_t vc_section_count_actual = 0; - int hdr_incomplete = 0; - int hdr_seen = 0; - int gzread_pass_status = 1; +fst_off_t blkpos = 0; +fst_off_t endfile; +uint64_t seclen; +int sectype; +uint64_t vc_section_count_actual = 0; +int hdr_incomplete = 0; +int hdr_seen = 0; +int gzread_pass_status = 1; - sectype = fgetc(xc->f); - if (sectype == FST_BL_ZWRAPPER) { +sectype = fgetc(xc->f); +if(sectype == FST_BL_ZWRAPPER) + { FILE *fcomp; fst_off_t offpnt, uclen; char gz_membuf[FST_GZIO_LEN]; @@ -4234,292 +4601,334 @@ int fstReaderInit(struct fstReaderContext *xc) int zfd; int flen = strlen(xc->filename); char *hf; + int hf_len; seclen = fstReaderUint64(xc->f); uclen = fstReaderUint64(xc->f); - if (!seclen) - return (0); /* not finished compressing, this is a failed read */ + if(!seclen) return(0); /* not finished compressing, this is a failed read */ - size_t hf_size = flen + 16 + 32 + 1; - hf = (char *)calloc(1, hf_size); + hf_len = flen + 16 + 32 + 1; + hf = (char *)calloc(1, hf_len); - snprintf(hf, hf_size, "%s.upk_%d_%p", xc->filename, getpid(), (void *)xc); + snprintf(hf, hf_len, "%s.upk_%d_%p", xc->filename, getpid(), (void *)xc); fcomp = fopen(hf, "w+b"); - if (!fcomp) { - fcomp = tmpfile_open(&xc->f_nam); - free(hf); - hf = NULL; - if (!fcomp) { - tmpfile_close(&fcomp, &xc->f_nam); - return (0); - } - } + if(!fcomp) + { + fcomp = tmpfile_open(&xc->f_nam); + free(hf); hf = NULL; + if(!fcomp) { tmpfile_close(&fcomp, &xc->f_nam); return(0); } + } -#if defined(FST_MACOSX) - setvbuf(fcomp, (char *)NULL, _IONBF, 0); /* keeps gzip from acting weird in tandem with fopen */ +#if defined(FST_UNBUFFERED_IO) + setvbuf(fcomp, (char *)NULL, _IONBF, 0); /* keeps gzip from acting weird in tandem with fopen */ #endif #ifdef __MINGW32__ - setvbuf(fcomp, (char *)NULL, _IONBF, 0); /* keeps gzip from acting weird in tandem with fopen */ xc->filename_unpacked = hf; #else - if (hf) { - unlink(hf); - free(hf); - } + if(hf) + { + unlink(hf); + free(hf); + } #endif - fstReaderFseeko(xc, xc->f, 1 + 8 + 8, SEEK_SET); + fstReaderFseeko(xc, xc->f, FST_ZWRAPPER_HDR_SIZE, SEEK_SET); #ifndef __MINGW32__ fflush(xc->f); +#else + /* Windows UCRT runtime library reads one byte ahead in the file + even with buffering disabled and does not synchronise the + file position after fseek. */ + _lseek(fileno(xc->f), FST_ZWRAPPER_HDR_SIZE, SEEK_SET); #endif zfd = dup(fileno(xc->f)); - lseek(zfd, ftell(xc->f), SEEK_SET); zhandle = gzdopen(zfd, "rb"); - if (zhandle) { - for (offpnt = 0; offpnt < uclen; offpnt += FST_GZIO_LEN) { - size_t this_len = ((uclen - offpnt) > FST_GZIO_LEN) ? FST_GZIO_LEN : (uclen - offpnt); - size_t gzreadlen = gzread(zhandle, gz_membuf, this_len); - size_t fwlen; + if(zhandle) + { + for(offpnt = 0; offpnt < uclen; offpnt += FST_GZIO_LEN) + { + size_t this_len = ((uclen - offpnt) > FST_GZIO_LEN) ? FST_GZIO_LEN : (uclen - offpnt); + size_t gzreadlen = gzread(zhandle, gz_membuf, this_len); + size_t fwlen; - if (gzreadlen != this_len) { - gzread_pass_status = 0; - break; + if(gzreadlen != this_len) + { + gzread_pass_status = 0; + break; + } + fwlen = fstFwrite(gz_membuf, this_len, 1, fcomp); + if(fwlen != 1) + { + gzread_pass_status = 0; + break; + } + } + gzclose(zhandle); } - fwlen = fstFwrite(gz_membuf, this_len, 1, fcomp); - if (fwlen != 1) { - gzread_pass_status = 0; - break; + else + { + close(zfd); } - } - gzclose(zhandle); - } else { - close(zfd); - } fflush(fcomp); fclose(xc->f); xc->f = fcomp; - } + } - if (gzread_pass_status) { +if(gzread_pass_status) + { fstReaderFseeko(xc, xc->f, 0, SEEK_END); endfile = ftello(xc->f); - while (blkpos < endfile) { - fstReaderFseeko(xc, xc->f, blkpos, SEEK_SET); + while(blkpos < endfile) + { + fstReaderFseeko(xc, xc->f, blkpos, SEEK_SET); - sectype = fgetc(xc->f); - seclen = fstReaderUint64(xc->f); + sectype = fgetc(xc->f); + seclen = fstReaderUint64(xc->f); - if (sectype == EOF) { - break; - } - - if ((hdr_incomplete) && (!seclen)) { - break; - } - - if (!hdr_seen && (sectype != FST_BL_HDR)) { - break; - } - - blkpos++; - if (sectype == FST_BL_HDR) { - if (!hdr_seen) { - int ch; - double dcheck; - - xc->start_time = fstReaderUint64(xc->f); - xc->end_time = fstReaderUint64(xc->f); - - hdr_incomplete = (xc->start_time == 0) && (xc->end_time == 0); - - fstFread(&dcheck, 8, 1, xc->f); - xc->double_endian_match = (dcheck == (double)FST_DOUBLE_ENDTEST); - if (!xc->double_endian_match) { - union + if(sectype == EOF) { - unsigned char rvs_buf[8]; - double d; - } vu; - - unsigned char *dcheck_alias = (unsigned char *)&dcheck; - int rvs_idx; - - for (rvs_idx = 0; rvs_idx < 8; rvs_idx++) { - vu.rvs_buf[rvs_idx] = dcheck_alias[7 - rvs_idx]; - } - if (vu.d != FST_DOUBLE_ENDTEST) { - break; /* either corrupt file or wrong architecture (offset +33 also functions as matchword) - */ - } - } - - hdr_seen = 1; - - xc->mem_used_by_writer = fstReaderUint64(xc->f); - xc->scope_count = fstReaderUint64(xc->f); - xc->var_count = fstReaderUint64(xc->f); - xc->maxhandle = fstReaderUint64(xc->f); - xc->num_alias = xc->var_count - xc->maxhandle; - xc->vc_section_count = fstReaderUint64(xc->f); - ch = fgetc(xc->f); - xc->timescale = (signed char)ch; - fstFread(xc->version, FST_HDR_SIM_VERSION_SIZE, 1, xc->f); - xc->version[FST_HDR_SIM_VERSION_SIZE] = 0; - fstFread(xc->date, FST_HDR_DATE_SIZE, 1, xc->f); - xc->date[FST_HDR_DATE_SIZE] = 0; - ch = fgetc(xc->f); - xc->filetype = (unsigned char)ch; - xc->timezero = fstReaderUint64(xc->f); - } - } else if ((sectype == FST_BL_VCDATA) || (sectype == FST_BL_VCDATA_DYN_ALIAS) || - (sectype == FST_BL_VCDATA_DYN_ALIAS2)) { - if (hdr_incomplete) { - uint64_t bt = fstReaderUint64(xc->f); - xc->end_time = fstReaderUint64(xc->f); - - if (!vc_section_count_actual) { - xc->start_time = bt; - } - } - - vc_section_count_actual++; - } else if (sectype == FST_BL_GEOM) { - if (!hdr_incomplete) { - uint64_t clen = seclen - 24; - uint64_t uclen = fstReaderUint64(xc->f); - unsigned char *ucdata = (unsigned char *)malloc(uclen); - unsigned char *pnt = ucdata; - unsigned int i; - - xc->contains_geom_section = 1; - xc->maxhandle = fstReaderUint64(xc->f); - xc->longest_signal_value_len = - 32; /* arbitrarily set at 32...this is much longer than an expanded double */ - - free(xc->process_mask); - xc->process_mask = (unsigned char *)calloc(1, (xc->maxhandle + 7) / 8); - - if (clen != uclen) { - unsigned char *cdata = (unsigned char *)malloc(clen); - unsigned long destlen = uclen; - unsigned long sourcelen = clen; - int rc; - - fstFread(cdata, clen, 1, xc->f); - rc = uncompress(ucdata, &destlen, cdata, sourcelen); - - if (rc != Z_OK) { - fprintf(stderr, FST_APIMESS "fstReaderInit(), geom uncompress rc = %d, exiting.\n", rc); - exit(255); + break; } - free(cdata); - } else { - fstFread(ucdata, uclen, 1, xc->f); - } - - free(xc->signal_lens); - xc->signal_lens = (uint32_t *)malloc(sizeof(uint32_t) * xc->maxhandle); - free(xc->signal_typs); - xc->signal_typs = (unsigned char *)malloc(sizeof(unsigned char) * xc->maxhandle); - - for (i = 0; i < xc->maxhandle; i++) { - int skiplen; - uint64_t val = fstGetVarint32(pnt, &skiplen); - - pnt += skiplen; - - if (val) { - xc->signal_lens[i] = (val != 0xFFFFFFFF) ? val : 0; - xc->signal_typs[i] = FST_VT_VCD_WIRE; - if (xc->signal_lens[i] > xc->longest_signal_value_len) { - xc->longest_signal_value_len = xc->signal_lens[i]; - } - } else { - xc->signal_lens[i] = 8; /* backpatch in real */ - xc->signal_typs[i] = FST_VT_VCD_REAL; - /* xc->longest_signal_value_len handled above by overly large init size */ + if((hdr_incomplete) && (!seclen)) + { + break; } - } - free(xc->temp_signal_value_buf); - xc->temp_signal_value_buf = (unsigned char *)malloc(xc->longest_signal_value_len + 1); + if(!hdr_seen && (sectype != FST_BL_HDR)) + { + break; + } - free(ucdata); + blkpos++; + if(sectype == FST_BL_HDR) + { + if(!hdr_seen) + { + int ch; + double dcheck; + + xc->start_time = fstReaderUint64(xc->f); + xc->end_time = fstReaderUint64(xc->f); + + hdr_incomplete = (xc->start_time == 0) && (xc->end_time == 0); + + fstFread(&dcheck, 8, 1, xc->f); + xc->double_endian_match = (dcheck == FST_DOUBLE_ENDTEST); + if(!xc->double_endian_match) + { + union { + unsigned char rvs_buf[8]; + double d; + } vu; + + unsigned char *dcheck_alias = (unsigned char *)&dcheck; + int rvs_idx; + + for(rvs_idx=0;rvs_idx<8;rvs_idx++) + { + vu.rvs_buf[rvs_idx] = dcheck_alias[7-rvs_idx]; + } + if(vu.d != FST_DOUBLE_ENDTEST) + { + break; /* either corrupt file or wrong architecture (offset +33 also functions as matchword) */ + } + } + + hdr_seen = 1; + + xc->mem_used_by_writer = fstReaderUint64(xc->f); + xc->scope_count = fstReaderUint64(xc->f); + xc->var_count = fstReaderUint64(xc->f); + xc->maxhandle = fstReaderUint64(xc->f); + xc->num_alias = xc->var_count - xc->maxhandle; + xc->vc_section_count = fstReaderUint64(xc->f); + ch = fgetc(xc->f); + xc->timescale = (signed char)ch; + fstFread(xc->version, FST_HDR_SIM_VERSION_SIZE, 1, xc->f); + xc->version[FST_HDR_SIM_VERSION_SIZE] = 0; + fstFread(xc->date, FST_HDR_DATE_SIZE, 1, xc->f); + xc->date[FST_HDR_DATE_SIZE] = 0; + ch = fgetc(xc->f); + xc->filetype = (unsigned char)ch; + xc->timezero = fstReaderUint64(xc->f); + } + } + else if((sectype == FST_BL_VCDATA) || (sectype == FST_BL_VCDATA_DYN_ALIAS) || (sectype == FST_BL_VCDATA_DYN_ALIAS2)) + { + if(hdr_incomplete) + { + uint64_t bt = fstReaderUint64(xc->f); + xc->end_time = fstReaderUint64(xc->f); + + if(!vc_section_count_actual) { xc->start_time = bt; } + } + + vc_section_count_actual++; + } + else if(sectype == FST_BL_GEOM) + { + if(!hdr_incomplete) + { + uint64_t clen = seclen - 24; + uint64_t uclen = fstReaderUint64(xc->f); + unsigned char *ucdata = (unsigned char *)malloc(uclen); + unsigned char *pnt = ucdata; + unsigned int i; + + xc->contains_geom_section = 1; + xc->maxhandle = fstReaderUint64(xc->f); + xc->longest_signal_value_len = 32; /* arbitrarily set at 32...this is much longer than an expanded double */ + + free(xc->process_mask); + xc->process_mask = (unsigned char *)calloc(1, (xc->maxhandle+7)/8); + + if(clen != uclen) + { + unsigned char *cdata = (unsigned char *)malloc(clen); + unsigned long destlen = uclen; + unsigned long sourcelen = clen; + int rc; + + fstFread(cdata, clen, 1, xc->f); + rc = uncompress(ucdata, &destlen, cdata, sourcelen); + + if(rc != Z_OK) + { + fprintf(stderr, FST_APIMESS "fstReaderInit(), geom uncompress rc = %d, exiting.\n", rc); + exit(255); + } + + free(cdata); + } + else + { + fstFread(ucdata, uclen, 1, xc->f); + } + + free(xc->signal_lens); + xc->signal_lens = (uint32_t *)malloc(sizeof(uint32_t) * xc->maxhandle); + free(xc->signal_typs); + xc->signal_typs = (unsigned char *)malloc(sizeof(unsigned char) * xc->maxhandle); + + for(i=0;imaxhandle;i++) + { + int skiplen; + uint64_t val = fstGetVarint32(pnt, &skiplen); + + pnt += skiplen; + + if(val) + { + xc->signal_lens[i] = (val != 0xFFFFFFFF) ? val : 0; + xc->signal_typs[i] = FST_VT_VCD_WIRE; + if(xc->signal_lens[i] > xc->longest_signal_value_len) + { + xc->longest_signal_value_len = xc->signal_lens[i]; + } + } + else + { + xc->signal_lens[i] = 8; /* backpatch in real */ + xc->signal_typs[i] = FST_VT_VCD_REAL; + /* xc->longest_signal_value_len handled above by overly large init size */ + } + } + + free(xc->temp_signal_value_buf); + xc->temp_signal_value_buf = (unsigned char *)malloc(xc->longest_signal_value_len + 1); + + free(ucdata); + } + } + else if(sectype == FST_BL_HIER) + { + xc->contains_hier_section = 1; + xc->hier_pos = ftello(xc->f); + } + else if(sectype == FST_BL_HIER_LZ4DUO) + { + xc->contains_hier_section_lz4 = 1; + xc->contains_hier_section_lz4duo = 1; + xc->hier_pos = ftello(xc->f); + } + else if(sectype == FST_BL_HIER_LZ4) + { + xc->contains_hier_section_lz4 = 1; + xc->hier_pos = ftello(xc->f); + } + else if(sectype == FST_BL_BLACKOUT) + { + uint32_t i; + uint64_t cur_bl = 0; + uint64_t delta; + + xc->num_blackouts = fstReaderVarint32(xc->f); + free(xc->blackout_times); + xc->blackout_times = (uint64_t *)calloc(xc->num_blackouts, sizeof(uint64_t)); + free(xc->blackout_activity); + xc->blackout_activity = (unsigned char *)calloc(xc->num_blackouts, sizeof(unsigned char)); + + for(i=0;inum_blackouts;i++) + { + xc->blackout_activity[i] = fgetc(xc->f) != 0; + delta = fstReaderVarint64(xc->f); + cur_bl += delta; + xc->blackout_times[i] = cur_bl; + } + } + + blkpos += seclen; + if(!hdr_seen) break; } - } else if (sectype == FST_BL_HIER) { - xc->contains_hier_section = 1; - xc->hier_pos = ftello(xc->f); - } else if (sectype == FST_BL_HIER_LZ4DUO) { - xc->contains_hier_section_lz4 = 1; - xc->contains_hier_section_lz4duo = 1; - xc->hier_pos = ftello(xc->f); - } else if (sectype == FST_BL_HIER_LZ4) { - xc->contains_hier_section_lz4 = 1; - xc->hier_pos = ftello(xc->f); - } else if (sectype == FST_BL_BLACKOUT) { - uint32_t i; - uint64_t cur_bl = 0; - uint64_t delta; - xc->num_blackouts = fstReaderVarint32(xc->f); - free(xc->blackout_times); - xc->blackout_times = (uint64_t *)calloc(xc->num_blackouts, sizeof(uint64_t)); - free(xc->blackout_activity); - xc->blackout_activity = (unsigned char *)calloc(xc->num_blackouts, sizeof(unsigned char)); + if(hdr_seen) + { + if(xc->vc_section_count != vc_section_count_actual) + { + xc->vc_section_count = vc_section_count_actual; + } - for (i = 0; i < xc->num_blackouts; i++) { - xc->blackout_activity[i] = fgetc(xc->f) != 0; - delta = fstReaderVarint64(xc->f); - cur_bl += delta; - xc->blackout_times[i] = cur_bl; + if(!xc->contains_geom_section) + { + fstReaderProcessHier(xc, NULL); /* recreate signal_lens/signal_typs info */ + } } - } - - blkpos += seclen; - if (!hdr_seen) - break; } - if (hdr_seen) { - if (xc->vc_section_count != vc_section_count_actual) { - xc->vc_section_count = vc_section_count_actual; - } - - if (!xc->contains_geom_section) { - fstReaderProcessHier(xc, NULL); /* recreate signal_lens/signal_typs info */ - } - } - } - - return (hdr_seen); +return(hdr_seen); } + void *fstReaderOpenForUtilitiesOnly(void) { - struct fstReaderContext *xc = (struct fstReaderContext *)calloc(1, sizeof(struct fstReaderContext)); +struct fstReaderContext *xc = (struct fstReaderContext *)calloc(1, sizeof(struct fstReaderContext)); - return (xc); +return(xc); } + void *fstReaderOpen(const char *nam) { - struct fstReaderContext *xc = (struct fstReaderContext *)calloc(1, sizeof(struct fstReaderContext)); +struct fstReaderContext *xc = (struct fstReaderContext *)calloc(1, sizeof(struct fstReaderContext)); - if ((!nam) || (!(xc->f = fopen(nam, "rb")))) { +if((!nam)||(!(xc->f=fopen(nam, "rb")))) + { free(xc); - xc = NULL; - } else { + xc=NULL; + } + else + { int flen = strlen(nam); char *hf = (char *)calloc(1, flen + 6); int rc; -#if defined(__MINGW32__) || defined(FST_MACOSX) - setvbuf(xc->f, (char *)NULL, _IONBF, 0); /* keeps gzip from acting weird in tandem with fopen */ +#if defined(FST_UNBUFFERED_IO) + setvbuf(xc->f, (char *)NULL, _IONBF, 0); /* keeps gzip from acting weird in tandem with fopen */ #endif memcpy(hf, nam, flen); @@ -4530,151 +4939,147 @@ void *fstReaderOpen(const char *nam) xc->filename = strdup(nam); rc = fstReaderInit(xc); - if ((rc) && (xc->vc_section_count) && (xc->maxhandle) && - ((xc->fh) || (xc->contains_hier_section || (xc->contains_hier_section_lz4)))) { - /* more init */ - xc->do_rewind = 1; - } else { - fstReaderClose(xc); - xc = NULL; + if((rc) && (xc->vc_section_count) && (xc->maxhandle) && ((xc->fh)||(xc->contains_hier_section||(xc->contains_hier_section_lz4)))) + { + /* more init */ + xc->do_rewind = 1; + } + else + { + fstReaderClose(xc); + xc = NULL; + } } - } - return (xc); +return(xc); } + static void fstReaderDeallocateRvatData(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc) { - free(xc->rvat_chain_mem); - xc->rvat_chain_mem = NULL; - free(xc->rvat_frame_data); - xc->rvat_frame_data = NULL; - free(xc->rvat_time_table); - xc->rvat_time_table = NULL; - free(xc->rvat_chain_table); - xc->rvat_chain_table = NULL; - free(xc->rvat_chain_table_lengths); - xc->rvat_chain_table_lengths = NULL; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +if(xc) + { + free(xc->rvat_chain_mem); xc->rvat_chain_mem = NULL; + free(xc->rvat_frame_data); xc->rvat_frame_data = NULL; + free(xc->rvat_time_table); xc->rvat_time_table = NULL; + free(xc->rvat_chain_table); xc->rvat_chain_table = NULL; + free(xc->rvat_chain_table_lengths); xc->rvat_chain_table_lengths = NULL; xc->rvat_data_valid = 0; - } + } } + void fstReaderClose(void *ctx) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - if (xc) { +if(xc) + { fstReaderDeallocateScopeData(xc); fstReaderDeallocateRvatData(xc); - free(xc->rvat_sig_offs); - xc->rvat_sig_offs = NULL; + free(xc->rvat_sig_offs); xc->rvat_sig_offs = NULL; - free(xc->process_mask); - xc->process_mask = NULL; - free(xc->blackout_times); - xc->blackout_times = NULL; - free(xc->blackout_activity); - xc->blackout_activity = NULL; - free(xc->temp_signal_value_buf); - xc->temp_signal_value_buf = NULL; - free(xc->signal_typs); - xc->signal_typs = NULL; - free(xc->signal_lens); - xc->signal_lens = NULL; - free(xc->filename); - xc->filename = NULL; + free(xc->process_mask); xc->process_mask = NULL; + free(xc->blackout_times); xc->blackout_times = NULL; + free(xc->blackout_activity); xc->blackout_activity = NULL; + free(xc->temp_signal_value_buf); xc->temp_signal_value_buf = NULL; + free(xc->signal_typs); xc->signal_typs = NULL; + free(xc->signal_lens); xc->signal_lens = NULL; + free(xc->filename); xc->filename = NULL; + free(xc->str_scope_attr); xc->str_scope_attr = NULL; - if (xc->fh) { - tmpfile_close(&xc->fh, &xc->fh_nam); - } + if(xc->fh) + { + tmpfile_close(&xc->fh, &xc->fh_nam); + } - if (xc->f) { - tmpfile_close(&xc->f, &xc->f_nam); - if (xc->filename_unpacked) { - unlink(xc->filename_unpacked); - free(xc->filename_unpacked); - } - } + if(xc->f) + { + tmpfile_close(&xc->f, &xc->f_nam); + if(xc->filename_unpacked) + { + unlink(xc->filename_unpacked); + free(xc->filename_unpacked); + } + } free(xc); - } + } } + /* * read processing */ /* normal read which re-interleaves the value change data */ int fstReaderIterBlocks(void *ctx, - void (*value_change_callback)(void *user_callback_data_pointer, uint64_t time, fstHandle facidx, - const unsigned char *value), - void *user_callback_data_pointer, FILE *fv) + void (*value_change_callback)(void *user_callback_data_pointer, uint64_t time, fstHandle facidx, const unsigned char *value), + void *user_callback_data_pointer, FILE *fv) { - return (fstReaderIterBlocks2(ctx, value_change_callback, NULL, user_callback_data_pointer, fv)); +return(fstReaderIterBlocks2(ctx, value_change_callback, NULL, user_callback_data_pointer, fv)); } + int fstReaderIterBlocks2(void *ctx, - void (*value_change_callback)(void *user_callback_data_pointer, uint64_t time, - fstHandle facidx, const unsigned char *value), - void (*value_change_callback_varlen)(void *user_callback_data_pointer, uint64_t time, - fstHandle facidx, const unsigned char *value, - uint32_t len), - void *user_callback_data_pointer, FILE *fv) + void (*value_change_callback)(void *user_callback_data_pointer, uint64_t time, fstHandle facidx, const unsigned char *value), + void (*value_change_callback_varlen)(void *user_callback_data_pointer, uint64_t time, fstHandle facidx, const unsigned char *value, uint32_t len), + void *user_callback_data_pointer, FILE *fv) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - uint64_t previous_time = UINT64_MAX; - uint64_t *time_table = NULL; - uint64_t tsec_nitems; - unsigned int secnum = 0; - int blocks_skipped = 0; - fst_off_t blkpos = 0; - uint64_t seclen, beg_tim; - uint64_t end_tim; - uint64_t frame_uclen, frame_clen, frame_maxhandle, vc_maxhandle; - fst_off_t vc_start; - fst_off_t indx_pntr, indx_pos; - fst_off_t *chain_table = NULL; - uint32_t *chain_table_lengths = NULL; - unsigned char *chain_cmem; - unsigned char *pnt; - long chain_clen; - fstHandle idx, pidx = 0, i; - uint64_t pval; - uint64_t vc_maxhandle_largest = 0; - uint64_t tsec_uclen = 0, tsec_clen = 0; - int sectype; - uint64_t mem_required_for_traversal; - unsigned char *mem_for_traversal = NULL; - uint32_t traversal_mem_offs; - uint32_t *scatterptr, *headptr, *length_remaining; - uint32_t cur_blackout = 0; - int packtype; - unsigned char *mc_mem = NULL; - uint32_t mc_mem_len; /* corresponds to largest value encountered in chain_table_lengths[i] */ - int dumpvars_state = 0; +uint64_t previous_time = UINT64_MAX; +uint64_t *time_table = NULL; +uint64_t tsec_nitems; +unsigned int secnum = 0; +int blocks_skipped = 0; +fst_off_t blkpos = 0; +uint64_t seclen, beg_tim; +uint64_t end_tim; +uint64_t frame_uclen, frame_clen, frame_maxhandle, vc_maxhandle; +fst_off_t vc_start; +fst_off_t indx_pntr, indx_pos; +fst_off_t *chain_table = NULL; +uint32_t *chain_table_lengths = NULL; +unsigned char *chain_cmem; +unsigned char *pnt; +long chain_clen; +fstHandle idx, pidx=0, i; +uint64_t pval; +uint64_t vc_maxhandle_largest = 0; +uint64_t tsec_uclen = 0, tsec_clen = 0; +int sectype; +uint64_t mem_required_for_traversal; +unsigned char *mem_for_traversal = NULL; +uint32_t traversal_mem_offs; +uint32_t *scatterptr, *headptr, *length_remaining; +uint32_t cur_blackout = 0; +int packtype; +unsigned char *mc_mem = NULL; +uint32_t mc_mem_len; /* corresponds to largest value encountered in chain_table_lengths[i] */ +int dumpvars_state = 0; - if (!xc) - return (0); +if(!xc) return(0); - scatterptr = (uint32_t *)calloc(xc->maxhandle, sizeof(uint32_t)); - headptr = (uint32_t *)calloc(xc->maxhandle, sizeof(uint32_t)); - length_remaining = (uint32_t *)calloc(xc->maxhandle, sizeof(uint32_t)); +scatterptr = (uint32_t *)calloc(xc->maxhandle, sizeof(uint32_t)); +headptr = (uint32_t *)calloc(xc->maxhandle, sizeof(uint32_t)); +length_remaining = (uint32_t *)calloc(xc->maxhandle, sizeof(uint32_t)); - if (fv) { +if(fv) + { #ifndef FST_WRITEX_DISABLE fflush(fv); - setvbuf(fv, (char *)NULL, _IONBF, - 0); /* even buffered IO is slow so disable it and use our own routines that don't need seeking */ + setvbuf(fv, (char *) NULL, _IONBF, 0); /* even buffered IO is slow so disable it and use our own routines that don't need seeking */ xc->writex_fd = fileno(fv); #endif - } + } - for (;;) { +for(;;) + { uint32_t *tc_head = NULL; + uint32_t tc_head_items = 0; traversal_mem_offs = 0; fstReaderFseeko(xc, xc->f, blkpos, SEEK_SET); @@ -4682,292 +5087,372 @@ int fstReaderIterBlocks2(void *ctx, sectype = fgetc(xc->f); seclen = fstReaderUint64(xc->f); - if ((sectype == EOF) || (sectype == FST_BL_SKIP)) { + if((sectype == EOF) || (sectype == FST_BL_SKIP)) + { #ifdef FST_DEBUG - fprintf(stderr, FST_APIMESS "<< EOF >>\n"); + fprintf(stderr, FST_APIMESS "<< EOF >>\n"); #endif - break; - } + break; + } blkpos++; - if ((sectype != FST_BL_VCDATA) && (sectype != FST_BL_VCDATA_DYN_ALIAS) && - (sectype != FST_BL_VCDATA_DYN_ALIAS2)) { - blkpos += seclen; - continue; - } + if((sectype != FST_BL_VCDATA) && (sectype != FST_BL_VCDATA_DYN_ALIAS) && (sectype != FST_BL_VCDATA_DYN_ALIAS2)) + { + blkpos += seclen; + continue; + } - if (!seclen) - break; + if(!seclen) break; beg_tim = fstReaderUint64(xc->f); end_tim = fstReaderUint64(xc->f); - if (xc->limit_range_valid) { - if (end_tim < xc->limit_range_start) { - blocks_skipped++; - blkpos += seclen; - continue; - } + if(xc->limit_range_valid) + { + if(end_tim < xc->limit_range_start) + { + blocks_skipped++; + blkpos += seclen; + continue; + } - if (beg_tim > - xc->limit_range_end) /* likely the compare in for(i=0;i xc->limit_range_end) /* likely the compare in for(i=0;if); - mem_for_traversal = - (unsigned char *)malloc(mem_required_for_traversal + 66); /* add in potential fastlz overhead */ + + mem_required_for_traversal = fstReaderUint64(xc->f) + 66; /* add in potential fastlz overhead */ + mem_for_traversal = (unsigned char *)malloc(mem_required_for_traversal); #ifdef FST_DEBUG - fprintf(stderr, FST_APIMESS "sec: %u seclen: %d begtim: %d endtim: %d\n", secnum, (int)seclen, (int)beg_tim, - (int)end_tim); - fprintf(stderr, FST_APIMESS "mem_required_for_traversal: %d\n", (int)mem_required_for_traversal); + fprintf(stderr, FST_APIMESS "sec: %u seclen: %d begtim: %d endtim: %d\n", + secnum, (int)seclen, (int)beg_tim, (int)end_tim); + fprintf(stderr, FST_APIMESS "mem_required_for_traversal: %d\n", (int)mem_required_for_traversal-66); #endif /* process time block */ { - unsigned char *ucdata; - unsigned char *cdata; - unsigned long destlen /* = tsec_uclen */; /* scan-build */ - unsigned long sourcelen /*= tsec_clen */; /* scan-build */ - int rc; - unsigned char *tpnt; - uint64_t tpval; - unsigned int ti; + unsigned char *ucdata; + unsigned char *cdata; + unsigned long destlen /* = tsec_uclen */; /* scan-build */ + unsigned long sourcelen /*= tsec_clen */; /* scan-build */ + int rc; + unsigned char *tpnt; + uint64_t tpval; + unsigned int ti; - if (fstReaderFseeko(xc, xc->f, blkpos + seclen - 24, SEEK_SET) != 0) - break; - tsec_uclen = fstReaderUint64(xc->f); - tsec_clen = fstReaderUint64(xc->f); - tsec_nitems = fstReaderUint64(xc->f); + if(fstReaderFseeko(xc, xc->f, blkpos + seclen - 24, SEEK_SET) != 0) break; + tsec_uclen = fstReaderUint64(xc->f); + tsec_clen = fstReaderUint64(xc->f); + tsec_nitems = fstReaderUint64(xc->f); #ifdef FST_DEBUG - fprintf(stderr, FST_APIMESS "time section unc: %d, com: %d (%d items)\n", (int)tsec_uclen, (int)tsec_clen, - (int)tsec_nitems); + fprintf(stderr, FST_APIMESS "time section unc: %d, com: %d (%d items)\n", + (int)tsec_uclen, (int)tsec_clen, (int)tsec_nitems); #endif - if (tsec_clen > seclen) - break; /* corrupted tsec_clen: by definition it can't be larger than size of section */ - ucdata = (unsigned char *)malloc(tsec_uclen); - if (!ucdata) - break; /* malloc fail as tsec_uclen out of range from corrupted file */ - destlen = tsec_uclen; - sourcelen = tsec_clen; + if(tsec_clen > seclen) break; /* corrupted tsec_clen: by definition it can't be larger than size of section */ + ucdata = (unsigned char *)malloc(tsec_uclen); + if(!ucdata) break; /* malloc fail as tsec_uclen out of range from corrupted file */ + destlen = tsec_uclen; + sourcelen = tsec_clen; - fstReaderFseeko(xc, xc->f, -24 - ((fst_off_t)tsec_clen), SEEK_CUR); + fstReaderFseeko(xc, xc->f, -24 - ((fst_off_t)tsec_clen), SEEK_CUR); - if (tsec_uclen != tsec_clen) { + if(tsec_uclen != tsec_clen) + { cdata = (unsigned char *)malloc(tsec_clen); fstFread(cdata, tsec_clen, 1, xc->f); rc = uncompress(ucdata, &destlen, cdata, sourcelen); - if (rc != Z_OK) { - fprintf(stderr, FST_APIMESS "fstReaderIterBlocks2(), tsec uncompress rc = %d, exiting.\n", rc); - exit(255); - } + if(rc != Z_OK) + { + fprintf(stderr, FST_APIMESS "fstReaderIterBlocks2(), tsec uncompress rc = %d, exiting.\n", rc); + exit(255); + } free(cdata); - } else { + } + else + { fstFread(ucdata, tsec_uclen, 1, xc->f); - } + } - free(time_table); - time_table = (uint64_t *)calloc(tsec_nitems, sizeof(uint64_t)); - tpnt = ucdata; - tpval = 0; - for (ti = 0; ti < tsec_nitems; ti++) { + free(time_table); + + if(sizeof(size_t) < sizeof(uint64_t)) + { + /* TALOS-2023-1792 for 32b overflow */ + uint64_t chk_64 = tsec_nitems * sizeof(uint64_t); + size_t chk_32 = ((size_t)tsec_nitems) * sizeof(uint64_t); + if(chk_64 != chk_32) chk_report_abort("TALOS-2023-1792"); + } + else + { + uint64_t chk_64 = tsec_nitems * sizeof(uint64_t); + if((chk_64/sizeof(uint64_t)) != tsec_nitems) + { + chk_report_abort("TALOS-2023-1792"); + } + } + time_table = (uint64_t *)calloc(tsec_nitems, sizeof(uint64_t)); + tpnt = ucdata; + tpval = 0; + for(ti=0;tif, blkpos + 32, SEEK_SET); + fstReaderFseeko(xc, xc->f, blkpos+32, SEEK_SET); frame_uclen = fstReaderVarint64(xc->f); frame_clen = fstReaderVarint64(xc->f); frame_maxhandle = fstReaderVarint64(xc->f); - if (secnum == 0) { - if ((beg_tim != time_table[0]) || (blocks_skipped)) { - unsigned char *mu = (unsigned char *)malloc(frame_uclen); - uint32_t sig_offs = 0; + if(secnum == 0) + { + if((beg_tim != time_table[0]) || (blocks_skipped)) + { + unsigned char *mu = (unsigned char *)malloc(frame_uclen); + uint32_t sig_offs = 0; - if (fv) { - char wx_buf[32]; - int wx_len; + if(fv) + { + char wx_buf[32]; + int wx_len; - if (beg_tim) { - if (dumpvars_state == 1) { - wx_len = snprintf(wx_buf, 6, "$end\n"); - fstWritex(xc, wx_buf, wx_len); - dumpvars_state = 2; - } - wx_len = snprintf(wx_buf, 20, "#%" PRIu64 "\n", beg_tim); - fstWritex(xc, wx_buf, wx_len); - if (!dumpvars_state) { - wx_len = snprintf(wx_buf, 11, "$dumpvars\n"); - fstWritex(xc, wx_buf, wx_len); - dumpvars_state = 1; - } - } - if ((xc->num_blackouts) && (cur_blackout != xc->num_blackouts)) { - if (beg_tim == xc->blackout_times[cur_blackout]) { - wx_len = snprintf(wx_buf, 16, "$dump%s $end\n", - (xc->blackout_activity[cur_blackout++]) ? "on" : "off"); - fstWritex(xc, wx_buf, wx_len); - } - } - } - - if (frame_uclen == frame_clen) { - fstFread(mu, frame_uclen, 1, xc->f); - } else { - unsigned char *mc = (unsigned char *)malloc(frame_clen); - int rc; - - unsigned long destlen = frame_uclen; - unsigned long sourcelen = frame_clen; - - fstFread(mc, sourcelen, 1, xc->f); - rc = uncompress(mu, &destlen, mc, sourcelen); - if (rc != Z_OK) { - fprintf(stderr, FST_APIMESS "fstReaderIterBlocks2(), frame uncompress rc: %d, exiting.\n", rc); - exit(255); - } - free(mc); - } - - for (idx = 0; idx < frame_maxhandle; idx++) { - int process_idx = idx / 8; - int process_bit = idx & 7; - - if (xc->process_mask[process_idx] & (1 << process_bit)) { - if (xc->signal_lens[idx] <= 1) { - if (xc->signal_lens[idx] == 1) { - unsigned char val = mu[sig_offs]; - if (value_change_callback) { - xc->temp_signal_value_buf[0] = val; - xc->temp_signal_value_buf[1] = 0; - value_change_callback(user_callback_data_pointer, beg_tim, idx + 1, - xc->temp_signal_value_buf); - } else { - if (fv) { - char vcd_id[16]; - - int vcdid_len = fstVcdIDForFwrite(vcd_id + 1, idx + 1); - vcd_id[0] = val; /* collapse 3 writes into one I/O call */ - vcd_id[vcdid_len + 1] = '\n'; - fstWritex(xc, vcd_id, vcdid_len + 2); - } - } - } else { - /* variable-length ("0" length) records have no initial state */ - } - } else { - if (xc->signal_typs[idx] != FST_VT_VCD_REAL) { - if (value_change_callback) { - memcpy(xc->temp_signal_value_buf, mu + sig_offs, xc->signal_lens[idx]); - xc->temp_signal_value_buf[xc->signal_lens[idx]] = 0; - value_change_callback(user_callback_data_pointer, beg_tim, idx + 1, - xc->temp_signal_value_buf); - } else { - if (fv) { - char vcd_id[16]; - int vcdid_len = fstVcdIDForFwrite(vcd_id + 1, idx + 1); - - vcd_id[0] = (xc->signal_typs[idx] != FST_VT_VCD_PORT) ? 'b' : 'p'; - fstWritex(xc, vcd_id, 1); - fstWritex(xc, mu + sig_offs, xc->signal_lens[idx]); - - vcd_id[0] = ' '; /* collapse 3 writes into one I/O call */ - vcd_id[vcdid_len + 1] = '\n'; - fstWritex(xc, vcd_id, vcdid_len + 2); - } - } - } else { - double d; - unsigned char *clone_d; - unsigned char *srcdata = mu + sig_offs; - - if (value_change_callback) { - if (xc->native_doubles_for_cb) { - if (xc->double_endian_match) { - clone_d = srcdata; - } else { - int j; - - clone_d = (unsigned char *)&d; - for (j = 0; j < 8; j++) { - clone_d[j] = srcdata[7 - j]; - } - } - value_change_callback(user_callback_data_pointer, beg_tim, idx + 1, clone_d); - } else { - clone_d = (unsigned char *)&d; - if (xc->double_endian_match) { - memcpy(clone_d, srcdata, 8); - } else { - int j; - - for (j = 0; j < 8; j++) { - clone_d[j] = srcdata[7 - j]; - } - } - snprintf((char *)xc->temp_signal_value_buf, 32, "%.16g", d); - value_change_callback(user_callback_data_pointer, beg_tim, idx + 1, - xc->temp_signal_value_buf); - } - } else { - if (fv) { - char vcdid_buf[16]; - char wx_buf[64]; - int wx_len; - - clone_d = (unsigned char *)&d; - if (xc->double_endian_match) { - memcpy(clone_d, srcdata, 8); - } else { - int j; - - for (j = 0; j < 8; j++) { - clone_d[j] = srcdata[7 - j]; - } - } - - fstVcdID(vcdid_buf, idx + 1); - wx_len = snprintf(wx_buf, sizeof(wx_buf), "r%.16g %s\n", d, vcdid_buf); + if(beg_tim) + { + if(dumpvars_state == 1) { wx_len = snprintf(wx_buf, 32, "$end\n"); fstWritex(xc, wx_buf, wx_len); dumpvars_state = 2; } + wx_len = snprintf(wx_buf, 32, "#%" PRIu64 "\n", beg_tim); fstWritex(xc, wx_buf, wx_len); - } + if(!dumpvars_state) { wx_len = snprintf(wx_buf, 32, "$dumpvars\n"); fstWritex(xc, wx_buf, wx_len); dumpvars_state = 1; } + } + if((xc->num_blackouts)&&(cur_blackout != xc->num_blackouts)) + { + if(beg_tim == xc->blackout_times[cur_blackout]) + { + wx_len = snprintf(wx_buf, 32, "$dump%s $end\n", (xc->blackout_activity[cur_blackout++]) ? "on" : "off"); + fstWritex(xc, wx_buf, wx_len); + } + } } - } + + if(frame_uclen == frame_clen) + { + fstFread(mu, frame_uclen, 1, xc->f); + } + else + { + unsigned char *mc = (unsigned char *)malloc(frame_clen); + int rc; + + unsigned long destlen = frame_uclen; + unsigned long sourcelen = frame_clen; + + fstFread(mc, sourcelen, 1, xc->f); + rc = uncompress(mu, &destlen, mc, sourcelen); + if(rc != Z_OK) + { + fprintf(stderr, FST_APIMESS "fstReaderIterBlocks2(), frame uncompress rc: %d, exiting.\n", rc); + exit(255); + } + free(mc); + } + + + for(idx=0;idxprocess_mask[process_idx]&(1<signal_lens[idx] <= 1) + { + if(xc->signal_lens[idx] == 1) + { + unsigned char val = mu[sig_offs]; + if(value_change_callback) + { + xc->temp_signal_value_buf[0] = val; + xc->temp_signal_value_buf[1] = 0; + value_change_callback(user_callback_data_pointer, beg_tim, idx+1, xc->temp_signal_value_buf); + } + else + { + if(fv) + { + char vcd_id[16]; + + int vcdid_len = fstVcdIDForFwrite(vcd_id+1, idx+1); + vcd_id[0] = val; /* collapse 3 writes into one I/O call */ + vcd_id[vcdid_len + 1] = '\n'; + fstWritex(xc, vcd_id, vcdid_len + 2); + } + } + } + else + { + /* variable-length ("0" length) records have no initial state */ + } + } + else + { + if(xc->signal_typs[idx] != FST_VT_VCD_REAL) + { + if(value_change_callback) + { + if(xc->signal_lens[idx] > xc->longest_signal_value_len) + { + chk_report_abort("TALOS-2023-1797"); + } + memcpy(xc->temp_signal_value_buf, mu+sig_offs, xc->signal_lens[idx]); + xc->temp_signal_value_buf[xc->signal_lens[idx]] = 0; + value_change_callback(user_callback_data_pointer, beg_tim, idx+1, xc->temp_signal_value_buf); + } + else + { + if(fv) + { + char vcd_id[16]; + int vcdid_len = fstVcdIDForFwrite(vcd_id+1, idx+1); + + vcd_id[0] = (xc->signal_typs[idx] != FST_VT_VCD_PORT) ? 'b' : 'p'; + fstWritex(xc, vcd_id, 1); + if((sig_offs + xc->signal_lens[idx]) > frame_uclen) + { + chk_report_abort("TALOS-2023-1793"); + } + fstWritex(xc,mu+sig_offs, xc->signal_lens[idx]); + + vcd_id[0] = ' '; /* collapse 3 writes into one I/O call */ + vcd_id[vcdid_len + 1] = '\n'; + fstWritex(xc, vcd_id, vcdid_len + 2); + } + } + } + else + { + double d; + unsigned char *clone_d; + unsigned char *srcdata = mu+sig_offs; + + if(value_change_callback) + { + if(xc->native_doubles_for_cb) + { + if(xc->double_endian_match) + { + clone_d = srcdata; + } + else + { + int j; + + clone_d = (unsigned char *)&d; + for(j=0;j<8;j++) + { + clone_d[j] = srcdata[7-j]; + } + } + value_change_callback(user_callback_data_pointer, beg_tim, idx+1, clone_d); + } + else + { + clone_d = (unsigned char *)&d; + if(xc->double_endian_match) + { + memcpy(clone_d, srcdata, 8); + } + else + { + int j; + + for(j=0;j<8;j++) + { + clone_d[j] = srcdata[7-j]; + } + } + snprintf((char *)xc->temp_signal_value_buf, xc->longest_signal_value_len + 1, "%.16g", d); + value_change_callback(user_callback_data_pointer, beg_tim, idx+1, xc->temp_signal_value_buf); + } + } + else + { + if(fv) + { + char vcdid_buf[16]; + char wx_buf[64]; + int wx_len; + + clone_d = (unsigned char *)&d; + if(xc->double_endian_match) + { + memcpy(clone_d, srcdata, 8); + } + else + { + int j; + + for(j=0;j<8;j++) + { + clone_d[j] = srcdata[7-j]; + } + } + + fstVcdID(vcdid_buf, idx+1); + wx_len = snprintf(wx_buf, 64, "r%.16g %s\n", d, vcdid_buf); + fstWritex(xc, wx_buf, wx_len); + } + } + } + } + } + + sig_offs += xc->signal_lens[idx]; + } + + free(mu); + fstReaderFseeko(xc, xc->f, -((fst_off_t)frame_clen), SEEK_CUR); } - } - - sig_offs += xc->signal_lens[idx]; } - free(mu); - fstReaderFseeko(xc, xc->f, -((fst_off_t)frame_clen), SEEK_CUR); - } - } - fstReaderFseeko(xc, xc->f, (fst_off_t)frame_clen, SEEK_CUR); /* skip past compressed data */ vc_maxhandle = fstReaderVarint64(xc->f); - vc_start = ftello(xc->f); /* points to '!' character */ + vc_start = ftello(xc->f); /* points to '!' character */ packtype = fgetc(xc->f); #ifdef FST_DEBUG - fprintf(stderr, FST_APIMESS "frame_uclen: %d, frame_clen: %d, frame_maxhandle: %d\n", (int)frame_uclen, - (int)frame_clen, (int)frame_maxhandle); + fprintf(stderr, FST_APIMESS "frame_uclen: %d, frame_clen: %d, frame_maxhandle: %d\n", + (int)frame_uclen, (int)frame_clen, (int)frame_maxhandle); fprintf(stderr, FST_APIMESS "vc_maxhandle: %d, packtype: %c\n", (int)vc_maxhandle, packtype); #endif - indx_pntr = blkpos + seclen - 24 - tsec_clen - 8; + indx_pntr = blkpos + seclen - 24 -tsec_clen -8; fstReaderFseeko(xc, xc->f, indx_pntr, SEEK_SET); chain_clen = fstReaderUint64(xc->f); indx_pos = indx_pntr - chain_clen; @@ -4975,106 +5460,168 @@ int fstReaderIterBlocks2(void *ctx, fprintf(stderr, FST_APIMESS "indx_pos: %d (%d bytes)\n", (int)indx_pos, (int)chain_clen); #endif chain_cmem = (unsigned char *)malloc(chain_clen); - if (!chain_cmem) - goto block_err; + if(!chain_cmem) goto block_err; fstReaderFseeko(xc, xc->f, indx_pos, SEEK_SET); fstFread(chain_cmem, chain_clen, 1, xc->f); - if (vc_maxhandle > vc_maxhandle_largest) { - free(chain_table); - free(chain_table_lengths); + if(vc_maxhandle > vc_maxhandle_largest) + { + free(chain_table); + free(chain_table_lengths); - vc_maxhandle_largest = vc_maxhandle; - chain_table = (fst_off_t *)calloc((vc_maxhandle + 1), sizeof(fst_off_t)); - chain_table_lengths = (uint32_t *)calloc((vc_maxhandle + 1), sizeof(uint32_t)); - } + vc_maxhandle_largest = vc_maxhandle; - if (!chain_table || !chain_table_lengths) - goto block_err; + if(!(vc_maxhandle+1)) + { + chk_report_abort("TALOS-2023-1798"); + } + + if(sizeof(size_t) < sizeof(uint64_t)) + { + /* TALOS-2023-1798 for 32b overflow */ + uint64_t chk_64 = (vc_maxhandle+1) * sizeof(fst_off_t); + size_t chk_32 = ((size_t)(vc_maxhandle+1)) * sizeof(fst_off_t); + if(chk_64 != chk_32) chk_report_abort("TALOS-2023-1798"); + } + else + { + uint64_t chk_64 = (vc_maxhandle+1) * sizeof(fst_off_t); + if((chk_64/sizeof(fst_off_t)) != (vc_maxhandle+1)) + { + chk_report_abort("TALOS-2023-1798"); + } + } + chain_table = (fst_off_t *)calloc((vc_maxhandle+1), sizeof(fst_off_t)); + + if(sizeof(size_t) < sizeof(uint64_t)) + { + /* TALOS-2023-1798 for 32b overflow */ + uint64_t chk_64 = (vc_maxhandle+1) * sizeof(uint32_t); + size_t chk_32 = ((size_t)(vc_maxhandle+1)) * sizeof(uint32_t); + if(chk_64 != chk_32) chk_report_abort("TALOS-2023-1798"); + } + else + { + uint64_t chk_64 = (vc_maxhandle+1) * sizeof(uint32_t); + if((chk_64/sizeof(uint32_t)) != (vc_maxhandle+1)) + { + chk_report_abort("TALOS-2023-1798"); + } + } + chain_table_lengths = (uint32_t *)calloc((vc_maxhandle+1), sizeof(uint32_t)); + } + + if(!chain_table || !chain_table_lengths) goto block_err; pnt = chain_cmem; idx = 0; pval = 0; - if (sectype == FST_BL_VCDATA_DYN_ALIAS2) { - uint32_t prev_alias = 0; + if(sectype == FST_BL_VCDATA_DYN_ALIAS2) + { + uint32_t prev_alias = 0; - do { - int skiplen; + do { + int skiplen; - if (*pnt & 0x01) { - int64_t shval = fstGetSVarint64(pnt, &skiplen) >> 1; - if (shval > 0) { - pval = chain_table[idx] = pval + shval; - if (idx) { - chain_table_lengths[pidx] = pval - chain_table[pidx]; - } - pidx = idx++; - } else if (shval < 0) { - chain_table[idx] = 0; /* need to explicitly zero as calloc above might not run */ - chain_table_lengths[idx] = prev_alias = - shval; /* because during this loop iter would give stale data! */ - idx++; - } else { - chain_table[idx] = 0; /* need to explicitly zero as calloc above might not run */ - chain_table_lengths[idx] = - prev_alias; /* because during this loop iter would give stale data! */ - idx++; - } - } else { - uint64_t val = fstGetVarint32(pnt, &skiplen); + if(*pnt & 0x01) + { + int64_t shval = fstGetSVarint64(pnt, &skiplen) >> 1; + if(shval > 0) + { + pval = chain_table[idx] = pval + shval; + if(idx) { chain_table_lengths[pidx] = pval - chain_table[pidx]; } + pidx = idx++; + } + else if(shval < 0) + { + chain_table[idx] = 0; /* need to explicitly zero as calloc above might not run */ + chain_table_lengths[idx] = prev_alias = shval; /* because during this loop iter would give stale data! */ + idx++; + } + else + { + chain_table[idx] = 0; /* need to explicitly zero as calloc above might not run */ + chain_table_lengths[idx] = prev_alias; /* because during this loop iter would give stale data! */ + idx++; + } + } + else + { + uint64_t val = fstGetVarint32(pnt, &skiplen); - fstHandle loopcnt = val >> 1; - for (i = 0; i < loopcnt; i++) { - chain_table[idx++] = 0; - } + fstHandle loopcnt = val >> 1; + if((idx+loopcnt-1) > vc_maxhandle) /* TALOS-2023-1789 */ + { + chk_report_abort("TALOS-2023-1789"); + } + + for(i=0;i> 1); + if(idx) { chain_table_lengths[pidx] = pval - chain_table[pidx]; } + pidx = idx++; + } + else + { + fstHandle loopcnt = val >> 1; - if (!val) { - pnt += skiplen; - val = fstGetVarint32(pnt, &skiplen); - chain_table[idx] = 0; /* need to explicitly zero as calloc above might not run */ - chain_table_lengths[idx] = -val; /* because during this loop iter would give stale data! */ - idx++; - } else if (val & 1) { - pval = chain_table[idx] = pval + (val >> 1); - if (idx) { - chain_table_lengths[pidx] = pval - chain_table[pidx]; - } - pidx = idx++; - } else { - fstHandle loopcnt = val >> 1; - for (i = 0; i < loopcnt; i++) { - chain_table[idx++] = 0; - } + if((idx+loopcnt-1) > vc_maxhandle) /* TALOS-2023-1789 */ + { + chk_report_abort("TALOS-2023-1789"); + } + + for(i=0;i xc->maxhandle) - idx = xc->maxhandle; - for (i = 0; i < idx; i++) { - if (chain_table[i]) { - int process_idx = i / 8; - int process_bit = i & 7; + if(idx > xc->maxhandle) idx = xc->maxhandle; + for(i=0;iprocess_mask[process_idx] & (1 << process_bit)) { - int rc = Z_OK; - uint32_t val; - uint32_t skiplen; - uint32_t tdelta; + if(xc->process_mask[process_idx]&(1<f, vc_start + chain_table[i], SEEK_SET); - val = fstReaderVarint32WithSkip(xc->f, &skiplen); - if (val) { - unsigned char *mu = mem_for_traversal + traversal_mem_offs; /* uncomp: dst */ - unsigned char *mc; /* comp: src */ - unsigned long destlen = val; - unsigned long sourcelen = chain_table_lengths[i]; + fstReaderFseeko(xc, xc->f, vc_start + chain_table[i], SEEK_SET); + val = fstReaderVarint32WithSkip(xc->f, &skiplen); + if(val) + { + unsigned char *mu = mem_for_traversal + traversal_mem_offs; /* uncomp: dst */ + unsigned char *mc; /* comp: src */ + unsigned long destlen = val; + unsigned long sourcelen = chain_table_lengths[i]; - if (mc_mem_len < chain_table_lengths[i]) { - free(mc_mem); - mc_mem = (unsigned char *)malloc(mc_mem_len = chain_table_lengths[i]); + if(traversal_mem_offs >= mem_required_for_traversal) + { + chk_report_abort("TALOS-2023-1785"); + } + + if(mc_mem_len < chain_table_lengths[i]) + { + free(mc_mem); + mc_mem = (unsigned char *)malloc(mc_mem_len = chain_table_lengths[i]); + } + mc = mc_mem; + + fstFread(mc, chain_table_lengths[i], 1, xc->f); + + switch(packtype) + { + case '4': rc = (destlen == (unsigned long)LZ4_decompress_safe_partial((char *)mc, (char *)mu, sourcelen, destlen, destlen)) ? Z_OK : Z_DATA_ERROR; + break; + case 'F': fastlz_decompress(mc, sourcelen, mu, destlen); /* rc appears unreliable */ + break; + default: rc = uncompress(mu, &destlen, mc, sourcelen); + break; + } + + /* data to process is for(j=0;j= mem_required_for_traversal) + { + chk_report_abort("TALOS-2023-1785"); + } + + fstFread(mu, destlen, 1, xc->f); + /* data to process is for(j=0;jsignal_lens[i] == 1) + { + uint32_t vli = fstGetVarint32NoSkip(mem_for_traversal + headptr[i]); + uint32_t shcnt = 2 << (vli & 1); + tdelta = vli >> shcnt; + } + else + { + uint32_t vli = fstGetVarint32NoSkip(mem_for_traversal + headptr[i]); + tdelta = vli >> 1; + } + + if(tdelta >= tc_head_items) + { + chk_report_abort("TALOS-2023-1791"); + } + + scatterptr[i] = tc_head[tdelta]; + tc_head[tdelta] = i+1; + } } - mc = mc_mem; - - fstFread(mc, chain_table_lengths[i], 1, xc->f); - - switch (packtype) { - case '4': - rc = (destlen == (unsigned long)LZ4_decompress_safe_partial((char *)mc, (char *)mu, - sourcelen, destlen, destlen)) - ? Z_OK - : Z_DATA_ERROR; - break; - case 'F': - fastlz_decompress(mc, sourcelen, mu, destlen); /* rc appears unreliable */ - break; - default: - rc = uncompress(mu, &destlen, mc, sourcelen); - break; - } - - /* data to process is for(j=0;jf); - /* data to process is for(j=0;jsignal_lens[i] == 1) { - uint32_t vli = fstGetVarint32NoSkip(mem_for_traversal + headptr[i]); - uint32_t shcnt = 2 << (vli & 1); - tdelta = vli >> shcnt; - } else { - uint32_t vli = fstGetVarint32NoSkip(mem_for_traversal + headptr[i]); - tdelta = vli >> 1; - } - - scatterptr[i] = tc_head[tdelta]; - tc_head[tdelta] = i + 1; } - } - } free(mc_mem); /* there is no usage below for this, no real need to clear out mc_mem or mc_mem_len */ - for (i = 0; i < tsec_nitems; i++) { - uint32_t tdelta; - int skiplen, skiplen2; - uint32_t vli; + for(i=0;ilimit_range_valid) { - if (time_table[i] > xc->limit_range_end) { - break; - } - } - - if (dumpvars_state == 1) { - wx_len = snprintf(wx_buf, 6, "$end\n"); - fstWritex(xc, wx_buf, wx_len); - dumpvars_state = 2; - } - wx_len = snprintf(wx_buf, 20, "#%" PRIu64 "\n", time_table[i]); - fstWritex(xc, wx_buf, wx_len); - if (!dumpvars_state) { - wx_len = snprintf(wx_buf, 11, "$dumpvars\n"); - fstWritex(xc, wx_buf, wx_len); - dumpvars_state = 1; - } - - if ((xc->num_blackouts) && (cur_blackout != xc->num_blackouts)) { - if (time_table[i] == xc->blackout_times[cur_blackout]) { - wx_len = snprintf(wx_buf, 16, "$dump%s $end\n", - (xc->blackout_activity[cur_blackout++]) ? "on" : "off"); - fstWritex(xc, wx_buf, wx_len); - } - } - previous_time = time_table[i]; - } - } else { - if (time_table[i] != previous_time) { - if (xc->limit_range_valid) { - if (time_table[i] > xc->limit_range_end) { - break; - } - } - previous_time = time_table[i]; - } - } - - while (tc_head[i]) { - idx = tc_head[i] - 1; - vli = fstGetVarint32(mem_for_traversal + headptr[idx], &skiplen); - - if (xc->signal_lens[idx] <= 1) { - if (xc->signal_lens[idx] == 1) { - unsigned char val; - if (!(vli & 1)) { - /* tdelta = vli >> 2; */ /* scan-build */ - val = ((vli >> 1) & 1) | '0'; - } else { - /* tdelta = vli >> 4; */ /* scan-build */ - val = FST_RCV_STR[((vli >> 1) & 7)]; - } - - if (value_change_callback) { - xc->temp_signal_value_buf[0] = val; - xc->temp_signal_value_buf[1] = 0; - value_change_callback(user_callback_data_pointer, time_table[i], idx + 1, - xc->temp_signal_value_buf); - } else { - if (fv) { - char vcd_id[16]; - int vcdid_len = fstVcdIDForFwrite(vcd_id + 1, idx + 1); - - vcd_id[0] = val; - vcd_id[vcdid_len + 1] = '\n'; - fstWritex(xc, vcd_id, vcdid_len + 2); - } - } - headptr[idx] += skiplen; - length_remaining[idx] -= skiplen; - - tc_head[i] = scatterptr[idx]; - scatterptr[idx] = 0; - - if (length_remaining[idx]) { - int shamt; - vli = fstGetVarint32NoSkip(mem_for_traversal + headptr[idx]); - shamt = 2 << (vli & 1); - tdelta = vli >> shamt; - - scatterptr[idx] = tc_head[i + tdelta]; - tc_head[i + tdelta] = idx + 1; - } - } else { - unsigned char *vdata; - uint32_t len; - - vli = fstGetVarint32(mem_for_traversal + headptr[idx], &skiplen); - len = fstGetVarint32(mem_for_traversal + headptr[idx] + skiplen, &skiplen2); - /* tdelta = vli >> 1; */ /* scan-build */ - skiplen += skiplen2; - vdata = mem_for_traversal + headptr[idx] + skiplen; - - if (!(vli & 1)) { - if (value_change_callback_varlen) { - value_change_callback_varlen(user_callback_data_pointer, time_table[i], idx + 1, vdata, - len); - } else { - if (fv) { - char vcd_id[16]; - int vcdid_len; - - vcd_id[0] = 's'; - fstWritex(xc, vcd_id, 1); - - vcdid_len = fstVcdIDForFwrite(vcd_id + 1, idx + 1); - { - unsigned char *vesc = (unsigned char *)malloc(len * 4 + 1); - int vlen = fstUtilityBinToEsc(vesc, vdata, len); - fstWritex(xc, vesc, vlen); - free(vesc); - } - - vcd_id[0] = ' '; - vcd_id[vcdid_len + 1] = '\n'; - fstWritex(xc, vcd_id, vcdid_len + 2); - } - } - } - - skiplen += len; - headptr[idx] += skiplen; - length_remaining[idx] -= skiplen; - - tc_head[i] = scatterptr[idx]; - scatterptr[idx] = 0; - - if (length_remaining[idx]) { - vli = fstGetVarint32NoSkip(mem_for_traversal + headptr[idx]); - tdelta = vli >> 1; - - scatterptr[idx] = tc_head[i + tdelta]; - tc_head[i + tdelta] = idx + 1; - } - } - } else { - uint32_t len = xc->signal_lens[idx]; - unsigned char *vdata; - - vli = fstGetVarint32(mem_for_traversal + headptr[idx], &skiplen); - /* tdelta = vli >> 1; */ /* scan-build */ - vdata = mem_for_traversal + headptr[idx] + skiplen; - - if (xc->signal_typs[idx] != FST_VT_VCD_REAL) { - if (!(vli & 1)) { - int byte = 0; - int bit; - unsigned int j; - - for (j = 0; j < len; j++) { - unsigned char ch; - byte = j / 8; - bit = 7 - (j & 7); - ch = ((vdata[byte] >> bit) & 1) | '0'; - xc->temp_signal_value_buf[j] = ch; - } - xc->temp_signal_value_buf[j] = 0; - - if (value_change_callback) { - value_change_callback(user_callback_data_pointer, time_table[i], idx + 1, - xc->temp_signal_value_buf); - } else { - if (fv) { - unsigned char ch_bp = (xc->signal_typs[idx] != FST_VT_VCD_PORT) ? 'b' : 'p'; - - fstWritex(xc, &ch_bp, 1); - fstWritex(xc, xc->temp_signal_value_buf, len); - } - } - - len = byte + 1; - } else { - if (value_change_callback) { - memcpy(xc->temp_signal_value_buf, vdata, len); - xc->temp_signal_value_buf[len] = 0; - value_change_callback(user_callback_data_pointer, time_table[i], idx + 1, - xc->temp_signal_value_buf); - } else { - if (fv) { - unsigned char ch_bp = (xc->signal_typs[idx] != FST_VT_VCD_PORT) ? 'b' : 'p'; - - fstWritex(xc, &ch_bp, 1); - fstWritex(xc, vdata, len); - } - } - } - } else { - double d; - unsigned char *clone_d /*= (unsigned char *)&d */; /* scan-build */ - unsigned char buf[8]; - unsigned char *srcdata; - - if (!(vli & 1)) /* very rare case, but possible */ + if(fv) { - int bit; - int j; + char wx_buf[32]; + int wx_len; - for (j = 0; j < 8; j++) { - unsigned char ch; - bit = 7 - (j & 7); - ch = ((vdata[0] >> bit) & 1) | '0'; - buf[j] = ch; - } + if(time_table[i] != previous_time) + { + if(xc->limit_range_valid) + { + if(time_table[i] > xc->limit_range_end) + { + break; + } + } - len = 1; - srcdata = buf; - } else { - srcdata = vdata; - } - - if (value_change_callback) { - if (xc->native_doubles_for_cb) { - if (xc->double_endian_match) { - clone_d = srcdata; - } else { - int j; - - clone_d = (unsigned char *)&d; - for (j = 0; j < 8; j++) { - clone_d[j] = srcdata[7 - j]; - } - } - value_change_callback(user_callback_data_pointer, time_table[i], idx + 1, clone_d); - } else { - clone_d = (unsigned char *)&d; - if (xc->double_endian_match) { - memcpy(clone_d, srcdata, 8); - } else { - int j; - - for (j = 0; j < 8; j++) { - clone_d[j] = srcdata[7 - j]; - } - } - snprintf((char *)xc->temp_signal_value_buf, 32, "%.16g", d); - value_change_callback(user_callback_data_pointer, time_table[i], idx + 1, - xc->temp_signal_value_buf); - } - } else { - if (fv) { - char wx_buf[32]; - int wx_len; - - clone_d = (unsigned char *)&d; - if (xc->double_endian_match) { - memcpy(clone_d, srcdata, 8); - } else { - int j; - - for (j = 0; j < 8; j++) { - clone_d[j] = srcdata[7 - j]; - } - } - - wx_len = snprintf(wx_buf, sizeof(wx_buf), "r%.16g", d); + if(dumpvars_state == 1) { wx_len = snprintf(wx_buf, 32, "$end\n"); fstWritex(xc, wx_buf, wx_len); dumpvars_state = 2; } + wx_len = snprintf(wx_buf, 32, "#%" PRIu64 "\n", time_table[i]); fstWritex(xc, wx_buf, wx_len); - } + if(!dumpvars_state) { wx_len = snprintf(wx_buf, 32, "$dumpvars\n"); fstWritex(xc, wx_buf, wx_len); dumpvars_state = 1; } + + if((xc->num_blackouts)&&(cur_blackout != xc->num_blackouts)) + { + if(time_table[i] == xc->blackout_times[cur_blackout]) + { + wx_len = snprintf(wx_buf, 32, "$dump%s $end\n", (xc->blackout_activity[cur_blackout++]) ? "on" : "off"); + fstWritex(xc, wx_buf, wx_len); + } + } + previous_time = time_table[i]; + } } - } - if (fv) { - char vcd_id[16]; - int vcdid_len = fstVcdIDForFwrite(vcd_id + 1, idx + 1); - vcd_id[0] = ' '; - vcd_id[vcdid_len + 1] = '\n'; - fstWritex(xc, vcd_id, vcdid_len + 2); - } + while(tc_head[i]) + { + idx = tc_head[i] - 1; + vli = fstGetVarint32(mem_for_traversal + headptr[idx], &skiplen); - skiplen += len; - headptr[idx] += skiplen; - length_remaining[idx] -= skiplen; + if(xc->signal_lens[idx] <= 1) + { + if(xc->signal_lens[idx] == 1) + { + unsigned char val; + if(!(vli & 1)) + { + /* tdelta = vli >> 2; */ /* scan-build */ + val = ((vli >> 1) & 1) | '0'; + } + else + { + /* tdelta = vli >> 4; */ /* scan-build */ + val = FST_RCV_STR[((vli >> 1) & 7)]; + } - tc_head[i] = scatterptr[idx]; - scatterptr[idx] = 0; + if(value_change_callback) + { + xc->temp_signal_value_buf[0] = val; + xc->temp_signal_value_buf[1] = 0; + value_change_callback(user_callback_data_pointer, time_table[i], idx+1, xc->temp_signal_value_buf); + } + else + { + if(fv) + { + char vcd_id[16]; + int vcdid_len = fstVcdIDForFwrite(vcd_id+1, idx+1); - if (length_remaining[idx]) { - vli = fstGetVarint32NoSkip(mem_for_traversal + headptr[idx]); - tdelta = vli >> 1; + vcd_id[0] = val; + vcd_id[vcdid_len+1] = '\n'; + fstWritex(xc, vcd_id, vcdid_len+2); + } + } + headptr[idx] += skiplen; + length_remaining[idx] -= skiplen; - scatterptr[idx] = tc_head[i + tdelta]; - tc_head[i + tdelta] = idx + 1; - } + tc_head[i] = scatterptr[idx]; + scatterptr[idx] = 0; + + if(length_remaining[idx]) + { + int shamt; + vli = fstGetVarint32NoSkip(mem_for_traversal + headptr[idx]); + shamt = 2 << (vli & 1); + tdelta = vli >> shamt; + + if((tdelta+i) >= tc_head_items) + { + chk_report_abort("TALOS-2023-1791"); + } + + scatterptr[idx] = tc_head[i+tdelta]; + tc_head[i+tdelta] = idx+1; + } + } + else + { + unsigned char *vdata; + uint32_t len; + + vli = fstGetVarint32(mem_for_traversal + headptr[idx], &skiplen); + len = fstGetVarint32(mem_for_traversal + headptr[idx] + skiplen, &skiplen2); + /* tdelta = vli >> 1; */ /* scan-build */ + skiplen += skiplen2; + vdata = mem_for_traversal + headptr[idx] + skiplen; + + if(!(vli & 1)) + { + if(value_change_callback_varlen) + { + value_change_callback_varlen(user_callback_data_pointer, time_table[i], idx+1, vdata, len); + } + else + { + if(fv) + { + char vcd_id[16]; + int vcdid_len; + + vcd_id[0] = 's'; + fstWritex(xc, vcd_id, 1); + + vcdid_len = fstVcdIDForFwrite(vcd_id+1, idx+1); + { + if(sizeof(size_t) < sizeof(uint64_t)) + { + /* TALOS-2023-1790 for 32b overflow */ + uint64_t chk_64 = len*4 + 1; + size_t chk_32 = len*4 + 1; + if(chk_64 != chk_32) chk_report_abort("TALOS-2023-1790"); + } + + unsigned char *vesc = (unsigned char *)malloc(len*4 + 1); + int vlen = fstUtilityBinToEsc(vesc, vdata, len); + fstWritex(xc, vesc, vlen); + free(vesc); + } + + vcd_id[0] = ' '; + vcd_id[vcdid_len + 1] = '\n'; + fstWritex(xc, vcd_id, vcdid_len+2); + } + } + } + + skiplen += len; + headptr[idx] += skiplen; + length_remaining[idx] -= skiplen; + + tc_head[i] = scatterptr[idx]; + scatterptr[idx] = 0; + + if(length_remaining[idx]) + { + vli = fstGetVarint32NoSkip(mem_for_traversal + headptr[idx]); + tdelta = vli >> 1; + + if((tdelta+i) >= tc_head_items) + { + chk_report_abort("TALOS-2023-1791"); + } + + scatterptr[idx] = tc_head[i+tdelta]; + tc_head[i+tdelta] = idx+1; + } + } + } + else + { + uint32_t len = xc->signal_lens[idx]; + unsigned char *vdata; + + vli = fstGetVarint32(mem_for_traversal + headptr[idx], &skiplen); + /* tdelta = vli >> 1; */ /* scan-build */ + vdata = mem_for_traversal + headptr[idx] + skiplen; + + if(xc->signal_typs[idx] != FST_VT_VCD_REAL) + { + if(len > xc->longest_signal_value_len) + { + chk_report_abort("TALOS-2023-1797"); + } + + if(!(vli & 1)) + { + int byte = 0; + int bit; + unsigned int j; + + for(j=0;j> bit) & 1) | '0'; + xc->temp_signal_value_buf[j] = ch; + } + xc->temp_signal_value_buf[j] = 0; + + if(value_change_callback) + { + value_change_callback(user_callback_data_pointer, time_table[i], idx+1, xc->temp_signal_value_buf); + } + else + { + if(fv) { + unsigned char ch_bp = (xc->signal_typs[idx] != FST_VT_VCD_PORT) ? 'b' : 'p'; + + fstWritex(xc, &ch_bp, 1); + fstWritex(xc, xc->temp_signal_value_buf, len); + } + } + + len = byte+1; + } + else + { + if(value_change_callback) + { + memcpy(xc->temp_signal_value_buf, vdata, len); + xc->temp_signal_value_buf[len] = 0; + value_change_callback(user_callback_data_pointer, time_table[i], idx+1, xc->temp_signal_value_buf); + } + else + { + if(fv) + { + unsigned char ch_bp = (xc->signal_typs[idx] != FST_VT_VCD_PORT) ? 'b' : 'p'; + uint64_t mem_required_for_traversal_chk = vdata - mem_for_traversal + len; + + fstWritex(xc, &ch_bp, 1); + if(mem_required_for_traversal_chk > mem_required_for_traversal) + { + chk_report_abort("TALOS-2023-1793"); + } + fstWritex(xc, vdata, len); + } + } + } + } + else + { + double d; + unsigned char *clone_d /*= (unsigned char *)&d */; /* scan-build */ + unsigned char buf[8]; + unsigned char *srcdata; + + if(!(vli & 1)) /* very rare case, but possible */ + { + int bit; + int j; + + for(j=0;j<8;j++) + { + unsigned char ch; + bit = 7 - (j & 7); + ch = ((vdata[0] >> bit) & 1) | '0'; + buf[j] = ch; + } + + len = 1; + srcdata = buf; + } + else + { + srcdata = vdata; + } + + if(value_change_callback) + { + if(xc->native_doubles_for_cb) + { + if(xc->double_endian_match) + { + clone_d = srcdata; + } + else + { + int j; + + clone_d = (unsigned char *)&d; + for(j=0;j<8;j++) + { + clone_d[j] = srcdata[7-j]; + } + } + value_change_callback(user_callback_data_pointer, time_table[i], idx+1, clone_d); + } + else + { + clone_d = (unsigned char *)&d; + if(xc->double_endian_match) + { + memcpy(clone_d, srcdata, 8); + } + else + { + int j; + + for(j=0;j<8;j++) + { + clone_d[j] = srcdata[7-j]; + } + } + snprintf((char *)xc->temp_signal_value_buf, xc->longest_signal_value_len + 1, "%.16g", d); + value_change_callback(user_callback_data_pointer, time_table[i], idx+1, xc->temp_signal_value_buf); + } + } + else + { + if(fv) + { + char wx_buf[32]; + int wx_len; + + clone_d = (unsigned char *)&d; + if(xc->double_endian_match) + { + memcpy(clone_d, srcdata, 8); + } + else + { + int j; + + for(j=0;j<8;j++) + { + clone_d[j] = srcdata[7-j]; + } + } + + wx_len = snprintf(wx_buf, 32, "r%.16g", d); + fstWritex(xc, wx_buf, wx_len); + } + } + } + + if(fv) + { + char vcd_id[16]; + int vcdid_len = fstVcdIDForFwrite(vcd_id+1, idx+1); + vcd_id[0] = ' '; + vcd_id[vcdid_len+1] = '\n'; + fstWritex(xc, vcd_id, vcdid_len+2); + } + + skiplen += len; + headptr[idx] += skiplen; + length_remaining[idx] -= skiplen; + + tc_head[i] = scatterptr[idx]; + scatterptr[idx] = 0; + + if(length_remaining[idx]) + { + vli = fstGetVarint32NoSkip(mem_for_traversal + headptr[idx]); + tdelta = vli >> 1; + + if((tdelta+i) >= tc_head_items) + { + chk_report_abort("TALOS-2023-1791"); + } + + scatterptr[idx] = tc_head[i+tdelta]; + tc_head[i+tdelta] = idx+1; + } + } + } } - } - } - block_err: +block_err: free(tc_head); free(chain_cmem); - free(mem_for_traversal); - mem_for_traversal = NULL; + free(mem_for_traversal); mem_for_traversal = NULL; secnum++; - if (secnum == xc->vc_section_count) - break; /* in case file is growing, keep with original block count */ + if(secnum == xc->vc_section_count) break; /* in case file is growing, keep with original block count */ blkpos += seclen; - } + } - if (mem_for_traversal) - free(mem_for_traversal); /* scan-build */ - free(length_remaining); - free(headptr); - free(scatterptr); +if(mem_for_traversal) free(mem_for_traversal); /* scan-build */ +free(length_remaining); +free(headptr); +free(scatterptr); - if (chain_table) - free(chain_table); - if (chain_table_lengths) - free(chain_table_lengths); +if(chain_table) free(chain_table); +if(chain_table_lengths) free(chain_table_lengths); - free(time_table); +free(time_table); #ifndef FST_WRITEX_DISABLE - if (fv) { +if(fv) + { fstWritex(xc, NULL, 0); - } + } #endif - return (1); +return(1); } + /* rvat functions */ static char *fstExtractRvatDataFromFrame(struct fstReaderContext *xc, fstHandle facidx, char *buf) { - if (facidx >= xc->rvat_frame_maxhandle) { - return (NULL); - } +if(facidx >= xc->rvat_frame_maxhandle) + { + return(NULL); + } - if (xc->signal_lens[facidx] == 1) { +if(xc->signal_lens[facidx] == 1) + { buf[0] = (char)xc->rvat_frame_data[xc->rvat_sig_offs[facidx]]; buf[1] = 0; - } else { - if (xc->signal_typs[facidx] != FST_VT_VCD_REAL) { - memcpy(buf, xc->rvat_frame_data + xc->rvat_sig_offs[facidx], xc->signal_lens[facidx]); - buf[xc->signal_lens[facidx]] = 0; - } else { - double d; - unsigned char *clone_d = (unsigned char *)&d; - unsigned char *srcdata = xc->rvat_frame_data + xc->rvat_sig_offs[facidx]; - - if (xc->double_endian_match) { - memcpy(clone_d, srcdata, 8); - } else { - int j; - - for (j = 0; j < 8; j++) { - clone_d[j] = srcdata[7 - j]; - } - } - - snprintf((char *)buf, 32, "%.16g", d); } - } + else + { + if(xc->signal_typs[facidx] != FST_VT_VCD_REAL) + { + memcpy(buf, xc->rvat_frame_data + xc->rvat_sig_offs[facidx], xc->signal_lens[facidx]); + buf[xc->signal_lens[facidx]] = 0; + } + else + { + double d; + unsigned char *clone_d = (unsigned char *)&d; + unsigned char *srcdata = xc->rvat_frame_data + xc->rvat_sig_offs[facidx]; - return (buf); + if(xc->double_endian_match) + { + memcpy(clone_d, srcdata, 8); + } + else + { + int j; + + for(j=0;j<8;j++) + { + clone_d[j] = srcdata[7-j]; + } + } + + snprintf((char *)buf, 32, "%.16g", d); /* this will write 18 bytes */ + } + } + +return(buf); } + char *fstReaderGetValueFromHandleAtTime(void *ctx, uint64_t tim, fstHandle facidx, char *buf) { - struct fstReaderContext *xc = (struct fstReaderContext *)ctx; - fst_off_t blkpos = 0, prev_blkpos; - uint64_t beg_tim, end_tim, beg_tim2, end_tim2; - int sectype; +struct fstReaderContext *xc = (struct fstReaderContext *)ctx; +fst_off_t blkpos = 0, prev_blkpos; +uint64_t beg_tim, end_tim, beg_tim2, end_tim2; +int sectype; #ifdef FST_DEBUG - unsigned int secnum = 0; +unsigned int secnum = 0; #endif - uint64_t seclen; - uint64_t tsec_uclen = 0, tsec_clen = 0; - uint64_t tsec_nitems; - uint64_t frame_uclen, frame_clen; +uint64_t seclen; +uint64_t tsec_uclen = 0, tsec_clen = 0; +uint64_t tsec_nitems; +uint64_t frame_uclen, frame_clen; #ifdef FST_DEBUG - uint64_t mem_required_for_traversal; +uint64_t mem_required_for_traversal; #endif - fst_off_t indx_pntr, indx_pos; - long chain_clen; - unsigned char *chain_cmem; - unsigned char *pnt; - fstHandle idx, pidx = 0, i; - uint64_t pval; +fst_off_t indx_pntr, indx_pos; +long chain_clen; +unsigned char *chain_cmem; +unsigned char *pnt; +fstHandle idx, pidx=0, i; +uint64_t pval; - if ((!xc) || (!facidx) || (facidx > xc->maxhandle) || (!buf) || (!xc->signal_lens[facidx - 1])) { - return (NULL); - } +if((!xc) || (!facidx) || (facidx > xc->maxhandle) || (!buf) || (!xc->signal_lens[facidx-1])) + { + return(NULL); + } - if (!xc->rvat_sig_offs) { +if(!xc->rvat_sig_offs) + { uint32_t cur_offs = 0; xc->rvat_sig_offs = (uint32_t *)calloc(xc->maxhandle, sizeof(uint32_t)); - for (i = 0; i < xc->maxhandle; i++) { - xc->rvat_sig_offs[i] = cur_offs; - cur_offs += xc->signal_lens[i]; + for(i=0;imaxhandle;i++) + { + xc->rvat_sig_offs[i] = cur_offs; + cur_offs += xc->signal_lens[i]; + } } - } - if (xc->rvat_data_valid) { - if ((xc->rvat_beg_tim <= tim) && (tim <= xc->rvat_end_tim)) { - goto process_value; - } +if(xc->rvat_data_valid) + { + if((xc->rvat_beg_tim <= tim) && (tim <= xc->rvat_end_tim)) + { + goto process_value; + } fstReaderDeallocateRvatData(xc); - } + } - xc->rvat_chain_pos_valid = 0; +xc->rvat_chain_pos_valid = 0; - for (;;) { +for(;;) + { fstReaderFseeko(xc, xc->f, (prev_blkpos = blkpos), SEEK_SET); sectype = fgetc(xc->f); seclen = fstReaderUint64(xc->f); - if ((sectype == EOF) || (sectype == FST_BL_SKIP) || (!seclen)) { - return (NULL); /* if this loop exits on break, it's successful */ - } + if((sectype == EOF) || (sectype == FST_BL_SKIP) || (!seclen)) + { + return(NULL); /* if this loop exits on break, it's successful */ + } blkpos++; - if ((sectype != FST_BL_VCDATA) && (sectype != FST_BL_VCDATA_DYN_ALIAS) && - (sectype != FST_BL_VCDATA_DYN_ALIAS2)) { - blkpos += seclen; - continue; - } + if((sectype != FST_BL_VCDATA) && (sectype != FST_BL_VCDATA_DYN_ALIAS) && (sectype != FST_BL_VCDATA_DYN_ALIAS2)) + { + blkpos += seclen; + continue; + } beg_tim = fstReaderUint64(xc->f); end_tim = fstReaderUint64(xc->f); - if ((beg_tim <= tim) && (tim <= end_tim)) { - if ((tim == end_tim) && (tim != xc->end_time)) { - fst_off_t cached_pos = ftello(xc->f); - fstReaderFseeko(xc, xc->f, blkpos, SEEK_SET); + if((beg_tim <= tim) && (tim <= end_tim)) + { + if((tim == end_tim) && (tim != xc->end_time)) + { + fst_off_t cached_pos = ftello(xc->f); + fstReaderFseeko(xc, xc->f, blkpos, SEEK_SET); - sectype = fgetc(xc->f); - seclen = fstReaderUint64(xc->f); + sectype = fgetc(xc->f); + seclen = fstReaderUint64(xc->f); - beg_tim2 = fstReaderUint64(xc->f); - end_tim2 = fstReaderUint64(xc->f); + beg_tim2 = fstReaderUint64(xc->f); + end_tim2 = fstReaderUint64(xc->f); - if (((sectype != FST_BL_VCDATA) && (sectype != FST_BL_VCDATA_DYN_ALIAS) && - (sectype != FST_BL_VCDATA_DYN_ALIAS2)) || - (!seclen) || (beg_tim2 != tim)) { - blkpos = prev_blkpos; - break; + if(((sectype != FST_BL_VCDATA)&&(sectype != FST_BL_VCDATA_DYN_ALIAS)&&(sectype != FST_BL_VCDATA_DYN_ALIAS2)) || (!seclen) || (beg_tim2 != tim)) + { + blkpos = prev_blkpos; + break; + } + beg_tim = beg_tim2; + end_tim = end_tim2; + fstReaderFseeko(xc, xc->f, cached_pos, SEEK_SET); + } + break; } - beg_tim = beg_tim2; - end_tim = end_tim2; - fstReaderFseeko(xc, xc->f, cached_pos, SEEK_SET); - } - break; - } blkpos += seclen; #ifdef FST_DEBUG secnum++; #endif - } + } - xc->rvat_beg_tim = beg_tim; - xc->rvat_end_tim = end_tim; +xc->rvat_beg_tim = beg_tim; +xc->rvat_end_tim = end_tim; #ifdef FST_DEBUG - mem_required_for_traversal = +mem_required_for_traversal = #endif - fstReaderUint64(xc->f); + fstReaderUint64(xc->f); #ifdef FST_DEBUG - fprintf(stderr, FST_APIMESS "rvat sec: %u seclen: %d begtim: %d endtim: %d\n", secnum, (int)seclen, (int)beg_tim, - (int)end_tim); - fprintf(stderr, FST_APIMESS "mem_required_for_traversal: %d\n", (int)mem_required_for_traversal); +fprintf(stderr, FST_APIMESS "rvat sec: %u seclen: %d begtim: %d endtim: %d\n", + secnum, (int)seclen, (int)beg_tim, (int)end_tim); +fprintf(stderr, FST_APIMESS "mem_required_for_traversal: %d\n", (int)mem_required_for_traversal); #endif - /* process time block */ - { - unsigned char *ucdata; - unsigned char *cdata; - unsigned long destlen /* = tsec_uclen */; /* scan-build */ - unsigned long sourcelen /* = tsec_clen */; /* scan-build */ - int rc; - unsigned char *tpnt; - uint64_t tpval; - unsigned int ti; +/* process time block */ +{ +unsigned char *ucdata; +unsigned char *cdata; +unsigned long destlen /* = tsec_uclen */; /* scan-build */ +unsigned long sourcelen /* = tsec_clen */; /* scan-build */ +int rc; +unsigned char *tpnt; +uint64_t tpval; +unsigned int ti; - fstReaderFseeko(xc, xc->f, blkpos + seclen - 24, SEEK_SET); - tsec_uclen = fstReaderUint64(xc->f); - tsec_clen = fstReaderUint64(xc->f); - tsec_nitems = fstReaderUint64(xc->f); +fstReaderFseeko(xc, xc->f, blkpos + seclen - 24, SEEK_SET); +tsec_uclen = fstReaderUint64(xc->f); +tsec_clen = fstReaderUint64(xc->f); +tsec_nitems = fstReaderUint64(xc->f); #ifdef FST_DEBUG - fprintf(stderr, FST_APIMESS "time section unc: %d, com: %d (%d items)\n", (int)tsec_uclen, (int)tsec_clen, - (int)tsec_nitems); +fprintf(stderr, FST_APIMESS "time section unc: %d, com: %d (%d items)\n", + (int)tsec_uclen, (int)tsec_clen, (int)tsec_nitems); #endif - ucdata = (unsigned char *)malloc(tsec_uclen); - destlen = tsec_uclen; - sourcelen = tsec_clen; +ucdata = (unsigned char *)malloc(tsec_uclen); +destlen = tsec_uclen; +sourcelen = tsec_clen; - fstReaderFseeko(xc, xc->f, -24 - ((fst_off_t)tsec_clen), SEEK_CUR); - if (tsec_uclen != tsec_clen) { - cdata = (unsigned char *)malloc(tsec_clen); - fstFread(cdata, tsec_clen, 1, xc->f); +fstReaderFseeko(xc, xc->f, -24 - ((fst_off_t)tsec_clen), SEEK_CUR); +if(tsec_uclen != tsec_clen) + { + cdata = (unsigned char *)malloc(tsec_clen); + fstFread(cdata, tsec_clen, 1, xc->f); - rc = uncompress(ucdata, &destlen, cdata, sourcelen); + rc = uncompress(ucdata, &destlen, cdata, sourcelen); - if (rc != Z_OK) { - fprintf(stderr, FST_APIMESS "fstReaderGetValueFromHandleAtTime(), tsec uncompress rc = %d, exiting.\n", - rc); + if(rc != Z_OK) + { + fprintf(stderr, FST_APIMESS "fstReaderGetValueFromHandleAtTime(), tsec uncompress rc = %d, exiting.\n", rc); exit(255); - } + } - free(cdata); - } else { - fstFread(ucdata, tsec_uclen, 1, xc->f); + free(cdata); + } + else + { + fstFread(ucdata, tsec_uclen, 1, xc->f); } - xc->rvat_time_table = (uint64_t *)calloc(tsec_nitems, sizeof(uint64_t)); - tpnt = ucdata; - tpval = 0; - for (ti = 0; ti < tsec_nitems; ti++) { - int skiplen; - uint64_t val = fstGetVarint64(tpnt, &skiplen); - tpval = xc->rvat_time_table[ti] = tpval + val; - tpnt += skiplen; +xc->rvat_time_table = (uint64_t *)calloc(tsec_nitems, sizeof(uint64_t)); +tpnt = ucdata; +tpval = 0; +for(ti=0;tirvat_time_table[ti] = tpval + val; + tpnt += skiplen; } - free(ucdata); - } +free(ucdata); +} - fstReaderFseeko(xc, xc->f, blkpos + 32, SEEK_SET); +fstReaderFseeko(xc, xc->f, blkpos+32, SEEK_SET); - frame_uclen = fstReaderVarint64(xc->f); - frame_clen = fstReaderVarint64(xc->f); - xc->rvat_frame_maxhandle = fstReaderVarint64(xc->f); - xc->rvat_frame_data = (unsigned char *)malloc(frame_uclen); +frame_uclen = fstReaderVarint64(xc->f); +frame_clen = fstReaderVarint64(xc->f); +xc->rvat_frame_maxhandle = fstReaderVarint64(xc->f); +xc->rvat_frame_data = (unsigned char *)malloc(frame_uclen); - if (frame_uclen == frame_clen) { +if(frame_uclen == frame_clen) + { fstFread(xc->rvat_frame_data, frame_uclen, 1, xc->f); - } else { + } + else + { unsigned char *mc = (unsigned char *)malloc(frame_clen); int rc; @@ -5716,277 +6383,321 @@ char *fstReaderGetValueFromHandleAtTime(void *ctx, uint64_t tim, fstHandle facid fstFread(mc, sourcelen, 1, xc->f); rc = uncompress(xc->rvat_frame_data, &destlen, mc, sourcelen); - if (rc != Z_OK) { - fprintf(stderr, FST_APIMESS "fstReaderGetValueFromHandleAtTime(), frame decompress rc: %d, exiting.\n", rc); - exit(255); - } + if(rc != Z_OK) + { + fprintf(stderr, FST_APIMESS "fstReaderGetValueFromHandleAtTime(), frame decompress rc: %d, exiting.\n", rc); + exit(255); + } free(mc); - } + } - xc->rvat_vc_maxhandle = fstReaderVarint64(xc->f); - xc->rvat_vc_start = ftello(xc->f); /* points to '!' character */ - xc->rvat_packtype = fgetc(xc->f); +xc->rvat_vc_maxhandle = fstReaderVarint64(xc->f); +xc->rvat_vc_start = ftello(xc->f); /* points to '!' character */ +xc->rvat_packtype = fgetc(xc->f); #ifdef FST_DEBUG - fprintf(stderr, FST_APIMESS "frame_uclen: %d, frame_clen: %d, frame_maxhandle: %d\n", (int)frame_uclen, - (int)frame_clen, (int)xc->rvat_frame_maxhandle); - fprintf(stderr, FST_APIMESS "vc_maxhandle: %d\n", (int)xc->rvat_vc_maxhandle); +fprintf(stderr, FST_APIMESS "frame_uclen: %d, frame_clen: %d, frame_maxhandle: %d\n", + (int)frame_uclen, (int)frame_clen, (int)xc->rvat_frame_maxhandle); +fprintf(stderr, FST_APIMESS "vc_maxhandle: %d\n", (int)xc->rvat_vc_maxhandle); #endif - indx_pntr = blkpos + seclen - 24 - tsec_clen - 8; - fstReaderFseeko(xc, xc->f, indx_pntr, SEEK_SET); - chain_clen = fstReaderUint64(xc->f); - indx_pos = indx_pntr - chain_clen; +indx_pntr = blkpos + seclen - 24 -tsec_clen -8; +fstReaderFseeko(xc, xc->f, indx_pntr, SEEK_SET); +chain_clen = fstReaderUint64(xc->f); +indx_pos = indx_pntr - chain_clen; #ifdef FST_DEBUG - fprintf(stderr, FST_APIMESS "indx_pos: %d (%d bytes)\n", (int)indx_pos, (int)chain_clen); +fprintf(stderr, FST_APIMESS "indx_pos: %d (%d bytes)\n", (int)indx_pos, (int)chain_clen); #endif - chain_cmem = (unsigned char *)malloc(chain_clen); - fstReaderFseeko(xc, xc->f, indx_pos, SEEK_SET); - fstFread(chain_cmem, chain_clen, 1, xc->f); +chain_cmem = (unsigned char *)malloc(chain_clen); +fstReaderFseeko(xc, xc->f, indx_pos, SEEK_SET); +fstFread(chain_cmem, chain_clen, 1, xc->f); - xc->rvat_chain_table = (fst_off_t *)calloc((xc->rvat_vc_maxhandle + 1), sizeof(fst_off_t)); - xc->rvat_chain_table_lengths = (uint32_t *)calloc((xc->rvat_vc_maxhandle + 1), sizeof(uint32_t)); +xc->rvat_chain_table = (fst_off_t *)calloc((xc->rvat_vc_maxhandle+1), sizeof(fst_off_t)); +xc->rvat_chain_table_lengths = (uint32_t *)calloc((xc->rvat_vc_maxhandle+1), sizeof(uint32_t)); - pnt = chain_cmem; - idx = 0; - pval = 0; +pnt = chain_cmem; +idx = 0; +pval = 0; - if (sectype == FST_BL_VCDATA_DYN_ALIAS2) { +if(sectype == FST_BL_VCDATA_DYN_ALIAS2) + { uint32_t prev_alias = 0; - do { - int skiplen; + do { + int skiplen; - if (*pnt & 0x01) { - int64_t shval = fstGetSVarint64(pnt, &skiplen) >> 1; - if (shval > 0) { - pval = xc->rvat_chain_table[idx] = pval + shval; - if (idx) { - xc->rvat_chain_table_lengths[pidx] = pval - xc->rvat_chain_table[pidx]; - } - pidx = idx++; - } else if (shval < 0) { - xc->rvat_chain_table[idx] = 0; /* need to explicitly zero as calloc above might not run */ - xc->rvat_chain_table_lengths[idx] = prev_alias = - shval; /* because during this loop iter would give stale data! */ - idx++; - } else { - xc->rvat_chain_table[idx] = 0; /* need to explicitly zero as calloc above might not run */ - xc->rvat_chain_table_lengths[idx] = - prev_alias; /* because during this loop iter would give stale data! */ - idx++; - } - } else { - uint64_t val = fstGetVarint32(pnt, &skiplen); + if(*pnt & 0x01) + { + int64_t shval = fstGetSVarint64(pnt, &skiplen) >> 1; + if(shval > 0) + { + pval = xc->rvat_chain_table[idx] = pval + shval; + if(idx) { xc->rvat_chain_table_lengths[pidx] = pval - xc->rvat_chain_table[pidx]; } + pidx = idx++; + } + else if(shval < 0) + { + xc->rvat_chain_table[idx] = 0; /* need to explicitly zero as calloc above might not run */ + xc->rvat_chain_table_lengths[idx] = prev_alias = shval; /* because during this loop iter would give stale data! */ + idx++; + } + else + { + xc->rvat_chain_table[idx] = 0; /* need to explicitly zero as calloc above might not run */ + xc->rvat_chain_table_lengths[idx] = prev_alias; /* because during this loop iter would give stale data! */ + idx++; + } + } + else + { + uint64_t val = fstGetVarint32(pnt, &skiplen); - fstHandle loopcnt = val >> 1; - for (i = 0; i < loopcnt; i++) { - xc->rvat_chain_table[idx++] = 0; - } - } + fstHandle loopcnt = val >> 1; + for(i=0;irvat_chain_table[idx++] = 0; + } + } - pnt += skiplen; - } while (pnt != (chain_cmem + chain_clen)); - } else { - do { - int skiplen; - uint64_t val = fstGetVarint32(pnt, &skiplen); - - if (!val) { pnt += skiplen; - val = fstGetVarint32(pnt, &skiplen); - xc->rvat_chain_table[idx] = 0; - xc->rvat_chain_table_lengths[idx] = -val; - idx++; - } else if (val & 1) { - pval = xc->rvat_chain_table[idx] = pval + (val >> 1); - if (idx) { - xc->rvat_chain_table_lengths[pidx] = pval - xc->rvat_chain_table[pidx]; - } - pidx = idx++; - } else { - fstHandle loopcnt = val >> 1; - for (i = 0; i < loopcnt; i++) { - xc->rvat_chain_table[idx++] = 0; - } - } - - pnt += skiplen; - } while (pnt != (chain_cmem + chain_clen)); - } - - free(chain_cmem); - xc->rvat_chain_table[idx] = indx_pos - xc->rvat_vc_start; - xc->rvat_chain_table_lengths[pidx] = xc->rvat_chain_table[idx] - xc->rvat_chain_table[pidx]; - - for (i = 0; i < idx; i++) { - int32_t v32 = xc->rvat_chain_table_lengths[i]; - if ((v32 < 0) && (!xc->rvat_chain_table[i])) { - v32 = -v32; - v32--; - if (((uint32_t)v32) < i) /* sanity check */ - { - xc->rvat_chain_table[i] = xc->rvat_chain_table[v32]; - xc->rvat_chain_table_lengths[i] = xc->rvat_chain_table_lengths[v32]; - } + } while (pnt != (chain_cmem + chain_clen)); + } + else + { + do + { + int skiplen; + uint64_t val = fstGetVarint32(pnt, &skiplen); + + if(!val) + { + pnt += skiplen; + val = fstGetVarint32(pnt, &skiplen); + xc->rvat_chain_table[idx] = 0; + xc->rvat_chain_table_lengths[idx] = -val; + idx++; + } + else + if(val&1) + { + pval = xc->rvat_chain_table[idx] = pval + (val >> 1); + if(idx) { xc->rvat_chain_table_lengths[pidx] = pval - xc->rvat_chain_table[pidx]; } + pidx = idx++; + } + else + { + fstHandle loopcnt = val >> 1; + for(i=0;irvat_chain_table[idx++] = 0; + } + } + + pnt += skiplen; + } while (pnt != (chain_cmem + chain_clen)); + } + +free(chain_cmem); +xc->rvat_chain_table[idx] = indx_pos - xc->rvat_vc_start; +xc->rvat_chain_table_lengths[pidx] = xc->rvat_chain_table[idx] - xc->rvat_chain_table[pidx]; + +for(i=0;irvat_chain_table_lengths[i]; + if((v32 < 0) && (!xc->rvat_chain_table[i])) + { + v32 = -v32; + v32--; + if(((uint32_t)v32) < i) /* sanity check */ + { + xc->rvat_chain_table[i] = xc->rvat_chain_table[v32]; + xc->rvat_chain_table_lengths[i] = xc->rvat_chain_table_lengths[v32]; + } + } } - } #ifdef FST_DEBUG - fprintf(stderr, FST_APIMESS "decompressed chain idx len: %" PRIu32 "\n", idx); +fprintf(stderr, FST_APIMESS "decompressed chain idx len: %" PRIu32 "\n", idx); #endif - xc->rvat_data_valid = 1; +xc->rvat_data_valid = 1; /* all data at this point is loaded or resident in fst cache, process and return appropriate value */ process_value: - if (facidx > xc->rvat_vc_maxhandle) { - return (NULL); - } - - facidx--; /* scale down for array which starts at zero */ - - if (((tim == xc->rvat_beg_tim) && (!xc->rvat_chain_table[facidx])) || (!xc->rvat_chain_table[facidx])) { - return (fstExtractRvatDataFromFrame(xc, facidx, buf)); - } - - if (facidx != xc->rvat_chain_facidx) { - if (xc->rvat_chain_mem) { - free(xc->rvat_chain_mem); - xc->rvat_chain_mem = NULL; - - xc->rvat_chain_pos_valid = 0; +if(facidx > xc->rvat_vc_maxhandle) + { + return(NULL); } - } - if (!xc->rvat_chain_mem) { +facidx--; /* scale down for array which starts at zero */ + + +if(((tim == xc->rvat_beg_tim)&&(!xc->rvat_chain_table[facidx])) || (!xc->rvat_chain_table[facidx])) + { + return(fstExtractRvatDataFromFrame(xc, facidx, buf)); + } + +if(facidx != xc->rvat_chain_facidx) + { + if(xc->rvat_chain_mem) + { + free(xc->rvat_chain_mem); + xc->rvat_chain_mem = NULL; + + xc->rvat_chain_pos_valid = 0; + } + } + +if(!xc->rvat_chain_mem) + { uint32_t skiplen; fstReaderFseeko(xc, xc->f, xc->rvat_vc_start + xc->rvat_chain_table[facidx], SEEK_SET); xc->rvat_chain_len = fstReaderVarint32WithSkip(xc->f, &skiplen); - if (xc->rvat_chain_len) { - unsigned char *mu = (unsigned char *)malloc(xc->rvat_chain_len); - unsigned char *mc = (unsigned char *)malloc(xc->rvat_chain_table_lengths[facidx]); - unsigned long destlen = xc->rvat_chain_len; - unsigned long sourcelen = xc->rvat_chain_table_lengths[facidx]; - int rc = Z_OK; + if(xc->rvat_chain_len) + { + unsigned char *mu = (unsigned char *)malloc(xc->rvat_chain_len); + unsigned char *mc = (unsigned char *)malloc(xc->rvat_chain_table_lengths[facidx]); + unsigned long destlen = xc->rvat_chain_len; + unsigned long sourcelen = xc->rvat_chain_table_lengths[facidx]; + int rc = Z_OK; - fstFread(mc, xc->rvat_chain_table_lengths[facidx], 1, xc->f); + fstFread(mc, xc->rvat_chain_table_lengths[facidx], 1, xc->f); - switch (xc->rvat_packtype) { - case '4': - rc = (destlen == - (unsigned long)LZ4_decompress_safe_partial((char *)mc, (char *)mu, sourcelen, destlen, destlen)) - ? Z_OK - : Z_DATA_ERROR; - break; - case 'F': - fastlz_decompress(mc, sourcelen, mu, destlen); /* rc appears unreliable */ - break; - default: - rc = uncompress(mu, &destlen, mc, sourcelen); - break; - } + switch(xc->rvat_packtype) + { + case '4': rc = (destlen == (unsigned long)LZ4_decompress_safe_partial((char *)mc, (char *)mu, sourcelen, destlen, destlen)) ? Z_OK : Z_DATA_ERROR; + break; + case 'F': fastlz_decompress(mc, sourcelen, mu, destlen); /* rc appears unreliable */ + break; + default: rc = uncompress(mu, &destlen, mc, sourcelen); + break; + } - free(mc); + free(mc); - if (rc != Z_OK) { - fprintf(stderr, - FST_APIMESS "fstReaderGetValueFromHandleAtTime(), rvat decompress clen: %d (rc=%d), exiting.\n", - (int)xc->rvat_chain_len, rc); - exit(255); - } + if(rc != Z_OK) + { + fprintf(stderr, FST_APIMESS "fstReaderGetValueFromHandleAtTime(), rvat decompress clen: %d (rc=%d), exiting.\n", (int)xc->rvat_chain_len, rc); + exit(255); + } - /* data to process is for(j=0;jrvat_chain_mem = mu; - } else { - int destlen = xc->rvat_chain_table_lengths[facidx] - skiplen; - unsigned char *mu = (unsigned char *)malloc(xc->rvat_chain_len = destlen); - fstFread(mu, destlen, 1, xc->f); - /* data to process is for(j=0;jrvat_chain_mem = mu; - } + /* data to process is for(j=0;jrvat_chain_mem = mu; + } + else + { + int destlen = xc->rvat_chain_table_lengths[facidx] - skiplen; + unsigned char *mu = (unsigned char *)malloc(xc->rvat_chain_len = destlen); + fstFread(mu, destlen, 1, xc->f); + /* data to process is for(j=0;jrvat_chain_mem = mu; + } xc->rvat_chain_facidx = facidx; - } - - /* process value chain here */ - - { - uint32_t tidx = 0, ptidx = 0; - uint32_t tdelta; - int skiplen; - unsigned int iprev = xc->rvat_chain_len; - uint32_t pvli = 0; - int pskip = 0; - - if ((xc->rvat_chain_pos_valid) && (tim >= xc->rvat_chain_pos_time)) { - i = xc->rvat_chain_pos_idx; - tidx = xc->rvat_chain_pos_tidx; - } else { - i = 0; - tidx = 0; - xc->rvat_chain_pos_time = xc->rvat_beg_tim; } - if (xc->signal_lens[facidx] == 1) { - while (i < xc->rvat_chain_len) { +/* process value chain here */ + +{ +uint32_t tidx = 0, ptidx = 0; +uint32_t tdelta; +int skiplen; +unsigned int iprev = xc->rvat_chain_len; +uint32_t pvli = 0; +int pskip = 0; + +if((xc->rvat_chain_pos_valid)&&(tim >= xc->rvat_chain_pos_time)) + { + i = xc->rvat_chain_pos_idx; + tidx = xc->rvat_chain_pos_tidx; + } + else + { + i = 0; + tidx = 0; + xc->rvat_chain_pos_time = xc->rvat_beg_tim; + } + +if(xc->signal_lens[facidx] == 1) + { + while(irvat_chain_len) + { uint32_t vli = fstGetVarint32(xc->rvat_chain_mem + i, &skiplen); uint32_t shcnt = 2 << (vli & 1); tdelta = vli >> shcnt; - if (xc->rvat_time_table[tidx + tdelta] <= tim) { - iprev = i; - pvli = vli; - ptidx = tidx; - /* pskip = skiplen; */ /* scan-build */ + if(xc->rvat_time_table[tidx + tdelta] <= tim) + { + iprev = i; + pvli = vli; + ptidx = tidx; + /* pskip = skiplen; */ /* scan-build */ - tidx += tdelta; - i += skiplen; - } else { - break; + tidx += tdelta; + i+=skiplen; + } + else + { + break; + } } - } - if (iprev != xc->rvat_chain_len) { + if(iprev != xc->rvat_chain_len) + { xc->rvat_chain_pos_tidx = ptidx; xc->rvat_chain_pos_idx = iprev; xc->rvat_chain_pos_time = tim; xc->rvat_chain_pos_valid = 1; - if (!(pvli & 1)) { - buf[0] = ((pvli >> 1) & 1) | '0'; - } else { - buf[0] = FST_RCV_STR[((pvli >> 1) & 7)]; - } + if(!(pvli & 1)) + { + buf[0] = ((pvli >> 1) & 1) | '0'; + } + else + { + buf[0] = FST_RCV_STR[((pvli >> 1) & 7)]; + } buf[1] = 0; - return (buf); - } else { - return (fstExtractRvatDataFromFrame(xc, facidx, buf)); - } - } else { - while (i < xc->rvat_chain_len) { + return(buf); + } + else + { + return(fstExtractRvatDataFromFrame(xc, facidx, buf)); + } + } + else + { + while(irvat_chain_len) + { uint32_t vli = fstGetVarint32(xc->rvat_chain_mem + i, &skiplen); tdelta = vli >> 1; - if (xc->rvat_time_table[tidx + tdelta] <= tim) { - iprev = i; - pvli = vli; - ptidx = tidx; - pskip = skiplen; + if(xc->rvat_time_table[tidx + tdelta] <= tim) + { + iprev = i; + pvli = vli; + ptidx = tidx; + pskip = skiplen; - tidx += tdelta; - i += skiplen; + tidx += tdelta; + i+=skiplen; - if (!(pvli & 1)) { - i += ((xc->signal_lens[facidx] + 7) / 8); - } else { - i += xc->signal_lens[facidx]; - } - } else { - break; + if(!(pvli & 1)) + { + i+=((xc->signal_lens[facidx]+7)/8); + } + else + { + i+=xc->signal_lens[facidx]; + } + } + else + { + break; + } } - } - if (iprev != xc->rvat_chain_len) { + if(iprev != xc->rvat_chain_len) + { unsigned char *vdata = xc->rvat_chain_mem + iprev + pskip; xc->rvat_chain_pos_tidx = ptidx; @@ -5994,72 +6705,90 @@ process_value: xc->rvat_chain_pos_time = tim; xc->rvat_chain_pos_valid = 1; - if (xc->signal_typs[facidx] != FST_VT_VCD_REAL) { - if (!(pvli & 1)) { - int byte = 0; - int bit; - unsigned int j; + if(xc->signal_typs[facidx] != FST_VT_VCD_REAL) + { + if(!(pvli & 1)) + { + int byte = 0; + int bit; + unsigned int j; - for (j = 0; j < xc->signal_lens[facidx]; j++) { - unsigned char ch; - byte = j / 8; - bit = 7 - (j & 7); - ch = ((vdata[byte] >> bit) & 1) | '0'; - buf[j] = ch; + for(j=0;jsignal_lens[facidx];j++) + { + unsigned char ch; + byte = j/8; + bit = 7 - (j & 7); + ch = ((vdata[byte] >> bit) & 1) | '0'; + buf[j] = ch; + } + buf[j] = 0; + + return(buf); + } + else + { + memcpy(buf, vdata, xc->signal_lens[facidx]); + buf[xc->signal_lens[facidx]] = 0; + return(buf); + } } - buf[j] = 0; + else + { + double d; + unsigned char *clone_d = (unsigned char *)&d; + unsigned char bufd[8]; + unsigned char *srcdata; - return (buf); - } else { - memcpy(buf, vdata, xc->signal_lens[facidx]); - buf[xc->signal_lens[facidx]] = 0; - return (buf); - } - } else { - double d; - unsigned char *clone_d = (unsigned char *)&d; - unsigned char bufd[8]; - unsigned char *srcdata; + if(!(pvli & 1)) /* very rare case, but possible */ + { + int bit; + int j; - if (!(pvli & 1)) /* very rare case, but possible */ - { - int bit; - int j; + for(j=0;j<8;j++) + { + unsigned char ch; + bit = 7 - (j & 7); + ch = ((vdata[0] >> bit) & 1) | '0'; + bufd[j] = ch; + } - for (j = 0; j < 8; j++) { - unsigned char ch; - bit = 7 - (j & 7); - ch = ((vdata[0] >> bit) & 1) | '0'; - bufd[j] = ch; + srcdata = bufd; + } + else + { + srcdata = vdata; + } + + if(xc->double_endian_match) + { + memcpy(clone_d, srcdata, 8); + } + else + { + int j; + + for(j=0;j<8;j++) + { + clone_d[j] = srcdata[7-j]; + } + } + + snprintf(buf, 32, "r%.16g", d); /* this will write 19 bytes */ + return(buf); } - - srcdata = bufd; - } else { - srcdata = vdata; - } - - if (xc->double_endian_match) { - memcpy(clone_d, srcdata, 8); - } else { - int j; - - for (j = 0; j < 8; j++) { - clone_d[j] = srcdata[7 - j]; - } - } - - snprintf(buf, 32, "r%.16g", d); - return (buf); } - } else { - return (fstExtractRvatDataFromFrame(xc, facidx, buf)); - } + else + { + return(fstExtractRvatDataFromFrame(xc, facidx, buf)); + } } - } - - /* return(NULL); */ } +/* return(NULL); */ +} + + + /**********************************************************************/ #ifndef _WAVE_HAVE_JUDY @@ -6095,36 +6824,18 @@ mix() was built out of 36 single-cycle latency instructions in a to choose from. I only looked at a billion or so. -------------------------------------------------------------------- */ -#define mix(a, b, c) \ - { \ - a -= b; \ - a -= c; \ - a ^= (c >> 13); \ - b -= c; \ - b -= a; \ - b ^= (a << 8); \ - c -= a; \ - c -= b; \ - c ^= (b >> 13); \ - a -= b; \ - a -= c; \ - a ^= (c >> 12); \ - b -= c; \ - b -= a; \ - b ^= (a << 16); \ - c -= a; \ - c -= b; \ - c ^= (b >> 5); \ - a -= b; \ - a -= c; \ - a ^= (c >> 3); \ - b -= c; \ - b -= a; \ - b ^= (a << 10); \ - c -= a; \ - c -= b; \ - c ^= (b >> 15); \ - } +#define mix(a,b,c) \ +{ \ + a -= b; a -= c; a ^= (c>>13); \ + b -= c; b -= a; b ^= (a<<8); \ + c -= a; c -= b; c ^= (b>>13); \ + a -= b; a -= c; a ^= (c>>12); \ + b -= c; b -= a; b ^= (a<<16); \ + c -= a; c -= b; c ^= (b>>5); \ + a -= b; a -= c; a ^= (c>>3); \ + b -= c; b -= a; b ^= (a<<10); \ + c -= a; c -= b; c ^= (b>>15); \ +} /* -------------------------------------------------------------------- @@ -6156,55 +6867,44 @@ acceptable. Do NOT use for cryptographic purposes. static uint32_t j_hash(const uint8_t *k, uint32_t length, uint32_t initval) { - uint32_t a, b, c, len; + uint32_t a,b,c,len; - /* Set up the internal state */ - len = length; - a = b = 0x9e3779b9; /* the golden ratio; an arbitrary value */ - c = initval; /* the previous hash value */ + /* Set up the internal state */ + len = length; + a = b = 0x9e3779b9; /* the golden ratio; an arbitrary value */ + c = initval; /* the previous hash value */ - /*---------------------------------------- handle most of the key */ - while (len >= 12) { - a += (k[0] + ((uint32_t)k[1] << 8) + ((uint32_t)k[2] << 16) + ((uint32_t)k[3] << 24)); - b += (k[4] + ((uint32_t)k[5] << 8) + ((uint32_t)k[6] << 16) + ((uint32_t)k[7] << 24)); - c += (k[8] + ((uint32_t)k[9] << 8) + ((uint32_t)k[10] << 16) + ((uint32_t)k[11] << 24)); - mix(a, b, c); - k += 12; - len -= 12; - } + /*---------------------------------------- handle most of the key */ + while (len >= 12) + { + a += (k[0] +((uint32_t)k[1]<<8) +((uint32_t)k[2]<<16) +((uint32_t)k[3]<<24)); + b += (k[4] +((uint32_t)k[5]<<8) +((uint32_t)k[6]<<16) +((uint32_t)k[7]<<24)); + c += (k[8] +((uint32_t)k[9]<<8) +((uint32_t)k[10]<<16)+((uint32_t)k[11]<<24)); + mix(a,b,c); + k += 12; len -= 12; + } - /*------------------------------------- handle the last 11 bytes */ - c += length; - switch (len) /* all the case statements fall through */ - { - case 11: - c += ((uint32_t)k[10] << 24); /* fallthrough */ - case 10: - c += ((uint32_t)k[9] << 16); /* fallthrough */ - case 9: - c += ((uint32_t)k[8] << 8); /* fallthrough */ - /* the first byte of c is reserved for the length */ - case 8: - b += ((uint32_t)k[7] << 24); /* fallthrough */ - case 7: - b += ((uint32_t)k[6] << 16); /* fallthrough */ - case 6: - b += ((uint32_t)k[5] << 8); /* fallthrough */ - case 5: - b += k[4]; /* fallthrough */ - case 4: - a += ((uint32_t)k[3] << 24); /* fallthrough */ - case 3: - a += ((uint32_t)k[2] << 16); /* fallthrough */ - case 2: - a += ((uint32_t)k[1] << 8); /* fallthrough */ - case 1: - a += k[0]; - /* case 0: nothing left to add */ - } - mix(a, b, c); - /*-------------------------------------------- report the result */ - return (c); + /*------------------------------------- handle the last 11 bytes */ + c += length; + switch(len) /* all the case statements fall through */ + { + case 11: c+=((uint32_t)k[10]<<24); /* fallthrough */ + case 10: c+=((uint32_t)k[9]<<16); /* fallthrough */ + case 9 : c+=((uint32_t)k[8]<<8); /* fallthrough */ + /* the first byte of c is reserved for the length */ + case 8 : b+=((uint32_t)k[7]<<24); /* fallthrough */ + case 7 : b+=((uint32_t)k[6]<<16); /* fallthrough */ + case 6 : b+=((uint32_t)k[5]<<8); /* fallthrough */ + case 5 : b+=k[4]; /* fallthrough */ + case 4 : a+=((uint32_t)k[3]<<24); /* fallthrough */ + case 3 : a+=((uint32_t)k[2]<<16); /* fallthrough */ + case 2 : a+=((uint32_t)k[1]<<8); /* fallthrough */ + case 1 : a+=k[0]; + /* case 0: nothing left to add */ + } + mix(a,b,c); + /*-------------------------------------------- report the result */ + return(c); } /********************************************************************/ @@ -6217,71 +6917,79 @@ static uint32_t j_hash(const uint8_t *k, uint32_t length, uint32_t initval) struct collchain_t { - struct collchain_t *next; - void *payload; - uint32_t fullhash, length; - unsigned char mem[1]; +struct collchain_t *next; +void *payload; +uint32_t fullhash, length; +unsigned char mem[1]; }; + void **JenkinsIns(void *base_i, const unsigned char *mem, uint32_t length, uint32_t hashmask) { - struct collchain_t ***base = (struct collchain_t ***)base_i; - uint32_t hf, h; - struct collchain_t **ar; - struct collchain_t *chain, *pchain; +struct collchain_t ***base = (struct collchain_t ***)base_i; +uint32_t hf, h; +struct collchain_t **ar; +struct collchain_t *chain, *pchain; - if (!*base) { +if(!*base) + { *base = (struct collchain_t **)calloc(1, (hashmask + 1) * sizeof(void *)); - } - ar = *base; - - h = (hf = j_hash(mem, length, length)) & hashmask; - pchain = chain = ar[h]; - while (chain) { - if ((chain->fullhash == hf) && (chain->length == length) && !memcmp(chain->mem, mem, length)) { - if (pchain != chain) /* move hit to front */ - { - pchain->next = chain->next; - chain->next = ar[h]; - ar[h] = chain; - } - return (&(chain->payload)); } +ar = *base; + +h = (hf = j_hash(mem, length, length)) & hashmask; +pchain = chain = ar[h]; +while(chain) + { + if((chain->fullhash == hf) && (chain->length == length) && !memcmp(chain->mem, mem, length)) + { + if(pchain != chain) /* move hit to front */ + { + pchain->next = chain->next; + chain->next = ar[h]; + ar[h] = chain; + } + return(&(chain->payload)); + } pchain = chain; chain = chain->next; - } + } - chain = (struct collchain_t *)calloc(1, sizeof(struct collchain_t) + length - 1); - memcpy(chain->mem, mem, length); - chain->fullhash = hf; - chain->length = length; - chain->next = ar[h]; - ar[h] = chain; - return (&(chain->payload)); +chain = (struct collchain_t *)calloc(1, sizeof(struct collchain_t) + length - 1); +memcpy(chain->mem, mem, length); +chain->fullhash = hf; +chain->length = length; +chain->next = ar[h]; +ar[h] = chain; +return(&(chain->payload)); } + void JenkinsFree(void *base_i, uint32_t hashmask) { - struct collchain_t ***base = (struct collchain_t ***)base_i; - uint32_t h; - struct collchain_t **ar; - struct collchain_t *chain, *chain_next; +struct collchain_t ***base = (struct collchain_t ***)base_i; +uint32_t h; +struct collchain_t **ar; +struct collchain_t *chain, *chain_next; - if (base && *base) { +if(base && *base) + { ar = *base; - for (h = 0; h <= hashmask; h++) { - chain = ar[h]; - while (chain) { - chain_next = chain->next; - free(chain); - chain = chain_next; - } - } + for(h=0;h<=hashmask;h++) + { + chain = ar[h]; + while(chain) + { + chain_next = chain->next; + free(chain); + chain = chain_next; + } + } free(*base); *base = NULL; - } + } } #endif @@ -6296,260 +7004,212 @@ void JenkinsFree(void *base_i, uint32_t hashmask) int fstUtilityBinToEscConvertedLen(const unsigned char *s, int len) { - const unsigned char *src = s; - int dlen = 0; - int i; +const unsigned char *src = s; +int dlen = 0; +int i; - for (i = 0; i < len; i++) { - switch (src[i]) { - case '\a': /* fallthrough */ - case '\b': /* fallthrough */ - case '\f': /* fallthrough */ - case '\n': /* fallthrough */ - case '\r': /* fallthrough */ - case '\t': /* fallthrough */ - case '\v': /* fallthrough */ - case '\'': /* fallthrough */ - case '\"': /* fallthrough */ - case '\\': /* fallthrough */ - case '\?': - dlen += 2; - break; - default: - if ((src[i] > ' ') && (src[i] <= '~')) /* no white spaces in output */ - { - dlen++; - } else { - dlen += 4; - } - break; +for(i=0;i ' ') && (src[i] <= '~')) /* no white spaces in output */ + { + dlen++; + } + else + { + dlen += 4; + } + break; + } } - } - return (dlen); +return(dlen); } + int fstUtilityBinToEsc(unsigned char *d, const unsigned char *s, int len) { - const unsigned char *src = s; - unsigned char *dst = d; - unsigned char val; - int i; +const unsigned char *src = s; +unsigned char *dst = d; +unsigned char val; +int i; - for (i = 0; i < len; i++) { - switch (src[i]) { - case '\a': - *(dst++) = '\\'; - *(dst++) = 'a'; - break; - case '\b': - *(dst++) = '\\'; - *(dst++) = 'b'; - break; - case '\f': - *(dst++) = '\\'; - *(dst++) = 'f'; - break; - case '\n': - *(dst++) = '\\'; - *(dst++) = 'n'; - break; - case '\r': - *(dst++) = '\\'; - *(dst++) = 'r'; - break; - case '\t': - *(dst++) = '\\'; - *(dst++) = 't'; - break; - case '\v': - *(dst++) = '\\'; - *(dst++) = 'v'; - break; - case '\'': - *(dst++) = '\\'; - *(dst++) = '\''; - break; - case '\"': - *(dst++) = '\\'; - *(dst++) = '\"'; - break; - case '\\': - *(dst++) = '\\'; - *(dst++) = '\\'; - break; - case '\?': - *(dst++) = '\\'; - *(dst++) = '\?'; - break; - default: - if ((src[i] > ' ') && (src[i] <= '~')) /* no white spaces in output */ - { - *(dst++) = src[i]; - } else { - val = src[i]; - *(dst++) = '\\'; - *(dst++) = (val / 64) + '0'; - val = val & 63; - *(dst++) = (val / 8) + '0'; - val = val & 7; - *(dst++) = (val) + '0'; - } - break; +for(i=0;i ' ') && (src[i] <= '~')) /* no white spaces in output */ + { + *(dst++) = src[i]; + } + else + { + val = src[i]; + *(dst++) = '\\'; + *(dst++) = (val/64) + '0'; val = val & 63; + *(dst++) = (val/8) + '0'; val = val & 7; + *(dst++) = (val) + '0'; + } + break; + } } - } - return (dst - d); +return(dst - d); } + /* * this overwrites the original string if the destination pointer is NULL */ int fstUtilityEscToBin(unsigned char *d, unsigned char *s, int len) { - unsigned char *src = s; - unsigned char *dst = (!d) ? s : (s = d); - unsigned char val[3]; - int i; +unsigned char *src = s; +unsigned char *dst = (!d) ? s : (s = d); +unsigned char val[3]; +int i; - for (i = 0; i < len; i++) { - if (src[i] != '\\') { - *(dst++) = src[i]; - } else { - switch (src[++i]) { - case 'a': - *(dst++) = '\a'; - break; - case 'b': - *(dst++) = '\b'; - break; - case 'f': - *(dst++) = '\f'; - break; - case 'n': - *(dst++) = '\n'; - break; - case 'r': - *(dst++) = '\r'; - break; - case 't': - *(dst++) = '\t'; - break; - case 'v': - *(dst++) = '\v'; - break; - case '\'': - *(dst++) = '\''; - break; - case '\"': - *(dst++) = '\"'; - break; - case '\\': - *(dst++) = '\\'; - break; - case '\?': - *(dst++) = '\?'; - break; - - case 'x': - val[0] = toupper(src[++i]); - val[1] = toupper(src[++i]); - val[0] = ((val[0] >= 'A') && (val[0] <= 'F')) ? (val[0] - 'A' + 10) : (val[0] - '0'); - val[1] = ((val[1] >= 'A') && (val[1] <= 'F')) ? (val[1] - 'A' + 10) : (val[1] - '0'); - *(dst++) = val[0] * 16 + val[1]; - break; - - case '0': - case '1': - case '2': - case '3': - case '4': - case '5': - case '6': - case '7': - val[0] = src[i] - '0'; - val[1] = src[++i] - '0'; - val[2] = src[++i] - '0'; - *(dst++) = val[0] * 64 + val[1] * 8 + val[2]; - break; - - default: +for(i=0;i='A')&&(val[0]<='F')) ? (val[0] - 'A' + 10) : (val[0] - '0'); + val[1] = ((val[1]>='A')&&(val[1]<='F')) ? (val[1] - 'A' + 10) : (val[1] - '0'); + *(dst++) = val[0] * 16 + val[1]; + break; + + case '0': + case '1': + case '2': + case '3': + case '4': + case '5': + case '6': + case '7': val[0] = src[ i] - '0'; + val[1] = src[++i] - '0'; + val[2] = src[++i] - '0'; + *(dst++) = val[0] * 64 + val[1] * 8 + val[2]; + break; + + default: *(dst++) = src[i]; break; + } + } + } + +return(dst - s); } + struct fstETab *fstUtilityExtractEnumTableFromString(const char *s) { - struct fstETab *et = NULL; - int num_spaces = 0; - int i; - int newlen; +struct fstETab *et = NULL; +int num_spaces = 0; +int i; +int newlen; - if (s) { - const char *csp = strchr(s, ' '); - int cnt = atoi(csp + 1); +if(s) + { + const char *csp = strchr(s, ' '); + int cnt = atoi(csp+1); - for (;;) { - csp = strchr(csp + 1, ' '); - if (csp) { - num_spaces++; - } else { - break; - } - } + for(;;) + { + csp = strchr(csp+1, ' '); + if(csp) { num_spaces++; } else { break; } + } - if (num_spaces == (2 * cnt)) { - char *sp, *sp2; + if(num_spaces == (2*cnt)) + { + char *sp, *sp2; - et = (struct fstETab *)calloc(1, sizeof(struct fstETab)); - et->elem_count = cnt; - et->name = strdup(s); - et->literal_arr = (char **)calloc(cnt, sizeof(char *)); - et->val_arr = (char **)calloc(cnt, sizeof(char *)); + et = (struct fstETab*)calloc(1, sizeof(struct fstETab)); + et->elem_count = cnt; + et->name = strdup(s); + et->literal_arr = (char**)calloc(cnt, sizeof(char *)); + et->val_arr = (char**)calloc(cnt, sizeof(char *)); - sp = strchr(et->name, ' '); - *sp = 0; + sp = strchr(et->name, ' '); + *sp = 0; - sp = strchr(sp + 1, ' '); + sp = strchr(sp+1, ' '); - for (i = 0; i < cnt; i++) { - sp2 = strchr(sp + 1, ' '); - *(char *)sp2 = 0; - et->literal_arr[i] = sp + 1; - sp = sp2; + for(i=0;iliteral_arr[i] = sp+1; + sp = sp2; - newlen = fstUtilityEscToBin(NULL, (unsigned char *)et->literal_arr[i], strlen(et->literal_arr[i])); - et->literal_arr[i][newlen] = 0; - } + newlen = fstUtilityEscToBin(NULL, (unsigned char*)et->literal_arr[i], strlen(et->literal_arr[i])); + et->literal_arr[i][newlen] = 0; + } - for (i = 0; i < cnt; i++) { - sp2 = strchr(sp + 1, ' '); - if (sp2) { - *sp2 = 0; - } - et->val_arr[i] = sp + 1; - sp = sp2; + for(i=0;ival_arr[i] = sp+1; + sp = sp2; - newlen = fstUtilityEscToBin(NULL, (unsigned char *)et->val_arr[i], strlen(et->val_arr[i])); - et->val_arr[i][newlen] = 0; - } - } - } + newlen = fstUtilityEscToBin(NULL, (unsigned char*)et->val_arr[i], strlen(et->val_arr[i])); + et->val_arr[i][newlen] = 0; + } + } + } - return (et); +return(et); } + void fstUtilityFreeEnumTable(struct fstETab *etab) { - if (etab) { - free(etab->literal_arr); - free(etab->val_arr); - free(etab->name); - free(etab); - } +if(etab) + { + free(etab->literal_arr); + free(etab->val_arr); + free(etab->name); + free(etab); + } } diff --git a/libs/fst/fstapi.h b/libs/fst/fstapi.h index a5e0971a1..e2ca1783a 100644 --- a/libs/fst/fstapi.h +++ b/libs/fst/fstapi.h @@ -33,30 +33,12 @@ extern "C" { #include #include #include +#include #include #if defined(_MSC_VER) -#include "libs/zlib/zlib.h" -#include - -#include - -#define ftruncate _chsize_s -#define unlink _unlink -#define fileno _fileno -#define lseek _lseeki64 - -#ifdef _WIN64 -#define ssize_t __int64 -#define SSIZE_MAX 9223372036854775807i64 + #include "fst_win_unistd.h" #else -#define ssize_t long -#define SSIZE_MAX 2147483647L -#endif - -#include "stdint.h" -#else -#include -#include + #include #endif #include @@ -65,433 +47,417 @@ extern "C" { typedef uint32_t fstHandle; typedef uint32_t fstEnumHandle; -enum fstWriterPackType -{ - FST_WR_PT_ZLIB = 0, - FST_WR_PT_FASTLZ = 1, - FST_WR_PT_LZ4 = 2 +enum fstWriterPackType { + FST_WR_PT_ZLIB = 0, + FST_WR_PT_FASTLZ = 1, + FST_WR_PT_LZ4 = 2 }; -enum fstFileType -{ - FST_FT_MIN = 0, +enum fstFileType { + FST_FT_MIN = 0, - FST_FT_VERILOG = 0, - FST_FT_VHDL = 1, - FST_FT_VERILOG_VHDL = 2, + FST_FT_VERILOG = 0, + FST_FT_VHDL = 1, + FST_FT_VERILOG_VHDL = 2, - FST_FT_MAX = 2 + FST_FT_MAX = 2 }; -enum fstBlockType -{ - FST_BL_HDR = 0, - FST_BL_VCDATA = 1, - FST_BL_BLACKOUT = 2, - FST_BL_GEOM = 3, - FST_BL_HIER = 4, - FST_BL_VCDATA_DYN_ALIAS = 5, - FST_BL_HIER_LZ4 = 6, - FST_BL_HIER_LZ4DUO = 7, - FST_BL_VCDATA_DYN_ALIAS2 = 8, +enum fstBlockType { + FST_BL_HDR = 0, + FST_BL_VCDATA = 1, + FST_BL_BLACKOUT = 2, + FST_BL_GEOM = 3, + FST_BL_HIER = 4, + FST_BL_VCDATA_DYN_ALIAS = 5, + FST_BL_HIER_LZ4 = 6, + FST_BL_HIER_LZ4DUO = 7, + FST_BL_VCDATA_DYN_ALIAS2 = 8, - FST_BL_ZWRAPPER = 254, /* indicates that whole trace is gz wrapped */ - FST_BL_SKIP = 255 /* used while block is being written */ + FST_BL_ZWRAPPER = 254, /* indicates that whole trace is gz wrapped */ + FST_BL_SKIP = 255 /* used while block is being written */ }; -enum fstScopeType -{ - FST_ST_MIN = 0, +enum fstScopeType { + FST_ST_MIN = 0, - FST_ST_VCD_MODULE = 0, - FST_ST_VCD_TASK = 1, - FST_ST_VCD_FUNCTION = 2, - FST_ST_VCD_BEGIN = 3, - FST_ST_VCD_FORK = 4, - FST_ST_VCD_GENERATE = 5, - FST_ST_VCD_STRUCT = 6, - FST_ST_VCD_UNION = 7, - FST_ST_VCD_CLASS = 8, - FST_ST_VCD_INTERFACE = 9, - FST_ST_VCD_PACKAGE = 10, - FST_ST_VCD_PROGRAM = 11, + FST_ST_VCD_MODULE = 0, + FST_ST_VCD_TASK = 1, + FST_ST_VCD_FUNCTION = 2, + FST_ST_VCD_BEGIN = 3, + FST_ST_VCD_FORK = 4, + FST_ST_VCD_GENERATE = 5, + FST_ST_VCD_STRUCT = 6, + FST_ST_VCD_UNION = 7, + FST_ST_VCD_CLASS = 8, + FST_ST_VCD_INTERFACE = 9, + FST_ST_VCD_PACKAGE = 10, + FST_ST_VCD_PROGRAM = 11, - FST_ST_VHDL_ARCHITECTURE = 12, - FST_ST_VHDL_PROCEDURE = 13, - FST_ST_VHDL_FUNCTION = 14, - FST_ST_VHDL_RECORD = 15, - FST_ST_VHDL_PROCESS = 16, - FST_ST_VHDL_BLOCK = 17, - FST_ST_VHDL_FOR_GENERATE = 18, - FST_ST_VHDL_IF_GENERATE = 19, - FST_ST_VHDL_GENERATE = 20, - FST_ST_VHDL_PACKAGE = 21, + FST_ST_VHDL_ARCHITECTURE = 12, + FST_ST_VHDL_PROCEDURE = 13, + FST_ST_VHDL_FUNCTION = 14, + FST_ST_VHDL_RECORD = 15, + FST_ST_VHDL_PROCESS = 16, + FST_ST_VHDL_BLOCK = 17, + FST_ST_VHDL_FOR_GENERATE = 18, + FST_ST_VHDL_IF_GENERATE = 19, + FST_ST_VHDL_GENERATE = 20, + FST_ST_VHDL_PACKAGE = 21, - FST_ST_MAX = 21, + FST_ST_MAX = 21, - FST_ST_GEN_ATTRBEGIN = 252, - FST_ST_GEN_ATTREND = 253, + FST_ST_GEN_ATTRBEGIN = 252, + FST_ST_GEN_ATTREND = 253, - FST_ST_VCD_SCOPE = 254, - FST_ST_VCD_UPSCOPE = 255 + FST_ST_VCD_SCOPE = 254, + FST_ST_VCD_UPSCOPE = 255 }; -enum fstVarType -{ - FST_VT_MIN = 0, /* start of vartypes */ +enum fstVarType { + FST_VT_MIN = 0, /* start of vartypes */ - FST_VT_VCD_EVENT = 0, - FST_VT_VCD_INTEGER = 1, - FST_VT_VCD_PARAMETER = 2, - FST_VT_VCD_REAL = 3, - FST_VT_VCD_REAL_PARAMETER = 4, - FST_VT_VCD_REG = 5, - FST_VT_VCD_SUPPLY0 = 6, - FST_VT_VCD_SUPPLY1 = 7, - FST_VT_VCD_TIME = 8, - FST_VT_VCD_TRI = 9, - FST_VT_VCD_TRIAND = 10, - FST_VT_VCD_TRIOR = 11, - FST_VT_VCD_TRIREG = 12, - FST_VT_VCD_TRI0 = 13, - FST_VT_VCD_TRI1 = 14, - FST_VT_VCD_WAND = 15, - FST_VT_VCD_WIRE = 16, - FST_VT_VCD_WOR = 17, - FST_VT_VCD_PORT = 18, - FST_VT_VCD_SPARRAY = 19, /* used to define the rownum (index) port for a sparse array */ - FST_VT_VCD_REALTIME = 20, + FST_VT_VCD_EVENT = 0, + FST_VT_VCD_INTEGER = 1, + FST_VT_VCD_PARAMETER = 2, + FST_VT_VCD_REAL = 3, + FST_VT_VCD_REAL_PARAMETER = 4, + FST_VT_VCD_REG = 5, + FST_VT_VCD_SUPPLY0 = 6, + FST_VT_VCD_SUPPLY1 = 7, + FST_VT_VCD_TIME = 8, + FST_VT_VCD_TRI = 9, + FST_VT_VCD_TRIAND = 10, + FST_VT_VCD_TRIOR = 11, + FST_VT_VCD_TRIREG = 12, + FST_VT_VCD_TRI0 = 13, + FST_VT_VCD_TRI1 = 14, + FST_VT_VCD_WAND = 15, + FST_VT_VCD_WIRE = 16, + FST_VT_VCD_WOR = 17, + FST_VT_VCD_PORT = 18, + FST_VT_VCD_SPARRAY = 19, /* used to define the rownum (index) port for a sparse array */ + FST_VT_VCD_REALTIME = 20, - FST_VT_GEN_STRING = - 21, /* generic string type (max len is defined dynamically via fstWriterEmitVariableLengthValueChange) */ + FST_VT_GEN_STRING = 21, /* generic string type (max len is defined dynamically via fstWriterEmitVariableLengthValueChange) */ - FST_VT_SV_BIT = 22, - FST_VT_SV_LOGIC = 23, - FST_VT_SV_INT = 24, /* declare as size = 32 */ - FST_VT_SV_SHORTINT = 25, /* declare as size = 16 */ - FST_VT_SV_LONGINT = 26, /* declare as size = 64 */ - FST_VT_SV_BYTE = 27, /* declare as size = 8 */ - FST_VT_SV_ENUM = 28, /* declare as appropriate type range */ - FST_VT_SV_SHORTREAL = - 29, /* declare and emit same as FST_VT_VCD_REAL (needs to be emitted as double, not a float) */ + FST_VT_SV_BIT = 22, + FST_VT_SV_LOGIC = 23, + FST_VT_SV_INT = 24, /* declare as size = 32 */ + FST_VT_SV_SHORTINT = 25, /* declare as size = 16 */ + FST_VT_SV_LONGINT = 26, /* declare as size = 64 */ + FST_VT_SV_BYTE = 27, /* declare as size = 8 */ + FST_VT_SV_ENUM = 28, /* declare as appropriate type range */ + FST_VT_SV_SHORTREAL = 29, /* declare and emit same as FST_VT_VCD_REAL (needs to be emitted as double, not a float) */ - FST_VT_MAX = 29 /* end of vartypes */ + FST_VT_MAX = 29 /* end of vartypes */ }; -enum fstVarDir -{ - FST_VD_MIN = 0, +enum fstVarDir { + FST_VD_MIN = 0, - FST_VD_IMPLICIT = 0, - FST_VD_INPUT = 1, - FST_VD_OUTPUT = 2, - FST_VD_INOUT = 3, - FST_VD_BUFFER = 4, - FST_VD_LINKAGE = 5, + FST_VD_IMPLICIT = 0, + FST_VD_INPUT = 1, + FST_VD_OUTPUT = 2, + FST_VD_INOUT = 3, + FST_VD_BUFFER = 4, + FST_VD_LINKAGE = 5, - FST_VD_MAX = 5 + FST_VD_MAX = 5 }; -enum fstHierType -{ - FST_HT_MIN = 0, +enum fstHierType { + FST_HT_MIN = 0, - FST_HT_SCOPE = 0, - FST_HT_UPSCOPE = 1, - FST_HT_VAR = 2, - FST_HT_ATTRBEGIN = 3, - FST_HT_ATTREND = 4, + FST_HT_SCOPE = 0, + FST_HT_UPSCOPE = 1, + FST_HT_VAR = 2, + FST_HT_ATTRBEGIN = 3, + FST_HT_ATTREND = 4, - /* FST_HT_TREEBEGIN and FST_HT_TREEEND are not yet used by FST but are currently used when fstHier bridges other - formats */ - FST_HT_TREEBEGIN = 5, - FST_HT_TREEEND = 6, + /* FST_HT_TREEBEGIN and FST_HT_TREEEND are not yet used by FST but are currently used when fstHier bridges other formats */ + FST_HT_TREEBEGIN = 5, + FST_HT_TREEEND = 6, - FST_HT_MAX = 6 + FST_HT_MAX = 6 }; -enum fstAttrType -{ - FST_AT_MIN = 0, +enum fstAttrType { + FST_AT_MIN = 0, - FST_AT_MISC = 0, /* self-contained: does not need matching FST_HT_ATTREND */ - FST_AT_ARRAY = 1, - FST_AT_ENUM = 2, - FST_AT_PACK = 3, + FST_AT_MISC = 0, /* self-contained: does not need matching FST_HT_ATTREND */ + FST_AT_ARRAY = 1, + FST_AT_ENUM = 2, + FST_AT_PACK = 3, - FST_AT_MAX = 3 + FST_AT_MAX = 3 }; -enum fstMiscType -{ - FST_MT_MIN = 0, +enum fstMiscType { + FST_MT_MIN = 0, - FST_MT_COMMENT = 0, /* use fstWriterSetComment() to emit */ - FST_MT_ENVVAR = 1, /* use fstWriterSetEnvVar() to emit */ - FST_MT_SUPVAR = 2, /* use fstWriterCreateVar2() to emit */ - FST_MT_PATHNAME = 3, /* reserved for fstWriterSetSourceStem() string -> number management */ - FST_MT_SOURCESTEM = 4, /* use fstWriterSetSourceStem() to emit */ - FST_MT_SOURCEISTEM = 5, /* use fstWriterSetSourceInstantiationStem() to emit */ - FST_MT_VALUELIST = 6, /* use fstWriterSetValueList() to emit, followed by fstWriterCreateVar*() */ - FST_MT_ENUMTABLE = 7, /* use fstWriterCreateEnumTable() and fstWriterEmitEnumTableRef() to emit */ - FST_MT_UNKNOWN = 8, + FST_MT_COMMENT = 0, /* use fstWriterSetComment() to emit */ + FST_MT_ENVVAR = 1, /* use fstWriterSetEnvVar() to emit */ + FST_MT_SUPVAR = 2, /* use fstWriterCreateVar2() to emit */ + FST_MT_PATHNAME = 3, /* reserved for fstWriterSetSourceStem() string -> number management */ + FST_MT_SOURCESTEM = 4, /* use fstWriterSetSourceStem() to emit */ + FST_MT_SOURCEISTEM = 5, /* use fstWriterSetSourceInstantiationStem() to emit */ + FST_MT_VALUELIST = 6, /* use fstWriterSetValueList() to emit, followed by fstWriterCreateVar*() */ + FST_MT_ENUMTABLE = 7, /* use fstWriterCreateEnumTable() and fstWriterEmitEnumTableRef() to emit */ + FST_MT_UNKNOWN = 8, - FST_MT_MAX = 8 + FST_MT_MAX = 8 }; -enum fstArrayType -{ - FST_AR_MIN = 0, +enum fstArrayType { + FST_AR_MIN = 0, - FST_AR_NONE = 0, - FST_AR_UNPACKED = 1, - FST_AR_PACKED = 2, - FST_AR_SPARSE = 3, + FST_AR_NONE = 0, + FST_AR_UNPACKED = 1, + FST_AR_PACKED = 2, + FST_AR_SPARSE = 3, - FST_AR_MAX = 3 + FST_AR_MAX = 3 }; -enum fstEnumValueType -{ - FST_EV_SV_INTEGER = 0, - FST_EV_SV_BIT = 1, - FST_EV_SV_LOGIC = 2, - FST_EV_SV_INT = 3, - FST_EV_SV_SHORTINT = 4, - FST_EV_SV_LONGINT = 5, - FST_EV_SV_BYTE = 6, - FST_EV_SV_UNSIGNED_INTEGER = 7, - FST_EV_SV_UNSIGNED_BIT = 8, - FST_EV_SV_UNSIGNED_LOGIC = 9, - FST_EV_SV_UNSIGNED_INT = 10, +enum fstEnumValueType { + FST_EV_SV_INTEGER = 0, + FST_EV_SV_BIT = 1, + FST_EV_SV_LOGIC = 2, + FST_EV_SV_INT = 3, + FST_EV_SV_SHORTINT = 4, + FST_EV_SV_LONGINT = 5, + FST_EV_SV_BYTE = 6, + FST_EV_SV_UNSIGNED_INTEGER = 7, + FST_EV_SV_UNSIGNED_BIT = 8, + FST_EV_SV_UNSIGNED_LOGIC = 9, + FST_EV_SV_UNSIGNED_INT = 10, FST_EV_SV_UNSIGNED_SHORTINT = 11, - FST_EV_SV_UNSIGNED_LONGINT = 12, - FST_EV_SV_UNSIGNED_BYTE = 13, + FST_EV_SV_UNSIGNED_LONGINT = 12, + FST_EV_SV_UNSIGNED_BYTE = 13, - FST_EV_REG = 14, - FST_EV_TIME = 15, + FST_EV_REG = 14, + FST_EV_TIME = 15, - FST_EV_MAX = 15 + FST_EV_MAX = 15 }; -enum fstPackType -{ - FST_PT_NONE = 0, - FST_PT_UNPACKED = 1, - FST_PT_PACKED = 2, +enum fstPackType { + FST_PT_NONE = 0, + FST_PT_UNPACKED = 1, + FST_PT_PACKED = 2, FST_PT_TAGGED_PACKED = 3, - FST_PT_MAX = 3 + FST_PT_MAX = 3 }; -enum fstSupplementalVarType -{ - FST_SVT_MIN = 0, +enum fstSupplementalVarType { + FST_SVT_MIN = 0, - FST_SVT_NONE = 0, + FST_SVT_NONE = 0, - FST_SVT_VHDL_SIGNAL = 1, - FST_SVT_VHDL_VARIABLE = 2, - FST_SVT_VHDL_CONSTANT = 3, - FST_SVT_VHDL_FILE = 4, - FST_SVT_VHDL_MEMORY = 5, + FST_SVT_VHDL_SIGNAL = 1, + FST_SVT_VHDL_VARIABLE = 2, + FST_SVT_VHDL_CONSTANT = 3, + FST_SVT_VHDL_FILE = 4, + FST_SVT_VHDL_MEMORY = 5, - FST_SVT_MAX = 5 + FST_SVT_MAX = 5 }; -enum fstSupplementalDataType -{ - FST_SDT_MIN = 0, +enum fstSupplementalDataType { + FST_SDT_MIN = 0, - FST_SDT_NONE = 0, + FST_SDT_NONE = 0, - FST_SDT_VHDL_BOOLEAN = 1, - FST_SDT_VHDL_BIT = 2, - FST_SDT_VHDL_BIT_VECTOR = 3, - FST_SDT_VHDL_STD_ULOGIC = 4, + FST_SDT_VHDL_BOOLEAN = 1, + FST_SDT_VHDL_BIT = 2, + FST_SDT_VHDL_BIT_VECTOR = 3, + FST_SDT_VHDL_STD_ULOGIC = 4, FST_SDT_VHDL_STD_ULOGIC_VECTOR = 5, - FST_SDT_VHDL_STD_LOGIC = 6, - FST_SDT_VHDL_STD_LOGIC_VECTOR = 7, - FST_SDT_VHDL_UNSIGNED = 8, - FST_SDT_VHDL_SIGNED = 9, - FST_SDT_VHDL_INTEGER = 10, - FST_SDT_VHDL_REAL = 11, - FST_SDT_VHDL_NATURAL = 12, - FST_SDT_VHDL_POSITIVE = 13, - FST_SDT_VHDL_TIME = 14, - FST_SDT_VHDL_CHARACTER = 15, - FST_SDT_VHDL_STRING = 16, + FST_SDT_VHDL_STD_LOGIC = 6, + FST_SDT_VHDL_STD_LOGIC_VECTOR = 7, + FST_SDT_VHDL_UNSIGNED = 8, + FST_SDT_VHDL_SIGNED = 9, + FST_SDT_VHDL_INTEGER = 10, + FST_SDT_VHDL_REAL = 11, + FST_SDT_VHDL_NATURAL = 12, + FST_SDT_VHDL_POSITIVE = 13, + FST_SDT_VHDL_TIME = 14, + FST_SDT_VHDL_CHARACTER = 15, + FST_SDT_VHDL_STRING = 16, - FST_SDT_MAX = 16, + FST_SDT_MAX = 16, - FST_SDT_SVT_SHIFT_COUNT = - 10, /* FST_SVT_* is ORed in by fstWriterCreateVar2() to the left after shifting FST_SDT_SVT_SHIFT_COUNT */ - FST_SDT_ABS_MAX = ((1 << (FST_SDT_SVT_SHIFT_COUNT)) - 1) + FST_SDT_SVT_SHIFT_COUNT = 10, /* FST_SVT_* is ORed in by fstWriterCreateVar2() to the left after shifting FST_SDT_SVT_SHIFT_COUNT */ + FST_SDT_ABS_MAX = ((1<<(FST_SDT_SVT_SHIFT_COUNT))-1) }; + struct fstHier { - unsigned char htyp; +unsigned char htyp; - union - { +union { /* if htyp == FST_HT_SCOPE */ - struct fstHierScope - { - unsigned char typ; /* FST_ST_MIN ... FST_ST_MAX */ - const char *name; - const char *component; - uint32_t name_length; /* strlen(u.scope.name) */ - uint32_t component_length; /* strlen(u.scope.component) */ - } scope; + struct fstHierScope { + unsigned char typ; /* FST_ST_MIN ... FST_ST_MAX */ + const char *name; + const char *component; + uint32_t name_length; /* strlen(u.scope.name) */ + uint32_t component_length; /* strlen(u.scope.component) */ + } scope; /* if htyp == FST_HT_VAR */ - struct fstHierVar - { - unsigned char typ; /* FST_VT_MIN ... FST_VT_MAX */ - unsigned char direction; /* FST_VD_MIN ... FST_VD_MAX */ - unsigned char svt_workspace; /* zeroed out by FST reader, for client code use */ - unsigned char sdt_workspace; /* zeroed out by FST reader, for client code use */ - unsigned int sxt_workspace; /* zeroed out by FST reader, for client code use */ - const char *name; - uint32_t length; - fstHandle handle; - uint32_t name_length; /* strlen(u.var.name) */ - unsigned is_alias : 1; - } var; + struct fstHierVar { + unsigned char typ; /* FST_VT_MIN ... FST_VT_MAX */ + unsigned char direction; /* FST_VD_MIN ... FST_VD_MAX */ + unsigned char svt_workspace; /* zeroed out by FST reader, for client code use */ + unsigned char sdt_workspace; /* zeroed out by FST reader, for client code use */ + unsigned int sxt_workspace; /* zeroed out by FST reader, for client code use */ + const char *name; + uint32_t length; + fstHandle handle; + uint32_t name_length; /* strlen(u.var.name) */ + unsigned is_alias : 1; + } var; /* if htyp == FST_HT_ATTRBEGIN */ - struct fstHierAttr - { - unsigned char typ; /* FST_AT_MIN ... FST_AT_MAX */ - unsigned char subtype; /* from fstMiscType, fstArrayType, fstEnumValueType, fstPackType */ - const char *name; - uint64_t arg; /* number of array elements, struct members, or some other payload (possibly ignored) */ - uint64_t arg_from_name; /* for when name is overloaded as a variable-length integer (FST_AT_MISC + - FST_MT_SOURCESTEM) */ - uint32_t name_length; /* strlen(u.attr.name) */ - } attr; - } u; + struct fstHierAttr { + unsigned char typ; /* FST_AT_MIN ... FST_AT_MAX */ + unsigned char subtype; /* from fstMiscType, fstArrayType, fstEnumValueType, fstPackType */ + const char *name; + uint64_t arg; /* number of array elements, struct members, or some other payload (possibly ignored) */ + uint64_t arg_from_name; /* for when name is overloaded as a variable-length integer (FST_AT_MISC + FST_MT_SOURCESTEM) */ + uint32_t name_length; /* strlen(u.attr.name) */ + } attr; + } u; }; + struct fstETab { - char *name; - uint32_t elem_count; - char **literal_arr; - char **val_arr; +char *name; +uint32_t elem_count; +char **literal_arr; +char **val_arr; }; + /* * writer functions */ -void fstWriterClose(void *ctx); -void *fstWriterCreate(const char *nam, int use_compressed_hier); -fstEnumHandle fstWriterCreateEnumTable(void *ctx, const char *name, uint32_t elem_count, unsigned int min_valbits, - const char **literal_arr, const char **val_arr); -/* used for Verilog/SV */ -fstHandle fstWriterCreateVar(void *ctx, enum fstVarType vt, enum fstVarDir vd, uint32_t len, const char *nam, - fstHandle aliasHandle); -/* future expansion for VHDL and other languages. The variable type, data type, etc map onto - the current Verilog/SV one. The "type" string is optional for a more verbose or custom description */ -fstHandle fstWriterCreateVar2(void *ctx, enum fstVarType vt, enum fstVarDir vd, uint32_t len, const char *nam, - fstHandle aliasHandle, const char *type, enum fstSupplementalVarType svt, - enum fstSupplementalDataType sdt); -void fstWriterEmitDumpActive(void *ctx, int enable); -void fstWriterEmitEnumTableRef(void *ctx, fstEnumHandle handle); -void fstWriterEmitValueChange(void *ctx, fstHandle handle, const void *val); -void fstWriterEmitValueChange32(void *ctx, fstHandle handle, uint32_t bits, uint32_t val); -void fstWriterEmitValueChange64(void *ctx, fstHandle handle, uint32_t bits, uint64_t val); -void fstWriterEmitValueChangeVec32(void *ctx, fstHandle handle, uint32_t bits, const uint32_t *val); -void fstWriterEmitValueChangeVec64(void *ctx, fstHandle handle, uint32_t bits, const uint64_t *val); -void fstWriterEmitVariableLengthValueChange(void *ctx, fstHandle handle, const void *val, uint32_t len); -void fstWriterEmitTimeChange(void *ctx, uint64_t tim); -void fstWriterFlushContext(void *ctx); -int fstWriterGetDumpSizeLimitReached(void *ctx); -int fstWriterGetFseekFailed(void *ctx); -void fstWriterSetAttrBegin(void *ctx, enum fstAttrType attrtype, int subtype, const char *attrname, uint64_t arg); -void fstWriterSetAttrEnd(void *ctx); -void fstWriterSetComment(void *ctx, const char *comm); -void fstWriterSetDate(void *ctx, const char *dat); -void fstWriterSetDumpSizeLimit(void *ctx, uint64_t numbytes); -void fstWriterSetEnvVar(void *ctx, const char *envvar); -void fstWriterSetFileType(void *ctx, enum fstFileType filetype); -void fstWriterSetPackType(void *ctx, enum fstWriterPackType typ); -void fstWriterSetParallelMode(void *ctx, int enable); -void fstWriterSetRepackOnClose(void *ctx, int enable); /* type = 0 (none), 1 (libz) */ -void fstWriterSetScope(void *ctx, enum fstScopeType scopetype, const char *scopename, const char *scopecomp); -void fstWriterSetSourceInstantiationStem(void *ctx, const char *path, unsigned int line, unsigned int use_realpath); -void fstWriterSetSourceStem(void *ctx, const char *path, unsigned int line, unsigned int use_realpath); -void fstWriterSetTimescale(void *ctx, int ts); -void fstWriterSetTimescaleFromString(void *ctx, const char *s); -void fstWriterSetTimezero(void *ctx, int64_t tim); -void fstWriterSetUpscope(void *ctx); -void fstWriterSetValueList(void *ctx, const char *vl); -void fstWriterSetVersion(void *ctx, const char *vers); +void fstWriterClose(void *ctx); +void * fstWriterCreate(const char *nam, int use_compressed_hier); +fstEnumHandle fstWriterCreateEnumTable(void *ctx, const char *name, uint32_t elem_count, unsigned int min_valbits, const char **literal_arr, const char **val_arr); + /* used for Verilog/SV */ +fstHandle fstWriterCreateVar(void *ctx, enum fstVarType vt, enum fstVarDir vd, + uint32_t len, const char *nam, fstHandle aliasHandle); + /* future expansion for VHDL and other languages. The variable type, data type, etc map onto + the current Verilog/SV one. The "type" string is optional for a more verbose or custom description */ +fstHandle fstWriterCreateVar2(void *ctx, enum fstVarType vt, enum fstVarDir vd, + uint32_t len, const char *nam, fstHandle aliasHandle, + const char *type, enum fstSupplementalVarType svt, enum fstSupplementalDataType sdt); +void fstWriterEmitDumpActive(void *ctx, int enable); +void fstWriterEmitEnumTableRef(void *ctx, fstEnumHandle handle); +void fstWriterEmitValueChange(void *ctx, fstHandle handle, const void *val); +void fstWriterEmitValueChange32(void *ctx, fstHandle handle, + uint32_t bits, uint32_t val); +void fstWriterEmitValueChange64(void *ctx, fstHandle handle, + uint32_t bits, uint64_t val); +void fstWriterEmitValueChangeVec32(void *ctx, fstHandle handle, + uint32_t bits, const uint32_t *val); +void fstWriterEmitValueChangeVec64(void *ctx, fstHandle handle, + uint32_t bits, const uint64_t *val); +void fstWriterEmitVariableLengthValueChange(void *ctx, fstHandle handle, const void *val, uint32_t len); +void fstWriterEmitTimeChange(void *ctx, uint64_t tim); +void fstWriterFlushContext(void *ctx); +int fstWriterGetDumpSizeLimitReached(void *ctx); +int fstWriterGetFseekFailed(void *ctx); +void fstWriterSetAttrBegin(void *ctx, enum fstAttrType attrtype, int subtype, + const char *attrname, uint64_t arg); +void fstWriterSetAttrEnd(void *ctx); +void fstWriterSetComment(void *ctx, const char *comm); +void fstWriterSetDate(void *ctx, const char *dat); +void fstWriterSetDumpSizeLimit(void *ctx, uint64_t numbytes); +void fstWriterSetEnvVar(void *ctx, const char *envvar); +void fstWriterSetFileType(void *ctx, enum fstFileType filetype); +void fstWriterSetPackType(void *ctx, enum fstWriterPackType typ); +void fstWriterSetParallelMode(void *ctx, int enable); +void fstWriterSetRepackOnClose(void *ctx, int enable); /* type = 0 (none), 1 (libz) */ +void fstWriterSetScope(void *ctx, enum fstScopeType scopetype, + const char *scopename, const char *scopecomp); +void fstWriterSetSourceInstantiationStem(void *ctx, const char *path, unsigned int line, unsigned int use_realpath); +void fstWriterSetSourceStem(void *ctx, const char *path, unsigned int line, unsigned int use_realpath); +void fstWriterSetTimescale(void *ctx, int ts); +void fstWriterSetTimescaleFromString(void *ctx, const char *s); +void fstWriterSetTimezero(void *ctx, int64_t tim); +void fstWriterSetUpscope(void *ctx); +void fstWriterSetValueList(void *ctx, const char *vl); +void fstWriterSetVersion(void *ctx, const char *vers); + /* * reader functions */ -void fstReaderClose(void *ctx); -void fstReaderClrFacProcessMask(void *ctx, fstHandle facidx); -void fstReaderClrFacProcessMaskAll(void *ctx); -uint64_t fstReaderGetAliasCount(void *ctx); -const char *fstReaderGetCurrentFlatScope(void *ctx); -void *fstReaderGetCurrentScopeUserInfo(void *ctx); -int fstReaderGetCurrentScopeLen(void *ctx); -const char *fstReaderGetDateString(void *ctx); -int fstReaderGetDoubleEndianMatchState(void *ctx); -uint64_t fstReaderGetDumpActivityChangeTime(void *ctx, uint32_t idx); -unsigned char fstReaderGetDumpActivityChangeValue(void *ctx, uint32_t idx); -uint64_t fstReaderGetEndTime(void *ctx); -int fstReaderGetFacProcessMask(void *ctx, fstHandle facidx); -int fstReaderGetFileType(void *ctx); -int fstReaderGetFseekFailed(void *ctx); -fstHandle fstReaderGetMaxHandle(void *ctx); -uint64_t fstReaderGetMemoryUsedByWriter(void *ctx); -uint32_t fstReaderGetNumberDumpActivityChanges(void *ctx); -uint64_t fstReaderGetScopeCount(void *ctx); -uint64_t fstReaderGetStartTime(void *ctx); -signed char fstReaderGetTimescale(void *ctx); -int64_t fstReaderGetTimezero(void *ctx); -uint64_t fstReaderGetValueChangeSectionCount(void *ctx); -char *fstReaderGetValueFromHandleAtTime(void *ctx, uint64_t tim, fstHandle facidx, char *buf); -uint64_t fstReaderGetVarCount(void *ctx); -const char *fstReaderGetVersionString(void *ctx); +void fstReaderClose(void *ctx); +void fstReaderClrFacProcessMask(void *ctx, fstHandle facidx); +void fstReaderClrFacProcessMaskAll(void *ctx); +uint64_t fstReaderGetAliasCount(void *ctx); +const char * fstReaderGetCurrentFlatScope(void *ctx); +void * fstReaderGetCurrentScopeUserInfo(void *ctx); +int fstReaderGetCurrentScopeLen(void *ctx); +const char * fstReaderGetDateString(void *ctx); +int fstReaderGetDoubleEndianMatchState(void *ctx); +uint64_t fstReaderGetDumpActivityChangeTime(void *ctx, uint32_t idx); +unsigned char fstReaderGetDumpActivityChangeValue(void *ctx, uint32_t idx); +uint64_t fstReaderGetEndTime(void *ctx); +int fstReaderGetFacProcessMask(void *ctx, fstHandle facidx); +int fstReaderGetFileType(void *ctx); +int fstReaderGetFseekFailed(void *ctx); +fstHandle fstReaderGetMaxHandle(void *ctx); +uint64_t fstReaderGetMemoryUsedByWriter(void *ctx); +uint32_t fstReaderGetNumberDumpActivityChanges(void *ctx); +uint64_t fstReaderGetScopeCount(void *ctx); +uint64_t fstReaderGetStartTime(void *ctx); +signed char fstReaderGetTimescale(void *ctx); +int64_t fstReaderGetTimezero(void *ctx); +uint64_t fstReaderGetValueChangeSectionCount(void *ctx); +char * fstReaderGetValueFromHandleAtTime(void *ctx, uint64_t tim, fstHandle facidx, char *buf); +uint64_t fstReaderGetVarCount(void *ctx); +const char * fstReaderGetVersionString(void *ctx); struct fstHier *fstReaderIterateHier(void *ctx); -int fstReaderIterateHierRewind(void *ctx); -int fstReaderIterBlocks(void *ctx, - void (*value_change_callback)(void *user_callback_data_pointer, uint64_t time, fstHandle facidx, - const unsigned char *value), +int fstReaderIterateHierRewind(void *ctx); +int fstReaderIterBlocks(void *ctx, + void (*value_change_callback)(void *user_callback_data_pointer, uint64_t time, fstHandle facidx, const unsigned char *value), void *user_callback_data_pointer, FILE *vcdhandle); -int fstReaderIterBlocks2(void *ctx, - void (*value_change_callback)(void *user_callback_data_pointer, uint64_t time, - fstHandle facidx, const unsigned char *value), - void (*value_change_callback_varlen)(void *user_callback_data_pointer, uint64_t time, - fstHandle facidx, const unsigned char *value, - uint32_t len), - void *user_callback_data_pointer, FILE *vcdhandle); -void fstReaderIterBlocksSetNativeDoublesOnCallback(void *ctx, int enable); -void *fstReaderOpen(const char *nam); -void *fstReaderOpenForUtilitiesOnly(void); -const char *fstReaderPopScope(void *ctx); -int fstReaderProcessHier(void *ctx, FILE *vcdhandle); -const char *fstReaderPushScope(void *ctx, const char *nam, void *user_info); -void fstReaderResetScope(void *ctx); -void fstReaderSetFacProcessMask(void *ctx, fstHandle facidx); -void fstReaderSetFacProcessMaskAll(void *ctx); -void fstReaderSetLimitTimeRange(void *ctx, uint64_t start_time, uint64_t end_time); -void fstReaderSetUnlimitedTimeRange(void *ctx); -void fstReaderSetVcdExtensions(void *ctx, int enable); +int fstReaderIterBlocks2(void *ctx, + void (*value_change_callback)(void *user_callback_data_pointer, uint64_t time, fstHandle facidx, const unsigned char *value), + void (*value_change_callback_varlen)(void *user_callback_data_pointer, uint64_t time, fstHandle facidx, const unsigned char *value, uint32_t len), + void *user_callback_data_pointer, FILE *vcdhandle); +void fstReaderIterBlocksSetNativeDoublesOnCallback(void *ctx, int enable); +void * fstReaderOpen(const char *nam); +void * fstReaderOpenForUtilitiesOnly(void); +const char * fstReaderPopScope(void *ctx); +int fstReaderProcessHier(void *ctx, FILE *vcdhandle); +const char * fstReaderPushScope(void *ctx, const char *nam, void *user_info); +void fstReaderResetScope(void *ctx); +void fstReaderSetFacProcessMask(void *ctx, fstHandle facidx); +void fstReaderSetFacProcessMaskAll(void *ctx); +void fstReaderSetLimitTimeRange(void *ctx, uint64_t start_time, uint64_t end_time); +void fstReaderSetUnlimitedTimeRange(void *ctx); +void fstReaderSetVcdExtensions(void *ctx, int enable); + /* * utility functions */ -int fstUtilityBinToEscConvertedLen(const unsigned char *s, int len); /* used for mallocs for fstUtilityBinToEsc() */ -int fstUtilityBinToEsc(unsigned char *d, const unsigned char *s, int len); -int fstUtilityEscToBin(unsigned char *d, unsigned char *s, int len); +int fstUtilityBinToEscConvertedLen(const unsigned char *s, int len); /* used for mallocs for fstUtilityBinToEsc() */ +int fstUtilityBinToEsc(unsigned char *d, const unsigned char *s, int len); +int fstUtilityEscToBin(unsigned char *d, unsigned char *s, int len); struct fstETab *fstUtilityExtractEnumTableFromString(const char *s); -void fstUtilityFreeEnumTable(struct fstETab *etab); /* must use to free fstETab properly */ +void fstUtilityFreeEnumTable(struct fstETab *etab); /* must use to free fstETab properly */ + #ifdef __cplusplus } diff --git a/libs/fst/lz4.cc b/libs/fst/lz4.cc index 7e94f2492..0a727596b 100644 --- a/libs/fst/lz4.cc +++ b/libs/fst/lz4.cc @@ -1,6 +1,6 @@ /* LZ4 - Fast LZ compression algorithm - Copyright (C) 2011-2015, Yann Collet. + Copyright (C) 2011-2023, Yann Collet. BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php) @@ -27,1396 +27,2559 @@ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - SPDX-License-Identifier: BSD-2-Clause - You can contact the author at : - - LZ4 source repository : https://github.com/Cyan4973/lz4 - - LZ4 public forum : https://groups.google.com/forum/#!forum/lz4c + - LZ4 homepage : http://www.lz4.org + - LZ4 source repository : https://github.com/lz4/lz4 */ -/************************************** - * Tuning parameters - **************************************/ +/*-************************************ +* Tuning parameters +**************************************/ /* - * HEAPMODE : - * Select how default compression functions will allocate memory for their hash table, + * LZ4_HEAPMODE : + * Select how stateless compression functions like `LZ4_compress_default()` + * allocate memory for their hash table, * in memory stack (0:default, fastest), or in memory heap (1:requires malloc()). */ -#define HEAPMODE 0 +#ifndef LZ4_HEAPMODE +# define LZ4_HEAPMODE 0 +#endif /* - * ACCELERATION_DEFAULT : + * LZ4_ACCELERATION_DEFAULT : * Select "acceleration" for LZ4_compress_fast() when parameter value <= 0 */ -#define ACCELERATION_DEFAULT 1 +#define LZ4_ACCELERATION_DEFAULT 1 +/* + * LZ4_ACCELERATION_MAX : + * Any "acceleration" value higher than this threshold + * get treated as LZ4_ACCELERATION_MAX instead (fix #876) + */ +#define LZ4_ACCELERATION_MAX 65537 + + +/*-************************************ +* CPU Feature Detection +**************************************/ +/* LZ4_FORCE_MEMORY_ACCESS + * By default, access to unaligned memory is controlled by `memcpy()`, which is safe and portable. + * Unfortunately, on some target/compiler combinations, the generated assembly is sub-optimal. + * The below switch allow to select different access method for improved performance. + * Method 0 (default) : use `memcpy()`. Safe and portable. + * Method 1 : `__packed` statement. It depends on compiler extension (ie, not portable). + * This method is safe if your compiler supports it, and *generally* as fast or faster than `memcpy`. + * Method 2 : direct access. This method is portable but violate C standard. + * It can generate buggy code on targets which assembly generation depends on alignment. + * But in some circumstances, it's the only known way to get the most performance (ie GCC + ARMv6) + * See https://fastcompression.blogspot.fr/2015/08/accessing-unaligned-memory.html for details. + * Prefer these methods in priority order (0 > 1 > 2) + */ +#ifndef LZ4_FORCE_MEMORY_ACCESS /* can be defined externally */ +# if defined(__GNUC__) && \ + ( defined(__ARM_ARCH_6__) || defined(__ARM_ARCH_6J__) || defined(__ARM_ARCH_6K__) \ + || defined(__ARM_ARCH_6Z__) || defined(__ARM_ARCH_6ZK__) || defined(__ARM_ARCH_6T2__) ) +# define LZ4_FORCE_MEMORY_ACCESS 2 +# elif (defined(__INTEL_COMPILER) && !defined(_WIN32)) || defined(__GNUC__) || defined(_MSC_VER) +# define LZ4_FORCE_MEMORY_ACCESS 1 +# endif +#endif -/************************************** - * CPU Feature Detection - **************************************/ /* * LZ4_FORCE_SW_BITCOUNT * Define this parameter if your target system or compiler does not support hardware bit count */ -#if defined(_MSC_VER) && defined(_WIN32_WCE) /* Visual Studio for Windows CE does not support Hardware bit count */ -#define LZ4_FORCE_SW_BITCOUNT +#if defined(_MSC_VER) && defined(_WIN32_WCE) /* Visual Studio for WinCE doesn't support Hardware bit count */ +# undef LZ4_FORCE_SW_BITCOUNT /* avoid double def */ +# define LZ4_FORCE_SW_BITCOUNT #endif -/************************************** - * Includes - **************************************/ + + +/*-************************************ +* Dependency +**************************************/ +/* + * LZ4_SRC_INCLUDED: + * Amalgamation flag, whether lz4.c is included + */ +#ifndef LZ4_SRC_INCLUDED +# define LZ4_SRC_INCLUDED 1 +#endif + +#ifndef LZ4_DISABLE_DEPRECATE_WARNINGS +# define LZ4_DISABLE_DEPRECATE_WARNINGS /* due to LZ4_decompress_safe_withPrefix64k */ +#endif + +#ifndef LZ4_STATIC_LINKING_ONLY +# define LZ4_STATIC_LINKING_ONLY +#endif #include "lz4.h" +/* see also "memory routines" below */ -/************************************** - * Compiler Options - **************************************/ -#ifdef _MSC_VER /* Visual Studio */ -#define FORCE_INLINE static __forceinline -#include -#pragma warning(disable : 4127) /* disable: C4127: conditional expression is constant */ -#pragma warning(disable : 4293) /* disable: C4293: too large shift (32-bits) */ -#else -#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 */ -#if defined(__GNUC__) || defined(__clang__) -#define FORCE_INLINE static inline __attribute__((always_inline)) -#else -#define FORCE_INLINE static inline -#endif -#else -#define FORCE_INLINE static -#endif /* __STDC_VERSION__ */ -#endif /* _MSC_VER */ -/* LZ4_GCC_VERSION is defined into lz4.h */ -#if (LZ4_GCC_VERSION >= 302) || (__INTEL_COMPILER >= 800) || defined(__clang__) -#define expect(expr, value) (__builtin_expect((expr), (value))) +/*-************************************ +* Compiler Options +**************************************/ +#if defined(_MSC_VER) && (_MSC_VER >= 1400) /* Visual Studio 2005+ */ +# include /* only present in VS2005+ */ +# pragma warning(disable : 4127) /* disable: C4127: conditional expression is constant */ +# pragma warning(disable : 6237) /* disable: C6237: conditional expression is always 0 */ +#endif /* _MSC_VER */ + +#ifndef LZ4_FORCE_INLINE +# ifdef _MSC_VER /* Visual Studio */ +# define LZ4_FORCE_INLINE static __forceinline +# else +# if defined (__cplusplus) || defined (__STDC_VERSION__) && __STDC_VERSION__ >= 199901L /* C99 */ +# ifdef __GNUC__ +# define LZ4_FORCE_INLINE static inline __attribute__((always_inline)) +# else +# define LZ4_FORCE_INLINE static inline +# endif +# else +# define LZ4_FORCE_INLINE static +# endif /* __STDC_VERSION__ */ +# endif /* _MSC_VER */ +#endif /* LZ4_FORCE_INLINE */ + +/* LZ4_FORCE_O2 and LZ4_FORCE_INLINE + * gcc on ppc64le generates an unrolled SIMDized loop for LZ4_wildCopy8, + * together with a simple 8-byte copy loop as a fall-back path. + * However, this optimization hurts the decompression speed by >30%, + * because the execution does not go to the optimized loop + * for typical compressible data, and all of the preamble checks + * before going to the fall-back path become useless overhead. + * This optimization happens only with the -O3 flag, and -O2 generates + * a simple 8-byte copy loop. + * With gcc on ppc64le, all of the LZ4_decompress_* and LZ4_wildCopy8 + * functions are annotated with __attribute__((optimize("O2"))), + * and also LZ4_wildCopy8 is forcibly inlined, so that the O2 attribute + * of LZ4_wildCopy8 does not affect the compression speed. + */ +#if defined(__PPC64__) && defined(__LITTLE_ENDIAN__) && defined(__GNUC__) && !defined(__clang__) +# define LZ4_FORCE_O2 __attribute__((optimize("O2"))) +# undef LZ4_FORCE_INLINE +# define LZ4_FORCE_INLINE static __inline __attribute__((optimize("O2"),always_inline)) #else -#define expect(expr, value) (expr) +# define LZ4_FORCE_O2 #endif -#define likely(expr) expect((expr) != 0, 1) -#define unlikely(expr) expect((expr) != 0, 0) - -/************************************** - * Memory routines - **************************************/ -#include /* malloc, calloc, free */ -#define ALLOCATOR(n, s) calloc(n, s) -#define FREEMEM free -#include /* memset, memcpy */ -#define MEM_INIT memset - -/************************************** - * Basic Types - **************************************/ -#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 */ -#include -typedef uint8_t BYTE; -typedef uint16_t U16; -typedef uint32_t U32; -typedef int32_t S32; -typedef uint64_t U64; +#if (defined(__GNUC__) && (__GNUC__ >= 3)) || (defined(__INTEL_COMPILER) && (__INTEL_COMPILER >= 800)) || defined(__clang__) +# define expect(expr,value) (__builtin_expect ((expr),(value)) ) #else -typedef unsigned char BYTE; -typedef unsigned short U16; -typedef unsigned int U32; -typedef signed int S32; -typedef unsigned long long U64; +# define expect(expr,value) (expr) #endif -/************************************** - * Reading and writing into memory - **************************************/ -#define STEPSIZE sizeof(size_t) +#ifndef likely +#define likely(expr) expect((expr) != 0, 1) +#endif +#ifndef unlikely +#define unlikely(expr) expect((expr) != 0, 0) +#endif -static unsigned LZ4_64bits(void) { return sizeof(void *) == 8; } +/* Should the alignment test prove unreliable, for some reason, + * it can be disabled by setting LZ4_ALIGN_TEST to 0 */ +#ifndef LZ4_ALIGN_TEST /* can be externally provided */ +# define LZ4_ALIGN_TEST 1 +#endif + + +/*-************************************ +* Memory routines +**************************************/ + +/*! LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION : + * Disable relatively high-level LZ4/HC functions that use dynamic memory + * allocation functions (malloc(), calloc(), free()). + * + * Note that this is a compile-time switch. And since it disables + * public/stable LZ4 v1 API functions, we don't recommend using this + * symbol to generate a library for distribution. + * + * The following public functions are removed when this symbol is defined. + * - lz4 : LZ4_createStream, LZ4_freeStream, + * LZ4_createStreamDecode, LZ4_freeStreamDecode, LZ4_create (deprecated) + * - lz4hc : LZ4_createStreamHC, LZ4_freeStreamHC, + * LZ4_createHC (deprecated), LZ4_freeHC (deprecated) + * - lz4frame, lz4file : All LZ4F_* functions + */ +#if defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) +# define ALLOC(s) lz4_error_memory_allocation_is_disabled +# define ALLOC_AND_ZERO(s) lz4_error_memory_allocation_is_disabled +# define FREEMEM(p) lz4_error_memory_allocation_is_disabled +#elif defined(LZ4_USER_MEMORY_FUNCTIONS) +/* memory management functions can be customized by user project. + * Below functions must exist somewhere in the Project + * and be available at link time */ +void* LZ4_malloc(size_t s); +void* LZ4_calloc(size_t n, size_t s); +void LZ4_free(void* p); +# define ALLOC(s) LZ4_malloc(s) +# define ALLOC_AND_ZERO(s) LZ4_calloc(1,s) +# define FREEMEM(p) LZ4_free(p) +#else +# include /* malloc, calloc, free */ +# define ALLOC(s) malloc(s) +# define ALLOC_AND_ZERO(s) calloc(1,s) +# define FREEMEM(p) free(p) +#endif + +#if ! LZ4_FREESTANDING +# include /* memset, memcpy */ +#endif +#if !defined(LZ4_memset) +# define LZ4_memset(p,v,s) memset((p),(v),(s)) +#endif +#define MEM_INIT(p,v,s) LZ4_memset((p),(v),(s)) + + +/*-************************************ +* Common Constants +**************************************/ +#define MINMATCH 4 + +#define WILDCOPYLENGTH 8 +#define LASTLITERALS 5 /* see ../doc/lz4_Block_format.md#parsing-restrictions */ +#define MFLIMIT 12 /* see ../doc/lz4_Block_format.md#parsing-restrictions */ +#define MATCH_SAFEGUARD_DISTANCE ((2*WILDCOPYLENGTH) - MINMATCH) /* ensure it's possible to write 2 x wildcopyLength without overflowing output buffer */ +#define FASTLOOP_SAFE_DISTANCE 64 +static const int LZ4_minLength = (MFLIMIT+1); + +#define KB *(1 <<10) +#define MB *(1 <<20) +#define GB *(1U<<30) + +#define LZ4_DISTANCE_ABSOLUTE_MAX 65535 +#if (LZ4_DISTANCE_MAX > LZ4_DISTANCE_ABSOLUTE_MAX) /* max supported by LZ4 format */ +# error "LZ4_DISTANCE_MAX is too big : must be <= 65535" +#endif + +#define ML_BITS 4 +#define ML_MASK ((1U<=1) +# include +#else +# ifndef assert +# define assert(condition) ((void)0) +# endif +#endif + +#define LZ4_STATIC_ASSERT(c) { enum { LZ4_static_assert = 1/(int)(!!(c)) }; } /* use after variable declarations */ + +#if defined(LZ4_DEBUG) && (LZ4_DEBUG>=2) +# include + static int g_debuglog_enable = 1; +# define DEBUGLOG(l, ...) { \ + if ((g_debuglog_enable) && (l<=LZ4_DEBUG)) { \ + fprintf(stderr, __FILE__ " %i: ", __LINE__); \ + fprintf(stderr, __VA_ARGS__); \ + fprintf(stderr, " \n"); \ + } } +#else +# define DEBUGLOG(l, ...) {} /* disabled */ +#endif + +static int LZ4_isAligned(const void* ptr, size_t alignment) +{ + return ((size_t)ptr & (alignment -1)) == 0; +} + + +/*-************************************ +* Types +**************************************/ +#include +#if defined(__cplusplus) || (defined (__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 */) +# include + typedef uint8_t BYTE; + typedef uint16_t U16; + typedef uint32_t U32; + typedef int32_t S32; + typedef uint64_t U64; + typedef uintptr_t uptrval; +#else +# if UINT_MAX != 4294967295UL +# error "LZ4 code (when not C++ or C99) assumes that sizeof(int) == 4" +# endif + typedef unsigned char BYTE; + typedef unsigned short U16; + typedef unsigned int U32; + typedef signed int S32; + typedef unsigned long long U64; + typedef size_t uptrval; /* generally true, except OpenVMS-64 */ +#endif + +#if defined(__x86_64__) + typedef U64 reg_t; /* 64-bits in x32 mode */ +#else + typedef size_t reg_t; /* 32-bits in x32 mode */ +#endif + +typedef enum { + notLimited = 0, + limitedOutput = 1, + fillOutput = 2 +} limitedOutput_directive; + + +/*-************************************ +* Reading and writing into memory +**************************************/ + +/** + * LZ4 relies on memcpy with a constant size being inlined. In freestanding + * environments, the compiler can't assume the implementation of memcpy() is + * standard compliant, so it can't apply its specialized memcpy() inlining + * logic. When possible, use __builtin_memcpy() to tell the compiler to analyze + * memcpy() as if it were standard compliant, so it can inline it in freestanding + * environments. This is needed when decompressing the Linux Kernel, for example. + */ +#if !defined(LZ4_memcpy) +# if defined(__GNUC__) && (__GNUC__ >= 4) +# define LZ4_memcpy(dst, src, size) __builtin_memcpy(dst, src, size) +# else +# define LZ4_memcpy(dst, src, size) memcpy(dst, src, size) +# endif +#endif + +#if !defined(LZ4_memmove) +# if defined(__GNUC__) && (__GNUC__ >= 4) +# define LZ4_memmove __builtin_memmove +# else +# define LZ4_memmove memmove +# endif +#endif static unsigned LZ4_isLittleEndian(void) { - const union - { - U32 i; - BYTE c[4]; - } one = {1}; /* don't use static : performance detrimental */ + const union { U32 u; BYTE c[4]; } one = { 1 }; /* don't use static : performance detrimental */ return one.c[0]; } -static U16 LZ4_read16(const void *memPtr) +#if defined(__GNUC__) || defined(__INTEL_COMPILER) +#define LZ4_PACK( __Declaration__ ) __Declaration__ __attribute__((__packed__)) +#elif defined(_MSC_VER) +#define LZ4_PACK( __Declaration__ ) __pragma( pack(push, 1) ) __Declaration__ __pragma( pack(pop)) +#endif + +#if defined(LZ4_FORCE_MEMORY_ACCESS) && (LZ4_FORCE_MEMORY_ACCESS==2) +/* lie to the compiler about data alignment; use with caution */ + +static U16 LZ4_read16(const void* memPtr) { return *(const U16*) memPtr; } +static U32 LZ4_read32(const void* memPtr) { return *(const U32*) memPtr; } +static reg_t LZ4_read_ARCH(const void* memPtr) { return *(const reg_t*) memPtr; } + +static void LZ4_write16(void* memPtr, U16 value) { *(U16*)memPtr = value; } +static void LZ4_write32(void* memPtr, U32 value) { *(U32*)memPtr = value; } + +#elif defined(LZ4_FORCE_MEMORY_ACCESS) && (LZ4_FORCE_MEMORY_ACCESS==1) + +/* __pack instructions are safer, but compiler specific, hence potentially problematic for some compilers */ +/* currently only defined for gcc and icc */ +LZ4_PACK(typedef struct { U16 u16; }) LZ4_unalign16; +LZ4_PACK(typedef struct { U32 u32; }) LZ4_unalign32; +LZ4_PACK(typedef struct { reg_t uArch; }) LZ4_unalignST; + +static U16 LZ4_read16(const void* ptr) { return ((const LZ4_unalign16*)ptr)->u16; } +static U32 LZ4_read32(const void* ptr) { return ((const LZ4_unalign32*)ptr)->u32; } +static reg_t LZ4_read_ARCH(const void* ptr) { return ((const LZ4_unalignST*)ptr)->uArch; } + +static void LZ4_write16(void* memPtr, U16 value) { ((LZ4_unalign16*)memPtr)->u16 = value; } +static void LZ4_write32(void* memPtr, U32 value) { ((LZ4_unalign32*)memPtr)->u32 = value; } + +#else /* safe and portable access using memcpy() */ + +static U16 LZ4_read16(const void* memPtr) { - U16 val16; - memcpy(&val16, memPtr, 2); - return val16; + U16 val; LZ4_memcpy(&val, memPtr, sizeof(val)); return val; } -static U16 LZ4_readLE16(const void *memPtr) +static U32 LZ4_read32(const void* memPtr) +{ + U32 val; LZ4_memcpy(&val, memPtr, sizeof(val)); return val; +} + +static reg_t LZ4_read_ARCH(const void* memPtr) +{ + reg_t val; LZ4_memcpy(&val, memPtr, sizeof(val)); return val; +} + +static void LZ4_write16(void* memPtr, U16 value) +{ + LZ4_memcpy(memPtr, &value, sizeof(value)); +} + +static void LZ4_write32(void* memPtr, U32 value) +{ + LZ4_memcpy(memPtr, &value, sizeof(value)); +} + +#endif /* LZ4_FORCE_MEMORY_ACCESS */ + + +static U16 LZ4_readLE16(const void* memPtr) { if (LZ4_isLittleEndian()) { return LZ4_read16(memPtr); } else { - const BYTE *p = (const BYTE *)memPtr; - return (U16)((U16)p[0] + (p[1] << 8)); + const BYTE* p = (const BYTE*)memPtr; + return (U16)((U16)p[0] + (p[1]<<8)); } } -static void LZ4_writeLE16(void *memPtr, U16 value) +#ifdef LZ4_STATIC_LINKING_ONLY_ENDIANNESS_INDEPENDENT_OUTPUT +static U32 LZ4_readLE32(const void* memPtr) { if (LZ4_isLittleEndian()) { - memcpy(memPtr, &value, 2); + return LZ4_read32(memPtr); } else { - BYTE *p = (BYTE *)memPtr; - p[0] = (BYTE)value; - p[1] = (BYTE)(value >> 8); + const BYTE* p = (const BYTE*)memPtr; + return (U32)p[0] + (p[1]<<8) + (p[2]<<16) + (p[3]<<24); + } +} +#endif + +static void LZ4_writeLE16(void* memPtr, U16 value) +{ + if (LZ4_isLittleEndian()) { + LZ4_write16(memPtr, value); + } else { + BYTE* p = (BYTE*)memPtr; + p[0] = (BYTE) value; + p[1] = (BYTE)(value>>8); } } -static U32 LZ4_read32(const void *memPtr) +/* customized variant of memcpy, which can overwrite up to 8 bytes beyond dstEnd */ +LZ4_FORCE_INLINE +void LZ4_wildCopy8(void* dstPtr, const void* srcPtr, void* dstEnd) { - U32 val32; - memcpy(&val32, memPtr, 4); - return val32; + BYTE* d = (BYTE*)dstPtr; + const BYTE* s = (const BYTE*)srcPtr; + BYTE* const e = (BYTE*)dstEnd; + + do { LZ4_memcpy(d,s,8); d+=8; s+=8; } while (d= 16. */ +LZ4_FORCE_INLINE void +LZ4_wildCopy32(void* dstPtr, const void* srcPtr, void* dstEnd) +{ + BYTE* d = (BYTE*)dstPtr; + const BYTE* s = (const BYTE*)srcPtr; + BYTE* const e = (BYTE*)dstEnd; + + do { LZ4_memcpy(d,s,16); LZ4_memcpy(d+16,s+16,16); d+=32; s+=32; } while (d= dstPtr + MINMATCH + * - there is at least 8 bytes available to write after dstEnd */ +LZ4_FORCE_INLINE void +LZ4_memcpy_using_offset(BYTE* dstPtr, const BYTE* srcPtr, BYTE* dstEnd, const size_t offset) +{ + BYTE v[8]; + + assert(dstEnd >= dstPtr + MINMATCH); + + switch(offset) { + case 1: + MEM_INIT(v, *srcPtr, 8); + break; + case 2: + LZ4_memcpy(v, srcPtr, 2); + LZ4_memcpy(&v[2], srcPtr, 2); +#if defined(_MSC_VER) && (_MSC_VER <= 1937) /* MSVC 2022 ver 17.7 or earlier */ +# pragma warning(push) +# pragma warning(disable : 6385) /* warning C6385: Reading invalid data from 'v'. */ +#endif + LZ4_memcpy(&v[4], v, 4); +#if defined(_MSC_VER) && (_MSC_VER <= 1937) /* MSVC 2022 ver 17.7 or earlier */ +# pragma warning(pop) +#endif + break; + case 4: + LZ4_memcpy(v, srcPtr, 4); + LZ4_memcpy(&v[4], srcPtr, 4); + break; + default: + LZ4_memcpy_using_offset_base(dstPtr, srcPtr, dstEnd, offset); + return; + } + + LZ4_memcpy(dstPtr, v, 8); + dstPtr += 8; + while (dstPtr < dstEnd) { + LZ4_memcpy(dstPtr, v, 8); + dstPtr += 8; + } +} +#endif + + +/*-************************************ +* Common functions +**************************************/ +static unsigned LZ4_NbCommonBytes (reg_t val) +{ + assert(val != 0); if (LZ4_isLittleEndian()) { - if (LZ4_64bits()) { -#if defined(_MSC_VER) && defined(_WIN64) && !defined(LZ4_FORCE_SW_BITCOUNT) + if (sizeof(val) == 8) { +# if defined(_MSC_VER) && (_MSC_VER >= 1800) && (defined(_M_AMD64) && !defined(_M_ARM64EC)) && !defined(LZ4_FORCE_SW_BITCOUNT) +/*-************************************************************************************************* +* ARM64EC is a Microsoft-designed ARM64 ABI compatible with AMD64 applications on ARM64 Windows 11. +* The ARM64EC ABI does not support AVX/AVX2/AVX512 instructions, nor their relevant intrinsics +* including _tzcnt_u64. Therefore, we need to neuter the _tzcnt_u64 code path for ARM64EC. +****************************************************************************************************/ +# if defined(__clang__) && (__clang_major__ < 10) + /* Avoid undefined clang-cl intrinsics issue. + * See https://github.com/lz4/lz4/pull/1017 for details. */ + return (unsigned)__builtin_ia32_tzcnt_u64(val) >> 3; +# else + /* x64 CPUS without BMI support interpret `TZCNT` as `REP BSF` */ + return (unsigned)_tzcnt_u64(val) >> 3; +# endif +# elif defined(_MSC_VER) && defined(_WIN64) && !defined(LZ4_FORCE_SW_BITCOUNT) unsigned long r = 0; _BitScanForward64(&r, (U64)val); - return (int)(r >> 3); -#elif (defined(__clang__) || (LZ4_GCC_VERSION >= 304)) && !defined(LZ4_FORCE_SW_BITCOUNT) - return (__builtin_ctzll((U64)val) >> 3); -#else - static const int DeBruijnBytePos[64] = {0, 0, 0, 0, 0, 1, 1, 2, 0, 3, 1, 3, 1, 4, 2, 7, 0, 2, 3, 6, 1, 5, - 3, 5, 1, 3, 4, 4, 2, 5, 6, 7, 7, 0, 1, 2, 3, 3, 4, 6, 2, 6, 5, 5, - 3, 4, 5, 6, 7, 1, 2, 4, 6, 4, 4, 5, 7, 2, 6, 5, 7, 6, 7, 7}; - return DeBruijnBytePos[((U64)((val & -(long long)val) * 0x0218A392CDABBD3FULL)) >> 58]; -#endif - } else /* 32 bits */ - { -#if defined(_MSC_VER) && !defined(LZ4_FORCE_SW_BITCOUNT) + return (unsigned)r >> 3; +# elif (defined(__clang__) || (defined(__GNUC__) && ((__GNUC__ > 3) || \ + ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 4))))) && \ + !defined(LZ4_FORCE_SW_BITCOUNT) + return (unsigned)__builtin_ctzll((U64)val) >> 3; +# else + const U64 m = 0x0101010101010101ULL; + val ^= val - 1; + return (unsigned)(((U64)((val & (m - 1)) * m)) >> 56); +# endif + } else /* 32 bits */ { +# if defined(_MSC_VER) && (_MSC_VER >= 1400) && !defined(LZ4_FORCE_SW_BITCOUNT) unsigned long r; _BitScanForward(&r, (U32)val); - return (int)(r >> 3); -#elif (defined(__clang__) || (LZ4_GCC_VERSION >= 304)) && !defined(LZ4_FORCE_SW_BITCOUNT) - return (__builtin_ctz((U32)val) >> 3); -#else - static const int DeBruijnBytePos[32] = {0, 0, 3, 0, 3, 1, 3, 0, 3, 2, 2, 1, 3, 2, 0, 1, - 3, 3, 1, 2, 2, 2, 2, 0, 3, 1, 2, 0, 1, 0, 1, 1}; - return DeBruijnBytePos[((U32)((val & -(S32)val) * 0x077CB531U)) >> 27]; -#endif + return (unsigned)r >> 3; +# elif (defined(__clang__) || (defined(__GNUC__) && ((__GNUC__ > 3) || \ + ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 4))))) && \ + !defined(__TINYC__) && !defined(LZ4_FORCE_SW_BITCOUNT) + return (unsigned)__builtin_ctz((U32)val) >> 3; +# else + const U32 m = 0x01010101; + return (unsigned)((((val - 1) ^ val) & (m - 1)) * m) >> 24; +# endif } - } else /* Big Endian CPU */ - { - if (LZ4_64bits()) { -#if defined(_MSC_VER) && defined(_WIN64) && !defined(LZ4_FORCE_SW_BITCOUNT) - unsigned long r = 0; - _BitScanReverse64(&r, val); - return (unsigned)(r >> 3); -#elif (defined(__clang__) || (LZ4_GCC_VERSION >= 304)) && !defined(LZ4_FORCE_SW_BITCOUNT) - return (__builtin_clzll((U64)val) >> 3); + } else /* Big Endian CPU */ { + if (sizeof(val)==8) { +# if (defined(__clang__) || (defined(__GNUC__) && ((__GNUC__ > 3) || \ + ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 4))))) && \ + !defined(__TINYC__) && !defined(LZ4_FORCE_SW_BITCOUNT) + return (unsigned)__builtin_clzll((U64)val) >> 3; +# else +#if 1 + /* this method is probably faster, + * but adds a 128 bytes lookup table */ + static const unsigned char ctz7_tab[128] = { + 7, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0, + 4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0, + 5, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0, + 4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0, + 6, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0, + 4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0, + 5, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0, + 4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0, + }; + U64 const mask = 0x0101010101010101ULL; + U64 const t = (((val >> 8) - mask) | val) & mask; + return ctz7_tab[(t * 0x0080402010080402ULL) >> 57]; #else + /* this method doesn't consume memory space like the previous one, + * but it contains several branches, + * that may end up slowing execution */ + static const U32 by32 = sizeof(val)*4; /* 32 on 64 bits (goal), 16 on 32 bits. + Just to avoid some static analyzer complaining about shift by 32 on 32-bits target. + Note that this code path is never triggered in 32-bits mode. */ unsigned r; - if (!(val >> 32)) { - r = 4; - } else { - r = 0; - val >>= 32; - } - if (!(val >> 16)) { - r += 2; - val >>= 8; - } else { - val >>= 24; - } - r += (!val); - return r; -#endif - } else /* 32 bits */ - { -#if defined(_MSC_VER) && !defined(LZ4_FORCE_SW_BITCOUNT) - unsigned long r = 0; - _BitScanReverse(&r, (unsigned long)val); - return (unsigned)(r >> 3); -#elif (defined(__clang__) || (LZ4_GCC_VERSION >= 304)) && !defined(LZ4_FORCE_SW_BITCOUNT) - return (__builtin_clz((U32)val) >> 3); -#else - unsigned r; - if (!(val >> 16)) { - r = 2; - val >>= 8; - } else { - r = 0; - val >>= 24; - } + if (!(val>>by32)) { r=4; } else { r=0; val>>=by32; } + if (!(val>>16)) { r+=2; val>>=8; } else { val>>=24; } r += (!val); return r; #endif +# endif + } else /* 32 bits */ { +# if (defined(__clang__) || (defined(__GNUC__) && ((__GNUC__ > 3) || \ + ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 4))))) && \ + !defined(LZ4_FORCE_SW_BITCOUNT) + return (unsigned)__builtin_clz((U32)val) >> 3; +# else + val >>= 8; + val = ((((val + 0x00FFFF00) | 0x00FFFFFF) + val) | + (val + 0x00FF0000)) >> 24; + return (unsigned)val ^ 3; +# endif } } } -static unsigned LZ4_count(const BYTE *pIn, const BYTE *pMatch, const BYTE *pInLimit) -{ - const BYTE *const pStart = pIn; - while (likely(pIn < pInLimit - (STEPSIZE - 1))) { - size_t diff = LZ4_read_ARCH(pMatch) ^ LZ4_read_ARCH(pIn); +#define STEPSIZE sizeof(reg_t) +LZ4_FORCE_INLINE +unsigned LZ4_count(const BYTE* pIn, const BYTE* pMatch, const BYTE* pInLimit) +{ + const BYTE* const pStart = pIn; + + if (likely(pIn < pInLimit-(STEPSIZE-1))) { + reg_t const diff = LZ4_read_ARCH(pMatch) ^ LZ4_read_ARCH(pIn); if (!diff) { - pIn += STEPSIZE; - pMatch += STEPSIZE; - continue; - } + pIn+=STEPSIZE; pMatch+=STEPSIZE; + } else { + return LZ4_NbCommonBytes(diff); + } } + + while (likely(pIn < pInLimit-(STEPSIZE-1))) { + reg_t const diff = LZ4_read_ARCH(pMatch) ^ LZ4_read_ARCH(pIn); + if (!diff) { pIn+=STEPSIZE; pMatch+=STEPSIZE; continue; } pIn += LZ4_NbCommonBytes(diff); return (unsigned)(pIn - pStart); } - if (LZ4_64bits()) - if ((pIn < (pInLimit - 3)) && (LZ4_read32(pMatch) == LZ4_read32(pIn))) { - pIn += 4; - pMatch += 4; - } - if ((pIn < (pInLimit - 1)) && (LZ4_read16(pMatch) == LZ4_read16(pIn))) { - pIn += 2; - pMatch += 2; - } - if ((pIn < pInLimit) && (*pMatch == *pIn)) - pIn++; + if ((STEPSIZE==8) && (pIn<(pInLimit-3)) && (LZ4_read32(pMatch) == LZ4_read32(pIn))) { pIn+=4; pMatch+=4; } + if ((pIn<(pInLimit-1)) && (LZ4_read16(pMatch) == LZ4_read16(pIn))) { pIn+=2; pMatch+=2; } + if ((pIn compression run slower on incompressible data */ -static const int LZ4_64Klimit = ((64 KB) + (MFLIMIT - 1)); -static const U32 LZ4_skipTrigger = 6; /* Increase this value ==> compression run slower on incompressible data */ -/************************************** - * Local Structures and types - **************************************/ -typedef struct -{ - U32 hashTable[HASH_SIZE_U32]; - U32 currentOffset; - U32 initCheck; - const BYTE *dictionary; - BYTE *bufferStart; /* obsolete, used for slideInputBuffer */ - U32 dictSize; -} LZ4_stream_t_internal; +/*-************************************ +* Local Structures and types +**************************************/ +typedef enum { clearedTable = 0, byPtr, byU32, byU16 } tableType_t; -typedef enum -{ - notLimited = 0, - limitedOutput = 1 -} limitedOutput_directive; -typedef enum -{ - byPtr, - byU32, - byU16 -} tableType_t; +/** + * This enum distinguishes several different modes of accessing previous + * content in the stream. + * + * - noDict : There is no preceding content. + * - withPrefix64k : Table entries up to ctx->dictSize before the current blob + * blob being compressed are valid and refer to the preceding + * content (of length ctx->dictSize), which is available + * contiguously preceding in memory the content currently + * being compressed. + * - usingExtDict : Like withPrefix64k, but the preceding content is somewhere + * else in memory, starting at ctx->dictionary with length + * ctx->dictSize. + * - usingDictCtx : Everything concerning the preceding content is + * in a separate context, pointed to by ctx->dictCtx. + * ctx->dictionary, ctx->dictSize, and table entries + * in the current context that refer to positions + * preceding the beginning of the current compression are + * ignored. Instead, ctx->dictCtx->dictionary and ctx->dictCtx + * ->dictSize describe the location and size of the preceding + * content, and matches are found by looking in the ctx + * ->dictCtx->hashTable. + */ +typedef enum { noDict = 0, withPrefix64k, usingExtDict, usingDictCtx } dict_directive; +typedef enum { noDictIssue = 0, dictSmall } dictIssue_directive; -typedef enum -{ - noDict = 0, - withPrefix64k, - usingExtDict -} dict_directive; -typedef enum -{ - noDictIssue = 0, - dictSmall -} dictIssue_directive; -typedef enum -{ - endOnOutputSize = 0, - endOnInputSize = 1 -} endCondition_directive; -typedef enum -{ - full = 0, - partial = 1 -} earlyEnd_directive; +/*-************************************ +* Local Utils +**************************************/ +int LZ4_versionNumber (void) { return LZ4_VERSION_NUMBER; } +const char* LZ4_versionString(void) { return LZ4_VERSION_STRING; } +int LZ4_compressBound(int isize) { return LZ4_COMPRESSBOUND(isize); } +int LZ4_sizeofState(void) { return sizeof(LZ4_stream_t); } -/************************************** - * Local Utils - **************************************/ -int LZ4_versionNumber(void) { return LZ4_VERSION_NUMBER; } -int LZ4_compressBound(int isize) { return LZ4_COMPRESSBOUND(isize); } -int LZ4_sizeofState() { return LZ4_STREAMSIZE; } -/******************************** - * Compression functions - ********************************/ +/*-**************************************** +* Internal Definitions, used only in Tests +*******************************************/ +#if defined (__cplusplus) +extern "C" { +#endif -static U32 LZ4_hashSequence(U32 sequence, tableType_t const tableType) +int LZ4_compress_forceExtDict (LZ4_stream_t* LZ4_dict, const char* source, char* dest, int srcSize); + +int LZ4_decompress_safe_forceExtDict(const char* source, char* dest, + int compressedSize, int maxOutputSize, + const void* dictStart, size_t dictSize); +int LZ4_decompress_safe_partial_forceExtDict(const char* source, char* dest, + int compressedSize, int targetOutputSize, int dstCapacity, + const void* dictStart, size_t dictSize); +#if defined (__cplusplus) +} +#endif + +/*-****************************** +* Compression functions +********************************/ +LZ4_FORCE_INLINE U32 LZ4_hash4(U32 sequence, tableType_t const tableType) { if (tableType == byU16) - return (((sequence)*2654435761U) >> ((MINMATCH * 8) - (LZ4_HASHLOG + 1))); + return ((sequence * 2654435761U) >> ((MINMATCH*8)-(LZ4_HASHLOG+1))); else - return (((sequence)*2654435761U) >> ((MINMATCH * 8) - LZ4_HASHLOG)); + return ((sequence * 2654435761U) >> ((MINMATCH*8)-LZ4_HASHLOG)); } -static const U64 prime5bytes = 889523592379ULL; -static U32 LZ4_hashSequence64(size_t sequence, tableType_t const tableType) +LZ4_FORCE_INLINE U32 LZ4_hash5(U64 sequence, tableType_t const tableType) { - const U32 hashLog = (tableType == byU16) ? LZ4_HASHLOG + 1 : LZ4_HASHLOG; - const U32 hashMask = (1 << hashLog) - 1; - return ((sequence * prime5bytes) >> (40 - hashLog)) & hashMask; -} - -static U32 LZ4_hashSequenceT(size_t sequence, tableType_t const tableType) -{ - if (LZ4_64bits()) - return LZ4_hashSequence64(sequence, tableType); - return LZ4_hashSequence((U32)sequence, tableType); -} - -static U32 LZ4_hashPosition(const void *p, tableType_t tableType) -{ - return LZ4_hashSequenceT(LZ4_read_ARCH(p), tableType); -} - -static void LZ4_putPositionOnHash(const BYTE *p, U32 h, void *tableBase, tableType_t const tableType, - const BYTE *srcBase) -{ - switch (tableType) { - case byPtr: { - const BYTE **hashTable = (const BYTE **)tableBase; - hashTable[h] = p; - return; - } - case byU32: { - U32 *hashTable = (U32 *)tableBase; - hashTable[h] = (U32)(p - srcBase); - return; - } - case byU16: { - U16 *hashTable = (U16 *)tableBase; - hashTable[h] = (U16)(p - srcBase); - return; - } + const U32 hashLog = (tableType == byU16) ? LZ4_HASHLOG+1 : LZ4_HASHLOG; + if (LZ4_isLittleEndian()) { + const U64 prime5bytes = 889523592379ULL; + return (U32)(((sequence << 24) * prime5bytes) >> (64 - hashLog)); + } else { + const U64 prime8bytes = 11400714785074694791ULL; + return (U32)(((sequence >> 24) * prime8bytes) >> (64 - hashLog)); } } -static void LZ4_putPosition(const BYTE *p, void *tableBase, tableType_t tableType, const BYTE *srcBase) +LZ4_FORCE_INLINE U32 LZ4_hashPosition(const void* const p, tableType_t const tableType) { - U32 h = LZ4_hashPosition(p, tableType); - LZ4_putPositionOnHash(p, h, tableBase, tableType, srcBase); + if ((sizeof(reg_t)==8) && (tableType != byU16)) return LZ4_hash5(LZ4_read_ARCH(p), tableType); + +#ifdef LZ4_STATIC_LINKING_ONLY_ENDIANNESS_INDEPENDENT_OUTPUT + return LZ4_hash4(LZ4_readLE32(p), tableType); +#else + return LZ4_hash4(LZ4_read32(p), tableType); +#endif } -static const BYTE *LZ4_getPositionOnHash(U32 h, void *tableBase, tableType_t tableType, const BYTE *srcBase) +LZ4_FORCE_INLINE void LZ4_clearHash(U32 h, void* tableBase, tableType_t const tableType) { - if (tableType == byPtr) { - const BYTE **hashTable = (const BYTE **)tableBase; + switch (tableType) + { + default: /* fallthrough */ + case clearedTable: { /* illegal! */ assert(0); return; } + case byPtr: { const BYTE** hashTable = (const BYTE**)tableBase; hashTable[h] = NULL; return; } + case byU32: { U32* hashTable = (U32*) tableBase; hashTable[h] = 0; return; } + case byU16: { U16* hashTable = (U16*) tableBase; hashTable[h] = 0; return; } + } +} + +LZ4_FORCE_INLINE void LZ4_putIndexOnHash(U32 idx, U32 h, void* tableBase, tableType_t const tableType) +{ + switch (tableType) + { + default: /* fallthrough */ + case clearedTable: /* fallthrough */ + case byPtr: { /* illegal! */ assert(0); return; } + case byU32: { U32* hashTable = (U32*) tableBase; hashTable[h] = idx; return; } + case byU16: { U16* hashTable = (U16*) tableBase; assert(idx < 65536); hashTable[h] = (U16)idx; return; } + } +} + +/* LZ4_putPosition*() : only used in byPtr mode */ +LZ4_FORCE_INLINE void LZ4_putPositionOnHash(const BYTE* p, U32 h, + void* tableBase, tableType_t const tableType) +{ + const BYTE** const hashTable = (const BYTE**)tableBase; + assert(tableType == byPtr); (void)tableType; + hashTable[h] = p; +} + +LZ4_FORCE_INLINE void LZ4_putPosition(const BYTE* p, void* tableBase, tableType_t tableType) +{ + U32 const h = LZ4_hashPosition(p, tableType); + LZ4_putPositionOnHash(p, h, tableBase, tableType); +} + +/* LZ4_getIndexOnHash() : + * Index of match position registered in hash table. + * hash position must be calculated by using base+index, or dictBase+index. + * Assumption 1 : only valid if tableType == byU32 or byU16. + * Assumption 2 : h is presumed valid (within limits of hash table) + */ +LZ4_FORCE_INLINE U32 LZ4_getIndexOnHash(U32 h, const void* tableBase, tableType_t tableType) +{ + LZ4_STATIC_ASSERT(LZ4_MEMORY_USAGE > 2); + if (tableType == byU32) { + const U32* const hashTable = (const U32*) tableBase; + assert(h < (1U << (LZ4_MEMORY_USAGE-2))); return hashTable[h]; } - if (tableType == byU32) { - U32 *hashTable = (U32 *)tableBase; - return hashTable[h] + srcBase; + if (tableType == byU16) { + const U16* const hashTable = (const U16*) tableBase; + assert(h < (1U << (LZ4_MEMORY_USAGE-1))); + return hashTable[h]; } - { - U16 *hashTable = (U16 *)tableBase; - return hashTable[h] + srcBase; - } /* default, to ensure a return */ + assert(0); return 0; /* forbidden case */ } -static const BYTE *LZ4_getPosition(const BYTE *p, void *tableBase, tableType_t tableType, const BYTE *srcBase) +static const BYTE* LZ4_getPositionOnHash(U32 h, const void* tableBase, tableType_t tableType) { - U32 h = LZ4_hashPosition(p, tableType); - return LZ4_getPositionOnHash(h, tableBase, tableType, srcBase); + assert(tableType == byPtr); (void)tableType; + { const BYTE* const* hashTable = (const BYTE* const*) tableBase; return hashTable[h]; } } -FORCE_INLINE int LZ4_compress_generic(void *const ctx, const char *const source, char *const dest, const int inputSize, - const int maxOutputSize, const limitedOutput_directive outputLimited, - const tableType_t tableType, const dict_directive dict, - const dictIssue_directive dictIssue, const U32 acceleration) +LZ4_FORCE_INLINE const BYTE* +LZ4_getPosition(const BYTE* p, + const void* tableBase, tableType_t tableType) { - LZ4_stream_t_internal *const dictPtr = (LZ4_stream_t_internal *)ctx; + U32 const h = LZ4_hashPosition(p, tableType); + return LZ4_getPositionOnHash(h, tableBase, tableType); +} - const BYTE *ip = (const BYTE *)source; - const BYTE *base; - const BYTE *lowLimit; - const BYTE *const lowRefLimit = ip - dictPtr->dictSize; - const BYTE *const dictionary = dictPtr->dictionary; - const BYTE *const dictEnd = dictionary + dictPtr->dictSize; - const size_t dictDelta = dictEnd - (const BYTE *)source; - const BYTE *anchor = (const BYTE *)source; - const BYTE *const iend = ip + inputSize; - const BYTE *const mflimit = iend - MFLIMIT; - const BYTE *const matchlimit = iend - LASTLITERALS; +LZ4_FORCE_INLINE void +LZ4_prepareTable(LZ4_stream_t_internal* const cctx, + const int inputSize, + const tableType_t tableType) { + /* If the table hasn't been used, it's guaranteed to be zeroed out, and is + * therefore safe to use no matter what mode we're in. Otherwise, we figure + * out if it's safe to leave as is or whether it needs to be reset. + */ + if ((tableType_t)cctx->tableType != clearedTable) { + assert(inputSize >= 0); + if ((tableType_t)cctx->tableType != tableType + || ((tableType == byU16) && cctx->currentOffset + (unsigned)inputSize >= 0xFFFFU) + || ((tableType == byU32) && cctx->currentOffset > 1 GB) + || tableType == byPtr + || inputSize >= 4 KB) + { + DEBUGLOG(4, "LZ4_prepareTable: Resetting table in %p", cctx); + MEM_INIT(cctx->hashTable, 0, LZ4_HASHTABLESIZE); + cctx->currentOffset = 0; + cctx->tableType = (U32)clearedTable; + } else { + DEBUGLOG(4, "LZ4_prepareTable: Re-use hash table (no reset)"); + } + } - BYTE *op = (BYTE *)dest; - BYTE *const olimit = op + maxOutputSize; + /* Adding a gap, so all previous entries are > LZ4_DISTANCE_MAX back, + * is faster than compressing without a gap. + * However, compressing with currentOffset == 0 is faster still, + * so we preserve that case. + */ + if (cctx->currentOffset != 0 && tableType == byU32) { + DEBUGLOG(5, "LZ4_prepareTable: adding 64KB to currentOffset"); + cctx->currentOffset += 64 KB; + } + /* Finally, clear history */ + cctx->dictCtx = NULL; + cctx->dictionary = NULL; + cctx->dictSize = 0; +} + +/** LZ4_compress_generic_validated() : + * inlined, to ensure branches are decided at compilation time. + * The following conditions are presumed already validated: + * - source != NULL + * - inputSize > 0 + */ +LZ4_FORCE_INLINE int LZ4_compress_generic_validated( + LZ4_stream_t_internal* const cctx, + const char* const source, + char* const dest, + const int inputSize, + int* inputConsumed, /* only written when outputDirective == fillOutput */ + const int maxOutputSize, + const limitedOutput_directive outputDirective, + const tableType_t tableType, + const dict_directive dictDirective, + const dictIssue_directive dictIssue, + const int acceleration) +{ + int result; + const BYTE* ip = (const BYTE*)source; + + U32 const startIndex = cctx->currentOffset; + const BYTE* base = (const BYTE*)source - startIndex; + const BYTE* lowLimit; + + const LZ4_stream_t_internal* dictCtx = (const LZ4_stream_t_internal*) cctx->dictCtx; + const BYTE* const dictionary = + dictDirective == usingDictCtx ? dictCtx->dictionary : cctx->dictionary; + const U32 dictSize = + dictDirective == usingDictCtx ? dictCtx->dictSize : cctx->dictSize; + const U32 dictDelta = + (dictDirective == usingDictCtx) ? startIndex - dictCtx->currentOffset : 0; /* make indexes in dictCtx comparable with indexes in current context */ + + int const maybe_extMem = (dictDirective == usingExtDict) || (dictDirective == usingDictCtx); + U32 const prefixIdxLimit = startIndex - dictSize; /* used when dictDirective == dictSmall */ + const BYTE* const dictEnd = dictionary ? dictionary + dictSize : dictionary; + const BYTE* anchor = (const BYTE*) source; + const BYTE* const iend = ip + inputSize; + const BYTE* const mflimitPlusOne = iend - MFLIMIT + 1; + const BYTE* const matchlimit = iend - LASTLITERALS; + + /* the dictCtx currentOffset is indexed on the start of the dictionary, + * while a dictionary in the current context precedes the currentOffset */ + const BYTE* dictBase = (dictionary == NULL) ? NULL : + (dictDirective == usingDictCtx) ? + dictionary + dictSize - dictCtx->currentOffset : + dictionary + dictSize - startIndex; + + BYTE* op = (BYTE*) dest; + BYTE* const olimit = op + maxOutputSize; + + U32 offset = 0; U32 forwardH; - size_t refDelta = 0; - /* Init conditions */ - if ((U32)inputSize > (U32)LZ4_MAX_INPUT_SIZE) - return 0; /* Unsupported input size, too large (or negative) */ - switch (dict) { - case noDict: - default: - base = (const BYTE *)source; - lowLimit = (const BYTE *)source; - break; - case withPrefix64k: - base = (const BYTE *)source - dictPtr->currentOffset; - lowLimit = (const BYTE *)source - dictPtr->dictSize; - break; - case usingExtDict: - base = (const BYTE *)source - dictPtr->currentOffset; - lowLimit = (const BYTE *)source; - break; + DEBUGLOG(5, "LZ4_compress_generic_validated: srcSize=%i, tableType=%u", inputSize, tableType); + assert(ip != NULL); + if (tableType == byU16) assert(inputSize= 1); + + lowLimit = (const BYTE*)source - (dictDirective == withPrefix64k ? dictSize : 0); + + /* Update context state */ + if (dictDirective == usingDictCtx) { + /* Subsequent linked blocks can't use the dictionary. */ + /* Instead, they use the block we just compressed. */ + cctx->dictCtx = NULL; + cctx->dictSize = (U32)inputSize; + } else { + cctx->dictSize += (U32)inputSize; } - if ((tableType == byU16) && (inputSize >= LZ4_64Klimit)) - return 0; /* Size too large (not within 64K limit) */ - if (inputSize < LZ4_minLength) - goto _last_literals; /* Input too small, no compression (all literals) */ + cctx->currentOffset += (U32)inputSize; + cctx->tableType = (U32)tableType; + + if (inputSizehashTable, byPtr); + } else { + LZ4_putIndexOnHash(startIndex, h, cctx->hashTable, tableType); + } } + ip++; forwardH = LZ4_hashPosition(ip, tableType); /* Main Loop */ - for (;;) { - const BYTE *match; - BYTE *token; - { - const BYTE *forwardIp = ip; - unsigned step = 1; - unsigned searchMatchNb = acceleration << LZ4_skipTrigger; + for ( ; ; ) { + const BYTE* match; + BYTE* token; + const BYTE* filledIp; - /* Find a match */ + /* Find a match */ + if (tableType == byPtr) { + const BYTE* forwardIp = ip; + int step = 1; + int searchMatchNb = acceleration << LZ4_skipTrigger; do { - U32 h = forwardH; + U32 const h = forwardH; ip = forwardIp; forwardIp += step; step = (searchMatchNb++ >> LZ4_skipTrigger); - if (unlikely(forwardIp > mflimit)) - goto _last_literals; + if (unlikely(forwardIp > mflimitPlusOne)) goto _last_literals; + assert(ip < mflimitPlusOne); - match = LZ4_getPositionOnHash(h, ctx, tableType, base); - if (dict == usingExtDict) { - if (match < (const BYTE *)source) { - refDelta = dictDelta; + match = LZ4_getPositionOnHash(h, cctx->hashTable, tableType); + forwardH = LZ4_hashPosition(forwardIp, tableType); + LZ4_putPositionOnHash(ip, h, cctx->hashTable, tableType); + + } while ( (match+LZ4_DISTANCE_MAX < ip) + || (LZ4_read32(match) != LZ4_read32(ip)) ); + + } else { /* byU32, byU16 */ + + const BYTE* forwardIp = ip; + int step = 1; + int searchMatchNb = acceleration << LZ4_skipTrigger; + do { + U32 const h = forwardH; + U32 const current = (U32)(forwardIp - base); + U32 matchIndex = LZ4_getIndexOnHash(h, cctx->hashTable, tableType); + assert(matchIndex <= current); + assert(forwardIp - base < (ptrdiff_t)(2 GB - 1)); + ip = forwardIp; + forwardIp += step; + step = (searchMatchNb++ >> LZ4_skipTrigger); + + if (unlikely(forwardIp > mflimitPlusOne)) goto _last_literals; + assert(ip < mflimitPlusOne); + + if (dictDirective == usingDictCtx) { + if (matchIndex < startIndex) { + /* there was no match, try the dictionary */ + assert(tableType == byU32); + matchIndex = LZ4_getIndexOnHash(h, dictCtx->hashTable, byU32); + match = dictBase + matchIndex; + matchIndex += dictDelta; /* make dictCtx index comparable with current context */ lowLimit = dictionary; } else { - refDelta = 0; - lowLimit = (const BYTE *)source; + match = base + matchIndex; + lowLimit = (const BYTE*)source; } + } else if (dictDirective == usingExtDict) { + if (matchIndex < startIndex) { + DEBUGLOG(7, "extDict candidate: matchIndex=%5u < startIndex=%5u", matchIndex, startIndex); + assert(startIndex - matchIndex >= MINMATCH); + assert(dictBase); + match = dictBase + matchIndex; + lowLimit = dictionary; + } else { + match = base + matchIndex; + lowLimit = (const BYTE*)source; + } + } else { /* single continuous memory segment */ + match = base + matchIndex; } forwardH = LZ4_hashPosition(forwardIp, tableType); - LZ4_putPositionOnHash(ip, h, ctx, tableType, base); + LZ4_putIndexOnHash(current, h, cctx->hashTable, tableType); - } while (((dictIssue == dictSmall) ? (match < lowRefLimit) : 0) || - ((tableType == byU16) ? 0 : (match + MAX_DISTANCE < ip)) || - (LZ4_read32(match + refDelta) != LZ4_read32(ip))); + DEBUGLOG(7, "candidate at pos=%u (offset=%u \n", matchIndex, current - matchIndex); + if ((dictIssue == dictSmall) && (matchIndex < prefixIdxLimit)) { continue; } /* match outside of valid area */ + assert(matchIndex < current); + if ( ((tableType != byU16) || (LZ4_DISTANCE_MAX < LZ4_DISTANCE_ABSOLUTE_MAX)) + && (matchIndex+LZ4_DISTANCE_MAX < current)) { + continue; + } /* too far */ + assert((current - matchIndex) <= LZ4_DISTANCE_MAX); /* match now expected within distance */ + + if (LZ4_read32(match) == LZ4_read32(ip)) { + if (maybe_extMem) offset = current - matchIndex; + break; /* match found */ + } + + } while(1); } /* Catch up */ - while ((ip > anchor) && (match + refDelta > lowLimit) && (unlikely(ip[-1] == match[refDelta - 1]))) { - ip--; - match--; + filledIp = ip; + assert(ip > anchor); /* this is always true as ip has been advanced before entering the main loop */ + if ((match > lowLimit) && unlikely(ip[-1] == match[-1])) { + do { ip--; match--; } while (((ip > anchor) & (match > lowLimit)) && (unlikely(ip[-1] == match[-1]))); } - { - /* Encode Literal length */ - unsigned litLength = (unsigned)(ip - anchor); + /* Encode Literals */ + { unsigned const litLength = (unsigned)(ip - anchor); token = op++; - if ((outputLimited) && (unlikely(op + litLength + (2 + 1 + LASTLITERALS) + (litLength / 255) > olimit))) - return 0; /* Check output limit */ + if ((outputDirective == limitedOutput) && /* Check output buffer overflow */ + (unlikely(op + litLength + (2 + 1 + LASTLITERALS) + (litLength/255) > olimit)) ) { + return 0; /* cannot compress within `dst` budget. Stored indexes in hash table are nonetheless fine */ + } + if ((outputDirective == fillOutput) && + (unlikely(op + (litLength+240)/255 /* litlen */ + litLength /* literals */ + 2 /* offset */ + 1 /* token */ + MFLIMIT - MINMATCH /* min last literals so last match is <= end - MFLIMIT */ > olimit))) { + op--; + goto _last_literals; + } if (litLength >= RUN_MASK) { - int len = (int)litLength - RUN_MASK; - *token = (RUN_MASK << ML_BITS); - for (; len >= 255; len -= 255) - *op++ = 255; + int len = (int)(litLength - RUN_MASK); + *token = (RUN_MASK<= 255 ; len-=255) *op++ = 255; *op++ = (BYTE)len; - } else - *token = (BYTE)(litLength << ML_BITS); + } + else *token = (BYTE)(litLength< olimit)) { + /* the match was too close to the end, rewind and go to last literals */ + op = token; + goto _last_literals; } - _next_match: /* Encode Offset */ - LZ4_writeLE16(op, (U16)(ip - match)); - op += 2; + if (maybe_extMem) { /* static test */ + DEBUGLOG(6, " with offset=%u (ext if > %i)", offset, (int)(ip - (const BYTE*)source)); + assert(offset <= LZ4_DISTANCE_MAX && offset > 0); + LZ4_writeLE16(op, (U16)offset); op+=2; + } else { + DEBUGLOG(6, " with offset=%u (same segment)", (U32)(ip - match)); + assert(ip-match <= LZ4_DISTANCE_MAX); + LZ4_writeLE16(op, (U16)(ip - match)); op+=2; + } /* Encode MatchLength */ - { - unsigned matchLength; + { unsigned matchCode; - if ((dict == usingExtDict) && (lowLimit == dictionary)) { - const BYTE *limit; - match += refDelta; - limit = ip + (dictEnd - match); - if (limit > matchlimit) - limit = matchlimit; - matchLength = LZ4_count(ip + MINMATCH, match + MINMATCH, limit); - ip += MINMATCH + matchLength; - if (ip == limit) { - unsigned more = LZ4_count(ip, (const BYTE *)source, matchlimit); - matchLength += more; + if ( (dictDirective==usingExtDict || dictDirective==usingDictCtx) + && (lowLimit==dictionary) /* match within extDict */ ) { + const BYTE* limit = ip + (dictEnd-match); + assert(dictEnd > match); + if (limit > matchlimit) limit = matchlimit; + matchCode = LZ4_count(ip+MINMATCH, match+MINMATCH, limit); + ip += (size_t)matchCode + MINMATCH; + if (ip==limit) { + unsigned const more = LZ4_count(limit, (const BYTE*)source, matchlimit); + matchCode += more; ip += more; } + DEBUGLOG(6, " with matchLength=%u starting in extDict", matchCode+MINMATCH); } else { - matchLength = LZ4_count(ip + MINMATCH, match + MINMATCH, matchlimit); - ip += MINMATCH + matchLength; + matchCode = LZ4_count(ip+MINMATCH, match+MINMATCH, matchlimit); + ip += (size_t)matchCode + MINMATCH; + DEBUGLOG(6, " with matchLength=%u", matchCode+MINMATCH); } - if ((outputLimited) && (unlikely(op + (1 + LASTLITERALS) + (matchLength >> 8) > olimit))) - return 0; /* Check output limit */ - if (matchLength >= ML_MASK) { + if ((outputDirective) && /* Check output buffer overflow */ + (unlikely(op + (1 + LASTLITERALS) + (matchCode+240)/255 > olimit)) ) { + if (outputDirective == fillOutput) { + /* Match description too long : reduce it */ + U32 newMatchCode = 15 /* in token */ - 1 /* to avoid needing a zero byte */ + ((U32)(olimit - op) - 1 - LASTLITERALS) * 255; + ip -= matchCode - newMatchCode; + assert(newMatchCode < matchCode); + matchCode = newMatchCode; + if (unlikely(ip <= filledIp)) { + /* We have already filled up to filledIp so if ip ends up less than filledIp + * we have positions in the hash table beyond the current position. This is + * a problem if we reuse the hash table. So we have to remove these positions + * from the hash table. + */ + const BYTE* ptr; + DEBUGLOG(5, "Clearing %u positions", (U32)(filledIp - ip)); + for (ptr = ip; ptr <= filledIp; ++ptr) { + U32 const h = LZ4_hashPosition(ptr, tableType); + LZ4_clearHash(h, cctx->hashTable, tableType); + } + } + } else { + assert(outputDirective == limitedOutput); + return 0; /* cannot compress within `dst` budget. Stored indexes in hash table are nonetheless fine */ + } + } + if (matchCode >= ML_MASK) { *token += ML_MASK; - matchLength -= ML_MASK; - for (; matchLength >= 510; matchLength -= 510) { - *op++ = 255; - *op++ = 255; + matchCode -= ML_MASK; + LZ4_write32(op, 0xFFFFFFFF); + while (matchCode >= 4*255) { + op+=4; + LZ4_write32(op, 0xFFFFFFFF); + matchCode -= 4*255; } - if (matchLength >= 255) { - matchLength -= 255; - *op++ = 255; - } - *op++ = (BYTE)matchLength; + op += matchCode / 255; + *op++ = (BYTE)(matchCode % 255); } else - *token += (BYTE)(matchLength); + *token += (BYTE)(matchCode); } + /* Ensure we have enough space for the last literals. */ + assert(!(outputDirective == fillOutput && op + 1 + LASTLITERALS > olimit)); anchor = ip; /* Test end of chunk */ - if (ip > mflimit) - break; + if (ip >= mflimitPlusOne) break; /* Fill table */ - LZ4_putPosition(ip - 2, ctx, tableType, base); + { U32 const h = LZ4_hashPosition(ip-2, tableType); + if (tableType == byPtr) { + LZ4_putPositionOnHash(ip-2, h, cctx->hashTable, byPtr); + } else { + U32 const idx = (U32)((ip-2) - base); + LZ4_putIndexOnHash(idx, h, cctx->hashTable, tableType); + } } /* Test next position */ - match = LZ4_getPosition(ip, ctx, tableType, base); - if (dict == usingExtDict) { - if (match < (const BYTE *)source) { - refDelta = dictDelta; - lowLimit = dictionary; - } else { - refDelta = 0; - lowLimit = (const BYTE *)source; + if (tableType == byPtr) { + + match = LZ4_getPosition(ip, cctx->hashTable, tableType); + LZ4_putPosition(ip, cctx->hashTable, tableType); + if ( (match+LZ4_DISTANCE_MAX >= ip) + && (LZ4_read32(match) == LZ4_read32(ip)) ) + { token=op++; *token=0; goto _next_match; } + + } else { /* byU32, byU16 */ + + U32 const h = LZ4_hashPosition(ip, tableType); + U32 const current = (U32)(ip-base); + U32 matchIndex = LZ4_getIndexOnHash(h, cctx->hashTable, tableType); + assert(matchIndex < current); + if (dictDirective == usingDictCtx) { + if (matchIndex < startIndex) { + /* there was no match, try the dictionary */ + assert(tableType == byU32); + matchIndex = LZ4_getIndexOnHash(h, dictCtx->hashTable, byU32); + match = dictBase + matchIndex; + lowLimit = dictionary; /* required for match length counter */ + matchIndex += dictDelta; + } else { + match = base + matchIndex; + lowLimit = (const BYTE*)source; /* required for match length counter */ + } + } else if (dictDirective==usingExtDict) { + if (matchIndex < startIndex) { + assert(dictBase); + match = dictBase + matchIndex; + lowLimit = dictionary; /* required for match length counter */ + } else { + match = base + matchIndex; + lowLimit = (const BYTE*)source; /* required for match length counter */ + } + } else { /* single memory segment */ + match = base + matchIndex; + } + LZ4_putIndexOnHash(current, h, cctx->hashTable, tableType); + assert(matchIndex < current); + if ( ((dictIssue==dictSmall) ? (matchIndex >= prefixIdxLimit) : 1) + && (((tableType==byU16) && (LZ4_DISTANCE_MAX == LZ4_DISTANCE_ABSOLUTE_MAX)) ? 1 : (matchIndex+LZ4_DISTANCE_MAX >= current)) + && (LZ4_read32(match) == LZ4_read32(ip)) ) { + token=op++; + *token=0; + if (maybe_extMem) offset = current - matchIndex; + DEBUGLOG(6, "seq.start:%i, literals=%u, match.start:%i", + (int)(anchor-(const BYTE*)source), 0, (int)(ip-(const BYTE*)source)); + goto _next_match; } - } - LZ4_putPosition(ip, ctx, tableType, base); - if (((dictIssue == dictSmall) ? (match >= lowRefLimit) : 1) && (match + MAX_DISTANCE >= ip) && - (LZ4_read32(match + refDelta) == LZ4_read32(ip))) { - token = op++; - *token = 0; - goto _next_match; } /* Prepare next loop */ forwardH = LZ4_hashPosition(++ip, tableType); + } _last_literals: /* Encode Last Literals */ - { - const size_t lastRun = (size_t)(iend - anchor); - if ((outputLimited) && - ((op - (BYTE *)dest) + lastRun + 1 + ((lastRun + 255 - RUN_MASK) / 255) > (U32)maxOutputSize)) - return 0; /* Check output limit */ + { size_t lastRun = (size_t)(iend - anchor); + if ( (outputDirective) && /* Check output buffer overflow */ + (op + lastRun + 1 + ((lastRun+255-RUN_MASK)/255) > olimit)) { + if (outputDirective == fillOutput) { + /* adapt lastRun to fill 'dst' */ + assert(olimit >= op); + lastRun = (size_t)(olimit-op) - 1/*token*/; + lastRun -= (lastRun + 256 - RUN_MASK) / 256; /*additional length tokens*/ + } else { + assert(outputDirective == limitedOutput); + return 0; /* cannot compress within `dst` budget. Stored indexes in hash table are nonetheless fine */ + } + } + DEBUGLOG(6, "Final literal run : %i literals", (int)lastRun); if (lastRun >= RUN_MASK) { size_t accumulator = lastRun - RUN_MASK; *op++ = RUN_MASK << ML_BITS; - for (; accumulator >= 255; accumulator -= 255) - *op++ = 255; - *op++ = (BYTE)accumulator; + for(; accumulator >= 255 ; accumulator-=255) *op++ = 255; + *op++ = (BYTE) accumulator; } else { - *op++ = (BYTE)(lastRun << ML_BITS); + *op++ = (BYTE)(lastRun< 0); + DEBUGLOG(5, "LZ4_compress_generic: compressed %i bytes into %i bytes", inputSize, result); + return result; } -int LZ4_compress_fast_extState(void *state, const char *source, char *dest, int inputSize, int maxOutputSize, - int acceleration) +/** LZ4_compress_generic() : + * inlined, to ensure branches are decided at compilation time; + * takes care of src == (NULL, 0) + * and forward the rest to LZ4_compress_generic_validated */ +LZ4_FORCE_INLINE int LZ4_compress_generic( + LZ4_stream_t_internal* const cctx, + const char* const src, + char* const dst, + const int srcSize, + int *inputConsumed, /* only written when outputDirective == fillOutput */ + const int dstCapacity, + const limitedOutput_directive outputDirective, + const tableType_t tableType, + const dict_directive dictDirective, + const dictIssue_directive dictIssue, + const int acceleration) { - LZ4_resetStream((LZ4_stream_t *)state); - if (acceleration < 1) - acceleration = ACCELERATION_DEFAULT; + DEBUGLOG(5, "LZ4_compress_generic: srcSize=%i, dstCapacity=%i", + srcSize, dstCapacity); + if ((U32)srcSize > (U32)LZ4_MAX_INPUT_SIZE) { return 0; } /* Unsupported srcSize, too large (or negative) */ + if (srcSize == 0) { /* src == NULL supported if srcSize == 0 */ + if (outputDirective != notLimited && dstCapacity <= 0) return 0; /* no output, can't write anything */ + DEBUGLOG(5, "Generating an empty block"); + assert(outputDirective == notLimited || dstCapacity >= 1); + assert(dst != NULL); + dst[0] = 0; + if (outputDirective == fillOutput) { + assert (inputConsumed != NULL); + *inputConsumed = 0; + } + return 1; + } + assert(src != NULL); + + return LZ4_compress_generic_validated(cctx, src, dst, srcSize, + inputConsumed, /* only written into if outputDirective == fillOutput */ + dstCapacity, outputDirective, + tableType, dictDirective, dictIssue, acceleration); +} + + +int LZ4_compress_fast_extState(void* state, const char* source, char* dest, int inputSize, int maxOutputSize, int acceleration) +{ + LZ4_stream_t_internal* const ctx = & LZ4_initStream(state, sizeof(LZ4_stream_t)) -> internal_donotuse; + assert(ctx != NULL); + if (acceleration < 1) acceleration = LZ4_ACCELERATION_DEFAULT; + if (acceleration > LZ4_ACCELERATION_MAX) acceleration = LZ4_ACCELERATION_MAX; if (maxOutputSize >= LZ4_compressBound(inputSize)) { - if (inputSize < LZ4_64Klimit) - return LZ4_compress_generic(state, source, dest, inputSize, 0, notLimited, byU16, noDict, noDictIssue, - acceleration); - else - return LZ4_compress_generic(state, source, dest, inputSize, 0, notLimited, LZ4_64bits() ? byU32 : byPtr, - noDict, noDictIssue, acceleration); + if (inputSize < LZ4_64Klimit) { + return LZ4_compress_generic(ctx, source, dest, inputSize, NULL, 0, notLimited, byU16, noDict, noDictIssue, acceleration); + } else { + const tableType_t tableType = ((sizeof(void*)==4) && ((uptrval)source > LZ4_DISTANCE_MAX)) ? byPtr : byU32; + return LZ4_compress_generic(ctx, source, dest, inputSize, NULL, 0, notLimited, tableType, noDict, noDictIssue, acceleration); + } } else { - if (inputSize < LZ4_64Klimit) - return LZ4_compress_generic(state, source, dest, inputSize, maxOutputSize, limitedOutput, byU16, noDict, - noDictIssue, acceleration); - else - return LZ4_compress_generic(state, source, dest, inputSize, maxOutputSize, limitedOutput, - LZ4_64bits() ? byU32 : byPtr, noDict, noDictIssue, acceleration); + if (inputSize < LZ4_64Klimit) { + return LZ4_compress_generic(ctx, source, dest, inputSize, NULL, maxOutputSize, limitedOutput, byU16, noDict, noDictIssue, acceleration); + } else { + const tableType_t tableType = ((sizeof(void*)==4) && ((uptrval)source > LZ4_DISTANCE_MAX)) ? byPtr : byU32; + return LZ4_compress_generic(ctx, source, dest, inputSize, NULL, maxOutputSize, limitedOutput, tableType, noDict, noDictIssue, acceleration); + } } } -int LZ4_compress_fast(const char *source, char *dest, int inputSize, int maxOutputSize, int acceleration) +/** + * LZ4_compress_fast_extState_fastReset() : + * A variant of LZ4_compress_fast_extState(). + * + * Using this variant avoids an expensive initialization step. It is only safe + * to call if the state buffer is known to be correctly initialized already + * (see comment in lz4.h on LZ4_resetStream_fast() for a definition of + * "correctly initialized"). + */ +int LZ4_compress_fast_extState_fastReset(void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration) { -#if (HEAPMODE) - void *ctxPtr = ALLOCATOR(1, sizeof(LZ4_stream_t)); /* malloc-calloc always properly aligned */ + LZ4_stream_t_internal* const ctx = &((LZ4_stream_t*)state)->internal_donotuse; + if (acceleration < 1) acceleration = LZ4_ACCELERATION_DEFAULT; + if (acceleration > LZ4_ACCELERATION_MAX) acceleration = LZ4_ACCELERATION_MAX; + assert(ctx != NULL); + + if (dstCapacity >= LZ4_compressBound(srcSize)) { + if (srcSize < LZ4_64Klimit) { + const tableType_t tableType = byU16; + LZ4_prepareTable(ctx, srcSize, tableType); + if (ctx->currentOffset) { + return LZ4_compress_generic(ctx, src, dst, srcSize, NULL, 0, notLimited, tableType, noDict, dictSmall, acceleration); + } else { + return LZ4_compress_generic(ctx, src, dst, srcSize, NULL, 0, notLimited, tableType, noDict, noDictIssue, acceleration); + } + } else { + const tableType_t tableType = ((sizeof(void*)==4) && ((uptrval)src > LZ4_DISTANCE_MAX)) ? byPtr : byU32; + LZ4_prepareTable(ctx, srcSize, tableType); + return LZ4_compress_generic(ctx, src, dst, srcSize, NULL, 0, notLimited, tableType, noDict, noDictIssue, acceleration); + } + } else { + if (srcSize < LZ4_64Klimit) { + const tableType_t tableType = byU16; + LZ4_prepareTable(ctx, srcSize, tableType); + if (ctx->currentOffset) { + return LZ4_compress_generic(ctx, src, dst, srcSize, NULL, dstCapacity, limitedOutput, tableType, noDict, dictSmall, acceleration); + } else { + return LZ4_compress_generic(ctx, src, dst, srcSize, NULL, dstCapacity, limitedOutput, tableType, noDict, noDictIssue, acceleration); + } + } else { + const tableType_t tableType = ((sizeof(void*)==4) && ((uptrval)src > LZ4_DISTANCE_MAX)) ? byPtr : byU32; + LZ4_prepareTable(ctx, srcSize, tableType); + return LZ4_compress_generic(ctx, src, dst, srcSize, NULL, dstCapacity, limitedOutput, tableType, noDict, noDictIssue, acceleration); + } + } +} + + +int LZ4_compress_fast(const char* src, char* dest, int srcSize, int dstCapacity, int acceleration) +{ + int result; +#if (LZ4_HEAPMODE) + LZ4_stream_t* const ctxPtr = (LZ4_stream_t*)ALLOC(sizeof(LZ4_stream_t)); /* malloc-calloc always properly aligned */ + if (ctxPtr == NULL) return 0; #else LZ4_stream_t ctx; - void *ctxPtr = &ctx; + LZ4_stream_t* const ctxPtr = &ctx; #endif + result = LZ4_compress_fast_extState(ctxPtr, src, dest, srcSize, dstCapacity, acceleration); - int result = LZ4_compress_fast_extState(ctxPtr, source, dest, inputSize, maxOutputSize, acceleration); - -#if (HEAPMODE) +#if (LZ4_HEAPMODE) FREEMEM(ctxPtr); #endif return result; } -int LZ4_compress_default(const char *source, char *dest, int inputSize, int maxOutputSize) + +int LZ4_compress_default(const char* src, char* dst, int srcSize, int dstCapacity) { - return LZ4_compress_fast(source, dest, inputSize, maxOutputSize, 1); + return LZ4_compress_fast(src, dst, srcSize, dstCapacity, 1); } -/* hidden debug function */ -/* strangely enough, gcc generates faster code when this function is uncommented, even if unused */ -int LZ4_compress_fast_force(const char *source, char *dest, int inputSize, int maxOutputSize, int acceleration) + +/* Note!: This function leaves the stream in an unclean/broken state! + * It is not safe to subsequently use the same state with a _fastReset() or + * _continue() call without resetting it. */ +static int LZ4_compress_destSize_extState_internal(LZ4_stream_t* state, const char* src, char* dst, int* srcSizePtr, int targetDstSize, int acceleration) { - LZ4_stream_t ctx; + void* const s = LZ4_initStream(state, sizeof (*state)); + assert(s != NULL); (void)s; - LZ4_resetStream(&ctx); - - if (inputSize < LZ4_64Klimit) - return LZ4_compress_generic(&ctx, source, dest, inputSize, maxOutputSize, limitedOutput, byU16, noDict, - noDictIssue, acceleration); - else - return LZ4_compress_generic(&ctx, source, dest, inputSize, maxOutputSize, limitedOutput, - LZ4_64bits() ? byU32 : byPtr, noDict, noDictIssue, acceleration); -} - -/******************************** - * destSize variant - ********************************/ - -static int LZ4_compress_destSize_generic(void *const ctx, const char *const src, char *const dst, int *const srcSizePtr, - const int targetDstSize, const tableType_t tableType) -{ - const BYTE *ip = (const BYTE *)src; - const BYTE *base = (const BYTE *)src; - const BYTE *lowLimit = (const BYTE *)src; - const BYTE *anchor = ip; - const BYTE *const iend = ip + *srcSizePtr; - const BYTE *const mflimit = iend - MFLIMIT; - const BYTE *const matchlimit = iend - LASTLITERALS; - - BYTE *op = (BYTE *)dst; - BYTE *const oend = op + targetDstSize; - BYTE *const oMaxLit = op + targetDstSize - 2 /* offset */ - 8 /* because 8+MINMATCH==MFLIMIT */ - 1 /* token */; - BYTE *const oMaxMatch = op + targetDstSize - (LASTLITERALS + 1 /* token */); - BYTE *const oMaxSeq = oMaxLit - 1 /* token */; - - U32 forwardH; - - /* Init conditions */ - if (targetDstSize < 1) - return 0; /* Impossible to store anything */ - if ((U32)*srcSizePtr > (U32)LZ4_MAX_INPUT_SIZE) - return 0; /* Unsupported input size, too large (or negative) */ - if ((tableType == byU16) && (*srcSizePtr >= LZ4_64Klimit)) - return 0; /* Size too large (not within 64K limit) */ - if (*srcSizePtr < LZ4_minLength) - goto _last_literals; /* Input too small, no compression (all literals) */ - - /* First Byte */ - *srcSizePtr = 0; - LZ4_putPosition(ip, ctx, tableType, base); - ip++; - forwardH = LZ4_hashPosition(ip, tableType); - - /* Main Loop */ - for (;;) { - const BYTE *match; - BYTE *token; - { - const BYTE *forwardIp = ip; - unsigned step = 1; - unsigned searchMatchNb = 1 << LZ4_skipTrigger; - - /* Find a match */ - do { - U32 h = forwardH; - ip = forwardIp; - forwardIp += step; - step = (searchMatchNb++ >> LZ4_skipTrigger); - - if (unlikely(forwardIp > mflimit)) - goto _last_literals; - - match = LZ4_getPositionOnHash(h, ctx, tableType, base); - forwardH = LZ4_hashPosition(forwardIp, tableType); - LZ4_putPositionOnHash(ip, h, ctx, tableType, base); - - } while (((tableType == byU16) ? 0 : (match + MAX_DISTANCE < ip)) || (LZ4_read32(match) != LZ4_read32(ip))); - } - - /* Catch up */ - while ((ip > anchor) && (match > lowLimit) && (unlikely(ip[-1] == match[-1]))) { - ip--; - match--; - } - - { - /* Encode Literal length */ - unsigned litLength = (unsigned)(ip - anchor); - token = op++; - if (op + ((litLength + 240) / 255) + litLength > oMaxLit) { - /* Not enough space for a last match */ - op--; - goto _last_literals; - } - if (litLength >= RUN_MASK) { - unsigned len = litLength - RUN_MASK; - *token = (RUN_MASK << ML_BITS); - for (; len >= 255; len -= 255) - *op++ = 255; - *op++ = (BYTE)len; - } else - *token = (BYTE)(litLength << ML_BITS); - - /* Copy Literals */ - LZ4_wildCopy(op, anchor, op + litLength); - op += litLength; - } - - _next_match: - /* Encode Offset */ - LZ4_writeLE16(op, (U16)(ip - match)); - op += 2; - - /* Encode MatchLength */ - { - size_t matchLength; - - matchLength = LZ4_count(ip + MINMATCH, match + MINMATCH, matchlimit); - - if (op + ((matchLength + 240) / 255) > oMaxMatch) { - /* Match description too long : reduce it */ - matchLength = (15 - 1) + (oMaxMatch - op) * 255; - } - /*printf("offset %5i, matchLength%5i \n", (int)(ip-match), matchLength + MINMATCH);*/ - ip += MINMATCH + matchLength; - - if (matchLength >= ML_MASK) { - *token += ML_MASK; - matchLength -= ML_MASK; - while (matchLength >= 255) { - matchLength -= 255; - *op++ = 255; - } - *op++ = (BYTE)matchLength; - } else - *token += (BYTE)(matchLength); - } - - anchor = ip; - - /* Test end of block */ - if (ip > mflimit) - break; - if (op > oMaxSeq) - break; - - /* Fill table */ - LZ4_putPosition(ip - 2, ctx, tableType, base); - - /* Test next position */ - match = LZ4_getPosition(ip, ctx, tableType, base); - LZ4_putPosition(ip, ctx, tableType, base); - if ((match + MAX_DISTANCE >= ip) && (LZ4_read32(match) == LZ4_read32(ip))) { - token = op++; - *token = 0; - goto _next_match; - } - - /* Prepare next loop */ - forwardH = LZ4_hashPosition(++ip, tableType); - } - -_last_literals: - /* Encode Last Literals */ - { - size_t lastRunSize = (size_t)(iend - anchor); - if (op + 1 /* token */ + ((lastRunSize + 240) / 255) /* litLength */ + lastRunSize /* literals */ > oend) { - /* adapt lastRunSize to fill 'dst' */ - lastRunSize = (oend - op) - 1; - lastRunSize -= (lastRunSize + 240) / 255; - } - ip = anchor + lastRunSize; - - if (lastRunSize >= RUN_MASK) { - size_t accumulator = lastRunSize - RUN_MASK; - *op++ = RUN_MASK << ML_BITS; - for (; accumulator >= 255; accumulator -= 255) - *op++ = 255; - *op++ = (BYTE)accumulator; - } else { - *op++ = (BYTE)(lastRunSize << ML_BITS); - } - memcpy(op, anchor, lastRunSize); - op += lastRunSize; - } - - /* End */ - *srcSizePtr = (int)(((const char *)ip) - src); - return (int)(((char *)op) - dst); -} - -static int LZ4_compress_destSize_extState(void *state, const char *src, char *dst, int *srcSizePtr, int targetDstSize) -{ - LZ4_resetStream((LZ4_stream_t *)state); - - if (targetDstSize >= LZ4_compressBound(*srcSizePtr)) /* compression success is guaranteed */ - { - return LZ4_compress_fast_extState(state, src, dst, *srcSizePtr, targetDstSize, 1); + if (targetDstSize >= LZ4_compressBound(*srcSizePtr)) { /* compression success is guaranteed */ + return LZ4_compress_fast_extState(state, src, dst, *srcSizePtr, targetDstSize, acceleration); } else { - if (*srcSizePtr < LZ4_64Klimit) - return LZ4_compress_destSize_generic(state, src, dst, srcSizePtr, targetDstSize, byU16); - else - return LZ4_compress_destSize_generic(state, src, dst, srcSizePtr, targetDstSize, - LZ4_64bits() ? byU32 : byPtr); - } + if (*srcSizePtr < LZ4_64Klimit) { + return LZ4_compress_generic(&state->internal_donotuse, src, dst, *srcSizePtr, srcSizePtr, targetDstSize, fillOutput, byU16, noDict, noDictIssue, acceleration); + } else { + tableType_t const addrMode = ((sizeof(void*)==4) && ((uptrval)src > LZ4_DISTANCE_MAX)) ? byPtr : byU32; + return LZ4_compress_generic(&state->internal_donotuse, src, dst, *srcSizePtr, srcSizePtr, targetDstSize, fillOutput, addrMode, noDict, noDictIssue, acceleration); + } } } -int LZ4_compress_destSize(const char *src, char *dst, int *srcSizePtr, int targetDstSize) +int LZ4_compress_destSize_extState(void* state, const char* src, char* dst, int* srcSizePtr, int targetDstSize, int acceleration) { -#if (HEAPMODE) - void *ctx = ALLOCATOR(1, sizeof(LZ4_stream_t)); /* malloc-calloc always properly aligned */ + int const r = LZ4_compress_destSize_extState_internal((LZ4_stream_t*)state, src, dst, srcSizePtr, targetDstSize, acceleration); + /* clean the state on exit */ + LZ4_initStream(state, sizeof (LZ4_stream_t)); + return r; +} + + +int LZ4_compress_destSize(const char* src, char* dst, int* srcSizePtr, int targetDstSize) +{ +#if (LZ4_HEAPMODE) + LZ4_stream_t* const ctx = (LZ4_stream_t*)ALLOC(sizeof(LZ4_stream_t)); /* malloc-calloc always properly aligned */ + if (ctx == NULL) return 0; #else LZ4_stream_t ctxBody; - void *ctx = &ctxBody; + LZ4_stream_t* const ctx = &ctxBody; #endif - int result = LZ4_compress_destSize_extState(ctx, src, dst, srcSizePtr, targetDstSize); + int result = LZ4_compress_destSize_extState_internal(ctx, src, dst, srcSizePtr, targetDstSize, 1); -#if (HEAPMODE) +#if (LZ4_HEAPMODE) FREEMEM(ctx); #endif return result; } -/******************************** - * Streaming functions - ********************************/ -LZ4_stream_t *LZ4_createStream(void) + +/*-****************************** +* Streaming functions +********************************/ + +#if !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) +LZ4_stream_t* LZ4_createStream(void) { - LZ4_stream_t *lz4s = (LZ4_stream_t *)ALLOCATOR(8, LZ4_STREAMSIZE_U64); - LZ4_STATIC_ASSERT( - LZ4_STREAMSIZE >= - sizeof(LZ4_stream_t_internal)); /* A compilation error here means LZ4_STREAMSIZE is not large enough */ - LZ4_resetStream(lz4s); + LZ4_stream_t* const lz4s = (LZ4_stream_t*)ALLOC(sizeof(LZ4_stream_t)); + LZ4_STATIC_ASSERT(sizeof(LZ4_stream_t) >= sizeof(LZ4_stream_t_internal)); + DEBUGLOG(4, "LZ4_createStream %p", lz4s); + if (lz4s == NULL) return NULL; + LZ4_initStream(lz4s, sizeof(*lz4s)); return lz4s; } +#endif -void LZ4_resetStream(LZ4_stream_t *LZ4_stream) { MEM_INIT(LZ4_stream, 0, sizeof(LZ4_stream_t)); } - -int LZ4_freeStream(LZ4_stream_t *LZ4_stream) +static size_t LZ4_stream_t_alignment(void) { +#if LZ4_ALIGN_TEST + typedef struct { char c; LZ4_stream_t t; } t_a; + return sizeof(t_a) - sizeof(LZ4_stream_t); +#else + return 1; /* effectively disabled */ +#endif +} + +LZ4_stream_t* LZ4_initStream (void* buffer, size_t size) +{ + DEBUGLOG(5, "LZ4_initStream"); + if (buffer == NULL) { return NULL; } + if (size < sizeof(LZ4_stream_t)) { return NULL; } + if (!LZ4_isAligned(buffer, LZ4_stream_t_alignment())) return NULL; + MEM_INIT(buffer, 0, sizeof(LZ4_stream_t_internal)); + return (LZ4_stream_t*)buffer; +} + +/* resetStream is now deprecated, + * prefer initStream() which is more general */ +void LZ4_resetStream (LZ4_stream_t* LZ4_stream) +{ + DEBUGLOG(5, "LZ4_resetStream (ctx:%p)", LZ4_stream); + MEM_INIT(LZ4_stream, 0, sizeof(LZ4_stream_t_internal)); +} + +void LZ4_resetStream_fast(LZ4_stream_t* ctx) { + LZ4_prepareTable(&(ctx->internal_donotuse), 0, byU32); +} + +#if !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) +int LZ4_freeStream (LZ4_stream_t* LZ4_stream) +{ + if (!LZ4_stream) return 0; /* support free on NULL */ + DEBUGLOG(5, "LZ4_freeStream %p", LZ4_stream); FREEMEM(LZ4_stream); return (0); } +#endif -#define HASH_UNIT sizeof(size_t) -int LZ4_loadDict(LZ4_stream_t *LZ4_dict, const char *dictionary, int dictSize) + +#define HASH_UNIT sizeof(reg_t) +int LZ4_loadDict (LZ4_stream_t* LZ4_dict, const char* dictionary, int dictSize) { - LZ4_stream_t_internal *dict = (LZ4_stream_t_internal *)LZ4_dict; - const BYTE *p = (const BYTE *)dictionary; - const BYTE *const dictEnd = p + dictSize; - const BYTE *base; + LZ4_stream_t_internal* const dict = &LZ4_dict->internal_donotuse; + const tableType_t tableType = byU32; + const BYTE* p = (const BYTE*)dictionary; + const BYTE* const dictEnd = p + dictSize; + U32 idx32; - if ((dict->initCheck) || (dict->currentOffset > 1 GB)) /* Uninitialized structure, or reuse overflow */ - LZ4_resetStream(LZ4_dict); + DEBUGLOG(4, "LZ4_loadDict (%i bytes from %p into %p)", dictSize, dictionary, LZ4_dict); + + /* It's necessary to reset the context, + * and not just continue it with prepareTable() + * to avoid any risk of generating overflowing matchIndex + * when compressing using this dictionary */ + LZ4_resetStream(LZ4_dict); + + /* We always increment the offset by 64 KB, since, if the dict is longer, + * we truncate it to the last 64k, and if it's shorter, we still want to + * advance by a whole window length so we can provide the guarantee that + * there are only valid offsets in the window, which allows an optimization + * in LZ4_compress_fast_continue() where it uses noDictIssue even when the + * dictionary isn't a full 64k. */ + dict->currentOffset += 64 KB; if (dictSize < (int)HASH_UNIT) { - dict->dictionary = NULL; - dict->dictSize = 0; return 0; } - if ((dictEnd - p) > 64 KB) - p = dictEnd - 64 KB; - dict->currentOffset += 64 KB; - base = p - dict->currentOffset; + if ((dictEnd - p) > 64 KB) p = dictEnd - 64 KB; dict->dictionary = p; dict->dictSize = (U32)(dictEnd - p); - dict->currentOffset += dict->dictSize; + dict->tableType = (U32)tableType; + idx32 = dict->currentOffset - dict->dictSize; - while (p <= dictEnd - HASH_UNIT) { - LZ4_putPosition(p, dict->hashTable, byU32, base); - p += 3; + while (p <= dictEnd-HASH_UNIT) { + U32 const h = LZ4_hashPosition(p, tableType); + LZ4_putIndexOnHash(idx32, h, dict->hashTable, tableType); + p+=3; idx32+=3; } - return dict->dictSize; + return (int)dict->dictSize; } -static void LZ4_renormDictT(LZ4_stream_t_internal *LZ4_dict, const BYTE *src) +void LZ4_attach_dictionary(LZ4_stream_t* workingStream, const LZ4_stream_t* dictionaryStream) { - if ((LZ4_dict->currentOffset > 0x80000000) || - ((size_t)LZ4_dict->currentOffset > (size_t)src)) /* address space overflow */ - { + const LZ4_stream_t_internal* dictCtx = (dictionaryStream == NULL) ? NULL : + &(dictionaryStream->internal_donotuse); + + DEBUGLOG(4, "LZ4_attach_dictionary (%p, %p, size %u)", + workingStream, dictionaryStream, + dictCtx != NULL ? dictCtx->dictSize : 0); + + if (dictCtx != NULL) { + /* If the current offset is zero, we will never look in the + * external dictionary context, since there is no value a table + * entry can take that indicate a miss. In that case, we need + * to bump the offset to something non-zero. + */ + if (workingStream->internal_donotuse.currentOffset == 0) { + workingStream->internal_donotuse.currentOffset = 64 KB; + } + + /* Don't actually attach an empty dictionary. + */ + if (dictCtx->dictSize == 0) { + dictCtx = NULL; + } + } + workingStream->internal_donotuse.dictCtx = dictCtx; +} + + +static void LZ4_renormDictT(LZ4_stream_t_internal* LZ4_dict, int nextSize) +{ + assert(nextSize >= 0); + if (LZ4_dict->currentOffset + (unsigned)nextSize > 0x80000000) { /* potential ptrdiff_t overflow (32-bits mode) */ /* rescale hash table */ - U32 delta = LZ4_dict->currentOffset - 64 KB; - const BYTE *dictEnd = LZ4_dict->dictionary + LZ4_dict->dictSize; + U32 const delta = LZ4_dict->currentOffset - 64 KB; + const BYTE* dictEnd = LZ4_dict->dictionary + LZ4_dict->dictSize; int i; - for (i = 0; i < HASH_SIZE_U32; i++) { - if (LZ4_dict->hashTable[i] < delta) - LZ4_dict->hashTable[i] = 0; - else - LZ4_dict->hashTable[i] -= delta; + DEBUGLOG(4, "LZ4_renormDictT"); + for (i=0; ihashTable[i] < delta) LZ4_dict->hashTable[i]=0; + else LZ4_dict->hashTable[i] -= delta; } LZ4_dict->currentOffset = 64 KB; - if (LZ4_dict->dictSize > 64 KB) - LZ4_dict->dictSize = 64 KB; + if (LZ4_dict->dictSize > 64 KB) LZ4_dict->dictSize = 64 KB; LZ4_dict->dictionary = dictEnd - LZ4_dict->dictSize; } } -int LZ4_compress_fast_continue(LZ4_stream_t *LZ4_stream, const char *source, char *dest, int inputSize, - int maxOutputSize, int acceleration) -{ - LZ4_stream_t_internal *streamPtr = (LZ4_stream_t_internal *)LZ4_stream; - const BYTE *const dictEnd = streamPtr->dictionary + streamPtr->dictSize; - const BYTE *smallest = (const BYTE *)source; - if (streamPtr->initCheck) - return 0; /* Uninitialized structure detected */ - if ((streamPtr->dictSize > 0) && (smallest > dictEnd)) - smallest = dictEnd; - LZ4_renormDictT(streamPtr, smallest); - if (acceleration < 1) - acceleration = ACCELERATION_DEFAULT; +int LZ4_compress_fast_continue (LZ4_stream_t* LZ4_stream, + const char* source, char* dest, + int inputSize, int maxOutputSize, + int acceleration) +{ + const tableType_t tableType = byU32; + LZ4_stream_t_internal* const streamPtr = &LZ4_stream->internal_donotuse; + const char* dictEnd = streamPtr->dictSize ? (const char*)streamPtr->dictionary + streamPtr->dictSize : NULL; + + DEBUGLOG(5, "LZ4_compress_fast_continue (inputSize=%i, dictSize=%u)", inputSize, streamPtr->dictSize); + + LZ4_renormDictT(streamPtr, inputSize); /* fix index overflow */ + if (acceleration < 1) acceleration = LZ4_ACCELERATION_DEFAULT; + if (acceleration > LZ4_ACCELERATION_MAX) acceleration = LZ4_ACCELERATION_MAX; + + /* invalidate tiny dictionaries */ + if ( (streamPtr->dictSize < 4) /* tiny dictionary : not enough for a hash */ + && (dictEnd != source) /* prefix mode */ + && (inputSize > 0) /* tolerance : don't lose history, in case next invocation would use prefix mode */ + && (streamPtr->dictCtx == NULL) /* usingDictCtx */ + ) { + DEBUGLOG(5, "LZ4_compress_fast_continue: dictSize(%u) at addr:%p is too small", streamPtr->dictSize, streamPtr->dictionary); + /* remove dictionary existence from history, to employ faster prefix mode */ + streamPtr->dictSize = 0; + streamPtr->dictionary = (const BYTE*)source; + dictEnd = source; + } /* Check overlapping input/dictionary space */ - { - const BYTE *sourceEnd = (const BYTE *)source + inputSize; - if ((sourceEnd > streamPtr->dictionary) && (sourceEnd < dictEnd)) { + { const char* const sourceEnd = source + inputSize; + if ((sourceEnd > (const char*)streamPtr->dictionary) && (sourceEnd < dictEnd)) { streamPtr->dictSize = (U32)(dictEnd - sourceEnd); - if (streamPtr->dictSize > 64 KB) - streamPtr->dictSize = 64 KB; - if (streamPtr->dictSize < 4) - streamPtr->dictSize = 0; - streamPtr->dictionary = dictEnd - streamPtr->dictSize; + if (streamPtr->dictSize > 64 KB) streamPtr->dictSize = 64 KB; + if (streamPtr->dictSize < 4) streamPtr->dictSize = 0; + streamPtr->dictionary = (const BYTE*)dictEnd - streamPtr->dictSize; } } /* prefix mode : source data follows dictionary */ - if (dictEnd == (const BYTE *)source) { - int result; + if (dictEnd == source) { if ((streamPtr->dictSize < 64 KB) && (streamPtr->dictSize < streamPtr->currentOffset)) - result = LZ4_compress_generic(LZ4_stream, source, dest, inputSize, maxOutputSize, limitedOutput, byU32, - withPrefix64k, dictSmall, acceleration); + return LZ4_compress_generic(streamPtr, source, dest, inputSize, NULL, maxOutputSize, limitedOutput, tableType, withPrefix64k, dictSmall, acceleration); else - result = LZ4_compress_generic(LZ4_stream, source, dest, inputSize, maxOutputSize, limitedOutput, byU32, - withPrefix64k, noDictIssue, acceleration); - streamPtr->dictSize += (U32)inputSize; - streamPtr->currentOffset += (U32)inputSize; - return result; + return LZ4_compress_generic(streamPtr, source, dest, inputSize, NULL, maxOutputSize, limitedOutput, tableType, withPrefix64k, noDictIssue, acceleration); } /* external dictionary mode */ - { - int result; - if ((streamPtr->dictSize < 64 KB) && (streamPtr->dictSize < streamPtr->currentOffset)) - result = LZ4_compress_generic(LZ4_stream, source, dest, inputSize, maxOutputSize, limitedOutput, byU32, - usingExtDict, dictSmall, acceleration); - else - result = LZ4_compress_generic(LZ4_stream, source, dest, inputSize, maxOutputSize, limitedOutput, byU32, - usingExtDict, noDictIssue, acceleration); - streamPtr->dictionary = (const BYTE *)source; + { int result; + if (streamPtr->dictCtx) { + /* We depend here on the fact that dictCtx'es (produced by + * LZ4_loadDict) guarantee that their tables contain no references + * to offsets between dictCtx->currentOffset - 64 KB and + * dictCtx->currentOffset - dictCtx->dictSize. This makes it safe + * to use noDictIssue even when the dict isn't a full 64 KB. + */ + if (inputSize > 4 KB) { + /* For compressing large blobs, it is faster to pay the setup + * cost to copy the dictionary's tables into the active context, + * so that the compression loop is only looking into one table. + */ + LZ4_memcpy(streamPtr, streamPtr->dictCtx, sizeof(*streamPtr)); + result = LZ4_compress_generic(streamPtr, source, dest, inputSize, NULL, maxOutputSize, limitedOutput, tableType, usingExtDict, noDictIssue, acceleration); + } else { + result = LZ4_compress_generic(streamPtr, source, dest, inputSize, NULL, maxOutputSize, limitedOutput, tableType, usingDictCtx, noDictIssue, acceleration); + } + } else { /* small data <= 4 KB */ + if ((streamPtr->dictSize < 64 KB) && (streamPtr->dictSize < streamPtr->currentOffset)) { + result = LZ4_compress_generic(streamPtr, source, dest, inputSize, NULL, maxOutputSize, limitedOutput, tableType, usingExtDict, dictSmall, acceleration); + } else { + result = LZ4_compress_generic(streamPtr, source, dest, inputSize, NULL, maxOutputSize, limitedOutput, tableType, usingExtDict, noDictIssue, acceleration); + } + } + streamPtr->dictionary = (const BYTE*)source; streamPtr->dictSize = (U32)inputSize; - streamPtr->currentOffset += (U32)inputSize; return result; } } -/* Hidden debug function, to force external dictionary mode */ -int LZ4_compress_forceExtDict(LZ4_stream_t *LZ4_dict, const char *source, char *dest, int inputSize) + +/* Hidden debug function, to force-test external dictionary mode */ +int LZ4_compress_forceExtDict (LZ4_stream_t* LZ4_dict, const char* source, char* dest, int srcSize) { - LZ4_stream_t_internal *streamPtr = (LZ4_stream_t_internal *)LZ4_dict; + LZ4_stream_t_internal* const streamPtr = &LZ4_dict->internal_donotuse; int result; - const BYTE *const dictEnd = streamPtr->dictionary + streamPtr->dictSize; - const BYTE *smallest = dictEnd; - if (smallest > (const BYTE *)source) - smallest = (const BYTE *)source; - LZ4_renormDictT((LZ4_stream_t_internal *)LZ4_dict, smallest); + LZ4_renormDictT(streamPtr, srcSize); - result = - LZ4_compress_generic(LZ4_dict, source, dest, inputSize, 0, notLimited, byU32, usingExtDict, noDictIssue, 1); + if ((streamPtr->dictSize < 64 KB) && (streamPtr->dictSize < streamPtr->currentOffset)) { + result = LZ4_compress_generic(streamPtr, source, dest, srcSize, NULL, 0, notLimited, byU32, usingExtDict, dictSmall, 1); + } else { + result = LZ4_compress_generic(streamPtr, source, dest, srcSize, NULL, 0, notLimited, byU32, usingExtDict, noDictIssue, 1); + } - streamPtr->dictionary = (const BYTE *)source; - streamPtr->dictSize = (U32)inputSize; - streamPtr->currentOffset += (U32)inputSize; + streamPtr->dictionary = (const BYTE*)source; + streamPtr->dictSize = (U32)srcSize; return result; } -int LZ4_saveDict(LZ4_stream_t *LZ4_dict, char *safeBuffer, int dictSize) + +/*! LZ4_saveDict() : + * If previously compressed data block is not guaranteed to remain available at its memory location, + * save it into a safer place (char* safeBuffer). + * Note : no need to call LZ4_loadDict() afterwards, dictionary is immediately usable, + * one can therefore call LZ4_compress_fast_continue() right after. + * @return : saved dictionary size in bytes (necessarily <= dictSize), or 0 if error. + */ +int LZ4_saveDict (LZ4_stream_t* LZ4_dict, char* safeBuffer, int dictSize) { - LZ4_stream_t_internal *dict = (LZ4_stream_t_internal *)LZ4_dict; - const BYTE *previousDictEnd = dict->dictionary + dict->dictSize; + LZ4_stream_t_internal* const dict = &LZ4_dict->internal_donotuse; - if ((U32)dictSize > 64 KB) - dictSize = 64 KB; /* useless to define a dictionary > 64 KB */ - if ((U32)dictSize > dict->dictSize) - dictSize = dict->dictSize; + DEBUGLOG(5, "LZ4_saveDict : dictSize=%i, safeBuffer=%p", dictSize, safeBuffer); - memmove(safeBuffer, previousDictEnd - dictSize, dictSize); + if ((U32)dictSize > 64 KB) { dictSize = 64 KB; } /* useless to define a dictionary > 64 KB */ + if ((U32)dictSize > dict->dictSize) { dictSize = (int)dict->dictSize; } - dict->dictionary = (const BYTE *)safeBuffer; + if (safeBuffer == NULL) assert(dictSize == 0); + if (dictSize > 0) { + const BYTE* const previousDictEnd = dict->dictionary + dict->dictSize; + assert(dict->dictionary); + LZ4_memmove(safeBuffer, previousDictEnd - dictSize, (size_t)dictSize); + } + + dict->dictionary = (const BYTE*)safeBuffer; dict->dictSize = (U32)dictSize; return dictSize; } -/******************************* + + +/*-******************************* * Decompression functions - *******************************/ -/* - * This generic decompression function cover all use cases. - * It shall be instantiated several times, using different sets of directives - * Note that it is essential this generic function is really inlined, - * in order to remove useless branches during compilation optimization. - */ -FORCE_INLINE int -LZ4_decompress_generic(const char *const source, char *const dest, int inputSize, - int outputSize, /* If endOnInput==endOnInputSize, this value is the max size of Output Buffer. */ + ********************************/ - int endOnInput, /* endOnOutputSize, endOnInputSize */ - int partialDecoding, /* full, partial */ - int targetOutputSize, /* only used if partialDecoding==partial */ - int dict, /* noDict, withPrefix64k, usingExtDict */ - const BYTE *const lowPrefix, /* == dest if dict == noDict */ - const BYTE *const dictStart, /* only if dict==usingExtDict */ - const size_t dictSize /* note : = 0 if noDict */ -) +typedef enum { decode_full_block = 0, partial_decode = 1 } earlyEnd_directive; + +#undef MIN +#define MIN(a,b) ( (a) < (b) ? (a) : (b) ) + + +/* variant for decompress_unsafe() + * does not know end of input + * presumes input is well formed + * note : will consume at least one byte */ +static size_t read_long_length_no_check(const BYTE** pp) { - /* Local Variables */ - const BYTE *ip = (const BYTE *)source; - const BYTE *const iend = ip + inputSize; + size_t b, l = 0; + do { b = **pp; (*pp)++; l += b; } while (b==255); + DEBUGLOG(6, "read_long_length_no_check: +length=%zu using %zu input bytes", l, l/255 + 1) + return l; +} - BYTE *op = (BYTE *)dest; - BYTE *const oend = op + outputSize; - BYTE *cpy; - BYTE *oexit = op + targetOutputSize; - const BYTE *const lowLimit = lowPrefix - dictSize; +/* core decoder variant for LZ4_decompress_fast*() + * for legacy support only : these entry points are deprecated. + * - Presumes input is correctly formed (no defense vs malformed inputs) + * - Does not know input size (presume input buffer is "large enough") + * - Decompress a full block (only) + * @return : nb of bytes read from input. + * Note : this variant is not optimized for speed, just for maintenance. + * the goal is to remove support of decompress_fast*() variants by v2.0 +**/ +LZ4_FORCE_INLINE int +LZ4_decompress_unsafe_generic( + const BYTE* const istart, + BYTE* const ostart, + int decompressedSize, - const BYTE *const dictEnd = (const BYTE *)dictStart + dictSize; - const size_t dec32table[] = {4, 1, 2, 1, 4, 4, 4, 4}; - const size_t dec64table[] = {0, 0, 0, (size_t)-1, 0, 1, 2, 3}; + size_t prefixSize, + const BYTE* const dictStart, /* only if dict==usingExtDict */ + const size_t dictSize /* note: =0 if dictStart==NULL */ + ) +{ + const BYTE* ip = istart; + BYTE* op = (BYTE*)ostart; + BYTE* const oend = ostart + decompressedSize; + const BYTE* const prefixStart = ostart - prefixSize; - const int safeDecode = (endOnInput == endOnInputSize); - const int checkOffset = ((safeDecode) && (dictSize < (int)(64 KB))); + DEBUGLOG(5, "LZ4_decompress_unsafe_generic"); + if (dictStart == NULL) assert(dictSize == 0); - /* Special cases */ - if ((partialDecoding) && (oexit > oend - MFLIMIT)) - oexit = oend - MFLIMIT; /* targetOutputSize too high => decode everything */ - if ((endOnInput) && (unlikely(outputSize == 0))) - return ((inputSize == 1) && (*ip == 0)) ? 0 : -1; /* Empty output buffer */ - if ((!endOnInput) && (unlikely(outputSize == 0))) - return (*ip == 0 ? 1 : -1); - - /* Main Loop */ while (1) { + /* start new sequence */ + unsigned token = *ip++; + + /* literals */ + { size_t ll = token >> ML_BITS; + if (ll==15) { + /* long literal length */ + ll += read_long_length_no_check(&ip); + } + if ((size_t)(oend-op) < ll) return -1; /* output buffer overflow */ + LZ4_memmove(op, ip, ll); /* support in-place decompression */ + op += ll; + ip += ll; + if ((size_t)(oend-op) < MFLIMIT) { + if (op==oend) break; /* end of block */ + DEBUGLOG(5, "invalid: literals end at distance %zi from end of block", oend-op); + /* incorrect end of block : + * last match must start at least MFLIMIT==12 bytes before end of output block */ + return -1; + } } + + /* match */ + { size_t ml = token & 15; + size_t const offset = LZ4_readLE16(ip); + ip+=2; + + if (ml==15) { + /* long literal length */ + ml += read_long_length_no_check(&ip); + } + ml += MINMATCH; + + if ((size_t)(oend-op) < ml) return -1; /* output buffer overflow */ + + { const BYTE* match = op - offset; + + /* out of range */ + if (offset > (size_t)(op - prefixStart) + dictSize) { + DEBUGLOG(6, "offset out of range"); + return -1; + } + + /* check special case : extDict */ + if (offset > (size_t)(op - prefixStart)) { + /* extDict scenario */ + const BYTE* const dictEnd = dictStart + dictSize; + const BYTE* extMatch = dictEnd - (offset - (size_t)(op-prefixStart)); + size_t const extml = (size_t)(dictEnd - extMatch); + if (extml > ml) { + /* match entirely within extDict */ + LZ4_memmove(op, extMatch, ml); + op += ml; + ml = 0; + } else { + /* match split between extDict & prefix */ + LZ4_memmove(op, extMatch, extml); + op += extml; + ml -= extml; + } + match = prefixStart; + } + + /* match copy - slow variant, supporting overlap copy */ + { size_t u; + for (u=0; u= ipmax before start of loop. Returns initial_error if so. + * @error (output) - error code. Must be set to 0 before call. +**/ +typedef size_t Rvl_t; +static const Rvl_t rvl_error = (Rvl_t)(-1); +LZ4_FORCE_INLINE Rvl_t +read_variable_length(const BYTE** ip, const BYTE* ilimit, + int initial_check) +{ + Rvl_t s, length = 0; + assert(ip != NULL); + assert(*ip != NULL); + assert(ilimit != NULL); + if (initial_check && unlikely((*ip) >= ilimit)) { /* read limit reached */ + return rvl_error; + } + s = **ip; + (*ip)++; + length += s; + if (unlikely((*ip) > ilimit)) { /* read limit reached */ + return rvl_error; + } + /* accumulator overflow detection (32-bit mode only) */ + if ((sizeof(length) < 8) && unlikely(length > ((Rvl_t)(-1)/2)) ) { + return rvl_error; + } + if (likely(s != 255)) return length; + do { + s = **ip; + (*ip)++; + length += s; + if (unlikely((*ip) > ilimit)) { /* read limit reached */ + return rvl_error; + } + /* accumulator overflow detection (32-bit mode only) */ + if ((sizeof(length) < 8) && unlikely(length > ((Rvl_t)(-1)/2)) ) { + return rvl_error; + } + } while (s == 255); + + return length; +} + +/*! LZ4_decompress_generic() : + * This generic decompression function covers all use cases. + * It shall be instantiated several times, using different sets of directives. + * Note that it is important for performance that this function really get inlined, + * in order to remove useless branches during compilation optimization. + */ +LZ4_FORCE_INLINE int +LZ4_decompress_generic( + const char* const src, + char* const dst, + int srcSize, + int outputSize, /* If endOnInput==endOnInputSize, this value is `dstCapacity` */ + + earlyEnd_directive partialDecoding, /* full, partial */ + dict_directive dict, /* noDict, withPrefix64k, usingExtDict */ + const BYTE* const lowPrefix, /* always <= dst, == dst when no prefix */ + const BYTE* const dictStart, /* only if dict==usingExtDict */ + const size_t dictSize /* note : = 0 if noDict */ + ) +{ + if ((src == NULL) || (outputSize < 0)) { return -1; } + + { const BYTE* ip = (const BYTE*) src; + const BYTE* const iend = ip + srcSize; + + BYTE* op = (BYTE*) dst; + BYTE* const oend = op + outputSize; + BYTE* cpy; + + const BYTE* const dictEnd = (dictStart == NULL) ? NULL : dictStart + dictSize; + + const int checkOffset = (dictSize < (int)(64 KB)); + + + /* Set up the "end" pointers for the shortcut. */ + const BYTE* const shortiend = iend - 14 /*maxLL*/ - 2 /*offset*/; + const BYTE* const shortoend = oend - 14 /*maxLL*/ - 18 /*maxML*/; + + const BYTE* match; + size_t offset; unsigned token; size_t length; - const BYTE *match; - /* get literal length */ - token = *ip++; - if ((length = (token >> ML_BITS)) == RUN_MASK) { - unsigned s; - do { - s = *ip++; - length += s; - } while (likely((endOnInput) ? ip < iend - RUN_MASK : 1) && (s == 255)); - if ((safeDecode) && unlikely((size_t)(op + length) < (size_t)(op))) - goto _output_error; /* overflow detection */ - if ((safeDecode) && unlikely((size_t)(ip + length) < (size_t)(ip))) - goto _output_error; /* overflow detection */ + + DEBUGLOG(5, "LZ4_decompress_generic (srcSize:%i, dstSize:%i)", srcSize, outputSize); + + /* Special cases */ + assert(lowPrefix <= op); + if (unlikely(outputSize==0)) { + /* Empty output buffer */ + if (partialDecoding) return 0; + return ((srcSize==1) && (*ip==0)) ? 0 : -1; + } + if (unlikely(srcSize==0)) { return -1; } + + /* LZ4_FAST_DEC_LOOP: + * designed for modern OoO performance cpus, + * where copying reliably 32-bytes is preferable to an unpredictable branch. + * note : fast loop may show a regression for some client arm chips. */ +#if LZ4_FAST_DEC_LOOP + if ((oend - op) < FASTLOOP_SAFE_DISTANCE) { + DEBUGLOG(6, "skip fast decode loop"); + goto safe_decode; } - /* copy literals */ - cpy = op + length; - if (((endOnInput) && - ((cpy > (partialDecoding ? oexit : oend - MFLIMIT)) || (ip + length > iend - (2 + 1 + LASTLITERALS)))) || - ((!endOnInput) && (cpy > oend - COPYLENGTH))) { - if (partialDecoding) { - if (cpy > oend) - goto _output_error; /* Error : write attempt beyond end of output buffer */ - if ((endOnInput) && (ip + length > iend)) - goto _output_error; /* Error : read attempt beyond end of input buffer */ - } else { - if ((!endOnInput) && (cpy != oend)) - goto _output_error; /* Error : block decoding must stop exactly there */ - if ((endOnInput) && ((ip + length != iend) || (cpy > oend))) - goto _output_error; /* Error : input must be consumed */ - } - memcpy(op, ip, length); - ip += length; - op += length; - break; /* Necessarily EOF, due to parsing restrictions */ - } - LZ4_wildCopy(op, ip, cpy); - ip += length; - op = cpy; + /* Fast loop : decode sequences as long as output < oend-FASTLOOP_SAFE_DISTANCE */ + DEBUGLOG(6, "using fast decode loop"); + while (1) { + /* Main fastloop assertion: We can always wildcopy FASTLOOP_SAFE_DISTANCE */ + assert(oend - op >= FASTLOOP_SAFE_DISTANCE); + assert(ip < iend); + token = *ip++; + length = token >> ML_BITS; /* literal length */ - /* get offset */ - match = cpy - LZ4_readLE16(ip); - ip += 2; - if ((checkOffset) && (unlikely(match < lowLimit))) - goto _output_error; /* Error : offset outside destination buffer */ - - /* get matchlength */ - length = token & ML_MASK; - if (length == ML_MASK) { - unsigned s; - do { - if ((endOnInput) && (ip > iend - LASTLITERALS)) + /* decode literal length */ + if (length == RUN_MASK) { + size_t const addl = read_variable_length(&ip, iend-RUN_MASK, 1); + if (addl == rvl_error) { + DEBUGLOG(6, "error reading long literal length"); goto _output_error; - s = *ip++; - length += s; - } while (s == 255); - if ((safeDecode) && unlikely((size_t)(op + length) < (size_t)op)) - goto _output_error; /* overflow detection */ - } - length += MINMATCH; - - /* check external dictionary */ - if ((dict == usingExtDict) && (match < lowPrefix)) { - if (unlikely(op + length > oend - LASTLITERALS)) - goto _output_error; /* doesn't respect parsing restriction */ - - if (length <= (size_t)(lowPrefix - match)) { - /* match can be copied as a single segment from external dictionary */ - match = dictEnd - (lowPrefix - match); - memmove(op, match, length); - op += length; - } else { - /* match encompass external dictionary and current segment */ - size_t copySize = (size_t)(lowPrefix - match); - memcpy(op, dictEnd - copySize, copySize); - op += copySize; - copySize = length - copySize; - if (copySize > (size_t)(op - lowPrefix)) /* overlap within current segment */ - { - BYTE *const endOfMatch = op + copySize; - const BYTE *copyFrom = lowPrefix; - while (op < endOfMatch) - *op++ = *copyFrom++; - } else { - memcpy(op, lowPrefix, copySize); - op += copySize; } + length += addl; + if (unlikely((uptrval)(op)+length<(uptrval)(op))) { goto _output_error; } /* overflow detection */ + if (unlikely((uptrval)(ip)+length<(uptrval)(ip))) { goto _output_error; } /* overflow detection */ + + /* copy literals */ + LZ4_STATIC_ASSERT(MFLIMIT >= WILDCOPYLENGTH); + if ((op+length>oend-32) || (ip+length>iend-32)) { goto safe_literal_copy; } + LZ4_wildCopy32(op, ip, op+length); + ip += length; op += length; + } else if (ip <= iend-(16 + 1/*max lit + offset + nextToken*/)) { + /* We don't need to check oend, since we check it once for each loop below */ + DEBUGLOG(7, "copy %u bytes in a 16-bytes stripe", (unsigned)length); + /* Literals can only be <= 14, but hope compilers optimize better when copy by a register size */ + LZ4_memcpy(op, ip, 16); + ip += length; op += length; + } else { + goto safe_literal_copy; } - continue; + + /* get offset */ + offset = LZ4_readLE16(ip); ip+=2; + DEBUGLOG(6, " offset = %zu", offset); + match = op - offset; + assert(match <= op); /* overflow check */ + + /* get matchlength */ + length = token & ML_MASK; + + if (length == ML_MASK) { + size_t const addl = read_variable_length(&ip, iend - LASTLITERALS + 1, 0); + if (addl == rvl_error) { + DEBUGLOG(6, "error reading long match length"); + goto _output_error; + } + length += addl; + length += MINMATCH; + if (unlikely((uptrval)(op)+length<(uptrval)op)) { goto _output_error; } /* overflow detection */ + if (op + length >= oend - FASTLOOP_SAFE_DISTANCE) { + goto safe_match_copy; + } + } else { + length += MINMATCH; + if (op + length >= oend - FASTLOOP_SAFE_DISTANCE) { + goto safe_match_copy; + } + + /* Fastpath check: skip LZ4_wildCopy32 when true */ + if ((dict == withPrefix64k) || (match >= lowPrefix)) { + if (offset >= 8) { + assert(match >= lowPrefix); + assert(match <= op); + assert(op + 18 <= oend); + + LZ4_memcpy(op, match, 8); + LZ4_memcpy(op+8, match+8, 8); + LZ4_memcpy(op+16, match+16, 2); + op += length; + continue; + } } } + + if ( checkOffset && (unlikely(match + dictSize < lowPrefix)) ) { + DEBUGLOG(6, "Error : pos=%zi, offset=%zi => outside buffers", op-lowPrefix, op-match); + goto _output_error; + } + /* match starting within external dictionary */ + if ((dict==usingExtDict) && (match < lowPrefix)) { + assert(dictEnd != NULL); + if (unlikely(op+length > oend-LASTLITERALS)) { + if (partialDecoding) { + DEBUGLOG(7, "partialDecoding: dictionary match, close to dstEnd"); + length = MIN(length, (size_t)(oend-op)); + } else { + DEBUGLOG(6, "end-of-block condition violated") + goto _output_error; + } } + + if (length <= (size_t)(lowPrefix-match)) { + /* match fits entirely within external dictionary : just copy */ + LZ4_memmove(op, dictEnd - (lowPrefix-match), length); + op += length; + } else { + /* match stretches into both external dictionary and current block */ + size_t const copySize = (size_t)(lowPrefix - match); + size_t const restSize = length - copySize; + LZ4_memcpy(op, dictEnd - copySize, copySize); + op += copySize; + if (restSize > (size_t)(op - lowPrefix)) { /* overlap copy */ + BYTE* const endOfMatch = op + restSize; + const BYTE* copyFrom = lowPrefix; + while (op < endOfMatch) { *op++ = *copyFrom++; } + } else { + LZ4_memcpy(op, lowPrefix, restSize); + op += restSize; + } } + continue; + } + + /* copy match within block */ + cpy = op + length; + + assert((op <= oend) && (oend-op >= 32)); + if (unlikely(offset<16)) { + LZ4_memcpy_using_offset(op, match, cpy, offset); + } else { + LZ4_wildCopy32(op, match, cpy); + } + + op = cpy; /* wildcopy correction */ + } + safe_decode: +#endif + + /* Main Loop : decode remaining sequences where output < FASTLOOP_SAFE_DISTANCE */ + DEBUGLOG(6, "using safe decode loop"); + while (1) { + assert(ip < iend); + token = *ip++; + length = token >> ML_BITS; /* literal length */ + + /* A two-stage shortcut for the most common case: + * 1) If the literal length is 0..14, and there is enough space, + * enter the shortcut and copy 16 bytes on behalf of the literals + * (in the fast mode, only 8 bytes can be safely copied this way). + * 2) Further if the match length is 4..18, copy 18 bytes in a similar + * manner; but we ensure that there's enough space in the output for + * those 18 bytes earlier, upon entering the shortcut (in other words, + * there is a combined check for both stages). + */ + if ( (length != RUN_MASK) + /* strictly "less than" on input, to re-enter the loop with at least one byte */ + && likely((ip < shortiend) & (op <= shortoend)) ) { + /* Copy the literals */ + LZ4_memcpy(op, ip, 16); + op += length; ip += length; + + /* The second stage: prepare for match copying, decode full info. + * If it doesn't work out, the info won't be wasted. */ + length = token & ML_MASK; /* match length */ + offset = LZ4_readLE16(ip); ip += 2; + match = op - offset; + assert(match <= op); /* check overflow */ + + /* Do not deal with overlapping matches. */ + if ( (length != ML_MASK) + && (offset >= 8) + && (dict==withPrefix64k || match >= lowPrefix) ) { + /* Copy the match. */ + LZ4_memcpy(op + 0, match + 0, 8); + LZ4_memcpy(op + 8, match + 8, 8); + LZ4_memcpy(op +16, match +16, 2); + op += length + MINMATCH; + /* Both stages worked, load the next token. */ + continue; + } + + /* The second stage didn't work out, but the info is ready. + * Propel it right to the point of match copying. */ + goto _copy_match; + } + + /* decode literal length */ + if (length == RUN_MASK) { + size_t const addl = read_variable_length(&ip, iend-RUN_MASK, 1); + if (addl == rvl_error) { goto _output_error; } + length += addl; + if (unlikely((uptrval)(op)+length<(uptrval)(op))) { goto _output_error; } /* overflow detection */ + if (unlikely((uptrval)(ip)+length<(uptrval)(ip))) { goto _output_error; } /* overflow detection */ + } + +#if LZ4_FAST_DEC_LOOP + safe_literal_copy: +#endif + /* copy literals */ + cpy = op+length; + + LZ4_STATIC_ASSERT(MFLIMIT >= WILDCOPYLENGTH); + if ((cpy>oend-MFLIMIT) || (ip+length>iend-(2+1+LASTLITERALS))) { + /* We've either hit the input parsing restriction or the output parsing restriction. + * In the normal scenario, decoding a full block, it must be the last sequence, + * otherwise it's an error (invalid input or dimensions). + * In partialDecoding scenario, it's necessary to ensure there is no buffer overflow. + */ + if (partialDecoding) { + /* Since we are partial decoding we may be in this block because of the output parsing + * restriction, which is not valid since the output buffer is allowed to be undersized. + */ + DEBUGLOG(7, "partialDecoding: copying literals, close to input or output end") + DEBUGLOG(7, "partialDecoding: literal length = %u", (unsigned)length); + DEBUGLOG(7, "partialDecoding: remaining space in dstBuffer : %i", (int)(oend - op)); + DEBUGLOG(7, "partialDecoding: remaining space in srcBuffer : %i", (int)(iend - ip)); + /* Finishing in the middle of a literals segment, + * due to lack of input. + */ + if (ip+length > iend) { + length = (size_t)(iend-ip); + cpy = op + length; + } + /* Finishing in the middle of a literals segment, + * due to lack of output space. + */ + if (cpy > oend) { + cpy = oend; + assert(op<=oend); + length = (size_t)(oend-op); + } + } else { + /* We must be on the last sequence (or invalid) because of the parsing limitations + * so check that we exactly consume the input and don't overrun the output buffer. + */ + if ((ip+length != iend) || (cpy > oend)) { + DEBUGLOG(6, "should have been last run of literals") + DEBUGLOG(6, "ip(%p) + length(%i) = %p != iend (%p)", ip, (int)length, ip+length, iend); + DEBUGLOG(6, "or cpy(%p) > oend(%p)", cpy, oend); + goto _output_error; + } + } + LZ4_memmove(op, ip, length); /* supports overlapping memory regions, for in-place decompression scenarios */ + ip += length; + op += length; + /* Necessarily EOF when !partialDecoding. + * When partialDecoding, it is EOF if we've either + * filled the output buffer or + * can't proceed with reading an offset for following match. + */ + if (!partialDecoding || (cpy == oend) || (ip >= (iend-2))) { + break; + } + } else { + LZ4_wildCopy8(op, ip, cpy); /* can overwrite up to 8 bytes beyond cpy */ + ip += length; op = cpy; + } + + /* get offset */ + offset = LZ4_readLE16(ip); ip+=2; + match = op - offset; + + /* get matchlength */ + length = token & ML_MASK; + + _copy_match: + if (length == ML_MASK) { + size_t const addl = read_variable_length(&ip, iend - LASTLITERALS + 1, 0); + if (addl == rvl_error) { goto _output_error; } + length += addl; + if (unlikely((uptrval)(op)+length<(uptrval)op)) goto _output_error; /* overflow detection */ + } + length += MINMATCH; + +#if LZ4_FAST_DEC_LOOP + safe_match_copy: +#endif + if ((checkOffset) && (unlikely(match + dictSize < lowPrefix))) goto _output_error; /* Error : offset outside buffers */ + /* match starting within external dictionary */ + if ((dict==usingExtDict) && (match < lowPrefix)) { + assert(dictEnd != NULL); + if (unlikely(op+length > oend-LASTLITERALS)) { + if (partialDecoding) length = MIN(length, (size_t)(oend-op)); + else goto _output_error; /* doesn't respect parsing restriction */ + } + + if (length <= (size_t)(lowPrefix-match)) { + /* match fits entirely within external dictionary : just copy */ + LZ4_memmove(op, dictEnd - (lowPrefix-match), length); + op += length; + } else { + /* match stretches into both external dictionary and current block */ + size_t const copySize = (size_t)(lowPrefix - match); + size_t const restSize = length - copySize; + LZ4_memcpy(op, dictEnd - copySize, copySize); + op += copySize; + if (restSize > (size_t)(op - lowPrefix)) { /* overlap copy */ + BYTE* const endOfMatch = op + restSize; + const BYTE* copyFrom = lowPrefix; + while (op < endOfMatch) *op++ = *copyFrom++; + } else { + LZ4_memcpy(op, lowPrefix, restSize); + op += restSize; + } } + continue; + } + assert(match >= lowPrefix); + + /* copy match within block */ + cpy = op + length; + + /* partialDecoding : may end anywhere within the block */ + assert(op<=oend); + if (partialDecoding && (cpy > oend-MATCH_SAFEGUARD_DISTANCE)) { + size_t const mlen = MIN(length, (size_t)(oend-op)); + const BYTE* const matchEnd = match + mlen; + BYTE* const copyEnd = op + mlen; + if (matchEnd > op) { /* overlap copy */ + while (op < copyEnd) { *op++ = *match++; } + } else { + LZ4_memcpy(op, match, mlen); + } + op = copyEnd; + if (op == oend) { break; } + continue; + } + + if (unlikely(offset<8)) { + LZ4_write32(op, 0); /* silence msan warning when offset==0 */ + op[0] = match[0]; + op[1] = match[1]; + op[2] = match[2]; + op[3] = match[3]; + match += inc32table[offset]; + LZ4_memcpy(op+4, match, 4); + match -= dec64table[offset]; + } else { + LZ4_memcpy(op, match, 8); + match += 8; + } + op += 8; + + if (unlikely(cpy > oend-MATCH_SAFEGUARD_DISTANCE)) { + BYTE* const oCopyLimit = oend - (WILDCOPYLENGTH-1); + if (cpy > oend-LASTLITERALS) { goto _output_error; } /* Error : last LASTLITERALS bytes must be literals (uncompressed) */ + if (op < oCopyLimit) { + LZ4_wildCopy8(op, match, oCopyLimit); + match += oCopyLimit - op; + op = oCopyLimit; + } + while (op < cpy) { *op++ = *match++; } + } else { + LZ4_memcpy(op, match, 8); + if (length > 16) { LZ4_wildCopy8(op+8, match+8, cpy); } + } + op = cpy; /* wildcopy correction */ } - /* copy repeated sequence */ - cpy = op + length; - if (unlikely((op - match) < 8)) { - const size_t dec64 = dec64table[op - match]; - op[0] = match[0]; - op[1] = match[1]; - op[2] = match[2]; - op[3] = match[3]; - match += dec32table[op - match]; - LZ4_copy4(op + 4, match); - op += 8; - match -= dec64; - } else { - LZ4_copy8(op, match); - op += 8; - match += 8; - } + /* end of decoding */ + DEBUGLOG(5, "decoded %i bytes", (int) (((char*)op)-dst)); + return (int) (((char*)op)-dst); /* Nb of output bytes decoded */ - if (unlikely(cpy > oend - 12)) { - if (cpy > oend - LASTLITERALS) - goto _output_error; /* Error : last LASTLITERALS bytes must be literals */ - if (op < oend - 8) { - LZ4_wildCopy(op, match, oend - 8); - match += (oend - 8) - op; - op = oend - 8; - } - while (op < cpy) - *op++ = *match++; - } else - LZ4_wildCopy(op, match, cpy); - op = cpy; /* correction */ + /* Overflow error detected */ + _output_error: + return (int) (-(((const char*)ip)-src))-1; } - - /* end of decoding */ - if (endOnInput) - return (int)(((char *)op) - dest); /* Nb of output bytes decoded */ - else - return (int)(((const char *)ip) - source); /* Nb of input bytes read */ - - /* Overflow error detected */ -_output_error: - return (int)(-(((const char *)ip) - source)) - 1; } -int LZ4_decompress_safe(const char *source, char *dest, int compressedSize, int maxDecompressedSize) + +/*===== Instantiate the API decoding functions. =====*/ + +LZ4_FORCE_O2 +int LZ4_decompress_safe(const char* source, char* dest, int compressedSize, int maxDecompressedSize) { - return LZ4_decompress_generic(source, dest, compressedSize, maxDecompressedSize, endOnInputSize, full, 0, noDict, - (BYTE *)dest, NULL, 0); + return LZ4_decompress_generic(source, dest, compressedSize, maxDecompressedSize, + decode_full_block, noDict, + (BYTE*)dest, NULL, 0); } -int LZ4_decompress_safe_partial(const char *source, char *dest, int compressedSize, int targetOutputSize, - int maxDecompressedSize) +LZ4_FORCE_O2 +int LZ4_decompress_safe_partial(const char* src, char* dst, int compressedSize, int targetOutputSize, int dstCapacity) { - return LZ4_decompress_generic(source, dest, compressedSize, maxDecompressedSize, endOnInputSize, partial, - targetOutputSize, noDict, (BYTE *)dest, NULL, 0); + dstCapacity = MIN(targetOutputSize, dstCapacity); + return LZ4_decompress_generic(src, dst, compressedSize, dstCapacity, + partial_decode, + noDict, (BYTE*)dst, NULL, 0); } -int LZ4_decompress_fast(const char *source, char *dest, int originalSize) +LZ4_FORCE_O2 +int LZ4_decompress_fast(const char* source, char* dest, int originalSize) { - return LZ4_decompress_generic(source, dest, 0, originalSize, endOnOutputSize, full, 0, withPrefix64k, - (BYTE *)(dest - 64 KB), NULL, 64 KB); + DEBUGLOG(5, "LZ4_decompress_fast"); + return LZ4_decompress_unsafe_generic( + (const BYTE*)source, (BYTE*)dest, originalSize, + 0, NULL, 0); } -/* streaming decompression functions */ +/*===== Instantiate a few more decoding cases, used more than once. =====*/ -typedef struct +LZ4_FORCE_O2 /* Exported, an obsolete API function. */ +int LZ4_decompress_safe_withPrefix64k(const char* source, char* dest, int compressedSize, int maxOutputSize) { - const BYTE *externalDict; - size_t extDictSize; - const BYTE *prefixEnd; - size_t prefixSize; -} LZ4_streamDecode_t_internal; + return LZ4_decompress_generic(source, dest, compressedSize, maxOutputSize, + decode_full_block, withPrefix64k, + (BYTE*)dest - 64 KB, NULL, 0); +} -/* - * If you prefer dynamic allocation methods, - * LZ4_createStreamDecode() - * provides a pointer (void*) towards an initialized LZ4_streamDecode_t structure. +LZ4_FORCE_O2 +static int LZ4_decompress_safe_partial_withPrefix64k(const char* source, char* dest, int compressedSize, int targetOutputSize, int dstCapacity) +{ + dstCapacity = MIN(targetOutputSize, dstCapacity); + return LZ4_decompress_generic(source, dest, compressedSize, dstCapacity, + partial_decode, withPrefix64k, + (BYTE*)dest - 64 KB, NULL, 0); +} + +/* Another obsolete API function, paired with the previous one. */ +int LZ4_decompress_fast_withPrefix64k(const char* source, char* dest, int originalSize) +{ + return LZ4_decompress_unsafe_generic( + (const BYTE*)source, (BYTE*)dest, originalSize, + 64 KB, NULL, 0); +} + +LZ4_FORCE_O2 +static int LZ4_decompress_safe_withSmallPrefix(const char* source, char* dest, int compressedSize, int maxOutputSize, + size_t prefixSize) +{ + return LZ4_decompress_generic(source, dest, compressedSize, maxOutputSize, + decode_full_block, noDict, + (BYTE*)dest-prefixSize, NULL, 0); +} + +LZ4_FORCE_O2 +static int LZ4_decompress_safe_partial_withSmallPrefix(const char* source, char* dest, int compressedSize, int targetOutputSize, int dstCapacity, + size_t prefixSize) +{ + dstCapacity = MIN(targetOutputSize, dstCapacity); + return LZ4_decompress_generic(source, dest, compressedSize, dstCapacity, + partial_decode, noDict, + (BYTE*)dest-prefixSize, NULL, 0); +} + +LZ4_FORCE_O2 +int LZ4_decompress_safe_forceExtDict(const char* source, char* dest, + int compressedSize, int maxOutputSize, + const void* dictStart, size_t dictSize) +{ + DEBUGLOG(5, "LZ4_decompress_safe_forceExtDict"); + return LZ4_decompress_generic(source, dest, compressedSize, maxOutputSize, + decode_full_block, usingExtDict, + (BYTE*)dest, (const BYTE*)dictStart, dictSize); +} + +LZ4_FORCE_O2 +int LZ4_decompress_safe_partial_forceExtDict(const char* source, char* dest, + int compressedSize, int targetOutputSize, int dstCapacity, + const void* dictStart, size_t dictSize) +{ + dstCapacity = MIN(targetOutputSize, dstCapacity); + return LZ4_decompress_generic(source, dest, compressedSize, dstCapacity, + partial_decode, usingExtDict, + (BYTE*)dest, (const BYTE*)dictStart, dictSize); +} + +LZ4_FORCE_O2 +static int LZ4_decompress_fast_extDict(const char* source, char* dest, int originalSize, + const void* dictStart, size_t dictSize) +{ + return LZ4_decompress_unsafe_generic( + (const BYTE*)source, (BYTE*)dest, originalSize, + 0, (const BYTE*)dictStart, dictSize); +} + +/* The "double dictionary" mode, for use with e.g. ring buffers: the first part + * of the dictionary is passed as prefix, and the second via dictStart + dictSize. + * These routines are used only once, in LZ4_decompress_*_continue(). */ -LZ4_streamDecode_t *LZ4_createStreamDecode(void) +LZ4_FORCE_INLINE +int LZ4_decompress_safe_doubleDict(const char* source, char* dest, int compressedSize, int maxOutputSize, + size_t prefixSize, const void* dictStart, size_t dictSize) { - LZ4_streamDecode_t *lz4s = (LZ4_streamDecode_t *)ALLOCATOR(1, sizeof(LZ4_streamDecode_t)); - return lz4s; + return LZ4_decompress_generic(source, dest, compressedSize, maxOutputSize, + decode_full_block, usingExtDict, + (BYTE*)dest-prefixSize, (const BYTE*)dictStart, dictSize); } -int LZ4_freeStreamDecode(LZ4_streamDecode_t *LZ4_stream) +/*===== streaming decompression functions =====*/ + +#if !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) +LZ4_streamDecode_t* LZ4_createStreamDecode(void) { + LZ4_STATIC_ASSERT(sizeof(LZ4_streamDecode_t) >= sizeof(LZ4_streamDecode_t_internal)); + return (LZ4_streamDecode_t*) ALLOC_AND_ZERO(sizeof(LZ4_streamDecode_t)); +} + +int LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream) +{ + if (LZ4_stream == NULL) { return 0; } /* support free on NULL */ FREEMEM(LZ4_stream); return 0; } +#endif -/* - * LZ4_setStreamDecode - * Use this function to instruct where to find the dictionary - * This function is not necessary if previous data is still available where it was decoded. - * Loading a size of 0 is allowed (same effect as no dictionary). - * Return : 1 if OK, 0 if error +/*! LZ4_setStreamDecode() : + * Use this function to instruct where to find the dictionary. + * This function is not necessary if previous data is still available where it was decoded. + * Loading a size of 0 is allowed (same effect as no dictionary). + * @return : 1 if OK, 0 if error */ -int LZ4_setStreamDecode(LZ4_streamDecode_t *LZ4_streamDecode, const char *dictionary, int dictSize) +int LZ4_setStreamDecode (LZ4_streamDecode_t* LZ4_streamDecode, const char* dictionary, int dictSize) { - LZ4_streamDecode_t_internal *lz4sd = (LZ4_streamDecode_t_internal *)LZ4_streamDecode; + LZ4_streamDecode_t_internal* lz4sd = &LZ4_streamDecode->internal_donotuse; lz4sd->prefixSize = (size_t)dictSize; - lz4sd->prefixEnd = (const BYTE *)dictionary + dictSize; + if (dictSize) { + assert(dictionary != NULL); + lz4sd->prefixEnd = (const BYTE*) dictionary + dictSize; + } else { + lz4sd->prefixEnd = (const BYTE*) dictionary; + } lz4sd->externalDict = NULL; - lz4sd->extDictSize = 0; + lz4sd->extDictSize = 0; return 1; } +/*! LZ4_decoderRingBufferSize() : + * when setting a ring buffer for streaming decompression (optional scenario), + * provides the minimum size of this ring buffer + * to be compatible with any source respecting maxBlockSize condition. + * Note : in a ring buffer scenario, + * blocks are presumed decompressed next to each other. + * When not enough space remains for next block (remainingSize < maxBlockSize), + * decoding resumes from beginning of ring buffer. + * @return : minimum ring buffer size, + * or 0 if there is an error (invalid maxBlockSize). + */ +int LZ4_decoderRingBufferSize(int maxBlockSize) +{ + if (maxBlockSize < 0) return 0; + if (maxBlockSize > LZ4_MAX_INPUT_SIZE) return 0; + if (maxBlockSize < 16) maxBlockSize = 16; + return LZ4_DECODER_RING_BUFFER_SIZE(maxBlockSize); +} + /* *_continue() : These decoding functions allow decompression of multiple blocks in "streaming" mode. @@ -1424,60 +2587,88 @@ int LZ4_setStreamDecode(LZ4_streamDecode_t *LZ4_streamDecode, const char *dictio If it's not possible, save the relevant part of decoded data into a safe buffer, and indicate where it stands using LZ4_setStreamDecode() */ -int LZ4_decompress_safe_continue(LZ4_streamDecode_t *LZ4_streamDecode, const char *source, char *dest, - int compressedSize, int maxOutputSize) +LZ4_FORCE_O2 +int LZ4_decompress_safe_continue (LZ4_streamDecode_t* LZ4_streamDecode, const char* source, char* dest, int compressedSize, int maxOutputSize) { - LZ4_streamDecode_t_internal *lz4sd = (LZ4_streamDecode_t_internal *)LZ4_streamDecode; + LZ4_streamDecode_t_internal* lz4sd = &LZ4_streamDecode->internal_donotuse; int result; - if (lz4sd->prefixEnd == (BYTE *)dest) { - result = LZ4_decompress_generic(source, dest, compressedSize, maxOutputSize, endOnInputSize, full, 0, - usingExtDict, lz4sd->prefixEnd - lz4sd->prefixSize, lz4sd->externalDict, - lz4sd->extDictSize); - if (result <= 0) - return result; - lz4sd->prefixSize += result; - lz4sd->prefixEnd += result; + if (lz4sd->prefixSize == 0) { + /* The first call, no dictionary yet. */ + assert(lz4sd->extDictSize == 0); + result = LZ4_decompress_safe(source, dest, compressedSize, maxOutputSize); + if (result <= 0) return result; + lz4sd->prefixSize = (size_t)result; + lz4sd->prefixEnd = (BYTE*)dest + result; + } else if (lz4sd->prefixEnd == (BYTE*)dest) { + /* They're rolling the current segment. */ + if (lz4sd->prefixSize >= 64 KB - 1) + result = LZ4_decompress_safe_withPrefix64k(source, dest, compressedSize, maxOutputSize); + else if (lz4sd->extDictSize == 0) + result = LZ4_decompress_safe_withSmallPrefix(source, dest, compressedSize, maxOutputSize, + lz4sd->prefixSize); + else + result = LZ4_decompress_safe_doubleDict(source, dest, compressedSize, maxOutputSize, + lz4sd->prefixSize, lz4sd->externalDict, lz4sd->extDictSize); + if (result <= 0) return result; + lz4sd->prefixSize += (size_t)result; + lz4sd->prefixEnd += result; } else { + /* The buffer wraps around, or they're switching to another buffer. */ lz4sd->extDictSize = lz4sd->prefixSize; lz4sd->externalDict = lz4sd->prefixEnd - lz4sd->extDictSize; - result = LZ4_decompress_generic(source, dest, compressedSize, maxOutputSize, endOnInputSize, full, 0, - usingExtDict, (BYTE *)dest, lz4sd->externalDict, lz4sd->extDictSize); - if (result <= 0) - return result; - lz4sd->prefixSize = result; - lz4sd->prefixEnd = (BYTE *)dest + result; + result = LZ4_decompress_safe_forceExtDict(source, dest, compressedSize, maxOutputSize, + lz4sd->externalDict, lz4sd->extDictSize); + if (result <= 0) return result; + lz4sd->prefixSize = (size_t)result; + lz4sd->prefixEnd = (BYTE*)dest + result; } return result; } -int LZ4_decompress_fast_continue(LZ4_streamDecode_t *LZ4_streamDecode, const char *source, char *dest, int originalSize) +LZ4_FORCE_O2 int +LZ4_decompress_fast_continue (LZ4_streamDecode_t* LZ4_streamDecode, + const char* source, char* dest, int originalSize) { - LZ4_streamDecode_t_internal *lz4sd = (LZ4_streamDecode_t_internal *)LZ4_streamDecode; + LZ4_streamDecode_t_internal* const lz4sd = + (assert(LZ4_streamDecode!=NULL), &LZ4_streamDecode->internal_donotuse); int result; - if (lz4sd->prefixEnd == (BYTE *)dest) { - result = LZ4_decompress_generic(source, dest, 0, originalSize, endOnOutputSize, full, 0, usingExtDict, - lz4sd->prefixEnd - lz4sd->prefixSize, lz4sd->externalDict, lz4sd->extDictSize); - if (result <= 0) - return result; - lz4sd->prefixSize += originalSize; - lz4sd->prefixEnd += originalSize; + DEBUGLOG(5, "LZ4_decompress_fast_continue (toDecodeSize=%i)", originalSize); + assert(originalSize >= 0); + + if (lz4sd->prefixSize == 0) { + DEBUGLOG(5, "first invocation : no prefix nor extDict"); + assert(lz4sd->extDictSize == 0); + result = LZ4_decompress_fast(source, dest, originalSize); + if (result <= 0) return result; + lz4sd->prefixSize = (size_t)originalSize; + lz4sd->prefixEnd = (BYTE*)dest + originalSize; + } else if (lz4sd->prefixEnd == (BYTE*)dest) { + DEBUGLOG(5, "continue using existing prefix"); + result = LZ4_decompress_unsafe_generic( + (const BYTE*)source, (BYTE*)dest, originalSize, + lz4sd->prefixSize, + lz4sd->externalDict, lz4sd->extDictSize); + if (result <= 0) return result; + lz4sd->prefixSize += (size_t)originalSize; + lz4sd->prefixEnd += originalSize; } else { + DEBUGLOG(5, "prefix becomes extDict"); lz4sd->extDictSize = lz4sd->prefixSize; - lz4sd->externalDict = (BYTE *)dest - lz4sd->extDictSize; - result = LZ4_decompress_generic(source, dest, 0, originalSize, endOnOutputSize, full, 0, usingExtDict, - (BYTE *)dest, lz4sd->externalDict, lz4sd->extDictSize); - if (result <= 0) - return result; - lz4sd->prefixSize = originalSize; - lz4sd->prefixEnd = (BYTE *)dest + originalSize; + lz4sd->externalDict = lz4sd->prefixEnd - lz4sd->extDictSize; + result = LZ4_decompress_fast_extDict(source, dest, originalSize, + lz4sd->externalDict, lz4sd->extDictSize); + if (result <= 0) return result; + lz4sd->prefixSize = (size_t)originalSize; + lz4sd->prefixEnd = (BYTE*)dest + originalSize; } return result; } + /* Advanced decoding functions : *_usingDict() : @@ -1485,131 +2676,114 @@ Advanced decoding functions : the dictionary must be explicitly provided within parameters */ -FORCE_INLINE int LZ4_decompress_usingDict_generic(const char *source, char *dest, int compressedSize, int maxOutputSize, - int safe, const char *dictStart, int dictSize) +int LZ4_decompress_safe_usingDict(const char* source, char* dest, int compressedSize, int maxOutputSize, const char* dictStart, int dictSize) { - if (dictSize == 0) - return LZ4_decompress_generic(source, dest, compressedSize, maxOutputSize, safe, full, 0, noDict, (BYTE *)dest, - NULL, 0); - if (dictStart + dictSize == dest) { - if (dictSize >= (int)(64 KB - 1)) - return LZ4_decompress_generic(source, dest, compressedSize, maxOutputSize, safe, full, 0, withPrefix64k, - (BYTE *)dest - 64 KB, NULL, 0); - return LZ4_decompress_generic(source, dest, compressedSize, maxOutputSize, safe, full, 0, noDict, - (BYTE *)dest - dictSize, NULL, 0); + if (dictSize==0) + return LZ4_decompress_safe(source, dest, compressedSize, maxOutputSize); + if (dictStart+dictSize == dest) { + if (dictSize >= 64 KB - 1) { + return LZ4_decompress_safe_withPrefix64k(source, dest, compressedSize, maxOutputSize); + } + assert(dictSize >= 0); + return LZ4_decompress_safe_withSmallPrefix(source, dest, compressedSize, maxOutputSize, (size_t)dictSize); } - return LZ4_decompress_generic(source, dest, compressedSize, maxOutputSize, safe, full, 0, usingExtDict, - (BYTE *)dest, (const BYTE *)dictStart, dictSize); + assert(dictSize >= 0); + return LZ4_decompress_safe_forceExtDict(source, dest, compressedSize, maxOutputSize, dictStart, (size_t)dictSize); } -int LZ4_decompress_safe_usingDict(const char *source, char *dest, int compressedSize, int maxOutputSize, - const char *dictStart, int dictSize) +int LZ4_decompress_safe_partial_usingDict(const char* source, char* dest, int compressedSize, int targetOutputSize, int dstCapacity, const char* dictStart, int dictSize) { - return LZ4_decompress_usingDict_generic(source, dest, compressedSize, maxOutputSize, 1, dictStart, dictSize); + if (dictSize==0) + return LZ4_decompress_safe_partial(source, dest, compressedSize, targetOutputSize, dstCapacity); + if (dictStart+dictSize == dest) { + if (dictSize >= 64 KB - 1) { + return LZ4_decompress_safe_partial_withPrefix64k(source, dest, compressedSize, targetOutputSize, dstCapacity); + } + assert(dictSize >= 0); + return LZ4_decompress_safe_partial_withSmallPrefix(source, dest, compressedSize, targetOutputSize, dstCapacity, (size_t)dictSize); + } + assert(dictSize >= 0); + return LZ4_decompress_safe_partial_forceExtDict(source, dest, compressedSize, targetOutputSize, dstCapacity, dictStart, (size_t)dictSize); } -int LZ4_decompress_fast_usingDict(const char *source, char *dest, int originalSize, const char *dictStart, int dictSize) +int LZ4_decompress_fast_usingDict(const char* source, char* dest, int originalSize, const char* dictStart, int dictSize) { - return LZ4_decompress_usingDict_generic(source, dest, 0, originalSize, 0, dictStart, dictSize); + if (dictSize==0 || dictStart+dictSize == dest) + return LZ4_decompress_unsafe_generic( + (const BYTE*)source, (BYTE*)dest, originalSize, + (size_t)dictSize, NULL, 0); + assert(dictSize >= 0); + return LZ4_decompress_fast_extDict(source, dest, originalSize, dictStart, (size_t)dictSize); } -/* debug function */ -int LZ4_decompress_safe_forceExtDict(const char *source, char *dest, int compressedSize, int maxOutputSize, - const char *dictStart, int dictSize) -{ - return LZ4_decompress_generic(source, dest, compressedSize, maxOutputSize, endOnInputSize, full, 0, usingExtDict, - (BYTE *)dest, (const BYTE *)dictStart, dictSize); -} -/*************************************************** - * Obsolete Functions - ***************************************************/ +/*=************************************************* +* Obsolete Functions +***************************************************/ /* obsolete compression functions */ -int LZ4_compress_limitedOutput(const char *source, char *dest, int inputSize, int maxOutputSize) +int LZ4_compress_limitedOutput(const char* source, char* dest, int inputSize, int maxOutputSize) { return LZ4_compress_default(source, dest, inputSize, maxOutputSize); } -int LZ4_compress(const char *source, char *dest, int inputSize) +int LZ4_compress(const char* src, char* dest, int srcSize) { - return LZ4_compress_default(source, dest, inputSize, LZ4_compressBound(inputSize)); + return LZ4_compress_default(src, dest, srcSize, LZ4_compressBound(srcSize)); } -int LZ4_compress_limitedOutput_withState(void *state, const char *src, char *dst, int srcSize, int dstSize) +int LZ4_compress_limitedOutput_withState (void* state, const char* src, char* dst, int srcSize, int dstSize) { return LZ4_compress_fast_extState(state, src, dst, srcSize, dstSize, 1); } -int LZ4_compress_withState(void *state, const char *src, char *dst, int srcSize) +int LZ4_compress_withState (void* state, const char* src, char* dst, int srcSize) { return LZ4_compress_fast_extState(state, src, dst, srcSize, LZ4_compressBound(srcSize), 1); } -int LZ4_compress_limitedOutput_continue(LZ4_stream_t *LZ4_stream, const char *src, char *dst, int srcSize, - int maxDstSize) +int LZ4_compress_limitedOutput_continue (LZ4_stream_t* LZ4_stream, const char* src, char* dst, int srcSize, int dstCapacity) { - return LZ4_compress_fast_continue(LZ4_stream, src, dst, srcSize, maxDstSize, 1); + return LZ4_compress_fast_continue(LZ4_stream, src, dst, srcSize, dstCapacity, 1); } -int LZ4_compress_continue(LZ4_stream_t *LZ4_stream, const char *source, char *dest, int inputSize) +int LZ4_compress_continue (LZ4_stream_t* LZ4_stream, const char* source, char* dest, int inputSize) { return LZ4_compress_fast_continue(LZ4_stream, source, dest, inputSize, LZ4_compressBound(inputSize), 1); } /* -These function names are deprecated and should no longer be used. +These decompression functions are deprecated and should no longer be used. They are only provided here for compatibility with older user programs. - LZ4_uncompress is totally equivalent to LZ4_decompress_fast - LZ4_uncompress_unknownOutputSize is totally equivalent to LZ4_decompress_safe */ -int LZ4_uncompress(const char *source, char *dest, int outputSize) +int LZ4_uncompress (const char* source, char* dest, int outputSize) { return LZ4_decompress_fast(source, dest, outputSize); } -int LZ4_uncompress_unknownOutputSize(const char *source, char *dest, int isize, int maxOutputSize) +int LZ4_uncompress_unknownOutputSize (const char* source, char* dest, int isize, int maxOutputSize) { return LZ4_decompress_safe(source, dest, isize, maxOutputSize); } /* Obsolete Streaming functions */ -int LZ4_sizeofStreamState() { return LZ4_STREAMSIZE; } +int LZ4_sizeofStreamState(void) { return sizeof(LZ4_stream_t); } -static void LZ4_init(LZ4_stream_t_internal *lz4ds, BYTE *base) +int LZ4_resetStreamState(void* state, char* inputBuffer) { - MEM_INIT(lz4ds, 0, LZ4_STREAMSIZE); - lz4ds->bufferStart = base; -} - -int LZ4_resetStreamState(void *state, char *inputBuffer) -{ - if ((((size_t)state) & 3) != 0) - return 1; /* Error : pointer is not aligned on 4-bytes boundary */ - LZ4_init((LZ4_stream_t_internal *)state, (BYTE *)inputBuffer); + (void)inputBuffer; + LZ4_resetStream((LZ4_stream_t*)state); return 0; } -void *LZ4_create(char *inputBuffer) +#if !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) +void* LZ4_create (char* inputBuffer) { - void *lz4ds = ALLOCATOR(8, LZ4_STREAMSIZE_U64); - LZ4_init((LZ4_stream_t_internal *)lz4ds, (BYTE *)inputBuffer); - return lz4ds; + (void)inputBuffer; + return LZ4_createStream(); +} +#endif + +char* LZ4_slideInputBuffer (void* state) +{ + /* avoid const char * -> char * conversion warning */ + return (char *)(uptrval)((LZ4_stream_t*)state)->internal_donotuse.dictionary; } -char *LZ4_slideInputBuffer(void *LZ4_Data) -{ - LZ4_stream_t_internal *ctx = (LZ4_stream_t_internal *)LZ4_Data; - int dictSize = LZ4_saveDict((LZ4_stream_t *)LZ4_Data, (char *)ctx->bufferStart, 64 KB); - return (char *)(ctx->bufferStart + dictSize); -} - -/* Obsolete streaming decompression functions */ - -int LZ4_decompress_safe_withPrefix64k(const char *source, char *dest, int compressedSize, int maxOutputSize) -{ - return LZ4_decompress_generic(source, dest, compressedSize, maxOutputSize, endOnInputSize, full, 0, withPrefix64k, - (BYTE *)dest - 64 KB, NULL, 64 KB); -} - -int LZ4_decompress_fast_withPrefix64k(const char *source, char *dest, int originalSize) -{ - return LZ4_decompress_generic(source, dest, 0, originalSize, endOnOutputSize, full, 0, withPrefix64k, - (BYTE *)dest - 64 KB, NULL, 64 KB); -} - -#endif /* LZ4_COMMONDEFS_ONLY */ +#endif /* LZ4_COMMONDEFS_ONLY */ diff --git a/libs/fst/lz4.h b/libs/fst/lz4.h index 929cf02ca..7a2dbfd4b 100644 --- a/libs/fst/lz4.h +++ b/libs/fst/lz4.h @@ -1,7 +1,7 @@ /* - LZ4 - Fast LZ compression algorithm - Header File - Copyright (C) 2011-2015, Yann Collet. + * LZ4 - Fast LZ compression algorithm + * Header File + * Copyright (C) 2011-2023, Yann Collet. BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php) @@ -28,340 +28,841 @@ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - SPDX-License-Identifier: BSD-2-Clause - You can contact the author at : - - LZ4 source repository : https://github.com/Cyan4973/lz4 - - LZ4 public forum : https://groups.google.com/forum/#!forum/lz4c + - LZ4 homepage : http://www.lz4.org + - LZ4 source repository : https://github.com/lz4/lz4 */ -#pragma once - -#if defined(__cplusplus) +#if defined (__cplusplus) extern "C" { #endif -/* - * lz4.h provides block compression functions, and gives full buffer control to programmer. - * If you need to generate inter-operable compressed data (respecting LZ4 frame specification), - * and can let the library handle its own memory, please use lz4frame.h instead. - */ +#ifndef LZ4_H_2983827168210 +#define LZ4_H_2983827168210 -/************************************** - * Version - **************************************/ -#define LZ4_VERSION_MAJOR 1 /* for breaking interface changes */ -#define LZ4_VERSION_MINOR 7 /* for new (non-breaking) interface capabilities */ -#define LZ4_VERSION_RELEASE 1 /* for tweaks, bug-fixes, or development */ -#define LZ4_VERSION_NUMBER (LZ4_VERSION_MAJOR * 100 * 100 + LZ4_VERSION_MINOR * 100 + LZ4_VERSION_RELEASE) -int LZ4_versionNumber(void); +/* --- Dependency --- */ +#include /* size_t */ -/************************************** - * Tuning parameter - **************************************/ -/* - * LZ4_MEMORY_USAGE : - * Memory usage formula : N->2^N Bytes (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB; etc.) - * Increasing memory usage improves compression ratio - * Reduced memory usage can improve speed, due to cache effect - * Default value is 14, for 16KB, which nicely fits into Intel x86 L1 cache - */ -#define LZ4_MEMORY_USAGE 14 -/************************************** - * Simple Functions - **************************************/ +/** + Introduction -int LZ4_compress_default(const char *source, char *dest, int sourceSize, int maxDestSize); -int LZ4_decompress_safe(const char *source, char *dest, int compressedSize, int maxDecompressedSize); + LZ4 is lossless compression algorithm, providing compression speed >500 MB/s per core, + scalable with multi-cores CPU. It features an extremely fast decoder, with speed in + multiple GB/s per core, typically reaching RAM speed limits on multi-core systems. -/* -LZ4_compress_default() : - Compresses 'sourceSize' bytes from buffer 'source' - into already allocated 'dest' buffer of size 'maxDestSize'. - Compression is guaranteed to succeed if 'maxDestSize' >= LZ4_compressBound(sourceSize). - It also runs faster, so it's a recommended setting. - If the function cannot compress 'source' into a more limited 'dest' budget, - compression stops *immediately*, and the function result is zero. - As a consequence, 'dest' content is not valid. - This function never writes outside 'dest' buffer, nor read outside 'source' buffer. - sourceSize : Max supported value is LZ4_MAX_INPUT_VALUE - maxDestSize : full or partial size of buffer 'dest' (which must be already allocated) - return : the number of bytes written into buffer 'dest' (necessarily <= maxOutputSize) - or 0 if compression fails + The LZ4 compression library provides in-memory compression and decompression functions. + It gives full buffer control to user. + Compression can be done in: + - a single step (described as Simple Functions) + - a single step, reusing a context (described in Advanced Functions) + - unbounded multiple steps (described as Streaming compression) -LZ4_decompress_safe() : - compressedSize : is the precise full size of the compressed block. - maxDecompressedSize : is the size of destination buffer, which must be already allocated. - return : the number of bytes decompressed into destination buffer (necessarily <= maxDecompressedSize) - If destination buffer is not large enough, decoding will stop and output an error code (<0). - If the source stream is detected malformed, the function will stop decoding and return a negative result. - This function is protected against buffer overflow exploits, including malicious data packets. - It never writes outside output buffer, nor reads outside input buffer. + lz4.h generates and decodes LZ4-compressed blocks (doc/lz4_Block_format.md). + Decompressing such a compressed block requires additional metadata. + Exact metadata depends on exact decompression function. + For the typical case of LZ4_decompress_safe(), + metadata includes block's compressed size, and maximum bound of decompressed size. + Each application is free to encode and pass such metadata in whichever way it wants. + + lz4.h only handle blocks, it can not generate Frames. + + Blocks are different from Frames (doc/lz4_Frame_format.md). + Frames bundle both blocks and metadata in a specified manner. + Embedding metadata is required for compressed data to be self-contained and portable. + Frame format is delivered through a companion API, declared in lz4frame.h. + The `lz4` CLI can only manage frames. */ -/************************************** - * Advanced Functions - **************************************/ -#define LZ4_MAX_INPUT_SIZE 0x7E000000 /* 2 113 929 216 bytes */ -#define LZ4_COMPRESSBOUND(isize) ((unsigned)(isize) > (unsigned)LZ4_MAX_INPUT_SIZE ? 0 : (isize) + ((isize) / 255) + 16) - +/*^*************************************************************** +* Export parameters +*****************************************************************/ /* -LZ4_compressBound() : +* LZ4_DLL_EXPORT : +* Enable exporting of functions when building a Windows DLL +* LZ4LIB_VISIBILITY : +* Control library symbols visibility. +*/ +#ifndef LZ4LIB_VISIBILITY +# if defined(__GNUC__) && (__GNUC__ >= 4) +# define LZ4LIB_VISIBILITY __attribute__ ((visibility ("default"))) +# else +# define LZ4LIB_VISIBILITY +# endif +#endif +#if defined(LZ4_DLL_EXPORT) && (LZ4_DLL_EXPORT==1) +# define LZ4LIB_API __declspec(dllexport) LZ4LIB_VISIBILITY +#elif defined(LZ4_DLL_IMPORT) && (LZ4_DLL_IMPORT==1) +# define LZ4LIB_API __declspec(dllimport) LZ4LIB_VISIBILITY /* It isn't required but allows to generate better code, saving a function pointer load from the IAT and an indirect jump.*/ +#else +# define LZ4LIB_API LZ4LIB_VISIBILITY +#endif + +/*! LZ4_FREESTANDING : + * When this macro is set to 1, it enables "freestanding mode" that is + * suitable for typical freestanding environment which doesn't support + * standard C library. + * + * - LZ4_FREESTANDING is a compile-time switch. + * - It requires the following macros to be defined: + * LZ4_memcpy, LZ4_memmove, LZ4_memset. + * - It only enables LZ4/HC functions which don't use heap. + * All LZ4F_* functions are not supported. + * - See tests/freestanding.c to check its basic setup. + */ +#if defined(LZ4_FREESTANDING) && (LZ4_FREESTANDING == 1) +# define LZ4_HEAPMODE 0 +# define LZ4HC_HEAPMODE 0 +# define LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION 1 +# if !defined(LZ4_memcpy) +# error "LZ4_FREESTANDING requires macro 'LZ4_memcpy'." +# endif +# if !defined(LZ4_memset) +# error "LZ4_FREESTANDING requires macro 'LZ4_memset'." +# endif +# if !defined(LZ4_memmove) +# error "LZ4_FREESTANDING requires macro 'LZ4_memmove'." +# endif +#elif ! defined(LZ4_FREESTANDING) +# define LZ4_FREESTANDING 0 +#endif + + +/*------ Version ------*/ +#define LZ4_VERSION_MAJOR 1 /* for breaking interface changes */ +#define LZ4_VERSION_MINOR 9 /* for new (non-breaking) interface capabilities */ +#define LZ4_VERSION_RELEASE 5 /* for tweaks, bug-fixes, or development */ + +#define LZ4_VERSION_NUMBER (LZ4_VERSION_MAJOR *100*100 + LZ4_VERSION_MINOR *100 + LZ4_VERSION_RELEASE) + +#define LZ4_LIB_VERSION LZ4_VERSION_MAJOR.LZ4_VERSION_MINOR.LZ4_VERSION_RELEASE +#define LZ4_QUOTE(str) #str +#define LZ4_EXPAND_AND_QUOTE(str) LZ4_QUOTE(str) +#define LZ4_VERSION_STRING LZ4_EXPAND_AND_QUOTE(LZ4_LIB_VERSION) /* requires v1.7.3+ */ + +LZ4LIB_API int LZ4_versionNumber (void); /**< library version number; useful to check dll version; requires v1.3.0+ */ +LZ4LIB_API const char* LZ4_versionString (void); /**< library version string; useful to check dll version; requires v1.7.5+ */ + + +/*-************************************ +* Tuning memory usage +**************************************/ +/*! + * LZ4_MEMORY_USAGE : + * Memory usage formula : N->2^N Bytes (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB) + * Increasing memory usage improves compression ratio, generally at the cost of speed. + * Reduced memory usage may improve speed at the cost of ratio, thanks to better cache locality. + * Default value is 14, for 16KB, which nicely fits into most L1 caches. + */ +#ifndef LZ4_MEMORY_USAGE +# define LZ4_MEMORY_USAGE LZ4_MEMORY_USAGE_DEFAULT +#endif + +#define LZ4_MEMORY_USAGE_MIN 10 +#define LZ4_MEMORY_USAGE_DEFAULT 14 +#define LZ4_MEMORY_USAGE_MAX 20 + +#if (LZ4_MEMORY_USAGE < LZ4_MEMORY_USAGE_MIN) +# error "LZ4_MEMORY_USAGE is too small !" +#endif + +#if (LZ4_MEMORY_USAGE > LZ4_MEMORY_USAGE_MAX) +# error "LZ4_MEMORY_USAGE is too large !" +#endif + +/*-************************************ +* Simple Functions +**************************************/ +/*! LZ4_compress_default() : + * Compresses 'srcSize' bytes from buffer 'src' + * into already allocated 'dst' buffer of size 'dstCapacity'. + * Compression is guaranteed to succeed if 'dstCapacity' >= LZ4_compressBound(srcSize). + * It also runs faster, so it's a recommended setting. + * If the function cannot compress 'src' into a more limited 'dst' budget, + * compression stops *immediately*, and the function result is zero. + * In which case, 'dst' content is undefined (invalid). + * srcSize : max supported value is LZ4_MAX_INPUT_SIZE. + * dstCapacity : size of buffer 'dst' (which must be already allocated) + * @return : the number of bytes written into buffer 'dst' (necessarily <= dstCapacity) + * or 0 if compression fails + * Note : This function is protected against buffer overflow scenarios (never writes outside 'dst' buffer, nor read outside 'source' buffer). + */ +LZ4LIB_API int LZ4_compress_default(const char* src, char* dst, int srcSize, int dstCapacity); + +/*! LZ4_decompress_safe() : + * @compressedSize : is the exact complete size of the compressed block. + * @dstCapacity : is the size of destination buffer (which must be already allocated), + * presumed an upper bound of decompressed size. + * @return : the number of bytes decompressed into destination buffer (necessarily <= dstCapacity) + * If destination buffer is not large enough, decoding will stop and output an error code (negative value). + * If the source stream is detected malformed, the function will stop decoding and return a negative result. + * Note 1 : This function is protected against malicious data packets : + * it will never writes outside 'dst' buffer, nor read outside 'source' buffer, + * even if the compressed block is maliciously modified to order the decoder to do these actions. + * In such case, the decoder stops immediately, and considers the compressed block malformed. + * Note 2 : compressedSize and dstCapacity must be provided to the function, the compressed block does not contain them. + * The implementation is free to send / store / derive this information in whichever way is most beneficial. + * If there is a need for a different format which bundles together both compressed data and its metadata, consider looking at lz4frame.h instead. + */ +LZ4LIB_API int LZ4_decompress_safe (const char* src, char* dst, int compressedSize, int dstCapacity); + + +/*-************************************ +* Advanced Functions +**************************************/ +#define LZ4_MAX_INPUT_SIZE 0x7E000000 /* 2 113 929 216 bytes */ +#define LZ4_COMPRESSBOUND(isize) ((unsigned)(isize) > (unsigned)LZ4_MAX_INPUT_SIZE ? 0 : (isize) + ((isize)/255) + 16) + +/*! LZ4_compressBound() : Provides the maximum size that LZ4 compression may output in a "worst case" scenario (input data not compressible) This function is primarily useful for memory allocation purposes (destination buffer size). Macro LZ4_COMPRESSBOUND() is also provided for compilation-time evaluation (stack memory allocation for example). - Note that LZ4_compress_default() compress faster when dest buffer size is >= LZ4_compressBound(srcSize) + Note that LZ4_compress_default() compresses faster when dstCapacity is >= LZ4_compressBound(srcSize) inputSize : max supported value is LZ4_MAX_INPUT_SIZE return : maximum output size in a "worst case" scenario - or 0, if input size is too large ( > LZ4_MAX_INPUT_SIZE) + or 0, if input size is incorrect (too large or negative) */ -int LZ4_compressBound(int inputSize); +LZ4LIB_API int LZ4_compressBound(int inputSize); -/* -LZ4_compress_fast() : - Same as LZ4_compress_default(), but allows to select an "acceleration" factor. +/*! LZ4_compress_fast() : + Same as LZ4_compress_default(), but allows selection of "acceleration" factor. The larger the acceleration value, the faster the algorithm, but also the lesser the compression. It's a trade-off. It can be fine tuned, with each successive value providing roughly +~3% to speed. An acceleration value of "1" is the same as regular LZ4_compress_default() - Values <= 0 will be replaced by ACCELERATION_DEFAULT (see lz4.c), which is 1. + Values <= 0 will be replaced by LZ4_ACCELERATION_DEFAULT (currently == 1, see lz4.c). + Values > LZ4_ACCELERATION_MAX will be replaced by LZ4_ACCELERATION_MAX (currently == 65537, see lz4.c). */ -int LZ4_compress_fast(const char *source, char *dest, int sourceSize, int maxDestSize, int acceleration); +LZ4LIB_API int LZ4_compress_fast (const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); -/* -LZ4_compress_fast_extState() : - Same compression function, just using an externally allocated memory space to store compression state. - Use LZ4_sizeofState() to know how much memory must be allocated, - and allocate it on 8-bytes boundaries (using malloc() typically). - Then, provide it as 'void* state' to compression function. -*/ -int LZ4_sizeofState(void); -int LZ4_compress_fast_extState(void *state, const char *source, char *dest, int inputSize, int maxDestSize, - int acceleration); -/* -LZ4_compress_destSize() : - Reverse the logic, by compressing as much data as possible from 'source' buffer - into already allocated buffer 'dest' of size 'targetDestSize'. - This function either compresses the entire 'source' content into 'dest' if it's large enough, - or fill 'dest' buffer completely with as much data as possible from 'source'. - *sourceSizePtr : will be modified to indicate how many bytes where read from 'source' to fill 'dest'. - New value is necessarily <= old value. - return : Nb bytes written into 'dest' (necessarily <= targetDestSize) - or 0 if compression fails -*/ -int LZ4_compress_destSize(const char *source, char *dest, int *sourceSizePtr, int targetDestSize); - -/* -LZ4_decompress_fast() : - originalSize : is the original and therefore uncompressed size - return : the number of bytes read from the source buffer (in other words, the compressed size) - If the source stream is detected malformed, the function will stop decoding and return a negative result. - Destination buffer must be already allocated. Its size must be a minimum of 'originalSize' bytes. - note : This function fully respect memory boundaries for properly formed compressed data. - It is a bit faster than LZ4_decompress_safe(). - However, it does not provide any protection against intentionally modified data stream (malicious input). - Use this function in trusted environment only (data to decode comes from a trusted source). -*/ -int LZ4_decompress_fast(const char *source, char *dest, int originalSize); - -/* -LZ4_decompress_safe_partial() : - This function decompress a compressed block of size 'compressedSize' at position 'source' - into destination buffer 'dest' of size 'maxDecompressedSize'. - The function tries to stop decompressing operation as soon as 'targetOutputSize' has been reached, - reducing decompression time. - return : the number of bytes decoded in the destination buffer (necessarily <= maxDecompressedSize) - Note : this number can be < 'targetOutputSize' should the compressed block to decode be smaller. - Always control how many bytes were decoded. - If the source stream is detected malformed, the function will stop decoding and return a negative result. - This function never writes outside of output buffer, and never reads outside of input buffer. It is -therefore protected against malicious data packets -*/ -int LZ4_decompress_safe_partial(const char *source, char *dest, int compressedSize, int targetOutputSize, - int maxDecompressedSize); - -/*********************************************** - * Streaming Compression Functions - ***********************************************/ -#define LZ4_STREAMSIZE_U64 ((1 << (LZ4_MEMORY_USAGE - 3)) + 4) -#define LZ4_STREAMSIZE (LZ4_STREAMSIZE_U64 * sizeof(long long)) -/* - * LZ4_stream_t - * information structure to track an LZ4 stream. - * important : init this structure content before first use ! - * note : only allocated directly the structure if you are statically linking LZ4 - * If you are using liblz4 as a DLL, please use below construction methods instead. +/*! LZ4_compress_fast_extState() : + * Same as LZ4_compress_fast(), using an externally allocated memory space for its state. + * Use LZ4_sizeofState() to know how much memory must be allocated, + * and allocate it on 8-bytes boundaries (using `malloc()` typically). + * Then, provide this buffer as `void* state` to compression function. */ -typedef struct -{ - long long table[LZ4_STREAMSIZE_U64]; -} LZ4_stream_t; +LZ4LIB_API int LZ4_sizeofState(void); +LZ4LIB_API int LZ4_compress_fast_extState (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); -/* - * LZ4_resetStream - * Use this function to init an allocated LZ4_stream_t structure - */ -void LZ4_resetStream(LZ4_stream_t *streamPtr); - -/* - * LZ4_createStream will allocate and initialize an LZ4_stream_t structure - * LZ4_freeStream releases its memory. - * In the context of a DLL (liblz4), please use these methods rather than the static struct. - * They are more future proof, in case of a change of LZ4_stream_t size. - */ -LZ4_stream_t *LZ4_createStream(void); -int LZ4_freeStream(LZ4_stream_t *streamPtr); - -/* - * LZ4_loadDict - * Use this function to load a static dictionary into LZ4_stream. - * Any previous data will be forgotten, only 'dictionary' will remain in memory. - * Loading a size of 0 is allowed. - * Return : dictionary size, in bytes (necessarily <= 64 KB) - */ -int LZ4_loadDict(LZ4_stream_t *streamPtr, const char *dictionary, int dictSize); - -/* - * LZ4_compress_fast_continue - * Compress buffer content 'src', using data from previously compressed blocks as dictionary to improve compression - * ratio. Important : Previous data blocks are assumed to still be present and unmodified ! 'dst' buffer must be already - * allocated. If maxDstSize >= LZ4_compressBound(srcSize), compression is guaranteed to succeed, and runs faster. If - * not, and if compressed data cannot fit into 'dst' buffer size, compression stops, and function returns a zero. - */ -int LZ4_compress_fast_continue(LZ4_stream_t *streamPtr, const char *src, char *dst, int srcSize, int maxDstSize, - int acceleration); - -/* - * LZ4_saveDict - * If previously compressed data block is not guaranteed to remain available at its memory location - * save it into a safer place (char* safeBuffer) - * Note : you don't need to call LZ4_loadDict() afterwards, - * dictionary is immediately usable, you can therefore call LZ4_compress_fast_continue() - * Return : saved dictionary size in bytes (necessarily <= dictSize), or 0 if error - */ -int LZ4_saveDict(LZ4_stream_t *streamPtr, char *safeBuffer, int dictSize); - -/************************************************ - * Streaming Decompression Functions - ************************************************/ - -#define LZ4_STREAMDECODESIZE_U64 4 -#define LZ4_STREAMDECODESIZE (LZ4_STREAMDECODESIZE_U64 * sizeof(unsigned long long)) -typedef struct -{ - unsigned long long table[LZ4_STREAMDECODESIZE_U64]; -} LZ4_streamDecode_t; -/* - * LZ4_streamDecode_t - * information structure to track an LZ4 stream. - * init this structure content using LZ4_setStreamDecode or memset() before first use ! +/*! LZ4_compress_destSize() : + * Reverse the logic : compresses as much data as possible from 'src' buffer + * into already allocated buffer 'dst', of size >= 'dstCapacity'. + * This function either compresses the entire 'src' content into 'dst' if it's large enough, + * or fill 'dst' buffer completely with as much data as possible from 'src'. + * note: acceleration parameter is fixed to "default". * - * In the context of a DLL (liblz4) please prefer usage of construction methods below. - * They are more future proof, in case of a change of LZ4_streamDecode_t size in the future. - * LZ4_createStreamDecode will allocate and initialize an LZ4_streamDecode_t structure - * LZ4_freeStreamDecode releases its memory. + * *srcSizePtr : in+out parameter. Initially contains size of input. + * Will be modified to indicate how many bytes where read from 'src' to fill 'dst'. + * New value is necessarily <= input value. + * @return : Nb bytes written into 'dst' (necessarily <= dstCapacity) + * or 0 if compression fails. + * + * Note : from v1.8.2 to v1.9.1, this function had a bug (fixed in v1.9.2+): + * the produced compressed content could, in specific circumstances, + * require to be decompressed into a destination buffer larger + * by at least 1 byte than the content to decompress. + * If an application uses `LZ4_compress_destSize()`, + * it's highly recommended to update liblz4 to v1.9.2 or better. + * If this can't be done or ensured, + * the receiving decompression function should provide + * a dstCapacity which is > decompressedSize, by at least 1 byte. + * See https://github.com/lz4/lz4/issues/859 for details */ -LZ4_streamDecode_t *LZ4_createStreamDecode(void); -int LZ4_freeStreamDecode(LZ4_streamDecode_t *LZ4_stream); +LZ4LIB_API int LZ4_compress_destSize(const char* src, char* dst, int* srcSizePtr, int targetDstSize); -/* - * LZ4_setStreamDecode - * Use this function to instruct where to find the dictionary. - * Setting a size of 0 is allowed (same effect as reset). - * Return : 1 if OK, 0 if error +/*! LZ4_decompress_safe_partial() : + * Decompress an LZ4 compressed block, of size 'srcSize' at position 'src', + * into destination buffer 'dst' of size 'dstCapacity'. + * Up to 'targetOutputSize' bytes will be decoded. + * The function stops decoding on reaching this objective. + * This can be useful to boost performance + * whenever only the beginning of a block is required. + * + * @return : the number of bytes decoded in `dst` (necessarily <= targetOutputSize) + * If source stream is detected malformed, function returns a negative result. + * + * Note 1 : @return can be < targetOutputSize, if compressed block contains less data. + * + * Note 2 : targetOutputSize must be <= dstCapacity + * + * Note 3 : this function effectively stops decoding on reaching targetOutputSize, + * so dstCapacity is kind of redundant. + * This is because in older versions of this function, + * decoding operation would still write complete sequences. + * Therefore, there was no guarantee that it would stop writing at exactly targetOutputSize, + * it could write more bytes, though only up to dstCapacity. + * Some "margin" used to be required for this operation to work properly. + * Thankfully, this is no longer necessary. + * The function nonetheless keeps the same signature, in an effort to preserve API compatibility. + * + * Note 4 : If srcSize is the exact size of the block, + * then targetOutputSize can be any value, + * including larger than the block's decompressed size. + * The function will, at most, generate block's decompressed size. + * + * Note 5 : If srcSize is _larger_ than block's compressed size, + * then targetOutputSize **MUST** be <= block's decompressed size. + * Otherwise, *silent corruption will occur*. */ -int LZ4_setStreamDecode(LZ4_streamDecode_t *LZ4_streamDecode, const char *dictionary, int dictSize); +LZ4LIB_API int LZ4_decompress_safe_partial (const char* src, char* dst, int srcSize, int targetOutputSize, int dstCapacity); -/* -*_continue() : - These decoding functions allow decompression of multiple blocks in "streaming" mode. - Previously decoded blocks *must* remain available at the memory position where they were decoded (up to 64 KB) - In the case of a ring buffers, decoding buffer must be either : - - Exactly same size as encoding buffer, with same update rule (block boundaries at same positions) - In which case, the decoding & encoding ring buffer can have any size, including very small ones ( < 64 KB). - - Larger than encoding buffer, by a minimum of maxBlockSize more bytes. - maxBlockSize is implementation dependent. It's the maximum size you intend to compress into a single block. - In which case, encoding and decoding buffers do not need to be synchronized, - and encoding ring buffer can have any size, including small ones ( < 64 KB). - - _At least_ 64 KB + 8 bytes + maxBlockSize. - In which case, encoding and decoding buffers do not need to be synchronized, - and encoding ring buffer can have any size, including larger than decoding buffer. - Whenever these conditions are not possible, save the last 64KB of decoded data into a safe buffer, - and indicate where it is saved using LZ4_setStreamDecode() + +/*-********************************************* +* Streaming Compression Functions +***********************************************/ +typedef union LZ4_stream_u LZ4_stream_t; /* incomplete type (defined later) */ + +/*! + Note about RC_INVOKED + + - RC_INVOKED is predefined symbol of rc.exe (the resource compiler which is part of MSVC/Visual Studio). + https://docs.microsoft.com/en-us/windows/win32/menurc/predefined-macros + + - Since rc.exe is a legacy compiler, it truncates long symbol (> 30 chars) + and reports warning "RC4011: identifier truncated". + + - To eliminate the warning, we surround long preprocessor symbol with + "#if !defined(RC_INVOKED) ... #endif" block that means + "skip this block when rc.exe is trying to read it". */ -int LZ4_decompress_safe_continue(LZ4_streamDecode_t *LZ4_streamDecode, const char *source, char *dest, - int compressedSize, int maxDecompressedSize); -int LZ4_decompress_fast_continue(LZ4_streamDecode_t *LZ4_streamDecode, const char *source, char *dest, - int originalSize); - -/* -Advanced decoding functions : -*_usingDict() : - These decoding functions work the same as - a combination of LZ4_setStreamDecode() followed by LZ4_decompress_x_continue() - They are stand-alone. They don't need nor update an LZ4_streamDecode_t structure. -*/ -int LZ4_decompress_safe_usingDict(const char *source, char *dest, int compressedSize, int maxDecompressedSize, - const char *dictStart, int dictSize); -int LZ4_decompress_fast_usingDict(const char *source, char *dest, int originalSize, const char *dictStart, - int dictSize); - -/************************************** - * Obsolete Functions - **************************************/ -/* Deprecate Warnings */ -/* Should these warnings messages be a problem, - it is generally possible to disable them, - with -Wno-deprecated-declarations for gcc - or _CRT_SECURE_NO_WARNINGS in Visual for example. - You can also define LZ4_DEPRECATE_WARNING_DEFBLOCK. */ -#ifndef LZ4_DEPRECATE_WARNING_DEFBLOCK -#define LZ4_DEPRECATE_WARNING_DEFBLOCK -#define LZ4_GCC_VERSION (__GNUC__ * 100 + __GNUC_MINOR__) -#if (LZ4_GCC_VERSION >= 405) || defined(__clang__) -#define LZ4_DEPRECATED(message) __attribute__((deprecated(message))) -#elif (LZ4_GCC_VERSION >= 301) -#define LZ4_DEPRECATED(message) __attribute__((deprecated)) -#elif defined(_MSC_VER) -#define LZ4_DEPRECATED(message) __declspec(deprecated(message)) -#else -#pragma message("WARNING: You need to implement LZ4_DEPRECATED for this compiler") -#define LZ4_DEPRECATED(message) +#if !defined(RC_INVOKED) /* https://docs.microsoft.com/en-us/windows/win32/menurc/predefined-macros */ +#if !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) +LZ4LIB_API LZ4_stream_t* LZ4_createStream(void); +LZ4LIB_API int LZ4_freeStream (LZ4_stream_t* streamPtr); +#endif /* !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) */ #endif -#endif /* LZ4_DEPRECATE_WARNING_DEFBLOCK */ -/* Obsolete compression functions */ -/* These functions are planned to start generate warnings by r131 approximately */ -int LZ4_compress(const char *source, char *dest, int sourceSize); -int LZ4_compress_limitedOutput(const char *source, char *dest, int sourceSize, int maxOutputSize); -int LZ4_compress_withState(void *state, const char *source, char *dest, int inputSize); -int LZ4_compress_limitedOutput_withState(void *state, const char *source, char *dest, int inputSize, int maxOutputSize); -int LZ4_compress_continue(LZ4_stream_t *LZ4_streamPtr, const char *source, char *dest, int inputSize); -int LZ4_compress_limitedOutput_continue(LZ4_stream_t *LZ4_streamPtr, const char *source, char *dest, int inputSize, - int maxOutputSize); +/*! LZ4_resetStream_fast() : v1.9.0+ + * Use this to prepare an LZ4_stream_t for a new chain of dependent blocks + * (e.g., LZ4_compress_fast_continue()). + * + * An LZ4_stream_t must be initialized once before usage. + * This is automatically done when created by LZ4_createStream(). + * However, should the LZ4_stream_t be simply declared on stack (for example), + * it's necessary to initialize it first, using LZ4_initStream(). + * + * After init, start any new stream with LZ4_resetStream_fast(). + * A same LZ4_stream_t can be re-used multiple times consecutively + * and compress multiple streams, + * provided that it starts each new stream with LZ4_resetStream_fast(). + * + * LZ4_resetStream_fast() is much faster than LZ4_initStream(), + * but is not compatible with memory regions containing garbage data. + * + * Note: it's only useful to call LZ4_resetStream_fast() + * in the context of streaming compression. + * The *extState* functions perform their own resets. + * Invoking LZ4_resetStream_fast() before is redundant, and even counterproductive. + */ +LZ4LIB_API void LZ4_resetStream_fast (LZ4_stream_t* streamPtr); -/* Obsolete decompression functions */ -/* These function names are completely deprecated and must no longer be used. - They are only provided here for compatibility with older programs. - - LZ4_uncompress is the same as LZ4_decompress_fast - - LZ4_uncompress_unknownOutputSize is the same as LZ4_decompress_safe - These function prototypes are now disabled; uncomment them only if you really need them. - It is highly recommended to stop using these prototypes and migrate to maintained ones */ -/* int LZ4_uncompress (const char* source, char* dest, int outputSize); */ -/* int LZ4_uncompress_unknownOutputSize (const char* source, char* dest, int isize, int maxOutputSize); */ +/*! LZ4_loadDict() : + * Use this function to reference a static dictionary into LZ4_stream_t. + * The dictionary must remain available during compression. + * LZ4_loadDict() triggers a reset, so any previous data will be forgotten. + * The same dictionary will have to be loaded on decompression side for successful decoding. + * Dictionary are useful for better compression of small data (KB range). + * While LZ4 itself accepts any input as dictionary, dictionary efficiency is also a topic. + * When in doubt, employ the Zstandard's Dictionary Builder. + * Loading a size of 0 is allowed, and is the same as reset. + * @return : loaded dictionary size, in bytes (note: only the last 64 KB are loaded) + */ +LZ4LIB_API int LZ4_loadDict (LZ4_stream_t* streamPtr, const char* dictionary, int dictSize); -/* Obsolete streaming functions; use new streaming interface whenever possible */ -LZ4_DEPRECATED("use LZ4_createStream() instead") void *LZ4_create(char *inputBuffer); -LZ4_DEPRECATED("use LZ4_createStream() instead") int LZ4_sizeofStreamState(void); -LZ4_DEPRECATED("use LZ4_resetStream() instead") int LZ4_resetStreamState(void *state, char *inputBuffer); -LZ4_DEPRECATED("use LZ4_saveDict() instead") char *LZ4_slideInputBuffer(void *state); +/*! LZ4_compress_fast_continue() : + * Compress 'src' content using data from previously compressed blocks, for better compression ratio. + * 'dst' buffer must be already allocated. + * If dstCapacity >= LZ4_compressBound(srcSize), compression is guaranteed to succeed, and runs faster. + * + * @return : size of compressed block + * or 0 if there is an error (typically, cannot fit into 'dst'). + * + * Note 1 : Each invocation to LZ4_compress_fast_continue() generates a new block. + * Each block has precise boundaries. + * Each block must be decompressed separately, calling LZ4_decompress_*() with relevant metadata. + * It's not possible to append blocks together and expect a single invocation of LZ4_decompress_*() to decompress them together. + * + * Note 2 : The previous 64KB of source data is __assumed__ to remain present, unmodified, at same address in memory ! + * + * Note 3 : When input is structured as a double-buffer, each buffer can have any size, including < 64 KB. + * Make sure that buffers are separated, by at least one byte. + * This construction ensures that each block only depends on previous block. + * + * Note 4 : If input buffer is a ring-buffer, it can have any size, including < 64 KB. + * + * Note 5 : After an error, the stream status is undefined (invalid), it can only be reset or freed. + */ +LZ4LIB_API int LZ4_compress_fast_continue (LZ4_stream_t* streamPtr, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); -/* Obsolete streaming decoding functions */ -LZ4_DEPRECATED("use LZ4_decompress_safe_usingDict() instead") -int LZ4_decompress_safe_withPrefix64k(const char *src, char *dst, int compressedSize, int maxDstSize); -LZ4_DEPRECATED("use LZ4_decompress_fast_usingDict() instead") -int LZ4_decompress_fast_withPrefix64k(const char *src, char *dst, int originalSize); +/*! LZ4_saveDict() : + * If last 64KB data cannot be guaranteed to remain available at its current memory location, + * save it into a safer place (char* safeBuffer). + * This is schematically equivalent to a memcpy() followed by LZ4_loadDict(), + * but is much faster, because LZ4_saveDict() doesn't need to rebuild tables. + * @return : saved dictionary size in bytes (necessarily <= maxDictSize), or 0 if error. + */ +LZ4LIB_API int LZ4_saveDict (LZ4_stream_t* streamPtr, char* safeBuffer, int maxDictSize); -#if defined(__cplusplus) + +/*-********************************************** +* Streaming Decompression Functions +* Bufferless synchronous API +************************************************/ +typedef union LZ4_streamDecode_u LZ4_streamDecode_t; /* tracking context */ + +/*! LZ4_createStreamDecode() and LZ4_freeStreamDecode() : + * creation / destruction of streaming decompression tracking context. + * A tracking context can be re-used multiple times. + */ +#if !defined(RC_INVOKED) /* https://docs.microsoft.com/en-us/windows/win32/menurc/predefined-macros */ +#if !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) +LZ4LIB_API LZ4_streamDecode_t* LZ4_createStreamDecode(void); +LZ4LIB_API int LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream); +#endif /* !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) */ +#endif + +/*! LZ4_setStreamDecode() : + * An LZ4_streamDecode_t context can be allocated once and re-used multiple times. + * Use this function to start decompression of a new stream of blocks. + * A dictionary can optionally be set. Use NULL or size 0 for a reset order. + * Dictionary is presumed stable : it must remain accessible and unmodified during next decompression. + * @return : 1 if OK, 0 if error + */ +LZ4LIB_API int LZ4_setStreamDecode (LZ4_streamDecode_t* LZ4_streamDecode, const char* dictionary, int dictSize); + +/*! LZ4_decoderRingBufferSize() : v1.8.2+ + * Note : in a ring buffer scenario (optional), + * blocks are presumed decompressed next to each other + * up to the moment there is not enough remaining space for next block (remainingSize < maxBlockSize), + * at which stage it resumes from beginning of ring buffer. + * When setting such a ring buffer for streaming decompression, + * provides the minimum size of this ring buffer + * to be compatible with any source respecting maxBlockSize condition. + * @return : minimum ring buffer size, + * or 0 if there is an error (invalid maxBlockSize). + */ +LZ4LIB_API int LZ4_decoderRingBufferSize(int maxBlockSize); +#define LZ4_DECODER_RING_BUFFER_SIZE(maxBlockSize) (65536 + 14 + (maxBlockSize)) /* for static allocation; maxBlockSize presumed valid */ + +/*! LZ4_decompress_safe_continue() : + * This decoding function allows decompression of consecutive blocks in "streaming" mode. + * The difference with the usual independent blocks is that + * new blocks are allowed to find references into former blocks. + * A block is an unsplittable entity, and must be presented entirely to the decompression function. + * LZ4_decompress_safe_continue() only accepts one block at a time. + * It's modeled after `LZ4_decompress_safe()` and behaves similarly. + * + * @LZ4_streamDecode : decompression state, tracking the position in memory of past data + * @compressedSize : exact complete size of one compressed block. + * @dstCapacity : size of destination buffer (which must be already allocated), + * must be an upper bound of decompressed size. + * @return : number of bytes decompressed into destination buffer (necessarily <= dstCapacity) + * If destination buffer is not large enough, decoding will stop and output an error code (negative value). + * If the source stream is detected malformed, the function will stop decoding and return a negative result. + * + * The last 64KB of previously decoded data *must* remain available and unmodified + * at the memory position where they were previously decoded. + * If less than 64KB of data has been decoded, all the data must be present. + * + * Special : if decompression side sets a ring buffer, it must respect one of the following conditions : + * - Decompression buffer size is _at least_ LZ4_decoderRingBufferSize(maxBlockSize). + * maxBlockSize is the maximum size of any single block. It can have any value > 16 bytes. + * In which case, encoding and decoding buffers do not need to be synchronized. + * Actually, data can be produced by any source compliant with LZ4 format specification, and respecting maxBlockSize. + * - Synchronized mode : + * Decompression buffer size is _exactly_ the same as compression buffer size, + * and follows exactly same update rule (block boundaries at same positions), + * and decoding function is provided with exact decompressed size of each block (exception for last block of the stream), + * _then_ decoding & encoding ring buffer can have any size, including small ones ( < 64 KB). + * - Decompression buffer is larger than encoding buffer, by a minimum of maxBlockSize more bytes. + * In which case, encoding and decoding buffers do not need to be synchronized, + * and encoding ring buffer can have any size, including small ones ( < 64 KB). + * + * Whenever these conditions are not possible, + * save the last 64KB of decoded data into a safe buffer where it can't be modified during decompression, + * then indicate where this data is saved using LZ4_setStreamDecode(), before decompressing next block. +*/ +LZ4LIB_API int +LZ4_decompress_safe_continue (LZ4_streamDecode_t* LZ4_streamDecode, + const char* src, char* dst, + int srcSize, int dstCapacity); + + +/*! LZ4_decompress_safe_usingDict() : + * Works the same as + * a combination of LZ4_setStreamDecode() followed by LZ4_decompress_safe_continue() + * However, it's stateless: it doesn't need any LZ4_streamDecode_t state. + * Dictionary is presumed stable : it must remain accessible and unmodified during decompression. + * Performance tip : Decompression speed can be substantially increased + * when dst == dictStart + dictSize. + */ +LZ4LIB_API int +LZ4_decompress_safe_usingDict(const char* src, char* dst, + int srcSize, int dstCapacity, + const char* dictStart, int dictSize); + +/*! LZ4_decompress_safe_partial_usingDict() : + * Behaves the same as LZ4_decompress_safe_partial() + * with the added ability to specify a memory segment for past data. + * Performance tip : Decompression speed can be substantially increased + * when dst == dictStart + dictSize. + */ +LZ4LIB_API int +LZ4_decompress_safe_partial_usingDict(const char* src, char* dst, + int compressedSize, + int targetOutputSize, int maxOutputSize, + const char* dictStart, int dictSize); + +#endif /* LZ4_H_2983827168210 */ + + +/*^************************************* + * !!!!!! STATIC LINKING ONLY !!!!!! + ***************************************/ + +/*-**************************************************************************** + * Experimental section + * + * Symbols declared in this section must be considered unstable. Their + * signatures or semantics may change, or they may be removed altogether in the + * future. They are therefore only safe to depend on when the caller is + * statically linked against the library. + * + * To protect against unsafe usage, not only are the declarations guarded, + * the definitions are hidden by default + * when building LZ4 as a shared/dynamic library. + * + * In order to access these declarations, + * define LZ4_STATIC_LINKING_ONLY in your application + * before including LZ4's headers. + * + * In order to make their implementations accessible dynamically, you must + * define LZ4_PUBLISH_STATIC_FUNCTIONS when building the LZ4 library. + ******************************************************************************/ + +#ifdef LZ4_STATIC_LINKING_ONLY + +#ifndef LZ4_STATIC_3504398509 +#define LZ4_STATIC_3504398509 + +#ifdef LZ4_PUBLISH_STATIC_FUNCTIONS +# define LZ4LIB_STATIC_API LZ4LIB_API +#else +# define LZ4LIB_STATIC_API +#endif + + +/*! LZ4_compress_fast_extState_fastReset() : + * A variant of LZ4_compress_fast_extState(). + * + * Using this variant avoids an expensive initialization step. + * It is only safe to call if the state buffer is known to be correctly initialized already + * (see above comment on LZ4_resetStream_fast() for a definition of "correctly initialized"). + * From a high level, the difference is that + * this function initializes the provided state with a call to something like LZ4_resetStream_fast() + * while LZ4_compress_fast_extState() starts with a call to LZ4_resetStream(). + */ +LZ4LIB_STATIC_API int LZ4_compress_fast_extState_fastReset (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); + +/*! LZ4_compress_destSize_extState() : + * Same as LZ4_compress_destSize(), but using an externally allocated state. + * Also: exposes @acceleration + */ +int LZ4_compress_destSize_extState(void* state, const char* src, char* dst, int* srcSizePtr, int targetDstSize, int acceleration); + +/*! LZ4_attach_dictionary() : + * This is an experimental API that allows + * efficient use of a static dictionary many times. + * + * Rather than re-loading the dictionary buffer into a working context before + * each compression, or copying a pre-loaded dictionary's LZ4_stream_t into a + * working LZ4_stream_t, this function introduces a no-copy setup mechanism, + * in which the working stream references the dictionary stream in-place. + * + * Several assumptions are made about the state of the dictionary stream. + * Currently, only streams which have been prepared by LZ4_loadDict() should + * be expected to work. + * + * Alternatively, the provided dictionaryStream may be NULL, + * in which case any existing dictionary stream is unset. + * + * If a dictionary is provided, it replaces any pre-existing stream history. + * The dictionary contents are the only history that can be referenced and + * logically immediately precede the data compressed in the first subsequent + * compression call. + * + * The dictionary will only remain attached to the working stream through the + * first compression call, at the end of which it is cleared. The dictionary + * stream (and source buffer) must remain in-place / accessible / unchanged + * through the completion of the first compression call on the stream. + */ +LZ4LIB_STATIC_API void +LZ4_attach_dictionary(LZ4_stream_t* workingStream, + const LZ4_stream_t* dictionaryStream); + + +/*! In-place compression and decompression + * + * It's possible to have input and output sharing the same buffer, + * for highly constrained memory environments. + * In both cases, it requires input to lay at the end of the buffer, + * and decompression to start at beginning of the buffer. + * Buffer size must feature some margin, hence be larger than final size. + * + * |<------------------------buffer--------------------------------->| + * |<-----------compressed data--------->| + * |<-----------decompressed size------------------>| + * |<----margin---->| + * + * This technique is more useful for decompression, + * since decompressed size is typically larger, + * and margin is short. + * + * In-place decompression will work inside any buffer + * which size is >= LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize). + * This presumes that decompressedSize > compressedSize. + * Otherwise, it means compression actually expanded data, + * and it would be more efficient to store such data with a flag indicating it's not compressed. + * This can happen when data is not compressible (already compressed, or encrypted). + * + * For in-place compression, margin is larger, as it must be able to cope with both + * history preservation, requiring input data to remain unmodified up to LZ4_DISTANCE_MAX, + * and data expansion, which can happen when input is not compressible. + * As a consequence, buffer size requirements are much higher, + * and memory savings offered by in-place compression are more limited. + * + * There are ways to limit this cost for compression : + * - Reduce history size, by modifying LZ4_DISTANCE_MAX. + * Note that it is a compile-time constant, so all compressions will apply this limit. + * Lower values will reduce compression ratio, except when input_size < LZ4_DISTANCE_MAX, + * so it's a reasonable trick when inputs are known to be small. + * - Require the compressor to deliver a "maximum compressed size". + * This is the `dstCapacity` parameter in `LZ4_compress*()`. + * When this size is < LZ4_COMPRESSBOUND(inputSize), then compression can fail, + * in which case, the return code will be 0 (zero). + * The caller must be ready for these cases to happen, + * and typically design a backup scheme to send data uncompressed. + * The combination of both techniques can significantly reduce + * the amount of margin required for in-place compression. + * + * In-place compression can work in any buffer + * which size is >= (maxCompressedSize) + * with maxCompressedSize == LZ4_COMPRESSBOUND(srcSize) for guaranteed compression success. + * LZ4_COMPRESS_INPLACE_BUFFER_SIZE() depends on both maxCompressedSize and LZ4_DISTANCE_MAX, + * so it's possible to reduce memory requirements by playing with them. + */ + +#define LZ4_DECOMPRESS_INPLACE_MARGIN(compressedSize) (((compressedSize) >> 8) + 32) +#define LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize) ((decompressedSize) + LZ4_DECOMPRESS_INPLACE_MARGIN(decompressedSize)) /**< note: presumes that compressedSize < decompressedSize. note2: margin is overestimated a bit, since it could use compressedSize instead */ + +#ifndef LZ4_DISTANCE_MAX /* history window size; can be user-defined at compile time */ +# define LZ4_DISTANCE_MAX 65535 /* set to maximum value by default */ +#endif + +#define LZ4_COMPRESS_INPLACE_MARGIN (LZ4_DISTANCE_MAX + 32) /* LZ4_DISTANCE_MAX can be safely replaced by srcSize when it's smaller */ +#define LZ4_COMPRESS_INPLACE_BUFFER_SIZE(maxCompressedSize) ((maxCompressedSize) + LZ4_COMPRESS_INPLACE_MARGIN) /**< maxCompressedSize is generally LZ4_COMPRESSBOUND(inputSize), but can be set to any lower value, with the risk that compression can fail (return code 0(zero)) */ + +#endif /* LZ4_STATIC_3504398509 */ +#endif /* LZ4_STATIC_LINKING_ONLY */ + + + +#ifndef LZ4_H_98237428734687 +#define LZ4_H_98237428734687 + +/*-************************************************************ + * Private Definitions + ************************************************************** + * Do not use these definitions directly. + * They are only exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`. + * Accessing members will expose user code to API and/or ABI break in future versions of the library. + **************************************************************/ +#define LZ4_HASHLOG (LZ4_MEMORY_USAGE-2) +#define LZ4_HASHTABLESIZE (1 << LZ4_MEMORY_USAGE) +#define LZ4_HASH_SIZE_U32 (1 << LZ4_HASHLOG) /* required as macro for static allocation */ + +#if defined(__cplusplus) || (defined (__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 */) +# include + typedef int8_t LZ4_i8; + typedef uint8_t LZ4_byte; + typedef uint16_t LZ4_u16; + typedef uint32_t LZ4_u32; +#else + typedef signed char LZ4_i8; + typedef unsigned char LZ4_byte; + typedef unsigned short LZ4_u16; + typedef unsigned int LZ4_u32; +#endif + +/*! LZ4_stream_t : + * Never ever use below internal definitions directly ! + * These definitions are not API/ABI safe, and may change in future versions. + * If you need static allocation, declare or allocate an LZ4_stream_t object. +**/ + +typedef struct LZ4_stream_t_internal LZ4_stream_t_internal; +struct LZ4_stream_t_internal { + LZ4_u32 hashTable[LZ4_HASH_SIZE_U32]; + const LZ4_byte* dictionary; + const LZ4_stream_t_internal* dictCtx; + LZ4_u32 currentOffset; + LZ4_u32 tableType; + LZ4_u32 dictSize; + /* Implicit padding to ensure structure is aligned */ +}; + +#define LZ4_STREAM_MINSIZE ((1UL << (LZ4_MEMORY_USAGE)) + 32) /* static size, for inter-version compatibility */ +union LZ4_stream_u { + char minStateSize[LZ4_STREAM_MINSIZE]; + LZ4_stream_t_internal internal_donotuse; +}; /* previously typedef'd to LZ4_stream_t */ + + +/*! LZ4_initStream() : v1.9.0+ + * An LZ4_stream_t structure must be initialized at least once. + * This is automatically done when invoking LZ4_createStream(), + * but it's not when the structure is simply declared on stack (for example). + * + * Use LZ4_initStream() to properly initialize a newly declared LZ4_stream_t. + * It can also initialize any arbitrary buffer of sufficient size, + * and will @return a pointer of proper type upon initialization. + * + * Note : initialization fails if size and alignment conditions are not respected. + * In which case, the function will @return NULL. + * Note2: An LZ4_stream_t structure guarantees correct alignment and size. + * Note3: Before v1.9.0, use LZ4_resetStream() instead +**/ +LZ4LIB_API LZ4_stream_t* LZ4_initStream (void* stateBuffer, size_t size); + + +/*! LZ4_streamDecode_t : + * Never ever use below internal definitions directly ! + * These definitions are not API/ABI safe, and may change in future versions. + * If you need static allocation, declare or allocate an LZ4_streamDecode_t object. +**/ +typedef struct { + const LZ4_byte* externalDict; + const LZ4_byte* prefixEnd; + size_t extDictSize; + size_t prefixSize; +} LZ4_streamDecode_t_internal; + +#define LZ4_STREAMDECODE_MINSIZE 32 +union LZ4_streamDecode_u { + char minStateSize[LZ4_STREAMDECODE_MINSIZE]; + LZ4_streamDecode_t_internal internal_donotuse; +} ; /* previously typedef'd to LZ4_streamDecode_t */ + + + +/*-************************************ +* Obsolete Functions +**************************************/ + +/*! Deprecation warnings + * + * Deprecated functions make the compiler generate a warning when invoked. + * This is meant to invite users to update their source code. + * Should deprecation warnings be a problem, it is generally possible to disable them, + * typically with -Wno-deprecated-declarations for gcc + * or _CRT_SECURE_NO_WARNINGS in Visual. + * + * Another method is to define LZ4_DISABLE_DEPRECATE_WARNINGS + * before including the header file. + */ +#ifdef LZ4_DISABLE_DEPRECATE_WARNINGS +# define LZ4_DEPRECATED(message) /* disable deprecation warnings */ +#else +# if defined (__cplusplus) && (__cplusplus >= 201402) /* C++14 or greater */ +# define LZ4_DEPRECATED(message) [[deprecated(message)]] +# elif defined(_MSC_VER) +# define LZ4_DEPRECATED(message) __declspec(deprecated(message)) +# elif defined(__clang__) || (defined(__GNUC__) && (__GNUC__ * 10 + __GNUC_MINOR__ >= 45)) +# define LZ4_DEPRECATED(message) __attribute__((deprecated(message))) +# elif defined(__GNUC__) && (__GNUC__ * 10 + __GNUC_MINOR__ >= 31) +# define LZ4_DEPRECATED(message) __attribute__((deprecated)) +# else +# pragma message("WARNING: LZ4_DEPRECATED needs custom implementation for this compiler") +# define LZ4_DEPRECATED(message) /* disabled */ +# endif +#endif /* LZ4_DISABLE_DEPRECATE_WARNINGS */ + +/*! Obsolete compression functions (since v1.7.3) */ +LZ4_DEPRECATED("use LZ4_compress_default() instead") LZ4LIB_API int LZ4_compress (const char* src, char* dest, int srcSize); +LZ4_DEPRECATED("use LZ4_compress_default() instead") LZ4LIB_API int LZ4_compress_limitedOutput (const char* src, char* dest, int srcSize, int maxOutputSize); +LZ4_DEPRECATED("use LZ4_compress_fast_extState() instead") LZ4LIB_API int LZ4_compress_withState (void* state, const char* source, char* dest, int inputSize); +LZ4_DEPRECATED("use LZ4_compress_fast_extState() instead") LZ4LIB_API int LZ4_compress_limitedOutput_withState (void* state, const char* source, char* dest, int inputSize, int maxOutputSize); +LZ4_DEPRECATED("use LZ4_compress_fast_continue() instead") LZ4LIB_API int LZ4_compress_continue (LZ4_stream_t* LZ4_streamPtr, const char* source, char* dest, int inputSize); +LZ4_DEPRECATED("use LZ4_compress_fast_continue() instead") LZ4LIB_API int LZ4_compress_limitedOutput_continue (LZ4_stream_t* LZ4_streamPtr, const char* source, char* dest, int inputSize, int maxOutputSize); + +/*! Obsolete decompression functions (since v1.8.0) */ +LZ4_DEPRECATED("use LZ4_decompress_fast() instead") LZ4LIB_API int LZ4_uncompress (const char* source, char* dest, int outputSize); +LZ4_DEPRECATED("use LZ4_decompress_safe() instead") LZ4LIB_API int LZ4_uncompress_unknownOutputSize (const char* source, char* dest, int isize, int maxOutputSize); + +/* Obsolete streaming functions (since v1.7.0) + * degraded functionality; do not use! + * + * In order to perform streaming compression, these functions depended on data + * that is no longer tracked in the state. They have been preserved as well as + * possible: using them will still produce a correct output. However, they don't + * actually retain any history between compression calls. The compression ratio + * achieved will therefore be no better than compressing each chunk + * independently. + */ +LZ4_DEPRECATED("Use LZ4_createStream() instead") LZ4LIB_API void* LZ4_create (char* inputBuffer); +LZ4_DEPRECATED("Use LZ4_createStream() instead") LZ4LIB_API int LZ4_sizeofStreamState(void); +LZ4_DEPRECATED("Use LZ4_resetStream() instead") LZ4LIB_API int LZ4_resetStreamState(void* state, char* inputBuffer); +LZ4_DEPRECATED("Use LZ4_saveDict() instead") LZ4LIB_API char* LZ4_slideInputBuffer (void* state); + +/*! Obsolete streaming decoding functions (since v1.7.0) */ +LZ4_DEPRECATED("use LZ4_decompress_safe_usingDict() instead") LZ4LIB_API int LZ4_decompress_safe_withPrefix64k (const char* src, char* dst, int compressedSize, int maxDstSize); +LZ4_DEPRECATED("use LZ4_decompress_fast_usingDict() instead") LZ4LIB_API int LZ4_decompress_fast_withPrefix64k (const char* src, char* dst, int originalSize); + +/*! Obsolete LZ4_decompress_fast variants (since v1.9.0) : + * These functions used to be faster than LZ4_decompress_safe(), + * but this is no longer the case. They are now slower. + * This is because LZ4_decompress_fast() doesn't know the input size, + * and therefore must progress more cautiously into the input buffer to not read beyond the end of block. + * On top of that `LZ4_decompress_fast()` is not protected vs malformed or malicious inputs, making it a security liability. + * As a consequence, LZ4_decompress_fast() is strongly discouraged, and deprecated. + * + * The last remaining LZ4_decompress_fast() specificity is that + * it can decompress a block without knowing its compressed size. + * Such functionality can be achieved in a more secure manner + * by employing LZ4_decompress_safe_partial(). + * + * Parameters: + * originalSize : is the uncompressed size to regenerate. + * `dst` must be already allocated, its size must be >= 'originalSize' bytes. + * @return : number of bytes read from source buffer (== compressed size). + * The function expects to finish at block's end exactly. + * If the source stream is detected malformed, the function stops decoding and returns a negative result. + * note : LZ4_decompress_fast*() requires originalSize. Thanks to this information, it never writes past the output buffer. + * However, since it doesn't know its 'src' size, it may read an unknown amount of input, past input buffer bounds. + * Also, since match offsets are not validated, match reads from 'src' may underflow too. + * These issues never happen if input (compressed) data is correct. + * But they may happen if input data is invalid (error or intentional tampering). + * As a consequence, use these functions in trusted environments with trusted data **only**. + */ +LZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe_partial() instead") +LZ4LIB_API int LZ4_decompress_fast (const char* src, char* dst, int originalSize); +LZ4_DEPRECATED("This function is deprecated and unsafe. Consider migrating towards LZ4_decompress_safe_continue() instead. " + "Note that the contract will change (requires block's compressed size, instead of decompressed size)") +LZ4LIB_API int LZ4_decompress_fast_continue (LZ4_streamDecode_t* LZ4_streamDecode, const char* src, char* dst, int originalSize); +LZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe_partial_usingDict() instead") +LZ4LIB_API int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize, const char* dictStart, int dictSize); + +/*! LZ4_resetStream() : + * An LZ4_stream_t structure must be initialized at least once. + * This is done with LZ4_initStream(), or LZ4_resetStream(). + * Consider switching to LZ4_initStream(), + * invoking LZ4_resetStream() will trigger deprecation warnings in the future. + */ +LZ4LIB_API void LZ4_resetStream (LZ4_stream_t* streamPtr); + + +#endif /* LZ4_H_98237428734687 */ + + +#if defined (__cplusplus) } #endif From c4a0845207b2931ebe0abf7cffbf7f52f80f484b Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 17 Oct 2024 07:05:23 +1300 Subject: [PATCH 095/496] libs/fst: Fix filename references --- libs/fst/00_UPDATE.sh | 3 +++ libs/fst/fastlz.cc | 4 ++-- libs/fst/fstapi.cc | 2 +- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/libs/fst/00_UPDATE.sh b/libs/fst/00_UPDATE.sh index 684e16a1d..db97fd8bb 100755 --- a/libs/fst/00_UPDATE.sh +++ b/libs/fst/00_UPDATE.sh @@ -11,3 +11,6 @@ for src in *.c; do mv -- "$src" "${src%.c}.cc" done mv config.h.bak config.h + +sed -i -e 's,,"config.h",' *.cc *.h +sed -i -e 's,"fastlz.c","fastlz.cc",' *.cc *.h diff --git a/libs/fst/fastlz.cc b/libs/fst/fastlz.cc index b52a799b9..3272ca7a8 100644 --- a/libs/fst/fastlz.cc +++ b/libs/fst/fastlz.cc @@ -108,7 +108,7 @@ int fastlz_decompress(const void* input, int length, void* output, int maxout); #define FASTLZ_DECOMPRESSOR fastlz1_decompress static FASTLZ_INLINE int FASTLZ_COMPRESSOR(const void* input, int length, void* output); static FASTLZ_INLINE int FASTLZ_DECOMPRESSOR(const void* input, int length, void* output, int maxout); -#include "fastlz.c" +#include "fastlz.cc" #undef FASTLZ_LEVEL #define FASTLZ_LEVEL 2 @@ -123,7 +123,7 @@ static FASTLZ_INLINE int FASTLZ_DECOMPRESSOR(const void* input, int length, void #define FASTLZ_DECOMPRESSOR fastlz2_decompress static FASTLZ_INLINE int FASTLZ_COMPRESSOR(const void* input, int length, void* output); static FASTLZ_INLINE int FASTLZ_DECOMPRESSOR(const void* input, int length, void* output, int maxout); -#include "fastlz.c" +#include "fastlz.cc" int fastlz_compress(const void* input, int length, void* output) { diff --git a/libs/fst/fstapi.cc b/libs/fst/fstapi.cc index 7bc7fd821..b77745900 100644 --- a/libs/fst/fstapi.cc +++ b/libs/fst/fstapi.cc @@ -39,7 +39,7 @@ */ #ifndef FST_CONFIG_INCLUDE -# define FST_CONFIG_INCLUDE +# define FST_CONFIG_INCLUDE "config.h" #endif #include FST_CONFIG_INCLUDE From a54721aa3931ddb527b7a21409b9b4db34096ef7 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 17 Oct 2024 07:05:23 +1300 Subject: [PATCH 096/496] libs/fst: Patch for zlib on windows --- libs/fst/00_PATCH_win_zlib.patch | 16 ++++++++++++++++ libs/fst/00_UPDATE.sh | 2 ++ libs/fst/fstapi.h | 3 ++- 3 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 libs/fst/00_PATCH_win_zlib.patch diff --git a/libs/fst/00_PATCH_win_zlib.patch b/libs/fst/00_PATCH_win_zlib.patch new file mode 100644 index 000000000..125e7cf58 --- /dev/null +++ b/libs/fst/00_PATCH_win_zlib.patch @@ -0,0 +1,16 @@ +--- fstapi.h ++++ fstapi.h +@@ -33,11 +33,12 @@ extern "C" { + #include + #include + #include +-#include + #include + #if defined(_MSC_VER) ++ #include "libs/zlib/zlib.h" + #include "fst_win_unistd.h" + #else ++ #include + #include + #endif + #include diff --git a/libs/fst/00_UPDATE.sh b/libs/fst/00_UPDATE.sh index db97fd8bb..f7066076f 100755 --- a/libs/fst/00_UPDATE.sh +++ b/libs/fst/00_UPDATE.sh @@ -14,3 +14,5 @@ mv config.h.bak config.h sed -i -e 's,,"config.h",' *.cc *.h sed -i -e 's,"fastlz.c","fastlz.cc",' *.cc *.h + +patch -p0 < 00_PATCH_win_zlib.patch diff --git a/libs/fst/fstapi.h b/libs/fst/fstapi.h index e2ca1783a..ba58c2017 100644 --- a/libs/fst/fstapi.h +++ b/libs/fst/fstapi.h @@ -33,11 +33,12 @@ extern "C" { #include #include #include -#include #include #if defined(_MSC_VER) + #include "libs/zlib/zlib.h" #include "fst_win_unistd.h" #else + #include #include #endif #include From 1055e8ce51167236ffc59c8ecc45bb780f5f6e5c Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 17 Oct 2024 07:05:23 +1300 Subject: [PATCH 097/496] libs/fst: Add fst_win_unistd.h to srcfiles.txt --- Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/Makefile b/Makefile index 91f48921e..350cc8989 100644 --- a/Makefile +++ b/Makefile @@ -1097,6 +1097,7 @@ vcxsrc: $(GENFILES) $(EXTRA_TARGETS) rm -rf yosys-win32-vcxsrc-$(YOSYS_VER){,.zip} set -e; for f in `ls $(filter %.cc %.cpp,$(GENFILES)) $(addsuffix .cc,$(basename $(OBJS))) $(addsuffix .cpp,$(basename $(OBJS))) 2> /dev/null`; do \ echo "Analyse: $$f" >&2; cpp -std=c++17 -MM -I. -D_YOSYS_ $$f; done | sed 's,.*:,,; s,//*,/,g; s,/[^/]*/\.\./,/,g; y, \\,\n\n,;' | grep '^[^/]' | sort -u | grep -v kernel/version_ > srcfiles.txt + echo "libs/fst/fst_win_unistd.h" >> srcfiles.txt bash misc/create_vcxsrc.sh yosys-win32-vcxsrc $(YOSYS_VER) $(GIT_REV) echo "namespace Yosys { extern const char *yosys_version_str; const char *yosys_version_str=\"Yosys (Version Information Unavailable)\"; }" > kernel/version.cc zip yosys-win32-vcxsrc-$(YOSYS_VER)/genfiles.zip $(GENFILES) kernel/version.cc From 5f83d4d9da90f4964f9f258ff3f40dc838e967f0 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 17 Oct 2024 07:05:23 +1300 Subject: [PATCH 098/496] libs/fst: Patch I think what's happening here is that the _WIN64 fix is correct for 64bit windows, but (for whatever reason) the visual studio build is targeting 32bit windows, so the fix is unnecessary, but the upstream fix doesn't expect to be targeting 32bit windows and assumes all windows builds are 64bit... so fix that. --- libs/fst/00_PATCH_win_io.patch | 11 +++++++++++ libs/fst/00_UPDATE.sh | 1 + libs/fst/fst_win_unistd.h | 2 +- 3 files changed, 13 insertions(+), 1 deletion(-) create mode 100644 libs/fst/00_PATCH_win_io.patch diff --git a/libs/fst/00_PATCH_win_io.patch b/libs/fst/00_PATCH_win_io.patch new file mode 100644 index 000000000..5813758cd --- /dev/null +++ b/libs/fst/00_PATCH_win_io.patch @@ -0,0 +1,11 @@ +--- fst_win_unistd.h ++++ fst_win_unistd.h +@@ -26,7 +26,7 @@ + #define WIN_UNISTD_H + + #include +-#ifdef _WIN64 ++#if defined(_MSC_VER) + #include + #else + #include diff --git a/libs/fst/00_UPDATE.sh b/libs/fst/00_UPDATE.sh index f7066076f..aef0e4fe8 100755 --- a/libs/fst/00_UPDATE.sh +++ b/libs/fst/00_UPDATE.sh @@ -16,3 +16,4 @@ sed -i -e 's,,"config.h",' *.cc *.h sed -i -e 's,"fastlz.c","fastlz.cc",' *.cc *.h patch -p0 < 00_PATCH_win_zlib.patch +patch -p0 < 00_PATCH_win_io.patch diff --git a/libs/fst/fst_win_unistd.h b/libs/fst/fst_win_unistd.h index 15ab2c1fc..089f0180b 100644 --- a/libs/fst/fst_win_unistd.h +++ b/libs/fst/fst_win_unistd.h @@ -26,7 +26,7 @@ #define WIN_UNISTD_H #include -#ifdef _WIN64 +#if defined(_MSC_VER) #include #else #include From 827e5baca717d9ff0736efb91e8e2bd0cf009b69 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 17 Oct 2024 07:05:23 +1300 Subject: [PATCH 099/496] libs/fst: Update from upstream --- libs/fst/fstapi.cc | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/libs/fst/fstapi.cc b/libs/fst/fstapi.cc index b77745900..3b0b35233 100644 --- a/libs/fst/fstapi.cc +++ b/libs/fst/fstapi.cc @@ -550,8 +550,9 @@ return(rc); static uint32_t fstReaderVarint32(FILE *f) { -int chk_len = 5; /* TALOS-2023-1783 */ -unsigned char buf[chk_len]; +const int chk_len_max = 5; /* TALOS-2023-1783 */ +int chk_len = chk_len_max; +unsigned char buf[chk_len_max]; unsigned char *mem = buf; uint32_t rc = 0; int ch; @@ -582,8 +583,9 @@ return(rc); static uint32_t fstReaderVarint32WithSkip(FILE *f, uint32_t *skiplen) { -int chk_len = 5; /* TALOS-2023-1783 */ -unsigned char buf[chk_len]; +const int chk_len_max = 5; /* TALOS-2023-1783 */ +int chk_len = chk_len_max; +unsigned char buf[chk_len_max]; unsigned char *mem = buf; uint32_t rc = 0; int ch; @@ -615,8 +617,9 @@ return(rc); static uint64_t fstReaderVarint64(FILE *f) { -int chk_len = 16; /* TALOS-2023-1783 */ -unsigned char buf[chk_len]; +const int chk_len_max = 16; /* TALOS-2023-1783 */ +int chk_len = chk_len_max; +unsigned char buf[chk_len_max]; unsigned char *mem = buf; uint64_t rc = 0; int ch; From 2157f671847d70a378eb274dfffdc8643aa5c2c6 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 17 Oct 2024 07:05:24 +1300 Subject: [PATCH 100/496] libs/fst: Patch more _MSC_VER checks --- libs/fst/00_PATCH_win_io.patch | 29 +++++++++++++++++++++++++++++ libs/fst/fstapi.cc | 6 +++--- 2 files changed, 32 insertions(+), 3 deletions(-) diff --git a/libs/fst/00_PATCH_win_io.patch b/libs/fst/00_PATCH_win_io.patch index 5813758cd..1105538e5 100644 --- a/libs/fst/00_PATCH_win_io.patch +++ b/libs/fst/00_PATCH_win_io.patch @@ -9,3 +9,32 @@ #include #else #include +--- fstapi.cc ++++ fstapi.cc +@@ -56,7 +56,7 @@ + #include + #endif + +-#ifdef __MINGW32__ ++#if defined __CYGWIN__ || defined __MINGW32__ || defined _MSC_VER + #define WIN32_LEAN_AND_MEAN + #include + #endif +@@ -159,7 +159,7 @@ void **JenkinsIns(void *base_i, const unsigned char *mem, uint32_t length, uint3 + /*** ***/ + /***********************/ + +-#ifdef __MINGW32__ ++#if defined(__MINGW32__) || defined(_MSC_VER) + #include + #ifndef HAVE_FSEEKO + #define ftello _ftelli64 +@@ -341,7 +341,7 @@ return(NULL); + /* + * mmap compatibility + */ +-#if defined __MINGW32__ ++#if defined __CYGWIN__ || defined __MINGW32__ || defined _MSC_VER + #include + #define fstMmap(__addr,__len,__prot,__flags,__fd,__off) fstMmap2((__len), (__fd), (__off)) + #define fstMunmap(__addr,__len) UnmapViewOfFile((LPCVOID)__addr) diff --git a/libs/fst/fstapi.cc b/libs/fst/fstapi.cc index 3b0b35233..00a304909 100644 --- a/libs/fst/fstapi.cc +++ b/libs/fst/fstapi.cc @@ -56,7 +56,7 @@ #include #endif -#ifdef __MINGW32__ +#if defined __CYGWIN__ || defined __MINGW32__ || defined _MSC_VER #define WIN32_LEAN_AND_MEAN #include #endif @@ -159,7 +159,7 @@ void **JenkinsIns(void *base_i, const unsigned char *mem, uint32_t length, uint3 /*** ***/ /***********************/ -#ifdef __MINGW32__ +#if defined(__MINGW32__) || defined(_MSC_VER) #include #ifndef HAVE_FSEEKO #define ftello _ftelli64 @@ -341,7 +341,7 @@ return(NULL); /* * mmap compatibility */ -#if defined __MINGW32__ +#if defined __CYGWIN__ || defined __MINGW32__ || defined _MSC_VER #include #define fstMmap(__addr,__len,__prot,__flags,__fd,__off) fstMmap2((__len), (__fd), (__off)) #define fstMunmap(__addr,__len) UnmapViewOfFile((LPCVOID)__addr) From e5da0e341e5d468ffae02d09a68b2dd53b8f0628 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 17 Oct 2024 07:12:34 +1300 Subject: [PATCH 101/496] Makefile: Combine gen_images and gen_examples gen_images and gen_examples are never called on their own, CI scripts call make -C docs directly. Since calling them both in parallel seems to cause issues, let's not do that, and instead combine them into a singular `make docs/gen`. This should resolve the parallelism problems by making them sequential while still retaining the -j support. --- Makefile | 11 ++++------- docs/Makefile | 5 +++++ 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/Makefile b/Makefile index 91f48921e..217fc4761 100644 --- a/Makefile +++ b/Makefile @@ -996,12 +996,9 @@ docs/source/cell/word_add.rst: $(TARGETS) $(EXTRA_TARGETS) docs/source/generated/cells.json: docs/source/generated $(TARGETS) $(EXTRA_TARGETS) $(Q) ./$(PROGRAM_PREFIX)yosys -p 'help -dump-cells-json $@' -PHONY: docs/gen_examples docs/gen_images docs/guidelines docs/usage docs/reqs -docs/gen_examples: $(TARGETS) - $(Q) $(MAKE) -C docs examples - -docs/gen_images: $(TARGETS) - $(Q) $(MAKE) -C docs images +PHONY: docs/gen docs/guidelines docs/usage docs/reqs +docs/gen: $(TARGETS) + $(Q) $(MAKE) -C docs gen DOCS_GUIDELINE_FILES := GettingStarted CodingStyle DOCS_GUIDELINE_SOURCE := $(addprefix guidelines/,$(DOCS_GUIDELINE_FILES)) @@ -1037,7 +1034,7 @@ docs/reqs: $(Q) $(MAKE) -C docs reqs .PHONY: docs/prep -docs/prep: docs/source/cmd/abc.rst docs/source/generated/cells.json docs/gen_examples docs/gen_images docs/guidelines docs/usage +docs/prep: docs/source/cmd/abc.rst docs/source/generated/cells.json docs/gen docs/guidelines docs/usage DOC_TARGET ?= html docs: docs/prep diff --git a/docs/Makefile b/docs/Makefile index 6dbf6f490..a8874bb83 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -252,6 +252,11 @@ images: $(MAKE) -C source/_images $(MAKE) -C source/_images convert +.PHONY: gen +gen: + $(MAKE) examples + $(MAKE) images + .PHONY: reqs reqs: $(PYTHON) -m pip install -r source/requirements.txt From d1c6699125629836ea1699b2c1bcb520e96ef5fc Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 17 Oct 2024 07:15:11 +1300 Subject: [PATCH 102/496] test-docs-build: Use fast runner --- .github/workflows/test-build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test-build.yml b/.github/workflows/test-build.yml index 4ac77a765..2c4deff23 100644 --- a/.github/workflows/test-build.yml +++ b/.github/workflows/test-build.yml @@ -192,7 +192,7 @@ jobs: test-docs-build: name: Try build docs - runs-on: [self-hosted, linux, x64] + runs-on: [self-hosted, linux, x64, fast] needs: [pre_docs_job] if: needs.pre_docs_job.outputs.should_skip != 'true' strategy: From 4b9c1350980f8e4b96f500d6c3a96fb2d88ba341 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Wed, 16 Oct 2024 22:46:23 +0200 Subject: [PATCH 103/496] py_wrap: refactor nesting_delta --- misc/py_wrap_generator.py | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/misc/py_wrap_generator.py b/misc/py_wrap_generator.py index a65d24d92..049c67f19 100644 --- a/misc/py_wrap_generator.py +++ b/misc/py_wrap_generator.py @@ -1958,7 +1958,10 @@ def assure_length(text, length, left = False): if left: return text + " "*(length - len(text)) return " "*(length - len(text)) + text - + +def nesting_delta(s): + return s.count("{") - s.count("}") + def parse_header(source): debug("Parsing " + source.name + ".pyh",1) source_file = open(source.name + ".pyh", "r") @@ -1982,6 +1985,7 @@ def parse_header(source): while i < len(source_text): line = source_text[i].replace("YOSYS_NAMESPACE_BEGIN", " namespace YOSYS_NAMESPACE{").replace("YOSYS_NAMESPACE_END"," }") ugly_line = unpretty_string(line) + debug(f"READ:>> {line}", 2) # for anonymous unions, ignore union enclosure by skipping start line and replacing end line with new line if 'union {' in line: @@ -2004,15 +2008,15 @@ def parse_header(source): continue if len(namespaces) != 0: - namespaces[-1] = (namespaces[-1][0], namespaces[-1][1] + ugly_line.count("{") - ugly_line.count("}")) + namespaces[-1] = (namespaces[-1][0], namespaces[-1][1] + nesting_delta(ugly_line)) if namespaces[-1][1] == 0: debug("-----END NAMESPACE " + concat_namespace(namespaces) + "-----",3) - del namespaces[-1] + namespaces.pop() i += 1 continue if class_ == None and (str.startswith(ugly_line, "struct ") or str.startswith(ugly_line, "class")) and ugly_line.count(";") == 0: - + # Opening a record declaration which isn't a forward declaration struct_name = ugly_line.split(" ")[1].split("::")[-1] impl_namespaces = ugly_line.split(" ")[1].split("::")[:-1] complete_namespace = concat_namespace(namespaces) @@ -2031,6 +2035,7 @@ def parse_header(source): base_class = class_by_name(base_class_name) class_ = (class_by_name(struct_name), ugly_line.count("{"))#calc_ident(line)) + debug(f"switch to {struct_name} in namespace {namespaces}", 2) if struct_name in classnames: class_[0].namespace = complete_namespace class_[0].base_class = base_class @@ -2038,12 +2043,14 @@ def parse_header(source): continue if class_ != None: - class_ = (class_[0], class_[1] + ugly_line.count("{") - ugly_line.count("}")) + class_ = (class_[0], class_[1] + nesting_delta(ugly_line)) + debug(f"switch to uhh depth {class_[1]}", 2) if class_[1] == 0: if class_[0] == None: debug("\tExiting unknown class", 3) else: debug("\tExiting class " + class_[0].name, 3) + debug(f"nevermind!", 2) class_ = None private_segment = False i += 1 @@ -2156,12 +2163,12 @@ def parse_header(source): line = source_text[i].replace("YOSYS_NAMESPACE_BEGIN", " namespace YOSYS_NAMESPACE{").replace("YOSYS_NAMESPACE_END"," }") ugly_line = unpretty_string(line) if len(namespaces) != 0: - namespaces[-1] = (namespaces[-1][0], namespaces[-1][1] + ugly_line.count("{") - ugly_line.count("}")) + namespaces[-1] = (namespaces[-1][0], namespaces[-1][1] + nesting_delta(ugly_line)) if namespaces[-1][1] == 0: debug("-----END NAMESPACE " + concat_namespace(namespaces) + "-----",3) - del namespaces[-1] + namespaces.pop() if class_ != None: - class_ = (class_[0] , class_[1] + ugly_line.count("{") - ugly_line.count("}")) + class_ = (class_[0] , class_[1] + nesting_delta(ugly_line)) if class_[1] == 0: if class_[0] == None: debug("\tExiting unknown class", 3) From 86630bba0823b0a1046c3b55de33e0f362bbf21e Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Wed, 16 Oct 2024 22:55:17 +0200 Subject: [PATCH 104/496] py_wrap: nested classes --- misc/py_wrap_generator.py | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/misc/py_wrap_generator.py b/misc/py_wrap_generator.py index 049c67f19..e95fc0e73 100644 --- a/misc/py_wrap_generator.py +++ b/misc/py_wrap_generator.py @@ -1979,7 +1979,7 @@ def parse_header(source): i = 0 namespaces = [] - class_ = None + classes = [] private_segment = False while i < len(source_text): @@ -2015,7 +2015,7 @@ def parse_header(source): i += 1 continue - if class_ == None and (str.startswith(ugly_line, "struct ") or str.startswith(ugly_line, "class")) and ugly_line.count(";") == 0: + if (str.startswith(ugly_line, "struct ") or str.startswith(ugly_line, "class")) and ugly_line.count(";") == 0: # Opening a record declaration which isn't a forward declaration struct_name = ugly_line.split(" ")[1].split("::")[-1] impl_namespaces = ugly_line.split(" ")[1].split("::")[:-1] @@ -2034,28 +2034,31 @@ def parse_header(source): debug("\t " + struct_name + " is derived from " + base_class_name,2) base_class = class_by_name(base_class_name) - class_ = (class_by_name(struct_name), ugly_line.count("{"))#calc_ident(line)) + c = (class_by_name(struct_name), ugly_line.count("{"))#calc_ident(line)) debug(f"switch to {struct_name} in namespace {namespaces}", 2) if struct_name in classnames: - class_[0].namespace = complete_namespace - class_[0].base_class = base_class + c[0].namespace = complete_namespace + c[0].base_class = base_class + classes.append(c) i += 1 continue - if class_ != None: - class_ = (class_[0], class_[1] + nesting_delta(ugly_line)) - debug(f"switch to uhh depth {class_[1]}", 2) - if class_[1] == 0: - if class_[0] == None: + if len(classes): + c = (classes[-1][0], classes[-1][1] + nesting_delta(ugly_line)) + debug(f"switch to uhh depth {c[1]}", 2) + if c[1] == 0: + if c[0] == None: debug("\tExiting unknown class", 3) else: - debug("\tExiting class " + class_[0].name, 3) + debug("\tExiting class " + c[0].name, 3) debug(f"nevermind!", 2) - class_ = None + classes.pop() private_segment = False i += 1 continue + class_ = classes[-1] if classes else None + if class_ != None and (line.find("private:") != -1 or line.find("protected:") != -1): private_segment = True i += 1 @@ -2167,14 +2170,14 @@ def parse_header(source): if namespaces[-1][1] == 0: debug("-----END NAMESPACE " + concat_namespace(namespaces) + "-----",3) namespaces.pop() - if class_ != None: - class_ = (class_[0] , class_[1] + nesting_delta(ugly_line)) - if class_[1] == 0: - if class_[0] == None: + if len(classes): + c = (classes[-1][0] , classes[-1][1] + nesting_delta(ugly_line)) + if c[1] == 0: + if c[0] == None: debug("\tExiting unknown class", 3) else: - debug("\tExiting class " + class_[0].name, 3) - class_ = None + debug("\tExiting class " + c[0].name, 3) + classes.pop() private_segment = False i += 1 else: From f219bb357f338aa53e2d21d564e34d9013b93744 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Wed, 16 Oct 2024 23:12:41 +0200 Subject: [PATCH 105/496] py_wrap: kinda fixed --- misc/py_wrap_generator.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/misc/py_wrap_generator.py b/misc/py_wrap_generator.py index e95fc0e73..fe80c8c85 100644 --- a/misc/py_wrap_generator.py +++ b/misc/py_wrap_generator.py @@ -2045,6 +2045,7 @@ def parse_header(source): if len(classes): c = (classes[-1][0], classes[-1][1] + nesting_delta(ugly_line)) + classes[-1] = c debug(f"switch to uhh depth {c[1]}", 2) if c[1] == 0: if c[0] == None: @@ -2172,6 +2173,7 @@ def parse_header(source): namespaces.pop() if len(classes): c = (classes[-1][0] , classes[-1][1] + nesting_delta(ugly_line)) + classes[-1] = c if c[1] == 0: if c[0] == None: debug("\tExiting unknown class", 3) From e9e67f381cd47763efd50a9cb331b3d2e3619421 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Wed, 16 Oct 2024 23:15:06 +0200 Subject: [PATCH 106/496] rtlil: remove trailing comma as pyosys workaround --- kernel/rtlil.h | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/kernel/rtlil.h b/kernel/rtlil.h index eaaae814d..136cf9a13 100644 --- a/kernel/rtlil.h +++ b/kernel/rtlil.h @@ -53,15 +53,9 @@ namespace RTLIL CONST_FLAG_NONE = 0, CONST_FLAG_STRING = 1, CONST_FLAG_SIGNED = 2, // only used for parameters - CONST_FLAG_REAL = 4, // only used for parameters + CONST_FLAG_REAL = 4 // only used for parameters }; - // // Union discriminator. Values are exclusive - // enum ConstRepr : unsigned char { - // CONST_REPR_BITS = 1, - // CONST_REPR_STRING = 2, - // }; - struct Const; struct AttrObject; struct Selection; From 0341265e64f218da36f8e7744a6c927e7363b6c8 Mon Sep 17 00:00:00 2001 From: "Emil J. Tywoniak" Date: Wed, 16 Oct 2024 23:56:45 +0200 Subject: [PATCH 107/496] driver: fix special args passing to tcl and python --- kernel/driver.cc | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/kernel/driver.cc b/kernel/driver.cc index 0c0dc9023..65f090993 100644 --- a/kernel/driver.cc +++ b/kernel/driver.cc @@ -222,7 +222,7 @@ int main(int argc, char **argv) #endif // YOSYS_ENABLE_TCL #ifdef WITH_PYTHON ("y,py-scriptfile", "execute the Python