tools/testing/selftests/arm64/signal/README

   1 KSelfTest arm64/signal/
   2 =======================
   3
   4 Signals Tests
   5 +++++++++++++
   6
   7 - Tests are built around a common main compilation unit: such shared main
   8   enforces a standard sequence of operations needed to perform a single
   9   signal-test (setup/trigger/run/result/cleanup)
  10
  11 - The above mentioned ops are configurable on a test-by-test basis: each test
  12   is described (and configured) using the descriptor signals.h::struct tdescr
  13
  14 - Each signal testcase is compiled into its own executable: a separate
  15   executable is used for each test since many tests complete successfully
  16   by receiving some kind of fatal signal from the Kernel, so it's safer
  17   to run each test unit in its own standalone process, so as to start each
  18   test from a clean slate.
  19
  20 - New tests can be simply defined in testcases/ dir providing a proper struct
  21   tdescr overriding all the defaults we wish to change (as of now providing a
  22   custom run method is mandatory though)
  23
  24 - Signals' test-cases hereafter defined belong currently to two
  25   principal families:
  26
  27   - 'mangle_' tests: a real signal (SIGUSR1) is raised and used as a trigger
  28     and then the test case code modifies the signal frame from inside the
  29     signal handler itself.
  30
  31   - 'fake_sigreturn_' tests: a brand new custom artificial sigframe structure
  32     is placed on the stack and a sigreturn syscall is called to simulate a
  33     real signal return. This kind of tests does not use a trigger usually and
  34     they are just fired using some simple included assembly trampoline code.
  35
  36  - Most of these tests are successfully passing if the process gets killed by
  37    some fatal signal: usually SIGSEGV or SIGBUS. Since while writing this
  38    kind of tests it is extremely easy in fact to end-up injecting other
  39    unrelated SEGV bugs in the testcases, it becomes extremely tricky to
  40    be really sure that the tests are really addressing what they are meant
  41    to address and they are not instead falling apart due to unplanned bugs
  42    in the test code.
  43    In order to alleviate the misery of the life of such test-developer, a few
  44    helpers are provided:
  45
  46    - a couple of ASSERT_BAD/GOOD_CONTEXT() macros to easily parse a ucontext_t
  47      and verify if it is indeed GOOD or BAD (depending on what we were
  48      expecting), using the same logic/perspective as in the arm64 Kernel signals
  49      routines.
  50
  51    - a sanity mechanism to be used in 'fake_sigreturn_'-alike tests: enabled by
  52      default it takes care to verify that the test-execution had at least
  53      successfully progressed up to the stage of triggering the fake sigreturn
  54      call.
  55
  56   In both cases test results are expected in terms of:
  57    - some fatal signal sent by the Kernel to the test process
  58   or
  59   - analyzing some final regs state