VHPIDIRECT, HDL_LOGIC_STATE/CHAR, C access example,

[radonnachie]

Description
I moved my Caccess example to under VHPIDIRECT examples, and added to appropriate toc.
I cleaned Examples page, reads more easily (directs one to quick_start then to VHPIDIRECT examples)
I added a label to .. _foreign_declarations:
I added HDL_LOGIC_STATE/CHAR to ghdl.h and expanded the tests in tb.vhdl and main.c

I think main.c should be renamed, its name had me searching for main() and anticipating ghd_main() calls.

🚨 Before submitting your PR, please read contribute in the Docs, and review the following checklist:

• Satisfies converstation under doc: add VHPIDIRECT demo ghdl/ghdl#1059.

When contributing to the GHDL codebase...

• requesting to pull a topic/feature/bugfix branch (right side). Don't request your master!
• making a pull request against the master branch (left side). Also you should start your branch off our master.
• GHDL can be successfully built. See Building GHDL.
• modifying the docs
• AVOID breaking the continuous integration build.
• AVOID breaking the testsuite.

When contributing to the docs...

• the build is successful. See.

Further comments

Primarily related to merging HDL_LOGIC_STATE and CHAR

❤️ Thank you!

---

Edit

• Existing unit test of tb.vhd/main.c with run.sh, PR now solves the issues with ghdlFromArray returning an unconstrained array of integers from C to VHDL (top of doc: add VHPIDIRECT demo ghdl/ghdl#1059)

[radonnachie]

Now the ghdl_NaturalDimArr_t->bounds is of type range_t*, enabling capabilities for unconstrained arrays of any dimension. This also simplified the ghdlFrom/ToArray() functions.

All tests are still passing.

---

Each index of an array is given the value of 11*(indexId+1), where indexId is the sequential enumeration of the possible indices: eg. 2D array (2, 3): (0,0)=0, (0,1)=1, (0,2)=2, (1,0)=3, (2,0)=4...etc.
For the 2D and 3D verification printouts in C, the (indexId) is printed after the [index list].

This is the output:

.../doc/examples/vhpidirect/demo$ ./run.sh 

1D Array values [5]:
[0]: 11
[1]: 22
[2]: 33
[3]: 44
[4]: 55

2D Array values [2,3]:
mat[0][0] = 11  mat[0][1] = 22  mat[0][2] = 33
mat[1][0] = 44  mat[1][1] = 55  mat[1][2] = 66

3D Array values [2,4,3]:
d3[0][0][0] = 11        d3[0][0][1] = 22        d3[0][0][2] = 33
d3[0][1][0] = 44        d3[0][1][1] = 55        d3[0][1][2] = 66
d3[0][2][0] = 77        d3[0][2][1] = 88        d3[0][2][2] = 99
d3[0][3][0] = 110       d3[0][3][1] = 121       d3[0][3][2] = 132

d3[1][0][0] = 143       d3[1][0][1] = 154       d3[1][0][2] = 165
d3[1][1][0] = 176       d3[1][1][1] = 187       d3[1][1][2] = 198
d3[1][2][0] = 209       d3[1][2][1] = 220       d3[1][2][2] = 231
d3[1][3][0] = 242       d3[1][3][1] = 253       d3[1][3][2] = 264

v_logic  : H
v_ulogic : Z
v_char : k
v_int  : -6
v_nat  : 9
v_pos  : 3
v_real : 3.340000
v_bool : 1
v_bit  : 1
v_time : 20000000
v_rec  : 0x7ffd82dffe10 y 5
v_enum : 2 2
v_str  : 0x560f70d1c0b8 'hellostr' [8]
v_vec_int  : 0x560f70d1c0e0 [5]
v_vec_real : 0x560f70d1c120 [6]
v_vec_bool : 0x7ffd82dffe0c [4]
v_vec_bit  : 0x560f70d1c188 [4]
v_vec_phy  : 0x7ffd82dffdc8 [3]
v_vec_rec  : 0x7ffd82dffd90 [2]
v_vec_enum : 0x7ffd82dffd55 [3]
v_2vec_real : 0x7ffd82dffd55 [2, 3]

Verify GHDL Matrix in C
C assert: 11 == (val: 11) @ [0,0](0)
C assert: 22 == (val: 22) @ [0,1](1)
C assert: 33 == (val: 33) @ [1,0](2)
C assert: 44 == (val: 44) @ [1,1](3)
C assert: 55 == (val: 55) @ [2,0](4)
C assert: 66 == (val: 66) @ [2,1](5)
v_mat_int  : 0x7ffd82dffc88 [3,2]


Verify the 3D GHDL array in C
C assert: 11 == (val: 11) @ [0,0,0](0)
C assert: 22 == (val: 22) @ [0,0,1](1)
C assert: 33 == (val: 33) @ [0,1,0](2)
C assert: 44 == (val: 44) @ [0,1,1](3)
C assert: 55 == (val: 55) @ [1,0,0](4)
C assert: 66 == (val: 66) @ [1,0,1](5)
C assert: 77 == (val: 77) @ [1,1,0](6)
C assert: 88 == (val: 88) @ [1,1,1](7)
C assert: 99 == (val: 99) @ [2,0,0](8)
C assert: 110 == (val: 110) @ [2,0,1](9)
C assert: 121 == (val: 121) @ [2,1,0](10)
C assert: 132 == (val: 132) @ [2,1,1](11)
v_3d_int  : 0x7ffd82dffc30 [3,2,2]

end testCinterface

tb.vhd:128:5:@0ms:(report note): g_str'length: 11
tb.vhd:130:7:@0ms:(report note): g_str: HELLO WORLD
tb.vhd:132:5:@0ms:(report note): string: HELLO WORLD
tb.vhd:134:5:@0ms:(report note): g_int_vec'length: 5
tb.vhd:136:7:@0ms:(report note): 0: 11
tb.vhd:136:7:@0ms:(report note): 1: 22
tb.vhd:136:7:@0ms:(report note): 2: 33
tb.vhd:136:7:@0ms:(report note): 3: 44
tb.vhd:136:7:@0ms:(report note): 4: 55
tb.vhd:140:5:@0ms:(report note): g_line: HELLO WORLD
tb.vhd:141:5:@0ms:(report note): getLine: HELLO WORLD
tb.vhd:168:5:@0ms:(report note): g_int_mat'length: 2
tb.vhd:173:9:@0ms:(report note): Asserted Mat [0,0]: 11
tb.vhd:173:9:@0ms:(report note): Asserted Mat [0,1]: 22
tb.vhd:173:9:@0ms:(report note): Asserted Mat [0,2]: 33
tb.vhd:173:9:@0ms:(report note): Asserted Mat [1,0]: 44
tb.vhd:173:9:@0ms:(report note): Asserted Mat [1,1]: 55
tb.vhd:173:9:@0ms:(report note): Asserted Mat [1,2]: 66
tb.vhd:178:5:@0ms:(report note): g_int_3d'length: 2
tb.vhd:184:11:@0ms:(report note): Asserted 3D [0,0,0]: 11
tb.vhd:184:11:@0ms:(report note): Asserted 3D [0,0,1]: 22
tb.vhd:184:11:@0ms:(report note): Asserted 3D [0,0,2]: 33
tb.vhd:184:11:@0ms:(report note): Asserted 3D [0,1,0]: 44
tb.vhd:184:11:@0ms:(report note): Asserted 3D [0,1,1]: 55
tb.vhd:184:11:@0ms:(report note): Asserted 3D [0,1,2]: 66
tb.vhd:184:11:@0ms:(report note): Asserted 3D [0,2,0]: 77
tb.vhd:184:11:@0ms:(report note): Asserted 3D [0,2,1]: 88
tb.vhd:184:11:@0ms:(report note): Asserted 3D [0,2,2]: 99
tb.vhd:184:11:@0ms:(report note): Asserted 3D [0,3,0]: 110
tb.vhd:184:11:@0ms:(report note): Asserted 3D [0,3,1]: 121
tb.vhd:184:11:@0ms:(report note): Asserted 3D [0,3,2]: 132
tb.vhd:184:11:@0ms:(report note): Asserted 3D [1,0,0]: 143
tb.vhd:184:11:@0ms:(report note): Asserted 3D [1,0,1]: 154
tb.vhd:184:11:@0ms:(report note): Asserted 3D [1,0,2]: 165
tb.vhd:184:11:@0ms:(report note): Asserted 3D [1,1,0]: 176
tb.vhd:184:11:@0ms:(report note): Asserted 3D [1,1,1]: 187
tb.vhd:184:11:@0ms:(report note): Asserted 3D [1,1,2]: 198
tb.vhd:184:11:@0ms:(report note): Asserted 3D [1,2,0]: 209
tb.vhd:184:11:@0ms:(report note): Asserted 3D [1,2,1]: 220
tb.vhd:184:11:@0ms:(report note): Asserted 3D [1,2,2]: 231
tb.vhd:184:11:@0ms:(report note): Asserted 3D [1,3,0]: 242
tb.vhd:184:11:@0ms:(report note): Asserted 3D [1,3,1]: 253
tb.vhd:184:11:@0ms:(report note): Asserted 3D [1,3,2]: 264

[umarcor]

Now that ghdl/ghdl-cosim is created, I think that this PR should be split into, at least, three different PRs:

• Modifications to the doc sources that are still located at ghdl/ghdl.
• Enhancements to ghdl.h and example 'demo' (Header file for VHPIDIRECT/C and demo ghdl/ghdl-cosim#3).
• Addition of example 'accarray', "Access to array". Actually, I'd further split it into 3 different examples:
  • A first one to just show that foreign procedures/functions can be defined in a package. All existing examples now do define them in the arch. The example would be as easy as having a simple C function and using it from two different entities/modules/components.
  • A second one to pass an array, including two possible solutions to using shared variables (-frelaxed or defining a protected type). This should use "easy" types.
  • A last one to show how to handle logic types. Since most of the signals in HDL designs are directly or indirectly std_logic or std_logic_vector, I believe it deserves a specific example. In fact, there might be multiple ways to handle the representation in C.

Having 5 separate PRs will hopefully make it easier to review them. I think that 1, 3 and 5 will be fast, while 2 and 4 might require some more care.

Since there are ~50 commits in this PR, I'd suggest to first rebase and then use filter-branch to extract subsets of changes.

[radonnachie]

I will keep track of the PRs that spawn off of this one:

• Modifications to the doc sources that are still located at ghdl/ghdl.

  • doc: add use case of -frelaxed ghdl/ghdl#1223
  • doc(vhpidirect/examples): break section statement out of IMPORTANT ghdl-cosim#9

• Enhancements to ghdl.h and example 'demo' (Header file for VHPIDIRECT/C and demo ghdl/ghdl-cosim#3).

  • Updated Header: std_u/logic, N Dim unconstrained arrays. ghdl-cosim#3

• Addition of example 'accarray', "Access to array". Actually, I'd further split it into 3 different examples:

  • A first one to just show that foreign procedures/functions can be defined in a package. All existing examples now do define them in the arch. The example would be as easy as having a simple C function and using it from two different entities/modules/components.

    • vhpidirect: add 'quickstart/package' ghdl-cosim#7
    • quickstart/sharedvar Example (Set Package shared variable) ghdl-cosim#4 vhpidirect: add 'quickstart/sharedvar' ghdl-cosim#13

  • A second one to pass an array, including two possible solutions to using shared variables (-frelaxed or defining a protected type). This should use "easy" types.

    • cinterface/accarraygen example (Bounded by Generic Package - VHDL 2008) ghdl-cosim#5
    • Add packageless intvector examples (#5 a + c) ghdl-cosim#11
    • Add packageless intvector generic example (#5 c) ghdl-cosim#12

  • A last one to show how to handle logic types. Since most of the signals in HDL designs are directly or indirectly std_logic or std_logic_vector, I believe it deserves a specific example. In fact, there might be multiple ways to handle the representation in C.

    • quickstart/logicvector example (Bounded) ghdl-cosim#6
    • cinterface/intro Example (Header intro) ghdl-cosim#8

[radonnachie]

A last one to show how to handle logic types. Since most of the signals in HDL designs are directly or indirectly std_logic or std_logic_vector

I was thinking this last night... Rather keen, but I will leave it for last as it is the most novel.