@asmlift/core 0.8.0 → 0.9.0

package/src/ir/alias.ts

@@ -86,6 +86,35 @@ export function globalCellOf(defs: Map<Value, Op>, addr: Value, off: number): Gl
   return null;
 }
 
+/**
+ * The named global an address value is DERIVED FROM, through defs alone — `gaddr`, an `add` where
+ * exactly one side reaches a name, and the LEFT side of a `sub`, whose right side is a distance and
+ * never a second object. Where {@link globalCellOf} asks which CELL an
+ * address denotes and answers null the moment a runtime term enters, this asks only which OBJECT
+ * it reaches, which a runtime index does not change: `gVolArr[i]` names no cell and one object.
+ *
+ * So it answers a DECLARATION question — volatile, const, the qualifiers that hold for every byte
+ * of the object — and never an aliasing one: two accesses this gives the same name are not thereby
+ * the same cell. Null when nothing reaches a name, and when two sides do (a sum of two `gaddr`s is
+ * a base the defs cannot tell apart); null is UNKNOWN rather than "no global", so a caller that
+ * refuses on a declared property must read it as "the map cannot say".
+ */
+export function globalBaseOf(defs: Map<Value, Op>, addr: Value): string | null {
+  const d = defs.get(addr);
+  if (d?.opcode === 'gaddr') {
+    return d.attrs.sym as string;
+  }
+  if (d?.opcode === 'add' && d.operands.length === 2) {
+    const a = globalBaseOf(defs, d.operands[0]);
+    const b = globalBaseOf(defs, d.operands[1]);
+    return a !== null && b !== null ? null : (a ?? b);
+  }
+  if (d?.opcode === 'sub' && d.operands.length === 2) {
+    return globalBaseOf(defs, d.operands[0]);
+  }
+  return null;
+}
+
 /**
  * The NUMERIC address an access denotes, resolved through defs alone — a literal base, or the sum
  * of two literals — plus the access's own `off`. Null when the address

package/src/ir/core.ts

@@ -56,8 +56,73 @@ export interface Fn {
   /** L1 SIDE DATA (see {@link ParamEvidence}); set by the SSA builder, `undefined` on parsed IR.
    *  REQUIRED-but-possibly-undefined for exactly the reason `writeOrder` and `slotHomes` are. */
   paramEvidence: ParamEvidence | undefined;
+  /** L1 SIDE DATA (see {@link LocalObjects}); set by a frontend that recovered one, `undefined` on
+   *  every other `Fn`. REQUIRED-but-possibly-undefined for exactly the reason `writeOrder` is. */
+  localObjects: LocalObjects | undefined;
 }
 
+/** Where a function-scope static lives, which decides how its definition is spelled: `rodata` is
+ *  `const` with an initializer, `data` has an initializer, `bss` has none. */
+export type LocalObjectSection = 'rodata' | 'data' | 'bss';
+
+/** One function-scope static, as the target defines it (frontend/local-object.ts). */
+export interface LocalObject {
+  /** the name the source wrote — the linker name without the compiler's counter */
+  name: string;
+  /** the linker name the target carries (`tide.3`, `sprHideTbl$797`) */
+  symbol: string;
+  /** the counter in that name, which is the order the source declared the function's statics in
+   *  (frontend/reloc-symbol.ts `localStaticName`) */
+  order: number;
+  section: LocalObjectSection;
+  /** bytes */
+  size: number;
+  /** the initial contents in target byte order; absent exactly for a `bss` object */
+  bytes?: Uint8Array;
+  bigEndian: boolean;
+  /** What an assembler LISTING shows of an initialized definition beyond its bytes, absent where
+   *  the target is an object file, which keeps no directives. */
+  directives?: LocalObjectDirectives;
+  /** What an object FILE records of where the object sits, absent for an assembler listing, whose
+   *  `.align` is among its directives. */
+  placement?: LocalObjectPlacement;
+}
+
+/** What an object file records of where a static sits. */
+export interface LocalObjectPlacement {
+  /** the alignment the compiler gave the object (mwcc's `.comment` record for its symbol) */
+  align: number;
+  /** the object file's own section (`.sbss`, where {@link LocalObject.section} says `bss`) */
+  section: string;
+  /** its offset in that section */
+  offset: number;
+}
+
+/** An initialized static's data directives, as the compiler wrote them. The compiler writes each
+ *  scalar of the initializer with the directive of its width, and aligns the object to its type's
+ *  alignment; both are facts about the source's TYPE that the bytes alone have lost. */
+export interface LocalObjectDirectives {
+  /** the alignment the object was placed at, in bytes (`.align N` ahead of the label: 2^N; none: 1) */
+  align: number;
+  /** the width every value directive writes, when they all agree (`.word` → 4); padding does not count */
+  unit?: number;
+  /** the directives share a `unit` narrower than a word and one wrote a negative value, which the
+   *  compiler only does for a signed element type */
+  negative: boolean;
+  /** every value directive writes a string (`.ascii`), as the compiler writes a string literal —
+   *  whole, or as the elements of an array or struct of strings */
+  string: boolean;
+}
+
+/** The function-scope statics a function DEFINES, keyed by {@link LocalObject.symbol} — the object a
+ *  `gaddr` of that name denotes. The IR keeps the linker name because it carries a `.` or `$` that
+ *  no C identifier and no declared symbol has, so a static can never be one name with a global of
+ *  its source name (a symbol map's `tide` beside `tide.3`); structure spells it by its source name.
+ *  A `gaddr` names a symbol some declaration elsewhere describes; these have none, because the
+ *  source defined them inside the function, so the definition travels with the function to the
+ *  emitter, which writes it in the body (structure/local-statics.ts). */
+export type LocalObjects = ReadonlyMap<string, LocalObject>;
+
 /** What the machine's own object shows about each ENTRY PARAMETER, beyond the value graph — two
  *  observations the lift destroys, recorded so raise/paramwidth.ts can read them. Every entry
  *  parameter of a lifted function has an entry; a `Fn` with no map is one nobody measured.
@@ -67,9 +132,11 @@ export interface Fn {
  *  `compilerBehaviors.narrowParamWitness` decides what the pair means, and the disassemblies for
  *  each value live there.
  *
- *  `deadHome` — THE STORE DOES NOT REACH THE IR. Both slot-modelling frontends spell a word
+ *  `deadHome` — THE STORE DOES NOT REACH THE IR. Every slot-modelling frontend spells a word
  *  sp-relative store as a write to the SSA key `sp@k` instead of a `store` op (`stackSlotKey`), so
- *  a slot nothing reloads has no reader, no op and no value: it simply is not there by L1. A
+ *  a slot nothing reloads has no reader, no op and no value: it simply is not there by L1. MIPS and
+ *  Thumb lift such a store. PowerPC refuses it, because an unread store may be a call's outgoing
+ *  stack argument (frontend/ppc.ts), so a PowerPC lift never reports a dead home. A
  *  parameter stored to two slots, one of them reloaded, still counts — the dead store happened —
  *  and the reader's own gates decide what a parameter with that much traffic may become.
  *
@@ -230,6 +297,37 @@ export function mkOp(opcode: Opcode, o: Partial<Op> = {}): Op {
   };
 }
 
+// ── a call's callee: a NAME (`attrs.target`) or, for a call through a register, a VALUE ─────────
+//
+// An INDIRECT call carries `indirect: true` and no `target`, and calls the function whose address
+// is its LAST operand. The arguments come first on both forms, so `operands[k]` is argument k on
+// either and a reader that indexes an argument needs no case; a reader that takes the WHOLE operand
+// list as the arguments must go through `callArgs`.
+
+/** The function an indirect call calls, or undefined for a call that names its callee. */
+export function calleeValue(op: Op): Value | undefined {
+  return op.opcode === 'call' && op.attrs.indirect === true ? op.operands[op.operands.length - 1] : undefined;
+}
+
+/** The callee a call names, or undefined for an indirect one. */
+export function calleeName(op: Op): string | undefined {
+  return op.opcode === 'call' && typeof op.attrs.target === 'string' ? op.attrs.target : undefined;
+}
+
+/** A call's arguments, the callee value of an indirect call aside. */
+export function callArgs(op: Op): Value[] {
+  return calleeValue(op) === undefined ? op.operands : op.operands.slice(0, -1);
+}
+
+/** Cut a call down to its first `n` arguments, keeping an indirect call's callee. */
+export function truncateCallArgs(op: Op, n: number): void {
+  const callee = calleeValue(op);
+  op.operands.length = n;
+  if (callee !== undefined) {
+    op.operands.push(callee);
+  }
+}
+
 /** A block's last op — its terminator on well-formed IR, `undefined` on a block with no ops.
  *
  *  `ir/verify.ts` rejects an empty block and every entry path verifies before raising, so the
@@ -412,7 +510,7 @@ export function forwardingTarget(b: Block): Block {
  *  a CFG fact a parameter for one caller's extra edges — so it stays where it is, and what this
  *  paragraph buys is that the next reader looking for a fourth copy knows which of the two the
  *  third one is. */
-export function mergeClasses(fn: Fn): Map<Value, readonly Value[]> {
+export function mergeClasses(fn: Pick<Fn, 'blocks'>): Map<Value, readonly Value[]> {
   const parent = new Map<Value, Value>();
   const find = (v: Value): Value => {
     let r = v;

package/src/ir/discipline.ts

@@ -0,0 +1,248 @@
+// asmlift IR — the access discipline: which ops the recompile must run where, and as often as, the
+// asm ran them, and the questions every pass asks about that.
+//
+// Two kinds of fact meet here. The registry's flags (ir/opcodes.ts `OpSig`: `effects`, `reads`,
+// `traps`) are facts about an OPCODE. A PLACEMENT is a fact about one OP, decided once by the pass
+// that knew it: `call` is its own opcode; `helper` is the stamp `runtime-helpers.ts` `helperOp` puts
+// on a value op the asm computed by calling a runtime routine; `device` is the `volatile` the
+// frontend's device-pin pass (frontend/device-pins.ts) puts on a memory access; `declared` is the
+// stamp raise/declared-volatile.ts puts on an access of an object the symbol map declares volatile —
+// a read only where the compiler could have made it of a `volatile` — as the lift is made and again
+// when structuring starts. Every question below takes the op, so a pass
+// asks one question instead of re-deriving the combination, and `PLACEMENT_ANSWERS` is the one
+// place a placement's answers are written, the attrs a rebuilt op carries it by among them.
+//
+// A new placement is three edits: its `Placement` member with a `PLACEMENT_ANSWERS` row, the
+// `placedAt` clause that reads its stamp, and its key in contracts.ts `assertEffectsPreserved`,
+// whose switch over `placedAt` does not compile until the member is keyed or answered as uncounted.
+//
+// NAMED RESIDUE. The sites below ask a registry question where a placement could change the answer,
+// and keep the registry's answer. DELIBERATE: the placement does not bear on what the site asks.
+// GAP: it does, and some input gets a wrong answer.
+//
+//   `speculationUnsafe` answers no for a plain read — DELIBERATE, argued at the function — and for
+//   a trapping divide — GAP: raise/shortcircuit.ts hoists one the structurer may name above its guard.
+//   A QUALIFIED read is one `qualified` answers yes for.
+//   Two qualified reads commuting (`orderSensitive` without `effectful` on either side):
+//     pattern/engine.ts `reordersUnsequenced` — DELIBERATE: the structurer's barrier scan names the
+//       first of two qualified reads the fold would join in one expression.
+//     structure/hazards.ts `movesPast` — DELIBERATE: the analysis names a qualified read another
+//       qualified read stands between it and its render, so the scan never weighs two.
+//   `effectful` as the barrier a read may not cross, without `isBarrier`'s helper and qualified-read
+//   clauses (structure/analysis.ts):
+//     structure/analysis.ts `writeBetween`, `standsOnMovableRead`, the multi-render rule — DELIBERATE:
+//       each asks about a memory write, and a qualified read writes nothing.
+//   The `call` placement alone, in structure/analysis.ts:
+//     `callPos` — DELIBERATE: it asks which values live across the registers a call clobbers.
+//     `readCone`, `isHomeableDef`, `copyInterdependentValues` — DELIBERATE: a qualified read is a
+//       `load` there, which each already stops at.
+//   `effectful` as block purity — structure.ts's exit ownership, preheader claim, header purity,
+//   copied `ret` target, `ends` and latch effect roots; structure/hazards.ts `testSkipsAnEffect`;
+//   structure/redundant-test.ts `testRereadsOnly` — DELIBERATE: a qualified read renders with its
+//   block, once on each path that runs the block, or declines upstream.
+//     raise/divpow2.ts's bias arm — GAP: the arm is deleted, and a dead qualified read in it with it.
+//   And three accesses the deciders leave unplaced, where a placement would change an answer — GAP:
+//     a device store a pinned read of the same cell re-reads in a loop, under the per-object policy
+//       (frontend/device-pins.ts's header argues it);
+//     a read of a map-declared volatile object through a base that reaches no name — a pointer
+//       walked along the object in a loop, a join of two different addresses in it
+//       (raise/declared-volatile.ts);
+//     a read the stamp cannot place by byte — a runtime index, an `aload` — of an object the map
+//       qualifies only some members of, which may reach a plain member (symbols.ts
+//       `declaresVolatile`).
+import type { Op } from './core';
+import { MEM_BASE_OPS, type OpSig, opSig } from './opcodes';
+
+/** Why an op must run where the asm ran it. */
+export type Placement = 'call' | 'helper' | 'device' | 'declared';
+
+/** Where a qualified access's spelling carries its `volatile`: on a cast of its own address, or
+ *  through the declaration of the object it names. */
+export type Qualifier = 'cast' | 'declaration';
+
+/** The attr raise/declared-volatile.ts stamps a `declared` access with. */
+export const DECLARED_VOLATILE = 'declaredVolatile';
+
+interface PlacementAnswers {
+  /** spelled even when nothing reads the result */
+  keptWhenDead: boolean;
+  /** never run on a path that did not run it */
+  speculationUnsafe: boolean;
+  /** each render is one more execution, so it renders once on every path the asm ran it on */
+  counted: boolean;
+  /** an access whose spelling must carry `volatile`, and where it carries it */
+  qualifiedBy: Qualifier | null;
+  /** the attrs that put this placement on an op a pass builds to stand for `from` */
+  carried: (from: Op) => Op['attrs'];
+}
+
+const PLACEMENT_ANSWERS: Readonly<Record<Placement, PlacementAnswers>> = {
+  // The registry's `effects` flag gives a call the first two answers on its own, and its opcode is
+  // its placement, which an op built to stand for it does not inherit.
+  call: { keptWhenDead: true, speculationUnsafe: true, counted: true, qualifiedBy: null, carried: () => ({}) },
+  // The value the helper computes is pure: nothing observes a divide nobody reads, a fold that
+  // moves one under a guard drops the stamp (`forgetHelperPlacement`), and agbcc computes one
+  // spelled twice once (`a / n + a / n` is one `bl __divsi3`).
+  helper: {
+    keptWhenDead: false,
+    speculationUnsafe: false,
+    counted: false,
+    qualifiedBy: null,
+    carried: (from) => ({ helper: from.attrs.helper }),
+  },
+  // The access is what is observable, not the value it yields, so its spelling is qualified.
+  device: {
+    keptWhenDead: true,
+    speculationUnsafe: true,
+    counted: true,
+    qualifiedBy: 'cast',
+    carried: () => ({ volatile: true }),
+  },
+  declared: {
+    keptWhenDead: true,
+    speculationUnsafe: true,
+    counted: true,
+    qualifiedBy: 'declaration',
+    carried: () => ({ [DECLARED_VOLATILE]: true }),
+  },
+};
+
+/** The placement an op carries, or null for an op that may render wherever its value is used. */
+export function placedAt(op: Op): Placement | null {
+  if (op.opcode === 'call') {
+    return 'call';
+  }
+  if (MEM_BASE_OPS.has(op.opcode) && op.attrs.volatile === true) {
+    return 'device';
+  }
+  if (MEM_BASE_OPS.has(op.opcode) && op.attrs[DECLARED_VOLATILE] === true) {
+    return 'declared';
+  }
+  // An `opaque` carries `helper` too, naming the call nothing could fold (`refuseUnmodelledHelpers`);
+  // it is no value op, and its `effects` flag already places it.
+  if (op.opcode !== 'opaque' && typeof op.attrs.helper === 'string') {
+    return 'helper';
+  }
+  return null;
+}
+
+const answered = (op: Op, q: 'keptWhenDead' | 'speculationUnsafe' | 'counted'): boolean => {
+  const p = placedAt(op);
+  return p !== null && PLACEMENT_ANSWERS[p][q];
+};
+
+/** Where this access's spelling carries the `volatile` the recompile needs to make it where, and as
+ *  often as, the asm did — or null for an op whose spelling needs none. A spelling through the
+ *  declaration needs a cast's qualifier too wherever it reaches the object through a cast, since a
+ *  cast's pointee drops the declaration's qualifiers (l3/volstore.ts `castOffDeclaration`). */
+export function qualifiedBy(op: Op): Qualifier | null {
+  const p = placedAt(op);
+  return p === null ? null : PLACEMENT_ANSWERS[p].qualifiedBy;
+}
+
+/** Must this access's spelling carry `volatile`? */
+export function qualified(op: Op): boolean {
+  return qualifiedBy(op) !== null;
+}
+
+const sigOf = (op: Op): OpSig | undefined => opSig(op.opcode);
+
+/** Does each render of this op execute it — a call, or a qualified access? Such an op is spelled
+ *  once on every path the asm ran it on, at the position it ran: named where a second use, an edge
+ *  or another block would render it again or elsewhere. */
+export function counted(op: Op): boolean {
+  return answered(op, 'counted');
+}
+
+/** Has an observable side effect: a memory write, a call, an unmodelled instruction. The question a
+ *  block-purity test asks, and the write a memory read may not cross. */
+export function effectful(op: Op): boolean {
+  return sigOf(op)?.effects === true;
+}
+
+/** May a dead result be deleted? Registered, no effect, not control flow, and not an op whose
+ *  placement keeps it. */
+export function deletableWhenDead(op: Op): boolean {
+  const sig = sigOf(op);
+  return !!sig && !sig.effects && !sig.terminator && !answered(op, 'keptWhenDead');
+}
+
+/** Must the structurer still SPELL this op when nothing consumes its result — an effect, or a
+ *  memory read?
+ *
+ *  The read half points the opposite way from `deletableWhenDead`, and both are right. That one is
+ *  the C claim: nothing observes a load nobody reads. This one is the COMPILER claim: an optimizing
+ *  compiler deletes every dead read it is allowed to delete, so one still in the target is evidence
+ *  the source's access was `volatile`. A yes here only says the op may not be dropped silently;
+ *  whether a `volatile` can reach the access is an ADDRESS-level question the caller asks
+ *  (structure.ts `volatileQualifiable`), and a read it answers no to is dropped.
+ *
+ *  Its own function and not `orderSensitive`, though the two agree on every registered opcode: they
+ *  ask different questions, and a registry change that splits them is a decision to make at each. */
+export function spelledWhenDead(op: Op): boolean {
+  const sig = sigOf(op);
+  return !!sig && (!!sig.effects || !!sig.reads);
+}
+
+/** May this op NOT be speculated — run on a path that did not run it? An effect, or an op whose
+ *  placement forbids it.
+ *
+ *  A plain memory read answers no, and that is the answer worth arguing. The consumer is
+ *  raise/shortcircuit.ts, which hoists an arm's body into the block above, and the structurer
+ *  inlines an unnamed value back into the `&&`/`||` right-hand side, where C's own short circuit
+ *  re-guards it. Answering yes for plain reads refuses every connective whose arm reads memory,
+ *  which branch-shortcircuit.test.ts's `refusals` pin. A qualified read is the read the re-guard
+ *  argument does not cover — it moves an access, not a value — so its placement answers yes.
+ *
+ *  The trapping divides answer no as well, and there the re-guard argument does NOT carry: a hoisted
+ *  `sdiv` the structurer NAMES becomes an unconditional statement. `reevalUnsafe` answers yes for
+ *  them, so the pre-update sink is not exposed to it.
+ *
+ *  THE EXEMPTION IS NOT TRANSFERABLE. A consumer asking "would gcc have speculated this arm above a
+ *  compare", where nothing re-guards anything, must refuse single-load arms (`gcc/jump.c:483`'s
+ *  `! may_trap_p`); `raise/narrowlocal.ts` asks `reevalUnsafe`, and asking this instead loses
+ *  `synthetic:mergeldcast:agbcc` its byte match. Ask this only where a C-level re-guard at the new
+ *  point actually holds. */
+export function speculationUnsafe(op: Op): boolean {
+  return effectful(op) || answered(op, 'speculationUnsafe');
+}
+
+/** Does this op's answer depend on WHERE it runs on one path? An effect (its order against other
+ *  effects is observable) or a memory read (it answers whichever stores ran before it). */
+export function orderSensitive(op: Op): boolean {
+  const sig = sigOf(op);
+  return !!sig && (!!sig.effects || !!sig.reads);
+}
+
+/** May this op NOT be re-evaluated at another program point — order-sensitive, or trapping? The trap
+ *  half separates it from `orderSensitive`: it matters only when the new point can be reached on a
+ *  path the old one was not. A collapsed switch re-renders a test block's ops at their uses, each
+ *  dominated by the def, so on a subset of the original paths — a narrowing, never a speculation —
+ *  and asks `orderSensitive` instead. */
+export function reevalUnsafe(op: Op): boolean {
+  const sig = sigOf(op);
+  return !!sig && (!!sig.effects || !!sig.reads || !!sig.traps);
+}
+
+/** Drop the `helper` placement from an op a pass moves out of the block the asm called it in, and
+ *  return the op. The stamp is read as WHERE the call ran, so an op moved elsewhere must stop
+ *  claiming it and renders as the pure value it computes. raise/shortcircuit.ts hoists a `&&`/`||`
+ *  guarded arm's body above the branch, and there C's short circuit re-guards the op at its use:
+ *  agbcc's `if (a > 0 && k / n != 0)` runs the `bl __divsi3` under the first compare, and named at
+ *  its hoisted def it would divide on the path the `&&` skips. */
+export function forgetHelperPlacement(op: Op): Op {
+  if (placedAt(op) === 'helper') {
+    const { helper: _, ...rest } = op.attrs;
+    op.attrs = rest;
+  }
+  return op;
+}
+
+/** `attrs`, plus the placement of `from`, for an op a pass builds to stand for `from`: a memory
+ *  access keeps its `volatile` or its `declared` stamp, a value op its `helper`. Every op rebuilder
+ *  carries the stamps through here, so a placement decided once is not lost to a rebuild that
+ *  forgot to copy it. */
+export function carryDiscipline(from: Op, attrs: Op['attrs']): Op['attrs'] {
+  const p = placedAt(from);
+  return p === null ? attrs : { ...attrs, ...PLACEMENT_ANSWERS[p].carried(from) };
+}

package/src/ir/float-bits.ts

@@ -0,0 +1,47 @@
+// asmlift IR — a double literal: the bit pattern the IR carries it as, and the C that spells it.
+//
+// THE IR CARRIES THE BITS, NOT A NUMBER, because a number has one value that is two doubles:
+// `-0` prints and serializes as `0`, so a literal keyed or dumped by its number would be the
+// other zero. Sixteen hex digits name exactly one double, NaN payloads included.
+
+const view = new DataView(new ArrayBuffer(8));
+
+/** The bit pattern, as sixteen hex digits, of the double whose high word (sign and exponent) is
+ *  `hi` and low word is `lo`. */
+export function doubleBits(hi: number, lo: number): string {
+  return (hi >>> 0).toString(16).padStart(8, '0') + (lo >>> 0).toString(16).padStart(8, '0');
+}
+
+/** Whether `bits` is a double's bit pattern: sixteen hex digits, as `doubleBits` spells one. A
+ *  single's eight would name another number read as a double, so nothing here takes one. */
+export const isDoubleBits = (bits: unknown): bits is string => typeof bits === 'string' && /^[0-9a-f]{16}$/.test(bits);
+
+/** The double a bit pattern names. */
+export function doubleOf(bits: string): number {
+  if (!isDoubleBits(bits)) {
+    throw new Error(`'${bits}' is not a double's bit pattern`);
+  }
+  view.setUint32(0, parseInt(bits.slice(0, 8), 16));
+  view.setUint32(4, parseInt(bits.slice(8, 16), 16));
+  return view.getFloat64(0);
+}
+
+/** The C spelling of a finite double: the shortest decimal that reads back as the same double
+ *  (ECMAScript's Number::toString, whose digits are the fewest that do), with a `.0` where it has
+ *  neither a point nor an exponent, so C reads a `double` and not an `int`, and `-0.0` for the
+ *  negative zero.
+ *
+ *  THAT IT READS BACK IS A PREMISE ABOUT THE COMPILER, and the one producer of a literal
+ *  (`raise/floathelpers.ts`) runs only where the target states it
+ *  (`compilerBehaviors.roundTripsDoubleLiterals`, which cites agbcc's source for it). */
+export function doubleLiteral(bits: string): string {
+  const x = doubleOf(bits);
+  if (!Number.isFinite(x)) {
+    throw new Error(`the double ${bits} is not finite and has no C literal`);
+  }
+  if (Object.is(x, -0)) {
+    return '-0.0';
+  }
+  const s = String(x);
+  return /[.e]/.test(s) ? s : `${s}.0`;
+}