WIP: doc: definitions for precisely defining API behavior

This is an evolving document used to come to consensus on the set of
defined terms necessary to precisely document the expected behavior of
API calls in various contexts.

It's in Markdown rather than reStructured Text because that's most
convenient for the editor.

This commit archives the original proposal in issue zephyrproject-rtos#18970.

Signed-off-by: Peter Bigot <[email protected]>

doc/api18970.md

@@ -0,0 +1,33 @@
+# Draft material to review in support of [#18970][]
+
+[//]: # (cmark-gfm doc/api18970.md > /tmp/api18970.html)
+
+[#18970]: https://github.com/zephyrproject-rtos/zephyr/issues/18970
+
+## Definitions
+
+### thread-safe
+
+A function is thread-safe if its behavior is correct when invoked from
+multiple threads at the same time.
+
+### reentrant
+
+A function is reentrant if its behavior is correct when it is invoked by
+(indirect) recursion from the same thread.
+
+### interrupt-safe
+
+A function is interrupt-safe if its behavior is not affected by
+concurrent access from interrupts.
+
+### block
+
+A call blocks if it can suspend the invoking thread while it waits for
+something to happen.
+
+### atomic
+
+An operation is atomic if the steps it makes internally cannot be
+affected by nor visible to interleaving executions, such as from
+interrupts or thread pre-emption.