khtst-rust / src /asm.rs
PowerMachine's picture
v0.11.0: provas r-36..r-42 completadas (M-R5′ guloso ótimo com contraexemplo exausto, V-2′ ECE_aceito com errata reproduzida, H-1′ pin slot) + raciocínio elástico RE-1..RE-8 (ênfase Hedge previsível, water-filling, certificado de compressão com bound estendido triangular e rollback defensivo) + tratamento de erros Rust&Assembly (tratamento.txt): kernels add/jc (CF) e ucomisd/ucomiss (PF) com códigos em registrador → Result, module::error thiserror, 13 sorts total_cmp (NaN nunca mais pânico no treino), checkpoint atômico SHA-256 restaurado e integrado ao treino real, tipos de domínio, MotorPensamento::novo_com_rng determinístico — árvore canônica plana (restos do split v0.10 removidos; ramo morto arquivado localmente) — 160/160 cargo 3×, 29/29 gates (79), 9/9 avaliação real Wikipédia PT-BR (80)
e352eeb verified
Raw History Blame
13.4 kB
//! `asm` — v0.11.0 (tratamento.txt §1+§2): kernels x86-64 em Assembly inline
//! (`core::arch::asm!`) com tratamento de erros por FLAGS do processador,
//! integrados ao protocolo Rust `Result<T, E>` — nunca `panic!` em estado
//! inválido (tratamento.txt: "erros recuperáveis e irrecuperáveis").
//!
//! # Protocolo de erro híbrido (Rust ⇄ Assembly)
//!
//! 1. **Rust (边界/validação)**: comprimentos e pré-condições são validados
//! ANTES do bloco asm ("valide os limites de pilha e divisores antes de
//! executar instruções críticas") — o Assembly nunca recebe entrada
//! inválida de estrutura (apenas valores que podem estourar).
//! 2. **Assembly (detecção)**: cada kernel lê o Registrador de Flags
//! (RFLAGS) após a instrução sensível e desvia com `jcc` condicional:
//! - `CF` (Carry Flag): overflow SEM SINAL — indicador EXATO de estouro
//! em adição `u64` (tratamento.txt §2: "empréstimo/overflow sem sinal");
//! - `PF` (Parity Flag): após `ucomisd`/`ucomiss`, PF=1 ⇔ comparação
//! UNORDERED ⇔ algum operando é NaN (detecção de NaN por hardware);
//! - `ZF` (Zero Flag): igualdade de ponteiros/contadores no fim de laço.
//! 3. **Convenção de retorno**: o bloco asm devolve um CÓDIGO NUMÉRICO em
//! registrador de propósito geral (tratamento.txt §2: "códigos de retorno
//! em registradores... 0 significa sucesso") que o Rust converte em
//! `Result` — o caminho feliz nunca silencia o erro.
//!
//! # Registradores e flags alterados (documentação obrigatória)
//!
//! | Kernel | Instrução sensível | Flags que altera | Flag consumida | Clobbers |
//! |---|---|---|---|---|
//! | `soma_u64_cheia` | `add` | AF CF OF SF ZF PF | `CF` (`jc`) | 3 GPRs (declarados) |
//! | `primeiro_nan_f64` | `ucomisd` | ZF PF CF | `PF` (`jp`) | 3 GPRs + 1 XMM |
//! | `primeiro_nan_f32` | `ucomiss` | ZF PF CF | `PF` (`jp`) | 3 GPRs + 1 XMM |
//!
//! O compilador Rust recebe a lista `in`/`out`/`inout` COMPLETA — nenhum
//! registrador é alterado implicitamente (clobber oculto = bug).
use std::arch::asm;
/// Padrão `module::error` (tratamento.txt §1): enum coeso no escopo do
/// módulo, `thiserror` para Display/Error sem código repetido.
pub mod error {
#[derive(Debug, Clone, PartialEq, thiserror::Error)]
pub enum ErroAsm {
/// `CF=1` após `add`: a soma excede `u64::MAX` — o valor NÃO é
/// confiável (wraparound evitado por hardware, não por software).
#[error("estouro de soma u64: {n} parcelas ultrapassam u64::MAX (CF=1 no kernel add/jc)")]
EstouroSoma { n: usize },
/// Pré-condição estrutural violada (nunca deve ocorrer via API pública).
#[error("pré-condição violada: {motivo}")]
PreCondicao { motivo: String },
}
}
pub use error::ErroAsm;
/// **Kernel 1 — soma u64 com estouro detectado por Carry Flag.**
///
/// Lógica computacional (prova por caso):
/// - `add rax, [ptr]` com valores u64: o processador soma em largura fixa
/// de 64 bits e arma `CF=1` sse o resultado verdadeiro ≥ 2^64 (definição
/// do sinal de carry em adição sem sinal — manual Intel, ADD). Não existe
/// estado intermediário: OU cabe (CF=0, soma exata), OU estoura (CF=1).
/// - `jc 1f` consome CF imediatamente após a adição (nenhuma instrução
/// intermediária altera flags — `add ptr, 8` vem DEPOIS do desvio).
/// - O laço termina por `cmp`/`jne` (ZF=0 ⇒ ponteiros distintos): após a
/// última parcela, `p == f` ⇒ ZF=1 ⇒ não desvia ⇒ sai com código 0.
/// - Com `CF=1` o kernel desvia para `mov {e}, 1` (código de erro 1 em
/// registrador — convenção tratamento.txt §2) e a soma parcial é
/// DESCARTADA pelo Rust (`Err`).
///
/// Determinismo: uma única ordem de soma (esquerda→direita) — o resultado é
/// bit-a-bit reprodutível (u64 é associativo/exato quando não estoura).
pub fn soma_u64_cheia(xs: &[u64]) -> Result<u64, ErroAsm> {
if xs.is_empty() {
return Ok(0); // validação de fronteira em Rust (tratamento.txt)
}
let mut soma: u64 = 0;
let mut codigo_erro: u64;
// {p} é inout: o kernel AVANÇA o ponteiro — modificar um `in` é UB
// de alocação de registradores (lesson v011-1, bug meu catalogado)
let mut ptr = xs.as_ptr();
unsafe {
asm!(
"xor {e}, {e}", // e := 0 (sucesso); ZF=1 (não consumido)
"2:", // ── corpo do laço ──
"add {s}, [{p}]", // soma += *p [AF CF OF SF ZF PF]
"jc 3f", // CF=1 ⇒ estouro sem sinal ⇒ erro
"add {p}, 8", // p += 8 (flags alteradas, NÃO consumidas)
"cmp {p}, {f}", // p == fim? [CF OF SF ZF PF]
"jne 2b", // ZF=0 ⇒ continua
"jmp 4f", // fim normal: código 0 preservado
"3:", // ── caminho de ERRO ──
"mov {e}, 1", // código de erro 1 (registrador)
"4:",
s = inout(reg) soma,
p = inout(reg) ptr,
f = in(reg) xs.as_ptr().wrapping_add(xs.len()),
e = out(reg) codigo_erro,
);
}
if codigo_erro != 0 {
return Err(ErroAsm::EstouroSoma { n: xs.len() });
}
Ok(soma)
}
/// **Kernel 2 — primeiro NaN f64 detectado por Parity Flag (ucomisd).**
///
/// Lógica computacional:
/// - `ucomisd xmm0, [ptr]` compara 0.0 (em xmm) com o valor da fatia:
/// o sinal PF é armado ⇔ a comparação é UNORDERED ⇔ ALGUM operando é NaN
/// (manual Intel, UCOMISD: "unordered" ⇔ QNaN/SNaN em qualquer lado).
/// Como 0.0 é sempre ordenado, PF=1 ⇔ o ELEMENTO é NaN (por eliminação).
/// - `jp 1f` consome PF imediatamente; `i` preserva o ÍNDICE exato do
/// primeiro NaN (código de retorno em registrador — o chamador sabe ONDE,
/// não apenas SE).
/// - Laço `cmp {i}, {n}` / `jne 2b` (ZF): termina com sentinel `−1` (64 bits
/// complemento-2 = `u64::MAX`) quando nenhum NaN existe.
/// - Exceção de ponto flutuante #I (invalid) de QNaN está MASCARADA por
/// padrão no MXCSR do processo Rust — o único efeito observável é PF=1.
///
/// Devolve `Ok(Some(idx))` no primeiro NaN, `Ok(None)` se a fatia é limpa.
pub fn primeiro_nan_f64(xs: &[f64]) -> Result<Option<usize>, ErroAsm> {
if xs.is_empty() {
return Ok(None);
}
let mut idx: u64;
// {p} é inout (o kernel avança o ponteiro — v011-1)
let mut ptr = xs.as_ptr();
unsafe {
asm!(
"xor {i}, {i}", // i := 0 (índice corrente); ZF=1
"2:", // ── corpo do laço ──
"ucomisd {zero}, [{p}]", // 0.0 vs xs[i] [ZF PF CF]
"jp 3f", // PF=1 ⇒ unordered ⇒ NaN no índice i
"add {p}, 8", // p += 8 (flags não consumidas)
"add {i}, 1", // i += 1 (flags não consumidas)
"cmp {i}, {n}", // i == n? [ZF CF OF SF PF]
"jne 2b", // ZF=0 ⇒ continua
"mov {i}, -1", // sentinel NOT_FOUND (u64::MAX)
"jmp 4f",
"3:", // ── achou: i já é o índice ──
"4:",
zero = in(xmm_reg) 0f64,
p = inout(reg) ptr,
n = in(reg) xs.len() as u64,
i = out(reg) idx,
);
}
if idx == u64::MAX {
return Ok(None);
}
Ok(Some(idx as usize))
}
/// **Kernel 3 — primeiro NaN f32 (ucomiss/jp)** — idem ao Kernel 2 em
/// precisão simples (os gradientes do treino são `Vec<f32>`).
pub fn primeiro_nan_f32(xs: &[f32]) -> Result<Option<usize>, ErroAsm> {
if xs.is_empty() {
return Ok(None);
}
let mut idx: u64;
// {p} é inout (o kernel avança o ponteiro — v011-1)
let mut ptr = xs.as_ptr();
unsafe {
asm!(
"xor {i}, {i}",
"2:",
"ucomiss {zero}, [{p}]", // 0.0f vs xs[i] [ZF PF CF]
"jp 3f", // PF=1 ⇒ NaN no índice i
"add {p}, 4", // passo de 4 bytes (f32)
"add {i}, 1",
"cmp {i}, {n}",
"jne 2b",
"mov {i}, -1",
"jmp 4f",
"3:",
"4:",
zero = in(xmm_reg) 0f32,
p = inout(reg) ptr,
n = in(reg) xs.len() as u64,
i = out(reg) idx,
);
}
if idx == u64::MAX {
return Ok(None);
}
Ok(Some(idx as usize))
}
/// Relatório do módulo (telemetria): alvo e kernels disponíveis.
pub fn relatorio() -> String {
format!(
"asm-0.11.0 | target x86-64 System V | kernels: soma_u64_cheia (add/jc, CF), \
primeiro_nan_f64 (ucomisd/jp, PF), primeiro_nan_f32 (ucomiss/jp, PF) | \
protocolo: código em registrador -> Result (tratamento.txt §1+§2)"
)
}
pub fn versao() -> &'static str {
"asm-0.11.0"
}
// ---------------------------------------------------------------------------
// Testes de falsificação (lógica computacional dos flags)
// ---------------------------------------------------------------------------
#[cfg(test)]
mod testes {
use super::*;
/// CF=1 exato: u64::MAX + 1 estoura e o kernel reporta (não wrapa).
#[test]
fn soma_estoura_na_segunda_parcela() {
assert_eq!(soma_u64_cheia(&[u64::MAX, 1]).unwrap_err(), ErroAsm::EstouroSoma { n: 2 });
assert_eq!(soma_u64_cheia(&[u64::MAX]).unwrap(), u64::MAX); // 1 parcela: ok
assert_eq!(
soma_u64_cheia(&[u64::MAX; 3]).unwrap_err(),
ErroAsm::EstouroSoma { n: 3 }
);
}
/// Equivalência EXATA com a soma Rust (u64 é associativo sem estouro).
#[test]
fn soma_equivalente_rust() {
let mut rng = crate::rng::RngDeterministico::novo(3);
for caso in 0..8 {
let n = 1 + caso * 37;
let v: Vec<u64> = (0..n).map(|_| (rng.uniforme() * 1e6) as u64).collect();
let esperado: u64 = v.iter().sum();
assert_eq!(soma_u64_cheia(&v).unwrap(), esperado, "caso {caso}");
}
// fronteira: soma que CHEGA exatamente em u64::MAX (CF=0)
assert_eq!(soma_u64_cheia(&[u64::MAX - 5, 5]).unwrap(), u64::MAX);
// fronteira: u64::MAX-1 + 1 = MAX (ok) e MAX + MAX (estoura)
assert_eq!(soma_u64_cheia(&[u64::MAX - 1, 1]).unwrap(), u64::MAX);
assert!(soma_u64_cheia(&[u64::MAX, u64::MAX]).is_err());
// vazio => Ok(0) (fronteira validada em Rust antes do asm)
assert_eq!(soma_u64_cheia(&[]).unwrap(), 0);
}
/// PF=1 exato: NaN em posição conhecida (quiet e signaling).
#[test]
fn nan_f64_localizado() {
let limpo: Vec<f64> = (0..1000).map(|i| i as f64 * 0.5 - 250.0).collect();
assert_eq!(primeiro_nan_f64(&limpo).unwrap(), None);
// quiet NaN (0x7FF8...) na posição 7
let mut v = limpo.clone();
v[7] = f64::from_bits(0x7FF8_0000_0000_0000);
assert_eq!(primeiro_nan_f64(&v).unwrap(), Some(7));
// signaling NaN (0x7FF0...001) na posição 0
v = limpo.clone();
v[0] = f64::from_bits(0x7FF0_0000_0000_0001);
assert_eq!(primeiro_nan_f64(&v).unwrap(), Some(0));
// último elemento
v = limpo.clone();
v[999] = f64::NAN;
assert_eq!(primeiro_nan_f64(&v).unwrap(), Some(999));
// inf NÃO é NaN (ucomisd ordenado com +inf) => None
v = limpo.clone();
v[500] = f64::INFINITY;
v[501] = f64::NEG_INFINITY;
assert_eq!(primeiro_nan_f64(&v).unwrap(), None);
// vazio => None
assert_eq!(primeiro_nan_f64(&[]).unwrap(), None);
}
/// PF=1 em f32 (gradientes do treino são Vec<f32>).
#[test]
fn nan_f32_localizado() {
let limpo: Vec<f32> = (0..512).map(|i| i as f32 - 256.0).collect();
assert_eq!(primeiro_nan_f32(&limpo).unwrap(), None);
let mut v = limpo.clone();
v[13] = f32::NAN;
assert_eq!(primeiro_nan_f32(&v).unwrap(), Some(13));
v[0] = f32::from_bits(0x7FC0_0000); // QNaN
assert_eq!(primeiro_nan_f32(&v).unwrap(), Some(0));
v = limpo.clone();
v[511] = f32::NAN;
assert_eq!(primeiro_nan_f32(&v).unwrap(), Some(511));
// inf/‑inf não são NaN
v = limpo.clone();
v[10] = f32::INFINITY;
assert_eq!(primeiro_nan_f32(&v).unwrap(), None);
}
/// Desempenho honesto: o kernel asm NÃO é mais lento que o iterador
/// Rust (verificação de sanidade — mesma ordem de grandeza).
#[test]
fn desempenho_comparavel_rust() {
let v: Vec<f64> = (0..1_000_000).map(|i| (i % 97) as f64 * 0.001).collect();
let t0 = std::time::Instant::now();
let r_asm = primeiro_nan_f64(&v).unwrap();
let d_asm = t0.elapsed();
let t1 = std::time::Instant::now();
let r_rust = v.iter().position(|x| x.is_nan());
let d_rust = t1.elapsed();
assert_eq!(r_asm, r_rust);
// tolerância 10× (kernel escalar por elemento; nunca deve ser 10× pior)
assert!(
d_asm.as_nanos() <= 10 * d_rust.as_nanos().max(1),
"asm {d_asm:?} vs rust {d_rust:?}"
);
}
}