Enhanced documentation for LayoutToNetlist class, two more methods (layer_indexes, layer_info)

src/db/db/gsiDeclDbLayoutToNetlist.cc

@@ -98,6 +98,24 @@ static std::vector<std::string> l2n_layer_names (const db::LayoutToNetlist *l2n)
   return ln;
 }
 
+static std::vector<unsigned int> l2n_layer_indexes (const db::LayoutToNetlist *l2n)
+{
+  std::vector<unsigned int> li;
+  for (db::LayoutToNetlist::layer_iterator l = l2n->begin_layers (); l != l2n->end_layers (); ++l) {
+    li.push_back (l->first);
+  }
+  return li;
+}
+
+static db::LayerProperties l2n_layer_info (const db::LayoutToNetlist *l2n, unsigned int layer)
+{
+  if (! l2n->internal_layout () || ! l2n->internal_layout ()->is_valid_layer (layer)) {
+    return db::LayerProperties ();
+  } else {
+    return l2n->internal_layout ()->get_properties (layer);
+  }
+}
+
 static db::Region antenna_check3 (db::LayoutToNetlist *l2n, const db::Region &poly, double poly_area_factor, double poly_perimeter_factor, const db::Region &metal, double metal_area_factor, double metal_perimeter_factor, double ratio, const std::vector<tl::Variant> &diodes, db::Texts *texts)
 {
   std::vector<std::pair<const db::Region *, double> > diode_pairs;
@@ -331,7 +349,22 @@ Class<db::LayoutToNetlist> decl_dbLayoutToNetlist ("db", "LayoutToNetlist",
     "This method has been generalized in version 0.27.\n"
   ) +
   gsi::method_ext ("layer_names", &l2n_layer_names,
-    "@brief Returns a list of names of the layer kept inside the LayoutToNetlist object."
+    "@brief Returns a list of names of the layers kept inside the LayoutToNetlist object."
+  ) +
+  gsi::method_ext ("layer_indexes", &l2n_layer_indexes,
+    "@brief Returns a list of indexes of the layers kept inside the LayoutToNetlist object.\n"
+    "You can use \\layer_name to get the name from a layer index. You can use \\layer_info to get "
+    "the \\LayerInfo object attached to a layer - if the layer is an original layer.\n"
+    "\n"
+    "This method has been introduced in version 0.29.2.\n"
+  ) +
+  gsi::method_ext ("layer_info", &l2n_layer_info, gsi::arg ("index"),
+    "@brief Returns the LayerInfo object attached to a layer (by index).\n"
+    "If the layer is an original layer and not a derived one, this method will return the "
+    "stream layer information where the original layer was taken from. Otherwise an empty \\LayerInfo object "
+    "is returned.\n"
+    "\n"
+    "This method has been introduced in version 0.29.2.\n"
   ) +
   gsi::factory ("layer_by_name", &db::LayoutToNetlist::layer_by_name, gsi::arg ("name"),
     "@brief Gets a layer object for the given name.\n"
@@ -599,8 +632,10 @@ Class<db::LayoutToNetlist> decl_dbLayoutToNetlist ("db", "LayoutToNetlist",
   ) +
   gsi::method_ext ("internal_layout", &l2n_internal_layout,
     "@brief Gets the internal layout\n"
-    "Usually it should not be required to obtain the internal layout. If you need to do so, make sure not to modify the layout as\n"
-    "the functionality of the netlist extractor depends on it."
+    "The internal layout is where the LayoutToNetlist database stores the shapes for the nets. "
+    "Usually you do not need to access this object - you must use \\build_net or \\shapes_of_net to "
+    "retrieve the per-net shape information. If you access the internal layout, make sure you do not "
+    "modify it."
   ) +
   gsi::method_ext ("internal_top_cell", &l2n_internal_top_cell,
     "@brief Gets the internal top cell\n"
@@ -664,8 +699,13 @@ Class<db::LayoutToNetlist> decl_dbLayoutToNetlist ("db", "LayoutToNetlist",
     "This method puts the shapes of a net into the given target cell using a variety of options\n"
     "to represent the net name and the hierarchy of the net.\n"
     "\n"
-    "If the netname_prop name is not nil, a property with the given name is created and assigned\n"
-    "the net name.\n"
+    "If 'netname_prop' is not nil, a property with the given name is created and attached to shapes. The value "
+    "of the property is the net name.\n"
+    "\n"
+    "'lmap' defines which layers are to be produced. It is map, where the keys are layer indexes in the "
+    "target layout and the values are Region objects indicating the layer where shapes are to be taken from. "
+    "Use \\layer_by_name or \\layer_by_index to get the Region object corresponding to a layer stored inside "
+    "the LayoutToNetlist database.\n"
     "\n"
     "Net hierarchy is covered in three ways:\n"
     "@ul\n"
@@ -696,6 +736,14 @@ Class<db::LayoutToNetlist> decl_dbLayoutToNetlist ("db", "LayoutToNetlist",
     "If no mapping is provided for a specific circuit cell, the nets are copied into the next mapped parent as "
     "many times as the circuit cell appears there (circuit flattening).\n"
     "\n"
+    "If 'netname_prop' is not nil, a property with the given name is created and attached to shapes. The value "
+    "of the property is the net name.\n"
+    "\n"
+    "'lmap' defines which layers are to be produced. It is map, where the keys are layer indexes in the "
+    "target layout and the values are Region objects indicating the layer where shapes are to be taken from. "
+    "Use \\layer_by_name or \\layer_by_index to get the Region object corresponding to a layer stored inside "
+    "the LayoutToNetlist database.\n"
+    "\n"
     "The method has three net annotation modes:\n"
     "@ul\n"
     " @li No annotation (net_cell_name_prefix == nil and netname_prop == nil): the shapes will be put\n"
@@ -910,6 +958,25 @@ Class<db::LayoutToNetlist> decl_dbLayoutToNetlist ("db", "LayoutToNetlist",
   "hierarchical data and an existing DeepShapeStore object, use the "
   "'LayoutToNetlist(dss)' constructor.\n"
   "\n"
+  "Once the extraction is done, you can persist the \\LayoutToNetlist object "
+  "using \\write and restore it using \\read. You can use the query API (see below) to "
+  "analyze the LayoutToNetlist database.\n"
+  "\n"
+  "The query API of the \\LayoutToNetlist object consists of the following parts:\n"
+  "\n"
+  "@ul\n"
+  "@li Net shape retrieval: \\build_all_nets, \\build_nets, \\build_net and \\shapes_per_net @/li\n"
+  "@li Layers: \\layer_by_index, \\layer_by_name, \\layer_indexes, \\layer_names, \\layer_info, \\layer_name @/li\n"
+  "@li Log entries: \\each_log_entry @/li\n"
+  "@li Probing (get net from position): \\probe_net @/li\n"
+  "@li Netlist: \\netlist @/li\n"
+  "@li Internal shape storage: \\internal_layout, \\internal_top_cell @/li\n"
+  "@li Helper functions: \\cell_mapping_into, \\const_cell_mapping_into @/li\n"
+  "@/ul\n"
+  "\n"
+  "The \\LayoutToNetlist object is also the entry point for connectivity-aware DRC checks, "
+  "such as antenna checks.\n"
+  "\n"
   "This class has been introduced in version 0.26."
 );
 

testdata/ruby/dbLayoutToNetlist.rb

@@ -551,6 +551,8 @@ END
     assert_equal(File.open(tmp, "r").read, File.open(input, "r").read)
 
     assert_equal(l2n.layer_names.join(","), "poly,poly_lbl,diff_cont,poly_cont,metal1,metal1_lbl,via1,metal2,metal2_lbl,psd,nsd")
+    assert_equal(l2n.layer_indexes.join(","), "1,2,3,4,5,6,7,8,9,10,11")
+    assert_equal(l2n.layer_indexes.collect { |li| l2n.layer_info(li).to_s }.join(","), "3/0,3/1,4/0,5/0,6/0,6/1,7/0,8/0,8/1,,")
     assert_equal(l2n.layer_name(l2n.layer_by_name("metal1")), "metal1")
     assert_equal(l2n.layer_name(l2n.layer_by_index(l2n.layer_of(l2n.layer_by_name("metal1")))), "metal1")