STRUCT TTM_TT(9)

💖 struct ttm_tt(9) 💖

okay so bestie, we're in the Kernel API Manual today and this one's a whole vibe — it's giving "structure holding the pages, caching- and aperture binding status for a buffer object that isn't backed by fixed (VRAM / AGP) memory." literally that's the whole NAME, no notes 💅

---

✨ SYNOPSIS ✨

struct ttm_tt {
    struct page **pages;
  #define TTM_TT_FLAG_SWAPPED             BIT(0);
  #define TTM_TT_FLAG_ZERO_ALLOC          BIT(1);
  #define TTM_TT_FLAG_EXTERNAL            BIT(2);
  #define TTM_TT_FLAG_EXTERNAL_MAPPABLE   BIT(3);
  #define TTM_TT_FLAG_DECRYPTED           BIT(4);
  #define TTM_TT_FLAG_BACKED_UP           BIT(5);
  #define TTM_TT_FLAG_PRIV_POPULATED      BIT(6);
    uint32_t page_flags;
    uint32_t num_pages;
    struct sg_table *sg;
    dma_addr_t *dma_address;
    struct file *swap_storage;
    struct file *backup;
    enum ttm_caching caching;
    struct ttm_pool_tt_restore *restore;
 };

---

🌸 Members 🌸

the actual fields, let's go 🫶

• pages — the Array of pages backing the data. iconic, foundational, we love her 💖
• page_flags — The page flags. and babes, there are so many valid values, buckle up:

Supported values:

• TTM_TT_FLAG_SWAPPED — Set by TTM when the pages have been unpopulated and swapped out by TTM. Calling ttm_tt_populate will then swap the pages back in, and unset the flag. Drivers should in general never need to touch this. like fr, hands off, TTM's got it 💅
• TTM_TT_FLAG_ZERO_ALLOC — Set if the pages will be zeroed on allocation. squeaky clean ✨
• TTM_TT_FLAG_EXTERNAL — Set if the underlying pages were allocated externally, like with dma-buf or userptr. This effectively disables TTM swapping out such pages. Also important is to prevent TTM from ever directly mapping these pages. ngl, this one means business 🔥

Note that enum ttm_bo_type.ttm_bo_type_sg objects will always enable this flag. no cap, always.

• TTM_TT_FLAG_EXTERNAL_MAPPABLE — Same behaviour as TTM_TT_FLAG_EXTERNAL, but with the reduced restriction that it is still valid to use TTM to map the pages directly. This is useful when implementing a ttm_tt backend which still allocates driver owned pages underneath(say with shmem). lowkey the chill version of EXTERNAL 🌈

Note that since this also implies TTM_TT_FLAG_EXTERNAL, the usage here should always be:

page_flags = TTM_TT_FLAG_EXTERNAL | TTM_TT_FLAG_EXTERNAL_MAPPABLE;

like, always always. iykyk 🎀

• TTM_TT_FLAG_DECRYPTED — The mapped ttm pages should be marked as not encrypted. The framework will try to match what the dma layer is doing, but note that it is a little fragile because ttm page fault handling abuses the DMA api a bit and dma_map_attrs can't be used to assure pgprot always matches. 😭 she's doing her best okay
• TTM_TT_FLAG_BACKED_UP — TTM internal only. This is set if the struct ttm_tt has been (possibly partially) backed up. back up bestie, back up 💀
• TTM_TT_FLAG_PRIV_POPULATED — TTM internal only. DO NOT USE. 🚨 This is set by TTM after ttm_tt_populate has successfully returned, and is then unset when TTM calls ttm_tt_unpopulate. like seriously do not touch, this is main character energy reserved for TTM itself 👑

• num_pages — Number of pages in the page array. maths 💜
• sg — for SG objects via dma-buf.
• dma_address — The DMA (bus) addresses of the pages.
• swap_storage — Pointer to shmem struct file for swap storage.
• backup — Pointer to backup struct for backed up tts. Could be unified with swap_storage. Meanwhile, the driver's ttm_tt_create callback is responsible for assigning this field. not me assigning responsibilities 🙈
• caching — The current caching state of the pages, see enum ttm_caching.
• restore — Partial restoration from backup state. TTM private. 🤫

---

🦋 SEE ALSO 🦋

Kernel file ./include/drm/ttm/ttm_tt.h plus the whole friend group:

• struct ttm_kmap_iter_tt(9)
• ttm_tt_is_swapped(9)
• ttm_tt_is_backed_up(9)
• ttm_tt_clear_backed_up(9)
• ttm_tt_create(9)
• ttm_tt_init(9)
• ttm_tt_fini(9)
• ttm_tt_destroy(9)
• ttm_tt_swapin(9)
• ttm_tt_populate(9)
• ttm_tt_unpopulate(9)
• ttm_tt_mark_for_clear(9)
• struct ttm_backup_flags(9)
• ttm_agp_tt_create(9)

---

and that's the whole page bestie, we ATE 💅✨

okay so this came from ./include/drm/ttm, dated October 2026 — manifesting that future for us, periodt 🌸🫶💖