Non-SFI mode: Add Linux asynchronous signal support

src/include/nacl/nacl_signal.h

+/*
+ * Copyright (c) 2015 The Native Client Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+/*
+ * NaCl Async Signal Support
+ */
+
+#ifndef __NATIVE_CLIENT_SRC_SERVICE_RUNTIME_INCLUDE_SYS_NACL_SIGNAL_H__
+#define __NATIVE_CLIENT_SRC_SERVICE_RUNTIME_INCLUDE_SYS_NACL_SIGNAL_H__ 1
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+

[Mark Seaborn, 2015/07/16 23:21:16]

For documentation, could you add a text file in documentation/ (e.g.
nonsfi_mode_async_signals.txt) that gives just a quick overview of the new
feature and its status.  i.e.:

 * This is for Non-SFI mode only.

 * It treats async signals entirely separate from hardware exceptions (which are
synchronous).

 * There is no notion of signal masks or multiple signal types.  These must be
implemented in user mode, on top of the IRT interfaces provided.

 * There is no equivalent of sigaltstack() for async signals yet.

 * It adds the concepts of:
    * thread IDs (TIDs)
    * async signal safety

 * In contrast to POSIX's async signals, this is not intended to abort any
in-progress operations (such as syscalls, IRT calls or PPAPI calls).

 * We don't provide any libc wrapper functions for this interface in libnacl at
the moment.

 * Link to https://code.google.com/p/nativeclient/issues/detail?id=4065

We've tended to have a documentation deficit for NaCl, and I'm trying to avoid
continuing that for new features.

[Luis Héctor Chávez, 2015/07/20 18:13:46]

Done.

+struct NaClExceptionContext;
+typedef void (*nacl_signal_handler_t)(struct NaClExceptionContext *context);
+
+/*
+ * Sets the global signal handler.

[Mark Seaborn, 2015/07/16 23:21:16]

Generally, everywhere you say "signal" (in comments and code), can you say
"async signal" to clarify, please?

(Except where there's a signal handler that really does cover both sync and
async signals.)

[Luis Héctor Chávez, 2015/07/20 18:13:46]

Merged the docs with unrusted/irt/irt.h

+ *
+ * NaCl applications can register a single, global signal handler that will be

[Mark Seaborn, 2015/07/16 23:21:16]

These comments are duplicating those in irt.h.  How about merging the two sets
of comments, and just referring to irt.h here?

[Luis Héctor Chávez, 2015/07/20 18:13:46]

Done.

+ * invoked on the thread that receives the signal.  As opposed to POSIX, the
+ * signal mask is not changed upon entering/exiting the handler, so it is
+ * possible for the signal handler to be interrupted by itself, even on the same
+ * thread.  Furthermore, the signal handler will run in the same thread in which
+ * the signal is delivered in the same stack.  This function is not
+ * async-signal-safe, and should not be used within a signal handler.
+ * @return 0 on success. A positive errno value on error.
+ */
+int nacl_signal_set_handler(nacl_signal_handler_t handler);

[Mark Seaborn, 2015/07/16 23:21:16]

The way you've currently got these functions defined, they are IRT-internal
functions -- i.e. there's no definition for linking into a user nexe.

Which is fine, but it means this .h doesn't belong in src/include/nacl/. 
Putting it in src/nonsfi/linux/ next to the definitions of these functions would
be more appropriate.

For comparison: src/include/nacl/nacl_exception.h declares functions that have
definitions in src/untrusted/nacl/nacl_exception.c that can be linked into user
nexes.

[Luis Héctor Chávez, 2015/07/20 18:13:46]

Done.

+
+/*
+ * Asynchronously delivers a signal to a thread.
+ *
+ * This function delivers a signal to the thread identified by |tid| within the
+ * same thread group as the caller.  This function requires
+ * |nacl_signal_set_handler| to be called first, otherwise it will fail with
+ * ESRCH.  |tid| must be a valid thread identifier obtained when creating the
+ * thread, or 0 to refer to the main thread.  Using an invalid |tid| will result
+ * in undefined behavior.  This function is async-signal-safe, and can be used
+ * within a signal handler.
+ * @return 0 on success. A positive errno value on error.
+ */
+int nacl_signal_send_async_signal(uintptr_t tid);
+
+#if defined(__cplusplus)
+}
+#endif
+
+#endif /* __NATIVE_CLIENT_SRC_SERVICE_RUNTIME_INCLUDE_SYS_NACL_SIGNAL_H__ */