Анализ, экспорт и проверка трассы

Проанализируйте трассу .altrace, сохраните её временную шкалу и экспорт в VCD или Chrome и храните результаты как пакет проверки, который можно повторно открыть.

Используйте Altifigence CLI 0.1.9 в Linux, чтобы проанализировать одну трассу .altrace, сохранить её временную шкалу, экспортировать её в VCD или в события трассы Chrome и хранить результаты в пакете проверки, который вы можете выводить списком, показывать и считывать обратно. Каждая команда запускает движок alti-trace, поставляемый вместе с alti.

Подготовка файла трассы

Команды alti trace читают файлы .altrace. Файл содержит четыре байта ALTR, два байта версии, два нулевых байта, длину заголовка в виде 8 байт в формате little-endian, заголовок JSON и полезную нагрузку, которую описывает заголовок. Приведённый ниже скрипт записывает небольшую трассу с одним ядром и пятью событиями: три MAC_COMPUTE, одно DMA_READ и один API_CALL с именем step_1. Каждая строка события имеет вид core start duration type [api_name].

PROJECT="$(cd "$HOME/alti-projects/demo-project" && pwd -P)"
cd "$PROJECT"

le() { local n=$1 v=$2; while [ "$n" -gt 0 ]; do printf "\\x$(printf %02x $((v & 255)))"; v=$((v >> 8)); n=$((n - 1)); done; }
str() { le 8 "${#1}"; printf '%s' "$1"; }
write_trace() {
  local out="$1" payload line core start dur type api total=0 header
  local -a lines
  mapfile -t lines
  payload="$(mktemp)"
  {
    for line in "${lines[@]}"; do
      read -r core start dur type api <<<"$line"
      (( start + dur > total )) && total=$((start + dur))
    done
    le 8 "$total"
    le 8 "${#lines[@]}"
    for line in "${lines[@]}"; do
      read -r core start dur type api <<<"$line"
      le 4 "$core"; le 8 "$start"; le 8 "$dur"; str "$type"
      if [ -n "$api" ]; then printf '\x01'; str "$api"; else printf '\x00'; fi
    done
  } >"$payload"
  header="{\"altifigence_trace_version\":\"1.0\",\"trace\":{\"cycles\":$total,\"cores\":1,\"clock_mhz\":1000},\"payload\":{\"encoding\":\"bincode\",\"byte_length\":$(wc -c <"$payload")}}"
  { printf 'ALTR\x01\x01\x00\x00'; le 8 "${#header}"; printf '%s' "$header"; cat "$payload"; } >"$out"
  rm -f "$payload"
}

write_trace run.altrace <<'EVENTS'
0 0 100 MAC_COMPUTE
0 100 50 DMA_READ
0 150 5 API_CALL step_1
0 160 100 MAC_COMPUTE
0 260 100 MAC_COMPUTE
EVENTS

wc -c < run.altrace

Убедитесь, что последняя команда выводит 376: 16 байт префикса, 136-байтовый заголовок, объявляющий "encoding":"bincode" и "byte_length":224, и 224 байта полезной нагрузки.

376

Анализ трассы

Выполните alti trace inspect с путём к трассе. Относительный путь разрешается относительно --project. По умолчанию выводится JSON, а .artifact.inspect содержит сводку трассы.

alti trace inspect --project "$PROJECT" run.altrace \
  | jq '.artifact.inspect | {payload_encoding, payload_bytes, total_cycles, cores, clock_mhz, event_count, event_types}'
{
  "payload_encoding": "bincode",
  "payload_bytes": 224,
  "total_cycles": 360,
  "cores": 1,
  "clock_mhz": 1000,
  "event_count": 5,
  "event_types": {
    "API_CALL": 1,
    "DMA_READ": 1,
    "MAC_COMPUTE": 3
  }
}

Убедитесь, что код завершения равен 0. Добавьте --format text, чтобы получить краткий отчёт.

alti trace inspect --project "$PROJECT" run.altrace --format text
alti-trace: run.altrace
  cycles: 360
  cores: 1
  clock: 1000 MHz
  payload: 224 bytes (bincode)
  events: 5
  - API_CALL: 1
  - DMA_READ: 1
  - MAC_COMPUTE: 3

Полный JSON имеет схему altifigence.trace.operation.result.v1. Его .artifact.artifact_id — идентификатор сохранённого результата в виде trace:altifigence.trace.inspect.v1: с последующим content_sha256 сводки. inspect читает трассы, у которых кодировка полезной нагрузки — bincode, flatbuf, flatbuf_v2 или flat.

Сохранение временной шкалы и экспорта

alti trace timeline записывает данные временной шкалы трассы в <OUTPUT>. alti trace export первым аргументом принимает формат, vcd или chrome, затем трассу и путь вывода. Каждая команда записывает выходной файл и выводит описывающий его результирующий JSON.

alti trace timeline --project "$PROJECT" run.altrace run.timeline \
  | jq '{operation_id, artifact: (.artifact | {artifact_schema, media_type, byte_length, records_written, output_label})}'
{
  "operation_id": "altifigence.trace.timeline.v1",
  "artifact": {
    "artifact_schema": "altifigence.trace.timeline.flatbuffer.v1",
    "media_type": "application/vnd.altifigence.trace-flatbuffer",
    "byte_length": 140,
    "records_written": 5,
    "output_label": "run.timeline"
  }
}

Временная шкала хранит по 24 байта на событие, затем имена API_CALL, поэтому для этой трассы byte_length равно 140, а records_written — 5. Экспортируйте ту же трассу в обоих форматах.

alti trace export vcd --project "$PROJECT" run.altrace run.vcd \
  | jq -c '.artifact | {artifact_schema, media_type, records_written, output_label}'
alti trace export chrome --project "$PROJECT" run.altrace run.json \
  | jq -c '.artifact | {artifact_schema, media_type, records_written, output_label}'
{"artifact_schema":"altifigence.trace.export.vcd.v1","media_type":"text/x-vcd","records_written":374,"output_label":"run.vcd"}
{"artifact_schema":"altifigence.trace.export.chrome.v1","media_type":"application/json","records_written":5,"output_label":"run.json"}

Убедитесь, что код завершения каждой команды равен 0. run.vcd начинается со строки $version, а run.json — это массив JSON с одним объектом на каждое событие.

head -n 1 "$PROJECT/run.vcd"
jq length "$PROJECT/run.json"
$version alti_core vcd_writer 0.1 $end
5

Хранение результатов в пакете проверки

Каждый успешный запуск inspect, timeline и export также сохраняет свой результат в $PROJECT/.altifigence/artifacts/trace-review. artifact_id, который выводят эти команды, — это идентификатор, принимаемый командой alti trace review materialize: сначала артефакт трассы, затем каждый артефакт --reference. Пакет может содержать до 16 ссылок.

INSPECT_ID="$(alti trace inspect --project "$PROJECT" run.altrace | jq -r '.artifact.artifact_id')"
TIMELINE_ID="$(alti trace timeline --project "$PROJECT" run.altrace run.timeline | jq -r '.artifact.artifact_id')"
alti trace review materialize --project "$PROJECT" "$TIMELINE_ID" --reference "$INSPECT_ID" > "$PROJECT/package.json"
jq -r '.schema' "$PROJECT/package.json"
PACKAGE_ID="$(jq -r '.package_id' "$PROJECT/package.json")"
altifigence.trace.review-package-summary.v1

Убедитесь, что код завершения равен 0. package_id — это trace-review: с последующими 64 шестнадцатеричными символами в нижнем регистре. list выводит не более 5 сводок пакетов, сначала самые новые. show выводит одну сводку с package_sha256 и byte_length. readback сверяет сохранённый пакет с сохранёнными артефактами и выводит полный пакет.

alti trace review list --project "$PROJECT" | jq 'length'
alti trace review show --project "$PROJECT" "$PACKAGE_ID" | jq -r '.schema'
alti trace review readback --project "$PROJECT" "$PACKAGE_ID" \
  | jq -c '{schema, references: (.reference_artifacts | length), operation: .trace_artifact.operation_id}'
1
altifigence.trace.review-package-summary.v1
{"schema":"altifigence.trace.review-package.v1","references":1,"operation":"altifigence.trace.timeline.v1"}

Первая строка равна 1, если в проекте нет других пакетов проверки.

Действия при типичных сбоях

alti-trace выводит error: <message> и завершается с кодом 2. alti возвращает тот же код завершения и добавляет в stderr строку состояния, содержащую exit=2.

Если путь к трассе не найден, выводится:

error: cannot read missing.altrace: No such file or directory (os error 2)

Выведите список содержимого каталога проекта и передайте путь к трассе относительно --project.

ls "$PROJECT"

Если файл не является трассой, выводится сообщение ниже. Передайте файл, который начинается с ALTR, например run.altrace.

printf 'this is not a trace\n' > "$PROJECT/notes.txt"
alti trace inspect --project "$PROJECT" notes.txt
error: cannot decode trace 'notes.txt': invalid .altrace magic

Если идентификатор не был сохранён в этом проекте, materialize выводит сообщение ниже. Скопируйте .artifact.artifact_id из запуска inspect, timeline или export с тем же --project.

error: owned trace artifact not found

Идентификатор неверного вида, повторяющийся идентификатор или более 16 ссылок приводят к выводу сообщения ниже. Идентификатор трассы или ссылки начинается с trace:altifigence.trace., а идентификатор пакета — это trace-review: с последующими 64 шестнадцатеричными символами в нижнем регистре. Копируйте каждый идентификатор без изменений из команды, которая его вывела, и указывайте каждый по одному разу.

error: invalid trace review request

Если каталоги хранилища доступны группе или другим пользователям, каждая команда trace, которая сохраняет или читает результаты, выводит сообщение ниже. Сделайте хранилище закрытым для всех, кроме вас.

error: trace review store unavailable
chmod -R go-rwx "$PROJECT/.altifigence"

Команды движков CLI