Skip to content

Commit e94faaa

Browse files
[Vulkan] Let tensor wrap an external image with caller-supplied sizes (pytorch#21930)
## Summary `vTensor(context, image)` infers the tensor's shape from the image's extents, and a `VkImage` has three: width, height and depth, so that inference always yields a rank-3 shape. A logical shape such as `[B, S, H, D]` is unreachable, which blocks wrapping an externally owned image as a tensor whose axes the shaders can index. This lets the caller pass the image to the main vTensor constructor instead, so the sizes, dtype and layout come from the caller and only the storage comes from the image. A ComputeGraph::add_tensor overload reaches it. The image is held as a `VulkanImage` copy, which aliases the handle with `is_copy_` set, so the adopted view never destroys memory. An extent check rejects an image whose size disagrees with the requested sizes. The allocating path is untouched. The parameter defaults to `nullptr` and construction only diverges when it is set, so `logical_limits` still seeds from the physical extents as before. ## Files - `backends/vulkan/runtime/api/containers/Tensor.h` — `external_image` on the `vTensor` constructor. - `backends/vulkan/runtime/api/containers/Tensor.cpp` — storage selection between the adopting and allocating `vTensorStorage`, and the extent check. - `backends/vulkan/runtime/graph/ComputeGraph.h`, `.cpp` — an `add_tensor` overload taking sizes, dtype, memory layout and an image. - `backends/vulkan/test/vulkan_compute_api_test.cpp` — 3 new tests. ## Testing `vulkan_compute_api_test` New coverage: adopting at `[1, 37, 8, 64]` and keeping all four sizes, asserted against the inferring constructor collapsing the same image to rank 3; rejecting an image whose extents disagree with the requested sizes; and an adopted view reporting `is_copy_of` the source and leaving the source image live after the view is destroyed and deferred cleanup has run. cc @SS-JIA @manuelcandales @digantdesai @cbilgin
1 parent d827cf7 commit e94faaa

5 files changed

Lines changed: 139 additions & 11 deletions

File tree

‎backends/vulkan/runtime/api/containers/Tensor.cpp‎

Lines changed: 24 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -851,7 +851,8 @@ vTensor::vTensor(
851851
const utils::StorageType storage_type,
852852
const utils::GPUMemoryLayout memory_layout,
853853
const bool allocate_memory,
854-
const utils::AxisMapLayout axis_map_layout)
854+
const utils::AxisMapLayout axis_map_layout,
855+
const vkapi::VulkanImage* external_image)
855856
: dtype_(get_effective_scalar_type(context, dtype, memory_layout)),
856857
packed_dim_info_(calculate_packed_dim_info(memory_layout, storage_type)),
857858
// Calculate tensor metadata
@@ -879,15 +880,28 @@ vTensor::vTensor(
879880
uniforms_(),
880881
buffer_meta_(),
881882
// Construct Tensor storage
882-
storage_(std::make_shared<vTensorStorage>(
883-
context,
884-
storage_type,
885-
axis_map_,
886-
packed_dim_info_,
887-
padded_sizes_,
888-
dtype_,
889-
physical_numel_,
890-
allocate_memory)) {
883+
storage_(
884+
external_image != nullptr
885+
? std::make_shared<vTensorStorage>(context, *external_image)
886+
: std::make_shared<vTensorStorage>(
887+
context,
888+
storage_type,
889+
axis_map_,
890+
packed_dim_info_,
891+
padded_sizes_,
892+
dtype_,
893+
physical_numel_,
894+
allocate_memory)) {
895+
// An external image was sized by its creator, so nothing guarantees it
896+
// matches the metadata derived from `sizes`. The extents feed the
897+
// shader-visible logical limits below, so they have to agree.
898+
if (external_image != nullptr) {
899+
VK_CHECK_COND(
900+
storage_->image_extents_ ==
901+
calculate_image_extents(
902+
dtype_, packed_dim_info_, padded_sizes_, axis_map_),
903+
"external image extents do not match the requested tensor sizes");
904+
}
891905
// uniform_data_ only valid for low dim tensors
892906
if (sizes.size() <= 4) {
893907
uniform_data_ = std::make_shared<UniformData>(UniformData{

‎backends/vulkan/runtime/api/containers/Tensor.h‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -210,7 +210,10 @@ class vTensor final {
210210
const utils::StorageType storage_type = utils::kTexture3D,
211211
const utils::GPUMemoryLayout memory_layout = utils::kChannelsPacked,
212212
const bool allocate_memory = true,
213-
const utils::AxisMapLayout axis_map_layout = utils::kDefaultAxisMap);
213+
const utils::AxisMapLayout axis_map_layout = utils::kDefaultAxisMap,
214+
// When non-null, wrap this image instead of allocating. Stored as a
215+
// VulkanImage copy, which aliases the handle without owning it.
216+
const vkapi::VulkanImage* external_image = nullptr);
214217

215218
vTensor(const vTensor& other) = delete;
216219

‎backends/vulkan/runtime/graph/ComputeGraph.cpp‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -554,6 +554,25 @@ ValueRef ComputeGraph::add_tensor(
554554
axis_map_layout);
555555
}
556556

557+
ValueRef ComputeGraph::add_tensor(
558+
const std::vector<int64_t>& sizes,
559+
const vkapi::ScalarType dtype,
560+
const utils::GPUMemoryLayout memory_layout,
561+
const vkapi::VulkanImage& image) {
562+
ValueRef idx(static_cast<int>(values_.size()));
563+
check_no_active_value_ptrs();
564+
values_.emplace_back(api::vTensor(
565+
context(),
566+
sizes,
567+
dtype,
568+
utils::kTexture3D,
569+
memory_layout,
570+
/*allocate_memory=*/false,
571+
utils::kDefaultAxisMap,
572+
&image));
573+
return idx;
574+
}
575+
557576
ValueRef ComputeGraph::add_tensor(const vkapi::VulkanImage& image) {
558577
ValueRef idx(static_cast<int>(values_.size()));
559578
check_no_active_value_ptrs();

‎backends/vulkan/runtime/graph/ComputeGraph.h‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -779,6 +779,17 @@ class ComputeGraph final {
779779
*/
780780
ValueRef add_tensor(const vkapi::VulkanImage& image);
781781

782+
/*
783+
* Wrap an externally owned image as a tensor with the given logical sizes.
784+
* Unlike add_tensor(image), the shape is taken from the caller instead of
785+
* being reconstructed from the image's extents.
786+
*/
787+
ValueRef add_tensor(
788+
const std::vector<int64_t>& sizes,
789+
const vkapi::ScalarType dtype,
790+
const utils::GPUMemoryLayout memory_layout,
791+
const vkapi::VulkanImage& image);
792+
782793
/*
783794
* Add a `api::vTensor` value to the graph with the properties of `vref`.
784795
*/

‎backends/vulkan/test/vulkan_compute_api_test.cpp‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1700,6 +1700,87 @@ TEST_F(VulkanComputeAPITest, test_tensor_creation_from_vulkan_image) {
17001700
EXPECT_TRUE(tensor.numel() == exp_numel);
17011701
}
17021702

1703+
// Sizes an image can carry but its extents cannot express: rank 4, and a
1704+
// sequence dim that is not the packed one.
1705+
static const std::vector<int64_t> kExternalSizes = {1, 37, 8, 64};
1706+
1707+
static vTensor make_image_owner() {
1708+
return vTensor(
1709+
context(),
1710+
kExternalSizes,
1711+
vkapi::kFloat,
1712+
utils::kTexture3D,
1713+
utils::kWidthPacked);
1714+
}
1715+
1716+
TEST_F(
1717+
VulkanComputeAPITest,
1718+
test_tensor_over_external_image_keeps_logical_sizes) {
1719+
vTensor owner = make_image_owner();
1720+
1721+
vTensor view(
1722+
context(),
1723+
kExternalSizes,
1724+
vkapi::kFloat,
1725+
utils::kTexture3D,
1726+
utils::kWidthPacked,
1727+
/*allocate_memory = */ false,
1728+
utils::kDefaultAxisMap,
1729+
&owner.image());
1730+
1731+
EXPECT_TRUE(view.sizes() == kExternalSizes);
1732+
EXPECT_TRUE(view.packed_dim() == 0);
1733+
EXPECT_TRUE(view.numel() == owner.numel());
1734+
1735+
// Reconstructing from the extents instead would collapse this to 3 sizes.
1736+
EXPECT_TRUE(vTensor(context(), owner.image()).sizes().size() == 3);
1737+
}
1738+
1739+
TEST_F(
1740+
VulkanComputeAPITest,
1741+
test_tensor_over_external_image_rejects_size_mismatch) {
1742+
vTensor owner = make_image_owner();
1743+
1744+
std::vector<int64_t> mismatched = kExternalSizes;
1745+
mismatched.back() *= 2;
1746+
1747+
EXPECT_THROW(
1748+
vTensor(
1749+
context(),
1750+
mismatched,
1751+
vkapi::kFloat,
1752+
utils::kTexture3D,
1753+
utils::kWidthPacked,
1754+
/*allocate_memory = */ false,
1755+
utils::kDefaultAxisMap,
1756+
&owner.image()),
1757+
vkapi::Error);
1758+
}
1759+
1760+
TEST_F(VulkanComputeAPITest, test_tensor_over_external_image_does_not_own_it) {
1761+
vTensor owner = make_image_owner();
1762+
1763+
{
1764+
vTensor view(
1765+
context(),
1766+
kExternalSizes,
1767+
vkapi::kFloat,
1768+
utils::kTexture3D,
1769+
utils::kWidthPacked,
1770+
/*allocate_memory = */ false,
1771+
utils::kDefaultAxisMap,
1772+
&owner.image());
1773+
1774+
EXPECT_TRUE(view.image().is_copy_of(owner.image()));
1775+
}
1776+
1777+
// The view is gone and its deferred cleanup has run; the image it aliased
1778+
// belongs to `owner` and is still live.
1779+
context()->flush();
1780+
EXPECT_TRUE(owner.image());
1781+
EXPECT_FALSE(owner.image().is_copy());
1782+
}
1783+
17031784
TEST(VulkanComputeGraphTest, test_values_scalars) {
17041785
GraphConfig config;
17051786
ComputeGraph graph(config);

0 commit comments

Comments
 (0)