Fuchsia.sysmem

添加时间：7

协议

分配器

在 fuchsia.sysmem/allocator.fidl 中定义

分配系统内存缓冲区。

已弃用：23 添加：7

AllocateNonSharedCollection

代表单个客户端（也称为发起者）分配 BufferCollection （从 sysmem 的角度来看）。

此调用主要用于临时/测试目的。此调用会跳过 BufferCollectionToken 阶段，因此 指定其约束条件。

建议真实客户端改用 AllocateSharedCollection()， 并让相关参与者直接表达他们对 sysmem.

collection_request 是 BufferCollection FIDL 的服务器端 。客户端可以调用 SetConstraints()，然后 此渠道的客户端上的 WaitForBuffersAlality() 以指定 然后确定成功/失败情况，并获取 BufferCollectionInfo_2。客户还应 在使用 BufferCollection，并且应在此通道关闭和停止时注意 你应该尽快使用 BufferCollection

请求

名称类型
collection_request server_end<BufferCollection>

AllocateSharedCollection

创建可与其之间共享的逻辑 BufferCollectionToken （使用 BufferCollectionToken.Duplicate()），然后再 转换为 BufferCollection。

使用缓冲区填充 BufferCollection 成功/失败 通过 BufferCollection 接口确定的。

请求

名称类型
token_request server_end<BufferCollectionToken>

BindSharedCollection

将 BufferCollectionToken 转换为与 BufferCollection.BufferCollection 中尚未填充 缓冲区 - 参与者还必须通过 客户端缓冲区返回。

所有 BufferCollectionToken 通过 AllocateSharedCollection() 创建的 BufferCollectionToken 必须 在逻辑 BufferCollection 之前通过 BindSharedCollection() 上交 将填充缓冲区

token，表示其服务器端已发送到的渠道的客户端端点 使用 AllocateSharedCollection 或服务器端被发送到的系统内存 使用 BufferCollectionToken.Duplicate() 实现系统内存。正在生成 “换货”将某个通道传递到逻辑 BufferCollection。

buffer_collection_request：BufferCollection 的服务器端 。发送者照常保留客户端。通过 BufferCollection 通道是单个参与者与 逻辑 BufferCollection。通常会有其他参与者 与自己的 BufferCollection 通道相连接，以连接到逻辑 BufferCollection。

请求

名称类型
token BufferCollectionToken
buffer_collection_request server_end<BufferCollection>

ConnectToSysmem2Allocator

这将允许在给定 sysmem(1) 的情况下创建 sysmem2 Allocator Allocator。

这主要在以下情形下非常有用：库代码收到一个 sysmem(1) 分配器，但库代码已更新为使用 sysmem2。通常，该库会提供一种在 sysmem2 中传入 sysmem2 的方法。 Allocator，但客户端代码并不总是位于同一代码库中，因此 此消息允许库仍然接受 sysmem(1) 分配器 临时性。

通过 SetDebugClientInfo 设置的信息（如果有）会复制到 sysmem2 中 Allocator。

已弃用：23 添加：20

请求

名称类型
allocator_request server_end<fuchsia.sysmem2/Allocator>

SetDebugClientInfo

将有关 sysmem 可以使用的当前客户端的信息设置为 帮助调试泄漏内存并挂起以等待约束。|name|罐 是任意字符串，但使用当前进程名称（请参阅 fsl::GetCurrentProcessName()）是一个很好的默认值。|id|可以是 任意 ID，使用当前进程 ID（请参阅 fsl::GetCurrentProcessKoid()) 是一个很好的默认值。

此信息会传播到使用 BindSharedCollection() 或 AllocateNonSharedCollection() 分配器。它不会影响 BufferCollectionTokens，因为它们 往往会跨进程传递，因此应手动管理其名称。

请求

名称类型
name string[64]
id uint64

ValidateBufferCollectionToken

验证系统内存服务器是否知道 BufferCollectionToken。

这可用于在不会调用 BindSharedCollection() 的情况下 直到 BufferCollectionToken.Duplicate() + BufferCollectionToken.Sync()，当客户端代码想要提前知道 传入的令牌是否有效（到目前为止）。

对未知的令牌调用 BufferCollectionToken.Sync() 系统内存存在导致 Sync() 永久挂起的风险。

考虑到传入的令牌可能随时失效（如果有） 参与者丢弃其 BufferCollectionToken 或 BufferCollection； 建议客户端代码作者不要调用 验证 BufferCollectionToken()，并改为处理异步失败 会调用 BufferCollection.Sync() BufferCollectionToken.Duplicate() 和 BindSharedCollection()（在 将任何重复的令牌发送到其他进程）。

无论此调用的结果如何，此调用对 包含所引用 koid 的令牌。

此调用的真实结果并不能保证令牌 在之后的任何期限内有效。

客户端代码将对客户端的令牌句柄执行 zx_object_get_info()， 传递 ZX_INFO_HANDLE_BASIC 并获得 related_koid 然后将其传递给 VerifyBufferCollectionToken()。

如果 ValidBufferCollectionToken() 返回 true，则令牌在 系统内存服务器处理调用的时间，但可能不再是 在客户端代码收到响应时有效/已知。

如果 ValidBufferCollectionToken() 返回 false，则表示令牌未知 系统内存服务器处理调用时发送的数据，但令牌可能 在客户端代码收到响应时获知。不过， 来降低令牌 令牌的来源应该已同步 在将令牌发送到客户端代码之前，先将令牌发送到 sysmem。

如果调用 VerifyBufferCollectionToken() 以某种方式失败，则 是 FIDL 层中的 zx_status_t。

token_server_koid：可能 是 BufferCollectionToken 渠道。该 ID 可通过 zx_object_get_info() ZX_INFO_HANDLE_BASIC related_koid。

请求

名称类型
token_server_koid zx/Koid

响应

名称类型
is_known bool

BufferCollection

在 fuchsia.sysmem/collection.fidl 中定义

BufferCollection 是直接从参与者到系统内存的连接。 逻辑 BufferCollection；逻辑缓冲区集合通常是共享的 与其他参与者共享换句话说，该 BufferCollection 实例 接口是“逻辑缓冲区集合”的视图。

此连接是为了方便异步指示逻辑 已用缓冲区填充 BufferCollection。

此外，服务器关闭通道可向客户端表明 客户端应关闭从 BufferCollection。

另外，此接口将来可能会允许指定 并且可能会允许就某些 学位。

此接口将来可能允许每个虚拟机拥有超过 64 个 VMO 句柄 BufferCollection，但目前上限为 64。

此接口将来可能会允许分配/取消分配单个 缓冲区。

一些发起者可能会等待一小段时间，直到所有旧逻辑 BufferCollection VMO 句柄已关闭（或直到运行时间较短） 之前分配新的 BufferCollection 来帮助控制 内存碎片化，并避免对 旧集合和新集合合集的规模足够大，物美价廉 避免分配重叠（在时间上）。

已弃用：23 添加：7

AttachLifetimeTracking

AttachLifetimeTracking:

AttachLifetimeTracking() 用于允许客户端等待 旧逻辑缓冲区收集 尝试分配新的逻辑缓冲区集合。

将事件对端点附加到逻辑缓冲区集合，以便 当分配的缓冲区数时，server_end 将被关闭 会减少到“buffers_remaining”。server_end 在以下时间后才会关闭： 逻辑分配已完成。

如果逻辑分配失败，例如对于附加的子树（使用 AttachToken()），在发生故障期间，server_end 将关闭，无论 整个逻辑路径中可能会分配的缓冲区数 缓冲区收集。

由此事件发出的生命周期包括对 分配的缓冲区，并且这种异步清理只能在所有 缓冲区的 VMO 句柄的持有者已关闭这些 VMO 句柄。 因此，客户端应小心谨慎，不要一直等待 ZX_EVENTPAIR_PEER_CLOSED 发出信号，尤其是当任何 使用逻辑缓冲区集合的参与者的可信度较低或 可靠性降低。

缓冲区_remaining 参数允许等待除 Buffers_remaining 缓冲区的缓冲区，以待完全取消分配。这对于 在刻意不指定已知数量的缓冲区的情况下 以便继续使用这些数据，例如将 界面中显示的最后一张可用视频图片， 视频流使用了受保护的输出缓冲区。不在 BufferCollection 接口（至少目前是这样）来确定 缓冲区可能不会关闭，但通常位于 0-2。

此机制旨在与提供 一个类似的 AttachLifetimeTracking() 机制，在该机制中， 可以将同一个事件发送到多个 AttachLifetimeTracking()，并且 在所有有效期内，ZX_EVENTPAIR_PEER_CLOSED 的生命周期 超过 个条件（所有重复项的持有者均已关闭 标识名）。

您无法取消连接。客户端结束 事件对不会从待处理连接数中减去。

关闭客户端不会导致服务器执行任何操作。 如果服务器监听到来自客户端的事件， 仅限调试日志记录。

服务器故意不“信任”任何由 客户端。此机制有意仅使用 ZX_EVENTPAIR_PEER_CLOSED 此方法无法过早触发，且仅在所有句柄都被触发时 到 server_end 的通信已关闭。与上述任何字段均无关联。 其他信号位，客户端在功能上应忽略任何其他信号， 事件对两端或其对等端上的信号位。

server_end 可能缺少 ZX_RIGHT_SIGNAL 或 ZX_RIGHT_SIGNAL_PEER， 必须具有 ZX_RIGHT_DUPLICATE（并且必须具有 ZX_RIGHT_TRANSFER 才能 传输，而不会导致 CodecFactory 通道故障）。

请求

名称类型
server_end handle<eventpair>
buffers_remaining uint32

AttachToken

创建新令牌，用于尝试将新参与者添加到现有令牌 如果现有集合的缓冲区计数、约束条件、 且参与者允许。

这对于替换失败的参与者和/或 缓冲结束后添加/重新添加参与者 已分配。

附加的令牌 / 收集失败不会传播到 附加令牌的父级。失败会从常规 可分配令牌的子项分配给一次性令牌。失败 如果附加了子级，则阻止其到达其父级， 或者，如果子级是可饮用的，并且故障是在合理的时间之后发生的， 分配。

在某些情况下，发起者可能会选择在开始时使用一次性的 提供相应的令牌，如果第一个事件发生， 该参与者的实例出现故障，系统会重新生成该参与者的第二个实例， 参与者将获得一个使用 AttachToken() 创建的令牌。

从 BufferCollectionToken 客户端的角度来看 令牌的作用与其他任何令牌一样。客户端可以 可以根据需要复制令牌，并且可以将令牌发送给其他 过程。令牌应转换为 BufferCollection 通道 调用 BindSharedCollection() 以照常操作。SetConstraints() 应该 该 BufferCollection 通道上调用该方法。

WaitForBuffersAlality() 的成功结果意味着新的 参与者的约束条件使用现有的 缓冲区收集，已经建立的 BufferCollectionInfo 包括图片格式限制，以及 参与者数量及其缓冲区计数。失败结果意味着新的 参与者的局限性。 缓冲区收集及其已逻辑分配的参与者。 如果改为创建新的收藏集，则可能会允许所有参与者 要满足约束条件，假设使用 SetDispensable() 或使用普通令牌。

使用 AttachToken() 创建的令牌通过 当前对缓冲区收集有效的所有约束条件，加上 正在考虑的附加令牌加上附件下的子令牌 令牌本身不是附加的令牌，也不在此类令牌之下。

对 min_buffer_count_for_camping 等的缓冲区计数分配为 “先到先得”，但子级无法按照逻辑进行分配， 它的所有父级都发送了 SetConstraints()。

另请参阅 SetDispensable()，它与 AttachToken() 相反，其具有 已创建的词元 + 子词同时参与约束条件汇总 与其父项相关联。

需要将新创建的令牌 Sync() 到 sysmem，然后再创建新令牌 可以传递给 BindSharedCollection()。新应用的 Sync() 可以使用此容器上的 BufferCollection.Sync() 来实现 BufferCollection.也可以在新的 同样有效。可以先后启动 BufferCollectionToken.Sync() 通过 以便将这些额外的令牌也同步到 sysmem 使用一次往返行程

这些值为 Rights_attenuation_mask 不会削弱（请注意， 0 不在此列表中；0 将向系统日志输出 ERROR 帮助诊断客户端代码中的错误）：

  • ZX_RIGHT_SAME_RIGHTS（首选）
  • 0xFFFFFFFF（在计算衰减掩码时这很合理）

请求

名称类型
rights_attenuation_mask uint32
token_request server_end<BufferCollectionToken>

CheckBuffersAllocated

如果 缓冲区收集已分配或失败，或者 ZX_ERR_UNAVAILABLE 如果 WaitForBuffersAlality 阻塞。

请求

<空>

响应

名称类型
status zx/Status

关闭

在 BufferCollectionToken 通道上：

通常，参与者会将 BufferCollectionToken 转换为 BufferCollection 视图，但是参与者也可以自由关闭 令牌（然后立即或稍后在 响应，以免产生逻辑缓冲区 收集失败。通常，令牌通道意外关闭 会导致逻辑缓冲区收集失败（唯一的例外情况是 涉及 AttachToken() 或 SetDispensable() 的情况）。

在 BufferCollection 频道上：

默认情况下，服务器会处理 BufferCollection 的意外故障 使整个逻辑缓冲区收集失败。部分目的在于 如有任何参与者，可加快关闭 VMO 句柄以回收内存 失败。如果参与者想要彻底关闭 BufferCollection 视图，而不会导致逻辑缓冲区收集失败，则参与者 可以在关闭 BufferCollection 的客户端之前发送 Close() 。如果这是最后一个 BufferCollection 视图，则此逻辑缓冲区为 仍会遭到停用Close() 可发生在 SetConstraints() 指定的约束条件。如果先于 SetConstraints()， 无需具有此节点的约束条件即可分配。如果 在 SetConstraints() 之后，系统会保留并汇总约束条件 以及任何后续逻辑分配，即使没有 。

在 BufferCollectionTokenGroup 通道上：

默认情况下，BufferCollectionTokenGroup 出现意外故障时 触发逻辑 BufferCollectionTokenGroup 的故障，并将 将失败传播到其父级。关闭 BufferCollectionTokenGroup 而不会出现逻辑组故障或不传播故障的情况，则发送 Close()，然后再关闭通道客户端端点。

如果 Close() 出现在 AllChildrenPresent() 之前，则逻辑缓冲区 尽管调用了 Close()，回收仍然会失败（因为 sysmem 不能 是否创建了所有相关的子项，因此会产生含糊不清的 是否会将所有相关约束条件提供给 sysmem）。如果 Close() 发生在 AllChildrenPresent() 之后，子级及其所有子级 约束条件保持不变（就像 BufferCollectionTokenGroup 渠道一直保持打开状态），而关闭 不会触发或传播失败。

请求

<空>

GetAuxBuffers

已移除：23 已弃用：9

请求

<空>

响应

名称类型
status zx/Status
buffer_collection_info_aux_buffers BufferCollectionInfo_2

GetNodeRef

这会获取一个事件句柄，该事件句柄可用作 在任何节点上调用 IsAlternateFor()。客户不会获得 因为此标识名只能用作证据 客户端从该节点获取此句柄的个数。

由于这是 get 方法，因此在 GetNodeRef() 和 IsAlternateFor() 调用，尽管进行了两次调用 可能位于不同的频道上

另请参阅 IsAlternateFor()。

请求

<空>

响应

名称类型
node_ref handle<event>

IsAlternateFor

这将检查调用节点是否位于根位于 公共父 BufferCollectionTokenGroup 的不同子令牌， 与传入的 node_ref 相关联。

此通话用于协助执行准入控制去重，以及 以及调试。

必须使用节点的 GetNodeRef() 获取 node_ref BufferCollectionToken、BufferCollection 或 BufferCollectionTokenGroup。

node_ref 可以是重复的句柄；因此无需调用 每次调用 IsAlternateFor() 时，返回 GetNodeRef()。

如果调用令牌实际上可能根本不是有效令牌， 令牌的可能恶意/不可信的提供商，调用 先验证 BufferCollectionToken()，而不是尽可能地 如果 IsAlternateFor() 因调用而未响应，则无限期卡住 令牌不是真实令牌（并非真正与 sysmem 通信）。另一个 首先使用此令牌调用 BindSharedCollection 验证令牌并将其转换为 BufferCollection，然后 会调用 BufferCollection IsAlternateFor()。

错误值：

ZX_ERR_NOT_FOUND 表示在同一逻辑节点中找不到 node_ref 缓冲区收集。在进行逻辑分配和 同一逻辑分配子树中，这实质上意味着 node_ref 从来不是此逻辑缓冲区集合的一部分，因为 在逻辑分配之前，所有存在的 node_ref 都会保留 至少存在，直到进行逻辑分配（包括 执行 Close() 并关闭其频道）后，对于 ZX_ERR_NOT_FOUND 此节点的频道仍需要连接到服务器 前提是整个逻辑分配都具有 已失败。在逻辑分配之后或在其他逻辑分配中 子树中，还有其他可能的原因会导致此错误。对于 一个不同的逻辑分配示例（与此节点分隔） AttachToken() 或 SetDispensable() 进行逻辑分配）可能会导致其 子树删除这些节点，或者 BufferCollectionTokenGroup 可能会选择与当前存在的子树不同的子树 node_ref 导致 node_ref 节点被删除。唯一的时间 在节点没有对应的通道后，sysmem 将在该节点周围保留一个节点 表示使用了 Close()，并且节点的子树尚未失败。 导致此错误的另一个原因是，如果 node_ref 是事件对句柄 但实际上不是从 GetNodeRef().

ZX_ERR_INVALID_ARGS 表示调用方传递的 node_ref 不是 事件对处理脚本，或者在真实环境中没有预期所需的权利， node_ref.

此调用不会返回其他失败的状态代码。不过， sysmem 将来可能会添加其他代码，因此客户端应该 对任何失败的状态代码进行合理的默认处理。

成功后，is_alternate 具有以下含义：

  • true - 调用节点和 node_ref 节点是一个 BufferCollectionTokenGroup。这意味着 调用节点和 node_ref 节点不会同时具有它们的 但 sysmem 会选择 约束条件 - 不能两者兼而有之。这是因为 在逻辑分配期间选择了 BufferCollectionTokenGroup， 并且只有一个子树的子树对约束有贡献 汇总。
  • false - 调用节点和 node_ref 节点不是 BufferCollectionTokenGroup。目前， 这意味着共同的第一个父节点是 BufferCollectionToken 或 BufferCollection（无论 Close()ed 或 Close()ed）。这意味着调用节点和 node_ref 节点可以同时在运行期间同时应用这两个约束条件 限制条件汇总的逻辑分配（如果这两个节点） 由任何涉及的父级 BufferCollectionTokenGroup 选择。 在此情况下，不会出现 直接阻止两个节点同时被选中 约束条件均经过汇总，但即使为 false，也汇总了其中一个或两个 如果存在一个或两个节点，这些节点可能仍会被排除在考虑范围之外 节点具有直接或间接父级 BufferCollectionTokenGroup 该方法会选择一个子树，而不是包含 调用 Node 或 node_ref 节点。

请求

名称类型
node_ref handle<event>

响应

名称类型
payload Node_IsAlternateFor_Result

SetConstraints

向逻辑 BufferCollection 提供 BufferCollectionConstraints。

参与者只能调用 SetConstraints() 一次。

有时发起者只是想要参与 使用缓冲区和 zx.Status 填充缓冲区空间，以便观察成功/失败情况 。在这种情况下，has_constraints 可以为 false。 将忽略constraints。

不会向发送 null 的客户端提供 VMO 句柄 如果发起者不需要 VMO 句柄。没有 VMO 句柄不会阻止发起者 调整缓冲区的哪个部分被视为有效且相似， 发起者无法将 VMO 句柄保持打开状态，以防止出现 如果逻辑 BufferCollection 需要 无论发起者的参与程度如何， 无论出于何种原因

对于要尝试的缓冲区填充， BufferCollection 客户端渠道需要先调用 SetConstraints() sysmem 将尝试分配缓冲区。

has_constraints 如果为 false，约束条件实际上为 null，并且 系统会忽略 constraints。null 约束条件的发送方将不会收到任何 VMO 在 BufferCollectionInfo 中进行处理，但仍可以了解 缓冲区已被分配，仍然可以通过它们的 buffer_index.

constraints 是对缓冲区集合的约束条件。

请求

名称类型
has_constraints bool
constraints BufferCollectionConstraints

SetConstraintsAuxBuffers

已移除：23 已弃用：9

请求

名称类型
constraints BufferCollectionConstraintsAuxBuffers

SetDebugClientInfo

将有关 sysmem 可以使用的当前客户端的信息设置为 帮助调试泄漏内存并挂起以等待约束。|name|罐 是任意字符串，但使用当前进程名称（请参阅 fsl::GetCurrentProcessName()）是一个很好的默认值。|id|可以是 任意 ID，使用当前进程 ID（请参阅 fsl::GetCurrentProcessKoid()) 是一个很好的默认值。

也在启用详细日志记录功能时使用（请参阅 SetVerboseLogging()），以 表明是哪个客户最先关闭其渠道，从而导致其 子树故障（如果子树的用途是 但如果比预期更早 客户渠道专用的名称有助于诊断 第一个来源）。

默认情况下（除非被此消息替换或使用 Allocator.SetDebugClientInfo()），那么节点将从其 父节点时创建的键。虽然可以 比没有要好，通常让每个参与者使用 Node.SetDebugClientInfo() 或 Allocator.SetDebugClientInfo() 可保留 与当前客户直接相关的信息。此外，SetVerboseLogging() 有助于消除不确定节点是否有 从其父级复制而来

请求

名称类型
name string[64]
id uint64

SetDebugTimeoutLogDeadline

如果并非所有客户端都设置了限制条件 5 秒，则系统会记录警告 创建集合后客户端可以调用此方法 。如果截止时间由多个客户设定 未指定将生效的截止期限。

请求

名称类型
deadline zx/Time

SetName

为此缓冲区集合中的 VMO 设置名称。名称可能被截断 。名称只会影响设置后分配的 VMO - 此调用 不会重命名现有 VMO。如果多个客户设置了不同的名称 则较大的优先级值将胜出

请求

名称类型
priority uint32
name string[64]

SetVerboseLogging

详细日志记录包括通过 SetConstraints() 设置的限制（从每个 以及通过 SetDebugClientInfo() 设置的信息以及 节点树。

通常，在汇总时，系统仅输出一行投诉 仅显示汇总失败的具体详细原因 提供最基本的信息。虽然这通常足以诊断问题 如果之前只进行了细微的更改并且系统在运行之前 这种微小的改动通常并不足以 缓冲区收集。尤其是 复杂的节点树，涉及 AttachToken()、 SetDispensable()、BufferCollectionTokenGroup 节点以及 节点的树状结构，详细日志记录可能有助于诊断树状结构中 原因、为什么逻辑分配失败， 子树的失败时间早于预期。

额外记录的目的是为了能在演出中获得 （如果仅在少量缓冲区集合上启用）。 如果我们没有跟踪错误，则不应发送此消息。

如果太多参与者保持启用详细日志记录功能，我们可能最终 需要允许系统级系统系统详细日志记录 通过一些其他设置，可避免系统因 此邮件。

对于某些节点，这可能是 NOP，因为这是有意为之关联的政策 日志记录。

请求

<空>

同步

确保之前的消息（包括 令牌、集合或组。

对不是/不是有效令牌的令牌调用 BufferCollectionToken.Sync() 有效的 sysmem 令牌可能会导致 Sync() 永久挂起。请参阅 ValidBufferCollectionToken() 来降低这种可能性 恶意/虚假 BufferCollectionToken，但只能以一次往返为代价。 另一种方法是将令牌传递给 BindSharedCollection()， 在用令牌交换 BufferCollection 时验证令牌 然后可以使用 BufferCollection Sync()。

调用 Sync() 之后，就可以安全地发送 token_request 的客户端一端 如果服务器收到请求后， 会由对方发送到 BindSharedCollection()。

其他选项包括等待每个 token.Duplicate() 完成 单独调用 token.Sync()，或者 上交令牌后，对 BufferCollection 调用 Sync() （通过 BindSharedCollection() 提供）

另一种缓解方法是避免对令牌调用 Sync() 而是稍后处理如果 BufferCollection.Sync() 可能失败， 原始令牌无效。 但需要客户端代码来延迟发送 在客户端代码转换之前，与此令牌复制的令牌 将令牌复制到 BufferCollection，并且成功接收 BufferCollection.Sync() 的响应。

如果可行，最好改用 BufferCollection.Sync()（参见上文）。 当 BufferCollection.Sync() 不可行时，调用方必须已 知道此令牌是有效的，否则 BufferCollectionToken.Sync() 可能会 永远挂起。请参阅 VerifyBufferCollectionToken() 以检查令牌 。

请求

<空>

响应

<空>

WaitForBuffersAllocated

分配缓冲区后，此请求完成，响应为 一些失败详情。

在分配缓冲区之前必须发生以下情况：

  • 逻辑 BufferCollectionToken 的所有 BufferCollectionToken 必须通过 BindSharedCollection() 上交。
  • 逻辑 BufferCollection 的所有 BufferCollection 都必须具有 SetConstraints() 的方法。

如果成功，则返回 ZX_OK。 如果请求有效但无法实现，则返回 ZX_ERR_NO_MEMORY 已因资源耗尽而得到满足 如果调用方无权执行以下操作，则返回 ZX_ERR_ACCESS_DENIED 获取请求的缓冲区。 如果请求的格式不正确，则返回 ZX_ERR_INVALID_ARGS。 如果请求有效但不可行，则返回 ZX_ERR_NOT_SUPPORTED 满意，可能是因为硬件限制。

buffer_collection_info 包含 VMO 句柄和其他相关信息。

请求

<空>

响应

名称类型
status zx/Status
buffer_collection_info BufferCollectionInfo_2

BufferCollectionToken

在 fuchsia.sysmem/collection.fidl 中定义

BufferCollectionToken 不是 BufferCollection，而是一种 在 BufferCollection 之前识别潜在的共享的 BufferCollection 正在分配

我们为 BufferCollectionToken 使用通道，而不是单个事件对 （配对），因为这样我们可以检测参与者等错误情况 在创作过程中死亡。

fuchsia.sysmem.BufferCollectionToken 类型尚未弃用， （目前还在其他协议中使用）， fuchsia.sysmem.BufferCollectionToken 已弃用。令牌通道提供服务 fuchsia.sysmem.BufferCollectionToken 和 fuchsia.sysmem2.BufferCollectionToken。

一旦其他协议将其弃用，此协议将被弃用 令牌字段设置为 fuchsia.sysmem2.BufferCollectionToken。

添加时间：7

关闭

在 BufferCollectionToken 通道上：

通常，参与者会将 BufferCollectionToken 转换为 BufferCollection 视图，但是参与者也可以自由关闭 令牌（然后立即或稍后在 响应，以免产生逻辑缓冲区 收集失败。通常，令牌通道意外关闭 会导致逻辑缓冲区收集失败（唯一的例外情况是 涉及 AttachToken() 或 SetDispensable() 的情况）。

在 BufferCollection 频道上：

默认情况下，服务器会处理 BufferCollection 的意外故障 使整个逻辑缓冲区收集失败。部分目的在于 如有任何参与者，可加快关闭 VMO 句柄以回收内存 失败。如果参与者想要彻底关闭 BufferCollection 视图，而不会导致逻辑缓冲区收集失败，则参与者 可以在关闭 BufferCollection 的客户端之前发送 Close() 。如果这是最后一个 BufferCollection 视图，则此逻辑缓冲区为 仍会遭到停用Close() 可发生在 SetConstraints() 指定的约束条件。如果先于 SetConstraints()， 无需具有此节点的约束条件即可分配。如果 在 SetConstraints() 之后，系统会保留并汇总约束条件 以及任何后续逻辑分配，即使没有 。

在 BufferCollectionTokenGroup 通道上：

默认情况下，BufferCollectionTokenGroup 出现意外故障时 触发逻辑 BufferCollectionTokenGroup 的故障，并将 将失败传播到其父级。关闭 BufferCollectionTokenGroup 而不会出现逻辑组故障或不传播故障的情况，则发送 Close()，然后再关闭通道客户端端点。

如果 Close() 出现在 AllChildrenPresent() 之前，则逻辑缓冲区 尽管调用了 Close()，回收仍然会失败（因为 sysmem 不能 是否创建了所有相关的子项，因此会产生含糊不清的 是否会将所有相关约束条件提供给 sysmem）。如果 Close() 发生在 AllChildrenPresent() 之后，子级及其所有子级 约束条件保持不变（就像 BufferCollectionTokenGroup 渠道一直保持打开状态），而关闭 不会触发或传播失败。

请求

<空>

CreateBufferCollectionTokenGroup

大多数系统内存客户端和许多参与者不需要关注这一点 消息或一般关于 BufferCollectionTokenGroup。

BufferCollectionTokenGroup 用于在 N 个子级之间创建 N 或 1 词元。在汇总过程中未选择的子令牌将 潜在参与者应该注意到的， BufferCollection 通道客户端端点看到 PEER_CLOSED，从而允许 以清理原本未得到的推测性使用， （这类似于正常的 BufferCollection 服务器端关闭 在逻辑缓冲区收集失败时返回）。

请参阅关于 BufferCollectionTokenGroup 协议的注释。

任何需要的权限_attenuation_mask 或 AttachToken()/SetDispensable() 为此，可以使用令牌来实现 作为该群组的直接父级。

group_request - BufferCollectionTokenGroup 通道的服务器端 由 sysmem 处理。

已弃用：23 添加：9

请求

名称类型
group_request server_end<BufferCollectionTokenGroup>

复制

此方法可用于在创建共享联系人之前添加参与者， BufferCollection.在 您并不希望等待这些实例 作为每项重复内容的一部分进行响应。

在发送一条或多条 Duplicate() 消息之后，在发送 向其他参与者（或其他分配器渠道）创建令牌， 客户端应发送 Sync() 并等待其响应。Sync() 可以对令牌进行调用，也可以对通过 将此令牌传递给 BindSharedCollection()。两者都可以确保 服务器在发送 其他参与者通过单独的分配器将令牌发送到服务器 。

所有令牌都必须通过 BindSharedCollection() 或 Close() 上交 BufferCollection。

当客户端调用 BindSharedCollection() 以提供 BufferCollectionToken，服务器将处理所有 Duplicate() 消息 然后再关闭 BufferCollectionToken。这样，客户端 Duplicate() 并立即使用以下代码提交 BufferCollectionToken BindSharedCollection，然后传输 token_request 的客户端端 那么服务器会发现 才能将此 BufferCollectionToken 完全关闭。

该掩码中为零的 rights_attenuation_mask 个权利位将是 可通过客户端客户端获取的缓冲区 VMO 权利 token_request.这样，发起者或中间参与者可以 会削弱参与者的权利。因此，不允许 获得该参与者所不具备的权利。 值 ZX_RIGHT_SAME_RIGHTS 可用于指定 因此应该应用弱音

以下为 Rights_attenuation_mask 值不会导致衰减：

  • ZX_RIGHT_SAME_RIGHTS（首选）
  • 0xFFFFFFFF（在计算衰减掩码时这很合理）
  • 0（已弃用 - 请勿使用 0 - 错误会记录到日志）

token_request 是 BufferCollectionToken 通道的服务器端。 此渠道的客户端是创建 共享的 BufferCollection。

已弃用：23 添加：7

请求

名称类型
rights_attenuation_mask uint32
token_request server_end<BufferCollectionToken>

DuplicateSync

该方法可用于在创建 共享的 BufferCollection。系统将为 rights_attenuation_masks 数组。返回值是客户端 每个新参与者令牌的末尾

如果调用令牌实际上可能根本不是有效令牌， 令牌的潜在恶意/不可信提供商，请考虑使用 先验证 BufferCollectionToken()，而不是尽可能地 如果 DuplicateSync() 因调用而未响应，则无限期卡住 令牌不是真实令牌。

与 Duplicate() 相反，不需要 Sync()（请参阅“Protocol Node”） 调用该方法。

所有令牌都必须通过 BindSharedCollection() 或 Close() 上交 BufferCollection。

在 rights_attenuation_masks 的每个条目中，权利位为零 不会包含在可通过相应 返回的令牌。这样，发起者或中间参与者可以 会削弱参与者的权利。因此，不允许 获得该参与者所不具备的权利。 值 ZX_RIGHT_SAME_RIGHTS 可用于指定 因此应该应用弱音

已弃用：23 添加：7

请求

名称类型
rights_attenuation_masks vector<zx/Rights>[64]

响应

名称类型
tokens vector<BufferCollectionToken>[64]

GetNodeRef

这会获取一个事件句柄，该事件句柄可用作 在任何节点上调用 IsAlternateFor()。客户不会获得 因为此标识名只能用作证据 客户端从该节点获取此句柄的个数。

由于这是 get 方法，因此在 GetNodeRef() 和 IsAlternateFor() 调用，尽管进行了两次调用 可能位于不同的频道上

另请参阅 IsAlternateFor()。

请求

<空>

响应

名称类型
node_ref handle<event>

IsAlternateFor

这将检查调用节点是否位于根位于 公共父 BufferCollectionTokenGroup 的不同子令牌， 与传入的 node_ref 相关联。

此通话用于协助执行准入控制去重，以及 以及调试。

必须使用节点的 GetNodeRef() 获取 node_ref BufferCollectionToken、BufferCollection 或 BufferCollectionTokenGroup。

node_ref 可以是重复的句柄；因此无需调用 每次调用 IsAlternateFor() 时，返回 GetNodeRef()。

如果调用令牌实际上可能根本不是有效令牌， 令牌的可能恶意/不可信的提供商，调用 先验证 BufferCollectionToken()，而不是尽可能地 如果 IsAlternateFor() 因调用而未响应，则无限期卡住 令牌不是真实令牌（并非真正与 sysmem 通信）。另一个 首先使用此令牌调用 BindSharedCollection 验证令牌并将其转换为 BufferCollection，然后 会调用 BufferCollection IsAlternateFor()。

错误值：

ZX_ERR_NOT_FOUND 表示在同一逻辑节点中找不到 node_ref 缓冲区收集。在进行逻辑分配和 同一逻辑分配子树中，这实质上意味着 node_ref 从来不是此逻辑缓冲区集合的一部分，因为 在逻辑分配之前，所有存在的 node_ref 都会保留 至少存在，直到进行逻辑分配（包括 执行 Close() 并关闭其频道）后，对于 ZX_ERR_NOT_FOUND 此节点的频道仍需要连接到服务器 前提是整个逻辑分配都具有 已失败。在逻辑分配之后或在其他逻辑分配中 子树中，还有其他可能的原因会导致此错误。对于 一个不同的逻辑分配示例（与此节点分隔） AttachToken() 或 SetDispensable() 进行逻辑分配）可能会导致其 子树删除这些节点，或者 BufferCollectionTokenGroup 可能会选择与当前存在的子树不同的子树 node_ref 导致 node_ref 节点被删除。唯一的时间 在节点没有对应的通道后，sysmem 将在该节点周围保留一个节点 表示使用了 Close()，并且节点的子树尚未失败。 导致此错误的另一个原因是，如果 node_ref 是事件对句柄 但实际上不是从 GetNodeRef().

ZX_ERR_INVALID_ARGS 表示调用方传递的 node_ref 不是 事件对处理脚本，或者在真实环境中没有预期所需的权利， node_ref.

此调用不会返回其他失败的状态代码。不过， sysmem 将来可能会添加其他代码，因此客户端应该 对任何失败的状态代码进行合理的默认处理。

成功后，is_alternate 具有以下含义：

  • true - 调用节点和 node_ref 节点是一个 BufferCollectionTokenGroup。这意味着 调用节点和 node_ref 节点不会同时具有它们的 但 sysmem 会选择 约束条件 - 不能两者兼而有之。这是因为 在逻辑分配期间选择了 BufferCollectionTokenGroup， 并且只有一个子树的子树对约束有贡献 汇总。
  • false - 调用节点和 node_ref 节点不是 BufferCollectionTokenGroup。目前， 这意味着共同的第一个父节点是 BufferCollectionToken 或 BufferCollection（无论 Close()ed 或 Close()ed）。这意味着调用节点和 node_ref 节点可以同时在运行期间同时应用这两个约束条件 限制条件汇总的逻辑分配（如果这两个节点） 由任何涉及的父级 BufferCollectionTokenGroup 选择。 在此情况下，不会出现 直接阻止两个节点同时被选中 约束条件均经过汇总，但即使为 false，也汇总了其中一个或两个 如果存在一个或两个节点，这些节点可能仍会被排除在考虑范围之外 节点具有直接或间接父级 BufferCollectionTokenGroup 该方法会选择一个子树，而不是包含 调用 Node 或 node_ref 节点。

请求

名称类型
node_ref handle<event>

响应

名称类型
payload Node_IsAlternateFor_Result

SetDebugClientInfo

将有关 sysmem 可以使用的当前客户端的信息设置为 帮助调试泄漏内存并挂起以等待约束。|name|罐 是任意字符串，但使用当前进程名称（请参阅 fsl::GetCurrentProcessName()）是一个很好的默认值。|id|可以是 任意 ID，使用当前进程 ID（请参阅 fsl::GetCurrentProcessKoid()) 是一个很好的默认值。

也在启用详细日志记录功能时使用（请参阅 SetVerboseLogging()），以 表明是哪个客户最先关闭其渠道，从而导致其 子树故障（如果子树的用途是 但如果比预期更早 客户渠道专用的名称有助于诊断 第一个来源）。

默认情况下（除非被此消息替换或使用 Allocator.SetDebugClientInfo()），那么节点将从其 父节点时创建的键。虽然可以 比没有要好，通常让每个参与者使用 Node.SetDebugClientInfo() 或 Allocator.SetDebugClientInfo() 可保留 与当前客户直接相关的信息。此外，SetVerboseLogging() 有助于消除不确定节点是否有 从其父级复制而来

请求

名称类型
name string[64]
id uint64

SetDebugTimeoutLogDeadline

如果并非所有客户端都设置了限制条件 5 秒，则系统会记录警告 创建集合后客户端可以调用此方法 。如果截止时间由多个客户设定 未指定将生效的截止期限。

请求

名称类型
deadline zx/Time

SetDispensable

在逻辑分配缓冲区后，可分配的令牌可能会失败 不会导致其父项（如果有）失败。

可消耗的令牌会与约束条件一起参与， 父实体。如果可分配的令牌 在逻辑分配缓冲区之前失败，则故障会传播到 该可分配令牌的父级。

合理分配缓冲区之后，可分配的令牌故障 （或可分配令牌的任何子项）不会传播到 令牌的父级。失败会从常规 可分配令牌的子项分配给一次性令牌。失败 如果附加了子级，则阻止其到达其父级， 或者，如果子级是可饮用的，并且故障是在合理的时间之后发生的， 分配。

参与者需要满足以下条件时，可以使用可分配的令牌 提供约束条件，但在分配缓冲区后，参与者 可以失败，而不会导致父级的缓冲区收集失败 看法。

相比之下，AttachToken() 可用于创建不 参与与其父级的约束条件聚合，以及 则其延迟不会传播到其父级， 提供约束条件不会阻止父项完成其 缓冲区分配。

在某些情况下，发起者可能会选择在开始时使用一次性的 提供相应的令牌，如果第一个事件发生， 该参与者的实例出现故障，系统会重新生成该参与者的第二个实例， 参与者将获得一个使用 AttachToken() 创建的令牌。

如果客户端使用此消息，则客户端不应依赖 或客户端自己的 BufferCollectionToken 或 BufferCollection 通道来关闭 因为任何 BufferCollectionToken 突然失败 或 BufferCollection，它具有 SetDispensable() 并提供给 另一个进程因此，客户应格外小心 以通过其他方式发现其他进程失败。

虽然可以在 BufferCollectionTokenGroup 的直接子级， 替换作为某个群组的直接子级但已失败的可分配令牌 以及使用 AttachToken() 获取新令牌（因为没有 AttachToken() ）。在这种情况下，如需启用 AttachToken() 替换， 创建一个作为直接子项的额外非需要的令牌（节点） 并将现有的可分配令牌设为 额外的令牌（节点）。这样，作为一个额外的令牌（节点）， 该组的直接子级具有 BufferCollection.AttachToken()， 用于替换失败的可凭令牌。

针对已经无法使用的令牌的 SetDispensable() 具有幂等性。

已弃用：23 添加：7

请求

<空>

SetName

为此缓冲区集合中的 VMO 设置名称。名称可能被截断 。名称只会影响设置后分配的 VMO - 此调用 不会重命名现有 VMO。如果多个客户设置了不同的名称 则较大的优先级值将胜出

请求

名称类型
priority uint32
name string[64]

SetVerboseLogging

详细日志记录包括通过 SetConstraints() 设置的限制（从每个 以及通过 SetDebugClientInfo() 设置的信息以及 节点树。

通常，在汇总时，系统仅输出一行投诉 仅显示汇总失败的具体详细原因 提供最基本的信息。虽然这通常足以诊断问题 如果之前只进行了细微的更改并且系统在运行之前 这种微小的改动通常并不足以 缓冲区收集。尤其是 复杂的节点树，涉及 AttachToken()、 SetDispensable()、BufferCollectionTokenGroup 节点以及 节点的树状结构，详细日志记录可能有助于诊断树状结构中 原因、为什么逻辑分配失败， 子树的失败时间早于预期。

额外记录的目的是为了能在演出中获得 （如果仅在少量缓冲区集合上启用）。 如果我们没有跟踪错误，则不应发送此消息。

如果太多参与者保持启用详细日志记录功能，我们可能最终 需要允许系统级系统系统详细日志记录 通过一些其他设置，可避免系统因 此邮件。

对于某些节点，这可能是 NOP，因为这是有意为之关联的政策 日志记录。

请求

<空>

同步

确保之前的消息（包括 令牌、集合或组。

对不是/不是有效令牌的令牌调用 BufferCollectionToken.Sync() 有效的 sysmem 令牌可能会导致 Sync() 永久挂起。请参阅 ValidBufferCollectionToken() 来降低这种可能性 恶意/虚假 BufferCollectionToken，但只能以一次往返为代价。 另一种方法是将令牌传递给 BindSharedCollection()， 在用令牌交换 BufferCollection 时验证令牌 然后可以使用 BufferCollection Sync()。

调用 Sync() 之后，就可以安全地发送 token_request 的客户端一端 如果服务器收到请求后， 会由对方发送到 BindSharedCollection()。

其他选项包括等待每个 token.Duplicate() 完成 单独调用 token.Sync()，或者 上交令牌后，对 BufferCollection 调用 Sync() （通过 BindSharedCollection() 提供）

另一种缓解方法是避免对令牌调用 Sync() 而是稍后处理如果 BufferCollection.Sync() 可能失败， 原始令牌无效。 但需要客户端代码来延迟发送 在客户端代码转换之前，与此令牌复制的令牌 将令牌复制到 BufferCollection，并且成功接收 BufferCollection.Sync() 的响应。

如果可行，最好改用 BufferCollection.Sync()（参见上文）。 当 BufferCollection.Sync() 不可行时，调用方必须已 知道此令牌是有效的，否则 BufferCollectionToken.Sync() 可能会 永远挂起。请参阅 VerifyBufferCollectionToken() 以检查令牌 。

请求

<空>

响应

<空>

BufferCollectionTokenGroup

在 fuchsia.sysmem/collection.fidl 中定义

系统内存实现一定会与逻辑 / 概念模型，如下所示：

与往常一样，逻辑分配会考虑根节点以及所有具有 不传输 AttachToken() 或子树的根连接 基于 AttachToken() 令牌以及连接到该令牌的所有节点 子树中不传输另一个 AttachToken()。这称为 剪枝的逻辑分配子树，简称为剪除的子树。

在约束汇总期间，每个 BufferCollectionTokenGroup 将选择 有一个子词元。其余子项 逻辑分配似乎失败，而选定的子级可能会成功。

当整体逻辑中存在多个 BufferCollectionTokenGroup 时， 分配剪枝后的子树中，两组之间的相对优先级为 相当于树的 DFS 预订单迭代中的排序， 父项的优先级高于子项，而左子项的优先级高于子项

选择某个组的特定子级时（无论是临时在 约束汇总尝试，或作为最终选择）， 如果未选择群组的其他子项，则可能导致“隐藏”其他 所有子组下。

在逻辑分配中，首先尝试通过临时 选择优先级最高的群组的子级 0，选择下一优先级组的子级 0 不会因临时选择而隐藏的最高优先级群组 远等

如果该汇总尝试失败，则系统将尝试对 所有相同组（除最低优先级的非隐藏组外）的序数 0 子项 组将暂时选择其序数 1 的子项（然后选择子项 2） 等等）。如果将优先级最低的新群组取消隐藏为临时群组 选择会更新，新取消隐藏的最低优先级群组 在更改临时选择之前，按顺序考虑其子项 之前优先级最低的群组中就结果而言 到系统化枚举 中所有可能的选择组合， 类似计数的顺序最频繁地更新优先级最低的群体， 优先级最高的群组出现的频率最低。我们并不实际尝试 我们可以跳过组合， 是多余的/等效的，因为它们会在不对结果进行任何更改的情况下隐藏。

尝试对枚举的非等效选项组合进行汇总 以这种方式继续，直到 (a) 所有汇总尝试都失败 在这种情况下，整个逻辑分配会失败，或者 (b) 直到尝试 聚合成功，此时缓冲区分配（如果需要）为 已尝试一次。如果基于第一个成功的缓冲区分配 聚合失败，则整个逻辑分配会失败（没有缓冲区） 分配重试 / 重试）。如果缓冲区分配成功（或不 则逻辑分配会成功。

如果这个优先级方案无法合理地用于 sysmem，请与 sysmem 的相关人员联系，讨论增加 实现您的目标。

请避免为每个容器创建大量 BufferCollectionTokenGroup 逻辑分配，尤其是在总子项数量较多的情况下，以及 尤其是在合理预期聚合时， 使用序数 0 的子节点失败，之后的子节点可能也会失败。周三 预计还可降低评估工作可能耗时的复杂性 只通过失败即可从过多的组中进行过多的子组合/选择 超出某个（相当高，但不算大）最大数值的逻辑分配 一组经过考虑的组子级组合/选择。更高级（以及更多 （复杂），但预计缓解措施实际上没有必要； 值得增加的复杂性。如果遇到上限，请与系统管理员联系 或者如果您预计它会受到攻击 选项。

最好在单个中使用多个 ImageFormatConstraints 在可行的情况下使用 BufferCollectionConstraints（当参与者只需要 表示支持多种 PixelFormat， 系统内存从所有支持的 PixelFormat 中选择要使用的 PixelFormat 参与者）。

与 BufferCollectionToken 和 BufferCollection 类似， 未先发送 Close() 的 BufferCollectionTokenGroup 通道会导致 逻辑缓冲区收集失败（如果使用 SetDispensable() 或 AttachToken()，并且 BufferCollectionTokenGroup 是 子树的另一个子树，该节点不会将故障传播到其 父级）。

已弃用：23 添加：9

AllChildrenPresent

AllChildrenPresent()

创建所有子项后，客户端必须调用 AllChildrenPresent() 用于告知 sysmem，不会再创建子项，这样 sysmem 可以知道何时可以开始聚合约束条件。

如果要发送 Close()，它应该在之后 AllChildrenPresent()，否则会导致群组失败，并且 则仍会触发失败

请求

<空>

关闭

在 BufferCollectionToken 通道上：

通常，参与者会将 BufferCollectionToken 转换为 BufferCollection 视图，但是参与者也可以自由关闭 令牌（然后立即或稍后在 响应，以免产生逻辑缓冲区 收集失败。通常，令牌通道意外关闭 会导致逻辑缓冲区收集失败（唯一的例外情况是 涉及 AttachToken() 或 SetDispensable() 的情况）。

在 BufferCollection 频道上：

默认情况下，服务器会处理 BufferCollection 的意外故障 使整个逻辑缓冲区收集失败。部分目的在于 如有任何参与者，可加快关闭 VMO 句柄以回收内存 失败。如果参与者想要彻底关闭 BufferCollection 视图，而不会导致逻辑缓冲区收集失败，则参与者 可以在关闭 BufferCollection 的客户端之前发送 Close() 。如果这是最后一个 BufferCollection 视图，则此逻辑缓冲区为 仍会遭到停用Close() 可发生在 SetConstraints() 指定的约束条件。如果先于 SetConstraints()， 无需具有此节点的约束条件即可分配。如果 在 SetConstraints() 之后，系统会保留并汇总约束条件 以及任何后续逻辑分配，即使没有 。

在 BufferCollectionTokenGroup 通道上：

默认情况下，BufferCollectionTokenGroup 出现意外故障时 触发逻辑 BufferCollectionTokenGroup 的故障，并将 将失败传播到其父级。关闭 BufferCollectionTokenGroup 而不会出现逻辑组故障或不传播故障的情况，则发送 Close()，然后再关闭通道客户端端点。

如果 Close() 出现在 AllChildrenPresent() 之前，则逻辑缓冲区 尽管调用了 Close()，回收仍然会失败（因为 sysmem 不能 是否创建了所有相关的子项，因此会产生含糊不清的 是否会将所有相关约束条件提供给 sysmem）。如果 Close() 发生在 AllChildrenPresent() 之后，子级及其所有子级 约束条件保持不变（就像 BufferCollectionTokenGroup 渠道一直保持打开状态），而关闭 不会触发或传播失败。

请求

<空>

CreateChild

创建子令牌。在将此令牌的客户端传递给 BindSharedCollection()，在 CreateChild() 后完成 Sync() 必填字段。或者，客户端可以使用 CreateChildrenSync()，这实质上是 包含 Sync()。

token_request - 新令牌通道的服务器端。

Rights_attenuation_mask - 如果 ZX_RIGHT_SAME_RIGHTS，则创建的令牌 允许持有人获得与父令牌相同的缓冲区权利 。

请求

名称类型
payload BufferCollectionTokenGroupCreateChildRequest

CreateChildrenSync

一次同步创建 1 个或多个子令牌。与此相反， CreateChild()，无需完成 Sync()，即可将 所返回令牌的客户端结束位置发送到 BindSharedCollection()。

Rights_attentuation_mask 的大小决定了 创建的子令牌。

索引较低的子令牌的优先级高于（尝试更快） 索引较高的子词元。

按照所有子令牌，成功的聚合将仅选择一个子令牌 在所有已创建的儿童中 可能会多次调用 CreateChild() 和 CreateChildrenSync()）。

每个群组允许的儿童总数上限 整个树中（从根节点开始）的节点数量设有上限 无法通过这些协议进行配置

请求

名称类型
rights_attenuation_masks vector<zx/Rights>[64]

响应

名称类型
tokens vector<BufferCollectionToken>[64]

GetNodeRef

这会获取一个事件句柄，该事件句柄可用作 在任何节点上调用 IsAlternateFor()。客户不会获得 因为此标识名只能用作证据 客户端从该节点获取此句柄的个数。

由于这是 get 方法，因此在 GetNodeRef() 和 IsAlternateFor() 调用，尽管进行了两次调用 可能位于不同的频道上

另请参阅 IsAlternateFor()。

请求

<空>

响应

名称类型
node_ref handle<event>

IsAlternateFor

这将检查调用节点是否位于根位于 公共父 BufferCollectionTokenGroup 的不同子令牌， 与传入的 node_ref 相关联。

此通话用于协助执行准入控制去重，以及 以及调试。

必须使用节点的 GetNodeRef() 获取 node_ref BufferCollectionToken、BufferCollection 或 BufferCollectionTokenGroup。

node_ref 可以是重复的句柄；因此无需调用 每次调用 IsAlternateFor() 时，返回 GetNodeRef()。

如果调用令牌实际上可能根本不是有效令牌， 令牌的可能恶意/不可信的提供商，调用 先验证 BufferCollectionToken()，而不是尽可能地 如果 IsAlternateFor() 因调用而未响应，则无限期卡住 令牌不是真实令牌（并非真正与 sysmem 通信）。另一个 首先使用此令牌调用 BindSharedCollection 验证令牌并将其转换为 BufferCollection，然后 会调用 BufferCollection IsAlternateFor()。

错误值：

ZX_ERR_NOT_FOUND 表示在同一逻辑节点中找不到 node_ref 缓冲区收集。在进行逻辑分配和 同一逻辑分配子树中，这实质上意味着 node_ref 从来不是此逻辑缓冲区集合的一部分，因为 在逻辑分配之前，所有存在的 node_ref 都会保留 至少存在，直到进行逻辑分配（包括 执行 Close() 并关闭其频道）后，对于 ZX_ERR_NOT_FOUND 此节点的频道仍需要连接到服务器 前提是整个逻辑分配都具有 已失败。在逻辑分配之后或在其他逻辑分配中 子树中，还有其他可能的原因会导致此错误。对于 一个不同的逻辑分配示例（与此节点分隔） AttachToken() 或 SetDispensable() 进行逻辑分配）可能会导致其 子树删除这些节点，或者 BufferCollectionTokenGroup 可能会选择与当前存在的子树不同的子树 node_ref 导致 node_ref 节点被删除。唯一的时间 在节点没有对应的通道后，sysmem 将在该节点周围保留一个节点 表示使用了 Close()，并且节点的子树尚未失败。 导致此错误的另一个原因是，如果 node_ref 是事件对句柄 但实际上不是从 GetNodeRef().

ZX_ERR_INVALID_ARGS 表示调用方传递的 node_ref 不是 事件对处理脚本，或者在真实环境中没有预期所需的权利， node_ref.

此调用不会返回其他失败的状态代码。不过， sysmem 将来可能会添加其他代码，因此客户端应该 对任何失败的状态代码进行合理的默认处理。

成功后，is_alternate 具有以下含义：

  • true - 调用节点和 node_ref 节点是一个 BufferCollectionTokenGroup。这意味着 调用节点和 node_ref 节点不会同时具有它们的 但 sysmem 会选择 约束条件 - 不能两者兼而有之。这是因为 在逻辑分配期间选择了 BufferCollectionTokenGroup， 并且只有一个子树的子树对约束有贡献 汇总。
  • false - 调用节点和 node_ref 节点不是 BufferCollectionTokenGroup。目前， 这意味着共同的第一个父节点是 BufferCollectionToken 或 BufferCollection（无论 Close()ed 或 Close()ed）。这意味着调用节点和 node_ref 节点可以同时在运行期间同时应用这两个约束条件 限制条件汇总的逻辑分配（如果这两个节点） 由任何涉及的父级 BufferCollectionTokenGroup 选择。 在此情况下，不会出现 直接阻止两个节点同时被选中 约束条件均经过汇总，但即使为 false，也汇总了其中一个或两个 如果存在一个或两个节点，这些节点可能仍会被排除在考虑范围之外 节点具有直接或间接父级 BufferCollectionTokenGroup 该方法会选择一个子树，而不是包含 调用 Node 或 node_ref 节点。

请求

名称类型
node_ref handle<event>

响应

名称类型
payload Node_IsAlternateFor_Result

SetDebugClientInfo

将有关 sysmem 可以使用的当前客户端的信息设置为 帮助调试泄漏内存并挂起以等待约束。|name|罐 是任意字符串，但使用当前进程名称（请参阅 fsl::GetCurrentProcessName()）是一个很好的默认值。|id|可以是 任意 ID，使用当前进程 ID（请参阅 fsl::GetCurrentProcessKoid()) 是一个很好的默认值。

也在启用详细日志记录功能时使用（请参阅 SetVerboseLogging()），以 表明是哪个客户最先关闭其渠道，从而导致其 子树故障（如果子树的用途是 但如果比预期更早 客户渠道专用的名称有助于诊断 第一个来源）。

默认情况下（除非被此消息替换或使用 Allocator.SetDebugClientInfo()），那么节点将从其 父节点时创建的键。虽然可以 比没有要好，通常让每个参与者使用 Node.SetDebugClientInfo() 或 Allocator.SetDebugClientInfo() 可保留 与当前客户直接相关的信息。此外，SetVerboseLogging() 有助于消除不确定节点是否有 从其父级复制而来

请求

名称类型
name string[64]
id uint64

SetDebugTimeoutLogDeadline

如果并非所有客户端都设置了限制条件 5 秒，则系统会记录警告 创建集合后客户端可以调用此方法 。如果截止时间由多个客户设定 未指定将生效的截止期限。

请求

名称类型
deadline zx/Time

SetName

为此缓冲区集合中的 VMO 设置名称。名称可能被截断 。名称只会影响设置后分配的 VMO - 此调用 不会重命名现有 VMO。如果多个客户设置了不同的名称 则较大的优先级值将胜出

请求

名称类型
priority uint32
name string[64]

SetVerboseLogging

详细日志记录包括通过 SetConstraints() 设置的限制（从每个 以及通过 SetDebugClientInfo() 设置的信息以及 节点树。

通常，在汇总时，系统仅输出一行投诉 仅显示汇总失败的具体详细原因 提供最基本的信息。虽然这通常足以诊断问题 如果之前只进行了细微的更改并且系统在运行之前 这种微小的改动通常并不足以 缓冲区收集。尤其是 复杂的节点树，涉及 AttachToken()、 SetDispensable()、BufferCollectionTokenGroup 节点以及 节点的树状结构，详细日志记录可能有助于诊断树状结构中 原因、为什么逻辑分配失败， 子树的失败时间早于预期。

额外记录的目的是为了能在演出中获得 （如果仅在少量缓冲区集合上启用）。 如果我们没有跟踪错误，则不应发送此消息。

如果太多参与者保持启用详细日志记录功能，我们可能最终 需要允许系统级系统系统详细日志记录 通过一些其他设置，可避免系统因 此邮件。

对于某些节点，这可能是 NOP，因为这是有意为之关联的政策 日志记录。

请求

<空>

同步

确保之前的消息（包括 令牌、集合或组。

对不是/不是有效令牌的令牌调用 BufferCollectionToken.Sync() 有效的 sysmem 令牌可能会导致 Sync() 永久挂起。请参阅 ValidBufferCollectionToken() 来降低这种可能性 恶意/虚假 BufferCollectionToken，但只能以一次往返为代价。 另一种方法是将令牌传递给 BindSharedCollection()， 在用令牌交换 BufferCollection 时验证令牌 然后可以使用 BufferCollection Sync()。

调用 Sync() 之后，就可以安全地发送 token_request 的客户端一端 如果服务器收到请求后， 会由对方发送到 BindSharedCollection()。

其他选项包括等待每个 token.Duplicate() 完成 单独调用 token.Sync()，或者 上交令牌后，对 BufferCollection 调用 Sync() （通过 BindSharedCollection() 提供）

另一种缓解方法是避免对令牌调用 Sync() 而是稍后处理如果 BufferCollection.Sync() 可能失败， 原始令牌无效。 但需要客户端代码来延迟发送 在客户端代码转换之前，与此令牌复制的令牌 将令牌复制到 BufferCollection，并且成功接收 BufferCollection.Sync() 的响应。

如果可行，最好改用 BufferCollection.Sync()（参见上文）。 当 BufferCollection.Sync() 不可行时，调用方必须已 知道此令牌是有效的，否则 BufferCollectionToken.Sync() 可能会 永远挂起。请参阅 VerifyBufferCollectionToken() 以检查令牌 。

请求

<空>

响应

<空>

DriverConnector

在 fuchsia.sysmem/driver_connector.fidl 中定义

向驱动程序建立具有此接口的信道（通常在 此接口允许异步发送 将由驱动程序提供的分配器频道。

目前，唯一通过常规 devhost FIDL 直接提供的 FIDL 接口 由 sysmem 驱动程序调度代码时所调用的接口。其他系统 主要是因为我们希望 建立异步通道，方法是将服务器通道发送到 司机无需来回打开，也无需管理频道 存储为一个文件描述符

https://fxbug.dev/42108063 跟踪到的一个次要当前原因是当前的开发者主机 调度代码不允许异步处理请求， 至少让 BufferCollection 接口能够正常运行， 该界面包含的请求只有在 devhost 执行 限制。

已移除：23 已弃用：9 添加：7

连接

此单向消息会在分配器频道的服务器端发送。

allocator_request 将由系统内存驱动程序（或相应通道）提供， 将关闭）。

请求

名称类型
allocator_request server_end<Allocator>

SetAuxServiceDirectory

请求

名称类型
service_directory fuchsia.io/Directory

节点

在 fuchsia.sysmem/collection.fidl 中定义

已弃用：23 添加：9

关闭

在 BufferCollectionToken 通道上：

通常，参与者会将 BufferCollectionToken 转换为 BufferCollection 视图，但是参与者也可以自由关闭 令牌（然后立即或稍后在 响应，以免产生逻辑缓冲区 收集失败。通常，令牌通道意外关闭 会导致逻辑缓冲区收集失败（唯一的例外情况是 涉及 AttachToken() 或 SetDispensable() 的情况）。

在 BufferCollection 频道上：

默认情况下，服务器会处理 BufferCollection 的意外故障 使整个逻辑缓冲区收集失败。部分目的在于 如有任何参与者，可加快关闭 VMO 句柄以回收内存 失败。如果参与者想要彻底关闭 BufferCollection 视图，而不会导致逻辑缓冲区收集失败，则参与者 可以在关闭 BufferCollection 的客户端之前发送 Close() 。如果这是最后一个 BufferCollection 视图，则此逻辑缓冲区为 仍会遭到停用Close() 可发生在 SetConstraints() 指定的约束条件。如果先于 SetConstraints()， 无需具有此节点的约束条件即可分配。如果 在 SetConstraints() 之后，系统会保留并汇总约束条件 以及任何后续逻辑分配，即使没有 。

在 BufferCollectionTokenGroup 通道上：

默认情况下，BufferCollectionTokenGroup 出现意外故障时 触发逻辑 BufferCollectionTokenGroup 的故障，并将 将失败传播到其父级。关闭 BufferCollectionTokenGroup 而不会出现逻辑组故障或不传播故障的情况，则发送 Close()，然后再关闭通道客户端端点。

如果 Close() 出现在 AllChildrenPresent() 之前，则逻辑缓冲区 尽管调用了 Close()，回收仍然会失败（因为 sysmem 不能 是否创建了所有相关的子项，因此会产生含糊不清的 是否会将所有相关约束条件提供给 sysmem）。如果 Close() 发生在 AllChildrenPresent() 之后，子级及其所有子级 约束条件保持不变（就像 BufferCollectionTokenGroup 渠道一直保持打开状态），而关闭 不会触发或传播失败。

请求

<空>

GetNodeRef

这会获取一个事件句柄，该事件句柄可用作 在任何节点上调用 IsAlternateFor()。客户不会获得 因为此标识名只能用作证据 客户端从该节点获取此句柄的个数。

由于这是 get 方法，因此在 GetNodeRef() 和 IsAlternateFor() 调用，尽管进行了两次调用 可能位于不同的频道上

另请参阅 IsAlternateFor()。

请求

<空>

响应

名称类型
node_ref handle<event>

IsAlternateFor

这将检查调用节点是否位于根位于 公共父 BufferCollectionTokenGroup 的不同子令牌， 与传入的 node_ref 相关联。

此通话用于协助执行准入控制去重，以及 以及调试。

必须使用节点的 GetNodeRef() 获取 node_ref BufferCollectionToken、BufferCollection 或 BufferCollectionTokenGroup。

node_ref 可以是重复的句柄；因此无需调用 每次调用 IsAlternateFor() 时，返回 GetNodeRef()。

如果调用令牌实际上可能根本不是有效令牌， 令牌的可能恶意/不可信的提供商，调用 先验证 BufferCollectionToken()，而不是尽可能地 如果 IsAlternateFor() 因调用而未响应，则无限期卡住 令牌不是真实令牌（并非真正与 sysmem 通信）。另一个 首先使用此令牌调用 BindSharedCollection 验证令牌并将其转换为 BufferCollection，然后 会调用 BufferCollection IsAlternateFor()。

错误值：

ZX_ERR_NOT_FOUND 表示在同一逻辑节点中找不到 node_ref 缓冲区收集。在进行逻辑分配和 同一逻辑分配子树中，这实质上意味着 node_ref 从来不是此逻辑缓冲区集合的一部分，因为 在逻辑分配之前，所有存在的 node_ref 都会保留 至少存在，直到进行逻辑分配（包括 执行 Close() 并关闭其频道）后，对于 ZX_ERR_NOT_FOUND 此节点的频道仍需要连接到服务器 前提是整个逻辑分配都具有 已失败。在逻辑分配之后或在其他逻辑分配中 子树中，还有其他可能的原因会导致此错误。对于 一个不同的逻辑分配示例（与此节点分隔） AttachToken() 或 SetDispensable() 进行逻辑分配）可能会导致其 子树删除这些节点，或者 BufferCollectionTokenGroup 可能会选择与当前存在的子树不同的子树 node_ref 导致 node_ref 节点被删除。唯一的时间 在节点没有对应的通道后，sysmem 将在该节点周围保留一个节点 表示使用了 Close()，并且节点的子树尚未失败。 导致此错误的另一个原因是，如果 node_ref 是事件对句柄 但实际上不是从 GetNodeRef().

ZX_ERR_INVALID_ARGS 表示调用方传递的 node_ref 不是 事件对处理脚本，或者在真实环境中没有预期所需的权利， node_ref.

此调用不会返回其他失败的状态代码。不过， sysmem 将来可能会添加其他代码，因此客户端应该 对任何失败的状态代码进行合理的默认处理。

成功后，is_alternate 具有以下含义：

  • true - 调用节点和 node_ref 节点是一个 BufferCollectionTokenGroup。这意味着 调用节点和 node_ref 节点不会同时具有它们的 但 sysmem 会选择 约束条件 - 不能两者兼而有之。这是因为 在逻辑分配期间选择了 BufferCollectionTokenGroup， 并且只有一个子树的子树对约束有贡献 汇总。
  • false - 调用节点和 node_ref 节点不是 BufferCollectionTokenGroup。目前， 这意味着共同的第一个父节点是 BufferCollectionToken 或 BufferCollection（无论 Close()ed 或 Close()ed）。这意味着调用节点和 node_ref 节点可以同时在运行期间同时应用这两个约束条件 限制条件汇总的逻辑分配（如果这两个节点） 由任何涉及的父级 BufferCollectionTokenGroup 选择。 在此情况下，不会出现 直接阻止两个节点同时被选中 约束条件均经过汇总，但即使为 false，也汇总了其中一个或两个 如果存在一个或两个节点，这些节点可能仍会被排除在考虑范围之外 节点具有直接或间接父级 BufferCollectionTokenGroup 该方法会选择一个子树，而不是包含 调用 Node 或 node_ref 节点。

请求

名称类型
node_ref handle<event>

响应

名称类型
payload Node_IsAlternateFor_Result

SetDebugClientInfo

将有关 sysmem 可以使用的当前客户端的信息设置为 帮助调试泄漏内存并挂起以等待约束。|name|罐 是任意字符串，但使用当前进程名称（请参阅 fsl::GetCurrentProcessName()）是一个很好的默认值。|id|可以是 任意 ID，使用当前进程 ID（请参阅 fsl::GetCurrentProcessKoid()) 是一个很好的默认值。

也在启用详细日志记录功能时使用（请参阅 SetVerboseLogging()），以 表明是哪个客户最先关闭其渠道，从而导致其 子树故障（如果子树的用途是 但如果比预期更早 客户渠道专用的名称有助于诊断 第一个来源）。

默认情况下（除非被此消息替换或使用 Allocator.SetDebugClientInfo()），那么节点将从其 父节点时创建的键。虽然可以 比没有要好，通常让每个参与者使用 Node.SetDebugClientInfo() 或 Allocator.SetDebugClientInfo() 可保留 与当前客户直接相关的信息。此外，SetVerboseLogging() 有助于消除不确定节点是否有 从其父级复制而来

请求

名称类型
name string[64]
id uint64

SetDebugTimeoutLogDeadline

如果并非所有客户端都设置了限制条件 5 秒，则系统会记录警告 创建集合后客户端可以调用此方法 。如果截止时间由多个客户设定 未指定将生效的截止期限。

请求

名称类型
deadline zx/Time

SetName

为此缓冲区集合中的 VMO 设置名称。名称可能被截断 。名称只会影响设置后分配的 VMO - 此调用 不会重命名现有 VMO。如果多个客户设置了不同的名称 则较大的优先级值将胜出

请求

名称类型
priority uint32
name string[64]

SetVerboseLogging

详细日志记录包括通过 SetConstraints() 设置的限制（从每个 以及通过 SetDebugClientInfo() 设置的信息以及 节点树。

通常，在汇总时，系统仅输出一行投诉 仅显示汇总失败的具体详细原因 提供最基本的信息。虽然这通常足以诊断问题 如果之前只进行了细微的更改并且系统在运行之前 这种微小的改动通常并不足以 缓冲区收集。尤其是 复杂的节点树，涉及 AttachToken()、 SetDispensable()、BufferCollectionTokenGroup 节点以及 节点的树状结构，详细日志记录可能有助于诊断树状结构中 原因、为什么逻辑分配失败， 子树的失败时间早于预期。

额外记录的目的是为了能在演出中获得 （如果仅在少量缓冲区集合上启用）。 如果我们没有跟踪错误，则不应发送此消息。

如果太多参与者保持启用详细日志记录功能，我们可能最终 需要允许系统级系统系统详细日志记录 通过一些其他设置，可避免系统因 此邮件。

对于某些节点，这可能是 NOP，因为这是有意为之关联的政策 日志记录。

请求

<空>

同步

确保之前的消息（包括 令牌、集合或组。

对不是/不是有效令牌的令牌调用 BufferCollectionToken.Sync() 有效的 sysmem 令牌可能会导致 Sync() 永久挂起。请参阅 ValidBufferCollectionToken() 来降低这种可能性 恶意/虚假 BufferCollectionToken，但只能以一次往返为代价。 另一种方法是将令牌传递给 BindSharedCollection()， 在用令牌交换 BufferCollection 时验证令牌 然后可以使用 BufferCollection Sync()。

调用 Sync() 之后，就可以安全地发送 token_request 的客户端一端 如果服务器收到请求后， 会由对方发送到 BindSharedCollection()。

其他选项包括等待每个 token.Duplicate() 完成 单独调用 token.Sync()，或者 上交令牌后，对 BufferCollection 调用 Sync() （通过 BindSharedCollection() 提供）

另一种缓解方法是避免对令牌调用 Sync() 而是稍后处理如果 BufferCollection.Sync() 可能失败， 原始令牌无效。 但需要客户端代码来延迟发送 在客户端代码转换之前，与此令牌复制的令牌 将令牌复制到 BufferCollection，并且成功接收 BufferCollection.Sync() 的响应。

如果可行，最好改用 BufferCollection.Sync()（参见上文）。 当 BufferCollection.Sync() 不可行时，调用方必须已 知道此令牌是有效的，否则 BufferCollectionToken.Sync() 可能会 永远挂起。请参阅 VerifyBufferCollectionToken() 以检查令牌 。

请求

<空>

响应

<空>

SecureMem

在 fuchsia.sysmem/secure_mem.fidl 中定义

SecureMem

客户端是 sysmem。服务器是 securemem 驱动程序。

TEE - 可信执行环境。

REE - 丰富的执行环境。

允许 sysmem 调用 securemem 驱动程序，以获取任何安全堆 通过 TEE（或通过 securemem 驱动程序）进行配置，并将任何 通过 sysmem 配置的安全堆。

目前，动态分配的安全堆通过 sysmem 进行配置，如 它在启动过程中很早就开始运行，并且可以成功地保留 物理内存目前，固定位置安全堆通过 TEE，因为连接从引导加载程序到 TEE。不过， 协议特意不在乎哪些堆是动态分配的 以及固定位置

已弃用：23 添加：7

AddSecureHeapPhysicalRange

从 sysmem 到 securemem 驱动程序的这一请求会将 要添加的范围（针对通过 sysmem.

只有 sysmem 可以调用此方法，因为只有 sysmem 传递给客户端 （通过 RegisterSecureMem() 提供此协议的 FIDL 通道）。通过 Securemem 驱动程序是此协议的服务器端。

Securemem 驱动程序必须将所有涵盖的偏移量配置为受保护 然后再成功回复此消息。

失败时，securemem 驱动程序必须确保受保护范围未处于 创建。

在 dynamic_protection_ranges 时，系统最多只能调用 1 次 false。

如果 dynamic_protection_ranges 为 true，sysmem 可以多次调用此值 次（只要当前范围数不超出） max_protected_range_count.

调用方不得尝试添加与 已存在的范围。添加的范围可以相互重叠，前提是 没有两个范围是完全匹配的

错误：

  • ZX_ERR_BAD_STATE：在以下情况下调用多次： !dynamic_protection_ranges。添加一个会导致整个进程的 堆计数将超过 max_protected_range_count。
  • ZX_ERR_INVALID_ARGS - 非预期的堆或不符合要求的范围 更改为 Protect_range_granularity。
  • ZX_ERR_INTERNAL - 一般内部错误（例如在通信 使用 TEE，它不会生成 zx_status_t 错误）。
  • 也可能出现其他错误，例如由于通信故障或 服务器传播 zx_status_t 故障。

请求

名称类型
heap_range SecureHeapAndRange

响应

名称类型
payload SecureMem_AddSecureHeapPhysicalRange_Result

DeleteSecureHeapPhysicalRange

从 sysmem 到 securemem 驱动程序的这一请求会将 要删除的范围（针对通过 sysmem.

只有 sysmem 可以调用此方法，因为只有 sysmem 传递给客户端 （通过 RegisterSecureMem() 提供此协议的 FIDL 通道）。通过 Securemem 驱动程序是此协议的服务器端。

Securemem 驱动程序必须将所有涵盖的偏移量配置为 才能成功回复此消息。

失败时，securemem 驱动程序必须确保受保护范围未处于 已删除。

如果 dynamic_protection_ranges 为 false，则系统不得调用此方法。

如果 dynamic_protection_ranges 为 true，sysmem 可以重复调用此方法， 调用时存在的各个范围上。

如果要删除的范围的任何部分都没有被另一个 受保护范围，然后将任何正在进行的 DMA 用于整个范围的任意部分 可能会中断 / 可能会失败， 整个系统（总线锁定或类似，具体取决于设备详细信息）。 因此，调用方必须确保不存在正在进行的 DMA， 范围的任何部分，除非调用方还有其他 有效范围，覆盖正在删除的范围的每个块。正在进行 与所删除范围之外的区块之间的 DMA 绝不会受到以下因素的影响： 删除。

错误：

  • ZX_ERR_BAD_STATE - 在 !dynamic_protection_ranges 中调用。
  • ZX_ERR_INVALID_ARGS - 非预期的堆或不符合要求的范围 更改为 Protect_range_granularity。
  • ZX_ERR_INTERNAL - 一般内部错误（例如在通信 使用 TEE，它不会生成 zx_status_t 错误）。
  • ZX_ERR_NOT_FOUND - 找不到指定的范围。
  • 也可能出现其他错误，例如由于通信故障或 服务器传播 zx_status_t 故障。

请求

名称类型
heap_range SecureHeapAndRange

响应

名称类型
payload SecureMem_DeleteSecureHeapPhysicalRange_Result

GetPhysicalSecureHeapProperties

从 sysmem 到 securemem 驱动程序的这一请求将获取 安全堆。

这仅处理具有单个连续物理范围的堆。

如果此请求需要 以自动检测有多少范围可供 REE 使用。不限 临时硬件保护范围将在此请求之前删除 。

添加时间：7

请求

名称类型
entire_heap SecureHeapAndRange

响应

名称类型
payload SecureMem_GetPhysicalSecureHeapProperties_Result

GetPhysicalSecureHeaps

获取为其物理资源分配的任何安全堆的物理地址和长度 范围通过 TEE 进行配置。

目前，这些是固定的物理地址和长度， 通过 TEE 获取位置信息。

此方法优于 ['fuchsia.hardware.sysmem.Sysmem/RegisterHeap'] 当没有任何特殊的堆专用每个 VMO 设置或拆解时 必填字段。

在 Securemem 驱动程序成功响应此请求。

系统应仅调用一次此方法。返回零堆不是 失败。

错误：

  • ZX_ERR_BAD_STATE - 调用了多次。
  • ZX_ERR_INTERNAL - 一般内部错误（例如在通信 使用 TEE，它不会生成 zx_status_t 错误）。
  • 允许出现其他错误；任何其他错误都应 为 ZX_ERR_INTERNAL。

请求

<空>

响应

名称类型
payload SecureMem_GetPhysicalSecureHeaps_Result

ModifySecureHeapPhysicalRange

从 sysmem 到 securemem 驱动程序的这一请求会将 要修改的范围及其新的基数和长度，适用于 范围是通过 sysmem 设置的。

只有 sysmem 可以调用此方法，因为只有 sysmem 传递给客户端 （通过 RegisterSecureMem() 提供此协议的 FIDL 通道）。通过 Securemem 驱动程序是此协议的服务器端。

Securemem 驱动程序必须将范围配置为仅涵盖新的 在成功响应此消息之前偏移。

失败时，securemem 驱动程序必须确保范围未更改。

如果 dynamic_protection_ranges 为 false，则系统不得调用此方法。Sysmem 如果 !is_mod_protected_range_available，则不得调用此方法。

如果 dynamic_protection_ranges 为 true，sysmem 可以重复调用此方法， 调用时存在的各个范围上。

范围只能在一端修改，但不能在两端修改。 范围变短了，且未覆盖的数据块 其他有效范围所覆盖的整个范围、任何进行中的特定媒体市场区域 有可能发生故障，从而破坏整个系统 （总线完整标识或类似），因此调用方必须确保不存在 DMA 但前提是，除非 此范围修改未涵盖的区块 其他有效范围所涵盖，在这种情况下，正在进行的 特定媒体市场区域。

如果范围被修改为长度小于等于零，则该范围将被删除。

错误：

  • ZX_ERR_BAD_STATE - 在 !dynamic_protection_ranges 中调用。
  • ZX_ERR_INVALID_ARGS - 意外堆、old_range 或 new_range 不符合 Protect_range_granularity 或 old_range 和 new_range 在 begin 和 end 上都不同（不允许）。
  • ZX_ERR_INTERNAL - 一般内部错误（例如在通信 使用 TEE，它不会生成 zx_status_t 错误）。
  • ZX_ERR_NOT_FOUND - 找不到指定的范围。
  • 也可能出现其他错误，例如由于通信故障或 服务器传播 zx_status_t 故障。

请求

名称类型
range_modification SecureHeapAndRangeModification

响应

名称类型
payload SecureMem_ModifySecureHeapPhysicalRange_Result

ZeroSubRange

将当前存在的物理范围的子范围设为零，通过 AddSecureHeapPhysicalRange()。子范围必须完全覆盖 一个物理范围，且不得与任何其他物理范围重叠

is_covering_range_显式 - 如果为 true，覆盖范围必须为 1 （通过 AddSecureHeapPhysicalRange() 明确创建的范围）， 可能会经过修改如果为 false，覆盖范围不得 必须是通过 AddSecureHeapPhysicalRange()，但覆盖范围必须以 不通过 AddSecureHeapPhysicalRange() 创建的覆盖范围。通过 覆盖范围通常为整个实际范围（或 （涵盖更多） 通过 GetPhysicalSecureHeaps() 将配置传送到 sysmem。

正在进行的 DMA 不会因此请求中断。

请求

名称类型
is_covering_range_explicit bool
heap_range SecureHeapAndRange

响应

名称类型
payload SecureMem_ZeroSubRange_Result

结构体

BufferCollectionConstraints

在 fuchsia.sysmem/constraints.fidl 中定义

对 BufferCollection 参数的约束。这些约束条件可以 。sysmem 服务会实现 多个参与者的限制。

新代码已废弃此类型，但仍被某些相机代码使用。

字段类型说明默认
usage BufferUsage

这种用法只是作为提示，帮助系统选择更优的 PixelFormat 或类似格式（如果存在多个兼容选项时）。

汇总 BufferCollectionConstraints 时，这些值是按位或运算的。

必须至少指定一个使用位，除非整个 由于 !has_constraints ，BufferCollectionConstraints 逻辑上为 null。

 无默认设置
min_buffer_count_for_camping uint32

每位参与者可同时享受的缓冲数量 仅供暂时使用（露营）。

例如，视频解码器会（至少）指定 的参考帧 + 目前正在解码为 1 帧的帧。

参与者不得露营超过此处指定的缓冲区（但 否则处理可能会停滞。

在聚合 BufferCollectionConstraints 时，这些值会相加。

在测试场景中，对于任何 Transformer 来说， 则很可能（理想情况下会）被标记为未通过。在 测试场景，可能无法为参与者提供更多缓冲区

无默认设置
min_buffer_count_for_dedicated_slack uint32

每个参与者所需的 Slack 缓冲区数量下限 以便提高处理重叠率 / 提高性能。

在聚合 BufferCollectionConstraints 时，这些值会相加。

参与者通常应在此处指定 0 或 1，通常是 0 为 如果 min_buffer_count_for_camping 已经足以保留 20% 的时间处于忙碌状态 而如果缓冲区比严格需要多 1 个，则 1 个比较合适 因为你需要充分休息，确保 100% 的时间都处于忙碌状态 （稍微落后于没有额外缓冲的较低百分比）。

在测试场景中，可能强制将此字段设为 0， 预计参与者可以继续工作，而不会遇到困难。如果 正向进度原因需要一个缓冲区，该缓冲区应该 被计入 min_buffer_count_for_camping。

 无默认设置
min_buffer_count_for_shared_slack uint32

与 min_buffer_count_for_dedicated_slack 类似，但汇总时除外 这些值最大（而不是 add）。此处的值未与 任何参与者的 min_buffer_count_for_dedicated_slack。

参与者可以指定 >如果参与者希望确保 但整体上还存在一些 Slack，但不需要将它用于专用状态。

选择是使用 min_buffer_count_for_dedicated_slack 还是 min_buffer_count_for_shared_slack（或两者）通常与 额外的 Slack 对性能的提升程度。

在测试场景中，可能强制将此字段设为 0， 预计参与者可以继续工作，而不会遇到困难。如果 正向进度原因需要一个缓冲区，该缓冲区应该 被计入 min_buffer_count_for_camping。

 无默认设置
min_buffer_count uint32

挑剔的参与者很不幸，可能需要 较窄的 buffer_count 范围，甚至是特定的 buffer_count。这个 字段应保持 0，除非参与者确实必须将此字段设置为 限制整个 BufferCollectionInfo_2.buffer_count。任何此类 参与者仍应填写 min_buffer_count_for_* 字段 。

 无默认设置
max_buffer_count uint32

0 将被视为 0xFFFFFFFF。

 无默认设置
has_buffer_memory_constraints bool

针对 BufferCollectionSettings.buffer_settings 的限制。

想要指定 image_format_constraints_count > 的参与者1 次 通常会通过以下方法隐式指定最小缓冲区空间： image_format_constraints 并可以仅指定最大缓冲区空间 通过 Buffer_memory_constraints 来实现此目的。

 无默认设置
buffer_memory_constraints BufferMemoryConstraints 无默认设置
image_format_constraints_count uint32

对所存储图片的图片格式参数的可选限制 在 BufferCollection 的缓冲区中。这包括像素格式和 图片布局。这些约束条件是基于像素格式 是允许的。列表中的条目必须具有唯一的 pixel_formats。

汇总时，只包括由所有 image_format_constraints_count（非 Null）的参与者 BufferCollectionConstraints）。

 无默认设置
image_format_constraints [32] 无默认设置

BufferCollectionConstraintsAuxBuffers

在 fuchsia.sysmem/constraints.fidl 中定义

已移除：23 已弃用：9 添加：7

字段类型说明默认
need_clear_aux_buffers_for_secure bool

如果为 true，则只有满足以下条件的所有参与者才能选择安全堆： BufferMemoryConstraints 指定 allow_clear_aux_buffers_for_secure。如果 “需要”为 true，即“允许”必须为 true。

如果设为 false，参与者仍然可以操作，即使启用了安全的 内存（取决于支持的堆），没有清除 aux 缓冲区。

 无默认设置
allow_clear_aux_buffers_for_secure bool

如果设为 true，参与者将使用清除 Aux 缓冲区（如果正在使用） 将适当地分配给相应参与者的角色如果参与者 一个生产方，则参与者生产方将填充清晰的 aux 包含清除（未加密、未受 DRM 保护）字节的缓冲区，以及 用无法模拟起始代码的数据填充受保护的字节， 为 0xFF。

如果 BufferCollectionConstraintsAuxBuffers 从不发送， 则“允许”当且仅当参与者指定了用途时，才为 true 处于只读状态。

如果使用写入功能的参与者未指定或设置为 false， 如果任何参与者指定了 required_clear_aux_buffers_for_secure true。

 无默认设置

BufferCollectionInfo 资源

在 fuchsia.sysmem/collections_deprecated.fidl 中定义

已弃用。请使用 ['fuchsia.sysmem2.BufferCollectionInfo']。

新代码已废弃此类型，但仍可供某些相机代码使用。

字段类型说明默认
buffer_count uint32

集合中的缓冲区数量。

 无默认设置
format BufferFormat

说明缓冲区内容的表示方式。 集合内的所有缓冲区具有相同的格式。

 无默认设置
vmos vmo[64]

集合中每个缓冲区的 VMO 句柄。 仅当缓冲区由 VMO 支持时，VMO 才会存在。

如果存在，则 buffer_count 之后的所有 VMO 都是无效句柄。 所有缓冲区 VMO 句柄的大小和访问权限都相同。 VMO 访问权限取决于 分配缓冲区集合时指定的客户端。例如： 表示为只读使用情况的客户端将收到未 写入权限。

 无默认设置
vmo_size uint64

提供的每个 VMO 的大小。 仅当缓冲区由 VMO 支持时，此属性才会显示。

 0

BufferCollectionInfo_2 资源

在 fuchsia.sysmem/constraints.fidl 中定义

缓冲区集合及其缓冲区的相关信息。

已弃用：23 添加：7

字段类型说明默认
buffer_count uint32

缓冲区的总数。

 无默认设置
settings SingleBufferSettings

这些设置适用于初始缓冲区分配中的所有缓冲区。

 无默认设置
buffers [64]

VMO 处理 中每个缓冲区的 VMO 处理 。

如果存在，则索引 buffer_count 或之后的所有 VMO 都无效 (0) 个句柄。

所有缓冲区 VMO 句柄的大小和访问权限都相同。尺寸 位于 settings.buffer_settings.size_bytes 中。

VMO 访问权限取决于 分配缓冲区集合时指定的客户端。例如： 表示为只读使用情况的客户端将收到未 写入权限。此外，权利可能由 参数传递给 BufferCollectionToken.Duplicate() 调用。

 无默认设置

BufferFormat

在 fuchsia.sysmem/formats_deprecated.fidl 中定义

说明缓冲区内容的表示方式。 每种类型的缓冲区由各自的表进行描述。

新代码已废弃此类型，但仍被某些相机代码使用。

字段类型说明默认
tag uint32

由于该结构体曾经是单个成员联合，因此我们保留了标记 以免传输格式发生任何变化该标记必须设置为 0， 其他值都不正确。

 0
image ImageFormat 无默认设置

BufferMemoryConstraints

在 fuchsia.sysmem/constraints.fidl 中定义

新代码已废弃此类型，但仍被某些相机代码使用。

字段类型说明默认
min_size_bytes uint32 0
max_size_bytes uint32

0 将被视为 0xFFFFFFFF。

 4294967295
physically_contiguous_required bool false
secure_required bool

如果为 true，则至少有一个参与者需要安全内存。

汇总 BufferCollectionConstraints 时，这些值是 boolean-OR。

 false
ram_domain_supported bool

默认情况下，参与者必须确保 CPU 可以读取或写入数据 缓冲区，不执行缓存操作。如果设备支持使用 RAM 域，数据必须在 RAM 中可用（且 CPU 缓存状态 写入 CPU 缓存行时不会损坏 RAM 数据 将数据错误地存储到 RAM 中），并且使用 CPU 的使用方必须 在读取之前使 CPU 缓存失效（生产者不能保证 零过时的“clean”缓存行）

 false
cpu_domain_supported bool true
inaccessible_domain_supported bool false
heap_permitted_count uint32

可选的堆约束条件。不在意哪个堆的参与者 则应将此字段保留为 0。

 无默认设置
heap_permitted [32] 无默认设置

BufferMemorySettings

在 fuchsia.sysmem/constraints.fidl 中定义

已弃用：23 添加：7

字段类型说明默认
size_bytes uint32 无默认设置
is_physically_contiguous bool 无默认设置
is_secure bool 无默认设置
coherency_domain CoherencyDomain 无默认设置
heap HeapType

从中分配缓冲区的特定堆。 如需了解堆标识符值，请参阅此文件中的上文。

 无默认设置

BufferUsage

在 fuchsia.sysmem/usages.fidl 中定义

描述客户端如何访问缓冲区的内容。

新代码已废弃此类型，但仍被某些相机代码使用。

字段类型说明默认
none uint32 无默认设置
cpu uint32 无默认设置
vulkan uint32 无默认设置
display uint32 无默认设置
video uint32 无默认设置

ColorSpace

在 fuchsia.sysmem/image_formats.fidl 中定义

描述图像中像素的呈现方式。 简单的颜色空间只需一个类型。 参数颜色空间可能需要其他属性。

新代码已废弃此类型，但仍被某些相机代码使用。

字段类型说明默认
type ColorSpaceType 无默认设置

FormatModifier

在 fuchsia.sysmem/format_modifier.fidl 中定义

新代码已废弃此类型，但仍被某些相机代码使用。

字段类型说明默认
value uint64

高 8 位是在 FormatModifierVendor 中分配的供应商代码 枚举。低 56 位由供应商定义。

此字段以及此字段中的值按如下方式定义： 兼容性原因。

 无默认设置

ImageFormat

在 fuchsia.sysmem/image_formats_deprecated.fidl 中定义

描述图片的表示方式。

新代码已废弃此类型，但仍被某些相机代码使用。

字段类型说明默认
width uint32

行宽（以像素为单位）。

 无默认设置
height uint32

行数。

 无默认设置
layers uint32

多层图片中的层数。 如果未指定，则默认为 1。

 1
pixel_format PixelFormat

像素格式。

已弃用：23 添加：7
 无默认设置
color_space ColorSpace

颜色空间。

已弃用：23 添加：7
 无默认设置
planes [4]
已弃用：23 添加：7
 无默认设置

ImageFormatConstraints

在 fuchsia.sysmem/constraints.fidl 中定义

描述了对缓冲区中图像数据布局的约束。

新代码已废弃此类型，但仍被某些相机代码使用。

字段类型说明默认
pixel_format PixelFormat

需要遵循以下限制条件的 PixelFormat。答 可能有多个受支持的 PixelFormat， 在此情况下，参与者可以使用 ImageFormatConstraints 列表 每个 PixelFormat 都有一个条目其他字段并不罕见 ImageFormatConstraints 的大小因 PixelFormat 而异。 线性格式，以支持比平铺格式更小的大小上限。

 无默认设置
color_spaces_count uint32

留空会出错。存在冗余条目会导致错误。任意排序 不是错误。

 无默认设置
color_space [32] 无默认设置
min_coded_width uint32

允许的最小宽度（以像素为单位）。

例如，视频解码器参与者可以将此字段设为 可能由视频流指定的最小编码宽度值。在 相比之下，required_min_coded_width 会设为当前的 coding_width。min_coding_width 可汇总 通过使用 最低

另请参阅 required_min_coded_width。

 无默认设置
max_coded_width uint32

宽度上限（以像素为单位）。例如，风景可将此字段设为 （直接或通过子参与者）设置为 进行合成。 0 将被视为 0xFFFFFFFF。

 无默认设置
min_coded_height uint32

最小高度（以像素为单位）。例如，视频解码器参与者 将此字段设置为流指定的 encoded_height。

 无默认设置
max_coded_height uint32

高度上限（以像素为单位）。例如，风景可将此字段设为 （直接或通过次级参与者）上传到 YouTube 上 进行合成。 0 将被视为 0xFFFFFFFF。

 无默认设置
min_bytes_per_row uint32

对于平面 0，必须大于等于 min_coded_width 所隐含的值。

 无默认设置
max_bytes_per_row uint32

对于平面 0，必须大于等于 max_encoded_width 隐含的值。 0 将被视为 0xFFFFFFFF。

 无默认设置
max_coded_width_times_coded_height uint32

以像素为单位的最大图片区域通过 BufferSettings.size_bytes，也可以通过 字段。 0 将被视为 0xFFFFFFFF。

 4294967295
layers uint32

多层图片中的层数。 0 将被视为 1。

 1
coded_width_divisor uint32

coding_width % width_divisor 必须为 0。 0 将被视为 1。

 1
coded_height_divisor uint32

编码高度 % 高度除数必须为 0。 0 将被视为 1。

 1
bytes_per_row_divisor uint32

bytes_per_row % bytes_per_row_divisor 必须为 0。 0 将被视为 1。

 1
start_offset_divisor uint32

vmo_usable_start % start_offset_divisor 必须为 0。 0 将被视为 1。

 1
display_width_divisor uint32

display_width % display_width_divisor 必须为 0。 0 将被视为 1。

 1
display_height_divisor uint32

display_height % display_height_divisor 必须为 0。 0 将被视为 1。

 1
required_min_coded_width uint32

required_ 维度边界。

与不带“required_”的相应字段相反在 这些字段（设置为非零值时）表示对 生成的汇总非必需字段会指定一个空格， 完全占据各参与者的必需_ 字段。

例如，生产者视频解码器对于 消费者愿意接受任何东西，视频解码器不会 想要限制可能 在视频流中出现并可能被消费者接受 解码器需要确保生成的维度范围包含 至少从数据流解码的当前尺寸。

同样，对于具有特定动态维度场景的发起者， 可以预先要求参与者同意处理 启动器所需的尺寸范围 （否则，越早失败， 更小的 required_ 空间）。

提供方或发起者经常会设置这些字段 而不是让使用方设置这些字段

non-required_ 字段通过交集进行汇总，而 required_ 字段通过并集来汇总。

如果设置了该字段，那么 required_max_coded_width 和 required_max_coded_height 将 使分配的缓冲区足够大，以容纳 required_max_coded_width * required_max_coded_height。

TODO(dustingreen)：可以更轻松地分配最小大小的缓冲区 它还可以（可选）处理 尺寸 / 其他主要宽高比的备用必需边界。 0 将被视为 0xFFFFFFFF。

 无默认设置
required_max_coded_width uint32 无默认设置
required_min_coded_height uint32

0 将被视为 0xFFFFFFFF。

 无默认设置
required_max_coded_height uint32 无默认设置
required_min_bytes_per_row uint32

0 将被视为 0xFFFFFFFF。

 无默认设置
required_max_bytes_per_row uint32 无默认设置

ImageFormat_2

在 fuchsia.sysmem/constraints.fidl 中定义

描述图片的表示方式。

新代码已废弃此类型，但仍被某些相机代码使用。

字段类型说明默认
pixel_format PixelFormat

像素格式。

 无默认设置
coded_width uint32

缓冲区中的行宽（以像素为单位）。必须 >= display_width。 可以是 <stride_bytes 暗示的宽度。

 无默认设置
coded_height uint32

行数。必须 >= display_height。

 无默认设置
bytes_per_row uint32

平面 0 的步长（以字节为单位）。平面 0 之外的平面（如果有，具体取决于 像素格式）与平面 0 的步长有已知的固定关系。 对于 Intel 平铺纹理，步长针对的是纹理的线性版本。

 无默认设置
display_width uint32

要显示的行宽（以像素为单位）。此值可以小于或等于 coding_width。任何裁剪都发生在图片的右侧（而非左侧）。

 无默认设置
display_height uint32

要显示的行数。此属性值可以是 <= encoded_height，可以是 剪裁底部（而非顶部）。

 无默认设置
layers uint32

多层图片中的层数。

 1
color_space ColorSpace

颜色空间。

 无默认设置
has_pixel_aspect_ratio bool

pixel_aspect_ratio_width : pixel_aspect_ratio_height 是 亮度的像素宽高比（即采样宽高比，也称为 SAR） (AKA Y) 样本。pixel_aspect_ratio 为 1:1 均方像素。答 pixel_aspect_ratio 为 2:1 表示像素显示两次 和高一样宽编解码器实现应确保 通过减小分数（除以 两者均由 GCF 处理）。

当 has_pixel_aspect_ratio == false 时，pixel_aspect_ratio 未知。 在某些情况下，默认 1:1 可能比较合适，但和往常一样， 消费者可以通过 OOB 方式确定实际的 pixel_aspect_ratio。

 false
pixel_aspect_ratio_width uint32 1
pixel_aspect_ratio_height uint32 1

ImagePlane

在 fuchsia.sysmem/image_formats_deprecated.fidl 中定义

此类型已废弃，但没有直接替换（有意为之），因为 fuchsia.images2 不需要单独描述每个平面。

已弃用：23 添加：7

字段类型说明默认
byte_offset uint32

平面起点相对于图片起点的字节偏移量。

 无默认设置
bytes_per_row uint32

每行的步长（以字节为单位）。 仅对线性缓冲区格式有意义。

 无默认设置

ImageSpec

在 fuchsia.sysmem/image_formats_deprecated.fidl 中定义

描述用于分配某种所需形式图片的约束条件。

已弃用：23 添加：7

字段类型说明默认
min_width uint32

最小宽度（以像素为单位）。

 无默认设置
min_height uint32

最小高度（以像素为单位）。

 无默认设置
layers uint32

多层图片中的层数。 如果未指定，则默认为 1。

 1
pixel_format PixelFormat

像素格式。

 无默认设置
color_space ColorSpace

颜色空间。

 无默认设置

Node_IsAlternateFor_Response

在 fuchsia.sysmem/collection.fidl 中定义

字段类型说明默认
is_alternate bool 无默认设置

PixelFormat

在 fuchsia.sysmem/image_formats.fidl 中定义

描述图像内像素的表示方式。 简单格式只需指定类型。 参数像素格式可能需要其他属性。

新代码已废弃此类型，但仍被某些相机代码使用。

字段类型说明默认
type PixelFormatType 无默认设置
has_format_modifier bool

此布尔值有效地使 format_modifier 成为可选项，以满足 “ForDeprecatedCBindings”，以满足“FIDL Simple C Bindings”。

 无默认设置
format_modifier FormatModifier 无默认设置

SecureMem_AddSecureHeapPhysicalRange_Response

在 fuchsia.sysmem/secure_mem.fidl 中定义

<空>

SecureMem_DeleteSecureHeapPhysicalRange_Response

在 fuchsia.sysmem/secure_mem.fidl 中定义

<空>

SecureMem_GetPhysicalSecureHeapProperties_Response

在 fuchsia.sysmem/secure_mem.fidl 中定义

字段类型说明默认
properties SecureHeapProperties 无默认设置

SecureMem_GetPhysicalSecureHeaps_Response

在 fuchsia.sysmem/secure_mem.fidl 中定义

字段类型说明默认
heaps SecureHeapsAndRanges 无默认设置

SecureMem_ModifySecureHeapPhysicalRange_Response

在 fuchsia.sysmem/secure_mem.fidl 中定义

<空>

SecureMem_ZeroSubRange_Response

在 fuchsia.sysmem/secure_mem.fidl 中定义

<空>

SingleBufferInfo 资源

在 fuchsia.sysmem/constraints.fidl 中定义

这种类型当前没有替代方法，但如果您需要 增量缓冲区分配，请联系我们。

已弃用：23 添加：7

字段类型说明默认
settings SingleBufferSettings 无默认设置
buffer VmoBuffer 无默认设置

SingleBufferSettings

在 fuchsia.sysmem/constraints.fidl 中定义

在初始缓冲区分配之后，可以关闭旧缓冲区并 分配新的缓冲区。当分配新的缓冲区时，其设置 与集合中的其余缓冲区不同，并且单个 并使用 struct:

已弃用：23 添加：7

字段类型说明默认
buffer_settings BufferMemorySettings 无默认设置
has_image_format_constraints bool

保存数据不是未压缩图片数据的缓冲区将没有 此字段。用于存放未压缩图片数据的缓冲区 可以设置此字段。

至少目前，更改 PixelFormat 需要重新分配 缓冲区。

 无默认设置
image_format_constraints ImageFormatConstraints 无默认设置

VmoBuffer 资源

在 fuchsia.sysmem/constraints.fidl 中定义

已弃用：23 添加：7

字段类型说明默认
vmo handle<vmo>?

多个 CodecBuffer 可以使用同一个 VMO（只有同一个 Buffer_lifetime_ordinal），但每个 vmo 句柄都必须是一个单独的句柄。

如果这是 BufferCollectionInfo_2 中的 VmoBuffer，则 vmo 字段可以为 0 不小于 BufferCollectionInfo_2.buffer_count。

 无默认设置
vmo_usable_start uint64

第一个可用字节的 VMO 内的偏移量。必须小于VMO 的 以字节为单位，同时留出足够的空间 BufferMemorySettings.size_bytes。

 无默认设置

精英

CoherencyDomain 严格

类型：uint32

在 fuchsia.sysmem/constraints.fidl 中定义

只有在没有对 缓冲区。Secure_required 缓冲区仍可具有 CoherencyDomain CPU 或 使用 RAM 时，即使 secure_required 缓冲区只能由 CPU 访问， CPU 在安全模式（或类似模式）下运行。相比之下，设备本地 因为无法访问 CPU 而导致内存无法访问， 即使可能会使设备（实体设备或虚拟设备） 将数据从无法访问的缓冲区发送到对 CPU 可见的缓冲区。

已弃用：23 添加：7

名称值说明
0
1
2

ColorSpaceType

类型：uint32

在 fuchsia.sysmem/image_formats.fidl 中定义

此列表对于颜色空间标准的每个变体都有一个单独的条目。

因此，我们是否应添加对 RGB 变体 709 的支持， 那么我们会在此列表中添加该变体的单独条目。同理 对于 2020 或 2100 的 RGB 变体。对于 YcCbcCrc 变体的 YcCbcCrc 变体 2020 年。对于 2100 的 ICtCp 变体也是如此。

给定 ColorSpaceType 可能允许与符合以下条件的 PixelFormatType 配合使用： 提供了与 ColorSpaceType 的 官方规范并非所有规范有效的组合都一定受支持。 有关最佳情况的程度，请参阅 ImageFormatIsSupportedColorSpaceForPixelFormat() 但“true”并不能保证任何给定的 所有参与者都将支持所需的 ColorSpaceType 和 PixelFormatType。

sysmem 服务可帮助查找互支持的组合并分配 合适的缓冲区

ColorSpaceType 的规范不会隐式扩展以支持 超出标准每样本位数（R、G、B 或 Y 样本）。例如： 对于 2020 和 2100，sysmem 不支持 8 位/Y 样本，因为 每个样本 8 位不在 2020 或 2100 的规范中。系统内存 试图通告支持 PixelFormat + ColorSpace 的参与者 则会导致系统内存拒绝该组合并失败 分配（刻意地不建议指定 定义不充分的组合）。

新代码已废弃此类型，但仍被某些相机代码使用。

名称值说明
0

颜色空间类型无效。
1

sRGB
2

601 NTSC（“525 line”）YCbCr 初选，窄
3

601 NTSC（“525 line”）YCbCr 初选，宽
4

601 PAL（“625 line”）YCbCr 初选，窄
5

601 PAL（“625 line”）YCbCr 初选，宽
6

709 YCbCr（非 RGB）
7

2020 YCbCr（不是 RGB，不是 YcCbcCrc）
8

2100 YCbCr（不是 RGB，不是 ICtCp）
9

像素格式不代表颜色，或 特定于应用的颜色空间，无法由其他条目描述 。
4294967294

sysmem 客户端明确指示 sysmem 客户端 而不在意选择 / 使用哪个颜色空间。

添加时间：10

堆类型严格

类型：uint64

在 fuchsia.sysmem/constraints.fidl 中定义

已知的堆类型。 特定于设备的类型应设置位 60。顶层位已预留 ，不应设置。

新代码已废弃此类型，但仍被某些相机代码使用。

名称值说明
0
1152921504606912512

用于受 amlogic 保护的内存的堆。
1152921504606912513

用于在解密和视频解码之间提供 amlogic 保护的内存的堆。
1152921504606978048

goldfish vulkan 用于设备本地内存的堆。
1152921504606978049

goldfish vulkan 用于主机可见内存的堆。
1152921504607043585

用于显示帧缓冲区的堆。由显示驱动程序使用 仅限位于特定物理地址的单个帧缓冲区。 帧缓冲区堆支持创建缓冲区集合 并在这些驱动程序中启用 sysmem 支持。

PixelFormatType 严格

类型：uint32

在 fuchsia.sysmem/image_formats.fidl 中定义

格式名称中渠道的顺序反映了 频道的实际布局

这些值中的每一个都是主观的。颜色空间， （与 Vulkan 不同）。

此字段应与 fuchsia.sysmem2.PixelFormatType 保持同步。

新代码已废弃此类型，但仍被某些相机代码使用。

名称值说明
0
1

仅限 RGB，每个 R/G/B/A 样本 8 位 与 VK_FORMAT_R8G8B8A8_UNORM 兼容。
101

32bpp BGRA，1 个平面。仅限 RGB，每个 B/G/R/A 样本 8 位。 与 VK_FORMAT_B8G8R8A8_UNORM 兼容。
102

仅限 YUV，每个 Y 样本 8 位 与 VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM 兼容。
103

仅限 YUV，每个 Y 样本 8 位 与任何 Vulkan 格式都不兼容。
104

仅限 YUV，每个 Y 样本 8 位 与 VK_FORMAT_G8_B8R8_2PLANE_420_UNORM 兼容。
105

仅限 YUV，每个 Y 样本 8 位 与 VK_FORMAT_G8B8G8R8_422_UNORM 兼容。
106
107

仅限 YUV，每个 Y 样本 8 位 与 VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM 兼容。U 平面可能位于 图片的 B 或 R 平面（V 平面也是如此）；顺序可能是 取决于 VkBufferCollectionPropertiesFUCHSIA.samplerYcbcrConversionComponents。
108

24bpp BGR，1 个平面。仅限 RGB，每个 B/G/R 样本 8 位 与 VK_FORMAT_B8G8R8_UNORM 兼容。
109

16bpp RGB，1 个平面。5 位 R、6 位 G、5 位 B 与 VK_FORMAT_R5G6B5_UNORM_PACK16 兼容。
110

8bpp RGB，1 个平面。3 位 R、3 位 G、2 位 B 与任何 Vulkan 格式都不兼容。
111

8bpp RGB，1 个平面。2 位 R、2 位 G、2 位 B 与任何 Vulkan 格式都不兼容。
112

8bpp，仅亮度（红色、绿色和蓝色具有相同的值。） 与 VK_FORMAT_R8_UNORM 兼容。
113

8bpp，仅红色（绿色和蓝色将被解读为 0）。 与 VK_FORMAT_R8_UNORM 兼容。
114

16bpp RG，1 个平面。8 位 R、8 位 G。 与 VK_FORMAT_R8G8_UNORM 兼容。
115

32bpp RGBA，1 个平面。2 位 A、10 位 R/G/B。 与 VK_FORMAT_A2R10G10B10_UNORM_PACK32 兼容。
116

32bpp BGRA，1 个平面。2 位 A、10 位 R/G/B。 与 VK_FORMAT_A2B10G10R10_UNORM_PACK32 兼容。
4294967294

sysmem 客户端明确指示 sysmem 客户端 而不在意选择 / 使用哪种像素格式。设置此值时 sysmem 客户端不得设置 format_modifier_value。

添加时间：10

表

BufferCollectionTokenGroupCreateChildRequest 资源

在 fuchsia.sysmem/collection.fidl 中定义

Ordinal字段类型说明
token_request server_end<BufferCollectionToken>

必须设置。
rights_attenuation_mask uint32

如果未设置，则默认值为 ZX_RIGHT_SAME_RIGHTS。

SecureHeapAndRange

在 fuchsia.sysmem/secure_mem.fidl 中定义

已弃用：23 添加：7

Ordinal字段类型说明
heap HeapType
range SecureHeapRange

SecureHeapAndRangeModification

在 fuchsia.sysmem/secure_mem.fidl 中定义

已弃用：23 添加：7

Ordinal字段类型说明
heap HeapType
old_range SecureHeapRange
new_range SecureHeapRange

SecureHeapAndRanges

在 fuchsia.sysmem/secure_mem.fidl 中定义

已弃用：23 添加：7

Ordinal字段类型说明
heap HeapType

这是安全/受保护的堆。
ranges vector<SecureHeapRange>[128]

物理范围列表。此列表必须按 实体地址（靠前），并且不得存在任何重叠 范围。允许使用直接相邻的范围（非 重叠）。

SecureHeapProperties

在 fuchsia.sysmem/secure_mem.fidl 中定义

已弃用：23 添加：7

Ordinal字段类型说明
heap HeapType

为方便起见，在此处重复列出堆类型。
dynamic_protection_ranges bool

如果为 true，则多次调用 SetPhysicalSecureHeap() 允许堆大小。如果为 false，则仅有一个 SetPhyscialSecureHeap() 调用 且不允许调用 DeleteSecureHeapPhysicalRange() 或 允许 ModifySecureHeapPhysicalRange()。即使这个结果是错误的 SecureMem 服务器（驱动程序）仍负责 如果受保护的范围不能以其他方式启动， 会在热重新启动期间被清除
protected_range_granularity uint32

保护范围的粒度。如果起始粒度是 与结束或长度的粒度不同，那么这就是 值。

该数字必须是 2 的幂。客户端不得请求 指定更小的粒度。

即使硬件可以执行，也必须至少为 zx_system_page_size() 更小的单位
max_protected_range_count uint64

SecureMem 服务器不应统计 SecureMem 的预留范围 如果 SecureMem 服务器需要执行此类模拟。通常如此 进行模拟。如果任何范围 由 SecureMem 服务器预留，这些预留范围不在 可供 SecureMem 客户端使用。

如果范围数仅受可用内存限制， SecureMem 服务器将此值报告为 0xFFFFFFFFFFFFFFFF。通过 字段。与往常一样，SecureMem 服务器应确保 SetPhysicalSecureHeapRanges() 以原子方式成功或失败（ 在完成之前进行完全更新或回滚）。
is_mod_protected_range_available bool

如果设为 true，系统会实现 ModifySecureHeapPhysicalRange()。正在呼叫 在 is_mod_protected_range_available 时修改 SecureSecureHeapPhysicalRange() false。请勿尝试检测 通过调用 ModifySecureHeapPhysicalRange() 查看是否失败；它 可以使用 ZX_PANIC()。

SecureHeapRange

在 fuchsia.sysmem/secure_mem.fidl 中定义

已弃用：23 添加：7

Ordinal字段类型说明
physical_address uint64

必须至少与 heap_range_granularity 对齐。
size_bytes uint64

必须至少与 heap_range_granularity 对齐。

SecureHeapsAndRanges

在 fuchsia.sysmem/secure_mem.fidl 中定义

已弃用：23 添加：7

Ordinal字段类型说明
heaps vector<SecureHeapAndRanges>[32]

联合体

Node_IsAlternateFor_Result 严格

在 fuchsia.sysmem/collection.fidl 中定义

Ordinal变体类型说明
response Node_IsAlternateFor_Response
err zx/Status

SecureMem_AddSecureHeapPhysicalRange_Result 严格

在 fuchsia.sysmem/secure_mem.fidl 中定义

Ordinal变体类型说明
response SecureMem_AddSecureHeapPhysicalRange_Response
err zx/Status

SecureMem_DeleteSecureHeapPhysicalRange_Result 严格

在 fuchsia.sysmem/secure_mem.fidl 中定义

Ordinal变体类型说明
response SecureMem_DeleteSecureHeapPhysicalRange_Response
err zx/Status

SecureMem_GetPhysicalSecureHeapProperties_Result 严格

在 fuchsia.sysmem/secure_mem.fidl 中定义

Ordinal变体类型说明
response SecureMem_GetPhysicalSecureHeapProperties_Response
err zx/Status

SecureMem_GetPhysicalSecureHeaps_Result 严格

在 fuchsia.sysmem/secure_mem.fidl 中定义

Ordinal变体类型说明
response SecureMem_GetPhysicalSecureHeaps_Response
err zx/Status

SecureMem_ModifySecureHeapPhysicalRange_Result 严格

在 fuchsia.sysmem/secure_mem.fidl 中定义

Ordinal变体类型说明
response SecureMem_ModifySecureHeapPhysicalRange_Response
err zx/Status

SecureMem_ZeroSubRange_Result 严格

在 fuchsia.sysmem/secure_mem.fidl 中定义

Ordinal变体类型说明
response SecureMem_ZeroSubRange_Response
err zx/Status

常量

名称值类型说明
FORMAT_MODIFIER_ARM_AFBC_16X16 576460752303423489 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_AFBC_16X16_SPLIT_BLOCK_SPARSE_YUV 576460752303423601 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_AFBC_16X16_SPLIT_BLOCK_SPARSE_YUV_TE 576460752303427697 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_AFBC_16X16_SPLIT_BLOCK_SPARSE_YUV_TE_TILED_HEADER 576460752303435889 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_AFBC_16X16_SPLIT_BLOCK_SPARSE_YUV_TILED_HEADER 576460752303431793 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_AFBC_16X16_TE 576460752303427585 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_AFBC_16X16_YUV_TILED_HEADER 576460752303431697 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_AFBC_32X8 576460752303423490 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_AFBC_32X8_TE 576460752303427586 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_BCH_BIT 2048 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_LINEAR_TE 576460752303427584 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_SPARSE_BIT 64 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_SPLIT_BLOCK_BIT 32 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_TE_BIT 4096 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_TILED_HEADER_BIT 8192 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_ARM_YUV_BIT 16 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_GOOGLE_GOLDFISH_OPTIMAL 648518346341351425 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_INTEL_CCS_BIT 16777216 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_INTEL_I915_X_TILED 72057594037927937 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_INTEL_I915_YF_TILED 72057594037927939 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_INTEL_I915_YF_TILED_CCS 72057594054705155 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_INTEL_I915_Y_TILED 72057594037927938 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_INTEL_I915_Y_TILED_CCS 72057594054705154 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_INVALID FORMAT_MODIFIER_VALUE_RESERVED uint64
已弃用：23 添加：7
FORMAT_MODIFIER_LINEAR 0 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_NONE 0 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_VALUE_RESERVED 72057594037927935 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_VENDOR_AMD 144115188075855872 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_VENDOR_ARM 576460752303423488 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_VENDOR_BROADCOM 504403158265495552 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_VENDOR_GOOGLE 648518346341351424 uint64

此值的含义已废弃。使用 fuchsia.images2.FORMAT_MODIFIER_VENDOR_GOOGLE 而是具有不同的值。

已弃用：23 添加：7
FORMAT_MODIFIER_VENDOR_INTEL 72057594037927936 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_VENDOR_NONE 0 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_VENDOR_NVIDIA 216172782113783808 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_VENDOR_QCOM 360287970189639680 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_VENDOR_SAMSUNG 288230376151711744 uint64
已弃用：23 添加：7
FORMAT_MODIFIER_VENDOR_VIVANTE 432345564227567616 uint64
已弃用：23 添加：7
MAX_COUNT_BUFFER_COLLECTION_CONSTRAINTS_IMAGE_FORMAT_CONSTRAINTS 32 uint32
MAX_COUNT_BUFFER_COLLECTION_INFO_BUFFERS 64 uint32
MAX_COUNT_BUFFER_MEMORY_CONSTRAINTS_HEAP_PERMITTED 32 uint32
MAX_COUNT_CREATE_CHILDREN 64 int32

在大多数典型的场景中，并不建议创建这么多的子元素 但不会被阻止 应对异常情况的需求缓解可能非常高的时间复杂性 会限制组子组合的实际数量 单独计算最大数值， 可通过这些协议设置系统中节点总数上限 词元树有单独的最大值，该最大值无法通过 协议

已弃用：23 添加：9
MAX_COUNT_DUPLICATES 64 uint32
已弃用：23 添加：7
MAX_COUNT_IMAGE_FORMAT_CONSTRAINTS_COLOR_SPACES 32 uint32
MAX_HEAPS_COUNT 32 uint32
已弃用：23 添加：7
MAX_RANGES_COUNT 128 uint32
已弃用：23 添加：7
VULKAN_BUFFER_USAGE_INDEX_BUFFER 4194304 uint32
已弃用：23 添加：7
VULKAN_BUFFER_USAGE_INDIRECT_BUFFER 16777216 uint32
已弃用：23 添加：7
VULKAN_BUFFER_USAGE_STORAGE_BUFFER 2097152 uint32
已弃用：23 添加：7
VULKAN_BUFFER_USAGE_STORAGE_TEXEL_BUFFER 524288 uint32
已弃用：23 添加：7
VULKAN_BUFFER_USAGE_TRANSFER_DST 131072 uint32
已弃用：23 添加：7
VULKAN_BUFFER_USAGE_TRANSFER_SRC 65536 uint32
已弃用：23 添加：7
VULKAN_BUFFER_USAGE_UNIFORM_BUFFER 1048576 uint32
已弃用：23 添加：7
VULKAN_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER 262144 uint32
已弃用：23 添加：7
VULKAN_BUFFER_USAGE_VERTEX_BUFFER 8388608 uint32
已弃用：23 添加：7
VULKAN_IMAGE_USAGE_COLOR_ATTACHMENT 16 uint32
已弃用：23 添加：7
VULKAN_IMAGE_USAGE_INPUT_ATTACHMENT 128 uint32
已弃用：23 添加：7
VULKAN_IMAGE_USAGE_SAMPLED 4 uint32
已弃用：23 添加：7
VULKAN_IMAGE_USAGE_STENCIL_ATTACHMENT 32 uint32
已弃用：23 添加：7
VULKAN_IMAGE_USAGE_STORAGE 8 uint32
已弃用：23 添加：7
VULKAN_IMAGE_USAGE_TRANSFER_DST 2 uint32
已弃用：23 添加：7
VULKAN_IMAGE_USAGE_TRANSFER_SRC 1 uint32
已弃用：23 添加：7
VULKAN_IMAGE_USAGE_TRANSIENT_ATTACHMENT 64 uint32
已弃用：23 添加：7
cpuUsageRead 1 uint32
已弃用：23 添加：7
cpuUsageReadOften 2 uint32
已弃用：23 添加：7
cpuUsageWrite 4 uint32
已弃用：23 添加：7
cpuUsageWriteOften 8 uint32
已弃用：23 添加：7
displayUsageCursor 2 uint32
已弃用：23 添加：7
displayUsageLayer 1 uint32
已弃用：23 添加：7
noneUsage 1 uint32
已弃用：23 添加：7
videoUsageCapture 8 uint32
已弃用：23 添加：7
videoUsageDecryptorOutput 16 uint32
已弃用：23 添加：7
videoUsageHwDecoder 1 uint32
已弃用：23 添加：7
videoUsageHwDecoderInternal 32 uint32
已弃用：23 添加：7
videoUsageHwEncoder 2 uint32
已弃用：23 添加：7
videoUsageHwProtected 4 uint32
已弃用：23 添加：7
vulkanUsageColorAttachment 16 uint32
已弃用：23 添加：7
vulkanUsageInputAttachment 128 uint32
已弃用：23 添加：7
vulkanUsageSampled 4 uint32
已弃用：23 添加：7
vulkanUsageStencilAttachment 32 uint32
已弃用：23 添加：7
vulkanUsageStorage 8 uint32
已弃用：23 添加：7
vulkanUsageTransferDst 2 uint32
已弃用：23 添加：7
vulkanUsageTransferSrc 1 uint32
已弃用：23 添加：7
vulkanUsageTransientAttachment 64 uint32
已弃用：23 添加：7