py/mphal: Declare the shared wake descriptor that extmod calls.

extmod/modselect.c reaches mp_hal_wake_event_fd() and
mp_hal_wake_event_drain() when it has no per-thread wake object to inject,
but both were declared only in ports/unix/mphalport.h. Portable code was
calling a port-private entry point that no contract described, and the two
sides did not even agree on when it existed: modselect tested the
descriptor capability while the port tested the wake-object one.

They are now declared in py/mphal.h behind MICROPY_HAL_HAS_WAKE_EVENT_FD,
which a port sets when its shared wake primitive can offer a descriptor.
The capability is independent of the wake-object one rather than its
negation, because a port may have neither: a wake object with no
descriptor is what an event register or a task notification looks like.
That combination now selects the third branch and falls back to the
period-capped sweep, where before it failed to compile.

Signed-off-by: Andrew Leech <andrew@alelec.net>

Author: andrewleech

extmod/modselect.c

@@ -435,8 +435,13 @@ static struct pollfd *poll_set_add_fd(poll_set_t *poll_set, int fd) {
 static bool poll_set_signal_wake_is_reliable(void) {
     #if MICROPY_HAL_WAKE_OBJ_HAS_POSIX_FD
     return true;
-    #else
+    #elif MICROPY_HAL_WAKE_EVENT_HAS_POSIX_FD
     return mp_sched_thread_can_run_callbacks() && mp_hal_wake_event_fd() >= 0;
+    #else
+    // Neither a per-thread object nor a shared descriptor to put in the set, so nothing
+    // here can end a deadline block early and the period-capped sweep is the only correct
+    // cadence for a signal source.
+    return false;
     #endif
 }
 #endif
@@ -906,13 +911,17 @@ static mp_uint_t poll_set_poll_until_ready_or_timeout(poll_set_t *poll_set, size
         // way, as neither relies on this reserved slot for its own readiness.
         #if MICROPY_HAL_WAKE_OBJ_HAS_POSIX_FD
         poll_set->pollfds[0].fd = mp_hal_wake_obj_posix_fd(wake_obj);
-        #else
+        #elif MICROPY_HAL_WAKE_EVENT_HAS_POSIX_FD
         // No per-thread wake object on this port or build: the shared wake event is the
         // only mechanism left, safe to inject for the same entitlement
         // poll_set_signal_wake_is_reliable() checks above (at most one thread ever holds
         // it), and -1 for every other thread so its poll() always falls back to the
         // periodic sweep below.
         poll_set->pollfds[0].fd = mp_sched_thread_can_run_callbacks() ? mp_hal_wake_event_fd() : -1;
+        #else
+        // No wake primitive this poll set can be given, so the slot stays empty and every
+        // signal source falls back to the periodic sweep below.
+        poll_set->pollfds[0].fd = -1;
         #endif
         poll_set->pollfds[0].events = POLLIN;
         poll_set->pollfds[0].revents = 0;
@@ -995,7 +1004,7 @@ static mp_uint_t poll_set_poll_until_ready_or_timeout(poll_set_t *poll_set, size
         if (poll_set->pollfds[0].revents != 0) {
             #if MICROPY_HAL_WAKE_OBJ_HAS_POSIX_FD
             mp_hal_wake_obj_drain(wake_obj);
-            #else
+            #elif MICROPY_HAL_WAKE_EVENT_HAS_POSIX_FD
             mp_hal_wake_event_drain();
             #endif
         }

ports/unix/mpconfigport.h

@@ -190,6 +190,11 @@ typedef long mp_off_t;
 #define MICROPY_HAL_HAS_WAKE_OBJ (MICROPY_PY_THREAD)
 #define MICROPY_HAL_WAKE_OBJ_HAS_POSIX_FD (MICROPY_PY_THREAD)
 
+// The shared wake event is opened, and so has a descriptor to offer, only on a build with
+// no per-thread objects; with them every waiter has its own and the shared one has no
+// reader (see mp_hal_wake_event_init()).
+#define MICROPY_HAL_WAKE_EVENT_HAS_POSIX_FD (!MICROPY_HAL_HAS_WAKE_OBJ)
+
 // Bare-metal ports don't have stderr. Printing debug to stderr may give tests
 // which check stdout a chance to pass, etc.
 extern const struct _mp_print_t mp_stderr_print;

ports/unix/mphalport.h

@@ -145,21 +145,8 @@ void mp_hal_wake_event_wait_ms(mp_uint_t timeout_ms);
 // timeout.  Returns 0 on timeout, or -1 with errno EINTR if cut short.
 int mp_hal_wake_event_wait_tv(struct timeval *tv);
 
-// The descriptor the wake event can be waited on, for a caller that runs its own
-// poll set and wants the event in it alongside its own descriptors, or -1 when
-// there is none to give.  Defined only where the wake event is backed by a
-// descriptor, so on this port and not on Windows.
-//
-// Drain it after, and only after, it has polled readable.  It is
-// level-triggered, so it stays readable until drained, and draining before a
-// wait instead discards a raise and leaves that wait with nothing to end it.
-//
-// Declared only where per-thread wake objects are unavailable: with them, a poll set
-// injects this thread's own object instead and these have no caller.
-#if !MICROPY_HAL_HAS_WAKE_OBJ
-int mp_hal_wake_event_fd(void);
-void mp_hal_wake_event_drain(void);
-#endif
+// mp_hal_wake_event_fd() and mp_hal_wake_event_drain() are declared in py/mphal.h, behind
+// MICROPY_HAL_WAKE_EVENT_HAS_POSIX_FD, because extmod/modselect.c calls them.
 
 #if MICROPY_PY_BLUETOOTH
 enum {

ports/unix/unix_mphal.c

@@ -52,7 +52,10 @@ typedef uint8_t wake_event_token_t;
 // wake_event_fd drains it, writing wake_event_wr_fd raises it; on Linux both
 // are the same descriptor, and both are negative when not initialised.
 // Only exists where something waits on it; with per-thread wake objects every waiter has
-// its own and this pair has no reader (see mp_hal_wake_event_init()).
+// its own and this pair has no reader (see mp_hal_wake_event_init()). Keyed on the wake
+// mechanism, not on MICROPY_HAL_WAKE_EVENT_HAS_POSIX_FD: that macro says whether this port hands
+// the descriptor out to extmod, which is a different question from whether the event
+// exists at all.
 #if !MICROPY_HAL_HAS_WAKE_OBJ
 static int wake_event_fd = -1;
 static int wake_event_wr_fd = -1;
@@ -435,7 +438,7 @@ int mp_hal_wake_event_wait_tv(struct timeval *tv) {
     return select(0, NULL, NULL, NULL, tv);
 }
 
-#if !MICROPY_HAL_HAS_WAKE_OBJ
+#if MICROPY_HAL_WAKE_EVENT_HAS_POSIX_FD
 // The shared event's descriptor, for a poll set to sleep on alongside its own entries.
 // Only where per-thread wake objects are unavailable: with them, extmod/modselect.c
 // injects this thread's own object instead and these have no caller.

py/mphal.h

@@ -165,8 +165,12 @@ void mp_hal_wake_obj_signal_all(void);
 // How a waiter composes its own object with everything else it is waiting on has no
 // port-neutral spelling, so it is deliberately not part of the contract above. Each port
 // that adopts wake objects exports whatever composition primitive it has behind its own
-// capability macro, and core code that uses one is guarded to match. The descriptor below
-// is the only such primitive today.
+// capability macro, and core code that uses one is guarded to match. A POSIX descriptor is
+// the only such primitive today, for either flavour of wake primitive: the one below for a
+// per-thread object, and MICROPY_HAL_WAKE_EVENT_HAS_POSIX_FD further down for a port whose
+// wake primitive is process-wide. Both are consumed only inside
+// MICROPY_PY_SELECT_POSIX_OPTIMISATIONS, since a struct pollfd is the only thing that
+// wants them.
 #ifndef MICROPY_HAL_WAKE_OBJ_HAS_POSIX_FD
 #define MICROPY_HAL_WAKE_OBJ_HAS_POSIX_FD (0)
 #endif
@@ -183,6 +187,28 @@ void mp_hal_wake_obj_signal_all(void);
 int mp_hal_wake_obj_posix_fd(mp_hal_wake_obj_t *w);
 #endif
 
+// A port with one process-wide wake primitive rather than per-thread objects may still be
+// able to hand its descriptor to a caller running its own poll()/select() set. That
+// primitive has exactly one legitimate consumer, whichever waiter drains it first, so a
+// caller must satisfy itself that this thread is the one entitled to it
+// (mp_sched_thread_can_run_callbacks()) before waiting on the descriptor.
+//
+// Independent of the wake-object capability above rather than its negation: a port may
+// have neither, and core code must then fall back to a bounded re-check instead of
+// blocking on something nothing can end.
+#ifndef MICROPY_HAL_WAKE_EVENT_HAS_POSIX_FD
+#define MICROPY_HAL_WAKE_EVENT_HAS_POSIX_FD (0)
+#endif
+
+#if MICROPY_HAL_WAKE_EVENT_HAS_POSIX_FD
+// The shared wake primitive's descriptor, or negative when there is none to give (the HAL
+// has been torn down). Drain it after, and only after, it has polled readable: it is
+// level-triggered, so draining ahead of a wait discards the raise and leaves that wait
+// with nothing to end it.
+int mp_hal_wake_event_fd(void);
+void mp_hal_wake_event_drain(void);
+#endif
+
 #if MICROPY_PY_SELECT_EVENT_SOURCE
 
 // Monotonic count of mp_event_signal() calls. A waiter compares a snapshot of this