便携式 C++ 编程¶
注意:本文档涵盖了需要为目标硬件环境构建和执行的代码。这适用于核心执行运行时,以及此存储库中的内核和后端实现。这些规则不一定适用于仅在开发主机上运行的代码,例如创作或构建工具。
ExecuTorch 运行时代码旨在可移植,并且应该能够构建用于各种系统,从服务器到手机到 DSP,从 POSIX 到 Windows 到裸机环境。
这意味着它不能假设存在
文件
线程
异常
stdout
,stderr
printf()
,fprintf()
POSIX API 和概念(一般)
它也不能假设
64 位指针
给定整数类型的尺寸
char
的符号性
为了将二进制文件大小保持在最小,并严格控制内存分配,代码可能不会使用
malloc()
,free()
new
,delete
大多数
stdlibc++
类型;特别是管理自身内存的容器类型,如string
和vector
,或内存管理包装器类型,如unique_ptr
和shared_ptr
。
为了帮助降低复杂性,代码可能不依赖于任何外部依赖项,除了
flatbuffers
(用于.pte
文件反序列化)flatcc
(用于事件跟踪序列化)核心 PyTorch(仅限 ATen 模式)
平台抽象层 (PAL)¶
为了避免假设目标系统的功能,ExecuTorch 运行时允许客户端覆盖其平台抽象层 (PAL) 中的低级函数,该层定义在 //executorch/runtime/platform/platform.h
中,以执行以下操作
获取当前时间戳
打印日志消息
使系统发生故障
内存分配¶
运行时代码不应使用 malloc()
或 new
,而应使用客户端提供的 MemoryManager
(//executorch/runtime/executor/memory_manager.h
)分配内存。
文件加载¶
客户端不应直接加载文件,而应提供包含已加载数据的缓冲区,或将其包装在 DataLoader
等类型中。
整数类型¶
ExecuTorch 运行时代码不应假设诸如 int
、short
或 char
等基本类型的尺寸。例如,C++ 标准仅保证 int
至少为 16 位宽。而 ARM 工具链将 char
视为无符号,而其他工具链通常将其视为有符号。
相反,运行时 API 使用一组更可预测但仍然标准的整数类型
<cstdint>
类型,如uint64_t
、int32_t
;这些类型保证了位宽和符号性,而不管体系结构如何。当您需要非常具体的整数宽度时,请使用这些类型。size_t
用于事物的计数或内存偏移量。size_t
保证足够大以表示任何内存字节偏移量;即,它将与目标系统的本机指针类型一样宽。优先使用它而不是uint64_t
用于计数/偏移量,以便 32 位系统无需为 64 位值的额外开销付费。ssize_t
用于某些 ATen 兼容性情况,其中Tensor
返回有符号计数。尽可能优先使用size_t
。
浮点运算¶
并非每个系统都支持浮点运算:有些系统甚至在其工具链中不启用浮点仿真。因此,核心运行时代码在运行时不得执行任何浮点运算,尽管创建或管理float
或double
值(例如,在EValue
中)是可以的。
内核位于核心运行时之外,允许执行浮点运算。尽管有些内核可能会选择不执行浮点运算,以便它们可以在没有浮点支持的系统上运行。
日志记录¶
ExecuTorch 运行时提供了 //executorch/runtime/platform/log.h
中的 ET_LOG
接口和 //executorch/runtime/platform/assert.h
中的 ET_CHECK
接口,而不是使用 printf()
、fprintf()
、cout
、cerr
或 folly::logging
或 glog
等库。这些消息使用 PAL 中的钩子打印,这意味着客户端可以将它们重定向到任何底层日志系统,或者如果可用,只将它们打印到 stderr
。
日志格式可移植性¶
定宽整数¶
当您有一个像这样的日志语句时
int64_t value;
ET_LOG(Error, "Value %??? is bad", value);
您应该为 %???
部分输入什么,以匹配 int64_t
?在不同的系统上,int64_t
类型定义可能是 int
、long int
或 long 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);
请注意,这需要将文字格式字符串分割(额外的双引号)。它还需要宏之前的引导 %
。
但是,通过使用这些宏,您可以保证工具链将对该类型使用适当的格式模式。
强制转换¶
有时,特别是在跨越 ATen 和精简模式的代码中,值的类型本身在不同的构建模式下可能不同。在这些情况下,将值强制转换为精简模式类型,例如
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()
在精简模式下返回 ssize_t
,而在 ATen 模式下,at::Tensor::dim()
返回 int64_t
。由于它们在概念上都返回(有符号)计数,因此 ssize_t
是最合适的整数类型。int64_t
可以工作,但它会不必要地要求 32 位系统在精简模式下处理 64 位值。
这是唯一需要强制转换的情况,即精简模式和 ATen 模式不一致。否则,使用与类型匹配的格式模式。