Symbol entries: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: Symbol entries

New		Line
1	+	back to contents [[FPC internals]]
2	+
3	+	# Symbol entries
4	+
5	+	## Architecture
6	+
7	+	> Warning: Last updated for FPC version 1.0.x
8	+
9	+	There are different possible types of symbols, each one having different fields then the others. Each symbol type has a specific signature to indicate what kind of entry it is. Each entry in the symbol table is actually one of the symbol entries described in the following sections. The relationship between a symbol entry, a type definition, and the type name symbol entry is shown in the following figure:
10	+
11	+	<http://www.pjh2.de/fpc/CompilerInternalsFigure06.png>
12	+
13	+	## Symbol entry types
14	+
15	+	> Warning: Last updated for FPC version 1.0.x
16	+
17	+	### Base symbol type (TSym)
18	+
19	+	All entries in the symbol table are derived from this base object which contains information on the symbol type as well as information on the owner of this symbol entry.
20	+
21	+	``` pascal
22	+	type
23	+	PSym = ^TSym;
24	+	TSym = object(TSymTableEntry)
25	+	SymOptions: TSymOptions; // Indicate the access scope of the symbol
26	+	FileInfo: TFilePosInfo;
27	+	Refs: Longint; // Indicates how many times this label is refered in the
28	+	// parsed code (is only used with variable and assembler
29	+	// label symbols).
30	+	LastRef: PRef;
31	+	DefRef: PRef;
32	+	LastWritten: PRef;
33	+	RefCount: Longint; // Browser information indicating the reference count
34	+	Typ: TSymTyp; // Indicates the symbol type
35	+	IsStabWritten: Boolean; // Set to TRUE if the stabs debugging information has
36	+	// been written for this symbol.
37	+	end;
38	+	```
39	+
40	+	\| TSymTyp \| Description \|
41	+	\|----\|----\|
42	+	\| AbstractSym \| This is a special abstract symbol (this should never occur) \|
43	+	\| VarSym \| This symbol is a variable declaration in the var section, or a var parameter. \|
44	+	\| TypeSym \| This symbol is a type name \|
45	+	\| ProcSym \| This symbol is a routine or method name \|
46	+	\| UnitSym \| This symbol is a unit name \|
47	+	\| ProgramSym \| This symbol is the main program name \|
48	+	\| ConstSym \| This symbol is a constant \|
49	+	\| EnumSym \| This symbol is an enumeration symbol (an element in an enumeration) \|
50	+	\| TypedConstSym \| This symbol is pre-initialized variable (pascal typed constant) \|
51	+	\| ErrorSym \| This symbol is created for error generation \|
52	+	\| SysSym \| This symbol represents an inlined system unit routine \|
53	+	\| LabelSym \| This symbol represents a label in a label pascal declaration \|
54	+	\| AbsoluteSym \| This symbol represents an the symbol following an absolute variable declaration \|
55	+	\| PropertySym \| This symbol is a property name \|
56	+	\| FuncRetSym \| This symbol is the name of the return value for functions \|
57	+	\| MacroSym \| This symbol is a macro symbol (just like \#define in C) \|
58	+
59	+	### Label symbol (TLabelSym)
60	+
61	+	The label symbol table entry is only created when a pascal label is declared via the label keyword. The object has the following fields which are available for use publicly:
62	+
63	+	``` pascal
64	+	type
65	+	PLabelSym = ^TLabelSym;
66	+	TLabelSym = object(TSym)
67	+	Used: Boolean; // Set to TRUE if this pascal label is used using a goto
68	+	// or in an assembler statement
69	+	Defined: Boolean; // Set to TRUE if this label has been declared
70	+	Lab: PAsmLabel; // Points to the actual assembler label structure which
71	+	// will be emitted by the code generator
72	+	Code: Pointer;
73	+	end;
74	+	```
75	+
76	+	### Unit symbol (TUnitSym)
77	+
78	+	The unit symbol is created and added to the symbol table each time that the uses clause is parsed and a unit name is found, it is also used when compiling a unit, with the first entry in that symbol table being the unit name being compiled. The unit symbol entry is actual part of a linked list which is used in the unit symbol table.
79	+
80	+	``` pascal
81	+	type
82	+	PUnitSym = ^TUnitSym;
83	+	TUnitSym = object(TSym)
84	+	UnitSymTable: PUnitSymTable; // Pointer to the global symbol table for that
85	+	// unit, containing entries for each public?
86	+	// symbol in that unit
87	+	PrevSym: PUnitSym; // Pointer to previous entry in the linked list
88	+	end;
89	+	```
90	+
91	+	### Macro symbol (TMacroSym)
92	+
93	+	The macro synbols are used in the preprocessor for conditional compilation statements. There is one such entry created for each \$define directive, it contains the value of the define (stored as a string).
94	+
95	+	``` pascal
96	+	type
97	+	PMacroSym = ^TMacroSym;
98	+	TMacroSym = object(TSym)
99	+	Defined: Boolean; // TRUE if the symbol has been defined with a
100	+	// $define directive, or false if it has been
101	+	// undefined with a $undef directive
102	+	Defined_At_Startup: Boolean; // TRUE if the symbol is a system wide define
103	+	Is_Used: Boolean; // TRUE if the define has been used such as in
104	+	// a $ifdef directive.
105	+	BufText: PChar; // The actual string text of the define
106	+	BufLength: Longint; // The actual string length of the define
107	+	end;
108	+	```
109	+
110	+	### Error symbol (TErrorSym)
111	+
112	+	This symbol is actually an empty symbol table entry. When the parser encounters an error when parsing a symbol, instead of putting nothing in the symbol table, it puts this symbol entry. This avoids illegal memory accesses later in parsing.
113	+
114	+	### Procedure symbol (TProcSym)
115	+
116	+	The procedure symbol is created each time a routine is defined in the code. This can be either a forward definition or the actual implementation of the routine. After creation, the symbol is added into the appropriate symbol table stack.
117	+
118	+	``` pascal
119	+	type
120	+	PProcSym = ^TProcSym;
121	+	TProcSym = object(TSym)
122	+	Is_Global: Boolean; // Set if the routine is exported by the unit
123	+	Definition: PProcDef; // Procedure definition, including parameter
124	+	// information and return values
125	+	end;
126	+	```
127	+
128	+	### Type symbol (TTypeSym)
129	+
130	+	The type symbol is created each time a new type declaration is done, the current symbol table stack is then inserted with this symbol. Furthermore, each time the compiler compiles a module, the default base types are initialized and added into the symbol table (psystem.pas) The type symbol contains the name of a type, as well as a pointer to its type definition.
131	+
132	+	``` pascal
133	+	type
134	+	PTypeSym = ^TTypeSym;
135	+	TTypeSym = object(TSym)
136	+	ResType: TType; // Contains base type information as well as the type
137	+	// definition
138	+	end;
139	+	```
140	+
141	+	### Variable symbol (TVarSym)
142	+
143	+	Variable declarations, as well as parameters which are passed onto routines are declared as variable symbol types. Access information, as well as type information and optimization information are stored in this symbol type.
144	+
145	+	``` pascal
146	+	type
147	+	PVarSym = ^TVarSym;
148	+	TVarSym = object(TSym)
149	+	Reg: TRegister; // If the value is a register variable, the reg field will
150	+	// be different then R_NO
151	+	VarSpez: TVarSpez; // Indicates the variable type (parameters only) (Cf. 32).
152	+	Address: Longint; // In the case where the variable is a routine parameter,
153	+	// this indicates the positive offset from theframe_pointer
154	+	// to access this variable. In the caseof a local variable,
155	+	// this field indicates the negative offset from the
156	+	// frame_pointer. to access this variable.
157	+	LocalVarSym: PVarSym;
158	+	VarType: TType; // Contains base type information as well as the type
159	+	// definition
160	+	VarOptions: TVarOptions; // Flags for this variable (Cf. 31)
161	+	VarState: TVarState; // Indicates the state of the variable, if it’s used or
162	+	// declared
163	+	end;
164	+	```
165	+
166	+	\| TVarOptions \| Description \|
167	+	\|----\|----\|
168	+	\| vo_regable \| The variable can be put into a hardware general purpose register \|
169	+	\| vo_is_c_var \| The variable is imported from a C module \|
170	+	\| vo_is_external \| The variable is declared external \|
171	+	\| vo_is_Dll_var \| The variable is a shared library variable \|
172	+	\| vo_is_thread_var \| The variable is declared as being thread safe \|
173	+	\| vo_fpuregable \| The variable can be put into a hardware floating point register \|
174	+	\| vo_is_local_copy \| \|
175	+	\| vo_is_const \| unused and useless \|
176	+	\| vo_is_exported \| The variable is declared as exported in a dynamic link library \|
177	+
178	+	\| TVarSpez \| Description \|
179	+	\|----------\|-------------------------------------------------\|
180	+	\| vs_value \| This is a value parameter \|
181	+	\| vs_const \| This is a constant parameter, property or array \|
182	+	\| vs_var \| This is a variable parameter \|
183	+
184	+	### Property symbol (TPropertySym)
185	+
186	+	``` pascal
187	+	type
188	+	PPropertySym = ^TPropertySym;
189	+	TPropertySym = object(TSym)
190	+	PropOptions: TPropertyOptions; // ???
191	+	PropType: TType; // Indicates the type of the property
192	+	PropOverriden: PPropertySym; // ???
193	+	IndexType: TType;
194	+	Index: Longint; // ????
195	+	Default: Longint; // ???
196	+	ReadAccess: PSymList; // ???
197	+	WriteAccess: PSymList; // ???
198	+	StoredAccess: PSymList; // ???
199	+	end;
200	+	```
201	+
202	+	### Return value of function symbol
203	+
204	+	...
205	+
206	+	### Absolute declared symbol (TAbsoluteSym)
207	+
208	+	This symbol represents a variable declared with the `absolute` keyword. The address of the `TVarSym` object holds the address of the variable in the case of an absolute address variable.
209	+
210	+	The possible types of absolute symbols, are from an external object reference, an absolute address (for certain targets only), or on top of another declared variable.
211	+
212	+	``` pascal
213	+	type
214	+	PAbsoluteSym = ^TAbsoluteSym;
215	+	TAbsoluteSym = object(TVarSym)
216	+	AbsTyp: TAbsoluteTyp; // Indicates the type of absolute symbol it is
217	+	AbsSeg: Boolean; // ???
218	+	Ref: PSym; // In case abstyp is tovar, this field indicates the
219	+	// symbol which is overlaid with this symbol. Otherwise
220	+	// this field is unused.
221	+	AsmName: PString; // In case abstyp is toasm, this field indicates label
222	+	// name for the variable.
223	+	end;
224	+	```
225	+
226	+	\| TAbsoluteTyp \| Description \|
227	+	\|----\|----\|
228	+	\| toVar \| The symbol will be declared on top of another symbol (variable or typed constant) \|
229	+	\| toAsm \| The variable is imported from an external module \|
230	+	\| toAddr \| The variable is declared as being at an absolute address \|
231	+
232	+	### Typed constant symbol
233	+
234	+	...
235	+
236	+	### Constant symbol (TConstSym)
237	+
238	+	This symbol type will contain all constants defined and encountered during the parsing. The values of the constants are also set in this symbol type entry.
239	+
240	+	``` pascal
241	+	type
242	+	PConstSym = ^TConstSym;
243	+	TConstSym = object(TSym)
244	+	ConstType: TType; // Type information for this constant (?).
245	+	ConstTyp: TConstTyp; // Indicates the type of the constant
246	+	ResStrIndex: Longint; // If this is a resource string constant, it indicates the
247	+	// index in the resource table
248	+	Value: Longint; // In certain cases, contains the value of the constant
249	+	Len: Longint;
250	+	end;
251	+	```
252	+
253	+	### Enumeration symbol
254	+
255	+	...
256	+
257	+	### Program symbol
258	+
259	+	The program symbol type (`TProgramSym`) is used to store the name of the program, which is declared using `program` in the pascal source. This symbol type is currently unused in FreePascal.
260	+
261	+	### Sys symbol
262	+
263	+	The `TSysSym` symbol type is used to load indexes into the symbol table of the internal routines which are inlined directly by the compiler. It has a single field, which is the index of the inline routine.
264	+
265	+	## Symbol interface
266	+
267	+	Next chapter: [[Type information]]
268	+
269	+	---
270	+	From the Free Pascal wiki, page "Symbol entries", as it stood on 2020-12-25 after a change by E-ric, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history