P1076 Web>VHDL2017>LCS2016_015 (2017-07-19, JimLewis)EditAttach

Language Change Specification for Report Calling Path

LCS Number:	LCS-2016-015
Version:	7
Date:	24-Mar-2017
Status:	Voting
Author:	Jim Lewis
Email:	Main.JimLewis and Main.PatrickLehmann
Source Doc:	Examples History Report Calling Path
Summary:	CALL_..._NAME = Call stack with SIMPLE_NAME, PATH_NAME, INSTANCE_NAME

Language Change Specification for Report Calling Path

Style Notes

Changes are shown in red font. Deletions are ~~crossed out~~. Editing notes in green font.

Details of Language Change

16.5 Standard environment package

16.5.1 General 015.1: [NEW headline level]

Package ENV contains declarations that provide a VHDL interface to the host environment.

---+++++015.2: [Additions to Package]


use work.textio.all; 
package ENV is
  . . . 
  [OTHER LCS Adding to std.env]

  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;
  
end package ENV;

16.5.X Current file and line 015.3: [NEW headline level]

---+++++015.3-1: [added paragraph 1] 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.

---+++++015.3-2: [added paragraph 2] 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, [see LCS_2016_006c] 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.

---+++++015.3-3: [added paragraph 3] 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.

---+++++015.3-4: [added paragraph 4] 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).

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

---+++++015.3-6: [added paragraph 6] 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).

---+++++015.3-7: [added paragraph 7] 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.

Comments

Topic revision: r23 - 2017-07-19 - 10:25:25 - JimLewis

P1076