# codebuffer.api
#
# (Overview comments are at bottom of file.)
# Compiled by:
# src/lib/compiler/back/low/lib/lowhalf.libstipulate
package lbl = codelabel; # codelabel is from src/lib/compiler/back/low/code/codelabel.pkgherein
# This api is "implemented" (mostly just echoed) in:
#
# src/lib/compiler/back/low/code/codebuffer-g.pkg #
api Codebuffer {
#
package pop: Pseudo_Ops; # Pseudo_Ops is from src/lib/compiler/back/low/mcg/pseudo-op.api Codebuffer (X,Y,Z,W)
=
{ start_new_cccomponent: Int -> Void, # Start new compilation unit consisting of one connected component of the callgraph.
get_completed_cccomponent: Y -> W, # End of callgraph connected component: finalize and return it.
put_op: X -> Void, # Accept assembly or machine instruction.
put_pseudo_op: pop::Pseudo_Op -> Void, # Accept a pseudo op.
put_public_label: lbl::Codelabel -> Void, # Accept an externally visible label marking current spot in codestream.
put_private_label: lbl::Codelabel -> Void, # Accept an externally invisible label marking current spot in codestream.
put_comment: String -> Void, # Accept a comment.
put_bblock_note: note::Note -> Void, # Add note to current basic block.
get_notes: Void -> Ref( note::Notes ), # Get annotations.
put_fn_liveout_info: Z -> Void # Mark the end of a procedure.
};
# Note:
# o Each compilation unit should be wrapped between start_new_cccomponent/get_completed_cccomponent.
#
# o The method 'put_bblock_note' adds an annotation to the current basic block,
# not to the current instruction.
#
# o The method put_comment adds a comment to the current basic block.
# Usually put_comment(msg) is the same as
# put_bblock_note(BasicAnnotations::COMMENT msg).
};
end;
# The compiler backend lowhalf components convert code
# from nextcode to treecode to machcode via 'streams'
# (more like buffers) of treecode expressions and machcode
# (abstract machine code) instructions.
#
# The main driver of this process is
#
# src/lib/compiler/back/low/main/main/translate-nextcode-to-treecode-g.pkg#
# Here we define the abstract API shared by all such streams;
# this API gets specialized to the various concrete streams.
#
# Codebuffer gets specialized for Treecode_Form in: # Treecode_Form is from src/lib/compiler/back/low/treecode/treecode-form.api#
# src/lib/compiler/back/low/treecode/treecode-codebuffer.api# src/lib/compiler/back/low/treecode/treecode-codebuffer-g.pkg#
# Codebuffer is also referenced in the architecture-agnostic files:
#
# src/lib/compiler/back/low/mcg/make-machcode-codebuffer-g.pkg# src/lib/compiler/back/low/emit/machcode-codebuffer.api# src/lib/compiler/back/low/treecode/instruction-sequence-generator.api# src/lib/compiler/back/low/treecode/instruction-sequence-generator-g.pkg#
# and the the architecture-specific files:
#
# src/lib/compiler/back/low/intel32/emit/translate-machcode-to-asmcode-intel32-g.codemade.pkg# src/lib/compiler/back/low/pwrpc32/emit/translate-machcode-to-asmcode-pwrpc32-g.codemade.pkg# src/lib/compiler/back/low/sparc32/emit/translate-machcode-to-asmcode-sparc32-g.codemade.pkg#
# src/lib/compiler/back/low/pwrpc32/emit/translate-machcode-to-execode-pwrpc32-g.codemade.pkg# src/lib/compiler/back/low/sparc32/emit/translate-machcode-to-execode-sparc32-g.codemade.pkg#
# The usage protocol here is basically:
#
# stream = mkg::make_machcode_codebuffer (); # mkg is defined as make_machcode_codebuffer_g(...) in src/lib/compiler/back/low/main/main/backend-lowhalf-g.pkg# # make_machcode_codebuffer_g is from src/lib/compiler/back/low/mcg/make-machcode-codebuffer-g.pkg# loop
# stream.start_new_cccomponent size; # 'size' is ignored by src/lib/compiler/back/low/mcg/make-machcode-codebuffer-g.pkg# # 'size' is used to size the codebuffer on pwrpc32 and sparc32: the relevant start_new_cccomponent versions are defined in
# # src/lib/compiler/back/low/sparc32/emit/translate-machcode-to-execode-sparc32-g.codemade.pkg# # src/lib/compiler/back/low/pwrpc32/emit/translate-machcode-to-execode-pwrpc32-g.codemade.pkg# # and called in
# # src/lib/compiler/back/low/jmp/squash-jumps-and-write-code-to-code-segment-buffer-pwrpc32-g.pkg# # src/lib/compiler/back/low/jmp/squash-jumps-and-write-code-to-code-segment-buffer-sparc32-g.pkg# any_number_of_any_of {
# stream.put_op op;
# | stream.put_public_label label;
# | stream.put_private_label label;
# | ...
# };
#
# resultgraph = stream.get_completed_cccomponent foo;
#
# do_whatever resultgraph;
# endloop;
####################################################################################################################
# NB: This whole codebuffer.api thing looks like pure empty generalization to me.
# The various implementations generated can never be used interchangably, so
# the superficial uniformity buys us not a damned thing, and many of the
# "implementations" do not in fact implement the interface -- they tie various
# calls to functions which crash out -- so the codebuffer.api pretense is in
# fact reducing typesafety and converting compiletime checks into runtime checks,
# which is exactly the reverse of what we should be doing:
#
# codebuffer.api IS A DEAD LOSS AND SHOULD BE KILLED DEAD DEAD DEAD. XXX SUCKO FIXME -- 2011-08-15 CrT
#
# We should just implement plain-Jane normal interfaces each place api Codebuffer
# is nominally specializaed.
####################################################################################################################