Перейти до основного вмісту

Контракт MPK

Цей документ визначає офіційний договір щодо завантаження даних в архів моделей і розбору контракту MPK.

Обсяг​

Дія цього договору поширюється на:

  • src/model/ModelPack.cpp
  • src/model/ModelArchiveLoader.cpp
  • src/model/internal/ModelArchiveLoader.h
  • src/pipeline/internal/sima/MpkContract.cpp
  • src/pipeline/internal/sima/static_contract/MpkDecoder.cpp

Підтримуваний формат архіву.​

Підтримуваний формат розширення пакета: лише точна відповідність, усі літери в нижньому регістрі .tar.gz. .mpk, .tgz, .tar і простий .gz відхиляються до перевірки архіву.

Вимоги до архіву:

  • Архів має бути доступним для читання у форматі tar.
  • Розмір архіву має бути меншим або рівним значенню max_archive_bytes, яке налаштовано в завантажувачі.
  • Кількість записів не повинна перевищувати значення, встановлене в налаштуваннях завантажувача: max_entries.
  • Розмір корисного навантаження запису має бути меншим або рівним значенню max_entry_bytes, яке налаштовано в завантажувачі.

Допустима схема розміщення​

Для розпакування приймаються лише звичайні файли. Записи про каталоги дозволені, але ігноруються.

Дозволені типи файлів для розпакування:

  • Файли конфігурації у форматі JSON (*.json) -> вилучені в etc/.
  • Загальні об’єкти (*.so) -> вилучено в lib/.
  • Виконані файли ELF (*.elf) -> вилучено в share/.

Необхідний перелік компонентів у комплекті:

  • Контракт для виконання висновків MPK (mpk.json або *_mpk.json).
  • JSON-файл зі стадією/конфігурацією для завантажувача, необхідний для середовища виконання.
  • Принаймні один бінарний артефакт моделі (*.elf або *.so).

Завантаження маніфесту MPK​

Завантаження моделі, побудова підготовленого середовища виконання та хост PCIe читають mpk.json через MpkDecoder::load. Вона один раз читає маніфест, будує з цих байтів семантичний MpkContract і знаходить виконувані файли кожного етапу всередині пакета: виконувані файли MLA — у share/, у lib/, потім у корені пакета; модулі A65 — у lib/, у корені пакета, потім у share/. Допуск до виконання та хост PCIe декодують ті самі байти з доказами ELF і GraphExecutor виконуваних файлів, тому план і контракт будуються з тих самих байтів.

Правила безпеки під час видобувних робіт​

У разі збою процес вилучення має завершуватися з блокуванням.

Недопустимі варіанти шляху:

  • Абсолютні шляхи (наприклад, /etc/passwd)
  • Сегменти обходу (..)
  • Префікси дисків Windows (C:)
  • Різні форми обходу змішаного роздільника (..\\, ..//).
  • Недійсні байти шляху у кодуванні UTF-8.
  • Символи Unicode, які можна сплутати (наприклад, пряма коса риска/зворотна коса риска: U+FF0F, U+2215, U+FF3C).
  • Символи Unicode, що візуально схожі на крапку і використовуються в шляхах, подібних до тих, що застосовуються для навігації (наприклад, U+FF0E, U+2024, U+FE52).

Типи записів, які не були прийняті:

  • Записи символічних посилань
  • Записи про жорсткі посилання
  • Записи про пристрої.
  • Записи за принципом «першим прийшов – першим пішов»

Характеристики екстракції:

  • Ніколи не вказуйте шляхи до архівів безпосередньо у вихідних шляхах файлової системи.
  • Спочатку нормалізуйте та перевірте правильність шляху до елемента архіву.
  • Вилучіть затверджені записи за певним типом контенту та помістіть їх у спеціальну тимчасову теку.
  • Ніколи не дозволяйте здійснювати записи за межами кореневої директорії для вилучення даних.
  • Дублікати нормалізованих шляхів до архівів у форматі tar відхиляються, оскільки вони є invalid_archive.
  • Пошкодження заголовка/контрольної суми архіву призводить до відхилення, і архів позначається як invalid_archive.

Перевірка JSON та послідовностей​

pipeline_sequence.json має відповідати наступним вимогам:

  • Об’єкт JSON з непустим масивом pipelines.
  • Перший об’єкт у конвеєрі повинен містити непустий масив sequence.
  • Кожна заявка на участь у етапі має містити:
    • sequence_id (ціле число)
    • name (непорожній рядок)
    • pluginId (непорожній рядок)
    • configPath (непорожній рядок)
    • processor (непорожній рядок)
    • kernel (непорожній рядок)
  • Повторювані назви етапів не приймаються.
  • Повторювані ключі JSON не допускаються.
  • Вкладеність JSON-структури на глибину, що перевищує значення max_json_depth, не підтримується.
  • Непідтримувані значення kernel відхиляються.
  • Залежності між етапами в input повинні посилатися лише на:
    • decoder, або
    • попередні назви етапів після встановлення стабільного порядку.

Таксономія помилок​

Усі випадки невдалого завантаження даних з архіву моделей або згідно з контрактом MPK мають бути класифіковані відповідно до однієї з наведених нижче категорій:

  • invalid_archive
  • path_traversal
  • schema_error
  • unsupported_version
  • size_limit_exceeded

Публічні повідомлення про помилки повинні містити ключ таксономії, щоб тести могли підтверджувати детерміновану класифікацію.

Вимоги до детермінізму​

  • Послідовність виконання має бути детермінованою під час повторних запусків.
  • Архівні файли з тестовими даними, що зберігаються за адресою tests/assets/mpk, повинні бути повністю відтворюваними, тобто кожен біт даних має відповідати оригіналу.
  • Згенеровані контрольні суми файлу маніфесту фікстур за адресою test-assets/model-archive/fixtures_manifest.json є основним джерелом інформації для фікстур безпеки структури збірки.

Вимоги до тестування відображення​

Кожен негативний тест, що проводиться для моделі-архіву/контракту MPK, має підтверджувати наявність одного з наведених вище ключових термінів таксономії.