clearly document internal kernel interfaces

[nashif]

Reported by Andrew Boie:

As a developer porting Zephyr to a new architecture, I would like the internal APIs that the kernel expects architectures to implement to be clearly documented in header files rather than it being a trial-and-error exercise.

Examples would be some but not all members of struct tcs. Certain functions like _IntLibInit, etc. _IS_IN_ISR. There's also an assortment of headers in the codebase which #ifdef on all arches, variously failing silently or loudly if the new architecture hasn't added there yet. These should be consolidated.

The required members of tcs and others should be defined in a new struct that gets embedded within the respective arch-specific implementations.

(Imported from Jira ZEP-618)

[nashif]

by Andrew Boie:

Per Ben this should wait until the unified kernel goes out.

[nashif]

by Sharron LIU:

As a tester, would need distinguish internal API/data structure/fields, too! Internal stuff should not be test focus, as test cases using internal stuff are less common across arch/platform.

[nashif]

by Sharron LIU:

To my understanding today, in kenel header file, naming space "_*" is reserved for internal usage.

But I think, unless every internal API/fields/structure has been documented (that is, an expected list given), otherwise it would not be possible from QA side to verify all internal stuff are aligned to "_*" naming space. So I would mark this "NotTest".

[nashif]

by Mark Linkmeyer:

Fixing incorrect priority

[nashif]

by David Kinder:

The title and references to nano-kernel in this Jira should be changed to be about the kernel in general, i.e., Update header files to clearly document internal APIs that the kernel expects architectures to implement ...