fix extern "C" use throughout Zephyr

[pabigot]

Inspired by #17993, the latest in an unending series of patches to fix broken C++ support, I did:

lilith[632]$ git grep -A12 'extern "C"' | grep '#include' | sed -e 's@\.h-.*$@.h@' | uniq | wc
    303     303   15609

That's at least 303 include files in the Zephyr tree that probably get this wrong, i.e. have an #include within the first ten lines after an extern "C" block. Excluding ext/hal (found in atmel, nordic, nxp, openisa, ti) reduces it to a mere 88.

As long as Zephyr claims C++ compatibility, even if only for application code, this should be cleaned up at least in non-HAL code before 2.0, and there should be some attempt toward adding a check for new occurrences to the commit checking code.

Rationale

Declarations that use C linkage should be placed within extern "C" so the language linkage is correct when the header is included by a C++ compiler.

Similarly #include directives should be outside the extern "C" to ensure the language-specific default linkage is applied to any declarations provided by the included header.

See: https://en.cppreference.com/w/cpp/language/language_linkage

Note Some "authorities" specifically recommend putting include files within extern "C". Ignore them. That solution is fragile because the supplier of the header may expect that when included from C++ the default linkage is correct for C++. This expectation is made by some Zephyr headers, which will produce compiler errors if included by a C++ compiler within an extern "C" block. Place the burden of assigning declaration linkage on the header that provides the declaration, rather than specifying it in the including header/code.

[jukkar]

I created a PR #18023 that changes the include file location in networking related include files.

[pfalcon]

Inspired by #17993,

I fail to see to see any inspiration there, it just says it moves headers around without explaining why. Some time later, another guy will submit patch which moves them back. Of course, without any explanation either.

[pabigot]

@pfalcon It would be fair to request that the commits and/or PR explain why it's done that way. Not everybody will recognize the problem. Or just link back here to the rationale in the description of this issue.

[pfalcon]

Similarly #include directives should be outside the extern "C" to ensure the language-specific default linkage is applied to any declarations provided by the included header.

Makes sense, hopefully authors of specific patches might mention that in PR commit messages, because the above fact might not be immediately obvious, and I guess effect of not following that rule might differ from header to header (so, some people might place one header inside extern "C", see no ill effects, and decide that moving headers around is useless sinecure; or worse, someone might decide that instead of putting extern "C" inside a header, it's "better" to put a header include inside extern "C" block).

[pabigot]

@pfalcon Good point; I've updated the explanation and moved it to the description of this issue. It should probably go into the developer area of the documentation. I'll try to remember to do that if/when I get back to doing C++ stuff in Zephyr.