//! `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` — 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 { 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, 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`). pub fn primeiro_nan_f32(xs: &[f32]) -> Result, 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 = (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 = (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). #[test] fn nan_f32_localizado() { let limpo: Vec = (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 = (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:?}" ); } }