zx_profile_create

摘要

建立排程器設定檔。

宣告

#include <zircon/syscalls.h>

zx_status_t zx_profile_create(zx_handle_t profile_rsrc,
                              uint32_t options,
                              const zx_profile_info_t* profile,
                              zx_handle_t* out);

說明

zx_profile_create() 會建立新的 profile 物件。

profile 參數會指定設定檔中的設定，進而套用至呼叫 zx_object_set_profile() 時的執行緒。個人資料的欄位如下所示。選項必須為零。

#define ZX_PROFILE_INFO_FLAG_PRIORITY (1 << 0)
#define ZX_PROFILE_INFO_FLAG_CPU_MASK (1 << 1)
#define ZX_PROFILE_INFO_FLAG_DEADLINE (1 << 2)
#define ZX_PROFILE_INFO_FLAG_NO_INHERIT (1 << 3)
#define ZX_PROFILE_INFO_FLAG_MEMORY_PRIORITY (1 << 4)
#define ZX_PROFILE_INFO_FLAG_CRITICAL (1 << 5)

typedef struct zx_profile_info {
  // A bitmask of ZX_PROFILE_INFO_FLAG_* values. Controls overall profile
  // options as well as determining which other fields below have been specified.
  // Other fields are considered unset.
  uint32_t flags;

  uint8_t padding1[4];

  union {
    struct {
      // Scheduling priority. |flags| must have ZX_PROFILE_INFO_FLAG_PRIORITY or
      // ZX_PROFILE_INFO_FLAG_MEMORY_PRIORITY set.
      int32_t priority;
      uint8_t padding2[20];
    };

    // Scheduling deadline. |flags| must have ZX_PROFILE_INFO_FLAG_DEADLINE set.
    zx_sched_deadline_params_t deadline_params;
  };

  // CPUs that threads may be scheduled on. |flags| must have
  // ZX_PROFILE_INFO_FLAG_CPU_MASK set.
  zx_cpu_set_t cpu_affinity_mask;
} zx_profile_info_t;

flags 欄位可控制整體設定檔選項，並指定 zx_profile_info_t 結構中的哪些欄位含有有效值。如果欄位沒有對應的 flag 位元集，系統就會忽略欄位中的值。這樣一來，即使日後新增其他欄位，系統也能區分值為 0 的欄位和未設定的欄位。

ZX_PROFILE_INFO_FLAG_PRIORITY 和 ZX_PROFILE_INFO_FLAG_DEADLINE 會指定設定檔的 scheduling discipline，可以是「公平調度」(適用於 PRIORITY) 或「期限調度」(適用於 DEADLINE)。一次最多只能選取其中一個學科。

ZX_PROFILE_INFO_FLAG_CRITICAL (選擇性) 修改 ZX_PROFILE_INFO_FLAG_DEADLINE，指出期限代表應放在獨立重要期限執行佇列的重要工作。重要期限設定檔等待器會將重要旗標傳播至所封鎖 futex 的擁有者。

只有在提供 ZX_PROFILE_INFO_FLAG_DEADLINE 時才有效。

ZX_PROFILE_INFO_FLAG_MEMORY_PRIORITY 可建立設定檔並套用至 VMAR，且與任何排程相關的標記不相容。選取記憶體優先順序時，目前只有 ZX_PRIORITY_DEFAULT 和 ZX_PRIORITY_HIGH 有意義，前者是所有 VMAR 最初的預設值，後者則表示應避免對設定檔套用的物件啟動所有核心回收作業。

根據預設，設定檔會參與設定檔繼承作業，前提是設定檔已指派給在 futex 中遭到封鎖的執行緒，且該執行緒已指派擁有者 (請參閱 zx_futex_wait())。使用 ZX_PROFILE_INFO_FLAG_NO_INHERIT 建立的設定檔則不會參與設定檔繼承作業。當指派這類設定檔的執行緒在 futex 中遭到封鎖 (且 futex 有擁有者)，futex 的擁有者不會直接受到封鎖執行緒的設定檔壓力 (但可能會受到封鎖執行緒後方封鎖的另一個執行緒壓力)。

Deadline 設定檔一律必須可繼承。嘗試建立不可繼承的期限設定檔時，會因 ZX_ERR_INVALID_ARGS 而失敗。

成功後，系統會傳回新設定檔的控制代碼。

權限

profile_rsrc 必須具有資源種類 ZX_RESOURCE_KIND_SYSTEM，且基底為 ZX_RSRC_SYSTEM_PROFILE_BASE。

呼叫端工作政策必須允許 ZX_POL_NEW_PROFILE。

傳回值

成功時，會傳回 ZX_OK 和新設定檔的控制代碼 (透過 out)。如果失敗，系統會傳回負數錯誤值。

錯誤

ZX_ERR_BAD_HANDLE profile_rsrc 不是有效的控制代碼。

ZX_ERR_ACCESS_DENIED profile_rsrc 不是設定檔資源。

ZX_ERR_INVALID_ARGS 您提供的一或多個引數無效：

• profile 或 out 是無效指標
• flags 包含不明選項
• 旗標未指定排程規範、CPU 親和性遮罩或記憶體優先順序。
• flags 一次指定多個排程規範。
• 旗標將排程規範指定為期限，但設定檔也標示為「no inherit」。
• 標記指定了排程規範和記憶體優先順序。
• flags 指定了重要標記，但未指定期限規範。
• 選項不為零
• priority 是無效的優先順序

ZX_ERR_NO_MEMORY 記憶體不足，導致失敗。

另請參閱

• zx_object_set_profile()
• zx_futex_wait()