I want to jump in on this too. For our porting of OpenVMS compilers
(BASIC, COBOL, Pascal, Fortran, C, VAX Macro assembler, BLISS) to
using LLVM for our x86 port, we want to provide some scheme for our
traditional OpenVMS "listing files" which an optionally include generated
machine code, cross reference information, command line summary, frontend
generated messages interspersed with the source listing, display of header
file contents, expansion of macros, optimization information, inlining
heuristic results, etc.
My plan was to come back here with an RFC later this year after we have our
early cross-compilers in place for the OS team to do their porting effort.
I have some resources that could help with such an effort.
Besides using these listing for debugging efforts, we also use them for
system archive purposes. Over the last 30+ years doing this, having a full
machine code listing from an older release is invaluable for debugging
system crashes, etc. With such a listing file, you can see EXACTLY the
source that was compiled and the exact generated code all in a single file.
Our generated code contains symbolized variable and routine names along with
line number information. And by having a qualifier summary at the tail end
of the listing file, you can always tell exactly which command line options
that were specified by the make files/command files/etc. that built the
software.
What I envision is some listing manager that is feed from various places in
the compiler. The frontend (not just clang but any frontend) could provide
file information, source line information, error message information, command
line processing, etc. The backend can provide optimization data, inline
decisions, generated code, diagnostics for uninitialized variables, unreachable
code, etc. Then the listing manager would collect, sort, etc. and generate the
single listing file. You might be able to cobble something together inside a
driver if you pick apart the output from various tools, but it wouldn't have the
look and feel from a single generated file.
As for interspersed machine code, that is often only useful with O0 or O1 compilations.
Once you get to O2 and higher, it is often just best to have the machine code
following the source code with line numbers (either as ".loc" directives or just with
"end of line" comments). In many cases, we use the comment area to denote "interesting"
instructions in the prologue/epilogue that correspond to unwind information.
The traditional VMS listings are 132 columns wide with "^L" form feeds between
sections since they were originally designed to be printed on greenbar printer
paper (Google it if don't know what I'm talking about 
)
Here's a little abridged example for the traditional "hello world" C program.
1 #include <stdio.h>
X 1612 #if 0
X 1613 An X is placed at the left to show this is eXcluded
X 1614 #endif
1615 #define m(p) int p;
1 1616 main () {
1 1617 m(ii);
E int ii ;
1 1618 printf("hello world\n");
1 1619 }
^L
Machine Code Listing 3-FEB-2017 14:01:37 VSI C V7.4-001-50L7J Page 2
3-FEB-2017 14:00:56 WORK20:[JREAGAN]HW.C;17
.psect $CODE$, CON, LCL, SHR, EXE, NOWRT, NOVEC, NOSHORT
.proc __MAIN
.align 32
.global __MAIN
.personality DECC$$SHELL_HANDLER
.handlerdata -8
__MAIN: // 001616
{ .mii
002C009229C0 0000 alloc r39 = rspfs, 6, 3, 8, 0
0120000A0380 0001 mov r14 = 80
010800100A00 0002 mov r40 = gp ;; // r40 = r1
}
{ .mib
010028E183C0 0010 sub r15 = sp, r14 // r15 = r12, r14
000188000980 0011 mov r38 = rp // r38 = br0
004000000000 0012 nop.b 0 ;;
}
.....