Google Git
Sign in
foss-fpga-tools / third_party / verible / de1451db099c723095c4863751faa3e7c9f525db / . / verilog / CST
tree: 3d126084ca629e4869d169b8474af071ea41a2ab [path history] [tgz]
  1. BUILD
  2. class.cc
  3. class.h
  4. class_test.cc
  5. constraints.cc
  6. constraints.h
  7. constraints_test.cc
  8. context_functions.h
  9. context_functions_test.cc
  10. data.cc
  11. data.h
  12. data_test.cc
  13. declaration.cc
  14. declaration.h
  15. declaration_test.cc
  16. dimensions.cc
  17. dimensions.h
  18. dimensions_test.cc
  19. DPI.cc
  20. DPI.h
  21. DPI_test.cc
  22. expression.cc
  23. expression.h
  24. expression_test.cc
  25. functions.cc
  26. functions.h
  27. functions_test.cc
  28. identifier.cc
  29. identifier.h
  30. identifier_test.cc
  31. macro.cc
  32. macro.h
  33. macro_test.cc
  34. match_test_utils.cc
  35. match_test_utils.h
  36. module.cc
  37. module.h
  38. module_test.cc
  39. net.cc
  40. net.h
  41. net_test.cc
  42. numbers.cc
  43. numbers.h
  44. numbers_test.cc
  45. package.cc
  46. package.h
  47. package_test.cc
  48. parameters.cc
  49. parameters.h
  50. parameters_test.cc
  51. port.cc
  52. port.h
  53. port_test.cc
  54. README.md
  55. seq_block.cc
  56. seq_block.h
  57. seq_block_test.cc
  58. statement.cc
  59. statement.h
  60. statement_test.cc
  61. tasks.cc
  62. tasks.h
  63. tasks_test.cc
  64. type.cc
  65. type.h
  66. type_test.cc
  67. verilog_matchers.cc
  68. verilog_matchers.h
  69. verilog_matchers_test.cc
  70. verilog_nonterminals.cc
  71. verilog_nonterminals.h
  72. verilog_nonterminals_foreach.inc
  73. verilog_nonterminals_test.cc
  74. verilog_tree_json.cc
  75. verilog_tree_json.h
  76. verilog_tree_json_test.cc
  77. verilog_tree_print.cc
  78. verilog_tree_print.h
  79. verilog_tree_print_test.cc
  80. verilog_treebuilder_utils.cc
  81. verilog_treebuilder_utils.h
  82. verilog_treebuilder_utils_test.cc
verilog/CST/README.md

SystemVerilog Concrete Syntax Tree

The SystemVerilog concrete syntax tree (CST) uses the language-agnostic syntax tree structure with its own set of (int) enumerations for tree nodes and leaves. The CST includes all syntactically relevant tokens, no comments, no attributes (at this time), and limited support for preprocessing constructs.

The exact node enumerations should be considered fragile until stated otherwise; they may change, get new enumerations, or remove obsolete ones. Code that depends direct use of these enumerations should be well-tested so that breakages are easy to diagnose and fix.

CST leaves contain tokens, which bear the token enumerations generated from the parser implementation. These token enumerations are relatively stable. However, where practical, we encourage use of token classification functions.

The node enumerations are used directly in the semantic actions of the SystemVerilog parser, with functions like MakeTaggedNode.

Both node and token enumerations are used in syntax tree analyzers and also drive formatting decisions in the formatter.

Ideals

Ideal properties of CST nodes:

  • Every construction of a CST node follows a consistent substructure, as if there were a class with one constructor for each node type. Consistency allows one to write simple functions that directly access substructure by descending through CST nodes positionally. For every node enumeration kFoo, there should be MakeFoo function that constructs a CST node from its arguments. Accessor functions should be short and composable.
    • Construction also provides an opportunity to check that the programmer has not made a mistake, by asserting invariant properties about the arguments.
  • Access into a CST node's substructure is exclusively done by GetFooFromBar-style functions that hide the structural details of a node, while remaining consistent with construction.
  • Both implementation of the constructor and accessor functions should ideally come from a single-source-of-truth, that is, they should be generated (no later than compile-time) from one specification for each node type, rather than maintained independently.

This is not the case today because of the haste in which initial development took place, but help is wanted towards achieving the aforementioned ideals. See also https://github.com/chipsalliance/verible/issues/159.

Abstract Syntax Tree?

Wouldn't an abstract syntax tree (AST) satisfy the above ideals? Yes, this would take time to write, and we would need help.

An AST may not be a great representation for unpreprocessed code, which is the focus of the first developer tool applications. Having a standard-compliant SV preprocessor would pave the way to making an AST more useful.

Testing

Most CST accessor function tests should follow this outline:

  • Declare an array of test data in the form of SyntaxTreeSearchTestCase
    • Each element compactly represents the code to analyze, and the set of expected findings as annotated subranges of text.
  • For every function-under-test, establish a function that extracts the targeted subranges of text (which must be non-overlapping). This could be a simple find-function on a syntax tree or contain any sequence of search refinements.
  • Pass these into the TestVerilogSyntaxRangeMatches test driver function which compare actual vs. expected subranges.