+/**
+ * Mark a function that executes in coroutine context
+ *
+ *
+ * Functions that execute in coroutine context cannot be called
+ * directly from normal functions. Use @coroutine_fn to mark such
+ * functions. For example:
+ *
+ * static void coroutine_fn foo(void) {
+ * ....
+ * }
+ *
+ * In the future it would be nice to have the compiler or a static
+ * checker catch misuse of such functions. This annotation might make
+ * it possible and in the meantime it serves as documentation.
+ */
+
Is it intentional that "#define coroutine_fn" is not here?
Yes: I moved it to qemu/osdep.h in PATCH 2, along with its doc comment.
To avoid compromising coroutine.h as overview documentation, I added
rephrased documentation there.