Write a document for others wanting to implement a rustc codegen backend

[bjorn3]

It should at least include assumptions made by rustc and libstd, like:

• fn((), u8) and fn(u8) are abi compatible (assumes by ClosureFnPointer, found in https://github.com/bjorn3/rustc_codegen_cranelift/issues/413)
• BinOp::Offset and the offset and arith_offset use pointer arithmetic (found in https://github.com/bjorn3/rustc_codegen_cranelift/issues/341)
• Don't ever stub out unimplemented stuff by using a dummy value, instead use a trap. Even something simple as making checked binops never overflow causes hard to debug breakage at many places, especially 128bit int emulation and bigint arithmetic, as those need the overflow flag as carry/borrow. (eg https://github.com/bjorn3/rustc_codegen_cranelift/issues/381#issuecomment-475882825)
• Dont implement stuff the way you think it should, without a test using it. See for example bjorn3@0d16dcf for the fix of a problem that could probably have been prevented that way.
• Alignment of stuff is important. libcore contains alignment debug asserts and some os functions will return an error on wrong alignment.
• DST's are hard to get right. Write many tests for then!
• Add many asserts, for example check that types are compatible when writing a value to a place.
• SysV abi requires ByRef params to be passed at the right memory offset, not passing a pointer to the value in register.

https://github.com/dropbox/rust-brotli-decompressor is a good example of a simple project which contains a binary.

[bjorn3]

This is not something actionable on cg_clif's side. Tracking this in rust-lang/rustc-dev-guide#442 instead would be better I think.