quickstart/logicvector example (Bounded)

doc/vhpidirect/examples/quickstart.rst

@@ -42,3 +42,40 @@ When the required functionality is not available in pre-built libraries, custom
 This example shows how to bind custom C functions in VHDL as either procedures or functions. Four cases are included: ``custom_procedure``, ``custom_procedure_withargs``, ``custom_function`` and ``custom_function_withargs``. In all cases, the parameters are defined as integers, in order to keep it simple. See :ref:`COSIM:VHPIDIRECT:Declarations` for further details.
 
 Since either C sources or pre-compiled ``.o`` objects can be added, in C/C++ projects of moderate complexity, it might be desirable to merge all the C sources in a single object before elaborating the design.
+
+:cosimtree:`logicvectors <vhpidirect/quickstart/logicvectors>`
+**************************************************************
+
+Commonly signals in VHDL are of a logic type or a vector thereof (``std_logic`` and ``std_logic_vector``), coming from the ``ieee.std_logic_1164.*`` package.
+Because logic values are more than high and low (``1`` and ``0``), the VHDL values of logic types (``std_logic`` and ``std_ulogic``) are enumrations:
+
+0. 'U' 
+1. 'X' 
+2. '0' 
+3. '1' 
+4. 'Z' 
+5. 'W' 
+6. 'L' 
+7. 'H' 
+8. '-' 
+
+Because number of enumeration values is less than 256, logic values are transported in 8 bit words (a ``char`` type in C).
+Logic vectors, of a bounded size, are easily created in C and passed to VHDL as ``char[]``. VHDL receives pointers as ``access`` types, in this case an access of a subtype of std_logic_vector.
+
+Providing logic values in C as their enumeration numbers is simplified with the use of a matching enumeration, provided as ``HDL_LOGIC_STATES``. Printing out a logic value's associated character is also simplified with the provided ``const char HDL_LOGIC_CHAR[]``.
+
+This example declares foreign subprograms that enable receiving the size of two different logic vectors as well as the vectors themselves from C. The two vectors are populated with logic values in different ways:
+
+- LogicVectorA's indices are manually filled with enumeration values from HDL_LOGIC_STATES.
+
+  - .. code-block:: C
+
+        logic_vec_A[0] = HDL_U;
+
+- LogicVectorB's indices are filled with an integer value. **The integer values must be limited to [0, 8]**.
+
+  - .. code-block:: C
+
+        for(int i = 0; i < SIZE_LOGIC_VEC_B; i++){
+          logic_vec_B[i] = 8-i;
+        }

vhpidirect/quickstart/logicvector/main.c → vhpidirect/quickstart/logicvector/caux.c

@@ -4,7 +4,7 @@
 
 static const char HDL_LOGIC_CHAR[] = { 'U', 'X', '0', '1', 'Z', 'W', 'L', 'H', '-'};
 
-enum HDL_LOGIC_STATE {
+enum HDL_LOGIC_STATES {
 HDL_U = 0,
 HDL_X = 1,
 HDL_0 = 2,
@@ -27,7 +27,7 @@ int getLogicVecSize(int returnA){
 }
 
 char* getLogicVecA(){
-	//The HDL_LOGIC_STATE enum is used
+	//The HDL_LOGIC_STATES enum is used
 	logic_vec_A[0] = HDL_U;
 	logic_vec_A[1] = HDL_X;
 	logic_vec_A[2] = HDL_0;
@@ -41,7 +41,7 @@ char* getLogicVecA(){
 }
 
 char* getLogicVecB(){
-	//The equivalent value of HDL_LOGIC_STATE is used
+	//The equivalent value of HDL_LOGIC_STATES is used
 	printf("B: 1D Array Logic Values [%ld]:\n", SIZE_LOGIC_VEC_B);
 	for(int i = 0; i < SIZE_LOGIC_VEC_B; i++){
 		logic_vec_B[i] = 8-i;//The last 'SIZE_LOGIC_VEC_B' HDL_LOGIC values, in reverse order.