編譯快取

從 Android 10 開始，Neural Networks API (NNAPI) 提供函式，可支援編譯構件快取，進而縮短應用程式啟動時所需的編譯時間。使用這項快取功能後，驅動程式就不需要管理或清除快取檔案。這是可透過 NN HAL 1.2 實作的選用功能。如要進一步瞭解這個函式，請參閱 ANeuralNetworksCompilation_setCaching。

驅動程式也可以實作不受 NNAPI 影響的編譯快取。無論是否使用 NNAPI NDK 和 HAL 快取功能，都可以實作這項功能。AOSP 提供低階公用程式庫 (快取引擎)。詳情請參閱「實作快取引擎」。

工作流程總覽

本節將說明實作編譯快取功能的一般工作流程。

提供快取資訊並命中快取

  1. 應用程式會傳遞快取目錄和模型專屬的總和檢查碼。
  2. NNAPI 執行階段會根據總和檢查碼、執行偏好設定和區隔結果，尋找快取檔案。
  3. NNAPI 會開啟快取檔案，並透過 prepareModelFromCache 將句柄傳遞至驅動程式。
  4. 驅動程式會直接從快取檔案準備模型，並傳回已準備的模型。

提供快取資訊和在快取中找不到所需資料

  1. 應用程式會傳遞模型和快取目錄的專屬總和檢查碼。
  2. NNAPI 執行階段會根據總和檢查碼、執行偏好設定和區隔結果，尋找快取檔案，但找不到快取檔案。
  3. NNAPI 會根據總和檢查碼、執行偏好設定和分割作業，建立空白快取檔案、開啟快取檔案，並透過 prepareModel_1_2 將句柄和模型傳遞至驅動程式。
  4. 驅動程式會編譯模型、將快取資訊寫入快取檔案，並傳回已準備好的模型。

未提供快取資訊

  1. 應用程式會在未提供任何快取資訊的情況下叫用編譯作業。
  2. 應用程式不會傳遞任何與快取相關的內容。
  3. NNAPI 執行階段會使用 prepareModel_1_2 將模型傳遞至驅動程式。
  4. 驅動程式會編譯模型，並傳回已準備好的模型。

快取資訊

提供給驅動程式的快取資訊包含符記和快取檔案句柄。

憑證

權杖是長度為 Constant::BYTE_SIZE_OF_CACHE_TOKEN 的快取權杖，用於識別已準備的模型。使用 prepareModel_1_2 儲存快取檔案，並使用 prepareModelFromCache 擷取已準備的模型時，系統會提供相同的符記。驅動程式的用戶端應選擇衝突率低的符記。驅動程式無法偵測符記衝突。衝突會導致執行作業失敗，或執行作業成功但產生不正確的輸出值。

快取檔案句柄 (兩種快取檔案)

兩種快取檔案分別是資料快取和模型快取。

  • 資料快取：用於快取常數資料，包括經過預處理和轉換的張量緩衝區。修改資料快取時，除了在執行期間產生不良的輸出值，不應造成任何其他負面影響。
  • 模型快取：用於將安全性敏感資料 (例如已編譯的機器碼) 快取至裝置的原生二進位格式。修改模型快取可能會影響驅動程式的執行行為，而惡意用戶端可能會利用這項功能，超出授予的權限執行操作。因此，驅動程式必須先檢查模型快取是否已損毀，再從快取中準備模型。詳情請參閱「安全性」。

驅動程式必須決定如何在兩種快取檔案類型之間分配快取資訊，並使用 getNumberOfCacheFilesNeeded 回報每個類型需要多少快取檔案。

NNAPI 執行階段一律會以讀取和寫入權限開啟快取檔案句柄。

安全性

在編譯快取作業中，模型快取可能會包含安全性敏感資料，例如以裝置原生二進位格式編譯的機器碼。如果未妥善保護，修改模型快取可能會影響驅動程式的執行行為。由於快取內容會儲存在應用程式目錄中，因此用戶端可以修改快取檔案。有瑕疵的用戶端可能會意外損毀快取，而惡意用戶端可能會故意利用這一點，在裝置上執行未經驗證的程式碼。視裝置特性而定，這可能會造成安全性問題。因此，驅動程式必須能夠在從快取中準備模型之前，先偵測潛在的模型快取毀損情形。

其中一種做法是讓驅動程式維護從權杖到模型快取的加密雜湊的對應項目。驅動程式可在將編譯內容儲存至快取時，儲存其模型快取的符記和雜湊。當驅動程式從快取中擷取編譯作業時，會使用已記錄的符記和雜湊值配對，檢查模型快取的新雜湊值。這項對應應在系統重新啟動時持續存在。驅動程式可以使用 Android 金鑰庫服務、framework/ml/nn/driver/cache 中的公用程式庫，或任何其他適當的機制來實作對應管理工具。在驅動程式更新時，應重新初始化這個對應管理工具，以免準備舊版的快取檔案。

為避免時間檢查到使用時間 (TOCTOU) 攻擊，驅動程式必須在將記錄的雜湊值儲存至檔案前計算，並在將檔案內容複製到內部緩衝區後計算新的雜湊值。

以下程式碼範例說明如何實作此邏輯。

bool saveToCache(const sp<V1_2::IPreparedModel> preparedModel,
                 const hidl_vec<hidl_handle>& modelFds, const hidl_vec<hidl_handle>& dataFds,
                 const HidlToken& token) {
    // Serialize the prepared model to internal buffers.
    auto buffers = serialize(preparedModel);

    // This implementation detail is important: the cache hash must be computed from internal
    // buffers instead of cache files to prevent time-of-check to time-of-use (TOCTOU) attacks.
    auto hash = computeHash(buffers);

    // Store the {token, hash} pair to a mapping manager that is persistent across reboots.
    CacheManager::get()->store(token, hash);

    // Write the cache contents from internal buffers to cache files.
    return writeToFds(buffers, modelFds, dataFds);
}

sp<V1_2::IPreparedModel> prepareFromCache(const hidl_vec<hidl_handle>& modelFds,
                                          const hidl_vec<hidl_handle>& dataFds,
                                          const HidlToken& token) {
    // Copy the cache contents from cache files to internal buffers.
    auto buffers = readFromFds(modelFds, dataFds);

    // This implementation detail is important: the cache hash must be computed from internal
    // buffers instead of cache files to prevent time-of-check to time-of-use (TOCTOU) attacks.
    auto hash = computeHash(buffers);

    // Validate the {token, hash} pair by a mapping manager that is persistent across reboots.
    if (CacheManager::get()->validate(token, hash)) {
        // Retrieve the prepared model from internal buffers.
        return deserialize<V1_2::IPreparedModel>(buffers);
    } else {
        return nullptr;
    }
}

進階用途

在某些進階用途中，驅動程式需要在編譯呼叫後存取快取內容 (讀取或寫入)。用途範例包括：

  • 即時編譯：編譯作業會延後至第一次執行時才進行。
  • 多階段編譯：系統會先執行快速編譯，然後視使用頻率而定，選擇性執行最佳化編譯。

如要在編譯呼叫之後存取快取內容 (讀取或寫入)，請確保驅動程式符合下列條件：

  • 在 prepareModel_1_2 或 prepareModelFromCache 的叫用期間複製檔案控制代碼，並稍後讀取/更新快取內容。
  • 在一般編譯呼叫之外實作檔案鎖定邏輯，以免寫入作業與讀取或其他寫入作業同時發生。

實作快取引擎

除了 NN HAL 1.2 編譯快取介面，您也可以在 frameworks/ml/nn/driver/cache 目錄中找到快取公用程式庫。nnCache 子目錄包含持久性儲存空間程式碼，可讓驅動程式在不使用 NNAPI 快取功能的情況下，實作編譯快取功能。這類編譯快取功能可使用任何版本的 NN HAL 實作。如果驅動程式選擇實作與 HAL 介面中斷的快取，則在不再需要快取的構件時，驅動程式會負責釋放這些構件。