Replace BTech Mersenne Twister with xoshiro

Author: gtaylor

CMakeLists.txt

@@ -298,6 +298,20 @@ if(BUILD_TESTING)
     "${CMAKE_SOURCE_DIR}/src")
   add_test(NAME btech_parts COMMAND btech_parts_test)
 
+  add_executable(btech_random_test tests/btech_random.c
+    ${BTECH_SOURCE_DIR}/core/random_xoshiro.c
+    ${BTECH_SOURCE_DIR}/ui/mech_stat.c)
+  target_compile_definitions(btech_random_test PRIVATE BTECH_INTERNAL=1)
+  target_compile_options(btech_random_test PRIVATE -ffunction-sections)
+  target_link_options(btech_random_test PRIVATE -Wl,--gc-sections)
+  target_link_libraries(btech_random_test PRIVATE btmux_options)
+  target_include_directories(btech_random_test PRIVATE
+    "${CMAKE_BINARY_DIR}/${BTECH_SOURCE_DIR}"
+    "${CMAKE_BINARY_DIR}"
+    ${BTECH_PRIVATE_INCLUDE_DIRS}
+    "${CMAKE_SOURCE_DIR}/src")
+  add_test(NAME btech_random COMMAND btech_random_test)
+
   add_executable(btech_persistence_schema_test
     tests/btech_persistence_schema.c
     ${BTECH_SOURCE_DIR}/persistence/schema.c)

docs/content/en/docs/concepts/btech-architecture.md

@@ -15,7 +15,7 @@ Each domain owns both its state and the operations that change that state:
 
 | Domain | Primary ownership |
 | --- | --- |
-| `core` | Runtime context, random generator, events, and heartbeat |
+| `core` | Runtime context, xoshiro256** random generator, events, and heartbeat |
 | `special` | Native special-object registry and typed object operations |
 | `map` | Battle maps, terrain, map objects, and cached LOS state |
 | `unit` | Mechs, templates, parts, sections, critical slots, and weapons |
@@ -31,6 +31,9 @@ Each domain owns both its state and the operations that change that state:
 | `persistence` | SQLite schema and domain persistence adapters |
 | `integration` | Narrow adapters to MUX-owned services |
 
+The context-owned gameplay generator is xoshiro256**, seeded once from Linux
+OS entropy during BTech startup. Its runtime state is not persisted.
+
 Concrete `Mech`, `BattleMap`, `Autopilot`, and runtime-context layouts are
 private. Cross-domain interfaces use forward declarations, database object
 references, or domain operations rather than copying another domain's state.

src/btech/CMakeLists.txt

@@ -90,7 +90,7 @@ set(BTECH_SOURCES
   core/context.c
   core/heartbeat.c
   core/legacy_events.c
-  core/random_mt.c
+  core/random_xoshiro.c
   economy/econ.c
   economy/econ_cmds.c
   economy/unit_cost.c

src/btech/core/random.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <stdbool.h>
+#include <stdint.h>
 
 typedef struct BtechRollStatistics {
   int rolls[11];
@@ -11,15 +12,15 @@ typedef struct BtechRollStatistics {
   int total_critical_rolls;
 } BtechRollStatistics;
 
-enum { BTECH_RANDOM_STATE_SIZE = 624 };
+enum { BTECH_RANDOM_STATE_SIZE = 4 };
 
 typedef struct BtechRandom {
-  unsigned long state[BTECH_RANDOM_STATE_SIZE];
-  int index;
+  uint64_t state[BTECH_RANDOM_STATE_SIZE];
   BtechRollStatistics statistics;
   bool initialized;
 } BtechRandom;
 
-void btech_random_seed(BtechRandom *random, unsigned long seed);
-unsigned long btech_random_u32(BtechRandom *random);
+void btech_random_seed(BtechRandom *random, uint64_t seed);
+bool btech_random_seed_from_system(BtechRandom *random);
+uint64_t btech_random_u64(BtechRandom *random);
 long btech_random_i31(BtechRandom *random);

src/btech/core/random_mt.c

@@ -0,0 +1,74 @@
+#include "random.h"
+
+#include <assert.h>
+#include <errno.h>
+#include <stddef.h>
+#include <sys/random.h>
+
+static uint64_t rotate_left(uint64_t value, int count) {
+  return (value << count) | (value >> (64 - count));
+}
+
+static uint64_t splitmix64_next(uint64_t *state) {
+  uint64_t value = (*state += UINT64_C(0x9e3779b97f4a7c15));
+
+  value = (value ^ (value >> 30)) * UINT64_C(0xbf58476d1ce4e5b9);
+  value = (value ^ (value >> 27)) * UINT64_C(0x94d049bb133111eb);
+  return value ^ (value >> 31);
+}
+
+void btech_random_seed(BtechRandom *random, uint64_t seed) {
+  assert(random != nullptr);
+
+  for (size_t index = 0; index < BTECH_RANDOM_STATE_SIZE; index++) {
+    random->state[index] = splitmix64_next(&seed);
+  }
+  random->initialized = true;
+}
+
+bool btech_random_seed_from_system(BtechRandom *random) {
+  uint64_t seed;
+  size_t offset = 0;
+
+  assert(random != nullptr);
+
+  while (offset < sizeof(seed)) {
+    ssize_t bytes = getrandom((char *)&seed + offset, sizeof(seed) - offset, 0);
+
+    if (bytes > 0) {
+      offset += (size_t)bytes;
+      continue;
+    }
+    if (bytes < 0 && errno == EINTR) {
+      continue;
+    }
+    return false;
+  }
+
+  btech_random_seed(random, seed);
+  return true;
+}
+
+uint64_t btech_random_u64(BtechRandom *random) {
+  uint64_t result;
+  uint64_t temporary;
+
+  assert(random != nullptr);
+  assert(random->initialized);
+
+  result = rotate_left(random->state[1] * UINT64_C(5), 7) * UINT64_C(9);
+  temporary = random->state[1] << 17;
+
+  random->state[2] ^= random->state[0];
+  random->state[3] ^= random->state[1];
+  random->state[1] ^= random->state[2];
+  random->state[0] ^= random->state[3];
+  random->state[2] ^= temporary;
+  random->state[3] = rotate_left(random->state[3], 45);
+
+  return result;
+}
+
+long btech_random_i31(BtechRandom *random) {
+  return (long)(btech_random_u64(random) >> 33);
+}

src/btech/core/random_xoshiro.c

@@ -13,7 +13,9 @@
 /* Make statistics 'bout what we do.. whatever it is we _do_ */
 
 #include <assert.h>
-#include <time.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
 
 #include "btech/context.h"
 #include "command_handlers_api.h"
@@ -26,7 +28,10 @@
 #include "registry_api.h"
 
 void init_stat(BtechContext *context) {
-  btech_random_seed(&context->random, (unsigned long)time(nullptr));
+  if (!btech_random_seed_from_system(&context->random)) {
+    perror("getrandom");
+    exit(EXIT_FAILURE);
+  }
 }
 
 static const int chances[11] = {1, 2, 3, 4, 5, 6, 5, 4, 3, 2, 1};
@@ -67,62 +72,31 @@ void do_show_stat(CommandInvocation *invocation) {
 /*
  * Returns an integer chosen randomly from the interval [low,high].
  *
- * To eliminate bias from rounding error, this routine repeatedly takes some
- * number of high order bits from the Mersenne Twister, until it finds a value
- * <= (high - low).  If we take n bits, such that 2^n is the smallest power of
- * two greater than (high - low), then this procedure should only require
- * another iteration 50% or less of the time. (The actual value would be
- * (2^n - (high - low)) / (high - low).) It also always terminates due to the
- * statistical qualities of the Mersenne Twister, although possibly only after
- * several (but generally very few) iterations.
- *
- * For example, computing a D6 should require a second iteration 33% (1/3rd) of
- * the time, a third iteration 11% (1/9th) of the time, a fourth iteration 3.7%
- * (1/27th) of the time, a fifth iteration 1.2% of the time (1/81st) of the
- * time, a sixth iteration 0.4% (1/243rd) of the time, and so on.  Or in other
- * words, this will require fewer than six iterations 99.6% of the time, while
- * completely eliminating rounding bias.
+ * To eliminate modulo bias, this routine repeatedly draws from xoshiro256**
+ * until it finds a value in the largest multiple of the interval width that
+ * fits in a uint64_t. This requires at most one additional draw on average.
  *
  * This code is on the critical path, but modern processors can compute this
  * stuff really fast.  There's really no need to have the compiler inline it to
  * perform further optimization.
  */
 long btech_random_range(BtechContext *context, long low, long high) {
-  const unsigned long int range = (unsigned long int)(high - low);
-
-  unsigned long value;
-  unsigned int nn;
+  uint64_t width;
+  uint64_t limit;
+  uint64_t value;
 
+  assert(context != nullptr);
   assert(high >= low);
 
-  /*
-   * Compute n, the shift value.  We're using the 32-bit version of the
-   * Mersenne Twister, so we only need shifts up to 32. (If we did need a
-   * larger value, we would also need to expand our random number size.)
-   *
-   * We can special case some of the common values (such as n = 8 for
-   * range = 5, for the D6) if this loop becomes a concern.
-   */
-  for (nn = 0; nn < 32; nn++) {
-    if ((range >> nn) == 0)
-      break;
+  width = (uint64_t)high - (uint64_t)low + UINT64_C(1);
+  if (width == 0) {
+    return (long)btech_random_u64(&context->random);
   }
 
-  nn = 32 - nn;
-
-  /* Shifts >= bit width are undefined in C.  At least on x86, they
-   * apparently do nothing, which causes the following do-while loop to
-   * run until the generator returns 0.  */
-  if (nn == 32) {
-    return 0;
-  }
-
-  assert(nn < 32);
-
-  /* Repeatedly select random numbers until we get an acceptable one.  */
+  limit = UINT64_MAX - UINT64_MAX % width;
   do {
-    value = btech_random_u32(&context->random) >> nn;
-  } while (value > range);
+    value = btech_random_u64(&context->random);
+  } while (value >= limit);
 
-  return low + value;
+  return (long)((uint64_t)low + value % width);
 }