Non-SFI mode: Add Linux asynchronous signal support

documentation/nonsfi_mode_async_signals.txt

Index: documentation/nonsfi_mode_async_signals.txt
diff --git a/documentation/nonsfi_mode_async_signals.txt b/documentation/nonsfi_mode_async_signals.txt
new file mode 100644
index 0000000000000000000000000000000000000000..e4d7d062a067a41c615cd14813d444f03ee0b782
--- /dev/null
+++ b/documentation/nonsfi_mode_async_signals.txt
@@ -0,0 +1,52 @@
+Async signals support in Non-SFI mode
+=====================================
+
+Issue: https://code.google.com/p/nativeclient/issues/detail?id=4065
+
+This provides a way to asynchronously send a notification to another thread in

[Mark Seaborn, 2015/08/12 01:43:06]

How about "asynchronously interrupt another thread"?  That's stronger than "send
a notification".

[Luis Héctor Chávez, 2015/08/12 22:14:25]

Done.

+the same process, in a similar fashion to POSIX signals.  Signal support is
+limited to Non-SFI mode.
+

[Mark Seaborn, 2015/08/12 01:43:06]

Can you add "see nacl_irt_async_signal_handling in src/untrusted/irt/irt.h" to
make it clear what interface you're referring to?

[Luis Héctor Chávez, 2015/08/12 22:14:25]

Done.

+Async signals have several differences with POSIX signals:

[Mark Seaborn, 2015/08/12 01:43:06]

Nit: "differences from"?

[Luis Héctor Chávez, 2015/08/12 22:14:26]

Done.

+
+* Hardware/synchonous signals are separate and their behavior is not changed.

[Mark Seaborn, 2015/08/12 01:43:06]

"synchronous"

Maybe say "Synchronous signals (from hardware exceptions)" to make it clear that
they're the same thing.  Otherwise "Hardware/synchonous signals" could refer to
two types.

[Luis Héctor Chávez, 2015/08/12 22:14:25]

Done.

+  Furthermore, synchronous signals cannot be handled with this interface.
+* There is a single type of signal, and only a single, global async signal
+  handler is supported.  This means that there is no support for POSIX signal
+  numbers.
+* There is no way to block signals, not even when the signal handler is running.
+  This means that the signal handler must be reentrant.

[Mark Seaborn, 2015/08/12 01:43:06]

This sentence is not necessarily true.  User code might only send a signal once.
 Or it might use some mutual exclusion to ensure that the body of the handler
never gets interrupted.

[Luis Héctor Chávez, 2015/08/12 22:14:25]

Removed

+* There is no equivalent to sigaltstack(), so the signal handler always runs on
+  the same stack as the thread.
+* We don't provide libc wrapper functions for this interface in libnacl at the
+  moment.  If full POSIX support is needed, it can be implemented in userspace,

[Mark Seaborn, 2015/08/12 01:43:06]

Nit: "user space" -> "user code"

[Luis Héctor Chávez, 2015/08/12 22:14:26]

Done.

+  on top of the IRT interfaces provided.
+* NaCl signals are not intended to abort any in-process operations (such as
+  syscalls, IRT calls or PPAPI calls).  Some syscalls may be interrupted and may
+  return EINTR, but users must not assume this will always be true.

[Mark Seaborn, 2015/08/12 01:43:06]

No, the intent is you *shouldn't* get EINTR.

Are there any cases where the current implementation gives EINTR?

See my other comment in tests/nonsfi/user_async_signal_test.cc...

[Luis Héctor Chávez, 2015/08/12 22:14:26]

Yes: futex_wait (with non-null timeout) and nanosleep (the two things I use in
the test).

I reworded this to mention that the norm is that you don't normally get EINTR
except in the two cases above.

+
+Similar to POSIX signals, NaCl signals are delivered the next time the thread is
+scheduled to run but before giving the process control of execution.  This also
+means that if several signals are sent to a thread before it is scheduled to
+run, a single async signal will be delivered, and the signal handler will be run
+just once.  That also means that the signal handler can run at any point during
+the program execution, so the signal handler must be written with care to avoid
+doing unsafe operations, such as acquiring mutexes that may be held by the
+interrupted thread.  Invoking any unsafe operation from within a signal handler
+is undefined.  NaCl only guarantees that the following functions are

[Mark Seaborn, 2015/08/12 01:43:06]

"functions" -> "IRT interfaces"

[Luis Héctor Chávez, 2015/08/12 22:14:26]

Done.

+async-signal-safe and can be called from within the signal handler:
+
+* tls_get

[Mark Seaborn, 2015/08/12 01:43:06]

Can you add "()" to these?

[Luis Héctor Chávez, 2015/08/12 22:14:26]

Done.

+* futex_wait_abs
+* futex_wake
+* send_async_signal
+
+In order to deliver signals to the correct thread, a new version of the
+nacl_irt_thread IRT functions has been introduced which will assign an opaque
+thread identifier to each new thread and will populate it into the |child_tid|
+parameter.  Since the main thread is not created using nacl_irt_thread, the

[Mark Seaborn, 2015/08/12 01:43:06]

Nit: "main thread" -> "initial thread"

[Luis Héctor Chávez, 2015/08/12 22:14:26]

Done.

+constant NACL_IRT_MAIN_THREAD_TID can be used to refer to it.  This thread
+identifier can be used as a parameter to send_async_signal.  Providing a thread

[Mark Seaborn, 2015/08/12 01:43:06]

Nit: Add "()" to "send_async_signal()"

[Luis Héctor Chávez, 2015/08/12 22:14:26]

Done.

+identifier that is not NACL_IRT_MAIN_THREAD_TID, was not obtained from
+thread_create, or belonged to a thread that has already terminated will produce
+undefined behavior.