Expand discussion of FFI safety

This is a port of rust-lang/rust#31227.

It is documented nowhere that primitives and thin pointers are FFI-safe

In particular, only thin pointers are FFI safe, and not fat pointers. This is somewhat confusing.

Also, it isn't documented (AFAICT) that one can pass a reference or mutable reference where an extern "C" function takes a const pointer or non-const pointer.

There's a lint for this, at least when declaring extern functions

I checked that and it works, i was wondering is there anything for the reverse - for e.g.: this.

The other function find does not give any warning. Though I understand that all it says is it follow C calling convention and no name-mangling none of which might warrant the parameter type warning, it is usually intended to be called form another language (with C compatibility) so should generate a warning in this case too ? Passing a callback from C for instance will be Undefined Behavior in this case. I was also stung by this:

#[no_mangle]
pub unsafe extern "C" fn(cb: extern "C" fn([u8; 32])) { // WRONG - should be fn(*const [u8; 32])
    let arr = [8u8; 32];
    cb(arr); // WRONG - should be &arr
}

Of-course looking back it was a stupid mistake - but i had subconciously assumed array would decay into a ptr like in C when callback was invoked. All my tests passed as they were written in rust. Only when interfacing with C and running into occassional seg-faults that i realised the mistake. If there was a warning or some language feature to mark that this function is not only for C ABI compatibility but also strictly for a call from C (like what extern "C" { } block does) it would be helpful.

Same with repr(C) - there is no warning for completely non-C struct having this attribute - i understand the reasoning from the docs for this but again if there is some lint/attribute to mark strict C only conformance then that would be great - as you know it's pita to debug C errors otherwise :(

No file, test, or entry point is named; start by locating the Nomicon’s existing FFI-safety documentation. Done means documenting primitive and pointer safety, reference-to-pointer usage, callback and array pitfalls, and the limits of extern "C" and repr(C), with the scope agreed by maintainers.