1 // backend.h -- Go frontend interface to backend -*- C++ -*-
3 // Copyright 2011 The Go Authors. All rights reserved.
4 // Use of this source code is governed by a BSD-style
5 // license that can be found in the LICENSE file.
15 // Pointers to these types are created by the backend, passed to the
16 // frontend, and passed back to the backend. The types must be
17 // defined by the backend using these names.
19 // The backend representation of a type.
22 // The backend represention of an expression.
25 // The backend representation of a statement.
28 // The backend representation of a function definition or declaration.
31 // The backend representation of a block.
34 // The backend representation of a variable.
37 // The backend representation of a label.
40 // The backend interface. This is a pure abstract class that a
41 // specific backend will implement.
46 virtual ~Backend() { }
48 // Name/type/location. Used for function parameters, struct fields,
50 struct Btyped_identifier
57 : name(), btype(NULL
), location(UNKNOWN_LOCATION
)
60 Btyped_identifier(const std::string
& a_name
, Btype
* a_btype
,
62 : name(a_name
), btype(a_btype
), location(a_location
)
68 // Produce an error type. Actually the backend could probably just
69 // crash if this is called.
73 // Get a void type. This is used in (at least) two ways: 1) as the
74 // return type of a function with no result parameters; 2)
75 // unsafe.Pointer is represented as *void.
79 // Get the unnamed boolean type.
83 // Get an unnamed integer type with the given signedness and number
86 integer_type(bool is_unsigned
, int bits
) = 0;
88 // Get an unnamed floating point type with the given number of bits
91 float_type(int bits
) = 0;
93 // Get an unnamed complex type with the given number of bits (64 or 128).
95 complex_type(int bits
) = 0;
97 // Get a pointer type.
99 pointer_type(Btype
* to_type
) = 0;
101 // Get a function type. The receiver, parameter, and results are
102 // generated from the types in the Function_type. The Function_type
103 // is provided so that the names are available. This should return
104 // not the type of a Go function (which is a pointer to a struct)
105 // but the type of a C function pointer (which will be used as the
106 // type of the first field of the struct). If there is more than
107 // one result, RESULT_STRUCT is a struct type to hold the results,
108 // and RESULTS may be ignored; if there are zero or one results,
109 // RESULT_STRUCT is NULL.
111 function_type(const Btyped_identifier
& receiver
,
112 const std::vector
<Btyped_identifier
>& parameters
,
113 const std::vector
<Btyped_identifier
>& results
,
114 Btype
* result_struct
,
115 Location location
) = 0;
117 // Get a struct type.
119 struct_type(const std::vector
<Btyped_identifier
>& fields
) = 0;
121 // Get an array type.
123 array_type(Btype
* element_type
, Bexpression
* length
) = 0;
125 // Create a placeholder pointer type. This is used for a named
126 // pointer type, since in Go a pointer type may refer to itself.
127 // NAME is the name of the type, and the location is where the named
128 // type is defined. This function is also used for unnamed function
129 // types with multiple results, in which case the type has no name
130 // and NAME will be empty. FOR_FUNCTION is true if this is for a C
131 // pointer to function type. A Go func type is represented as a
132 // pointer to a struct, and the first field of the struct is a C
133 // pointer to function. The return value will later be passed as
134 // the first parameter to set_placeholder_pointer_type or
135 // set_placeholder_function_type.
137 placeholder_pointer_type(const std::string
& name
, Location
,
138 bool for_function
) = 0;
140 // Fill in a placeholder pointer type as a pointer. This takes a
141 // type returned by placeholder_pointer_type and arranges for it to
142 // point to the type that TO_TYPE points to (that is, PLACEHOLDER
143 // becomes the same type as TO_TYPE). Returns true on success,
146 set_placeholder_pointer_type(Btype
* placeholder
, Btype
* to_type
) = 0;
148 // Fill in a placeholder pointer type as a function. This takes a
149 // type returned by placeholder_pointer_type and arranges for it to
150 // become a real Go function type (which corresponds to a C/C++
151 // pointer to function type). FT will be something returned by the
152 // function_type method. Returns true on success, false on failure.
154 set_placeholder_function_type(Btype
* placeholder
, Btype
* ft
) = 0;
156 // Create a placeholder struct type. This is used for a named
157 // struct type, as with placeholder_pointer_type. It is also used
158 // for interface types, in which case NAME will be the empty string.
160 placeholder_struct_type(const std::string
& name
, Location
) = 0;
162 // Fill in a placeholder struct type. This takes a type returned by
163 // placeholder_struct_type and arranges for it to become a real
164 // struct type. The parameter is as for struct_type. Returns true
165 // on success, false on failure.
167 set_placeholder_struct_type(Btype
* placeholder
,
168 const std::vector
<Btyped_identifier
>& fields
)
171 // Create a placeholder array type. This is used for a named array
172 // type, as with placeholder_pointer_type, to handle cases like
175 placeholder_array_type(const std::string
& name
, Location
) = 0;
177 // Fill in a placeholder array type. This takes a type returned by
178 // placeholder_array_type and arranges for it to become a real array
179 // type. The parameters are as for array_type. Returns true on
180 // success, false on failure.
182 set_placeholder_array_type(Btype
* placeholder
, Btype
* element_type
,
183 Bexpression
* length
) = 0;
185 // Return a named version of a type. The location is the location
186 // of the type definition. This will not be called for a type
187 // created via placeholder_pointer_type, placeholder_struct_type, or
188 // placeholder_array_type.. (It may be called for a pointer,
189 // struct, or array type in a case like "type P *byte; type Q P".)
191 named_type(const std::string
& name
, Btype
*, Location
) = 0;
193 // Create a marker for a circular pointer type. Go pointer and
194 // function types can refer to themselves in ways that are not
195 // permitted in C/C++. When a circular type is found, this function
196 // is called for the circular reference. This permits the backend
197 // to decide how to handle such a type. PLACEHOLDER is the
198 // placeholder type which has already been created; if the backend
199 // is prepared to handle a circular pointer type, it may simply
200 // return PLACEHOLDER. FOR_FUNCTION is true if this is for a
203 // For "type P *P" the sequence of calls will be
204 // bt1 = placeholder_pointer_type();
205 // bt2 = circular_pointer_type(bt1, false);
206 // set_placeholder_pointer_type(bt1, bt2);
208 circular_pointer_type(Btype
* placeholder
, bool for_function
) = 0;
210 // Return whether the argument could be a special type created by
211 // circular_pointer_type. This is used to introduce explicit type
212 // conversions where needed. If circular_pointer_type returns its
213 // PLACEHOLDER parameter, this may safely always return false.
215 is_circular_pointer_type(Btype
*) = 0;
217 // Return the size of a type.
219 type_size(Btype
*) = 0;
221 // Return the alignment of a type.
223 type_alignment(Btype
*) = 0;
225 // Return the alignment of a struct field of this type. This is
226 // normally the same as type_alignment, but not always.
228 type_field_alignment(Btype
*) = 0;
230 // Return the offset of field INDEX in a struct type. INDEX is the
231 // entry in the FIELDS std::vector parameter of struct_type or
232 // set_placeholder_struct_type.
234 type_field_offset(Btype
*, size_t index
) = 0;
238 // Return an expression for a zero value of the given type. This is
239 // used for cases such as local variable initialization and
240 // converting nil to other types.
242 zero_expression(Btype
*) = 0;
244 // Create an error expression. This is used for cases which should
245 // not occur in a correct program, in order to keep the compilation
246 // going without crashing.
248 error_expression() = 0;
250 // Create a reference to a variable.
252 var_expression(Bvariable
* var
, Location
) = 0;
254 // Create an expression that indirects through the pointer expression EXPR
255 // (i.e., return the expression for *EXPR). KNOWN_VALID is true if the pointer
256 // is known to point to a valid memory location.
258 indirect_expression(Bexpression
* expr
, bool known_valid
, Location
) = 0;
260 // Return an expression that declares a constant named NAME with the
261 // constant value VAL in BTYPE.
263 named_constant_expression(Btype
* btype
, const std::string
& name
,
264 Bexpression
* val
, Location
) = 0;
266 // Return an expression for the multi-precision integer VAL in BTYPE.
268 integer_constant_expression(Btype
* btype
, mpz_t val
) = 0;
270 // Return an expression for the floating point value VAL in BTYPE.
272 float_constant_expression(Btype
* btype
, mpfr_t val
) = 0;
274 // Return an expression for the complex value REAL/IMAG in BTYPE.
276 complex_constant_expression(Btype
* btype
, mpfr_t real
, mpfr_t imag
) = 0;
278 // Return an expression for the string value VAL.
280 string_constant_expression(const std::string
& val
) = 0;
282 // Return an expression for the real part of BCOMPLEX.
284 real_part_expression(Bexpression
* bcomplex
, Location
) = 0;
286 // Return an expression for the imaginary part of BCOMPLEX.
288 imag_part_expression(Bexpression
* bcomplex
, Location
) = 0;
290 // Return an expression for the complex number (BREAL, BIMAG).
292 complex_expression(Bexpression
* breal
, Bexpression
* bimag
, Location
) = 0;
294 // Return an expression that converts EXPR to TYPE.
296 convert_expression(Btype
* type
, Bexpression
* expr
, Location
) = 0;
298 // Create an expression for the address of a function. This is used to
299 // get the address of the code for a function.
301 function_code_expression(Bfunction
*, Location
) = 0;
303 // Create an expression that takes the address of an expression.
305 address_expression(Bexpression
*, Location
) = 0;
307 // Return an expression for the field at INDEX in BSTRUCT.
309 struct_field_expression(Bexpression
* bstruct
, size_t index
, Location
) = 0;
311 // Create an expression that executes BSTAT before BEXPR.
313 compound_expression(Bstatement
* bstat
, Bexpression
* bexpr
, Location
) = 0;
315 // Return an expression that executes THEN_EXPR if CONDITION is true, or
316 // ELSE_EXPR otherwise and returns the result as type BTYPE. ELSE_EXPR
317 // may be NULL. BTYPE may be NULL.
319 conditional_expression(Btype
* btype
, Bexpression
* condition
,
320 Bexpression
* then_expr
, Bexpression
* else_expr
,
323 // Return an expression for the unary operation OP EXPR.
324 // Supported values of OP are (from operators.h):
327 unary_expression(Operator op
, Bexpression
* expr
, Location
) = 0;
329 // Return an expression for the binary operation LEFT OP RIGHT.
330 // Supported values of OP are (from operators.h):
331 // EQEQ, NOTEQ, LT, LE, GT, GE, PLUS, MINUS, OR, XOR, MULT, DIV, MOD,
332 // LSHIFT, RSHIFT, AND, NOT.
334 binary_expression(Operator op
, Bexpression
* left
, Bexpression
* right
,
337 // Return an expression that constructs BTYPE with VALS. BTYPE must be the
338 // backend representation a of struct. VALS must be in the same order as the
339 // corresponding fields in BTYPE.
341 constructor_expression(Btype
* btype
, const std::vector
<Bexpression
*>& vals
,
344 // Return an expression that constructs an array of BTYPE with INDEXES and
345 // VALS. INDEXES and VALS must have the same amount of elements. Each index
346 // in INDEXES must be in the same order as the corresponding value in VALS.
348 array_constructor_expression(Btype
* btype
,
349 const std::vector
<unsigned long>& indexes
,
350 const std::vector
<Bexpression
*>& vals
,
353 // Return an expression for the address of BASE[INDEX].
354 // BASE has a pointer type. This is used for slice indexing.
356 pointer_offset_expression(Bexpression
* base
, Bexpression
* index
,
359 // Return an expression for ARRAY[INDEX] as an l-value. ARRAY is a valid
360 // fixed-length array, not a slice.
362 array_index_expression(Bexpression
* array
, Bexpression
* index
, Location
) = 0;
364 // Create an expression for a call to FN with ARGS.
366 call_expression(Bexpression
* fn
, const std::vector
<Bexpression
*>& args
,
371 // Create an error statement. This is used for cases which should
372 // not occur in a correct program, in order to keep the compilation
373 // going without crashing.
375 error_statement() = 0;
377 // Create an expression statement.
379 expression_statement(Bexpression
*) = 0;
381 // Create a variable initialization statement. This initializes a
382 // local variable at the point in the program flow where it is
385 init_statement(Bvariable
* var
, Bexpression
* init
) = 0;
387 // Create an assignment statement.
389 assignment_statement(Bexpression
* lhs
, Bexpression
* rhs
,
392 // Create a return statement, passing the representation of the
393 // function and the list of values to return.
395 return_statement(Bfunction
*, const std::vector
<Bexpression
*>&,
398 // Create an if statement. ELSE_BLOCK may be NULL.
400 if_statement(Bexpression
* condition
, Bblock
* then_block
, Bblock
* else_block
,
403 // Create a switch statement where the case values are constants.
404 // CASES and STATEMENTS must have the same number of entries. If
405 // VALUE matches any of the list in CASES[i], which will all be
406 // integers, then STATEMENTS[i] is executed. STATEMENTS[i] will
407 // either end with a goto statement or will fall through into
408 // STATEMENTS[i + 1]. CASES[i] is empty for the default clause,
409 // which need not be last. FUNCTION is the current function.
411 switch_statement(Bfunction
* function
, Bexpression
* value
,
412 const std::vector
<std::vector
<Bexpression
*> >& cases
,
413 const std::vector
<Bstatement
*>& statements
,
416 // Create a single statement from two statements.
418 compound_statement(Bstatement
*, Bstatement
*) = 0;
420 // Create a single statement from a list of statements.
422 statement_list(const std::vector
<Bstatement
*>&) = 0;
424 // Create a statement that attempts to execute BSTAT and calls EXCEPT_STMT if
425 // an exception occurs. EXCEPT_STMT may be NULL. FINALLY_STMT may be NULL and
426 // if not NULL, it will always be executed. This is used for handling defers
427 // in Go functions. In C++, the resulting code is of this form:
428 // try { BSTAT; } catch { EXCEPT_STMT; } finally { FINALLY_STMT; }
430 exception_handler_statement(Bstatement
* bstat
, Bstatement
* except_stmt
,
431 Bstatement
* finally_stmt
, Location
) = 0;
435 // Create a block. The frontend will call this function when it
436 // starts converting a block within a function. FUNCTION is the
437 // current function. ENCLOSING is the enclosing block; it will be
438 // NULL for the top-level block in a function. VARS is the list of
439 // local variables defined within this block; each entry will be
440 // created by the local_variable function. START_LOCATION is the
441 // location of the start of the block, more or less the location of
442 // the initial curly brace. END_LOCATION is the location of the end
443 // of the block, more or less the location of the final curly brace.
444 // The statements will be added after the block is created.
446 block(Bfunction
* function
, Bblock
* enclosing
,
447 const std::vector
<Bvariable
*>& vars
,
448 Location start_location
, Location end_location
) = 0;
450 // Add the statements to a block. The block is created first. Then
451 // the statements are created. Then the statements are added to the
452 // block. This will called exactly once per block. The vector may
453 // be empty if there are no statements.
455 block_add_statements(Bblock
*, const std::vector
<Bstatement
*>&) = 0;
457 // Return the block as a statement. This is used to include a block
458 // in a list of statements.
460 block_statement(Bblock
*) = 0;
464 // Create an error variable. This is used for cases which should
465 // not occur in a correct program, in order to keep the compilation
466 // going without crashing.
468 error_variable() = 0;
470 // Create a global variable. PACKAGE_NAME is the name of the
471 // package where the variable is defined. PKGPATH is the package
472 // path for that package, from the -fgo-pkgpath or -fgo-prefix
473 // option. NAME is the name of the variable. BTYPE is the type of
474 // the variable. IS_EXTERNAL is true if the variable is defined in
475 // some other package. IS_HIDDEN is true if the variable is not
476 // exported (name begins with a lower case letter).
477 // IN_UNIQUE_SECTION is true if the variable should be put into a
478 // unique section if possible; this is intended to permit the linker
479 // to garbage collect the variable if it is not referenced.
480 // LOCATION is where the variable was defined.
482 global_variable(const std::string
& package_name
,
483 const std::string
& pkgpath
,
484 const std::string
& name
,
488 bool in_unique_section
,
489 Location location
) = 0;
491 // A global variable will 1) be initialized to zero, or 2) be
492 // initialized to a constant value, or 3) be initialized in the init
493 // function. In case 2, the frontend will call
494 // global_variable_set_init to set the initial value. If this is
495 // not called, the backend should initialize a global variable to 0.
496 // The init function may then assign a value to it.
498 global_variable_set_init(Bvariable
*, Bexpression
*) = 0;
500 // Create a local variable. The frontend will create the local
501 // variables first, and then create the block which contains them.
502 // FUNCTION is the function in which the variable is defined. NAME
503 // is the name of the variable. TYPE is the type. IS_ADDRESS_TAKEN
504 // is true if the address of this variable is taken (this implies
505 // that the address does not escape the function, as otherwise the
506 // variable would be on the heap). LOCATION is where the variable
507 // is defined. For each local variable the frontend will call
508 // init_statement to set the initial value.
510 local_variable(Bfunction
* function
, const std::string
& name
, Btype
* type
,
511 bool is_address_taken
, Location location
) = 0;
513 // Create a function parameter. This is an incoming parameter, not
514 // a result parameter (result parameters are treated as local
515 // variables). The arguments are as for local_variable.
517 parameter_variable(Bfunction
* function
, const std::string
& name
,
518 Btype
* type
, bool is_address_taken
,
519 Location location
) = 0;
521 // Create a temporary variable. A temporary variable has no name,
522 // just a type. We pass in FUNCTION and BLOCK in case they are
523 // needed. If INIT is not NULL, the variable should be initialized
524 // to that value. Otherwise the initial value is irrelevant--the
525 // backend does not have to explicitly initialize it to zero.
526 // ADDRESS_IS_TAKEN is true if the programs needs to take the
527 // address of this temporary variable. LOCATION is the location of
528 // the statement or expression which requires creating the temporary
529 // variable, and may not be very useful. This function should
530 // return a variable which can be referenced later and should set
531 // *PSTATEMENT to a statement which initializes the variable.
533 temporary_variable(Bfunction
*, Bblock
*, Btype
*, Bexpression
* init
,
534 bool address_is_taken
, Location location
,
535 Bstatement
** pstatement
) = 0;
537 // Create a GC root variable. TYPE is the __go_gc_root_list struct described
538 // in Gogo::register_gc_vars. INIT is the composite literal consisting of a
539 // pointer to the next GC root and the global variables registered.
541 gc_root_variable(Btype
* type
, Bexpression
* init
) = 0;
543 // Create a named immutable initialized data structure. This is
544 // used for type descriptors, map descriptors, and function
545 // descriptors. This returns a Bvariable because it corresponds to
546 // an initialized const variable in C.
548 // NAME is the name to use for the initialized global variable which
549 // this call will create.
551 // IS_HIDDEN will be true if the descriptor should only be visible
552 // within the current object.
554 // IS_COMMON is true if NAME may be defined by several packages, and
555 // the linker should merge all such definitions. If IS_COMMON is
556 // false, NAME should be defined in only one file. In general
557 // IS_COMMON will be true for the type descriptor of an unnamed type
558 // or a builtin type. IS_HIDDEN and IS_COMMON will never both be
561 // TYPE will be a struct type; the type of the returned expression
562 // must be a pointer to this struct type.
564 // We must create the named structure before we know its
565 // initializer, because the initializer may refer to its own
566 // address. After calling this the frontend will call
567 // immutable_struct_set_init.
569 immutable_struct(const std::string
& name
, bool is_hidden
, bool is_common
,
570 Btype
* type
, Location
) = 0;
572 // Set the initial value of a variable created by immutable_struct.
573 // The NAME, IS_HIDDEN, IS_COMMON, TYPE, and location parameters are
574 // the same ones passed to immutable_struct. INITIALIZER will be a
575 // composite literal of type TYPE. It will not contain any function
576 // calls or anything else that can not be put into a read-only data
577 // section. It may contain the address of variables created by
580 immutable_struct_set_init(Bvariable
*, const std::string
& name
,
581 bool is_hidden
, bool is_common
, Btype
* type
,
582 Location
, Bexpression
* initializer
) = 0;
584 // Create a reference to a named immutable initialized data
585 // structure defined in some other package. This will be a
586 // structure created by a call to immutable_struct with the same
587 // NAME and TYPE and with IS_COMMON passed as false. This
588 // corresponds to an extern const global variable in C.
590 immutable_struct_reference(const std::string
& name
, Btype
* type
,
595 // Create a new label. NAME will be empty if this is a label
596 // created by the frontend for a loop construct. The location is
597 // where the the label is defined.
599 label(Bfunction
*, const std::string
& name
, Location
) = 0;
601 // Create a statement which defines a label. This statement will be
602 // put into the codestream at the point where the label should be
605 label_definition_statement(Blabel
*) = 0;
607 // Create a goto statement to a label.
609 goto_statement(Blabel
*, Location
) = 0;
611 // Create an expression for the address of a label. This is used to
612 // get the return address of a deferred function which may call
615 label_address(Blabel
*, Location
) = 0;
619 // Create an error function. This is used for cases which should
620 // not occur in a correct program, in order to keep the compilation
621 // going without crashing.
623 error_function() = 0;
625 // Declare or define a function of FNTYPE.
626 // NAME is the Go name of the function. ASM_NAME, if not the empty string, is
627 // the name that should be used in the symbol table; this will be non-empty if
628 // a magic extern comment is used.
629 // IS_VISIBLE is true if this function should be visible outside of the
630 // current compilation unit. IS_DECLARATION is true if this is a function
631 // declaration rather than a definition; the function definition will be in
632 // another compilation unit.
633 // IS_INLINABLE is true if the function can be inlined.
634 // DISABLE_SPLIT_STACK is true if this function may not split the stack; this
635 // is used for the implementation of recover.
636 // IN_UNIQUE_SECTION is true if this function should be put into a unique
637 // location if possible; this is used for field tracking.
639 function(Btype
* fntype
, const std::string
& name
, const std::string
& asm_name
,
640 bool is_visible
, bool is_declaration
, bool is_inlinable
,
641 bool disable_split_stack
, bool in_unique_section
, Location
) = 0;
643 // Create a statement that runs all deferred calls for FUNCTION. This should
644 // be a statement that looks like this in C++:
646 // try { UNDEFER; } catch { CHECK_DEFER; goto finish; }
648 function_defer_statement(Bfunction
* function
, Bexpression
* undefer
,
649 Bexpression
* check_defer
, Location
) = 0;
651 // Record PARAM_VARS as the variables to use for the parameters of FUNCTION.
652 // This will only be called for a function definition. Returns true on
653 // success, false on failure.
655 function_set_parameters(Bfunction
* function
,
656 const std::vector
<Bvariable
*>& param_vars
) = 0;
658 // Set the function body for FUNCTION using the code in CODE_STMT. Returns
659 // true on success, false on failure.
661 function_set_body(Bfunction
* function
, Bstatement
* code_stmt
) = 0;
663 // Look up a named built-in function in the current backend implementation.
664 // Returns NULL if no built-in function by that name exists.
666 lookup_builtin(const std::string
&) = 0;
670 // Write the definitions for all TYPE_DECLS, CONSTANT_DECLS,
671 // FUNCTION_DECLS, and VARIABLE_DECLS declared globally.
673 write_global_definitions(const std::vector
<Btype
*>& type_decls
,
674 const std::vector
<Bexpression
*>& constant_decls
,
675 const std::vector
<Bfunction
*>& function_decls
,
676 const std::vector
<Bvariable
*>& variable_decls
) = 0;
679 // The backend interface has to define this function.
681 extern Backend
* go_get_backend();
683 // FIXME: Temporary helper functions while converting to new backend
686 extern Btype
* tree_to_type(tree
);
687 extern Bexpression
* tree_to_expr(tree
);
688 extern Bstatement
* tree_to_stat(tree
);
689 extern Bfunction
* tree_to_function(tree
);
690 extern Bblock
* tree_to_block(tree
);
691 extern tree
type_to_tree(Btype
*);
692 extern tree
expr_to_tree(Bexpression
*);
693 extern tree
stat_to_tree(Bstatement
*);
694 extern tree
block_to_tree(Bblock
*);
695 extern tree
var_to_tree(Bvariable
*);
696 extern tree
function_to_tree(Bfunction
*);
698 #endif // !defined(GO_BACKEND_H)