LCS2016_015 < P1076

P1076 Web>VHDL2017>LCS2016_015 (2017-07-19, JimLewis) (raw view)EditAttach
---+ Language Change Specification for Report Calling Path

---++ 

 | <sticky><b>LCS Number:</b></sticky> | LCS-2016-015 |
 | <sticky><b>Version:</b>   </sticky> | 7 |
 | <sticky><b>Date:</b>      </sticky> | 24-Mar-2017 |
 | <sticky><b>Status:</b>    </sticky> | Voting |
 | <sticky><b>Author:</b>    </sticky> | Jim Lewis |
 | <sticky><b>Email:</b>     </sticky> | [[Main.JimLewis]] and [[Main.PatrickLehmann]] |
 | <sticky><b>Source Doc:</b></sticky> | [[LCS_2016_015_Examples][Examples]] [[LCS_2016_015_History][History]] [[ReportCallingPath][Report Calling Path]] |
 | <sticky><b>Summary:</b>   </sticky> | CALL_..._NAME = Call stack with SIMPLE_NAME, PATH_NAME, INSTANCE_NAME |


%TOC%

---++ Style Notes
<noautolink><sticky>
Changes are shown in %RED%red font%ENDCOLOR%.  
Deletions are %RED%<del>crossed out</del>%ENDCOLOR%. 
Editing notes in %GREEN%green font%ENDCOLOR%. 
 

---++ Details of Language Change

---+++ 16.5 Standard environment package  
---++++ 16.5.1 General %GREEN%015.1:  [NEW headline level]%ENDCOLOR%
Package ENV contains declarations that provide a VHDL interface to the host environment.

 ---+++++%GREEN%015.2: [Additions to Package]%ENDCOLOR%
<pre><font color="black">
use work.textio.all; 
package ENV is
  . . . 
  %GREEN%[OTHER LCS Adding to std.env]%ENDCOLOR%
<font color="red">
  type CALL_PATH_ELEMENT is record
    name             : LINE;   
    file_name        : LINE; 
    file_path        : LINE; 
    file_line        : POSITIVE;  
  end record;
  -- function "="  (anonymous, anonymous: CALL_PATH_ELEMENT) return BOOLEAN;
  -- function "/=" (anonymous, anonymous: CALL_PATH_ELEMENT) return BOOLEAN;  
  impure function TO_STRING (call_path : CALL_PATH_ELEMENT ) return STRING;  

  type CALL_PATH_VECTOR is array (natural range <>) of CALL_PATH_ELEMENT;   
  -- function "="  (anonymous, anonymous: CALL_PATH_VECTOR) return BOOLEAN;
  -- function "/=" (anonymous, anonymous: CALL_PATH_VECTOR) return BOOLEAN;
  impure function TO_STRING (call_path : CALL_PATH_VECTOR; Separator : STRING := "" & LF ) return STRING; 

  type CALL_PATH_VECTOR_PTR is access CALL_PATH_VECTOR;                    
  -- function "="  (anonymous, anonymous: CALL_PATH_VECTOR_PTR) return BOOLEAN;
  -- function "/=" (anonymous, anonymous: CALL_PATH_VECTOR_PTR) return BOOLEAN;
  -- procedure DEALLOCATE (P: inout CALL_PATH_VECTOR_PTR);
  impure function TO_STRING (call_path : CALL_PATH_VECTOR_PTR; Separator : STRING := "" & LF ) return STRING; 
  
  impure function GET_CALL_PATH return CALL_PATH_VECTOR_PTR;</font>
  
end package ENV;
</font></pre>

---++++ %RED%16.5.X Current file and line%ENDCOLOR%  %GREEN%015.3:  [NEW headline level]%ENDCOLOR%
 ---+++++%GREEN%015.3-1: [added paragraph 1]%ENDCOLOR%
<font color="red">
The record type CALL_PATH_ELEMENT contains calling information for 
one element of the call stack.  
The name element contains either the name a subprogram or the name of 
the construct that called the subprogram.
The file_name element contains the VHDL file name.  
The file_name does not contain any path information.
The file_path element contains the fully resolved absolute path 
of the current VHDL file.
The file_path shall not include the name. 
The file_path shall not end with a directory separator.
The file_line element contains the line number in the current file.

 ---+++++%GREEN%015.3-2: [added paragraph 2]%ENDCOLOR%
The overloaded function TO_STRING[CALL_PATH_ELEMENT return STRING] 
converts a CALL_PATH_ELEMENT to type STRING.
This STRING is the result of concatenating
the value designated by the file_path element,
the value returned by DIR_SEPARATOR, %GREEN%[see LCS_2016_006c]%ENDCOLOR%
the value designated by the file_name element,
a colon, 
the result of calling TO_STRING on the file_line element,
a colon, 
and finally
the value designated by the name element.   

 ---+++++%GREEN%015.3-3: [added paragraph 3]%ENDCOLOR%
The type CALL_PATH_VECTOR is a one-dimensional array 
of the type CALL_PATH_ELEMENT.
The left most element of CALL_PATH_VECTOR is 
the CALL_PATH_ELEMENT for the current subprogram.
The right most element of CALL_PATH_VECTOR is 
the root of the call stack.
The CALL_PATH_ELEMENT name element of each record, except the last one,
contains the name of the subprogram.
The CALL_PATH_ELEMENT name element of the last record (the root)
is the architecture or process name that initiated the call sequence.

 ---+++++%GREEN%015.3-4: [added paragraph 4]%ENDCOLOR%
The overloaded function TO_STRING[CALL_PATH_VECTOR, STRING return STRING] 
converts a CALL_PATH_VECTOR to type STRING.
If the range of call_path is not a null range, to_STRING returns a STRING 
value which is the concatenation of the STRING value of each element value, 
in the order of left to right, separated by the parameter separator.
The STRING value of an element value is determined by calling 
TO_STRING(Path(I)) where I is the Ith element of Path.  
If the range of the Path is a null range, TO_STRING returns "" (an empty STRING value).

 ---+++++%GREEN%015.3-5: [added paragraph 5]%ENDCOLOR%
The type CALL_PATH_VECTOR_PTR is a access type whose 
designated type is CALL_PATH_VECTOR.

 ---+++++%GREEN%015.3-6: [added paragraph 6]%ENDCOLOR%
The overloaded function TO_STRING[CALL_PATH_VECTOR_PTR, STRING return STRING] 
converts a CALL_PATH_VECTOR_PTR to type STRING.  
If Path is not a null access value, TO_STRING returns the value 
of TO_STRING(Path.all, path_separator).
If Path is a null access value, TO_STRING returns "" (an empty STRING value).

 ---+++++%GREEN%015.3-7: [added paragraph 7]%ENDCOLOR%
The function GET_CALL_PATH returns a value of CALL_PATH_VECTOR_PTR.   
If GET_CALL_PATH is called from a place other than a subprogram,
the call path contains only the information for the construct that 
called GET_CALL_PATH.   
The value designated by the return value has an ascending index range
and a left-most index that is 0.
</font>

<br>
<br>

---++ Comments
Topic revision: r23 - 2017-07-19 - 10:25:25 - JimLewis
P1076