Keccak and KangarooTwelve: C sources and modules
================================================

Which file includes which, and what each Python extension module is
compiled from (see setup.py and compiler_opt.py).
Lines from a module name go to the file it is built from;
the other arrows are #include.

  _keccak     _keccak_avx2_bmi2           _k12        _k12_avx2_bmi2
     │                   ▼                   │                   ▼
     │        ┌────────────────────┐         │        ┌────────────────────┐
     │        │ keccak_avx2_bmi2.c │         │        │  k12_avx2_bmi2.c   │
     │        │  KECCAK_MODULE =   │         │        │    K12_MODULE =    │
     │        │  keccak_avx2_bmi2  │         │        │   k12_avx2_bmi2    │
     │        └──────────┬─────────┘         │        │      K12_AVX2      │
     │                   │                   │        └──────────┬─────────┘
     │                   │                   │                   │
     ▼                   ▼                   ▼                   ▼
  ┌────────────────────────────┐          ┌────────────────────────────┐
  │          keccak.c          │          │           k12.c            │
  │                            │ #include │                            │
  │     Keccak sponge and      │◀─────────┤       KangarooTwelve       │
  │   scalar Keccak-p[1600]    │          │   (keccak.c is private)    │
  └────────────────────────────┘          └──────────────┬─────────────┘
                                                         │ #ifdef K12_AVX2
                                                         ▼
                                          ┌────────────────────────────┐
                                          │      keccak_x4_avx2.c      │
                                          │                            │
                                          │  4 Keccak-p[1600] states   │
                                          │     at once, with AVX2     │
                                          └────────────────────────────┘


  Module              Built from               Exports     Compiler flags         4-way AVX2
  ------------------  -----------------------  ----------  ---------------------  ----------
  _keccak             keccak.c                 keccak_*    (none)                 no
  _keccak_avx2_bmi2   keccak_avx2_bmi2.c       keccak_*    -mavx2 -mbmi -mbmi2    no
                      -> keccak.c
  _k12                k12.c                    k12_*       (none)                 no
                      -> keccak.c
  _k12_avx2_bmi2      k12_avx2_bmi2.c          k12_*       -mavx2 -mbmi -mbmi2    yes
                      -> k12.c -> keccak.c
                               + keccak_x4_avx2.c

Notes:
  - keccak.c names its module after KECCAK_MODULE (default: keccak), and
    k12.c after K12_MODULE (default: k12); so each module gets exactly
    one FAKE_INIT. Inside k12.c, keccak.c is always private (KECCAK_EMBEDDED).
  - keccak_x4_avx2.c is included after keccak.c, because it uses the round
    constants defined there.
  - The *_avx2_bmi2 modules are only compiled if the compiler supports AVX2,
    BMI1 and BMI2, and only loaded if the CPU supports all three
    (lib/Crypto/Hash/keccak.py and lib/Crypto/Hash/KangarooTwelve.py).
