Bugfix: virtual_bus @keepports (new PR)

src/colibri/documenter/diagram.ts

@@ -164,8 +164,21 @@ function get_ports(hdl_element: common_hdl.Hdl_element) {
     const port_list = hdl_element.get_port_array();
     const port_list_vbus = doxygen.get_virtual_bus(port_list);
     let complete_list: any[] = [];
+
+    // Add normal ports (not part of virtual buses)
     complete_list = complete_list.concat(port_list_vbus.port_list);
-    complete_list = complete_list.concat(port_list_vbus.v_port_list);
+
+    // Process virtual buses
+    for (const virtual_bus of port_list_vbus.v_port_list) {
+        if (virtual_bus.keepports) {
+            // If @keepports is enabled, expand virtual bus to show individual ports
+            complete_list = complete_list.concat(virtual_bus.port_list);
+        } else {
+            // If @keepports is not enabled, show virtual bus as single entity
+            complete_list.push(virtual_bus);
+        }
+    }
+
     return complete_list;
 }
 

src/colibri/documenter/doxygen_parser.ts

@@ -67,6 +67,7 @@ export function parse_virtualbus_init(description: string) {
         name: '',
         direction: 'in',
         notable: false,
+        keepports: false,
         description: '',
         to_delete: ''
     };
@@ -83,6 +84,7 @@ export function parse_virtualbus_init(description: string) {
             result.notable = true;
             corpus = notable_element.text;
         }
+
         //Port name
         const virtual_port_element = parse_element('virtualbus', corpus);
         if (virtual_port_element.element_list.length === 0) {
@@ -96,14 +98,21 @@ export function parse_virtualbus_init(description: string) {
 
         // Direction
         const direction_port_element = parse_element('dir', corpus);
-        if (direction_port_element.element_list.length === 0) {
-            result.description = corpus.trim();
-            return result;
+        if (direction_port_element.element_list.length !== 0) {
+            corpus = direction_port_element.element_list[0].description.trim();
+            element_0 = get_first_element(corpus);
+            result.direction = element_0.name;
+            corpus = element_0.text.trim();
+        }
+
+        // Keep ports
+        const keepports_element = is_keepports(corpus);
+        if (keepports_element.is_in === true) {
+            result.keepports = true;
+            corpus = keepports_element.text;
         }
-        corpus = direction_port_element.element_list[0].description.trim();
-        element_0 = get_first_element(corpus);
-        result.direction = element_0.name;
-        result.description = element_0.text.trim();
+
+        result.description = corpus.trim();
         if (result.is_in === true) {
             return result;
         }
@@ -125,6 +134,20 @@ function is_notable(text: string) {
     return result;
 }
 
+function is_keepports(text: string) {
+    const regex = /@keepports/gms;
+    const element_parser = text.match(regex);
+    const result = {
+        text: text,
+        is_in: false
+    };
+    if (element_parser !== null) {
+        result.is_in = true;
+        result.text = text.replace(regex, '').trim();
+    }
+    return result;
+}
+
 function get_first_element(text: string) {
     let corpus_split = text.split(' ');
     const name = corpus_split[0];
@@ -188,6 +211,7 @@ export function get_virtual_bus(port_list: common_hdl.Port_hdl[]) {
                     },
                     direction: virtual_port.direction,
                     notable: virtual_port.notable,
+                    keepports: virtual_port.keepports,
                     port_list: [],
                     type: "virtual_bus"
                 };
@@ -196,7 +220,7 @@ export function get_virtual_bus(port_list: common_hdl.Port_hdl[]) {
                     info: {
                         position: port_i.info.position,
                         name: port_i.info.name,
-                        description: port_description.replace(virtual_port.to_delete, '')
+                        description: port_i.inline_comment.trim()
                     },
                     inline_comment: "",
                     over_comment: "",
@@ -279,6 +303,7 @@ export function get_virtual_bus(port_list: common_hdl.Port_hdl[]) {
                     },
                     direction: virtual_port.direction,
                     notable: virtual_port.notable,
+                    keepports: virtual_port.keepports,
                     port_list: [],
                     type: "virtual_bus"
                 };

src/colibri/parser/common.ts

@@ -114,6 +114,7 @@ export type Virtual_bus_hdl = {
     info: Common_info;
     direction: string;
     notable: boolean;
+    keepports: boolean;
     port_list: Port_hdl[];
     type: string;
 };

test_keepports_diagram.ts

@@ -0,0 +1,54 @@
+import { documenter_factory } from "../src/colibri/documenter/factory";
+import { HDL_LANG } from "../src/colibri/common/general";
+import { Diagram } from "../src/colibri/documenter/diagram";
+import * as fs from "fs";
+import * as path from "path";
+
+async function test_keepports_diagram() {
+    const test_file = path.join(__dirname, "test_keepports_diagram.vhdl");
+    const vhdl_code = fs.readFileSync(test_file, "utf8");
+
+    console.log("Testing @keepports diagram functionality...");
+
+    // Create documenter
+    const documenter = documenter_factory(HDL_LANG.VHDL);
+
+    // Parse the VHDL code
+    const result = await documenter.get_documentation(vhdl_code, {
+        language: HDL_LANG.VHDL,
+        path: test_file,
+        configuration: {
+            enable_markdown: true,
+            enable_comments: true
+        }
+    });
+
+    console.log("Parsed entities:", result.length);
+
+    if (result.length > 0) {
+        const entity = result[0];
+        console.log("Entity name:", entity.name);
+        console.log("Number of ports:", entity.port.length);
+        console.log("Virtual buses:", entity.virtual_bus);
+
+        // Create diagram
+        const diagram = new Diagram();
+        const svg_content = diagram.get_entity_as_svg(entity);
+
+        // Save diagram to file for visual inspection
+        const output_file = path.join(__dirname, "keepports_diagram_test.svg");
+        fs.writeFileSync(output_file, svg_content);
+        console.log("Diagram saved to:", output_file);
+
+        // Check virtual bus properties
+        entity.virtual_bus.forEach((vbus, index) => {
+            console.log(`Virtual bus ${index + 1}:`);
+            console.log(`  Name: ${vbus.name}`);
+            console.log(`  Description: ${vbus.description}`);
+            console.log(`  Keepports: ${vbus.keepports}`);
+            console.log(`  Ports: ${vbus.port_list.map(p => p.name).join(", ")}`);
+        });
+    }
+}
+
+test_keepports_diagram().catch(console.error);

tests/documenter/complete/entity.vhdlSource

@@ -78,15 +78,34 @@ entity test_entity_name is
         --! @virtualbus v_bus_1  @keepports  Description of virtual bus 1
         j : in std_logic := '1';
         l : out std_logic;
-        m : in std_logic;
+        m : in std_logic; --! @end
         --! @virtualbus v_bus_2  Description of virtual bus 2
         n : in std_logic; --! Description 3
-        o : out std_logic; --! @end
-        p : in std_logic;
+        o : out std_logic;
+        p : in std_logic; --! @end
         q : out std_logic; --! Inline comment
         r : in std_logic;
         --! Over comment
-        s : out std_logic --! Preference inline
+        s : out std_logic; --! Preference inline
+        --! @virtualbus video_in_axi_stream @dir in a slave axi stream interface for video in
+        video_in_tdata  : in  std_logic_vector(23 downto 0);      --! axis data bus
+        video_in_tlast  : in  std_logic;                          --! axis last
+        video_in_tuser  : in  std_logic_vector(0 downto 0);       --! axis user
+        video_in_tvalid : in  std_logic;                          --! axis valid handshake signal
+        video_in_tready : out std_logic;                          --! axis ready handshake signal
+        --! @end
+        --! @virtualbus video_out_axi_stream @dir out @keepports a master axi stream interface for video out
+        video_out_tdata  : out std_logic_vector(23 downto 0);     --! axis data bus video_out
+        video_out_tlast  : out std_logic;                         --! axis last
+        video_out_tuser  : out std_logic_vector(0 downto 0);      --! axis user
+        video_out_tvalid : out std_logic;                         --! axis valid handshake signal
+        video_out_tready : in  std_logic;                         --! axis ready handshake signal
+        --! @end
+        --! @virtualbus SPI @dir out description of SPI
+        cs : OUT std_logic; --! Chip select
+        clk_out: OUT std_logic; --! SPI clock
+        miso: OUT std_logic; --! Master in slave out
+        mosi: OUT std_logic  --! Master out slave in @end
     );
 end test_entity_name;
 

tests/documenter/complete/expected/entity_vhdlSource_markdown/output.markdown

@@ -44,15 +44,15 @@ image:
 
 
 
-![alt text](wavedrom_yTaI0.svg "title")
+![alt text](wavedrom_6Vtl0.svg "title")
 
 
 
 Example of bitfield:
 
 
 
-![alt text](wavedrom_xpwo1.svg "title")
+![alt text](wavedrom_wHVW1.svg "title")
 
 
 
@@ -69,17 +69,20 @@ Example of bitfield:
 
 ## Ports
 
-| Port name | Direction | Type                          | Description                              |
-| --------- | --------- | ----------------------------- | ---------------------------------------- |
-| ee        | in        | std_logic                     | Over comment in ```port```               |
-| h         | in        | std_logic_vector(31 downto 0) |                                          |
-| i         | in        | std_logic_vector(31 downto 0) |                                          |
-| p         | in        | std_logic                     |                                          |
-| q         | out       | std_logic                     | Inline comment                           |
-| r         | in        | std_logic                     |                                          |
-| s         | out       | std_logic                     | Preference inline                        |
-| v_bus_0   | out       | Virtual bus                   | @keepports  Description of virtual bus 0 |
-| v_bus_1   | in        | Virtual bus                   | @keepports  Description of virtual bus 1 |
+| Port name            | Direction | Type                          | Description                                 |
+| -------------------- | --------- | ----------------------------- | ------------------------------------------- |
+| ee                   | in        | std_logic                     | Over comment in ```port```                  |
+| h                    | in        | std_logic_vector(31 downto 0) |                                             |
+| i                    | in        | std_logic_vector(31 downto 0) |                                             |
+| q                    | out       | std_logic                     | Inline comment                              |
+| r                    | in        | std_logic                     |                                             |
+| s                    | out       | std_logic                     | Preference inline                           |
+| v_bus_0              | out       | Virtual bus                   | Description of virtual bus 0                |
+| v_bus_1              | in        | Virtual bus                   | Description of virtual bus 1                |
+| v_bus_2              | in        | Virtual bus                   | Description of virtual bus 2                |
+| video_in_axi_stream  | in        | Virtual bus                   | a slave axi stream interface for video in   |
+| video_out_axi_stream | out       | Virtual bus                   | a master axi stream interface for video out |
+| SPI                  | out       | Virtual bus                   | description of SPI                          |
 
 ### Virtual Buses
 
@@ -92,13 +95,44 @@ Example of bitfield:
 | g         | inout     | std_logic |             |
 #### v_bus_1
 
+| Port name | Direction | Type      | Description |
+| --------- | --------- | --------- | ----------- |
+| j         | in        | std_logic |             |
+| l         | out       | std_logic |             |
+| m         | in        | std_logic |             |
+#### v_bus_2
+
 | Port name | Direction | Type      | Description   |
 | --------- | --------- | --------- | ------------- |
-| j         | in        | std_logic |               |
-| l         | out       | std_logic |               |
-| m         | in        | std_logic |               |
 | n         | in        | std_logic | Description 3 |
 | o         | out       | std_logic |               |
+| p         | in        | std_logic |               |
+#### video_in_axi_stream
+
+| Port name       | Direction | Type                          | Description                 |
+| --------------- | --------- | ----------------------------- | --------------------------- |
+| video_in_tdata  | in        | std_logic_vector(23 downto 0) | axis data bus               |
+| video_in_tlast  | in        | std_logic                     | axis last                   |
+| video_in_tuser  | in        | std_logic_vector(0 downto 0)  | axis user                   |
+| video_in_tvalid | in        | std_logic                     | axis valid handshake signal |
+| video_in_tready | out       | std_logic                     | axis ready handshake signal |
+#### video_out_axi_stream
+
+| Port name        | Direction | Type                          | Description                 |
+| ---------------- | --------- | ----------------------------- | --------------------------- |
+| video_out_tdata  | out       | std_logic_vector(23 downto 0) | axis data bus video_out     |
+| video_out_tlast  | out       | std_logic                     | axis last                   |
+| video_out_tuser  | out       | std_logic_vector(0 downto 0)  | axis user                   |
+| video_out_tvalid | out       | std_logic                     | axis valid handshake signal |
+| video_out_tready | in        | std_logic                     | axis ready handshake signal |
+#### SPI
+
+| Port name | Direction | Type      | Description         |
+| --------- | --------- | --------- | ------------------- |
+| cs        | out       | std_logic | Chip select         |
+| clk_out   | out       | std_logic | SPI clock           |
+| miso      | out       | std_logic | Master in slave out |
+| mosi      | out       | std_logic | Master out slave in |
 
 ## Signals