Comandos de engine da CLI

Visão geral

Esta página aborda comandos de engines locais de projeto, seus principais argumentos e seus limites de execução. Use o --help do comando específico instalado para obter a lista completa de opções e valores enumerados. Leia os próprios limites do resultado antes de usá-lo como evidência de engenharia.

Leia primeiro Interface de comandos da CLI. Ela define o roteamento, os códigos de saída, os envelopes de comprovantes e a regra de resolução de executáveis irmãos da qual todos os comandos abaixo dependem. O namespace job, analyze run e evolve run estão em Comandos de jobs e Cloud da CLI.

Convenções usadas nas tabelas:

• <ANGLE> é um argumento posicional; [ANGLE]... é um argumento opcional repetível.

• As opções na coluna Obrigatório devem estar presentes, ou o comando sai com 2 antes de iniciar qualquer coisa.

• Todo subcomando também aceita --json e -h/--help. Essas opções não são repetidas em cada linha.

• --project é --project <PROJECT>, um diretório de trabalho opcional para caminhos relativos de entrada e saída, salvo indicação contrária na linha. Ele deve resolver para um diretório real; um valor que não possa ser resolvido sai com 2.

capabilities

alti capabilities examina a estrutura instalada autenticada e informa sua interface de operações. Conclua primeiro Instalar no Linux; o bootstrap embutido 0.1.9 fornece a estrutura de comprovantes e payload anteriormente ausente. Uma resposta de capacidade não é evidência de um kernel ou projeto executado.

rtl

Vinte e oito subcomandos. rtl compile e rtl synthesize são os dois caminhos de compatibilidade com --runner; todo outro subcomando de rtl é executado localmente e de forma incondicional.

Diferentemente de physical run e px analyze, esses dois iniciam sua engine sem argumentos de repasse, pois cada um fornece uma operação fixa de engine. A engine então informa seu próprio erro de argumento ausente, e seu status de saída é repassado sem alteração. Forneça os argumentos necessários após --.

--schematic nos três subcomandos rtl artifact seleciona o armazenamento fixo de comprovantes de esquemático em vez do armazenamento de resultados de operações RTL.

--entry-id nos comandos específicos de identidade confirmada deve conter exatamente 64 caracteres hexadecimais minúsculos. Qualquer outra coisa sai com 2 e entry id must be exactly 64 lowercase hexadecimal characters.

Limites de rtl schematic

rtl schematic valida seus caminhos antes de iniciar qualquer coisa. Cada arquivo de código-fonte, diretório de include e define é rejeitado na admissão se violar um destes limites:

Os caminhos devem ser relativos ao projeto selecionado, não devem começar com -, não devem conter bytes de controle nem conter ... --top e o nome de um define devem ser identificadores SystemVerilog de 1 a 128 bytes; um define pode conter um valor após = até 4096 bytes no total.

Opções de rtl target-analysis

admit e preflight leem JSON canônico de pacote de código-fonte de stdin e ambos exigem as mesmas onze opções: --module <NAME>, --top <NAME>, --targets <CSV>, --primary-target <ID>, --tools <CSV>, --report-detail <LEVEL>, --profile <ID>, --cpu-slots <N>, --memory-bytes <N>, --max-wall-time-ms <N> e --deadline-unix-ms <N>. --cell-decomposition é uma flag booleana opcional.

--cpu-slots é um inteiro sem sinal de 32 bits; --memory-bytes, --max-wall-time-ms e --deadline-unix-ms são inteiros sem sinal de 64 bits.

Um valor duplicado ou não listado em qualquer CSV é recusado durante a análise, por exemplo targets must be a comma-separated subset of: generic-asic, sky130-asic, xc7-fpga.

O envelope de solicitação de simulação

<REQUEST_JSON> é um caminho relativo ao projeto para um arquivo que a CLI lê e verifica antes de iniciar qualquer coisa. O caminho deve ser normalizado e relativo, não deve atravessar um link simbólico em nenhum componente e deve resolver dentro da raiz do projeto. O arquivo deve ser regular e ter no máximo 260 MiB.

Seu JSON deve ser um objeto com exatamente quatro chaves:

{
  "schema": "altifigence.rtl.operation-request.v1",
  "version": 1,
  "operationId": "altifigence.rtl.simulate.v1",
  "request": {}
}

operationId deve ser altifigence.rtl.simulate.v1 para rtl simulate e altifigence.rtl.simulate.v2 para rtl simulate-v2. Uma incompatibilidade é recusada antes da inicialização com RTL simulation request must be the exact <id> envelope.

Os subcomandos de identidade confirmada não podem ser executados

Os oito comandos específicos rtl *-committed-identities list e read despacham para uma engine chamada alti-rtl-runner. Esse binário não é um dos 24 binários de engine que a versão compila e distribui; portanto, não pode ser resolvido como irmão de alti nem em PATH a partir de uma instalação correta. Invocar um deles produz um comprovante de engine local com status: "unavailable" e exitCode: 127:

Texto

$ alti --json rtl fanout-free-committed-identities list
{
  "schema": "altifigence.local-engine-execution.v1",
  "status": "unavailable",
  "domain": "rtl",
  "operation": "fanout-free-committed-identities-list",
  "runner": "local",
  "binary": "alti-rtl-runner",
  ...
}

Não baseie automações nesses oito comandos.

sv

Vinte e três subcomandos, todos locais e incondicionais. Nenhum aceita --runner.

Regras de valores posicionais:

• <LINE> e <COLUMN> são inteiros não zero com base 1. 0 sai com 2.

• <REPLACEMENT> deve ser um identificador SystemVerilog: o primeiro caractere é uma letra, _ ou $, e os demais são alfanuméricos, _ ou $.

• <REVIEWED_PLAN_SHA256> deve conter 64 caracteres hexadecimais minúsculos.

• <STABLE_ID> deve conter de 1 a 128 caracteres entre letras minúsculas, dígitos e hífens.

• --filter deve conter de 1 a 128 bytes que não sejam de controle; --limit deve ser um inteiro de 1 a 64, e --limit 65 sai com 2.

sv frontend rename-apply é o único subcomando de sv que exige --project, e o valor deve ser um caminho absoluto para um diretório real que não seja link simbólico. Sem ele, o comando sai com 1 e SV rename apply requires --project <absolute-workspace>.

sv review immediate e sv review interprocess leem código-fonte SystemVerilog de stdin. São os únicos subcomandos de sv respaldados por suas próprias engines, alti-sv-immediate-review e alti-sv-interprocess-review; todo o resto no namespace usa alti-sv-frontend.

sv uvm simulation admit exige treze opções: --bundle-id, --bundle-sha256, --source-count, --source-bytes, --test, --top, --clock, --period-ps, --cycles, --max-wall-time-ms, --max-cpu-cores, --max-memory-bytes e --max-artifact-bytes. sv uvm simulation preflight exige essas treze mais --attempt-id, --observed-at-unix-ms e --deadline-unix-ms e também aceita o booleano --cancellation-requested (padrão false). --source-count é um inteiro sem sinal de 32 bits, --max-cpu-cores é um inteiro sem sinal de 16 bits, e as demais opções numéricas são inteiros sem sinal de 64 bits.

verification

--tolerance-pct deve ser um número finito não negativo; um valor negativo ou não numérico sai com 2 e tolerance-pct must be a finite non-negative number.

--format aqui seleciona o próprio formato de saída da engine e é independente da flag de envelope --json no nível da CLI. Ambas podem ser usadas juntas.

trace

<FORMAT> em trace export é um valor enumerado posicional, não uma flag, e vem antes do caminho de entrada. Seus valores são vcd e chrome.

--reference pode ser repetido para indicar artefatos de referência adicionais. <TRACE_ARTIFACT_ID>, os IDs de referência e <PACKAGE_ID> podem começar com hífen sem precisar de --.

Observe que alti trace sem subcomando chega ao analisador local e sai com 2 pedindo um subcomando. Portanto, a ação de uma palavra trace no manifesto de ações embutido não pode ser acessada pela linha de comando nesta versão; consulte Comandos de jobs e Cloud da CLI.

labs

Descritores e validação somente leitura. A execução de fluxos de trabalho não é exposta pela CLI.

labs validate é rigoroso com suas duas entradas, e todas as regras abaixo são verificadas antes de a engine iniciar:

• --project deve ser um caminho absoluto para um diretório real, não um link simbólico.

• <DESCRIPTOR> deve ser relativo ao espaço de trabalho, não deve conter .. nem componente de raiz e deve ter no máximo 4096 bytes.

• Deve usar a extensão .json.

• Deve resolver para um arquivo regular real de no máximo 1048576 bytes, e o caminho resolvido ainda deve estar dentro do projeto.

tcl

Os quatro primeiros respondem a partir de descritores pela engine empacotada alti-tcl e emitem o envelope padrão de engine local.

tcl evaluate é diferente de três formas. Ele lê o script de stdin, com limite de 4194304 bytes; entrada vazia é recusada. Exige alti-tcl-local-runner como irmão estrito de alti, sem alternativa por PATH, e o verifica em relação à cadeia de confiança instalada. O bootstrap 0.1.9 instala o componente Tcl assinado fixo necessário para esse caminho; use o binário instalado. Ele também emite seu próprio esquema de comprovante, altifigence.cli.tcl-evaluation.v1, com seus próprios códigos de saída — ambos estão em Interface de comandos da CLI.

eidb

eidb capabilities, eidb readback e eidb semantic-readback não recebem --project; não usam caminhos do ponto de vista da CLI.

physical

Quarenta e dois subcomandos. physical run é o caminho de compatibilidade com --runner; os demais são executados localmente e de forma incondicional, e cada um repassa seu próprio nome de subcomando diretamente para alti-physical-runner como operação de engine. O papel da CLI neste namespace é admitir argumentos e formatar comprovantes, portanto a interface é regular o suficiente para ser apresentada em dois grupos.

Toda operação seguinte com escopo de entrada lê uma entrada persistida produzida por uma operação anterior com escopo de projeto. Omitir --entry-id sai com 2 antes de iniciar qualquer coisa. Isso corresponde a trinta e seis das quarenta e duas. As seis restantes são:

physical route-evidence-closure read é um comando de duas etapas: a CLI primeiro lista as identidades confirmadas, exige que seu --identity-key-sha256 apareça nessa lista e então relê exatamente essa identidade. Uma chave que não contenha 64 caracteres hexadecimais minúsculos ou não esteja na lista atual é recusada com saída 1 antes da segunda etapa. A etapa de listagem não usa caminhos e não recebe --project.

physical run não inicia sem uma operação de engine após --:

Texto

$ alti physical run
error: legacy local engine operation is required after `--`

Isso sai com 1. As operações legadas aceitas são --capabilities-json, capabilities e execute; qualquer outra sai com 1 e legacy local engine operation ... is not in the public allowlist.

px

px analyze é o caminho de compatibilidade com --runner. Quando um argumento posicional se chama <INPUTS_RELATIVE_...>, ele é resolvido dentro do diretório inputs/ do projeto, não em relação ao seu diretório de trabalho.

Três desses comandos declaram seus próprios limites no texto de ajuda, e esses limites fazem parte do contrato: px static-timing explicitamente não é signoff, px spef-summary explicitamente não contém autoridade de análise, e px fdtd2d preflight informa um impedimento de prontidão em vez de um resultado. Trate suas saídas de acordo.

Assim como physical run, px analyze exige uma operação legada após -- e, caso contrário, sai com 1. Sua lista permitida é capabilities e execute.

Operações PX de CPU e CUDA

Esses comandos aceitam --project; os dois primeiros também aceitam --timeout-ms 1..300000. Selecionar explicitamente cuda exige execução CUDA utilizável. auto permite separadamente o fallback para CPU registrado pela engine; examine o backend informado. Essas operações numéricas limitadas não estabelecem signoff físico geral nem aceleração por GPU de toda operação PX.

isa

Quatro dos seis subcomandos leem código-fonte CX exclusivamente de stdin. isa run é o caminho de compatibilidade com --runner.

--check aceita exatamente elaboration, static-semantics, encoding-uniqueness e decode-determinism. --bit-len é um inteiro sem sinal de 32 bits. --text e --bits não devem estar vazios nem conter apenas espaços.

Diferentemente de physical run e px analyze, isa run contém uma operação fixa de engine, portanto inicia sem argumentos de repasse e a engine informa seus próprios requisitos:

Texto

$ alti isa run
cx run: run requires --program <path> or --program-text
[failed] isa.run runner=local engine=alti-cx/run executable=alti-cx resolution=path exit=1 project=.

ide

Operações do host Desktop. A computação permanece nos namespaces de engine acima.

ide open inicia o aplicativo de desktop instalado separadamente. Os comandos nativos de espaço de trabalho, Cloud, serviço e criação de projeto abaixo funcionam por seus próprios backends explícitos.

--project deve ser um diretório absoluto canônico: absoluto, existente, não um link simbólico e igual à sua própria forma canônica. Um caminho que resolve por um symlink é recusado em vez de seguido silenciosamente.

ide open não usa um binário de engine. Ele resolve um executável chamado altifigence-ide como irmão de alti e depois em PATH, inicia-o com --project <canonical-dir> e emite um comprovante altifigence.ide-launcher-receipt.v1:

O status de saída é 0 para spawned e 1 nos demais casos. altifigence-ide é distribuído com Digital Design Studio, não com o arquivo da CLI, portanto ide open informa unavailable em uma instalação apenas da CLI.

Operações nativas de projeto e espaço de trabalho

ide init --parent ABSOLUTE_DIR --name NAME cria uma nova estrutura inicial dentro de uma pasta pai canônica pertencente ao chamador. Não sobrescreve um projeto existente. ide workspace opera em arquivos locais salvos sem abrir a UI:

O resultado do plano nativo é uma entrada completa opaca para aplicação. Salve a saída bruta da engine sem o --json global, revise-a e passe o mesmo documento ao comando de aplicação correspondente. Por exemplo, com seu projeto absoluto existente e solicitação tipada de hierarquia:

alti ide workspace hierarchy-plan --project "$PROJECT" \
  --request "$HIERARCHY_REQUEST" > "$PLAN_FILE"
# Review the complete plan and changed source before the next command.
alti ide workspace hierarchy-apply --project "$PROJECT" --request "$PLAN_FILE"

Não encaminhe a saída de um comando com falha para apply. Escolha um novo arquivo de plano e confira cada status de saída. A criação de arquivos usa transações duráveis e serializadas e hashes atuais do código-fonte; não oferece atomicidade instantânea em todo o sistema de arquivos contra processos de escrita não relacionados. Conflitos exigem uma nova revisão. A criação de hierarquias é seleção limitada de código-fonte e criação de estrutura inicial, não refatoração semântica completa de SystemVerilog nem prova de equivalência.

As configurações preservam o formato DDS .alti/ide-settings.json, chaves desconhecidas e valores literais null. O patch é uma mesclagem recursiva, não uma exclusão RFC 7396. O orçamento de solicitação/resultado é 256 KiB e profundidade 8; a UI nativa e a CLI usam o mesmo .alti/.ide-settings.lock. A CLI aborda o formato atual de projeto, não um segundo escopo independente de configurações globais do desktop.

Transações nativas e Git exigem o contrato Linux. A recuperação atual lê diários V1 e V2. Após uma criação/exclusão ou aplicação de hierarquia interrompida, execute health da nova CLI antes de abrir um backend DDS antigo que só suporte V1. Um backend antigo recusa um diário V2 pendente sem limpá-lo. Transações normalmente concluídas limpam seu diário ativo; uma atualização do backend com recuperação transparente é recomendada, não um pré-requisito para toda edição concluída pela CLI.

Git

Em ide workspace git, todos os comandos recebem --project ABS:

Essas operações recuperam e serializam em relação às transações nativas do espaço de trabalho. Elas não expõem argumentos Git arbitrários, hooks ou credenciais de push remoto.

Busca em código-fonte salvo

alti ide workspace search --project "$PROJECT" --query 'module' --limit 80

A busca nativa suporta --match-case, --whole-word, um --regex conservador de largura fixa, limites de 1–500 correspondências e --timeout-seconds 1..120. Ela lê texto salvo pelo limite nativo files/read, com orçamentos de 500 arquivos, 4 MiB por arquivo, 16 MiB no total e 1 MiB de saída. Confira o truncamento e as evidências de conteúdo. Buffers não salvos do editor não são pesquisados. A busca Cloud e a busca/substituição HTTP legada são operações de serviço separadas.

xls

O caminho nativo suporta funções DSLX e XLS IR limitadas com valores de 1–64 bits, avaliação de constantes/remoção de código morto e RTL combinacional ou RTL com 1–16 estágios de registradores de saída. A solicitação seleciona cpu ou explicitamente cuda para avaliação em lote suportada. Um backend CUDA indisponível é um erro, não uma execução automática na CPU. Comece com o exemplo de CPU.

O caminho upstream separado instala uma toolchain pública Google XLS Linux fixada, verifica seu arquivo e inventário de ferramentas/stdlib e preserva os arquivos de licença. Suporta imports, parâmetros, structs, enums, tipos agregados e de largura arbitrária e procs quando a ferramenta upstream selecionada suporta a operação solicitada. Não usa o analisador limitado bits64 nem acelera toda a toolchain Google com CUDA.

Solicitações upstream selecionam check, eval, convert, optimize ou codegen. Uma avaliação DSLX sem vetores/ticks explícitos executa testes reais do módulo; zero testes unitários executados não é sucesso. O arquivo base não contém executáveis independentes de avaliadores IR/proc. Vetores explícitos ou ticks de canal exigem um pacote adicional verificado de avaliadores admitido durante a instalação com --evaluator-bundle e --evaluator-manifest-sha256. Examine as capacidades antes de solicitar essas operações. A geração de código de pipeline upstream suporta 1–64 estágios; sua programação de atraso unitário não é temporização de silício caracterizada.

compute

Os comandos de solicitação aceitam --project. A entrada de Simulation/Evolve é limitada a 4 MiB; a de verify, a 16 MiB. O componente empacotado alti-rtl-cuda é responsável por esse caminho. compute rtl-evolve recebe altifigence.rtl.evolve-request.v1, com a solicitação nativa de geração existente aninhada em request; não é um envelope de operação evolve run.

O Evolve CUDA calcula diagnósticos limitados de atividade combinacional. A geração de candidatos, as verificações de correção, a síntese e a avaliação do objetivo permanecem na CPU. Os executáveis reais Icarus iverilog e vvp devem estar disponíveis pela configuração de ferramentas do host. cpu-reference exige cuda_timeout_ms: 0 e device_memory_bytes: 0; cuda recusa execução indisponível em vez de usar fallback. Use um novo request.run_dir com uma pasta pai existente.

A solicitação limita gerações e filhos a 1–16, ilhas a 1–4, avaliações planejadas totais a 256 e filhos de LLM a zero. A memória de dispositivo é um orçamento limitado de buffer do worker, não um limite de memória total do driver. O cancel_file local opcional e os prazos suportam cancelamento cooperativo; chamadas de ferramentas nativas mantêm seus próprios limites. Um resultado CUDA bem-sucedido exige atividade real aceita de candidatos e proveniência de hardware armazenada, não apenas descoberta de dispositivos ou uma sondagem inicial. A concordância funcional CPU/CUDA não é uma alegação de aceleração.

Comandos ausentes do download atual

Os namespaces anteriormente omitidos eda e reports agora são roteados:

Essas operações são de inspeção, análise sintática ou vinculação limitadas, não de execução geral de ferramentas EDA. ide init e os comandos explícitos nativos do Evolve também estão disponíveis. O caminho de compatibilidade não distribuído alti-rtl-runner descrito acima continua sendo uma limitação separada; não infira suporte apenas pela ajuda.

Prepare um fluxo de engine

1. Escolha a operação e leia sua resposta de capacidades instaladas e a ajuda do comando específico.

2. Crie uma pequena entrada salva dentro do projeto selecionado e identifique seu topo/módulo ou ponto de entrada.

3. Forneça as ferramentas externas necessárias e use um backend explícito quando a solicitação suportar seleção CPU/CUDA.

4. Execute uma vez com recursos limitados e mantenha os diagnósticos e o resultado nativo completo.

5. Examine o backend real, as entradas, os artefatos de saída e as métricas não suportadas antes de montar um fluxo maior.

Use Análise DDS para o fluxo gráfico e Evolve para comparação de candidatos. O suporte de engine da CLI, um painel de desktop e uma rota Cloud são integrações separadas; confira o fluxo que realmente usará.