• 文档 >
  • 便携式 C++ 编程
快捷方式

便携式 C++ 编程

注意:本文档涵盖了需要在目标硬件环境中构建和执行的代码。这适用于核心执行运行时以及此仓库中的内核和后端实现。这些规则不一定适用于仅在开发主机上运行的代码,例如创作或构建工具。

ExecuTorch 运行时代码旨在实现可移植性,应能在各种系统上构建,从服务器到移动电话再到 DSP,从 POSIX 到 Windows 再到裸机环境。

这意味着它不能假定存在以下内容:

  • 文件

  • 线程

  • 异常

  • stdout, stderr

  • printf(), fprintf()

  • 一般的 POSIX API 和概念

它也不能假定

  • 64 位指针

  • 给定整数类型的大小

  • char 的有无符号性

为了使二进制文件大小最小化,并严格控制内存分配,代码不得使用

  • malloc(), free()

  • new, delete

  • 大多数 stdlibc++ 类型;特别是那些管理自身内存的容器类型,如 stringvector,或者内存管理包装类型,如 unique_ptrshared_ptr

为了帮助降低复杂性,代码不得依赖于任何外部依赖项,除了

  • flatbuffers(用于 .pte 文件反序列化)

  • flatcc(用于事件跟踪序列化)

  • Core PyTorch(仅用于 ATen 模式)

平台抽象层 (PAL)

为了避免假定目标系统的能力,ExecuTorch 运行时允许客户端在其平台抽象层 (PAL) 中覆盖低级函数,PAL 定义在 //executorch/runtime/platform/platform.h 中,用于执行以下操作:

  • 获取当前时间戳

  • 打印日志消息

  • 使系统崩溃

内存分配

运行时代码应使用客户端提供的 MemoryManager//executorch/runtime/executor/memory_manager.h)来分配内存,而不是使用 malloc()new

文件加载

客户端不应直接加载文件,而应提供已加载数据的缓冲区,或封装在如 DataLoader 这样的类型中。

整数类型

ExecuTorch 运行时代码不应假定基本类型(如 int, shortchar)的任何大小。例如,C++ 标准只保证 int 至少有 16 位宽。ARM 工具链将 char 视为无符号类型,而其他工具链通常将其视为有符号类型。

相反,运行时 API 使用一组更可预测但仍然标准的整数类型

  • <cstdint> 类型,如 uint64_t, int32_t`;这些类型保证了位宽和有无符号性,与架构无关。当你需要非常特定的整数宽度时使用这些类型。

  • size_t 用于计数或内存偏移量。size_t 保证足够大,可以表示任何内存字节偏移量;也就是说,它的宽度将与目标系统的原生指针类型相同。对于计数/偏移量,优先使用它而不是 uint64_t,这样 32 位系统就不需要为 64 位值的额外开销付费。

  • 在某些 ATen 兼容场景下,Tensor 返回有符号计数时使用 ssize_t。尽可能优先使用 size_t

浮点算术

并非所有系统都支持浮点算术:有些甚至不在其工具链中启用浮点仿真。因此,核心运行时代码在运行时不得执行任何浮点算术,尽管可以简单地创建或管理 floatdouble 值(例如,在 EValue 中)。

内核,作为核心运行时之外的部分,允许执行浮点算术。尽管有些内核可能会选择不这样做,以便它们可以在不支持浮点运算的系统上运行。

日志记录

ExecuTorch 运行时提供了 //executorch/runtime/platform/log.h 中的 ET_LOG 接口和 //executorch/runtime/platform/assert.h 中的 ET_CHECK 接口,而不是使用 printf(), fprintf(), cout, cerr,或像 folly::loggingglog 这样的库。消息使用 PAL 中的一个钩子打印,这意味着客户端可以将它们重定向到任何底层日志系统,或者如果可用,直接打印到 stderr

日志格式可移植性

定宽整数

当你有一个日志语句,例如

int64_t value;
ET_LOG(Error, "Value %??? is bad", value);

对于 %??? 部分,应该填写什么来匹配 int64_t?在不同的系统上,int64_t 的 typedef 可能是 int`, `long intlong long int。选择像 %d`, `%ld%lld 这样的格式可能在一个目标系统上有效,但在其他系统上会出错。

为了实现可移植性,运行时代码使用了标准(但确实有点别扭)的 <cinttypes> 辅助宏。每种可移植整数类型都有一个对应的 PRIn## 宏,例如

  • int32_t -> PRId32

  • uint32_t -> PRIu32

  • int64_t -> PRId64

  • uint64_t -> PRIu64

  • 更多信息请参阅 https://cppreference.cn/w/cpp/header/cinttypes

这些宏是字面量字符串,可以与格式字符串的其他部分连接,例如

int64_t value;
ET_LOG(Error, "Value %" PRId64 " is bad", value);

请注意,这需要将字面格式字符串切分(额外的双引号)。它还需要在宏前面加上前导的 %

但是,通过使用这些宏,可以保证工具链将为该类型使用适当的格式模式。

size_t, ssize_t

与定宽整数类型不同,格式字符串已经有了一种可移植的方式来处理 size_tssize_t

  • size_t -> %zu

  • ssize_t -> %zd

类型转换

有时,特别是在跨越 ATen 和 lean 模式的代码中,值本身的类型在不同构建模式下可能不同。在这种情况下,将值转换为 lean 模式类型,例如

ET_CHECK_MSG(
    input.dim() == output.dim(),
    "input.dim() %zd not equal to output.dim() %zd",
    (ssize_t)input.dim(),
    (ssize_t)output.dim());

在这种情况下,Tensor::dim() 在 lean 模式下返回 ssize_t,而 at::Tensor::dim() 在 ATen 模式下返回 int64_t。由于它们在概念上都返回(有符号的)计数,ssize_t 是最合适的整数类型。int64_t 也能工作,但在 lean 模式下会不必要地要求 32 位系统处理 64 位值。

这是唯一需要进行类型转换的情况,即当 lean 模式和 ATen 模式不一致时。否则,请使用与类型匹配的格式模式。

文档

访问 PyTorch 的全面开发者文档

查看文档

教程

获取面向初学者和高级开发者的深度教程

查看教程

资源

查找开发资源并解答你的问题

查看资源